spring-boot-engineer

Spring Boot Engineer 是一个用于 Spring Boot 3.x 开发的技能，帮助开发者生成配置、创建 REST 控制器、实现 Spring Security 6 认证流程、搭建 Spring Data JPA 仓库等。

核心工作流

1. 分析需求：识别服务边界、API、数据模型和安全需求。
2. 设计架构：规划微服务、数据访问、云集成和安全；在编码前确认设计。
3. 实现：使用构造器注入和分层架构创建服务。
4. 安全加固：添加 Spring Security、OAuth2、方法安全和 CORS 配置；验证安全规则可编译并通过测试。若编译或测试失败，需查看错误输出、修复失败的规则或配置并重新运行后再继续。
5. 测试：编写单元、集成和切片测试；运行 ./mvnw test（或 ./gradlew test）并确认全部通过后再继续。若测试失败，需查看堆栈跟踪、定位失败的断言或组件、修复问题并重新运行完整测试套件。
6. 部署：通过 Actuator 配置健康检查和可观测性；验证 /actuator/health 返回 UP。若健康状态为 DOWN，需检查响应中的组件详情，解决失败组件（如数据源、消息代理）并重新验证。

参考指南

可根据上下文加载详细指导：

• 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、测试切片。

快速开始——最小可用结构

一个标准的 Spring Boot 功能由以下层组成，可作为复制粘贴的起点。

实体（Entity）：使用 @Entity 和 @Table 注解，包含 @Id、@GeneratedValue 主键，以及 @NotBlank、@DecimalMin 等校验注解。

仓库（Repository）：继承 JpaRepository，可声明如 findByNameContainingIgnoreCase 的查询方法。

服务（Service）：使用构造器注入（不使用 @Autowired），读操作标注 @Transactional(readOnly = true)，写操作标注 @Transactional。

REST 控制器（Controller）：使用 @RestController、@RequestMapping、@Validated，通过构造器注入服务，使用 @GetMapping、@PostMapping 等映射请求，@Valid @RequestBody 校验输入。

DTO（record）：使用 record 定义请求对象，并附带校验注解。

全局异常处理器：使用 @RestControllerAdvice，通过 @ExceptionHandler 处理校验异常和实体未找到异常，返回合适的 HTTP 状态码和错误信息。

测试切片：使用 @WebMvcTest、MockMvc、@MockBean 编写控制器测试。

约束

必须遵守：

• 使用构造器注入，如 public MyService(Dep dep) { this.dep = dep; }。
• 在每个变更端点使用 @Valid @RequestBody MyRequest req 校验 API 输入。
• 使用 @ConfigurationProperties(prefix = "app") 绑定到 record/class 实现类型安全配置。
• 使用合适的构造型注解：业务逻辑用 @Service，数据用 @Repository，HTTP 用 @RestController。
• 事务范围：多步写操作使用 @Transactional，读操作使用 @Transactional(readOnly = true)。
• 隐藏内部实现：在 @RestControllerAdvice 中捕获领域异常，返回问题详情而非堆栈跟踪。
• 外部化密钥：使用环境变量或 Spring Cloud Config，绝不写入 application.properties。

禁止事项：

• 使用字段注入（在字段上使用 @Autowired）。
• 在 API 端点上跳过输入校验。
• 在适用 @Service/@Repository/@Controller 时使用 @Component。
• 混用阻塞和响应式代码（如在 WebFlux 链中调用 .block()）。
• 在 application.properties/application.yml 中存储密钥或凭据。
• 硬编码 URL、凭据或环境特定值。
• 使用已弃用的 Spring Boot 2.x 模式（如 WebSecurityConfigurerAdapter）。