api-and-interface-design

API 与接口设计

概览

设计稳定、文档清晰且难以误用的接口。好的接口让正确的事情容易做，让错误的事情难做。这适用于 REST API、GraphQL schema、模块边界、组件 props，以及任何一段代码与另一段代码对话的表面。

何时使用

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

核心原则

Hyrum's Law

只要 API 用户足够多，系统中所有可观察行为都会被某些人依赖，无论你在契约中承诺了什么。

这意味着：每个公共行为，包括未记录的怪癖、错误消息文本、时序和排序，一旦被用户依赖，就会成为事实契约。设计含义：

• 有意识地决定暴露什么。 每个可观察行为都是潜在承诺。
• 不要泄漏实现细节。 如果用户能观察到，他们就会依赖它。
• 在设计时规划废弃。 如何安全移除用户依赖的内容，见 deprecation-and-migration。
• 测试还不够。 即使有完美的契约测试，Hyrum's Law 也意味着“安全”的改动仍会破坏依赖未记录行为的真实用户。

单版本规则

避免迫使消费者在同一个依赖或 API 的多个版本之间选择。当不同消费者需要同一事物的不同版本时，就会出现 diamond dependency 问题。为一次只存在一个版本的世界设计：扩展，而不是 fork。

1. 契约优先

先定义接口，再实现它。契约就是规格，实现随后而来。

// 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)