mcpField
A
api-architect

api-architect

github.com/curiositech开发257224 次安装2 天前更新
代码仓库

关于 api-architect

api-architect 是面向 API 设计者的技能，涵盖 REST、GraphQL、gRPC 和 WebSocket 架构。它侧重 API 优先的契约设计，并提供规范示例、验证脚本与常见设计问题检查。

主要功能

  1. 01设计 REST、GraphQL、gRPC 和 WebSocket API
  2. 02编写 OpenAPI、SDL 与 Protocol Buffers 规范
  3. 03规划版本、错误响应和分页
  4. 04检查安全、限流及常见反模式
  5. 05运行 API 规范验证脚本

适用场景

  1. 01为新服务起草 API 契约
  2. 02设计 GraphQL Schema 或 gRPC 服务
  3. 03审查 API 版本与错误响应策略
  4. 04验证 OpenAPI、GraphQL 或 Protocol Buffers 规范

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/curiositech/some_claude_skills --skill api-architect

安装后在 Claude Code 中输入/api-architect确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

CHANGELOG.md
.claude-plugin/
plugin.json
references/
grpc-service.proto
openapi-spec.yaml
rate-limiting.yaml
graphql-schema.graphql
api-security.yaml
scripts/
validate-api-spec.sh

详细介绍

API 架构师

专精于 REST、GraphQL、gRPC 和 WebSocket 架构的 API 设计专家。

激活条件

在以下情况下激活：“API 设计”、“REST API”、“GraphQL 模式”、“gRPC 服务”、“OpenAPI”、“Swagger”、“API 版本管理”、“端点设计”、“速率限制”、“OAuth 流程”、“API 网关”

**不适用于：**数据库模式 → data-pipeline-engineer | 前端使用 → web-design-expert | 部署 → devops-automator

快速开始

  1. 先定义 API 契约（API 优先设计）
  2. 选择范式：CRUD 适用 REST，灵活查询适用 GraphQL，内部服务适用 gRPC
  3. 编写规范：REST 使用 OpenAPI，GraphQL 使用 SDL，gRPC 使用 .proto
  4. 设计错误响应，确保结构一致
  5. 在首次发布前规划版本管理

核心能力

领域技术
RESTOpenAPI 3.1、HATEOAS、分页
GraphQLSDL、Relay、DataLoader、Federation
gRPCProtocol Buffers、流式传输模式
安全OAuth 2.0、JWT、API 密钥、RBAC
DXSwagger UI、SDK 生成、沙盒

架构模式

API 优先开发
Design Contract → Generate Stubs → Implement → Test Against Spec
响应封装
success: { data: <resource>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }
版本管理选项
  • URL：/v1/users（最明确）
  • Header：Accept: application/vnd.api+json;version=1
  • 查询参数：/users?version=1

参考文件

./references/ 中的完整示例：

文件说明行数
openapi-spec.yaml完整的 OpenAPI 3.1 规范162
graphql-schema.graphql使用 Relay 连接的 GraphQL111
grpc-service.protoProtocol Buffer，包含所有流式传输模式95
rate-limiting.yaml基于层级的速率限制配置85
api-security.yaml身份验证、CORS、安全标头130

反模式（请避免）

1. 使用动词的 URL

表现：/getUsers、/createOrder、/deleteProduct **修复：**使用名词（/users、/orders），由 HTTP 方法表达操作

2. 响应封装不一致

**表现：**有时使用 {data: [...]}，有时返回原始数组 **修复：**始终使用一致的封装结构

3. 不做版本管理就引入破坏性变更

**表现：**未提前告知就删除字段或更改类型 **修复：**采用语义化版本管理、弃用标头和停用期限

4. GraphQL 中的 N+1 问题

**表现：**解析器为列表中的每个项目单独查询数据库 **修复：**使用 DataLoader 模式进行批处理；对大型负载使用 @defer

5. REST 端点过度获取数据

表现：/users 返回 50 个字段，而客户端只需要 3 个 **修复：**使用稀疏字段集（?fields=id,name,email）或 GraphQL

6. 缺少分页

**表现：**列表端点返回所有记录 **修复：**设置默认上限、使用基于游标的分页，并提供 hasMore 指示器

7. 没有幂等键

**表现：**重复的 POST 请求会创建重复资源 **修复：**接受 Idempotency-Key 标头并返回缓存的响应

8. 泄露内部错误

**表现：**在 500 响应中暴露堆栈跟踪或 SQL 错误 **修复：**在生产环境使用通用错误消息，并通过请求 ID 进行调试

9. 缺少 CORS 配置

**表现：**浏览器客户端因 CORS 错误而被拦截 **修复：**明确配置允许的来源、方法和标头

10. 没有速率限制

**表现：**API 易受滥用，且无法查看使用情况 **修复：**按层级实施限制，并返回 X-RateLimit-* 标头

验证脚本

运行 ./scripts/validate-api-spec.sh 以检查：

  • OpenAPI 规范中的版本、安全方案和 operationIds
  • GraphQL 模式中的 Query 类型、分页和错误处理
  • Protocol Buffers 的语法、包和字段编号
  • 硬编码 URL、缺少版本管理等常见问题

质量检查清单

[ ] All endpoints use nouns, not verbs
[ ] Consistent response envelope structure
[ ] Error responses include codes and actionable messages
[ ] Pagination on all list endpoints
[ ] Authentication/authorization documented
[ ] Rate limit headers defined
[ ] Versioning strategy documented
[ ] CORS configured for known origins
[ ] Idempotency keys for mutating operations
[ ] OpenAPI spec validates without errors
[ ] SDK generation tested
[ ] Examples for all request/response types

输出工件

  1. OpenAPI 规范 - 完整的 API 契约
  2. GraphQL 架构 - 带连接的类型定义
  3. Protocol Buffers - gRPC 服务定义
  4. API 文档 - 开发者指南
  5. SDK 示例 - 客户端代码示例
  6. Postman 集合 - API 测试套件

可用工具

  • Read、Write、Edit - 规范文件操作
  • Bash(npm:*, npx:*) - OpenAPI 检查、代码生成
  • Bash(openapi-generator:*) - SDK 生成

评论

支持 Markdown