Spring Boot 项目结构最佳实践

一个清晰合理的项目结构是大型Spring Boot项目长期可维护的基础。本文将从分层架构、模块化设计、配置管理和代码规范四个维度，总结实际项目中的最佳实践。

1. 分层架构设计

传统的三层架构（Controller-Service-DAO）在中小型项目中仍然是最佳选择。推荐的项目包结构如下：

com.company.project/
├── controller/        # 接口层，接收请求、返回响应
├── service/           # 业务逻辑层
│   └── impl/          # 业务实现类
├── repository/        # 数据访问层（DAO/Repository）
├── model/
│   ├── entity/        # 数据库实体
│   ├── dto/           # 数据传输对象
│   └── vo/            # 视图响应对象
├── config/            # 配置类
├── common/
│   ├── exception/     # 全局异常
│   ├── util/          # 工具类
│   └── constant/      # 常量定义
├── interceptor/       # 拦截器
└── aspect/            # 切面定义

1.1 分层职责

• Controller层：只负责请求路由、参数校验和响应封装，不应包含任何业务逻辑
• Service层：封装核心业务逻辑，一个方法对应一个完整的业务流程
• Repository层：数据访问抽象，屏蔽底层数据库差异

关键原则：严禁跨层调用。Controller不能直接调用Repository，Service不能直接持有HttpServletRequest。每一层只能与相邻层交互。

2. 模块化拆分策略

当项目规模增大时，单模块架构会导致编译慢、耦合高、职责不清。此时应考虑多模块拆分：

project-root/
├── project-common/        # 公共工具、异常定义、通用响应
├── project-dal/           # 数据访问层（MyBatis Mapper、Entity）
├── project-service/       # 业务逻辑层
├── project-web/           # Web接口层（Controller）
├── project-job/           # 定时任务模块
└── project-api/           # 对外API定义（Feign接口）

2.1 拆分原则

• 高内聚低耦合：每个模块内部高度相关，模块间依赖最小化
• 单向依赖：web层依赖service层，service层依赖dal层，避免循环依赖
• 接口隔离：模块间通过接口通信，避免直接暴露内部实现

在Maven中通过dependencyManagement统一管理版本：

<!-- 父POM统一管理版本 -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.company</groupId>
            <artifactId>project-common</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

3. 配置管理最佳实践

3.1 多环境配置

Spring Boot推荐使用Profile机制管理不同环境的配置：

• application.yml：公共配置
• application-dev.yml：开发环境
• application-test.yml：测试环境
• application-prod.yml：生产环境

在application.yml中激活Profile：

spring:
  profiles:
    active: dev  # 通过启动参数 --spring.profiles.active=prod 覆盖

3.2 配置管理注意事项

• 敏感信息加密：数据库密码、API密钥等使用Jasypt或配置中心加密
• 配置集中化：生产环境推荐使用Nacos、Apollo等配置中心
• 避免魔法值：业务常量写在配置文件中，而非代码中硬编码

4. 代码规范与命名约定

统一的代码规范能极大降低团队协作成本：

4.1 命名规范

元素	规范	示例
Controller类	XxxController	UserController
Service接口	IXxxService	IUserService
ServiceImpl	XxxServiceImpl	UserServiceImpl
Mapper接口	XxxMapper	UserMapper
Entity类	XxxEntity或XxxDO	UserEntity
DTO类	XxxDTO	UserCreateDTO

4.2 RESTful接口规范

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    @GetMapping
    public Result<PageResult<UserVO>> list(UserQuery query) { }

    @GetMapping("/{id}")
    public Result<UserVO> get(@PathVariable Long id) { }

    @PostMapping
    public Result<Long> create(@Valid @RequestBody UserCreateDTO dto) { }

    @PutMapping("/{id}")
    public Result<Void> update(@PathVariable Long id,
                                @Valid @RequestBody UserUpdateDTO dto) { }

    @DeleteMapping("/{id}")
    public Result<Void> delete(@PathVariable Long id) { }
}

4.3 统一响应体

定义统一的API响应结构，方便前端统一处理：

public class Result<T> {
    private int code;
    private String message;
    private T data;
    private long timestamp;

    public static <T> Result<T> success(T data) {
        return new Result<>(200, "success", data, System.currentTimeMillis());
    }

    public static <T> Result<T> error(int code, String message) {
        return new Result<>(code, message, null, System.currentTimeMillis());
    }
}

好的项目结构是良好设计的体现。它不仅让代码更容易理解和维护，也为后续的功能迭代和团队扩展打下了坚实的基础。希望本文的经验能对你的项目实践有所帮助。