api-and-interface-design

API 与接口设计

概览

设计稳定、文档完备且不容易被误用的接口。好的接口会让正确用法变得容易，让错误用法变得困难。这适用于 REST API、GraphQL schema、模块边界、组件 props，以及任何一段代码与另一段代码对话的表面。

何时使用

• 设计新的 API endpoint
• 定义模块边界或团队之间的契约
• 设计组件 prop 接口
• 制定会影响 API 形状的数据库 schema
• 修改现有公开接口

核心原则

海勒姆定律（Hyrum's Law）

With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract.

这句话的意思是：只要用户足够多，系统里每一个可观察行为，哪怕是没写进文档的怪癖、错误文案、时序和顺序，都会被某些人依赖上。一旦有人依赖，它就变成了事实契约。因此：

• 暴露什么必须是有意识的。 每一个可观察行为都可能成为长期承诺
• 不要泄露实现细节。 用户能观察到，就会依赖它
• 在设计时就考虑弃用。 如何安全移除已被依赖的东西，见 deprecation-and-migration
• 测试不够。 即使有完美的契约测试，Hyrum's Law 仍意味着“看似安全”的改动也可能打断真实用户

单版本原则（One-Version Rule）

尽量避免让消费者在同一个依赖或 API 的多个版本之间做选择。不同消费者依赖不同版本时，会形成经典的菱形依赖问题。设计时要尽量假设“同一时间只存在一个版本”，优先扩展而不是分叉。

1. 先定义契约

先定义接口，再实现它。契约本身就是 spec，实现应该跟着契约走。

// Define the contract first
interface TaskAPI {
  // Creates a task and returns the created task with server-generated fields
  createTask(input: CreateTaskInput): Promise<Task>;

  // Returns paginated tasks matching filters
  listTasks(params: ListTasksParams): Promise<PaginatedResult<Task>>;

  // Returns a single task or throws NotFoundError
  getTask(id: string): Promise<Task>;

  // Partial update — only provided fields change
  updateTask(id: string, input: UpdateTaskInput): Promise<Task>;

  // Idempotent delete — succeeds even if already deleted
  deleteTask(id: string): Promise<void>;
}

2. 错误语义保持一致

选一种错误策略，然后在所有地方都坚持使用：

// REST: HTTP status codes + structured error body
// Every error response follows the same shape
interface APIError {
  error: {
    code: string;        // Machine-readable: "VALIDATION_ERROR"
    message: string;     // Human-readable: "Email is required"
    details?: unknown;   // Additional context when helpful
  };
}

// Status code mapping
// 400 → Client sent invalid data
// 401 → Not authenticated
// 403 → Authenticated but not authorized
// 404 → Resource not found
// 409 → Conflict (duplicate, version mismatch)
// 422 → Validation failed (semantically invalid)
// 500 → Server error (never expose internal details)