mcpField
A
api-design

api-design

github.com/akillness开发52387 次安装1 天前更新
代码仓库

关于 api-design

api-design 帮助团队将集成构想和服务边界转化为可供实现的 API 契约。它引导 REST 或 GraphQL 等设计选择，并明确操作、错误、兼容性及待解决问题，供后续团队使用。

主要功能

  1. 01说明理由并选择 API 风格
  2. 02定义资源、操作与边界
  3. 03规定请求和响应行为
  4. 04明确认证、错误及兼容性预期
  5. 05生成 OpenAPI 或 GraphQL 契约

适用场景

  1. 01在实现前设计新的服务 API
  2. 02评审 API 变更对客户端的兼容性
  3. 03为 REST 服务准备 OpenAPI 大纲
  4. 04为仪表盘起草 GraphQL 模式

安装

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

$npx skills add https://github.com/akillness/jeo-skills --skill api-design

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

包含的文件

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

SKILL.toon
evals/
evals.json
references/
boundary-guide.md
contract-review-checklist.md

详细介绍

API 设计

使用此技能，将模糊的集成构想、后端功能或服务边界转化为稳定的 API 契约，供其他技能基于此开展工作。

目标不是生成精美文档，而是：

  • 为问题选择合适的 API 风格
  • 定义资源、操作、输入、输出和失败语义
  • 明确兼容性和版本控制决策
  • 生成实现、测试和文档可共用的契约工件
  • 在团队固化错误的接口之前，揭示各种权衡

处理不寻常或高风险的 API 工作前，请先阅读 references/contract-review-checklist.md 和 references/boundary-guide.md。

如果用户主要需要：

  • 参考文档、教程、示例丰富的指南或文档门户设置 → 使用 api-documentation
  • 身份验证实现或令牌／会话配置 → 使用 authentication-setup
  • 契约／集成测试策略 → 使用 backend-testing
  • 架构／索引／存储设计 → 使用 database-schema-design

适用场景

  • 设计新的 REST API、GraphQL 架构或内部服务契约
  • 重构现有 API，同时避免不必要地破坏客户端
  • 审查命名、资源边界、状态码、分页、筛选、幂等性或错误模型
  • 在开始实现前生成 OpenAPI 或 GraphQL SDL 契约
  • 评估版本控制和向后兼容性决策
  • 判断 API 应继续使用 REST、迁移到 GraphQL，还是有意同时提供两种层
  • 为后端、前端、QA 或合作伙伴团队准备可直接用于实现的契约包

不适用场景

  • 主要任务是构建交互式文档、SDK 文档、入门指南或示例门户 → 使用 api-documentation
  • 主要任务是编写服务端代码、身份验证中间件、解析器或持久化逻辑
  • 主要任务是数据库规范化、索引或存储模型优化 → 使用 database-schema-design
  • 请求主要涉及测试规划或契约测试覆盖 → 使用 backend-testing
  • 目前信息还不够明确，无法准确确定 API 形态；此时应列出待解决的问题并规划设计探索，而不是假装已经确定

说明

步骤 1：明确契约问题

在设计端点之前，先记录设计输入。

记录：

  • 调用 API 的用户或系统
  • 业务操作或要完成的任务
  • 领域实体和所有权边界
  • 影响兼容性的现有客户端或迁移
  • 敏感性／安全要求
  • 预期的规模模式：读取、写入、扇出、分页、突发流量
  • 所需的工件格式：OpenAPI、GraphQL SDL、端点表或设计备忘录

如果请求信息不充分，请在设计包中明确说明缺失的假设。

步骤 2：审慎选择接口风格

不要因为习惯而默认采用某种风格。

优先选择 REST 的情况
  • 工作流以资源为中心
  • 缓存、可预测的 URL 或简单的类 CRUD 操作很重要
  • 外部客户端需要稳定、规范的 HTTP 语义
  • 需要使用 OpenAPI 工具、模拟工具和广泛兼容的生态
优先选择 GraphQL 的情况
  • 客户端需要灵活选择字段或组合遍历图数据
  • 前端团队需要减少多个页面中的过度获取／获取不足
  • 相比固定的端点列表，架构更适合作为共享契约
  • 已有或预计会使用架构注册表／破坏性变更检查
仅在以下情况下采用混合方案
  • 各自职责明确不同
  • 团队能够说明由谁使用哪一层，以及原因
  • 能够避免所有权重复和接口漂移

说明选择该风格的原因。“因为大家都在用”并不足够。

步骤 3：对资源、操作和边界建模

对于 REST：

  • 定义顶层资源及其所有权边界
  • 使用名词，而非动词形式的端点；只有在操作端点确实更清晰时才使用
  • 除非嵌套资源具有明确的父子关系，否则保持 URL 结构扁平
  • 分别列出标准操作和领域特定操作

对于 GraphQL：

  • 定义核心类型、关系、查询和变更
  • 避免设计一个包揽所有操作的巨型变更接口
  • 说明分页、筛选和字段级授权的适用范围
  • 指出可能频繁变更的架构区域

对于任一种风格：

  • 标明同步与异步行为
  • 指明写入操作是否幂等
  • 如有相关情况，说明最终一致性或长时间运行的任务行为
步骤 4：定义请求／响应契约

设计契约，而不只是理想情况下的流程。

包括：

  • 请求结构和必填字段
  • 成功时的响应结构
  • 分页或游标规则
  • 筛选／排序语义
  • 可空性和默认值
  • 字段命名约定
  • 时间戳、ID 和枚举行为
  • 部分更新行为

如果 API 同时支持机器对机器和前端客户端，请说明响应结构或扩展模式有哪些不同。

步骤 5：设计身份验证、错误和兼容性规则

记录客户端所依赖的运行语义。

定义：

  • 契约层面的身份验证模型预期（例如：必须提供 bearer token、角色检查、租户范围限定）
  • 常见状态码／错误类别
  • 机器可读的错误代码
  • 重试／幂等性预期
  • 弃用和停止服务行为
  • 兼容性承诺：可安全增补、存在破坏性变更、受版本控制，或需要迁移

此处不要完整实现身份验证。只需定义契约；必要时将详细配置交接给 authentication-setup。

步骤 6：生成契约文档

选择足以支持后续工作的最轻量级文档。

推荐格式：

  • OpenAPI 大纲，适用于 REST 契约和注重评审的环境
  • GraphQL SDL 草案，适用于以架构为先的 GraphQL 工作
  • 端点／操作表，适用于早期架构讨论
  • 设计备忘录 + 风险清单，适用于仍在讨论合适方案的情况

最低限度的契约材料包：

  • 选择的风格及原因
  • 目标受众／使用方
  • 实体或类型映射
  • 操作以及请求／响应摘要
  • 身份验证／错误／版本控制说明
  • 未决问题／风险
  • 后续交接事项
步骤 7：检查破坏性变更和交接质量

定稿前，请检查：

  • 是否会导致现有客户端出问题？
  • 命名和语义是否一致？
  • 分页／筛选规则是否切实可实现？
  • 错误状态和身份验证失败是否描述得足够明确，便于前端／QA／文档工作？
  • 是否不小心将契约设计与教程编写或服务端实现混在了一起？

明确安排后续步骤：

  • api-documentation：编写公开文档、教程、示例并配置文档门户
  • backend-testing：规划契约测试和集成测试
  • authentication-setup：实现具体的身份验证
  • database-schema-design：存储模型需要单独设计时使用

输出格式

## API Design Packet: [Name]

### Contract framing
- Style: [REST | GraphQL | mixed-with-justification]
- Consumers: [internal services / frontend app / partners / public developers]
- Primary job: [what the API enables]

### Resource or type model
- [resource/type]: [purpose]
- [resource/type]: [purpose]

### Operations
| Operation | Purpose | Input summary | Output summary | Notes |
|-----------|---------|---------------|----------------|-------|
| [GET/POST/query/mutation] | ... | ... | ... | ... |

### Contract rules
- Auth model: [...]
- Error model: [...]
- Pagination/filtering: [...]
- Versioning / compatibility: [...]

### Risks / open questions
- [...]

### Handoffs
- Documentation: [does `api-documentation` need to turn this into published docs?]
- Testing: [does `backend-testing` need contract/integration coverage?]
- Auth / data model: [adjacent handoffs]

示例

示例 1：面向合作伙伴集成的公开 REST 契约

输入：“为电商供应商设计一个面向合作伙伴的订单状态 API。我们需要稳定的轮询机制、后续可回退到 Webhook，并谨慎处理版本控制。”

良好的响应结构：

  • 选择 REST，因为外部合作伙伴需要可预测的 HTTP 语义
  • 清晰定义 orders 和 order-events
  • 说明状态转换、分页、按更新时间筛选以及版本控制／弃用规则
  • 包含机器可读的错误代码，以及对幂等 Webhook 注册操作的预期
  • 将合作伙伴文档和示例交接给 api-documentation
示例 2：面向仪表板客户端的 GraphQL 架构

输入：“我们需要一个包含项目、部署、事件和警报的仪表板 API。界面有许多视图，而且 REST 会持续过度获取数据。”

良好响应形式：

  • 说明为何选择 GraphQL 来支持灵活的客户端读取
  • 定义核心类型以及查询／变更的边界
  • 指出分页以及字段／查询级别的授权
  • 标记可能的架构热点和需要审核的破坏性变更
  • 移交给 backend-testing 进行契约检查，并移交给 api-documentation 编写示例查询

最佳实践

  1. 将 API 契约视为产品边界，而不只是代码上的便利。
  2. 将设计决策与文档发布分开。
  3. 记录假设和未解决的问题，不要假装确定无疑。
  4. 优先采用增量演进和明确弃用，避免意外引入破坏性变更。
  5. 选择 REST 还是 GraphQL 时，清楚呈现选择依据。
  6. 使用能让下游团队采取行动的最小产物。
  7. 有意移交给相邻技能，而不是让本技能变得臃肿。

参考资料

评论

支持 Markdown