构建/配置/调试 Spring Boot 3.x 企业级…

面向 Spring Boot 3.x、Java 21、微服务/响应式编程的企业 Java 应用，提供架构设计、实现、数据访问、安全配置与测试质量保障的可复用做法。

适用场景

解决思路

1. 架构分析：审查项目结构、依赖和 Spring 配置。
2. 领域设计：按 DDD 与 Clean Architecture 创建模型；继续实现前先验证领域边界；若边界不清晰，先解决歧义再实现。
3. 实现：使用 Spring Boot 最佳实践构建服务。
4. 数据层：优化 JPA 查询并实现 Repository；运行 `./mvnw verify -pl <module>` 确认查询正确性；若集成测试失败，查看 Hibernate SQL 日志，修复查询或映射，然后重新运行再继续。
5. 安全与配置：应用 Spring Security，外置配置，添加可观测性；安全变更后运行 `./mvnw verify` 确认过滤器链和 JWT 接线；若测试失败，检查 `SecurityFilterChain` bean 顺序和 token 校验配置，然后重新运行。
6. 质量保证：运行 `./mvnw verify`（Maven）或 `./gradlew check`（Gradle），确认所有测试通过且覆盖率在关闭前达到 85%+；若覆盖率低于阈值，通过 JaCoCo 报告（`target/site/jacoco/index.html`）识别未测试分支，补充缺失测试用例并重新运行。
7. 按上下文加载参考指南：Spring Boot 项目设置/配置/starters 时加载 `references/spring-boot-setup.md`；WebFlux/Project Reactor/R2DBC 时加载 `references/reactive-webflux.md`；JPA/Hibernate/查询调优时加载 `references/jpa-optimization.md`；OAuth2/JWT/方法安全时加载 `references/spring-security.md`；JUnit 5/TestContainers/Mockito 时加载 `references/testing-patterns.md`。
8. MUST DO：使用 Java 21 LTS 特性（records、sealed classes、pattern matching）。
9. MUST DO：应用数据库迁移（Flyway/Liquibase）。
10. MUST DO：用 OpenAPI/Swagger 记录 API。
11. MUST DO：使用合适的异常处理层级。
12. MUST DO：外置所有配置（绝不硬编码值）。
13. MUST NOT DO：使用已弃用的 Spring API。
14. MUST NOT DO：跳过输入校验。
15. MUST NOT DO：未加密存储敏感数据。
16. MUST NOT DO：在响应式应用中使用阻塞代码。
17. MUST NOT DO：忽略事务边界。
18. 输出模板：实现 Java 功能时提供：领域模型（实体、DTO、records）；服务层（业务逻辑、事务）；Repository 接口（Spring Data）；Controller/REST 端点；具有全面覆盖的测试类；架构决策的简要说明。
19. 最小 WebFlux REST 端点示例：使用 `@RestController`、`@RequestMapping("/api/v1/orders")`、`@RequiredArgsConstructor` 构造器注入 `OrderService`；GET `/{id}` 返回 `Mono<ResponseEntity<OrderDto>>`，用 `map(ResponseEntity::ok)` 和 `defaultIfEmpty(ResponseEntity.notFound().build())`；POST 方法接收 `@Valid @RequestBody CreateOrderRequest`，返回 `Mono<OrderDto>`，用 `@ResponseStatus(HttpStatus.CREATED)`。
20. JPA Repository 优化查询示例：避免 N+1，使用 `@Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.customerId = :customerId")`；使用投影 `@Query("SELECT new com.example.dto.OrderSummary(o.id, o.status, o.total) FROM Order o WHERE o.status = :status")` 和 `Pageable` 限制获取列。
21. Spring Security OAuth2 JWT 配置示例：使用 `@Configuration` 和 `@EnableMethodSecurity`；定义 `SecurityFilterChain` bean，禁用 CSRF，设置 `SessionCreationPolicy.STATELESS`，允许 `/actuator/health`，其他请求需认证，启用 `oauth2ResourceServer().jwt()`。
22. 围绕以下技术栈实现：Spring Boot 3.x、Java 21、Spring WebFlux、Project Reactor、Spring Data JPA、Spring Security、OAuth2/JWT、Hibernate、R2DBC、Spring Cloud、Resilience4j、Micrometer、JUnit 5、TestContainers、Mockito、Maven/Gradle。

适用边界 · 注意事项

• 项目不是 Java/Spring Boot 3.x/Java 21 企业应用时，不应套用该技能。
• 无法运行 Maven/Gradle 构建验证，或无法接受 85%+ 覆盖率门禁时。
• 项目明确不使用 DDD/Clean Architecture、OAuth2/JWT 或响应式编程时。