# Spring Boot REST API 标准该技能为在 Spring Boot 应用程序中构建 RESTful API 提供了全面的指导，具有一致的设计模式、正确的错误处理、验证以及基于 REST 原则和 Spring Boot 约定的架构最佳实践。 ## 概述 Spring Boot REST API 标准为构建生产就绪的 REST API 建立了一致的模式。这些标准涵盖基于资源的 URL 设计、正确的 HTTP 方法使用、状态代码约定、DTO 模式、验证、错误处理、分页、安全标头和体系结构分层。实现这些模式可确保 API 一致性、可维护性并遵守 REST 原则。 ## 何时使用此技能在以下情况下使用此技能： * 创建新的 REST 端点和 API 路由 * 设计请求/响应 DTO 和 API 合约 * 规划HTTP方法和状态码 * 实现错误处理和验证 * 设置分页、过滤和排序 * 设计安全标头和 CORS 策略 * 实现 HATEOAS（超媒体作为应用程序状态的引擎） * 回顾 REST API 架构和设计模式 * 使用一致的 API 标准构建微服务 * 使用清晰的合同记录 API 端点 ## 说明 ### 构建 RESTful API 端点请按照以下步骤创建设计良好的 REST API 端点： 1. **设计基于资源的 URL** * 资源名称使用复数名词 * 遵循 REST 约定：GET /users、POST /users、PUT /users/{id} * 避免基于操作的 URL，例如 /getUserList 2. **实施正确的 HTTP 方法** * GET：检索资源（安全、幂等） * POST：创建资源（非幂等） * PUT：替换整个资源（幂等） * PATCH：部分更新（非幂等） * DELETE：删除资源（幂等） 3. **使用适当的状态代码** * 200 OK：成功获取/放置/修补 * 201 已创建：带有位置标头的成功 POST * 204 无内容：删除成功 * 400 Bad Request：无效的请求数据 * 404 Not Found：资源不存在 * 409 冲突：重复资源 * 500 内部服务器错误：意外错误 4. **创建请求/响应 DTO** * 将 API 合约与域实体分开 * 使用Java记录或Lombok `@Data`/`@Value` * 应用Jakarta验证注释 * 尽可能保持 DTO 不可变 5. **实施验证** * 在`@RequestBody`参数上使用`@Valid`注解 * 应用验证约束（`@NotBlank`、`@Email`、`@Size` 等） * 使用“MethodArgumentNotValidException”处理验证错误 6. **设置错误处理** * 使用`@RestControllerAdvice`进行全局异常处理 * 返回带有状态、错误、消息和时间戳的标准化错误响应 * 对特定的 HTTP 状态代码使用 `ResponseStatusException` 7. **配置分页** * 对大型数据集使用 Pageable * 包含页面、大小、排序参数 * 返回元数据，包括总元素数、总页数等。 8. **添加安全标头** * 配置CORS策略 * 设置内容安全策略 * 包括X-Frame-Options、X-Content-Type-Options ## 示例 ### 基本 CRUD 控制器 @RestController @RequestMapping(“/v1/用户”) @RequiredArgsConstructor @Slf4j 公共类用户控制器{ 私有最终 UserService userService； @GetMapping 公共 ResponseEntity<页面> getAllUsers( @RequestParam(defaultValue = "0") int 页， @RequestParam(defaultValue = "10") int pageSize) { log.debug("正在获取用户页面{}大小{}", page, pageSize); Page users = userService.getAll(page, pageSize); 返回 ResponseEntity.ok(用户); } @GetMapping("/{id}") 公共 ResponseEntity getUserById(@PathVariable Long id) { 返回 ResponseEntity.ok(userService.getById(id)); } @PostMapping 公共 ResponseEntity createUser(@Valid @RequestBody CreateUserRequest 请求) { 创建的 UserResponse = userService.create(request); 返回 ResponseEntity.status(HttpStatus.CREATED).body(已创建); } @PutMapping("/{id}") 公共 ResponseEntity updateUser( @PathVariable长id， @Valid @RequestBody UpdateUserRequest 请求）{ 返回 ResponseEntity.ok(userService.update(id, request)); } @DeleteMapping("/{id}") 公共 ResponseEntity deleteUser(@PathVariable Long id) { userService.delete(id); 返回 ResponseEntity.noContent().build(); } } ### 请求/响应 DTO // 请求DTO @数据 @NoArgs构造函数 @AllArgsConstructor 公共类CreateUserRequest { @NotBlank(message = "用户名不能为空") 私有字符串名称； @Email(message = "需要有效的电子邮件地址") 私人字符串电子邮件； } // 响应DTO @数据 @NoArgs构造函数 @AllArgsConstructor 公共类用户响应{ 私人长ID；私有字符串名称；私人字符串电子邮件；私有 LocalDateTime 创建于； } ### 全局异常处理程序 @RestControllerAdvice @Slf4j 公共类 GlobalExceptionHandler { @ExceptionHandler(MethodArgumentNotValidException.class) 公共 ResponseEntity handleValidationException( MethodArgumentNotValidException 例如，WebRequest 请求）{ 字符串错误 = ex.getBindingResult().getFieldErrors().stream() .map(f -> f.getField() + ": " + f.getDefaultMessage()) .collect(Collectors.joining(", ")); 错误响应错误响应 = 新的错误响应( HttpStatus.BAD_REQUEST.value(), “验证错误”， “验证失败：” + 错误， request.getDescription(false).replaceFirst("uri=", "") ）；返回新的 ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST); } @ExceptionHandler(ResponseStatusException.class) 公共 ResponseEntity handlerResponseStatusException( ResponseStatusException 例如，WebRequest 请求）{ 错误响应错误=新的错误响应（ ex.getStatusCode().value(), 例如.getStatusCode().toString(), 例如 getReason(), request.getDescription(false).replaceFirst("uri=", "") ）；返回新的 ResponseEntity<>(错误, ex.getStatusCode()); } } ## 最佳实践 ### 1\.使用构造函数注入 @服务 @RequiredArgsConstructor 公共类用户服务{ 私有最终 UserRepository userRepository；私人最终电子邮件服务电子邮件服务； // 依赖关系是明确的且可测试的 } ### 2\.更喜欢不可变的 DTO // Java 记录 (JDK 16+) 公共记录 UserResponse(长 id, 字符串名称, 字符串电子邮件, LocalDateTime 创建时间) {} // Lombok @Value 的不变性 @值公共类用户响应{ 长 ID；字符串名称；字符串电子邮件；本地日期时间创建于； } ### 3\.尽早验证输入 @PostMapping 公共 ResponseEntity createUser(@Valid @RequestBody CreateUserRequest 请求) { // 验证在方法执行之前自动发生返回 ResponseEntity.status(HttpStatus.CREATED).body(userService.create(request)); } ### 4\.灵活使用ResponseEntity 返回 ResponseEntity.status(HttpStatus.CREATED) .header("位置", "/api/users/" + created.getId()) .header("X-Total-Count", String.valueOf(userService.count())) .body（创建）； ### 5\.实施适当的交易管理 @服务 @事务性公共类用户服务{ @Transactional(只读 = true) 公共可选<用户> findById（长id）{ 返回 userRepository.findById(id); } @事务性公共用户创建（用户用户）{ 返回 userRepository.save(user); } } ### 6\.添加有意义的日志记录 @Slf4j @服务公共类用户服务{ 公共用户创建（用户用户）{ log.info("使用电子邮件创建用户：{}", user.getEmail()); 返回 userRepository.save(user); } } ### 7\.使用 Javadoc 记录 API /** * 通过 id 检索用户。 * * @param id 用户id * @return 包含 UserResponse 的 ResponseEntity * 如果未找到用户，则抛出 ResponseStatusException 404 */ @GetMapping("/{id}") 公共 ResponseEntity getUserById(@PathVariable Long id) ## 限制和警告 ### 1\.切勿直接暴露实体使用 DTO 将 API 契约与域模型分开。这可以防止内部数据结构的意外暴露，并允许在不更改数据库模式的情况下进行 API 演进。 ### 2\.严格遵循 REST 约定 * 使用名词作为资源名称，而不是动词 * 使用正确的HTTP方法进行操作 * 使用复数资源名称（/user，而不是/user） * 为每个操作返回适当的HTTP状态代码 ### 3\.处理全局所有异常使用 @RestControllerAdvice 一致地捕获所有异常。不要让原始异常出现给客户。 ### 4\.始终对大型结果集进行分页对于可能返回许多结果的 GET 端点，实施分页以防止性能问题和 DDoS 漏洞。 ### 5\.验证所有输入数据永远不要相信客户的输入。在所有请求 DTO 上使用 Jakarta 验证注释来验证控制器边界的数据。 ### 6\.独占使用构造函数注入避免字段注入（`@Autowired`）以获得更好的可测试性和显式依赖声明。 ### 7\.保持控制器纤薄控制器应该只处理 HTTP 请求/响应适配。将业务逻辑委托给服务层。 ### 8\. API版本控制始终从一开始就对 API 进行版本控制（例如“/v1/users”），以允许将来进行更改，而不会破坏现有客户端。 ### 9\.敏感数据保护切勿在 API 响应或日志中记录或暴露敏感数据（密码、令牌、PII）。 ## 参考文献 * 请参阅 `references/` 目录以获取全面的参考资料，包括 HTTP 状态代码、Spring 注释和详细示例 * 请参阅 `developer-kit-java:spring-boot-code-review-expert` 代理以获取代码审查指南 * 查看 `spring-boot-dependency-injection/SKILL.md` 以了解依赖注入模式 * 检查 `../spring-boot-test-patterns/SKILL.md` 以测试 REST API

Spring Boot Rest Api 标准

包含技能