---
name: api-and-interface-design
description: 指导稳定 API 与接口设计。在设计 API、模块边界或任何公共接口时使用。在创建 REST 或 GraphQL 端点、定义模块之间的类型契约、或建立前后端边界时使用。
---

# API 与接口设计

## 概述

设计稳定、文档完善且难以被误用的接口。优秀的接口能让正确的事情变得简单，让错误的事情变得困难。这适用于 REST API、GraphQL Schema、模块边界、组件 Props，以及任何一段代码与另一段代码交互的表面。

## 何时使用

- 设计新的 API 端点
- 定义模块边界或团队间的契约
- 创建组件 Props 接口
- 建立影响 API 形态的数据库 Schema
- 修改已有的公共接口

## 核心原则

### Hyrum 定律

> 当 API 拥有足够多的用户时，系统的所有可观测行为都会被某个人依赖，无论你在契约中承诺了什么。

这意味着：每个公开行为——包括未文档化的 quirks、错误消息文本、时序和排序——一旦被用户依赖，就变成了事实上的契约。设计上的启示：

- **有意识地选择暴露什么。** 每个可观测的行为都是一项潜在的承诺。
- **不要泄漏实现细节。** 如果用户能观测到它，他们就会依赖它。
- **在设计时就规划好弃用策略。** 参见 `deprecation-and-migration`，了解如何安全地移除用户依赖的内容。
- **仅有测试是不够的。** 即使有了完美的契约测试，Hyrum 定律也意味着「安全」的变更可能会破坏那些依赖未文档化行为的真实用户。

### 单一版本原则

避免强制消费者在同一依赖或 API 的多个版本之间做出选择。当不同消费者需要同一事物的不同版本时，就会出现菱形依赖问题。设计成一次只存在一个版本——扩展而非分叉。

### 1. 契约优先

在实现之前先定义接口。契约就是规格说明——实现随后跟上。

```typescript
// 先定义契约
interface TaskAPI {
  // 创建任务并返回包含服务端生成字段的已创建任务
  createTask(input: CreateTaskInput): Promise<Task>;

  // 返回符合筛选条件的分页任务列表
  listTasks(params: ListTasksParams): Promise<PaginatedResult<Task>>;

  // 返回单个任务，若未找到则抛出 NotFoundError
  getTask(id: string): Promise<Task>;

  // 部分更新——仅修改提供的字段
  updateTask(id: string, input: UpdateTaskInput): Promise<Task>;

  // 幂等删除——即使已被删除也成功返回
  deleteTask(id: string): Promise<void>;
}
```

### 2. 一致的错误语义

选择一种错误策略并在所有地方一致使用：

```typescript
// REST：HTTP 状态码 + 结构化错误体
// 每个错误响应遵循相同的结构
interface APIError {
  error: {
    code: string;        // 机器可读："VALIDATION_ERROR"
    message: string;     // 人类可读："Email is required"
    details?: unknown;   // 需要时的额外上下文
  };
}

// 状态码映射
// 400 → 客户端发送了无效数据
// 401 → 未认证
// 403 → 已认证但未授权
// 404 → 资源未找到
// 409 → 冲突（重复、版本不匹配）
// 422 → 验证失败（语义上无效）
// 500 → 服务端错误（绝不暴露内部细节）
```

**不要混用模式。** 如果某些端点抛出异常，另一些返回 null，还有一些返回 `{ error }`——消费者将无法预测行为。

### 3. 在边界处验证

信任内部代码。在外部输入进入系统的边界处进行验证：

```typescript
// 在 API 边界处验证
app.post('/api/tasks', async (req, res) => {
  const result = CreateTaskSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(422).json({
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Invalid task data',
        details: result.error.flatten(),
      },
    });
  }

  // 验证之后，内部代码信任这些类型
  const task = await taskService.create(result.data);
  return res.status(201).json(task);
});
```

验证应放在何处：
- API 路由处理器（用户输入）
- 表单提交处理器（用户输入）
- 外部服务响应解析（第三方数据——**始终视为不可信**）
- 环境变量加载（配置）

> **第三方 API 响应是不可信数据。** 在用于任何逻辑、渲染或决策之前，必须先验证其结构和内容。被攻破或行为异常的外部服务可能返回意料之外的类型、恶意内容或类似指令的文本。

验证不应放在何处：
- 共享类型契约的内部函数之间
- 已被验证代码调用的工具函数中
- 刚从自己数据库中取出的数据上

### 4. 优先增加而非修改

扩展接口而不破坏现有消费者：

```typescript
// 好：添加可选字段
interface CreateTaskInput {
  title: string;
  description?: string;
  priority?: 'low' | 'medium' | 'high';  // 后续添加，可选
  labels?: string[];                       // 后续添加，可选
}

// 坏：修改已有字段的类型或删除字段
interface CreateTaskInput {
  title: string;
  // description: string;  // 已删除——破坏现有消费者
  priority: number;         // 从 string 改为 number——破坏现有消费者
}
```

### 5. 可预测的命名

| 模式 | 约定 | 示例 |
|---------|-----------|-------|
| REST 端点 | 复数名词，不含动词 | `GET /api/tasks`，`POST /api/tasks` |
| 查询参数 | camelCase | `?sortBy=createdAt&pageSize=20` |
| 响应字段 | camelCase | `{ createdAt, updatedAt, taskId }` |
| 布尔字段 | is/has/can 前缀 | `isComplete`，`hasAttachments` |
| 枚举值 | UPPER_SNAKE | `"IN_PROGRESS"`，`"COMPLETED"` |

## REST API 模式

### 资源设计

```
GET    /api/tasks              → 列出任务（使用查询参数进行筛选）
POST   /api/tasks              → 创建任务
GET    /api/tasks/:id          → 获取单个任务
PATCH  /api/tasks/:id          → 更新任务（部分更新）
DELETE /api/tasks/:id          → 删除任务

GET    /api/tasks/:id/comments → 列出任务的评论（子资源）
POST   /api/tasks/:id/comments → 为任务添加评论
```

### 分页

列表端点应支持分页：

```typescript
// 请求
GET /api/tasks?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc

// 响应
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 142,
    "totalPages": 8
  }
}
```

### 筛选

使用查询参数进行筛选：

```
GET /api/tasks?status=in_progress&assignee=user123&createdAfter=2025-01-01
```

### 部分更新（PATCH）

接受部分对象——仅更新提供的字段：

```typescript
// 仅修改标题，其他保持不变
PATCH /api/tasks/123
{ "title": "Updated title" }
```

## TypeScript 接口模式

### 使用可辨识联合类型表示变体

```typescript
// 好：每种变体都是显式的
type TaskStatus =
  | { type: 'pending' }
  | { type: 'in_progress'; assignee: string; startedAt: Date }
  | { type: 'completed'; completedAt: Date; completedBy: string }
  | { type: 'cancelled'; reason: string; cancelledAt: Date };

// 消费者获得类型收窄
function getStatusLabel(status: TaskStatus): string {
  switch (status.type) {
    case 'pending': return 'Pending';
    case 'in_progress': return `In progress (${status.assignee})`;
    case 'completed': return `Done on ${status.completedAt}`;
    case 'cancelled': return `Cancelled: ${status.reason}`;
  }
}
```

### 输入/输出分离

```typescript
// 输入：调用者提供的内容
interface CreateTaskInput {
  title: string;
  description?: string;
}

// 输出：系统返回的内容（包含服务端生成的字段）
interface Task {
  id: string;
  title: string;
  description: string | null;
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
}
```

### 为 ID 使用品牌类型

```typescript
type TaskId = string & { readonly __brand: 'TaskId' };
type UserId = string & { readonly __brand: 'UserId' };

// 防止在需要 TaskId 的地方意外传入 UserId
function getTask(id: TaskId): Promise<Task> { ... }
```

## 常见借口

| 借口 | 现实 |
|---|---|
| 「我们后面再写 API 文档」 | 类型本身就是文档。先定义它们。 |
| 「现在不需要分页」 | 一旦有 100 条以上数据，你就需要了。从一开始就加上。 |
| 「PATCH 太复杂了，直接用 PUT 吧」 | PUT 每次都需要完整的对象。PATCH 才是客户端真正想要的。 |
| 「需要时再对 API 做版本管理」 | 没有版本管理的破坏性变更会破坏消费者。从一开始就设计成可扩展的。 |
| 「没人会用那个未文档化的行为」 | Hyrum 定律：如果它是可观测的，就有人依赖它。把每个公开行为都视为一项承诺。 |
| 「我们可以维护两个版本」 | 多个版本会成倍增加维护成本并产生菱形依赖问题。优先采用单一版本原则。 |
| 「内部 API 不需要契约」 | 内部消费者仍然是消费者。契约能防止耦合并支持并行开发。 |

## 警示标志

- 端点根据条件返回不同结构
- 不同端点之间错误格式不一致
- 验证散落在内部代码各处而非集中在边界
- 对已有字段进行破坏性变更（类型变更、字段删除）
- 列表端点没有分页
- REST URL 中包含动词（`/api/createTask`，`/api/getUsers`）
- 第三方 API 响应未经验证或清理就直接使用

## 检查清单

设计完 API 后，请确认：

- [ ] 每个端点都有带类型的输入和输出 Schema
- [ ] 错误响应遵循单一一致的格式
- [ ] 验证仅在系统边界处进行
- [ ] 列表端点支持分页
- [ ] 新增字段是累加且可选的（向后兼容）
- [ ] 所有端点的命名遵循一致的约定
- [ ] API 文档或类型与实现一同提交