spring-boot-rest-api-standards 是做什么的？
为Spring Boot项目提供REST API设计标准与最佳实践，适用于创建或审查REST端点、DTO、错误处理、分页、安全头、HATEOAS及架构模式。
概述
此技能旨在帮助开发者在Spring Boot项目中遵循经过验证的REST API设计标准。通过一系列最佳实践，确保API的可读性、一致性和可维护性。
核心原则
- 一致性：所有端点、DTO和错误响应保持统一的命名和结构。
- 安全性：默认启用安全头部，防止常见Web攻击。
- 可扩展性：支持分页和HATEOAS，便于客户端发现和使用API。
- 健壮性：统一的错误处理机制，提供有意义的错误信息。
使用场景
- 创建新的REST端点
- 审查现有API设计
- 重构遗留接口以符合标准
- 培训新团队成员
最佳实践清单
端点设计
- 使用名词而非动词：
/users而非/getUsers - 使用复数形式：
/users而非/user - 资源嵌套：
/users/{userId}/orders - 版本控制：
/api/v1/users
DTO设计
- 使用
@Data注解生成getter/setter - 使用
@Builder模式构建复杂DTO - 使用
@Valid进行请求参数验证 - 分离请求DTO和响应DTO
错误处理
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
ErrorResponse error = new ErrorResponse(
HttpStatus.NOT_FOUND.value(),
ex.getMessage(),
LocalDateTime.now()
);
return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
}
}
分页
- 使用Spring Data的
Pageable接口 - 返回
Page<T>格式 - 包含分页元数据：
totalElements,totalPages,number,size
安全头
- 使用
Content-Security-Policy - 启用
X-Content-Type-Options: nosniff - 设置
X-Frame-Options: DENY - 配置
Strict-Transport-Security
HATEOAS
- 使用
RepresentationModel或CollectionModel - 提供
self、next、prev链接 - 使用
WebMvcLinkBuilder构建链接
架构模式
- 分层架构：Controller -> Service -> Repository
- 使用接口定义服务契约
- 使用依赖注入管理组件
- 遵循SOLID原则
工具支持
- 集成Checkstyle或PMD进行静态检查
- 使用Postman或Swagger进行API测试
- 使用Spring Boot Actuator监控端点
相关资源
此技能适用于任何Spring Boot项目，建议作为团队开发标准的一部分。