一、包结构设计核心原则

Spring Boot项目包结构设计需遵循三大核心原则：领域驱动设计（DDD）思想、关注点分离（SoC）原则和单一职责原则。合理的包结构应像城市规划般层次分明，既能快速定位功能模块，又能保持各组件间的松耦合关系。

典型的三层架构包含表现层（Web）、业务逻辑层（Service）和数据访问层（Repository），但在实际项目中往往需要更细化的分层。建议采用”纵向分模块+横向分层”的混合架构，既保持业务完整性又实现技术复用。

二、根目录标准化规范

src/main/java
├── com.example.app          # 基础包路径
│   ├── Application.java     # 启动入口类
│   ├── common               # 公共组件层
│   ├── modules              # 业务模块层
│   └── infrastructure       # 基础设施层

启动类需遵循<groupId>.<artifactId>的包命名规范，使用@SpringBootApplication注解标记。建议将配置类集中放置在config子包下，避免与业务代码混杂。

三、公共模块(common)设计实践

3.1 异常处理体系

构建完整的异常处理链需要三个核心组件：

业务异常基类：

public class BusinessException extends RuntimeException {
  private final int code;
  private final String message;
  // 构造方法与getter省略
}

全局异常处理器：

@RestControllerAdvice
public class GlobalExceptionHandler {
  @ExceptionHandler(BusinessException.class)
  public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException ex) {
      // 异常转换逻辑
  }
}

异常码枚举：建议采用模块前缀+序号的编码规则，如USER_1001表示用户模块第一个异常。

3.2 分页组件实现

分页功能应包含三个核心类：

请求参数：

public class PageRequest {
  private int pageNum = 1;
  private int pageSize = 10;
  // 计算offset的getter方法
}

结果封装：

public class PageResult<T> {
  private List<T> data;
  private long total;
  // 构造方法与getter省略
}

工具类：实现MyBatis分页插件集成或JPA分页查询转换。

3.3 响应封装规范

统一响应格式应包含：

public class Result<T> {
    private int code;
    private String message;
    private T data;
    private long timestamp;
    public static <T> Result<T> success(T data) {
        // 实现逻辑
    }
}

建议定义ResultCode枚举规范成功/失败场景，错误响应可继承ErrorResponse扩展更多字段。

四、业务模块(modules)设计范式

4.1 模块划分标准

业务模块应按照领域边界划分，每个模块包含：

Controller：处理HTTP请求，参数校验
Service：业务逻辑实现，可细分接口与实现类
Repository：数据访问，可按技术栈选择MyBatis/JPA
Model：包含DTO、Entity、VO等数据对象
Converter：对象转换逻辑，推荐使用MapStruct等工具

4.2 数据对象分层

建议采用四层数据模型：

Entity：与数据库表映射的实体类
DTO：数据传输对象，区分Request/Response
VO：视图对象，用于前端展示
Query：复杂查询条件封装

以用户模块为例：

user/model/
├── dto/
│   ├── request/
│   │   ├── UserCreateRequest.java
│   │   └── UserUpdateRequest.java
│   └── response/
│       └── UserResponse.java
├── entity/
│   └── UserEntity.java
├── vo/
│   └── UserVO.java
└── query/
    └── UserQueryCondition.java

4.3 转换器实现

推荐使用MapStruct实现对象转换：

@Mapper(componentModel = "spring")
public interface UserConverter {
    UserConverter INSTANCE = Mappers.getMapper(UserConverter.class);
    UserVO entityToVo(UserEntity entity);
    @Mapping(target = "createTime", expression = "java(java.time.LocalDateTime.now())")
    UserEntity requestToEntity(UserCreateRequest request);
}

五、基础设施层(infrastructure)设计

5.1 持久化配置

MyBatis配置示例：

@Configuration
@MapperScan("com.example.app.modules.*.repository")
public class MyBatisConfig {
    @Bean
    public ConfigurationCustomizer configurationCustomizer() {
        return configuration -> {
            configuration.setMapUnderscoreToCamelCase(true);
            configuration.setCacheEnabled(false);
        };
    }
}

5.2 Web配置增强

自定义WebMvcConfig可实现：

统一异常处理
跨域配置
拦截器注册
参数校验全局配置

5.3 安全模块集成

安全配置建议独立成模块，包含：

认证授权配置
权限校验注解
安全相关异常处理
CSRF/XSS防护配置

六、进阶优化建议

多环境配置：使用application-{profile}.yml实现环境隔离
日志规范：采用AOP实现统一日志记录
监控集成：暴露Actuator端点并配置安全策略
文档生成：集成Swagger或SmartDoc自动生成API文档
代码生成：基于MyBatis-Plus等工具自动生成CRUD代码

合理的包结构设计是项目长期可维护性的基础保障。建议在新项目启动时投入足够时间进行架构设计，对于已有项目可采用渐进式重构策略。实际开发中应结合团队规模、项目复杂度等因素灵活调整，在标准化与灵活性之间找到最佳平衡点。

Spring Boot项目标准化包结构设计指南