
> 本文是"API 设计模式"系列第 6 篇，介绍 apidesign.org 九组模式中的 **Evolution（演进）**。这是**最核心、最有分量的一组**——整本《Practical API Design》的灵魂都在这里。案例与代码为原创，思想承自 Tulach。

## 1. 实践故事：给接口加一个方法，编译崩了一片

一个平台定义了扩展点接口，供各业务方实现：

```java
public interface OrderListener {
    void onCreated(Order order);
    void onPaid(Order order);
}
```

几十个业务方各自写了实现类。半年后，平台要加"订单取消"事件，很自然地想给接口加一个方法：

```java
public interface OrderListener {
    void onCreated(Order order);
    void onPaid(Order order);
    void onCancelled(Order order);   // 新增
}
```

发布之后，**所有既有实现类全部编译失败**——它们没实现新方法。平台等于用一次"小改动"逼着几十个团队同时改代码、同时发版。这就是 Tulach 反复强调的铁律：

> **给"供别人实现的接口"（SPI）加方法，是破坏性变更。** 接口是"固定点"，一动就破。

Tulach 给的解法有好几种，最直观的两条解法是：

**方案 A：`default` 方法**（Java 8+）

```java
default void onCancelled(Order order) { /* 默认什么都不做 */ }
```

老实现不用改，新实现可选覆盖——一个方法的新增从"破坏性"变成了"兼容性"。

**方案 B：ExtendingInterfaces（新增子接口 + `instanceof`）**——在没有 `default` 的年代或需要更精细控制时：

```java
public interface OrderListener2 extends OrderListener {
    void onCancelled(Order order);
}
// 触发处：
if (listener instanceof OrderListener2 l2) l2.onCancelled(order);
```

老实现照旧工作，新实现按需升级。**核心思想都是一个：不动老契约，把新能力叠加上去。**

## 2. 这一组设计模式的意图

Evolution 组的意图，就是这一组的立身之本：

> **让一个已经发布、已被大量依赖的 API，能够在不破坏任何既有调用方/实现方的前提下，持续增加能力、修正设计、走向下一版。**

这一组回答的是 API 设计里最难的问题：**发布之后怎么办？** 一切都能设计得很美，直到它被发布出去、被十年地依赖。演进组就是"发布之后的生存指南"。

它的地基是导论里那条主线——**ClientAPI 是开放空间（只增不减），ProviderAPI/SPI 是固定点（一动就破）**。所有演进模式都是围绕这条线展开的战术。

![文05.png](https://developer.qcloudimg.com/http-save/yehe-11563618/81684cfa4cfde1500f87d5775ddd7482.png)

## 3. 这一组包含的模式（完整清单，共 34 个）

下表严格对应 wiki 分类页 `Category:APIDesignPatterns:Evolution` 列出的**全部成员页面**——这是成员最多、也最核心的一组。

| 模式（wiki 页面名） | 解决的演进难题 |
|---|---|
| **APIvsSPI** | 区分调用者 API（开放空间）与实现者 SPI（固定点），演进规则相反 |
| **Adaptable** | 设计可适配的 API，未来行为可替换 |
| **AlternativeBehavior** | 提供可替代的行为，而非只有一种写法 |
| **AssemblableTypes** | 可组装的类型，组合出未来能力 |
| **BinaryCompatibleDefaultMethods** | 用默认方法新增能力时保持二进制兼容 |
| **Case Study of Writing the Extensible Visitor Pattern** | 可扩展访问者模式的案例研究 |
| **ClarityOfTypes** | 类型清晰，减少演进时的歧义 |
| **ClearDefinitionOfVersion** | 版本定义清晰，演进有对照 |
| **ClientAPI** | 给调用者的 API = 开放空间，只增不减 |
| **ConfigurationObject** | 可生长的配置对象，加选项不破签名 |
| **Contravariance** | 参数逆变的演进手法 |
| **Covariance** | 返回类型协变的演进手法 |
| **Default Listener Methods** | 监听器默认方法，让新增回调可选 |
| **DefaultMethods** | 接口默认方法，新增方法不破坏既有实现 |
| **DesignForJDK9** | 为 JPMS 设计，利用模块边界保护演进 |
| **ExceptionExtensibility** | 异常层次可扩展，新增错误不破老 catch |
| **ExtendingInterfaces** | 新增子接口 + `instanceof`，不动老接口 |
| **Final interface** | `final` 接口作为固定点的演进约束 |
| **GradleWrapper** | 背景/相关条目（wiki 归入此类） |
| **ImplementationCompatibilityTest** | 实现兼容性测试，验证新版本仍兼容旧调用方 |
| **Incremental deployment** | 增量部署，支持逐步演进 |
| **Intelligent design** | "智能设计"：让 API 在演进中保持易用 |
| **InvisibleAbstractMethod** | 警惕凭空出现的抽象方法破坏实现方 |
| **Library** | 库的边界与演进责任 |
| **MarketingVersion** | 营销版本号 vs 内部兼容契约版本 |
| **OlderBlogPosts** | 背景/相关条目（wiki 归入此类） |
| **OrderOfElements** | 元素顺序的演进稳定性 |
| **PropertyFiles** | 用属性文件承载可演进的配置 |
| **ProviderAPI** | 给实现者的 SPI = 固定点，慎动 |
| **Proximity** | 相关元素就近，降低演进时的查找成本 |
| **RequestResponse** | 招牌模式：可生长的请求/响应对象，加字段永不改签名 |
| **Vendor library** | 供应商库的演进与依赖管理 |
| **Visitor** | 访问者模式：操作可增长 |
| **Visitor18** | 面向 Java 8+ 的访问者演进变体 |

## 4. 著名案例

- **Java 8 的 `default` 方法**：语言层为了让 `Collection` 接口能加 `stream()`、`forEach()` 而不破坏全世界的既有实现，专门引入了默认方法——这是"演进优先"影响语言设计的历史性案例。
- **`Iterable` → `Iterator` → `Stream` 的层层扩展**：JDK 集合体系用"新增接口/方法"的方式生长了二十年而基本保持兼容。
- **Servlet API 的版本演进**：靠向后兼容让十几年的 web 应用还能跑，是"发布即承诺"的工业级证明。
- **Protobuf 的字段编号与 `optional`**：字段带编号、只增不改编号、新字段可选——这是 RequestResponse"可生长对象"思想在序列化层最彻底的实现。

**Web API 语境的翻译**：这一组在 HTTP API 上有最直接、最重要的对应——
- **加字段用"新增可选字段"，永不原地改语义**（呼应导论的 `amount` 事故）；这就是 RequestResponse"可生长对象"的契约版；
- **宽容读取（Robustness Principle）**：客户端应忽略未知字段，这样服务端加字段才安全；
- **弃用要走生命周期**：`Deprecation` / `Sunset` 响应头 + 公告期 + 版本共存，而不是某天直接删；
- **版本化策略**（URI/Header/媒体类型）与 MarketingVersion 思想一致：对外的 `v1/v2` 是营销标签，真正的契约兼容由字段级规则守护。版本化本身值得单独深挖。

## 5. 实际案例详解

下面把 Stripe Java SDK 与 JDK 9+ 两个案例拆开，配代码说明它们各自对应清单里的哪些演进模式、以及"为什么这么设计就不破"。

### 5.1 Stripe Java SDK：`ExpandableField` 与可生长参数对象

**问题**：一个资源（如 `PaymentIntent`）关联另一个资源（如 `PaymentMethod`）。早期只返回对方 ID，后来平台想"支持展开成完整对象"。如果直接把字段类型从 `String` 改成 `PaymentMethod`，所有老调用方立刻编译失败——这就是 Tulach 铁律在 SDK 侧的翻版（给既有"类型"改结构 = 破坏）。

**设计**：`stripe-java` 用 `ExpandableField<T>` 把"ID"和"展开对象"两种形态统一封装，字段类型从一开始就是 `ExpandableField`，永不再改：

```java
// 稳定的"可生长"字段类型（简化示意，非 Stripe 源码）
public final class ExpandableField<T> {
    private final String id;
    private final T expanded;                 // 未展开时为 null
    public ExpandableField(String id, T expanded) { this.id = id; this.expanded = expanded; }
    public String getId() { return id; }       // 老代码永远成立
    public T getExpanded() { return expanded; } // 新能力：可能为 null，需判空
    public boolean isExpanded() { return expanded != null; }
}
```

资源类一律用 `ExpandableField` 承载关联字段：

```java
public class PaymentIntent extends ApiResource {
    private ExpandableField<PaymentMethod> paymentMethod;
    public ExpandableField<PaymentMethod> getPaymentMethod() { return paymentMethod; }
}
```

调用方视角——老代码完全不用动，新能力按需启用：

```java
// 老代码（展开能力上线前就写好的，永不改动）
String pmId = intent.getPaymentMethod().getId();

// 新能力：请求时声明展开，响应里多带一个对象，类型仍是 ExpandableField
PaymentIntent pi = PaymentIntent.retrieve(
    PaymentIntentRetrieveParams.builder().setExpand("payment_method").build());
PaymentMethod pm = pi.getPaymentMethod().getExpanded(); // 需判空，但老代码不受影响
```

**对应模式**：
- **RequestResponse（可生长对象）**：字段的*承载内容*从"只有 ID"生长到"ID 或完整对象"，但字段类型签名稳定，调用方零改动——这是"可生长对象"在 Java SDK 层的落地。
- **AssemblableTypes（可组装类型）**：`ExpandableField` 把 id + 可选对象组合成一个类型，响应可由任意一种形态组装出来。
- **ConfigurationObject（可生长配置对象）**：请求参数类（`*Params` + Builder）只增可选字段、永不改既有方法签名：

```java
PaymentIntentCreateParams params = PaymentIntentCreateParams.builder()
    .setAmount(2000L)                  // 老字段
    .setCurrency("usd")                // 老字段
    .setPaymentMethod("pm_123")        // 老字段
    .setAutomaticPaymentMethods(...)   // 新字段，可选，老调用方无需感知
    .build();
```

### 5.2 JDK 9+：模块系统（JPMS）与默认方法延续

**问题**：JDK 自己也是被亿万人依赖的"已发布 API"。它既要能内部演进（改实现、重排包），又不能破坏调用方。难点在于——很多内部类早年意外成了 public，调用方偷偷依赖了它们。

**设计一：用模块边界把实现藏起来（DesignForJDK9）**

JDK 9 引入 `module-info.java`，只有 `exports` 的包对外可见，其余一律强封装：

```java
// module-info.java（java.base 示意）
module java.base {
    exports java.util;
    exports java.util.stream;
    // 内部实现类（如 com.sun.*）不 exports
    // → 调用方无法再依赖，JDK 可自由改内部而不破外部
}
```

这呼应了 API-04「让 API 隐藏实现以便可修改」：模块边界就是一层硬性"隐藏"，把演进空间留给 JDK 自己。对应清单 **DesignForJDK9（为 JPMS 设计，利用模块边界保护演进）**。

**设计二：给既有接口加能力用 default / static（DefaultMethods）**

Java 9 起继续给标准库接口追加方法，但一律走 `default` 或 `static`，绝不新增抽象方法——这正是 Tulach 铁律"给 SPI 加方法要用 default 兜底"的官方示范：

```java
public interface Optional<T> {
    void ifPresent(Consumer<? super T> action);                 // Java 8
    // Java 9 新增：default 方法，既有实现零改动
    default void ifPresentOrElse(Consumer<? super T> action, Runnable emptyAction) {
        if (isPresent()) action.accept(get()); else emptyAction.run();
    }
    default Stream<T> stream() { return isPresent() ? Stream.of(get()) : Stream.empty(); }
}
```

`Stream` 的 `takeWhile`/`dropWhile`、`List`/`Map`/`Set` 的 `of(...)` 工厂同理——前者是 `default` 方法，后者是 `static` 方法（给接口加 `static` 方法本就不要求实现类改动）。对应清单 **DefaultMethods（默认方法）**。

**小结**：JDK 用"模块边界藏实现 + default/static 加能力"两条腿走路，既守护了 ClientAPI（调用方只依赖导出 API），又守住了 ProviderAPI/SPI（给标准库接口加方法不再破坏既有实现）。

## 6. 演进的三条铁律

1. **只增不改不删**：已发布的字段、方法、状态码语义永远不动；要变，新增。
2. **区分开放空间与固定点**：给调用者的能尽量加；给实现者的（SPI）加方法必须用 `default`/子接口兜底。
3. **断裂要有仪式**：万不得已要 breaking，就走大版本 + 弃用期 + 迁移指南 + 双版本并存，而不是"某天上线一改了之"。

**本篇要点**

- Evolution 是演进组之魂，回答"**发布之后怎么办**"。
- 记住 SPI 演进两板斧：**`default` 方法** 与 **ExtendingInterfaces（子接口 + `instanceof`）**。
- **RequestResponse（可生长对象）** 是招牌模式，直接翻译成 Web API 的"只新增可选字段"。
- 三铁律：**只增不改不删、分清开放空间/固定点、断裂要有仪式。**

---

**上一篇**：《API-04 让API隐藏实现以便可修改》
**下一篇**：《API-06 出错是可演化API契约的一部分》

**参考**：apidesign.org（Jaroslav Tulach 的 API 设计模式 wiki）


本文是"API 设计模式"系列第 6 篇，介绍 apidesign.org 九组模式中的 Evolution（演进）。这是最核心、最有分量的一组——整本《Practical API Design》的灵魂都在这里。案例与代码为原创，思想承自 Tulach。

API-05 设计可兼容可演进的API

本文是"API 设计模式"系列第 6 篇

编程语言

架构设计

后端

本文深入探讨API设计中的演进模式，重点解析如何在不破坏现有实现的前提下扩展API功能。通过Java接口演进案例，对比default方法与子接口两种解决方案，揭示SPI演进的核心原则。文章还剖析Stripe SDK和JDK9+的实际案例，总结API演进三大铁律：只增不改不删、区分开放空间与固定点、断裂要有仪式。这些模式为API长期维护提供实用指导，帮助开发者构建可持续演进的系统架构。

兼容性测试

代码解释

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

本文深入探讨API设计中的演进模式，重点解析如何在不破坏现有实现的前提下扩展API功能。通过Java接口演进案例，对比default方法与子接口两种解决方案，揭示SPI演进的核心原则。文章还剖析Stripe SDK和JDK9+的实际案例，总结API演进三大铁律：只增不改不删、区分开放空间与固定点、断裂要有仪式。这些模式...

API-05 设计可兼容可演进的API-腾讯云开发者社区-腾讯云

API-05 设计可兼容可演进的API

API-05 设计可兼容可演进的API

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐