SpringBoot从零搭建项目系列（三）｜项目结构设计与分层架构

📝 文章摘要：本文是SpringBoot系列的第三篇，深入讲解企业级项目的结构设计和分层架构，包括包命名规范、代码组织原则、统一异常处理、响应格式标准化等核心内容，帮助读者建立规范的开发习惯和架构思维。

📋 前言与概述

在前面两篇文章中，我们完成了开发环境搭建和配置管理的学习。今天我们将探讨如何设计一个规范、可维护的企业级SpringBoot项目结构。良好的项目架构不仅影响代码质量，更是团队协作和项目长期维护的基础。

🎯 项目架构的重要性

企业级需求：

🏗️ 结构清晰：便于团队成员理解和维护
🔧 易于扩展：支持业务功能的灵活扩展
🛡️ 职责分离：各层职责明确，降低耦合度
📊 可测试性：便于单元测试和集成测试
🚀 性能优化：合理的架构有利于性能调优

🎯 本文学习目标

学完本章后，你将能够：

✅ 设计标准的企业级项目结构
✅ 理解分层架构设计原则
✅ 实现统一异常处理机制
✅ 设计标准化的响应格式
✅ 建立代码规范和命名约定
✅ 实现参数校验和数据绑定

💡 前置知识：需要掌握前两篇的环境搭建和配置管理内容

🏗️ 项目结构设计

2.1 标准目录结构

2.1.1 Maven标准结构

# demo-project/
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/example/demo/
│ │ │ ├── │ │ │ ├── config/ │ │ │ ├── controller/ │ │ │ ├── service/ │ │ │ │ └── impl/ │ │ │ ├── repository/ │ │ │ ├── entity/ │ │ │ ├── dto/ │ │ │ ├── vo/ │ │ │ ├── enums/ │ │ │ ├── exception/ │ │ │ ├── util/ │ │ │ ├── aspect/ │ │ │ └── interceptor/ │ │ └── resources/
│ │ ├── application.yml │ │ ├── application-dev.yml │ │ ├── application-prod.yml │ │ ├── static/ │ │ ├── templates/ │ │ └── mapper/ │ └── test/
│ └── java/
│ └── com/example/demo/
│ ├── controller/ │ ├── service/ │ └── repository/ ├── pom.xml ├── README.md └── .gitignore 标准Maven项目结构
DemoApplication.java # 启动类
# 配置类
# 控制层
# 业务服务层
# 服务实现
# 数据访问层
# 实体类
# 数据传输对象
# 视图对象
# 枚举类
# 异常处理
# 工具类
# 切面类
# 拦截器
# 主配置文件
# 开发环境配置
# 生产环境配置
# 静态资源
# 模板文件
# MyBatis映射文件
# 控制器测试
# 服务测试
# 数据访问测试
# Maven配置文件
# 项目说明文档
# Git忽略文件

2.1.2 多模块项目结构

# 企业级多模块项目结构
enterprise-platform/
├── platform-parent/ # 父项目
│ └── pom.xml
├── platform-common/ # 公共模块
│ ├── platform-common-core/ # 核心工具类
│ ├── platform-common-security/ # 安全模块
│ └── platform-common-log/ # 日志模块
├── platform-business/ # 业务模块
│ ├── platform-user/ # 用户服务
│ ├── platform-order/ # 订单服务
│ └── platform-product/ # 商品服务
├── platform-gateway/ # 网关服务
├── platform-monitor/ # 监控服务
└── docs/ # 文档目录

2.2 包命名规范

2.2.1 基本命名原则

// 包命名规范示例
package com.company.project.module.layer;

// 具体示例
package com.example.ecommerce.user.controller; // 用户控制层
package com.example.ecommerce.user.service; // 用户服务层
package com.example.ecommerce.user.service.impl; // 用户服务实现
package com.example.ecommerce.user.repository; // 用户数据访问层
package com.example.ecommerce.user.entity; // 用户实体类
package com.example.ecommerce.common.exception; // 公共异常处理
package com.example.ecommerce.common.util; // 公共工具类

2.2.2 分层包结构

// 推荐的分层包结构
com.example.demo
├── DemoApplication.java // 启动类
├── config/ // 配置层
│ ├── WebConfig.java // Web配置
│ ├── DatabaseConfig.java // 数据库配置
│ ├── SecurityConfig.java // 安全配置
│ └── SwaggerConfig.java // API文档配置
├── controller/ // 控制层
│ ├── UserController.java
│ ├── ProductController.java
│ └── OrderController.java
├── service/ // 服务层接口
│ ├── UserService.java
│ ├── ProductService.java
│ ├── OrderService.java
│ └── impl/ // 服务实现
│ ├── UserServiceImpl.java
│ ├── ProductServiceImpl.java
│ └── OrderServiceImpl.java
├── repository/ // 数据访问层
│ ├── UserRepository.java
│ ├── ProductRepository.java
│ └── OrderRepository.java
├── entity/ // 实体类
│ ├── User.java
│ ├── Product.java
│ └── Order.java
├── dto/ // 数据传输对象
│ ├── request/ // 请求DTO
│ │ ├── UserCreateRequest.java
│ │ └── ProductQueryRequest.java
│ └── response/ // 响应DTO
│ ├── UserResponse.java
│ └── ProductResponse.java
├── vo/ // 视图对象
│ ├── UserVO.java
│ └── ProductVO.java
├── enums/ // 枚举类
│ ├── UserStatusEnum.java
│ ├── OrderStatusEnum.java
│ └── ErrorCodeEnum.java
├── exception/ // 异常处理
│ ├── GlobalExceptionHandler.java
│ ├── BusinessException.java
│ └── ValidationException.java
├── util/ // 工具类
│ ├── ResponseUtil.java
│ ├── DateUtil.java
│ └── SecurityUtil.java
├── aspect/ // 切面类
│ ├── LogAspect.java
│ └── SecurityAspect.java
└── interceptor/ // 拦截器
├── AuthInterceptor.java
└── LoggingInterceptor.java

🛡️ 统一异常处理

3.1 异常体系设计

3.1.1 基础异常类

// BusinessException.java – 业务异常基类
@Data
@EqualsAndHashCode(callSuper = true)
public class BusinessException extends RuntimeException {

private Integer code;
private String message;
private Object data;
private Long timestamp;

public BusinessException(String message) {

super(message);
this.code = 500;
this.message = message;
this.timestamp = System.currentTimeMillis();
}

public BusinessException(Integer code, String message) {

super(message);
this.code = code;
this.message = message;
this.timestamp = System.currentTimeMillis();
}

public BusinessException(ErrorCodeEnum errorCode) {

super(errorCode.getMessage());
this.code = errorCode.getCode();
this.message = errorCode.getMessage();
this.timestamp = System.currentTimeMillis();
}

public BusinessException(ErrorCodeEnum errorCode, Object data) {

super(errorCode.getMessage());
this.code = errorCode.getCode();
this.message = errorCode.getMessage();
this.data = data;
this.timestamp = System.currentTimeMillis();
}
}

3.1.2 错误码枚举

// ErrorCodeEnum.java – 错误码枚举
@Getter
@AllArgsConstructor
public enum ErrorCodeEnum {

// 通用错误码 (1000-1999)
SUCCESS(0, \”操作成功\”),
SYSTEM_ERROR(1000, \”系统错误\”),
PARAM_ERROR(1001, \”参数错误\”),
VALIDATION_ERROR(1002, \”数据验证失败\”),
UNAUTHORIZED(1003, \”未授权访问\”),
FORBIDDEN(1004, \”权限不足\”),
NOT_FOUND(1005, \”资源不存在\”),
METHOD_NOT_ALLOWED(1006, \”请求方法不允许\”),

// 用户相关错误码 (2000-2999)
USER_NOT_FOUND(2000, \”用户不存在\”),
USER_ALREADY_EXISTS(2001, \”用户已存在\”),
USER_PASSWORD_ERROR(2002, \”密码错误\”),
USER_ACCOUNT_LOCKED(2003, \”账户已被锁定\”),
USER_LOGIN_EXPIRED(2004, \”登录已过期\”),

// 业务相关错误码 (3000-3999)
ORDER_NOT_F

SpringBoot从零搭建项目系列（三）｜项目结构设计与分层架构