Java Spring Boot 后端开发

一项专注于构建生产级 Java Spring Boot 后端服务的专业技能。

触发条件

当用户意图涉及以下场景时，启用该技能：

• 构建/创建 Spring Boot 项目或应用
• 编写 REST API、Controller、Service 或 Repository
• 配置数据库访问（Spring Data JPA、MyBatis、MyBatis-Plus）
• 实现认证与授权（Spring Security、JWT、OAuth2）
• 微服务架构（Spring Cloud、Nacos、Feign、Gateway）
• Java 代码审查、重构或性能优化
• 调试 Spring Boot 启动错误、依赖冲突或运行时问题
• 编写单元测试/集成测试（JUnit 5、Mockito、TestContainers）
• 部署 Spring Boot 应用（Docker、K8s、CI/CD）

技术栈偏好

构建工具

• Maven 为默认首选，除非用户明确指定使用 Gradle
• 以 spring-boot-starter-parent 作为父 POM
• 遵循标准 Maven 目录结构

Java 版本

• 默认使用 Java 17 LTS，除非用户另行指定（也支持 Java 8、11、21）

关键依赖（常用 Starter）

数据库规范

• 关系型数据库默认首选 MySQL；若用户明确指定，则使用 PostgreSQL
• 对于简化 CRUD 操作，推荐使用 MyBatis-Plus 而非原生 MyBatis
• 使用 JPA 时，简单查询优先采用派生查询（derived query），避免过度使用 @Query
• 务必配置连接池（HikariCP 为默认实现，仅需合理调优）
• 生产环境中使用 Flyway 或 Liquibase 进行数据库 Schema 迁移

项目架构

采用清晰关注点分离的分层架构：

src/main/java/com/example/project/
├── controller/      # REST 端点，请求/响应 DTO
├── service/         # 业务逻辑接口
│   └── impl/        # Service 实现类
├── mapper/          # 数据访问层（MyBatis）或 repository/（JPA）
├── entity/          # 数据库实体类
├── dto/             # 数据传输对象
│   ├── request/     # 入参 DTO
│   └── response/    # 出参 DTO
├── config/          # 配置类
├── common/          # 公共工具、常量、枚举
│   ├── exception/   # 自定义异常及全局异常处理器
│   ├── result/      # 统一 API 响应包装器
│   └── util/        # 工具类
└── Application.java

核心架构规则

1. Controller 层 — 仅处理 HTTP 相关逻辑：参数绑定、校验、响应封装。禁止包含任何业务逻辑。
2. Service 层 — 所有业务逻辑集中于此。Service 为无状态组件，通过 @Service 注入。
3. Mapper / Repository 层 — 仅负责数据访问，不得包含业务逻辑。
4. DTO 分离 — 禁止直接将 Entity 类暴露于 API 接口。Entity 与 DTO 之间必须显式映射。
5. 使用 MapStruct 进行 Entity-DTO 映射（字段较复杂时）；字段简单时可手动映射。

编码规范

命名约定

• Controller： XxxController
• Service 接口： XxxService
• Service 实现类： XxxServiceImpl
• Mapper： XxxMapper
• Entity： Xxx（单数名词，对应数据库表名，使用 snake_case）
• DTO： XxxRequest、XxxResponse、XxxDTO

API 设计

• 遵循 RESTful 规范（正确使用 HTTP 方法、资源命名）
• 对请求体使用 @Valid 进行校验
• 统一返回格式：

  { "code": 200, "message": "success", "data": { ... } }
  

• 使用 @RestControllerAdvice + @ExceptionHandler 实现全局异常处理
• 列表类 API 必须支持分页：使用 Spring Data 的 Pageable 或自定义分页 DTO

错误处理

• 定义继承自 RuntimeException 的自定义业务异常
• 全局异常处理器捕获所有异常，并返回结构化响应
• 按恰当级别记录日志（ERROR：未预期异常；WARN：业务规则违反）

日志

• 通过 Lombok @Slf4j 使用 SLF4J
• 按语义选择日志级别：ERROR（异常）、WARN（业务规则违规）、INFO（关键业务事件）、DEBUG（开发调试细节）
• 严禁记录敏感信息（密码、Token、PII）

配置最佳实践

application.yml 结构

server:
  port: 8080

spring:
  profiles:
    active: dev
  datasource:
    url: jdbc:mysql://localhost:3306/mydb?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
    open-in-view: false

mybatis-plus:
  mapper-locations: classpath*:mapper/**/*.xml
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

logging:
  level:
    com.example.project: info

多环境配置

• application-dev.yml — 本地开发环境（使用 H2 或本地 MySQL）
• application-test.yml — 测试环境
• application-prod.yml — 生产环境（外部化配置，禁止硬编码密钥）

测试策略

1. 单元测试：针对 Service 层，使用 JUnit 5 + Mockito
2. 集成测试：针对 Controller 层，使用 @WebMvcTest 或 MockMvc
3. Repository 测试：使用 @DataJpaTest 搭配 H2 内存数据库
4. 使用 TestContainers：对需真实数据库（MySQL、Redis 等）的集成测试场景
5. 测试方法命名规范：methodName_stateUnderTest_expectedBehavior（例如：createUser_withValidInput_returnsCreatedUser）

常见陷阱规避指南

1. 循环依赖 — 避免构造器注入形成循环；必要时使用 @Lazy 或重构依赖关系
2. 事务未回滚 — 确保 @Transactional 注解作用于 public 方法
3. N+1 查询问题 — JPA 中使用 @EntityGraph 或 JOIN FETCH；MyBatis 中使用 标签
4. 懒加载时 Session 已关闭 — 关闭 spring.jpa.open-in-view，并主动预加载所需关联数据
5. Swagger 未扫描到 Controller — 确保 Controller 所在包位于组件扫描路径内
6. 日期时区问题 — JDBC URL 中始终设置 serverTimezone=Asia/Shanghai；优先使用 Instant/LocalDateTime，避免使用 Date
7. Docker 镜像体积过大 — 使用多阶段构建；避免引入冗余镜像层

参考材料

详细参考资料存放于 references/ 目录下：

• references/spring-boot-common-patterns.md — 常见编码模式与实践方案
• references/troubleshooting.md — 高频报错及其解决方案

在当前任务涉及调试或实现特定模式时，请加载对应参考文件。