用 Spring Boot 3.x 构建 REST API…

在开发 Spring Boot 3.x 应用、微服务或响应式 Java 服务时，按分层结构实现控制器、服务、数据访问、安全与测试。

适用场景

解决思路

1. 分析需求：识别服务边界、API、数据模型与安全需求。
2. 设计架构：规划微服务、数据访问、云集成与安全方案，编码前先确认设计。
3. 实现：使用构造器注入和分层架构创建服务（Entity、Repository、Service、REST Controller、DTO record、全局异常处理器）。
4. 安全：添加 Spring Security、OAuth2、方法级安全与 CORS 配置；验证安全规则能编译并通过测试，若编译或测试失败则查看错误输出、修复失败的规则或配置并重新运行。
5. 测试：编写单元测试、集成测试与切片测试；运行 `./mvnw test`（或 `./gradlew test`）并确认全部通过，若失败则查看堆栈跟踪、定位失败的断言或组件、修复后重新运行完整测试套件。
6. 部署：通过 Actuator 配置健康检查与可观测性；验证 `/actuator/health` 返回 `UP`，若为 `DOWN` 则检查响应中的 `components` 详情、解决失败组件（如数据源、消息代理）并重新验证。
7. 按上下文加载参考文档：Web 层（`references/web.md`，用于控制器、REST API、校验、异常处理）、数据访问（`references/data.md`，用于 Spring Data JPA、仓库、事务、投影）、安全（`references/security.md`，用于 Spring Security 6、OAuth2、JWT、方法级安全）、云原生（`references/cloud.md`，用于 Spring Cloud、Config、Discovery、Gateway、弹性）、测试（`references/testing.md`，用于 @SpringBootTest、MockMvc、Testcontainers、测试切片）。
8. 使用构造器注入：`public MyService(Dep dep) { this.dep = dep; }`，不要用字段注入。
9. 在每个变更端点使用 `@Valid @RequestBody MyRequest req` 校验 API 输入。
10. 使用类型安全配置：`@ConfigurationProperties(prefix = "app")` 绑定到 record/class。
11. 使用合适的构造型注解：业务逻辑用 `@Service`，数据访问用 `@Repository`，HTTP 用 `@RestController`。
12. 事务范围：多步写入用 `@Transactional`，读取用 `@Transactional(readOnly = true)`。
13. 隐藏内部细节：在 `@RestControllerAdvice` 中捕获领域异常，返回 problem details 而非堆栈跟踪。
14. 外部化密钥：使用环境变量或 Spring Cloud Config，绝不要写在 `application.properties` 中。
15. 不要使用字段注入（在字段上使用 `@Autowired`）。
16. 不要跳过 API 端点的输入校验。
17. 不要在适用 `@Service`/`@Repository`/`@Controller` 时使用 `@Component`。
18. 不要混用阻塞与响应式代码（例如在 WebFlux 链中调用 `.block()`）。
19. 不要在 `application.properties`/`application.yml` 中存储密钥或凭据。
20. 不要硬编码 URL、凭据或环境相关值。
21. 不要使用已弃用的 Spring Boot 2.x 模式（例如 `WebSecurityConfigurerAdapter`）。

适用边界 · 注意事项

• 不使用 Spring Boot 3.x 或仍基于 Spring Boot 2.x 已弃用模式的项目。
• 不需要 Java 后端、微服务或响应式 WebFlux 的场景。
• 无法运行 Maven/Gradle 测试或 Actuator 健康检查的环境。