用途:在 Spring Boot 项目中生成或修改 REST 接口时,统一控制器、DTO、成功响应契约、分页、HTTP 状态映射与 API 版本策略,并规范 RFC 9457 异常与错误响应。
主要能力:提供成功/错误响应格式、ApiResponse 包装、状态码映射表、URL 命名与嵌套层级、原生 API 版本、分页契约与全局异常处理示例。
必要用法:先检查现有控制器、测试和 OpenAPI,保留既有 ID、响应结构与版本策略,不要顺手迁移无关端点。成功与错误格式相互独立,需保持项目已有一致的错误策略。
要点:资源用复数名词,多词用 kebab-case,版本放路径如 /api/v1/orders,嵌套最多两级。状态码:GET 200、POST 201、PUT/PATCH 200、DELETE 204(无响应体)、校验失败 400、未认证 401、禁止 403、未找到 404、冲突 409、未处理 500。版本用 Boot 4 原生配置 spring.mvc.apiversion.(WebFlux 为 spring.webflux.),通过 version 属性路由,不要复制 V1/V2 控制器。分页使用 Pageable,并设置 spring.data.web.pageable.default-page-size 与 max-page-size 限制大小,避免无界分页;PageImpl 应映射为 DTO 再包 PageResponse。
限制:技能文档提到 Boot 4 的 web starter 已更名、Jackson 3 注解更名、MockMvc 需显式 @AutoConfigureMockMvc 等迁移注意点;具体收费、平台与效果暂未提供。