设计稳定、文档完善且不易被误用的接口。良好的接口使正确的做法变得容易，而错误的做法变得困难。这适用于 REST API、GraphQL 模式、模块边界、组件属性，以及任何一段代码与另一段代码交互的地方。

这意味着：每一个公共行为——包括未记录的怪癖、错误信息文本、时间安排和顺序——一旦用户依赖，它就成为一种事实上的契约。设计上的影响：

避免强迫消费者在同一依赖项或 API 的多个版本之间进行选择。当不同的消费者需要同一事物的不同版本时，会出现菱形依赖问题。设计时应考虑一个时代中同一时间只存在一个版本——扩展而不是分叉。

在实现接口之前先定义接口。契约就是规范——实现随后而来。

// 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>;
}

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

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

不要混合使用模式。 如果有些端点会抛出异常，有些返回 null，还有些返回 { error } —— 使用者无法预测行为。

信任内部代码。在系统边缘验证外部输入进入时：

// Validate at the API boundary
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(),
      },
    });
  }

  // After validation, internal code trusts the types
  const task = await taskService.create(result.data);
  return res.status(201).json(task);
});

在不破坏现有使用者的情况下扩展接口：

// Good: Add optional fields
interface CreateTaskInput {
  title: string;
  description?: string;
  priority?: 'low' | 'medium' | 'high';  // Added later, optional
  labels?: string[];                       // Added later, optional
}

// Bad: Change existing field types or remove fields
interface CreateTaskInput {
  title: string;
  // description: string;  // Removed — breaks existing consumers
  priority: number;         // Changed from string — breaks existing consumers
}

REST endpoints Plural nouns, no verbs GET /api/tasks, POST /api/tasks

Query params camelCase ?sortBy=createdAt&pageSize=20

Response fields camelCase { createdAt, updatedAt, taskId }

Boolean fields is/has/can prefix isComplete, hasAttachments

Enum values UPPER_SNAKE "IN_PROGRESS", "COMPLETED"

GET    /api/tasks              → List tasks (with query params for filtering)
POST   /api/tasks              → Create a task
GET    /api/tasks/:id          → Get a single task
PATCH  /api/tasks/:id          → Update a task (partial)
DELETE /api/tasks/:id          → Delete a task

GET    /api/tasks/:id/comments → List comments for a task (sub-resource)
POST   /api/tasks/:id/comments → Add a comment to a task

// Request
GET /api/tasks?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc

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

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

接受部分对象 — 只更新提供的内容：

// Only title changes, everything else preserved
PATCH /api/tasks/123
{ "title": "Updated title" }

// Good: Each variant is explicit
type TaskStatus =
  | { type: 'pending' }
  | { type: 'in_progress'; assignee: string; startedAt: Date }
  | { type: 'completed'; completedAt: Date; completedBy: string }
  | { type: 'cancelled'; reason: string; cancelledAt: Date };

// Consumer gets type narrowing
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}`;
  }
}

// Input: what the caller provides
interface CreateTaskInput {
  title: string;
  description?: string;
}

// Output: what the system returns (includes server-generated fields)
interface Task {
  id: string;
  title: string;
  description: string | null;
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
}

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

// Prevents accidentally passing a UserId where a TaskId is expected
function getTask(id: TaskId): Promise<Task> { ... }

"We'll document the API later" The types ARE the documentation. Define them first.

"We don't need pagination for now" You will the moment someone has 100+ items. Add it from the start.

"PATCH is complicated, let's just use PUT" PUT requires the full object every time. PATCH is what clients actually want.

"We'll version the API when we need to" Breaking changes without versioning break consumers. Design for extension from the start.

"Nobody uses that undocumented behavior" Hyrum's Law: if it's observable, somebody depends on it. Treat every public behavior as a commitment.

"We can just maintain two versions" Multiple versions multiply maintenance cost and create diamond dependency problems. Prefer the One-Version Rule.

"Internal APIs don't need contracts" Internal consumers are still consumers. Contracts prevent coupling and enable parallel work.

来源说明：本文内容整理自开源项目 agentic-awesome-skills（中文翻译版），遵循 CC BY 4.0（知识共享署名 4.0 国际）许可协议，此处作为中文资料整理分享，版权归原作者所有。

Api And Interface Design 实用指南

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.

编程语言

后端

架构设计

本文系统讲解API与接口设计核心原则，涵盖海勒姆定律、单一版本规则、契约先行等关键概念，提供REST API、TypeScript接口模式及分页、错误处理等实用模式，并附常见误区和验证清单，助你设计稳定、易用且不易被误用的接口。

TypeScript 

数据库

GraphQL

路由

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

Api And Interface Design 实用指南

Api And Interface Design 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐