用途：这是一份 REST API 设计原则与模式资料，适用于设计新端点、创建 DTO、规划 API 结构等场景。
主要能力： 一、URL 结构。以 /api/v1/resources 为资源根路径，列出 GET（列表）、GET /{id}（单条）、POST（创建）、PUT /{id}（替换）、PATCH /{id}（部分更新）、DELETE /{id}（删除）；嵌套资源用 GET/POST /api/v1/parents/{id}/children。 二、HTTP 状态码。200 用于成功的 GET/PUT/PATCH，201 用于创建成功，204 用于删除成功，400 校验或请求格式错误，401 认证缺失或无效，403 无权限，404 资源不存在，409 重复或状态冲突，422 语义错误，500 服务器错误。 三、请求与响应格式。集合响应包含 data 数组和 pagination（page、pageSize、totalItems、totalPages）；单资源包含 id、name、createdAt、updatedAt；错误响应包含 error.code、error.message、error.details 数组（field 与 message）。 四、查询参数。支持过滤（status、type）、排序（sort=createdAt,desc）、分页（page、pageSize）、字段选择（fields）、搜索（search）。 五、幂等性。带唯一标识的 POST 遇重复应返回已存在资源（200）；PUT/DELETE 应幂等；可用 Pair<Result, Boolean> 表示新建还是已存在。 六、版本控制。使用 URL 路径版本（/api/v1/、/api/v2/），破坏性变更时升版本，迁移期支持旧版本。 七、安全。在 API 边界校验输入，使用参数化查询（JOOQ 可处理），在服务层检查授权，不暴露内部 ID 或敏感数据，公共端点限流。
使用方式：资料以原则、路径示例、状态码表与 JSON 结构呈现，可据此设计端点与 DTO。具体安装命令、运行方式与工具集成方式暂未提供。
限制：仅提供设计约定与示例，未说明具体框架、语言运行时或强制校验机制；部分内容（如 JOOQ、Pair 模式）属于特定技术栈建议，是否适用需自行判断。