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

---

## 1. 实践故事：一个 `getConfig()` 泄露的内部 Map

某框架有个配置类，图省事提供了：

```java
public Map<String, String> getConfig() {
    return this.config;  // 直接把内部 Map 返回出去
}
```

看起来无害。但它把**内部可变状态**整个交了出去。很快出事：

- 有用户拿到这个 Map 后直接 `config.clear()`，把框架的运行时配置清空了；
- 有用户往里 `put` 了一堆自定义键，框架下个版本想改配置的内部数据结构（从 `Map` 换成分层结构），却发现**用户已经在依赖它是个可写的 Map**，改不动了；
- 有并发场景直接 `ConcurrentModificationException`。

我们想收回这个设计，却发现——它已经 `public`，已经发布，几十个方在直接改这个 Map。**一次"图省事的暴露"，变成了永久的负债。**

正确做法是从一开始就封装：

```java
public String getConfig(String key) { return config.get(key); }
public Map<String, String> getConfigSnapshot() {
    return Collections.unmodifiableMap(new HashMap<>(config)); // 只读快照
}
```

内部用什么数据结构，是我们的自由；对外只暴露"读一个值"和"拿一份只读快照"两个**契约**。**封装的本质，是把"未来改实现的自由"留给自己，把"依赖实现细节的可能"从用户手里拿走。**

---

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

Encapsulation 组的意图：

> **在 API 与实现之间划一道清晰的墙——只暴露契约，隐藏一切实现细节，从而保住"未来自由地重写实现而不惊动任何调用方"的能力。**

这套方法有个精神内核：**你没暴露的东西，才是你能自由改的东西。** 每多暴露一个内部类型、内部字段、内部异常，你未来的演化空间就少一分。封装不是"面向对象的口号"，而是**演化自由度的储蓄账户**。

![文04.png](https://developer.qcloudimg.com/http-save/yehe-11563618/29ba397e7d7378cf81b5370013cc8181.png)

---

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

下表严格对应 wiki 分类页 `Category:APIDesignPatterns:Encapsulation` 列出的**全部成员页面**。该组的信条是 *Never expose more than you have to!*（绝不多暴露）。

| 模式（wiki 页面名） | 讲什么 |
|---|---|
| **APILessAPI** | 反例参照：暴露内部却无稳定边界，等于没封装 |
| **ConfigurationObject** | 用配置对象收口内部可变状态，只暴露稳定契约 |
| **DesignForJDK9** | 为 Java 9 模块系统（JPMS）而设计：用 `exports` 强制封装 |
| **EnforcingProperUsage** | 用类型/结构强制"只能被正确用法使用"，而非靠文档 |
| **Factory** | 隐藏具体实现类型，只返回接口 |
| **FriendPackages** | 同一模块内共享内部 API、对外部隐藏的"半公开"暴露 |
| **GettersAndSetters** | 存取器的取舍：不要机械配 get/set，暴露状态即暴露契约 |
| **LiveDB** | 与"活数据库"交互时的封装/一致性边界 |
| **PrivateJavascript** | 前端/脚本场景下用模块化、闭包隐藏内部实现 |

---

## 4. 著名案例

- **`Collections.unmodifiableList/Map`**：把可变集合包成只读视图对外暴露，是"不泄露内部可变状态"的标准工具。
- **`java.util.List` 作为接口、`ArrayList` 作为实现**：调用方依赖接口 `List`，实现方可以自由在 `ArrayList`/`LinkedList` 间切换——接口即墙。
- **JPMS（Java 9 模块系统）的 `exports`**：把"哪些包对外可见"从约定升级为语言强制，是 FriendPackages 思想的官方化——模块内可见、模块外隐藏。
- **`String` 是 `final` 的**：JDK 用 `final` 封死 `String`，既为安全，也为保留内部实现（如 Java 9 的 `byte[]` 紧凑字符串改造）的自由——正是"封装换演化自由"的经典。

**Web API 语境的翻译**：HTTP API 的封装，是**"契约与内部模型解耦"**——
- **DTO 与领域模型分离**：绝不把数据库实体（含内部字段、外键、审计列）直接序列化返回。返回的是精心裁剪的 DTO，内部表结构随便改；
- **字段最小暴露**：能不返回的内部字段就不返回，返回了就是承诺；
- **不泄露内部错误**：别把数据库栈、内部异常类名漏进响应体（既是封装也是安全）；
- **URL 里不暴露内部结构**：`/orders/{id}` 而不是 `/db/order_table/rows/{pk}`。

---

## 5. 来自真实 SDK 的两个 `ConfigurationObject` 例子

> 一个来自 Stripe 的官方 Java SDK，一个来自 Amazon SP-API（spapi.vip 文档）。两者都把"一堆会影响运行期行为的内部可变状态"收口进一个配置对象，对外只暴露稳定的构造契约——正是 `ConfigurationObject` 的本职。

**例子一 · 对应 `ConfigurationObject`：Stripe 的 `StripeClient.builder()`**

Stripe 的 `StripeClient` 不是让你到处 `set` 全局变量，而是把所有客户端配置收口进一个 Builder 式的配置对象，在 `build()` 前一次性设好：

```java
StripeClient stripeClient = new StripeClient.StripeClientBuilder()
    .setApiKey("sk_test_YourSecretKeyHere")   // 认证密钥
    .setHttpClient(customHttpClient)          // 注入带连接池的 HTTP 客户端
    .setMaxNetworkRetries(3)                  // 失败最多重试 3 次
    .setConnectTimeout(5000)                  // 连接超时 5 秒
    .setReadTimeout(30000)                    // 读取超时 30 秒
    .build();                                 // 产出不可变的 StripeClient
```

被收口进这个配置对象的"内部可变状态"包括：认证凭据、HTTP 客户端实例（内含连接池/代理/超时）、重试计数器、各类基础 URL。这些全都在 `build()` 前定死，之后拿到的 `StripeClient` 不可变、线程安全，业务代码只能调它的请求方法，改不了底层配置。调用方从没见过连接池怎么建、重试怎么计——**它们被配置对象挡在了稳定契约之后。**

**例子二 · 对应 `ConfigurationObject`：SP-API 生成 Java SDK 的凭证配置对象（来源：spapi.vip）**

SP-API 的官方 Java SDK 把连接所需的 AWS 凭证、LWA 凭证、服务端点分别收口进独立的配置对象，再用 `SellersApi.Builder()` 组装成客户端（来源：spapi.vip 的《使用生成的 Java SDK 连接到销售伙伴 API》）：

```java
AWSAuthenticationCredentials awsCreds = AWSAuthenticationCredentials.builder()
    .accessKeyId("myAccessKeyId").secretKey("mySecretId").region("us-east-1").build();

LWAAuthorizationCredentials lwaCreds = LWAAuthorizationCredentials.builder()
    .clientId("myClientId").clientSecret("myClientSecret")
    .refreshToken("Aztr|...").endpoint("https://api.amazon.com/auth/o2/token").build();

SellersApi sellersApi = new SellersApi.Builder()
    .awsAuthenticationCredentials(awsCreds)
    .lwaAuthorizationCredentials(lwaCreds)
    .awsAuthenticationCredentialsProvider(awsAuthProvider)
    .endpoint("https://sellingpartnerapi-na.amazon.com")
    .build();
```

被收口进这些配置对象的"内部可变状态"是：LWA 令牌换取（token exchange）、AWS SigV4 请求签名、令牌缓存与刷新、重试/会话管理。调用方只填不可变的凭证与端点字段，完全不接触 token 缓存、签名计算等可变状态。SDK 内部怎么换 token、怎么签名、怎么重试，都是它自己的自由——**这正是 `ConfigurationObject` 与封装的合流：配置收口，实现隐藏，契约稳定。**

---

## 6. 一个判断标准

暴露任何东西之前，问一句：

> **"如果三年后我想彻底重写这部分实现，眼前这个暴露会不会挡住我？"**

如果会，就别暴露，或者只暴露一层稳定的契约把它挡在后面。**每个 `public`、每个返回的内部对象、每个可被继承的类，都是在花掉你未来的自由。**

**本篇要点**

- 封装 = **演化自由度的储蓄**：没暴露的，才是能自由改的。
- 工具箱：**`final` 防继承、只读视图防篡改、接口做墙、友元包/模块做半公开。**
- 别机械配 getter/setter，别让 getter 有副作用，别泄露内部可变集合。
- Web API 的封装 = **DTO 与领域模型解耦 + 字段最小暴露 + 不泄露内部错误**。

---

**上一篇**：《API-03 在API设计中为构造留后路》
**下一篇**：《API-05 设计可兼容可演进的API》

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


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

API-04 让API隐藏实现以便可修改

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

编程语言

开发工具

架构设计

本文探讨API设计中封装的重要性，通过真实案例揭示直接暴露内部状态的风险。介绍9种封装模式，包括ConfigurationObject、Factory等，强调"只暴露契约，隐藏实现"原则。分析Stripe和Amazon SP-API的配置对象实践，展示如何通过封装保留未来修改自由。提出判断标准：每个公开接口都应考虑三年后的兼容性。

数据结构

代码解释

数据库

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

本文探讨API设计中封装的重要性，通过真实案例揭示直接暴露内部状态的风险。介绍9种封装模式，包括ConfigurationObject、Factory等，强调"只暴露契约，隐藏实现"原则。分析Stripe和Amazon SP-API的配置对象实践，展示如何通过封装保留未来修改自由。提出判断标准：每个公开接口都应考虑三年...

API-04 让API隐藏实现以便可修改-腾讯云开发者社区-腾讯云

API-04 让API隐藏实现以便可修改

API-04 让API隐藏实现以便可修改

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐