api-and-interface-design

name	api-and-interface-design
description	Contract-first interface design. Use when designing APIs, module boundaries, or public interfaces.

API 与接口设计

Overview

接口是软件系统中最重要且最难改的契约。一旦发布，消费者就会依赖它的每一个行为——包括 bug。因此接口设计必须是 contract-first：先定义契约，再实现内部。好的接口让调用者感到"符合直觉"，让实现者感到"有改动的自由"。

When to Use

• 设计新的 REST/gRPC/GraphQL API
• 定义模块之间的公共接口或抽象层
• 设计库/包/框架的公开 API
• 定义跨服务通信协议（事件、消息、RPC）
• 设计配置接口或插件系统
• NOT for 纯内部实现细节（private 方法、模块内部函数）
• NOT for 一次性的脚本或工具

Core Process

1. 理解消费者 — 在写任何接口之前，先明确消费者是谁（前端、另一个服务、第三方开发者）以及他们需要什么
2. Contract First — 先定义接口契约（OpenAPI、Protobuf、TypeScript 类型、接口定义文件）再写实现
3. 设计语义 — 为每个操作定义清晰的语义：
   • 成功时返回什么？
   • 失败时返回什么错误？什么 HTTP 状态码？
   • 边界条件是什么？（空数组、重复提交、超大输入）
4. 遵循 Hyrum's Law — 假设你的每一个可观察行为都会被消费者依赖。所以：
   • 不要暴露内部实现细节
   • 不要让你的 API 的副作用成为契约的一部分
   • 保持向后兼容
5. One-Version Rule — 一个接口只有一个版本。如果需要破坏性变更，创建新接口而不是新版本号
6. 边界验证 — 所有输入在边界处验证一次，不允许无效数据流入内部

API 设计 Checklist

• 命名一致（动词/名词、大小写、单复数）
• 错误信息有结构（不是纯字符串）
• 幂等性：重复调用同一次操作的结果可预测
• 分页：对列表接口总是默认分页
• 速率限制：服务端应声明限制
• 弃用策略：任何字段/端点的弃用都有迁移路径

Common Rationalizations

Rationalization	Reality
"先写实现，接口后面再抽象出来"	从实现里抽接口 = 把实现细节泄露到契约里
"加个新参数，默认值不影响"	每个参数都增加复杂度，默认值只是让 bug 更隐蔽
"先发布 v1，后面再兼容"	一旦发布，改接口的成本高到几乎不可能
"这个字段反正没人用，直接改"	Hyrum's Law — 没人用是因为你还不知道谁在用
"错误返回一个字符串就够了"	字符串不可编程，消费者必须做字符串匹配来区分错误
"就一个内部接口，不用这么正式"	内部接口的变更成本 = 同一个代码库所有调用的重构成本

Red Flags

• 接口参数超过 5 个
• 接口返回类型是 any、object 或 dict
• 错误信息是字符串而不是结构化类型
• 文档中说"不要这样做"但接口允许它（设计的诱惑力 > 文档的约束力）
• 一个接口有多个职责（违反单一职责）
• 接口的响应中包含内部数据结构

Verification

• 接口定义先于实现编写
• 每个操作的输入和输出类型是精确的（非 any）
• 错误类型是结构化的（错误码 + 消息 + 详情）
• 所有边界情况（空、null、超长、大量）在接口层有定义的行为
• 接口是幂等的（或明确声明了不是）
• 没有暴露实现细节在接口中