
> 本文是"API 设计模式"系列的第一篇。全系列共 10 篇：本篇讲清"API 设计什么、为什么重要"，并介绍 [apidesign.org 的 APIDesignPatterns](https://wiki.apidesign.org/wiki/APIDesignPatterns) 及其九大分组；随后九篇各讲一组。
>
> 本系列的一个自我约束：**思想谱系诚实注明出处（Jaroslav Tulach 及其 wiki）。**
>
>apidesign.org 的模式主要面向"进程内 Java 库"。而本系列文章，在借鉴其思想的同时，会把它翻译到 Web API 语境，这也是文章意图所在。

---

## 1. 实践故事：那个"只加一个字段"的下午

某团队对外开放的订单查询接口，长这样：

```json
GET /orders/{id}
{ "id": "A1001", "amount": 1990, "status": "PAID" }
```

三个月后，业务要加"币种"。改动小到不能再小——加一个 `currency` 字段。负责的同学顺手把 `amount` 也"顺便优化"了一下：原来 `amount` 是"分"（1990 表示 19.90 元），大家都觉得别扭，于是改成"元"，`1990` 变成 `19.9`，并加了 `currency: "CNY"`。

```json
{ "id": "A1001", "amount": 19.9, "currency": "CNY", "status": "PAID" }
```

代码评审通过了，测试通过了（显然，这家公司没有接口兼容性测试）。上线。

当晚开始，客服工单爆了。三家接入方——一家跨境电商、一家财务对账系统、一家数据大屏——同时出问题：跨境那家把 `19.9` 当成"分"入账，用户被扣了两百倍的钱去对账；财务系统的金额字段是整型，`19.9` 直接被截断成 `19`；数据大屏干脆把当日 GMV 画成了平时的百分之一。

这个下午值多少钱？直接赔付 + 对账人力 + 三家客户的信任，粗算六位数。

此例：只改了一个字段的**含义**，没改它的名字、没改它的类型签名、编译毫无问题——但**违背了已发布API的功能承诺**。

而它本可以被一条规则挡住：**已发布字段的语义不可变；要变，就新增，不要原地改。** 这条规则，正是本系列要系统讲的一整套"API 设计模式"里最基础的一条。

记住这句话：

> **API 一旦发布，就不再属于你。它属于所有依赖它的人。**

---

## 2. API 设计在设计什么

很多人以为"API 设计"就是"起接口名、定 JSON 字段"。那只是最表层。API 设计真正在设计的是**一份跨越时间与团队边界的契约**，它至少包含四层内容：

| 层次 | 设计的是什么 | 上面故事里对应的翻车点 |
|---|---|---|
| **语法层** | 端点、方法、参数、字段名、类型、状态码 | 字段类型 int→float |
| **语义层** | 每个字段/操作到底"是什么意思"（单位、时区、幂等性、错误含义） | `amount` 从"分"变"元" |
| **契约层** | 调用方能依赖什么、不能依赖什么；什么算破坏性变更 | 原地改语义 = 破坏契约 |
| **演进层** | 下一版怎么加功能而不伤到老客户；怎么优雅地废弃旧功能 | 没有"只增不改"的纪律 |

普通的功能代码，写完自己用，随时能改。API 不同：**你写下的每一行，都可能被你永远见不到的人依赖十年。** 

所以 API 设计的核心命题不是"怎么让它现在能用"，而是——

> **怎么让它在被无数人依赖之后，还能继续演化。**

这也是 Tulach 反复强调的**"演进优先"（evolution-first）**：好的 API 不是"设计得最漂亮的"，而是"最能在不破坏别人的前提下长期生长的"。

---

## 3. 为什么 API 设计如此重要

- **API错误是"复利"的。** 普通 bug 改了就没了；API 的错误一旦发布，每多一个接入方，回收成本就翻一倍。上面故事里，如果只有一个客户端，改回去很容易；有三个外部依赖，就成了公关事故。
- **API是团队与团队之间的"法律"。** 微服务、开放平台、SDK、前后端分离——今天的软件几乎全靠 API 拼装。API 是团队之间唯一的接触面，写得含糊，协作成本就无限上升。
- **API决定产品的"可扩展性"。** 一个留了扩展余地的 API，新需求来了能平滑加上去；一个写死的 API，每次改动都是一次"破坏性发布"，客户苦不堪言，你也不敢动。
- **API是信任资产。** 稳定、可预期的 API 会积累开发者信任（想想那些十几年不破坏兼容的老牌 API）；反复 breaking 的 API 会赶走生态。

一句话：**API 设计的水平，直接决定一个系统能不能长期、低成本地演化，以及一个平台能不能长出生态。**

![询问书籍原版及中文版全文.png](https://developer.qcloudimg.com/http-save/yehe-11563618/5e10d47d55636c40231a39a284563506.png)

---

## 4. apidesign.org 的九组设计模式

- **网站**：<https://wiki.apidesign.org/wiki/APIDesignPatterns>，一个 MediaWiki 形态的公开协作站点。
- **作者**：Jaroslav Tulach——NetBeans 的创建人与首任架构师。他设计并维护 NetBeans 的公共 API 十余年，这个 wiki 与其配套书全部来自一线实战。
- **配套书**：《Practical API Design: Confessions of a Java Framework Architect》（Apress, 2008；中译《软件框架设计的艺术》）。书是 2008 年的快照，wiki 则是持续生长的续篇。
- **核心主张**（首页原话，转述）：API 设计模式是"带有演进特化的经典设计模式"，它们的存在只为一个目的——**让共享库与框架能以兼容的方式随时间演化**。

apidesign.org 最大的价值，是把"兼容演化"这件最难、最容易被忽视的事，讲到了别处见不到的深度：二进制兼容、行为兼容、SPI 演化、`@since` 纪律……每个模式背后都是一段 NetBeans 的真实"伤疤"。

它的局限也很清楚（这正是本系列的加工空间）：所有例子都是**进程内 Java 库**，没有网络、没有 HTTP、没有契约文件（OpenAPI/IDL）；成书于 2008 年，早于 REST/gRPC/OpenAPI 的成熟。所以本系列在讲每一组模式时，都会把它翻译到 Web API 的世界。**


apidesign.org 把 76 个模式条目归入 **9 个顶层分组**。wiki 上每个分类页都明确列出了它归属的模式页面（成员列表），下表据此给出各组的真实成员数量与代表模式；**完整、准确的成员清单见各分篇的"包含的模式"一节**（以 wiki 分类页为准，不臆测）。

| # | 分组 | 一句话意图 | 真实成员数 / 代表模式 | 本系列篇目 |
|---|---|---|---|---|
| 1 | **Anti（反模式）** | 收集"别这么干"的踩坑清单，从错误反推原则 | 22 个（DeepHierarchy、MagicalStrings、Stateful、Synchronized、PullXorPush 等） | API-01 API设计的常见误区 |
| 2 | **Clarity（清晰性）** | 让 API 一眼看懂、难以误用 | 17 个（ClarityOfTypes、ClarityOfAccessModifiers、EliminateFuzzyModifiers 等） | API-02 语义清晰的API接口设计 |
| 3 | **Creational（创建型）** | 优雅、可演化地构造对象 | 15 个（Builder 家族、Factory、Singletonizer、ConfigurationObject 等） | API-03 在API设计中为构造留后路 |
| 4 | **Encapsulation（封装）** | 把实现藏好，只暴露该暴露的 | 9 个（FriendPackages、GettersAndSetters、PrivateJavascript、DesignForJDK9 等） | API-04 让API隐藏实现以便可修改 |
| 5 | **Evolution（演进）** | 发布后如何兼容地加功能——演进组之魂 | 34 个（ExtendingInterfaces、DefaultMethods、RequestResponse、MarketingVersion、ClientAPI、ProviderAPI 等） | API-05 设计可兼容可演进的API |
| 6 | **Exceptions（异常）** | 设计可演化的错误体系 | 9 个（Checked exception、ExceptionExtensibility、ExceptionVariance、TryCatchRedo 等） | API-06 出错是可演化API契约的一部分 |
| 7 | **Meta（元设计）** | API 的元方法：由什么构成、概念面与边界 | 6 个（AssemblableTypes、Conceptual surface、Copy Based Design、Injectable Singleton、MetaDesign、Teleinterface） | API-07 组装、注入、配置等API使能技术 |
| 8 | **Performance（性能）** | 让 API 的接口结构不制造运行期开销 | 3 个（CacheForModularity、CompileTimeCache、Startup） | API-08 高性能的API接口设计 |
| 9 | **Tests（测试）** | 用测试守住兼容契约 | 6 个（Never update tests、CodeCoverage、Race conditions、RandomizedTests 等） | API-09 自动测试是API兼容性的守门员 |

## 5. 一条贯穿全系列的主线

如果把九组模式压缩成一句话，那就是 Tulach 的招牌思想——**ClientAPI 与 ProviderAPI 的二分**：

- **给"调用者"的 API 是开放空间**：只能增，不能减。加接口安全，删/改即破坏。
- **给"实现者"的 API（即 SPI）是固定点**：一动就破，因为你会让所有既有实现无法工作。

几乎所有模式，都是围绕"如何在这两种约束下继续生长"展开的。本系列九篇会不断回到这条主线。

---

**下一篇**：《API-01 API设计的常见误区》。

**参考**：
- [APIDesignPatterns 首页](https://wiki.apidesign.org/wiki/APIDesignPatterns)


本文是"API 设计模式"系列的第一篇。全系列共 10 篇：本篇讲清"API 设计什么、为什么重要"，并介绍 apidesign.org 的 APIDesignPatterns 及其九大分组；随后九篇各讲一组。

API-00 API设计概述与9组模式总览

1. API 设计设计的是一份**跨时间、跨团队的契约**，其难点在语义与演进，而不在语法。
2. API 的错误是**复利**的，发布即承诺，"只加一个字段"也可能是六位数的事故。

编程语言

架构设计

后端

本文探讨API设计的重要性与演进原则，通过真实案例揭示API变更的风险，介绍apidesign.org的九大API设计模式分组。强调API作为跨团队契约的核心价值，解析如何设计稳定、可演进的接口，避免破坏性变更。适合开发者、架构师提升API设计能力，构建长期可维护的系统接口。

兼容性测试

代码解释

客服工单

JSON

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

API-00 API设计概述与9组模式总览-腾讯云开发者社区-腾讯云

API-00 API设计概述与9组模式总览

API-00 API设计概述与9组模式总览

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐