用途:为后端 API 设计与评审提供统一约定参考,由 Agent(general-purpose) 携带后端指令调用,将模式直接应用于 API 实现与审查。
主要能力:RESTful 设计约定,资源名用复数小写 kebab-case(如 /api/v1/user-profiles),集合 GET 返回带分页数组,单资源 GET 返回对象,POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除,嵌套最多两层,过滤与排序用查询参数,版本用 URL 前缀。HTTP 状态码指南覆盖 200/201/204、400/401/403/404/409/422/429、500/503。错误响应统一为 error 对象,含 code、message、details 字段级信息与 request_id;生产环境不得暴露堆栈,登录失败统一提示“Invalid email or password”。分页支持页码式(page/limit/total/total_pages/has_next/has_prev)与游标式(cursor.next/has_more)。输入校验清单涵盖类型、长度、正则、范围、枚举,以及 SQL 注入(参数化查询/ORM)、XSS、路径穿越防护。限流按目标设定:认证端点 5 req/min 按 IP,通用 API 100 req/min 按用户令牌,文件上传 10 req/hour,公开 API 30 req/min,并返回 X-RateLimit-* 与 Retry-After 头。版本化支持 URL 前缀、Header、查询参数三种策略,并区分破坏性与非破坏性变更。
使用方式:作为参考技能在 API 实现与评审时套用上述约定;资料未提供具体安装命令或调用代码。
适用场景:后端接口设计、代码评审、错误与分页规范统一、限流与版本化规划。
限制:资料未提供 GraphQL 具体模式细节、实现语言绑定或工具集成方式;内容为约定参考,不替代具体项目规范。