rest-api-conventions-rrezartprebreza-spring-boot-skills

1. 基本信息

项目	内容
名称	rest-api-conventions-rrezartprebreza-spring-boot-skills
作者/维护者	rrezartprebreza（个人开发者）
来源链接	https://github.com/rrezartprebreza/spring-boot-skills/tree/main/skills/spring-boot-4/rest-api-conventions
许可证	MIT（GitHub API 获取）
GitHub Stars	196（整个 spring-boot-skills 合集仓库；该数字属整个合集，不代表本技能自身热度，GitHub API 获取）
Forks	35（同上，合集整体，GitHub API 获取）
最新版本	无独立版本号；该子目录最近一次内容提交为 2026-07-04，仓库整体最近一次修订为 2026-07-30（GitHub API 获取）
安装方式	复制该子目录到 agent 的 skills 目录（见第 10 章）

2. 功能介绍与亮点

这是一份 Spring Boot REST 接口层的“团队约定”参考，把散落在个人经验里的响应格式、状态码、URL 规范、分页与版本策略整理成一份可直接对照执行的清单。核心内容：

统一响应信封：ApiResponse<T> record 封装 success/data/error/timestamp，正常与错误响应均走同一结构，配 ApiError 错误体（code/message/details）
HTTP 状态码映射表：GET/POST/PUT/PATCH/DELETE 各自对应的成功状态码，以及校验失败、未鉴权、禁止访问、未找到、冲突、服务器错误的标准映射
URL 规范：复数名词、kebab-case、路径版本化、嵌套资源不超过两层、路径 ID 一律用 UUID 而非自增整数
Spring Boot 4 原生 API 版本路由：详解 Boot 4 / Spring Framework 7 新增的原生版本路由机制（spring.mvc.apiversion.* 配置 + @GetMapping(version = ...) 注解），明确告诫不要再手写重复的 V1/V2 控制器，并给出弃用旧版本的 Deprecation/Sunset 响应头写法
分页规范：统一分页响应结构，并特别标注“裸 Pageable 允许 ?size=100000 把整张表拉进内存”这一容易被 agent 忽略的资源耗尽风险，给出 max-page-size 配置修法
全局异常处理器：@RestControllerAdvice 统一捕获找不到、校验失败、未知异常三类场景，全部走同一响应信封

文末附 10 条“agent 常犯错误”清单，除上述分页风险外，还包括：漏加响应信封直接返回裸对象、把异常处理逻辑写在控制器里而非全局处理器、路径 ID 用 Long 而非 UUID、直接序列化 Page<Entity> 暴露 Hibernate 内部结构、手写重复版本控制器而不用 Boot 4 原生版本路由、误用 Boot 4 中改名后的依赖坐标（spring-boot-starter-webmvc）与 Jackson 3 改名后的注解（@JacksonComponent）、误以为 @SpringBootTest 仍自动装配 MockMvc。全部内容为纯 Markdown 配可编译 Java 代码示例。

3. 适用场景

所属分类：工程效率与代码质量——本技能产出的是 REST 接口代码本身的结构与写法规范，属于技术栈编码指南范畴，不涉及连接外部系统或运维基础设施。

适合任何使用 Spring Boot 4.x（或 3.x，可切换到仓库对应分支）、用 AI 编程 agent 生成或维护 REST 控制器代码的后端团队。响应格式不统一、分页无上限保护、手写重复版本控制器，都是 agent 独立生成接口代码时容易各写各的、且不会在单次代码审查中被察觉的隐性问题——直到某个客户端传入超大 size 参数拖垮内存，或者不同接口的错误结构互不一致给前端消费方增加成本。这份技能把这些约定前置到 agent 写代码之前。

4. 跨 Agent 兼容性

Claude Code：原生支持——仓库明确提供 .claude/skills/ 安装路径与徽章标注兼容
Codex：原生支持——仓库同时提供 .codex/skills/ 安装路径与徽章标注兼容
OpenClaw：未验证——SKILL.md 遵循标准 YAML front matter + Markdown 正文格式，理论上可迁移，但仓库文档未点名支持
Hermes Agent：未验证——同上，未见任何提及

5. 推荐理由

REST 接口约定是团队协作中最容易“人人心里有一套、写下来的却没有”的部分，agent 独立生成代码时更是如此——没有约定文档，同一个项目里不同接口的响应结构、错误码、分页行为都可能各不相同。这份技能把响应信封、状态码映射、URL 规范、分页边界、Spring Boot 4 原生版本路由整理成一份可直接对照执行的清单，其中“裸 Pageable 无上限可拖垮内存”与“手写重复版本控制器”两条尤其抓住了 agent 在快速生成代码时容易忽略、但在生产环境才会暴露的问题。对任何用 agent 编写 Spring Boot REST 服务的团队，这是一份可以直接落地的护栏文档。

6. 评分

维度	分数	说明
受欢迎程度	5	该技能所属子目录本身尚无独立的第三方讨论或引用证据；所属合集仓库由单一开发者维护，196 星与 35 复刻数字属整体仓库，不可归给单个子技能
可用性	9	复制单个文件夹即可安装，无需配置或付费依赖；内容随 Spring Boot 4 当前版本同步维护，仓库最近一次修订为 2026-07-30；代码示例完整可编译，覆盖信封定义到异常处理器的全套用例
安全性	9	纯 Markdown 文档配代码示例，技能自身不执行任何命令、不联网、不要求任何凭据；仓库许可证明确（MIT）；内容未见任何可疑指令或误导性说明

综合评分：7.7

7. 跟同类 Skills 相比的优势

项目	定位	与本技能的差异
spring-boot-rest-api-standards（giuseppe-trisciuoglio/developer-kit）	同为 Spring Boot REST 接口约定类技能，覆盖 URL 设计、DTO、校验、错误处理、分页、安全响应头、HATEOAS 与架构分层	覆盖面更广（含 HATEOAS 与安全响应头），但不含 Spring Boot 4 原生 API 版本路由这一较新特性的写法；本技能聚焦响应信封+分页边界+版本路由三点，配套完整可编译示例与逐条“agent 常犯错误”框架
problem-details-rfc9457-rrezartprebreza-spring-boot-skills（同一仓库）	RFC 9457 标准错误响应体（`ProblemDetail`）写法	主题互补——本技能的错误响应走自定义信封结构（`ApiError`），该技能走行业标准 `ProblemDetail` 格式，两者是同一问题的两种不同技术选型，非重复
openapi-first-rrezartprebreza-spring-boot-skills（同一仓库）	OpenAPI 优先的接口生成方式，从 spec 反向生成控制器接口与 DTO	适用前提不同——该技能假设团队已采用 OpenAPI-first 代码生成流程，本技能面向手写控制器场景，两者可配合使用但非竞争关系

8. 用户评价

该技能目前在第三方平台尚无具名用户评价。

9. 其他补充

仓库同时维护 Spring Boot 3 分支下的等价版本（响应信封与 URL 规范部分不变，仅版本路由等 Boot 4 专属特性在 Boot 3 分支被替换为等效的手写方案），供仍在 Spring Boot 3.x 的团队使用。

10. 安装使用方式

Claude Code：

mkdir -p "$PROJECT_DIR/.claude/skills"
cp -r skills/spring-boot-4/rest-api-conventions "$PROJECT_DIR/.claude/skills/"

Codex：

mkdir -p "$PROJECT_DIR/.codex/skills"
cp -r skills/spring-boot-4/rest-api-conventions "$PROJECT_DIR/.codex/skills/"

安装后无需重启 agent，下次涉及 REST 控制器、响应结构或分页代码的生成与修改时会被自动读取触发；仓库同时提供 Spring Boot 3 分支的等价目录（skills/spring-boot-3/rest-api-conventions），按项目实际框架版本二选一。

11. 注意事项

Spring Boot 4 原生 API 版本路由部分以 Spring Boot 4.0.x/4.1.x 与 Spring Framework 7 为准，Spring Boot 3.x 项目需改用仓库对应分支目录，版本路由需改回手写方案
技能给出的是响应信封与规范的模板，落地时仍需团队根据自身错误码体系与既有接口做一次性适配，不是开箱即用的最终产物
仓库由个人开发者维护，无企业组织背书，长期维护的连续性无法保证