Skills Directory精选自 GitHub 的开源 Skills
中文

api-and-interface-designcommit 63128d0SKILL.md · 架构设计

API 与接口设计

设计稳定、难以误用的 API 与模块接口：契约先行、错误语义统一、在边界校验、只做增量扩展。

npx skills add addyosmani/agent-skills --skill api-and-interface-design
权限
  • read-repo
  • write-files
  • shell
  • network
兼容工具
Claude Code, Codex, Cursor, Copilot, Gemini CLI
GitHub
112.3k
来源
社区 · Addy Osmani
状态
扫描通过
许可证
MIT
分类
架构设计
代码仓库
github.com/addyosmani/agent-skills/skills/api-and-interface-design

核心规则

海勒姆定律：任何可观察的行为都会被人依赖，因此要谨慎决定暴露什么。

执行阶段

  1. 阶段 01契约先行

    实现前先定义带类型的输入输出接口，契约就是规格。

  2. 阶段 02统一错误与校验

    所有端点使用同一种错误格式，只在系统边界校验输入，第三方 API 响应一律视为不可信。

  3. 阶段 03为扩展而设计

    新增字段一律可选，不改类型、不删字段；遵循单一版本原则、一致命名，并为列表端点分页。

  4. 阶段 04落实幂等键

    幂等键取自意图而非尝试，借唯一约束原子地占用，同键不同请求体要明确报错，保留期覆盖最长重试链。

  5. 阶段 05按清单验证

    确认每个端点都有类型化的输入输出、错误格式一致、改动向后兼容，并与实现一同提交类型或文档。

权限说明（据 SKILL.md 整理）

能力是否需要说明
文件写入需要编写接口类型、模式定义、API 处理代码及随附文档。
命令执行不需要技能未要求运行命令。
网络外发不需要不访问网络。

SKILL.md 头部信息（YAML）

SKILL.md 头部信息（YAML）commit 63128d0
---
name: api-and-interface-design
description: Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
---

相关技能

规则扫描无法覆盖所有风险，安装前请阅读此技能的 SKILL.md，确认权限后再使用。
Markdown 版本 GitHub