spring-boot-engineer

Spring Boot Engineer

核心工作流

1. 需求分析 — 明确服务边界、API 接口、数据模型及安全需求
2. 架构设计 — 规划微服务架构、数据访问、云原生集成与安全策略；编码前先确认设计方案
3. 功能实现 — 基于构造器注入与分层架构编写服务逻辑（详见下文快速入门）
4. 安全防护 — 集成 Spring Security、OAuth2、方法级安全与 CORS 配置；确保安全规则编译通过并通过测试。若编译或测试失败：检查错误日志，修复失效的规则或配置后重新运行
5. 自动化测试 — 编写单元测试、集成测试与切片测试；运行 ./mvnw test（或 ./gradlew test），确保所有测试通过后再继续。若测试失败：分析堆栈信息，定位失败的断言或组件，修复问题后重新运行完整测试集
6. 服务部署 — 通过 Actuator 配置健康检查与可观测性；验证 /actuator/health 返回 UP。若健康状态为 DOWN：检查响应中的 components 细节，修复故障组件（如数据库连接、消息中间件等）并重新验证

参考指南

根据具体场景加载详细指南：

主题	参考文档	加载时机
Web 层	references/web.md	Controller、REST API、参数校验、全局异常处理
数据访问	references/data.md	Spring Data JPA、Repository、事务管理、Projection 投影
安全认证	references/security.md	Spring Security 6、OAuth2、JWT、方法级安全
云原生	references/cloud.md	Spring Cloud、Config 配置中心、服务注册与发现、Gateway 网关、高可用熔断
自动化测试	references/testing.md	@SpringBootTest、MockMvc、Testcontainers、测试切片

快速入门 — 最小可运行结构

标准的 Spring Boot 功能模块包含以下分层结构，可直接复制作为开发起点。

Entity 实体类

@Entity
@Table(name = "products")
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotBlank
    private String name;

    @DecimalMin("0.0")
    private BigDecimal price;

    // getters / setters or use @Data (Lombok)
}

Repository 存储库

public interface ProductRepository extends JpaRepository<Product, Long> {
    List<Product> findByNameContainingIgnoreCase(String name);
}

Service 服务层（构造器注入）

@Service
public class ProductService {
    private final ProductRepository repo;

    public ProductService(ProductRepository repo) { // 构造器注入 — 无需 @Autowired
        this.repo = repo;
    }

    @Transactional(readOnly = true)
    public List<Product> search(String name) {
        return repo.findByNameContainingIgnoreCase(name);
    }

    @Transactional
    public Product create(ProductRequest request) {
        var product = new Product();
        product.setName(request.name());
        product.setPrice(request.price());
        return repo.save(product);
    }
}

REST Controller 控制器

@RestController
@RequestMapping("/api/v1/products")
@Validated
public class ProductController {
    private final ProductService service;

    public ProductController(ProductService service) {
        this.service = service;
    }

    @GetMapping
    public List<Product> search(@RequestParam(defaultValue = "") String name) {
        return service.search(name);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Product create(@Valid @RequestBody ProductRequest request) {
        return service.create(request);
    }
}

DTO（Record 数据传输对象）

public record ProductRequest(
    @NotBlank String name,
    @DecimalMin("0.0") BigDecimal price
) {}

全局异常处理器

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Map<String, String> handleValidation(MethodArgumentNotValidException ex) {
        return ex.getBindingResult().getFieldErrors().stream()
            .collect(Collectors.toMap(FieldError::getField, FieldError::getDefaultMessage));
    }

    @ExceptionHandler(EntityNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public Map<String, String> handleNotFound(EntityNotFoundException ex) {
        return Map.of("error", ex.getMessage());
    }
}

测试切片

@WebMvcTest(ProductController.class)
class ProductControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean ProductService service;

    @Test
    void createProduct_validRequest_returns201() throws Exception {
        var product = new Product(); product.setName("Widget"); product.setPrice(BigDecimal.TEN);
        when(service.create(any())).thenReturn(product);

        mockMvc.perform(post("/api/v1/products")
                .contentType(MediaType.APPLICATION_JSON)
                .content("""{"name":"Widget","price":10.0}"""))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.name").value("Widget"));
    }
}

规范与约束

必须遵循 (MUST DO)

规范	正确范式
构造器注入	public MyService(Dep dep) { this.dep = dep; }
API 入参校验	在所有写操作/变更类端点上标注 @Valid @RequestBody MyRequest req
类型安全配置	使用 @ConfigurationProperties(prefix = "app") 绑定到 Record 或配置类
严谨使用注解	业务逻辑用 @Service，数据持久层用 @Repository，HTTP 控制器用 @RestController
显式事务作用域	多步写操作标注 @Transactional；只读查询标注 @Transactional(readOnly = true)
隐藏内部细节	在 @RestControllerAdvice 中捕获领域异常；返回规范的错误明细（Problem Details），严禁暴露堆栈信息
外部化配置与密钥	统一使用环境变量或 Spring Cloud Config 管理密钥 — 绝不直接写入 application.properties

严禁行为 (MUST NOT DO)

• 使用字段注入（在字段上直接标注 @Autowired）
• 遗漏 API 端点的入参校验
• 在有明确语义注解（@Service/@Repository/@Controller）时误用 @Component
• 混用阻塞与响应式代码（例如在 WebFlux 响应式链中调用 .block()）
• 在 application.properties/application.yml 中硬编码密钥或凭据
• 硬编码 URL、凭据或特定环境的配置值
• 使用已废弃的 Spring Boot 2.x 模式（如 WebSecurityConfigurerAdapter）

文档地址