
> 本文是"API 设计模式"系列第 4 篇，介绍 apidesign.org 九组模式中的 **Creational（创建型）**。案例与代码为原创，思想承自 Tulach。

---

## 1. 实践故事：那个再也加不了参数的构造器

一个支付 SDK，最初提供一个 `PaymentClient`，构造器很朴素：

```java
new PaymentClient(String appId, String secret)
```

后来要支持自定义超时，加了个重载：

```java
new PaymentClient(String appId, String secret, int timeoutMs)
```

再后来要支持代理、重试、自定义域名、日志开关……构造器重载爆炸成七八个，其中还出现了灾难性的一对：

```java
new PaymentClient(String appId, String secret, int timeoutMs, int retry)
new PaymentClient(String appId, String secret, int retry, int timeoutMs)  // 顺序反了！
```

两个 `int` 参数顺序不同、含义不同，编译都能过，用户神不知鬼不觉地把超时和重试传反。而且构造器是"固定点"——**已经发布的构造器签名一个都不能删**，只能眼睁睁看着它继续膨胀。

我们最终引入 Builder 收场：

```java
PaymentClient client = PaymentClient.builder()
    .appId("x").secret("y")
    .timeoutMs(3000)
    .retry(2)
    .enableLog()
    .build();
```

从此加新配置项 = 给 builder 加一个方法，**老代码零改动，参数不再靠位置、每一项自解释**。这就是创建型模式的核心价值：**把"对象怎么造"设计成一件可以长期演化的事。**

---

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

Creational 组的意图：

> **提供比"直接 `new`"更灵活、更可演化的对象构造方式——既让调用方用得舒服，又给作者留下未来增加参数、切换实现、控制实例数量的自由。**

关键洞察：**构造器是"固定点"**。一旦 `new Foo(a, b)` 发布出去，它的参数列表就锁死了。而创建型模式（尤其 Builder / Factory）的本质，是在"调用方"和"真正的构造"之间插入一层，把这层做成"开放空间"，从而恢复演化自由度。

![文03.png](https://developer.qcloudimg.com/http-save/yehe-11563618/696d6c9208caed0817f00e7ba94536db.png)

---

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

下表严格对应 wiki 分类页 `Category:APIDesignPatterns:Creational` 列出的**全部成员页面**。Builder 家族最为庞大。

| 模式（wiki 页面名） | 解决的问题 |
|---|---|
| **Builder** | 多参数、可选参数的构造；链式、自解释、可增长 |
| **BuilderWithConditionalException** | 参数组合非法时，在构建期（而非运行期）抛异常 |
| **ChameleonBuilder** | 根据前一步选择动态改变后续可调用的方法集 |
| **ConfigurationObject** | 把一堆配置收拢成一个可生长的对象 |
| **CumulativeFactory** | 分步累积配置再产出，介于 Factory 与 Builder 之间 |
| **Factory** | 隐藏具体类型、返回接口，未来可替换实现 |
| **HiddenBuilder** | 连 Builder 类都不暴露，只暴露入口，保留替换构建过程的自由 |
| **ImplementOnlyAbstractClass** | 明确"这是给你继承实现的"抽象类 |
| **ImplementOnlyInterface** | 明确"这是给你实现的"接口 |
| **Injectable Singleton** | 受控地管理唯一实例，且保持可测试、可注入 |
| **ObjectAlgebras** | 用代数方式组合地构造对象/操作 |
| **Privileged API** | 区分"普通 API"与"特权 API"，控制能力暴露 |
| **Singletonizer** | 把任意类变成受控单例的通用机制 |
| **TypedBuilder** | 用类型分步引导，强制必填项填完才能 build |
| **WhiningBuilder** | 参数组合非法时"抱怨"（尽早报错）的构建器 |

---

## 4. 著名案例

- **`StringBuilder` / `StringBuffer`**：最朴素的 Builder 直觉——分步累积，最后 `toString()` 产出。
- **Guava 的 `ImmutableList.builder()`、`CacheBuilder`**：Builder 模式在工业级库里的典范，加配置项从不破坏兼容。
- **OkHttp 的 `OkHttpClient.Builder`、`Request.Builder`**：链式构建 + 不可变产物，是现代 SDK 的标配写法。
- **`java.util.stream.Stream` 的工厂方法（`Stream.of`、`Collectors`）**：工厂隐藏具体实现类型，只暴露接口。
- **Spring 的 Bean 容器**：把"单例的创建与生命周期"从 `new` 中夺出来交给容器管理，是 Injectable Singleton 思想的大规模实践——单例但可注入、可替换、可测试。

**Web API 语境的翻译**：REST/RPC 里没有"构造器"，但"创建型"的精神依然适用——
- **创建资源用 `POST`，返回 `201 Created` + `Location`**：让服务端掌握 ID 生成与实例化过程（相当于工厂），客户端不臆造资源 ID；
- **请求体用"可生长的对象"而非位置化参数**：JSON 对象天生是"命名参数"，新增可选字段不破坏老客户端——这正是 Builder"可增长"精神在契约层的体现；
- **`ConfigurationObject` 思想**：把一堆查询参数收拢成一个结构化的过滤/配置对象，比一长串扁平 query 更可演化。

---

## 5. 来自真实 SDK 与 API 的两个 Builder 例子

> 一个来自 Stripe 的官方 Java SDK，一个来自 Amazon SP-API（spapi.vip 文档）。两者都把"对象怎么造"做成了可演化、自解释的事。

**例子一 · 对应 `Builder`（兼 `TypedBuilder`）：Stripe Java SDK 的 `PaymentIntentCreateParams.builder()`**

Stripe 的官方 Java SDK 没有给 `PaymentIntent.create(...)` 塞一长串位置参数，而是让你用 Builder 链式拼出请求参数：

```java
PaymentIntentCreateParams params = PaymentIntentCreateParams.builder()
    .setAmount(1000L)                     // 必填：金额（最小货币单位，1000 = $10.00）
    .setCurrency("usd")                   // 必填：货币
    .setDescription("Demo charge")
    .setCustomer("cus_Ji8s9aB2eX")        // 选填
    .addPaymentMethodType("card")         // 选填：集合字段用 addXxx
    .putMetadata("order_id", "ord_10293") // 选填：Map 字段用 putXxx
    .build();                             // 产出不可变的 PaymentIntentCreateParams
```

每个 `setXxx` 都返回 Builder 自身，所以能一直链下去；`build()` 产出的是**不可变**参数对象。必填项 `setAmount` / `setCurrency` 若漏设，`build()` 阶段就报错——这正是 `TypedBuilder` 想达到的"漏填即失败"。将来 Stripe 要加新字段，只需给 Builder 加一个 `setXxx`，老代码一行不用改。

**例子二 · 对应 `ConfigurationObject`（Builder 精神在 REST 契约层的体现）：Amazon SP-API 的 `createFeed` 请求体**

REST API 没有"构造器"，但 SP-API 的 `createFeed`（`POST /feeds/2020-09-04/feeds`）把"可增长、命名参数"的 Builder 精神搬到了 JSON 请求体里（来源：spapi.vip 的 Feeds API 参考）。它的请求体 `CreateFeedSpecification` 是一个命名参数的对象：

```json
{
  "feedType": "POST_PRODUCT_DATA",
  "marketplaceIds": ["ATVPDKIKX0DER"],
  "inputFeedDocumentId": "amzn1.tortuga.3.abc123",
  "feedOptions": {
    "sku": "example-sku",
    "language": "en"
  }
}
```

- 字段全靠名字引用，不靠位置——加字段不会让老客户端错位；
- `feedType` / `marketplaceIds` / `inputFeedDocumentId` 是必填，`feedOptions` 是可选；
- `feedOptions` 本身是个 `<string, string>` 的 map，调用方可以按不同 feed 类型动态塞任意键值对，顶层结构不用改。

这正是 `ConfigurationObject` 思想：把一堆配置收拢成一个可生长的对象，比一长串扁平 query 更可演化——和 Stripe 的 Builder 异曲同工，只是把"链式方法"换成了"JSON 命名字段"。

---

## 6. 选型小抄

| 场景 | 首选 |
|---|---|
| 参数多、有可选项、未来还会加 | **Builder** |
| 有必填项、想让漏填编译失败 | **TypedBuilder** |
| 想隐藏具体实现类型、未来替换实现 | **Factory** |
| 需要受控的唯一实例、又要可测试 | **Injectable Singleton（配合依赖注入）** |
| 参数只有一两个且永不增长 | 直接构造器也没错——别过度设计 |

> 最后一条很重要：创建型模式是为"会演化的构造"准备的。如果一个对象天生简单且稳定，硬套 Builder 反而是过度工程。

**本篇要点**

- 构造器是**固定点**，一旦发布就锁死；创建型模式在其上加一层"开放空间"恢复演化自由。
- **Builder 家族**是核心：链式、自解释、可增长、可分步校验。
- `StringBuilder`、OkHttp `Builder`、Guava、Spring 容器是名场面。
- Web API 里，用 `POST`/`201` 让服务端掌控创建、用可生长的 JSON 对象取代位置化参数，就是创建型精神的翻译。

---

**上一篇**：《API-02 语义清晰的API接口设计》
**下一篇**：《API-04 让API隐藏实现以便可修改》

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

本文是"API 设计模式"系列第 4 篇，介绍 apidesign.org 九组模式中的 Creational（创建型）。案例与代码为原创，思想承自 Tulach。

API-03 在API设计中为构造留后路

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

编程语言

架构设计

开发工具

本文探讨API设计中的创建型模式，重点分析Builder模式如何解决构造器参数爆炸问题。通过支付SDK案例，展示Builder如何实现链式调用、参数自解释和可扩展性。文章还介绍15种创建型模式，包括Factory、TypedBuilder等，并列举Stripe、Amazon等真实案例。创建型模式核心价值在于将对象构造设计为可长期演化的过程，适用于参数多变、需持续扩展的场景。

代码解释

容器

JSON

Java

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

本文探讨API设计中的创建型模式，重点分析Builder模式如何解决构造器参数爆炸问题。通过支付SDK案例，展示Builder如何实现链式调用、参数自解释和可扩展性。文章还介绍15种创建型模式，包括Factory、TypedBuilder等，并列举Stripe、Amazon等真实案例。创建型模式核心价值在于将对象构造设...

API-03 在API设计中为构造留后路-腾讯云开发者社区-腾讯云

API-03 在API设计中为构造留后路

API-03 在API设计中为构造留后路

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐