claude-skills 的 API Designer 实战指南从资源建模到 OpenAPI 3.1 契约交付【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills本指南围绕开源仓库 claude-skills 中的 api-designer 技能 展开系统讲解如何使用该技能完成 REST / GraphQL API 设计、OpenAPI 3.1 规范编写、分页与版本化策略制定以及 RFC 7807 错误处理标准落地。读完本文你将掌握一套从领域分析、资源建模、端点设计、契约校验到 Mock 验证、演进规划的完整 API 设计工作流并能在 Claude Code 等 Agent 环境中按需触发该技能获得专业架构级输出。技能定位与触发场景api-designer是仓库中面向 API 架构领域的专用技能在 SKILLS_GUIDE.md 中被定位为 RESTful API design, OpenAPI, API versioning 的能力提供者。根据其 frontmatter 定义它的角色role是架构师architect、职责范围scope是设计design、输出格式output-format是规范specification。该技能在以下场景下应被触发设计 REST 或 GraphQL API创建 OpenAPI 规范规划 API 架构进行资源建模resource modeling制定版本化策略设计分页模式建立错误处理标准。在仓库的实际使用中api-designer与graphql-architect、fastapi-expert、nestjs-expert、spring-boot-engineer、security-reviewer互为关联技能见 related-skills并与mcp-developer、atlassian-mcp、csharp-developer等技能存在交叉引用。仓库文档 discovery-for-feature-forge.md 还展示了它在功能需求发现阶段被feature-forge流程调用、用于将需求转化为 API 契约的典型应用路径。核心工作流六步完成 API 设计SKILL.md 定义了一条从需求到契约的可执行工作流推荐顺序如下Analyze domain分析领域——理解业务需求、数据模型与客户端诉求明确 API 要解决的业务问题与使用方约束Model resources建模资源——识别资源、关系与操作在编写任何规范之前先画出实体关系草图确保资源边界清晰Design endpoints设计端点——定义 URI 模式、HTTP 方法与请求/响应结构Specify contract编写契约——创建 OpenAPI 3.1 规范并在继续之前完成校验校验命令为npx redocly/cli lint openapi.yamlMock and verifyMock 验证——启动 Mock 服务器验证契约的可用性npx stoplight/prism-cli mock openapi.yamlPlan evolution规划演进——设计版本化、弃用与向后兼容策略。这条工作流强调先设计、后编码的契约优先思想资源模型是契约的骨架OpenAPI 规范是契约的载体lint 与 Mock 则是契约质量的双重保险。资源导向的 REST 设计模式REST API 围绕资源名词而非动作动词构建。详细的模式说明位于 references/rest-patterns.md。资源识别与命名推荐的资源 URIGET /users # 集合 GET /users/{id} # 单个资源 GET /users/{id}/orders # 嵌套集合 POST /users # 创建资源 PUT /users/{id} # 整体替换资源 PATCH /users/{id} # 部分更新资源 DELETE /users/{id} # 删除资源反模式 URI严禁使用POST /getUser # URI 中带动词 POST /createUser # URI 中带动词 GET /user?actiondelete # 把动作塞进查询参数命名约定方面rest-patterns.md 要求集合使用复数名词/users、/orders、/products、统一使用小写与连字符提升可读性/shipping-addresses、嵌套层级不超过 23 层/users/{id}/orders/{orderId}并使用查询参数完成过滤/users?statusactiveroleadmin。HTTP 方法与幂等性语义方法安全幂等用途GET是是检索资源POST否否创建资源、非幂等操作PUT否是整体替换资源PATCH否否部分更新DELETE否是删除资源HEAD是是仅获取元数据OPTIONS是是获取允许的方法方法的使用要点对应完整 HTTP 示例见 rest-patterns.mdGET成功返回200 OKPOST创建成功返回201 Created并携带Location: /users/124响应头指向新资源PUT整体替换成功返回200 OKPATCH部分更新成功返回200 OKDELETE成功返回204 No Content无响应体。关于幂等性rest-patterns.md 指出 PUT 天然幂等多次相同请求结果一致、DELETE 幂等首次返回 204其后返回 404但终态相同而 POST 默认非幂等需要幂等操作时通过Idempotency-Key请求头实现POST /payments Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 Content-Type: application/json { amount: 100.00, currency: USD }服务端存储幂等键对重复请求返回相同响应。HTTP 状态码语义完整状态码目录见 rest-patterns.md要点如下2xx 成功200 OKGET/PUT/PATCH、201 CreatedPOST须带 Location、202 Accepted异步处理、204 No ContentDELETE3xx 重定向301 Moved Permanently、302 Found、304 Not Modified缓存仍有效4xx 客户端错误400 Bad Request、401 Unauthorized认证、403 Forbidden已认证但无权限、404 Not Found、405 Method Not Allowed、409 Conflict与当前状态冲突如重复数据、422 Unprocessable Entity语法合法但语义错误、429 Too Many Requests限流5xx 服务端错误500 Internal Server Error、502 Bad Gateway、503 Service Unavailable、504 Gateway Timeout。HATEOAS 与超媒体rest-patterns.md 建议通过超媒体链接让 API 自描述、可发现。基础形式在响应中内嵌_links{ id: 123, name: John Doe, email: johnexample.com, _links: { self: { href: /users/123 }, orders: { href: /users/123/orders }, update: { href: /users/123, method: PATCH }, delete: { href: /users/123, method: DELETE } } }若采用 HALHypertext Application Language媒体类型则用_links表达关联、_embedded表达内嵌资源并通过Accept: application/haljson/Content-Type: application/haljson进行内容协商见 rest-patterns.md。缓存、条件请求与查询参数rest-patterns.md 还覆盖了缓存控制与条件请求通过Cache-Control、ETag、Last-Modified头组合实现缓存用If-None-Match发起条件 GET命中返回 304用If-Match在 PUT 时做乐观并发控制ETag 不匹配返回 412 Precondition Failed。查询参数方面支持四种能力过滤?statusactiveroleadmin、?price_min100price_max500、排序?sortcreated_at、?sort-created_at降序、?sortname,created_at多字段、字段选择?fieldsid,name,email与?excludepassword,...与搜索?qjohn。REST 最佳实践清单用名词而非动词——资源是名词方法是动词集合用复数——用/users而非/user命名一致——选择 snake_case 或 camelCase 后全局统一使用恰当的状态码响应中携带分页、过滤、排序元数据从第一天起就规划版本化完整文档化——OpenAPI 规范、示例、错误码安全默认——HTTPS、认证、限流支持过滤——让客户端只取所需实现 HATEOAS——让 API 自文档化、可发现。分页模式为所有集合端点建立统一策略SKILL.md 要求所有集合端点必须实现分页且每个集合响应都要包含分页元数据。完整策略对比与示例位于 references/pagination.md。四种主流分页策略1. Offset 分页最直观适合中小数据集GET /users?offset20limit10{ data: [ {id: 21, name: User 21}, {id: 22, name: User 22} ], pagination: { offset: 20, limit: 10, total: 150, has_more: true }, links: { first: /users?offset0limit10, prev: /users?offset10limit10, next: /users?offset30limit10, last: /users?offset140limit10 } }优点是实现简单、支持随机跳页、可返回总数缺点是深偏移下数据库扫描行多、数据变化时结果不一致、COUNT 查询昂贵。适用于数据规模小、变化不频繁、需要随机翻页的场景。2. Page 分页offset 的简化形式GET /users?page3per_page10计算方式为offset (page - 1) * per_page、total_pages ceil(total_count / per_page)。适合 Web 应用 UI。3. Cursor 分页不透明游标适合大数据量与实时流GET /users?cursoreyJpZCI6MTIzfQlimit10{ data: [ {id: 21, name: User 21}, {id: 22, name: User 22} ], pagination: { next_cursor: eyJpZCI6MzB9, prev_cursor: eyJpZCI6MjB9, has_more: true } }游标为 base64 编码的不透明指针内部结构如{id: 30, sort: created_at}实现上利用排序键做 SQL 过滤如WHERE created_at ... ORDER BY created_at DESC LIMIT 10。优点是结果一致不重不漏、大数据量下高效、无昂贵 COUNT、适合无限滚动与实时数据缺点是无法随机跳页、不返回总数。4. Keyset 分页可见键分页GET /users?after_id20limit10实现为WHERE id 20 ORDER BY id ASC LIMIT 10。利用索引、游标人类可读、结果一致但要求排序字段有索引、无法随机访问、多字段排序较复杂。其特化形态为时间驱动的 Seek 分页/events?since...until...limit100适合日志、事件流、分析等时序数据。默认值与边界处理SKILL.md 的 OpenAPI 模板将limit默认值设为 20、上限 100。references 进一步建议合理默认 2050强制上限1001000并对非法值返回 400GET /users?limit1000 Response: 400 Bad Request { error: { code: INVALID_LIMIT, message: Limit must be between 1 and 100. Default is 20. } }分页的边界场景空结果、最后一页、越界处理方式见 pagination.md越界 offset 可以返回空数组200 has_more: false也可以对不存在的页码返回 404PAGE_NOT_FOUND。分页响应还推荐通过Link响应头RFC 5988GitHub API 风格暴露first/prev/next/last导航链接。分页与排序、过滤的组合分页必须与排序、过滤协同先过滤记录 → 统计过滤结果 → 再应用分页 → 返回子集顺序不可颠倒。游标分页时游标必须包含排序字段如{id: 123, created_at: ..., sort_fields: [created_at, id]}否则翻页会乱序。策略对比矩阵特性OffsetPageCursorKeyset性能大偏移差差优秀优秀随机访问是是否否总数是是否可选一致性差差优秀优秀复杂度简单简单中等中等实时数据差差优秀优秀数据库负载高高低低典型场景小数据集Web UI流/信息流大数据集错误处理RFC 7807 Problem Details 与错误码目录SKILL.md 强制要求设计带有可操作信息的标准错误响应RFC 7807。完整规范位于 references/error-handling.md。标准错误响应模板SKILL.md 在 OpenAPI 模板中定义了Problem模式RFC 7807并要求错误响应统一使用Content-Type: application/problemjson{ type: https://api.example.com/errors/validation-error, title: Validation Error, status: 422, detail: The email field must be a valid email address., instance: /users/req-abc123, errors: [ { field: email, message: Must be a valid email address. } ] }使用规则SKILL.md错误响应必须使用Content-Type: application/problemjsontype必须是稳定、有文档的 URI绝不能用随意字符串detail必须人类可读且可操作字段级校验失败用errors[]数组扩展。RFC 7807 的五个标准字段含义error-handling.mdtype标识错误类型的 URItitle简短人类可读摘要statusHTTP 状态码detail针对本次发生的可读说明instance指向本次具体发生的 URI。按状态码分类的错误设计error-handling.md 对八类错误逐一给出了请求-响应示例400 校验错误请求数据非法字段级明细用details[]数组给出field、code如REQUIRED、INVALID_FORMAT、OUT_OF_RANGE与constraints如{min: 18, max: 120}401 认证错误缺失/非法凭证带WWW-Authenticate头常见错误码MISSING_TOKEN、INVALID_TOKEN、EXPIRED_TOKEN、REVOKED_TOKEN403 授权错误已认证但无权限如INSUFFICIENT_PERMISSIONS可附带required_permission与your_permissions帮助定位404 资源不存在如RESOURCE_NOT_FOUND附带resource_type、resource_id409 冲突与当前状态冲突如重复创建时RESOURCE_ALREADY_EXISTS可指向existing_resource429 限流必须带Retry-After并可附带X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset头500 服务端错误只返回泛化信息 request_idtimestamp严禁暴露堆栈、数据库错误、内部路径与敏感配置503 服务不可用带Retry-After与可选的maintenance_end。错误码目录Error Code Catalog建议为整个 API 建立标准错误码目录error-handling.md{ VALIDATION_ERROR: { status: 400, description: Request validation failed, subcodes: { REQUIRED: Required field is missing, INVALID_FORMAT: Field has invalid format, OUT_OF_RANGE: Value is out of allowed range, INVALID_ENUM: Value is not in allowed set } }, AUTHENTICATION_ERROR: { status: 401, description: Authentication failed }, AUTHORIZATION_ERROR: { status: 403, description: Insufficient permissions }, RESOURCE_NOT_FOUND: { status: 404, description: Resource not found }, CONFLICT_ERROR: { status: 409, description: Request conflicts with current state }, RATE_LIMIT_EXCEEDED: { status: 429, description: Rate limit exceeded }, INTERNAL_SERVER_ERROR: { status: 500, description: Internal server error } }请求 ID、重试指引与多语言请求 ID 追踪所有响应携带X-Request-ID头错误体中也回显request_id便于支持工单追踪error-handling.md重试指引可重试的错误为 408/429带 Retry-After/500有时/502/503/504不可重试的为 400/401/403/404/409/422。可在错误体中返回retry: {retryable: true, retry_after: 60, max_retries: 3, backoff: exponential}多语言配合Accept-Language返回本地化message但必须始终保留code以便客户端自行翻译。错误处理的最佳实践与反模式最佳实践使用标准状态码不用 200 承载错误、机器可读错误码 人类可读消息、具体但不泄露敏感信息、包含 request_id、文档化每个端点的全部错误、跨端点格式一致、指明是否可重试、尽早校验、服务端记录日志。反模式泛化错误消息Error occurred、暴露堆栈、各端点错误结构不一致、只有人类可读消息而无错误码、用 200 包错误、无 request_id、错误未文档化、暴露内部实现细节。OpenAPI 3.1 契约从模板到校验、Mock 与代码生成可直接复制的 OpenAPI 3.1 资源端点模板SKILL.md 提供了一份完整可用的用户资源端点模板涵盖集合与单资源操作、游标分页、RFC 7807 错误响应引用与 JWT Bearer 安全方案。其结构要点顶层字段openapi: 3.1.0infotitle/versionpathscomponentssecurity集合端点/usersGET 带cursor不透明分页游标与limit默认 20、最大 100查询参数响应体required: [data, pagination]分页引用CursorPageschemanext_cursor可空、has_more布尔单资源端点/users/{id}路径参数id为format: uuid404 引用NotFound响应组件Userschemaid/created_at标记readOnly: trueemail使用format: emailProblemschemaRFC 7807 标准四字段 示例值可复用响应组件BadRequest、Unauthorized、NotFound、TooManyRequests含Retry-After响应头均以application/problemjson返回Problem安全方案BearerAuthtype: http、scheme: bearer、bearerFormat: JWT并作为全局security应用。更完整的端点设计参考references/openapi.md 提供了比模板更全面的编写指南最小规范骨架openapi: 3.1.0infoserverspathscomponents。其中info对象除 title/version 外还支持description支持 Markdown、termsOfService、contact、license及x-*扩展字段如x-api-id、x-audienceservers支持variables变量模板servers: - url: https://{environment}.example.com/v1 description: Dynamic environment variables: environment: default: api enum: [api, staging, dev]完整端点示例见 openapi.md展示了带offset/limit/status参数、security、examples、requestBody、Location响应头与204删除响应的 GET/POST/PUT/DELETE 全流程写法。安全方案Security Schemes支持三种主流认证components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT apiKey: type: apiKey in: header name: X-API-Key oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://auth.example.com/oauth/authorize tokenUrl: https://auth.example.com/oauth/token scopes: users:read: Read user data users:write: Create and update users安全方案可全局应用顶层security或按操作覆盖paths./users.get.security支持多种认证方式并存。数据类型与校验约束OpenAPI 3.1 支持stringemail/date-time/date/uuid/uri等 format、integerint64、numberdouble、boolean、arrayminItems/maxItems/uniqueItems、objectadditionalProperties可设 false/true/类型约束与enum组合模型用oneOf恰好一个匹配、anyOf一个或多个、allOf全部匹配可实现继承校验约束包括字符串的minLength/maxLength/pattern、数字的minimum/maximum/exclusiveMinimum/multipleOf。最佳实践多用components复用 schema/response/parameter所有 schema 配真实示例每个端点、参数、响应都要文档化规范本身也要版本化用工具定期校验用$ref引用组件而非复制文档化全部错误响应为每个操作添加唯一operationId利于代码生成用tags分组明确安全方案。契约的验证、Mock 与代码生成规范校验SKILL.md 指定 Redoclyopenapi.md 补充备选# 首选Redocly CLI技能工作流内置命令 npx redocly/cli lint openapi.yaml # 备选Swagger CLI swagger-cli validate openapi.yaml # 备选Spectral高级规则 lint spectral lint openapi.yamlMock 服务SKILL.mdnpx stoplight/prism-cli mock openapi.yaml启动 Mock 后可在不实现真实后端的情况下对契约做端到端验证前端与契约测试可并行推进。代码生成openapi.md# 生成 TypeScript 客户端 openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client # 生成 Python 客户端 openapi-generator-cli generate -i openapi.yaml -g python -o ./python-client # 生成 Node.js Express 服务端桩代码 openapi-generator-cli generate -i openapi.yaml -g nodejs-express-server -o ./serverSKILL.md 的交付清单明确要求验证结果达标npx redocly/cli lint openapi.yaml通过且无错误。版本化策略从第一天开始规划演进SKILL.md 要求 API 必须带清晰的弃用策略进行版本化。完整策略对比与生命周期管理见 references/versioning.md。什么时候必须升版本破坏性变更必须新开版本删除或重命名字段、改变字段类型如 string → integer、请求新增必填字段、改变响应结构、删除端点、同一场景改变状态码、改变认证机制。非破坏性变更无需新版本新增端点、新增可选请求字段、响应新增字段客户端应忽略未知字段、修复 bug、性能优化、为既有资源新增 HTTP 方法。四种版本化策略对比策略示例优点缺点URI 版本化GET /v1/users/123最显式、易理解、路由与缓存简单、可并行运行多版本违反同资源同 URI、客户端需改码换版本、URI 泛滥Header 版本化Accept: application/vnd.myapi.v1json或API-Version: 1URI 稳定、更 RESTful不易调试、路由复杂、浏览器难测、缓存复杂查询参数版本化GET /users/123?version1实现与测试简单、URL 可见污染查询串、语义不佳、干扰其他参数内容协商Accept: application/vnd.myapijson; version1很 RESTful、URI 稳定实现复杂、对开发者不直观、难测试推荐方案versioning.md 明确推荐多数 API 使用URI 版本化因为最显式、可发现、易调试、易维护、版本隔离清晰。版本格式与生命周期仅大版本公开 API 使用v1、v2、v3而非 v1.1强制深思熟虑的破坏性变更日期版本部分 API参考 Stripe、GitHub API 的实践使用2024-01-01日期做版本时间线清晰但客户端不易理解三阶段生命周期versioning.md引入期新旧版本并行运行/v1/users仍受支持、/v2/users可用同时发布博客说明、迁移指南、破坏性变更清单与 v1 弃用时间线弃用期旧版本继续运行但标记弃用通过响应头传达GET /v1/users/123 Deprecation: true Sunset: Wed, 15 Jan 2025 00:00:00 GMT Link: /v2/users/123; relsuccessor-versionDeprecation: true表示已弃用、SunsetRFC 8594标明下线时间、Link头指向新版本下线期按公告日期下线对弃用端点返回410 Gone并附指引如错误码VERSION_SUNSET 迁移文档链接。弃用政策与迁移推荐时间线versioning.md提前至少 6 个月公告弃用 → 新旧版本并行支持 612 个月 → 明确下线日期 → 完全关停前有 30 天的 410 Gone 缓冲期。沟通渠道包括响应头、开发者邮件、博客与变更日志、控制台通知、文档更新与状态页公告。迁移策略方面需要提供迁移指南逐条列出破坏性变更与字段映射如name拆分为first_name/last_name、迁移脚本、更新后的 SDK、API diff 查看器与临时兼容层。建议通过根端点GET /返回versions字典标注各版本status、sunset_date、documentation_url和版本信息端点GET /v2/version提供版本发现能力。OpenAPI 规范如何承载多版本两种方式versioning.md每个版本一份独立完整的规范文件openapi-v1.yaml、openapi-v2.yaml、openapi-v3.yaml或在单份规范中通过servers声明多版本openapi: 3.1.0 info: title: My API version: 2.0.0 servers: - url: https://api.example.com/v1 description: Version 1 (deprecated) - url: https://api.example.com/v2 description: Version 2 (current)版本化最佳实践与反模式最佳实践从第一天就版本化用/v1而非/api只用大版本号弃用期足够长612 个月多渠道清晰沟通至少同时维护 2 个版本提供详细迁移指南内部/SDK 用语义化版本破坏性变更必须事先公告提供迁移工具监控各版本使用量。反模式不升版本就引入破坏性变更、版本过多活跃版本控制在 23 个以内、弃用期过短、没有迁移路径、突然下线、各端点版本化策略不一致、单独为某个端点升版本。设计约束MUST DO 与 MUST NOT DOSKILL.md 定义了技能执行时的硬性约束是设计产出的质量底线。MUST DO必须遵守遵循 REST 原则面向资源、正确使用 HTTP 方法命名约定一致snake_case 或 camelCase——二选一并全局贯彻提供完整的 OpenAPI 3.1 规范设计带可操作信息的标准错误响应RFC 7807所有集合端点实现分页版本化 API 并带清晰的弃用政策文档化认证与授权提供请求/响应示例。MUST NOT DO严禁违反资源 URI 中使用动词用/users/{id}不用/getUser/{id}返回不一致的响应结构跳过错误码文档化忽视 HTTP 状态码语义无版本化策略就设计 API在 API 表面暴露实现细节在没有迁移路径的情况下制造破坏性变更忽略限流考虑。交付清单一份合格 API 设计的验收标准SKILL.md 要求交付 API 设计时提供以下 8 项产物资源模型与关系图或表含 URI 与 HTTP 方法的端点规范OpenAPI 3.1 规范YAML认证与授权流程错误响应目录覆盖全部 4xx/5xx且每个都带typeURI分页与过滤模式版本化与弃用策略校验结果npx redocly/cli lint openapi.yaml通过且无错误。这 8 项清单与技能的工作流六步一一对应既可作为 Agent 自动执行的验收门禁也可以作为人工审查 API 设计的核对表。技能覆盖的领域知识还包括 REST 架构、OpenAPI 3.1、GraphQL、HTTP 语义、JSON:API、HATEOAS、OAuth 2.0、JWT、RFC 7807、版本化模式、分页策略、限流、Webhook 设计与 SDK 生成见 SKILL.md实际项目中可与此仓库的 graphql-architect、fastapi-expert、nestjs-expert、spring-boot-engineer、security-reviewer 等关联技能配合使用从契约设计一路贯通到实现与安全审查。小结api-designer技能将 API 设计沉淀为一套可重复、可校验的工程流程先做领域分析与资源建模再产出 URI 与 HTTP 方法设计以 OpenAPI 3.1 规范固化为机器可读契约经 Redocly lint 与 Prism Mock 双重验证并配套分页、错误处理与版本化的长期演进策略。无论你是在 Claude Code 中通过 Agent 触发该技能还是把文中的模板与清单作为团队 API 设计规范都可以直接从 skills/api-designer/SKILL.md 及其 references 目录 下的五份主题文档REST 模式、版本化、分页、错误处理、OpenAPI获取完整细节。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 claude-skills 的 API Designer 实战指南：从资源建模到 OpenAPI 3.1 契约交付
claude-skills 的 API Designer 实战指南从资源建模到 OpenAPI 3.1 契约交付【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills本指南围绕开源仓库 claude-skills 中的 api-designer 技能 展开系统讲解如何使用该技能完成 REST / GraphQL API 设计、OpenAPI 3.1 规范编写、分页与版本化策略制定以及 RFC 7807 错误处理标准落地。读完本文你将掌握一套从领域分析、资源建模、端点设计、契约校验到 Mock 验证、演进规划的完整 API 设计工作流并能在 Claude Code 等 Agent 环境中按需触发该技能获得专业架构级输出。技能定位与触发场景api-designer是仓库中面向 API 架构领域的专用技能在 SKILLS_GUIDE.md 中被定位为 RESTful API design, OpenAPI, API versioning 的能力提供者。根据其 frontmatter 定义它的角色role是架构师architect、职责范围scope是设计design、输出格式output-format是规范specification。该技能在以下场景下应被触发设计 REST 或 GraphQL API创建 OpenAPI 规范规划 API 架构进行资源建模resource modeling制定版本化策略设计分页模式建立错误处理标准。在仓库的实际使用中api-designer与graphql-architect、fastapi-expert、nestjs-expert、spring-boot-engineer、security-reviewer互为关联技能见 related-skills并与mcp-developer、atlassian-mcp、csharp-developer等技能存在交叉引用。仓库文档 discovery-for-feature-forge.md 还展示了它在功能需求发现阶段被feature-forge流程调用、用于将需求转化为 API 契约的典型应用路径。核心工作流六步完成 API 设计SKILL.md 定义了一条从需求到契约的可执行工作流推荐顺序如下Analyze domain分析领域——理解业务需求、数据模型与客户端诉求明确 API 要解决的业务问题与使用方约束Model resources建模资源——识别资源、关系与操作在编写任何规范之前先画出实体关系草图确保资源边界清晰Design endpoints设计端点——定义 URI 模式、HTTP 方法与请求/响应结构Specify contract编写契约——创建 OpenAPI 3.1 规范并在继续之前完成校验校验命令为npx redocly/cli lint openapi.yamlMock and verifyMock 验证——启动 Mock 服务器验证契约的可用性npx stoplight/prism-cli mock openapi.yamlPlan evolution规划演进——设计版本化、弃用与向后兼容策略。这条工作流强调先设计、后编码的契约优先思想资源模型是契约的骨架OpenAPI 规范是契约的载体lint 与 Mock 则是契约质量的双重保险。资源导向的 REST 设计模式REST API 围绕资源名词而非动作动词构建。详细的模式说明位于 references/rest-patterns.md。资源识别与命名推荐的资源 URIGET /users # 集合 GET /users/{id} # 单个资源 GET /users/{id}/orders # 嵌套集合 POST /users # 创建资源 PUT /users/{id} # 整体替换资源 PATCH /users/{id} # 部分更新资源 DELETE /users/{id} # 删除资源反模式 URI严禁使用POST /getUser # URI 中带动词 POST /createUser # URI 中带动词 GET /user?actiondelete # 把动作塞进查询参数命名约定方面rest-patterns.md 要求集合使用复数名词/users、/orders、/products、统一使用小写与连字符提升可读性/shipping-addresses、嵌套层级不超过 23 层/users/{id}/orders/{orderId}并使用查询参数完成过滤/users?statusactiveroleadmin。HTTP 方法与幂等性语义方法安全幂等用途GET是是检索资源POST否否创建资源、非幂等操作PUT否是整体替换资源PATCH否否部分更新DELETE否是删除资源HEAD是是仅获取元数据OPTIONS是是获取允许的方法方法的使用要点对应完整 HTTP 示例见 rest-patterns.mdGET成功返回200 OKPOST创建成功返回201 Created并携带Location: /users/124响应头指向新资源PUT整体替换成功返回200 OKPATCH部分更新成功返回200 OKDELETE成功返回204 No Content无响应体。关于幂等性rest-patterns.md 指出 PUT 天然幂等多次相同请求结果一致、DELETE 幂等首次返回 204其后返回 404但终态相同而 POST 默认非幂等需要幂等操作时通过Idempotency-Key请求头实现POST /payments Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 Content-Type: application/json { amount: 100.00, currency: USD }服务端存储幂等键对重复请求返回相同响应。HTTP 状态码语义完整状态码目录见 rest-patterns.md要点如下2xx 成功200 OKGET/PUT/PATCH、201 CreatedPOST须带 Location、202 Accepted异步处理、204 No ContentDELETE3xx 重定向301 Moved Permanently、302 Found、304 Not Modified缓存仍有效4xx 客户端错误400 Bad Request、401 Unauthorized认证、403 Forbidden已认证但无权限、404 Not Found、405 Method Not Allowed、409 Conflict与当前状态冲突如重复数据、422 Unprocessable Entity语法合法但语义错误、429 Too Many Requests限流5xx 服务端错误500 Internal Server Error、502 Bad Gateway、503 Service Unavailable、504 Gateway Timeout。HATEOAS 与超媒体rest-patterns.md 建议通过超媒体链接让 API 自描述、可发现。基础形式在响应中内嵌_links{ id: 123, name: John Doe, email: johnexample.com, _links: { self: { href: /users/123 }, orders: { href: /users/123/orders }, update: { href: /users/123, method: PATCH }, delete: { href: /users/123, method: DELETE } } }若采用 HALHypertext Application Language媒体类型则用_links表达关联、_embedded表达内嵌资源并通过Accept: application/haljson/Content-Type: application/haljson进行内容协商见 rest-patterns.md。缓存、条件请求与查询参数rest-patterns.md 还覆盖了缓存控制与条件请求通过Cache-Control、ETag、Last-Modified头组合实现缓存用If-None-Match发起条件 GET命中返回 304用If-Match在 PUT 时做乐观并发控制ETag 不匹配返回 412 Precondition Failed。查询参数方面支持四种能力过滤?statusactiveroleadmin、?price_min100price_max500、排序?sortcreated_at、?sort-created_at降序、?sortname,created_at多字段、字段选择?fieldsid,name,email与?excludepassword,...与搜索?qjohn。REST 最佳实践清单用名词而非动词——资源是名词方法是动词集合用复数——用/users而非/user命名一致——选择 snake_case 或 camelCase 后全局统一使用恰当的状态码响应中携带分页、过滤、排序元数据从第一天起就规划版本化完整文档化——OpenAPI 规范、示例、错误码安全默认——HTTPS、认证、限流支持过滤——让客户端只取所需实现 HATEOAS——让 API 自文档化、可发现。分页模式为所有集合端点建立统一策略SKILL.md 要求所有集合端点必须实现分页且每个集合响应都要包含分页元数据。完整策略对比与示例位于 references/pagination.md。四种主流分页策略1. Offset 分页最直观适合中小数据集GET /users?offset20limit10{ data: [ {id: 21, name: User 21}, {id: 22, name: User 22} ], pagination: { offset: 20, limit: 10, total: 150, has_more: true }, links: { first: /users?offset0limit10, prev: /users?offset10limit10, next: /users?offset30limit10, last: /users?offset140limit10 } }优点是实现简单、支持随机跳页、可返回总数缺点是深偏移下数据库扫描行多、数据变化时结果不一致、COUNT 查询昂贵。适用于数据规模小、变化不频繁、需要随机翻页的场景。2. Page 分页offset 的简化形式GET /users?page3per_page10计算方式为offset (page - 1) * per_page、total_pages ceil(total_count / per_page)。适合 Web 应用 UI。3. Cursor 分页不透明游标适合大数据量与实时流GET /users?cursoreyJpZCI6MTIzfQlimit10{ data: [ {id: 21, name: User 21}, {id: 22, name: User 22} ], pagination: { next_cursor: eyJpZCI6MzB9, prev_cursor: eyJpZCI6MjB9, has_more: true } }游标为 base64 编码的不透明指针内部结构如{id: 30, sort: created_at}实现上利用排序键做 SQL 过滤如WHERE created_at ... ORDER BY created_at DESC LIMIT 10。优点是结果一致不重不漏、大数据量下高效、无昂贵 COUNT、适合无限滚动与实时数据缺点是无法随机跳页、不返回总数。4. Keyset 分页可见键分页GET /users?after_id20limit10实现为WHERE id 20 ORDER BY id ASC LIMIT 10。利用索引、游标人类可读、结果一致但要求排序字段有索引、无法随机访问、多字段排序较复杂。其特化形态为时间驱动的 Seek 分页/events?since...until...limit100适合日志、事件流、分析等时序数据。默认值与边界处理SKILL.md 的 OpenAPI 模板将limit默认值设为 20、上限 100。references 进一步建议合理默认 2050强制上限1001000并对非法值返回 400GET /users?limit1000 Response: 400 Bad Request { error: { code: INVALID_LIMIT, message: Limit must be between 1 and 100. Default is 20. } }分页的边界场景空结果、最后一页、越界处理方式见 pagination.md越界 offset 可以返回空数组200 has_more: false也可以对不存在的页码返回 404PAGE_NOT_FOUND。分页响应还推荐通过Link响应头RFC 5988GitHub API 风格暴露first/prev/next/last导航链接。分页与排序、过滤的组合分页必须与排序、过滤协同先过滤记录 → 统计过滤结果 → 再应用分页 → 返回子集顺序不可颠倒。游标分页时游标必须包含排序字段如{id: 123, created_at: ..., sort_fields: [created_at, id]}否则翻页会乱序。策略对比矩阵特性OffsetPageCursorKeyset性能大偏移差差优秀优秀随机访问是是否否总数是是否可选一致性差差优秀优秀复杂度简单简单中等中等实时数据差差优秀优秀数据库负载高高低低典型场景小数据集Web UI流/信息流大数据集错误处理RFC 7807 Problem Details 与错误码目录SKILL.md 强制要求设计带有可操作信息的标准错误响应RFC 7807。完整规范位于 references/error-handling.md。标准错误响应模板SKILL.md 在 OpenAPI 模板中定义了Problem模式RFC 7807并要求错误响应统一使用Content-Type: application/problemjson{ type: https://api.example.com/errors/validation-error, title: Validation Error, status: 422, detail: The email field must be a valid email address., instance: /users/req-abc123, errors: [ { field: email, message: Must be a valid email address. } ] }使用规则SKILL.md错误响应必须使用Content-Type: application/problemjsontype必须是稳定、有文档的 URI绝不能用随意字符串detail必须人类可读且可操作字段级校验失败用errors[]数组扩展。RFC 7807 的五个标准字段含义error-handling.mdtype标识错误类型的 URItitle简短人类可读摘要statusHTTP 状态码detail针对本次发生的可读说明instance指向本次具体发生的 URI。按状态码分类的错误设计error-handling.md 对八类错误逐一给出了请求-响应示例400 校验错误请求数据非法字段级明细用details[]数组给出field、code如REQUIRED、INVALID_FORMAT、OUT_OF_RANGE与constraints如{min: 18, max: 120}401 认证错误缺失/非法凭证带WWW-Authenticate头常见错误码MISSING_TOKEN、INVALID_TOKEN、EXPIRED_TOKEN、REVOKED_TOKEN403 授权错误已认证但无权限如INSUFFICIENT_PERMISSIONS可附带required_permission与your_permissions帮助定位404 资源不存在如RESOURCE_NOT_FOUND附带resource_type、resource_id409 冲突与当前状态冲突如重复创建时RESOURCE_ALREADY_EXISTS可指向existing_resource429 限流必须带Retry-After并可附带X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset头500 服务端错误只返回泛化信息 request_idtimestamp严禁暴露堆栈、数据库错误、内部路径与敏感配置503 服务不可用带Retry-After与可选的maintenance_end。错误码目录Error Code Catalog建议为整个 API 建立标准错误码目录error-handling.md{ VALIDATION_ERROR: { status: 400, description: Request validation failed, subcodes: { REQUIRED: Required field is missing, INVALID_FORMAT: Field has invalid format, OUT_OF_RANGE: Value is out of allowed range, INVALID_ENUM: Value is not in allowed set } }, AUTHENTICATION_ERROR: { status: 401, description: Authentication failed }, AUTHORIZATION_ERROR: { status: 403, description: Insufficient permissions }, RESOURCE_NOT_FOUND: { status: 404, description: Resource not found }, CONFLICT_ERROR: { status: 409, description: Request conflicts with current state }, RATE_LIMIT_EXCEEDED: { status: 429, description: Rate limit exceeded }, INTERNAL_SERVER_ERROR: { status: 500, description: Internal server error } }请求 ID、重试指引与多语言请求 ID 追踪所有响应携带X-Request-ID头错误体中也回显request_id便于支持工单追踪error-handling.md重试指引可重试的错误为 408/429带 Retry-After/500有时/502/503/504不可重试的为 400/401/403/404/409/422。可在错误体中返回retry: {retryable: true, retry_after: 60, max_retries: 3, backoff: exponential}多语言配合Accept-Language返回本地化message但必须始终保留code以便客户端自行翻译。错误处理的最佳实践与反模式最佳实践使用标准状态码不用 200 承载错误、机器可读错误码 人类可读消息、具体但不泄露敏感信息、包含 request_id、文档化每个端点的全部错误、跨端点格式一致、指明是否可重试、尽早校验、服务端记录日志。反模式泛化错误消息Error occurred、暴露堆栈、各端点错误结构不一致、只有人类可读消息而无错误码、用 200 包错误、无 request_id、错误未文档化、暴露内部实现细节。OpenAPI 3.1 契约从模板到校验、Mock 与代码生成可直接复制的 OpenAPI 3.1 资源端点模板SKILL.md 提供了一份完整可用的用户资源端点模板涵盖集合与单资源操作、游标分页、RFC 7807 错误响应引用与 JWT Bearer 安全方案。其结构要点顶层字段openapi: 3.1.0infotitle/versionpathscomponentssecurity集合端点/usersGET 带cursor不透明分页游标与limit默认 20、最大 100查询参数响应体required: [data, pagination]分页引用CursorPageschemanext_cursor可空、has_more布尔单资源端点/users/{id}路径参数id为format: uuid404 引用NotFound响应组件Userschemaid/created_at标记readOnly: trueemail使用format: emailProblemschemaRFC 7807 标准四字段 示例值可复用响应组件BadRequest、Unauthorized、NotFound、TooManyRequests含Retry-After响应头均以application/problemjson返回Problem安全方案BearerAuthtype: http、scheme: bearer、bearerFormat: JWT并作为全局security应用。更完整的端点设计参考references/openapi.md 提供了比模板更全面的编写指南最小规范骨架openapi: 3.1.0infoserverspathscomponents。其中info对象除 title/version 外还支持description支持 Markdown、termsOfService、contact、license及x-*扩展字段如x-api-id、x-audienceservers支持variables变量模板servers: - url: https://{environment}.example.com/v1 description: Dynamic environment variables: environment: default: api enum: [api, staging, dev]完整端点示例见 openapi.md展示了带offset/limit/status参数、security、examples、requestBody、Location响应头与204删除响应的 GET/POST/PUT/DELETE 全流程写法。安全方案Security Schemes支持三种主流认证components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT apiKey: type: apiKey in: header name: X-API-Key oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://auth.example.com/oauth/authorize tokenUrl: https://auth.example.com/oauth/token scopes: users:read: Read user data users:write: Create and update users安全方案可全局应用顶层security或按操作覆盖paths./users.get.security支持多种认证方式并存。数据类型与校验约束OpenAPI 3.1 支持stringemail/date-time/date/uuid/uri等 format、integerint64、numberdouble、boolean、arrayminItems/maxItems/uniqueItems、objectadditionalProperties可设 false/true/类型约束与enum组合模型用oneOf恰好一个匹配、anyOf一个或多个、allOf全部匹配可实现继承校验约束包括字符串的minLength/maxLength/pattern、数字的minimum/maximum/exclusiveMinimum/multipleOf。最佳实践多用components复用 schema/response/parameter所有 schema 配真实示例每个端点、参数、响应都要文档化规范本身也要版本化用工具定期校验用$ref引用组件而非复制文档化全部错误响应为每个操作添加唯一operationId利于代码生成用tags分组明确安全方案。契约的验证、Mock 与代码生成规范校验SKILL.md 指定 Redoclyopenapi.md 补充备选# 首选Redocly CLI技能工作流内置命令 npx redocly/cli lint openapi.yaml # 备选Swagger CLI swagger-cli validate openapi.yaml # 备选Spectral高级规则 lint spectral lint openapi.yamlMock 服务SKILL.mdnpx stoplight/prism-cli mock openapi.yaml启动 Mock 后可在不实现真实后端的情况下对契约做端到端验证前端与契约测试可并行推进。代码生成openapi.md# 生成 TypeScript 客户端 openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client # 生成 Python 客户端 openapi-generator-cli generate -i openapi.yaml -g python -o ./python-client # 生成 Node.js Express 服务端桩代码 openapi-generator-cli generate -i openapi.yaml -g nodejs-express-server -o ./serverSKILL.md 的交付清单明确要求验证结果达标npx redocly/cli lint openapi.yaml通过且无错误。版本化策略从第一天开始规划演进SKILL.md 要求 API 必须带清晰的弃用策略进行版本化。完整策略对比与生命周期管理见 references/versioning.md。什么时候必须升版本破坏性变更必须新开版本删除或重命名字段、改变字段类型如 string → integer、请求新增必填字段、改变响应结构、删除端点、同一场景改变状态码、改变认证机制。非破坏性变更无需新版本新增端点、新增可选请求字段、响应新增字段客户端应忽略未知字段、修复 bug、性能优化、为既有资源新增 HTTP 方法。四种版本化策略对比策略示例优点缺点URI 版本化GET /v1/users/123最显式、易理解、路由与缓存简单、可并行运行多版本违反同资源同 URI、客户端需改码换版本、URI 泛滥Header 版本化Accept: application/vnd.myapi.v1json或API-Version: 1URI 稳定、更 RESTful不易调试、路由复杂、浏览器难测、缓存复杂查询参数版本化GET /users/123?version1实现与测试简单、URL 可见污染查询串、语义不佳、干扰其他参数内容协商Accept: application/vnd.myapijson; version1很 RESTful、URI 稳定实现复杂、对开发者不直观、难测试推荐方案versioning.md 明确推荐多数 API 使用URI 版本化因为最显式、可发现、易调试、易维护、版本隔离清晰。版本格式与生命周期仅大版本公开 API 使用v1、v2、v3而非 v1.1强制深思熟虑的破坏性变更日期版本部分 API参考 Stripe、GitHub API 的实践使用2024-01-01日期做版本时间线清晰但客户端不易理解三阶段生命周期versioning.md引入期新旧版本并行运行/v1/users仍受支持、/v2/users可用同时发布博客说明、迁移指南、破坏性变更清单与 v1 弃用时间线弃用期旧版本继续运行但标记弃用通过响应头传达GET /v1/users/123 Deprecation: true Sunset: Wed, 15 Jan 2025 00:00:00 GMT Link: /v2/users/123; relsuccessor-versionDeprecation: true表示已弃用、SunsetRFC 8594标明下线时间、Link头指向新版本下线期按公告日期下线对弃用端点返回410 Gone并附指引如错误码VERSION_SUNSET 迁移文档链接。弃用政策与迁移推荐时间线versioning.md提前至少 6 个月公告弃用 → 新旧版本并行支持 612 个月 → 明确下线日期 → 完全关停前有 30 天的 410 Gone 缓冲期。沟通渠道包括响应头、开发者邮件、博客与变更日志、控制台通知、文档更新与状态页公告。迁移策略方面需要提供迁移指南逐条列出破坏性变更与字段映射如name拆分为first_name/last_name、迁移脚本、更新后的 SDK、API diff 查看器与临时兼容层。建议通过根端点GET /返回versions字典标注各版本status、sunset_date、documentation_url和版本信息端点GET /v2/version提供版本发现能力。OpenAPI 规范如何承载多版本两种方式versioning.md每个版本一份独立完整的规范文件openapi-v1.yaml、openapi-v2.yaml、openapi-v3.yaml或在单份规范中通过servers声明多版本openapi: 3.1.0 info: title: My API version: 2.0.0 servers: - url: https://api.example.com/v1 description: Version 1 (deprecated) - url: https://api.example.com/v2 description: Version 2 (current)版本化最佳实践与反模式最佳实践从第一天就版本化用/v1而非/api只用大版本号弃用期足够长612 个月多渠道清晰沟通至少同时维护 2 个版本提供详细迁移指南内部/SDK 用语义化版本破坏性变更必须事先公告提供迁移工具监控各版本使用量。反模式不升版本就引入破坏性变更、版本过多活跃版本控制在 23 个以内、弃用期过短、没有迁移路径、突然下线、各端点版本化策略不一致、单独为某个端点升版本。设计约束MUST DO 与 MUST NOT DOSKILL.md 定义了技能执行时的硬性约束是设计产出的质量底线。MUST DO必须遵守遵循 REST 原则面向资源、正确使用 HTTP 方法命名约定一致snake_case 或 camelCase——二选一并全局贯彻提供完整的 OpenAPI 3.1 规范设计带可操作信息的标准错误响应RFC 7807所有集合端点实现分页版本化 API 并带清晰的弃用政策文档化认证与授权提供请求/响应示例。MUST NOT DO严禁违反资源 URI 中使用动词用/users/{id}不用/getUser/{id}返回不一致的响应结构跳过错误码文档化忽视 HTTP 状态码语义无版本化策略就设计 API在 API 表面暴露实现细节在没有迁移路径的情况下制造破坏性变更忽略限流考虑。交付清单一份合格 API 设计的验收标准SKILL.md 要求交付 API 设计时提供以下 8 项产物资源模型与关系图或表含 URI 与 HTTP 方法的端点规范OpenAPI 3.1 规范YAML认证与授权流程错误响应目录覆盖全部 4xx/5xx且每个都带typeURI分页与过滤模式版本化与弃用策略校验结果npx redocly/cli lint openapi.yaml通过且无错误。这 8 项清单与技能的工作流六步一一对应既可作为 Agent 自动执行的验收门禁也可以作为人工审查 API 设计的核对表。技能覆盖的领域知识还包括 REST 架构、OpenAPI 3.1、GraphQL、HTTP 语义、JSON:API、HATEOAS、OAuth 2.0、JWT、RFC 7807、版本化模式、分页策略、限流、Webhook 设计与 SDK 生成见 SKILL.md实际项目中可与此仓库的 graphql-architect、fastapi-expert、nestjs-expert、spring-boot-engineer、security-reviewer 等关联技能配合使用从契约设计一路贯通到实现与安全审查。小结api-designer技能将 API 设计沉淀为一套可重复、可校验的工程流程先做领域分析与资源建模再产出 URI 与 HTTP 方法设计以 OpenAPI 3.1 规范固化为机器可读契约经 Redocly lint 与 Prism Mock 双重验证并配套分页、错误处理与版本化的长期演进策略。无论你是在 Claude Code 中通过 Agent 触发该技能还是把文中的模板与清单作为团队 API 设计规范都可以直接从 skills/api-designer/SKILL.md 及其 references 目录 下的五份主题文档REST 模式、版本化、分页、错误处理、OpenAPI获取完整细节。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考