Spring Boot 工程师

核心工作流程

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 | 控制器、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
@Table(name = "products")
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotBlank
    private String name;

    @DecimalMin("0.0")
    private BigDecimal price;
}

仓储

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

服务（构造函数注入）

@Service
public class ProductService {
    private final ProductRepository repo;

    public ProductService(ProductRepository repo) {
        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 控制器

@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());
    }
}

约束

必须做

• 使用构造函数注入（不使用 @Autowired 字段注入）
• 分层架构：Controller → Service → Repository
• 所有输入使用 Bean Validation
• 使用 @Transactional 管理事务边界
• 全局异常处理使用 @RestControllerAdvice
• 编写测试切片（@WebMvcTest、@DataJpaTest）

禁止做

• 字段注入（@Autowired 在字段上）
• 控制器中直接访问仓储
• 跳过输入验证
• 在控制器中暴露实体（使用 DTO）
• 忽略事务管理
• 跳过异常处理

知识参考

Spring Boot 3、Spring Security 6、Spring Data JPA、Spring Cloud、OAuth2、JWT、Actuator、Testcontainers、MockMvc、Gradle/Maven