用途:为 Spring Boot 项目提供 REST API 设计规范与最佳实践,用于创建或评审 REST 端点、DTO、错误处理、校验、分页与安全响应头。
主要能力:
- URL 设计:资源名用复数名词,遵循 GET /users、POST /users、PUT /users/{id} 等约定,避免 /getUserList 这类动作式 URL。
- HTTP 方法:GET 安全幂等、POST 非幂等、PUT 整体替换幂等、PATCH 部分更新非幂等、DELETE 幂等。
- 状态码:200、201(带 Location 头)、204、400、404、409、500 等。
- DTO:API 契约与领域实体分离,可用 Java record 或 Lombok @Data/@Value,尽量不可变,并加 Jakarta 校验注解。
- 校验:@RequestBody 参数加 @Valid,使用 @NotBlank、@Email、@Size 等,处理 MethodArgumentNotValidException。
- 错误处理:用 @RestControllerAdvice 全局处理,返回含 status、error、message、timestamp 的统一错误响应,也可用 ResponseStatusException。
- 分页:使用 Pageable,支持 page、size、sort,返回 total elements、totalPages 等元数据。
- 安全头:配置 CORS、内容安全策略、X-Frame-Options、X-Content-Type-Options。
使用方式:按步骤设计 URL、选择方法、确定状态码、编写 DTO、加校验、配置全局异常处理、分页与安全头;每步后可用 curl 或 HTTPie 验证。示例包含基础 CRUD 控制器、请求/响应 DTO 与全局异常处理器。
最佳实践:构造器注入、不可变 DTO、正确事务管理(@Transactional 与只读事务)。
限制与警告:不要直接暴露实体;遵循 REST 约定;全局处理所有异常;大结果集必须分页;校验所有输入;不得记录或暴露密码、令牌、PII。参考资料见 references/ 目录,代码评审可参考 developer-kit-java:spring-boot-code-review-expert,依赖注入见 spring-boot-dependency-injection/SKILL.md,测试见 ../spring-boot-test-patterns/SKILL.md。