api-design-framework

用途

API Design Framework 是一个用于设计健壮、可扩展且对开发者友好的 API 的技能框架。无论构建 REST、GraphQL 还是 gRPC 服务，该框架都旨在保证一致性、可用性与可维护性。

适用场景包括：

设计新的 API 端点或服务
为团队或组织建立 API 约定
审查 API 设计的一致性与最佳实践
迁移或版本化现有 API
创建 API 文档（OpenAPI、AsyncAPI）
在 REST、GraphQL 或 gRPC 之间做选择

主要能力

API 设计原则

开发者体验优先：API 应当直观且自文档化，包括清晰一致的命名约定、可预测的行为与响应、完整的文档、有帮助的错误信息。
一致性优于取巧：遵循既有模式而非另创新法，包括标准 HTTP 方法与状态码（REST）、常规查询结构（GraphQL）、符合习惯的 proto 定义（gRPC）。
无破坏性演进：从第一天起就为变更而设计，包括 API 版本化策略、向后兼容考量、弃用政策、迁移路径。
性能内建：考虑性能影响，包括大数据集的分页、过滤与部分响应、缓存策略、限流。

随附资源

assets/openapi-template.yaml：OpenAPI 3.1 规范模板
assets/asyncapi-template.yaml：AsyncAPI 规范模板
references/rest-api.md：REST API 设计模式
references/graphql-api.md：GraphQL API 设计模式
references/grpc-api.md：gRPC API 设计模式
references/frontend-integration.md：前端 API 集成模式

协议参考

REST API 设计（见 references/rest-api.md）覆盖：资源命名约定（复数名词、层级关系）、HTTP 方法（GET、POST、PUT、PATCH、DELETE）、状态码（2xx、4xx、5xx）、请求/响应格式、分页（基于游标 vs 基于偏移）、过滤、排序、字段选择、API 版本化策略、限流响应头、认证模式（Bearer、API Key）。

GraphQL API 设计（见 references/graphql-api.md）覆盖：模式设计原则（默认可空）、列表的 Connection 模式（edges、nodes、pageInfo）、变更的输入类型、查询设计模式、字段级错误处理。

gRPC API 设计（见 references/grpc-api.md）覆盖：proto 文件结构、服务与消息定义、gRPC 状态码到 HTTP 等价码的映射。

前端 API 集成（见 references/frontend-integration.md）覆盖：使用 Zod 进行运行时校验、使用 ky 的请求拦截器、错误增强模式、TanStack Query 集成。

快速参考：HTTP 状态码

200 OK：成功的 GET、PUT、PATCH
201 Created：成功的 POST
204 No Content：成功的 DELETE
400 Bad Request：无效请求
401 Unauthorized：缺少认证
403 Forbidden：无权限
404 Not Found：资源缺失
409 Conflict：重复
422 Unprocessable：校验失败
429 Too Many Requests：被限流
500 Internal Error：服务器错误

快速参考：错误响应格式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Email is already registered" }
    ],
    "request_id": "req_abc123"
  }
}

常见陷阱

URL 中出现动词：应使用 POST /users，而非 POST /createUser
命名不一致：应使用 /users、/orders，而非 /users、/userOrders
忽略 HTTP 方法：应使用 DELETE /users/123，而非 POST /users/123/delete
暴露内部实现：应使用 /users，而非 /users-table
泛化错误：应使用“Email already exists”，而非“Something went wrong”

最佳实践摘要

资源使用复数名词：/users、/orders
多词使用 kebab-case：/user-preferences
使用层级 URL：/users/123/orders
大数据集使用游标分页
公共 API 使用 URI 版本化：/api/v1/users
在响应中包含限流响应头
在前端边界使用 Zod 校验
在错误响应中包含 request_id

使用方式

该技能以参考文档与模板资源的形式提供，按需加载。使用时可查阅对应的 references 文件获取 REST、GraphQL、gRPC 或前端集成的具体模式，并可直接使用 assets 中的 OpenAPI 3.1 与 AsyncAPI 模板。

与智能体集成

backend-system-architect：使用本框架设计新 API
frontend-ui-developer：审查契约并与 API 集成
code-quality-reviewer：依据标准校验 API 设计

关键决策

分页默认：基于游标，理由是对大数据集更高效，在插入/删除下更稳定
错误格式：带 request_id 的结构化 JSON，理由是便于调试、关联与一致的客户端处理
版本化策略：URI 路径（/api/v1/），理由是最明确、适用于所有客户端、易于文档化
资源命名：复数名词、kebab-case，理由是行业标准、一致、避免动词混淆

能力细节

rest-design：关键词 rest、restful、http、endpoint、route、path、resource、CRUD；解决如何设计 RESTful API、REST 端点模式与约定、HTTP 方法与状态码、API 版本化与分页。
graphql-design：关键词 graphql、schema、query、mutation、connection、relay；解决如何设计 GraphQL API、模式设计最佳实践、分页的 Connection 模式。
grpc-design：关键词 grpc、protobuf、proto、rpc、streaming；解决如何设计 gRPC 服务、proto 文件结构、gRPC 状态码。
endpoint-design：关键词 endpoint、route、path、resource、CRUD；解决如何组织 API 端点、某资源的最佳 URL 模式、RESTful 端点命名约定。
pagination：关键词 pagination、paginate、paging、offset、cursor、limit；解决如何为端点添加分页、游标 vs 偏移分页、分页最佳实践。
versioning：关键词 version、v1、v2、api version、breaking change；解决如何版本化 API、何时创建新 API 版本、URL vs 请求头版本化。
error-handling：关键词 error、exception、status code、error response、validation error；解决如何组织错误响应、使用哪些 HTTP 状态码、错误信息最佳实践。
rate-limiting：关键词 rate limit、throttle、quota、requests per second、429；解决如何实现限流、限流响应头与响应、分层限流策略。
authentication：关键词 auth、authentication、bearer、jwt、oauth、api key；解决如何保护 API 端点、JWT vs API Key 认证、API 的 OAuth2 流程。
frontend-integration：关键词 zod、validation、fetch、ky、tanstack、react-query；解决如何以类型安全方式消费 API、API 响应的运行时校验、请求拦截器与错误处理。

版本信息

技能版本：1.2.0；最后更新：2026-01-14。

变更日志：

v1.2.0（2026-01-14）：拆分为参考文件以支持渐进式加载；新增 references/rest-api.md、references/graphql-api.md、references/grpc-api.md、references/frontend-integration.md；修复格式错误的 YAML frontmatter。
v1.1.0（2025-12-29）：新增前端 API 集成章节；新增 Zod 运行时校验模式；新增使用 ky 的请求拦截器；新增 TanStack Query 集成示例。

限制

资料未提供该技能的收费、价格、平台支持范围或具体安装命令等信息，暂未提供。

技能介绍

用途