Builder API 演进时如何保证兼容性和可维护性？

简化版

Builder API 演进要尽量做到新增可选字段不破坏旧调用，新增必填字段要谨慎设计迁移路径，默认值、校验规则和废弃字段都要有明确策略。维护重点是保持 build() 语义稳定、避免多个默认值来源、用测试覆盖旧链式调用行为。

详细版

Builder 常用于 SDK、配置对象、请求对象和领域命令，一旦对外发布，就变成 API 契约。常见演进包括：

新增可选字段；
新增必填字段；
修改默认值；
废弃旧字段；
拆分复杂字段；
增加新的校验规则。

新增可选字段通常比较安全，只要给出默认值即可。新增必填字段比较危险，因为旧调用点没有设置它。如果直接在 build() 抛异常，可能破坏线上旧逻辑。更稳的做法是提供兼容默认、迁移方法、废弃提示、版本化构建器，或在大版本中做破坏性调整。

面试回答要强调：Builder 的链式 API 看起来只是代码风格，但对调用方来说是稳定契约。维护 Builder 要像维护公共接口一样，关注二进制兼容、源码兼容、行为兼容和测试覆盖。

完整版教学

一、为什么 Builder 一旦发布就是 API 契约

内部项目里 Builder 只是一个类；SDK、公共模块、跨团队基础库里，Builder 就是调用方依赖的 API。调用方会把方法名、默认值、异常类型、调用顺序都当成稳定行为。

ClientConfig config = ClientConfig.builder()
        .endpoint("https://api.example.com")
        .timeoutMs(3000)
        .build();

如果下个版本突然要求必须调用 .region("cn")，旧代码虽然源码没改，但运行时可能在 build() 失败。对公共 API 来说，这就是兼容性问题。Builder 的演进不能只看“类还能不能编译”，还要看旧调用链的行为有没有变化。

记忆钩子：Builder 方法不是随便加减的链式语法，它是调用方已经写进代码里的契约。

二、兼容性要分四层看

Builder API 的兼容性至少有四层。第一是源码兼容，旧源码重新编译是否通过。第二是二进制兼容，旧 jar 不重新编译能否运行。第三是行为兼容，默认值和校验是否导致结果变化。第四是语义兼容，方法名表达的含义是否仍然一致。

兼容层次	例子	风险
源码兼容	删除 `timeoutMs()` 后旧源码编译失败	立即暴露
二进制兼容	改方法签名导致 `NoSuchMethodError`	运行时暴露
行为兼容	默认 timeout 从 3000 改成 500	可能线上才发现
语义兼容	`retry(3)` 从总次数变成额外重试次数	最隐蔽

很多 Builder 演进事故不是编译失败，而是行为变化。比如默认超时从 3 秒改成 500 毫秒，调用方没有改代码，但大量慢接口开始失败。

三、新增可选字段通常怎么做

新增可选字段是最常见也最安全的演进。原则是给出明确默认值，并保证旧调用链行为不变。

public static class Builder {
    private int timeoutMs = 3000;
    private int maxRetries = 2;
    private boolean gzipEnabled = false; // 新增可选字段

    public Builder gzipEnabled(boolean gzipEnabled) {
        this.gzipEnabled = gzipEnabled;
        return this;
    }
}

如果新增字段默认值会改变行为，就要谨慎。例如默认开启 gzip 可能影响网关兼容、签名计算或 CPU 使用。对公共 SDK 来说，默认值最好保持保守，新的增强能力由调用方显式开启。

旧版本:
  gzipEnabled 不存在 -> 默认不压缩

新版本:
  gzipEnabled=false -> 旧行为保持
  调用 gzipEnabled(true) -> 新行为显式开启

这类演进通常只需要补文档、补默认值测试和新字段测试。

四、新增必填字段为什么最危险

新增必填字段意味着旧调用方无法提供它。普通 Builder 中，如果直接在 build() 加校验，旧代码会从“能构建”变成“运行时报错”。分阶段 Builder 中，如果把新字段加入必填阶段，旧代码会编译失败。

假设旧版构建 1000 个调用点都没有设置 region，新版要求 region 必填。直接破坏会产生 1000 个迁移点。更稳的做法有几种：

方案 A: 给兼容默认 region="default"，标记未来版本必填
方案 B: 新增 builderV2()，旧 builder() 保持旧语义
方案 C: 提供 fromOldConfig(old).region(...).build()
方案 D: 大版本升级时破坏兼容，并给迁移文档

如果新字段真的无法默认，例如加密密钥、租户 ID、合规区域，就要把破坏性变化做成显式版本升级，而不是悄悄在小版本里让 build() 抛异常。

五、修改默认值比新增字段更隐蔽

默认值是 Builder 的隐藏契约。调用方不传某个字段，其实是在依赖默认值。修改默认值不会让源码报错，却会改变系统行为。

举个数字例子：某 HTTP 客户端默认超时 3000 ms，重试 2 次，最坏等待约为 3 * 3000 = 9000 ms。如果默认超时改为 10000 ms，最坏等待变成 3 * 10000 = 30000 ms。线程池占用、上游等待和熔断行为都会变化。

旧默认:
  timeoutMs=3000, retries=2 -> 最多 3 次请求，约 9 秒

新默认:
  timeoutMs=10000, retries=2 -> 最多 3 次请求，约 30 秒

因此默认值变更要像行为变更一样处理：写入变更说明，增加回归测试，评估调用方未显式设置该字段的影响。公共 API 中，默认值宁愿通过新 Builder 或新 profile 引入，也不要随意改旧默认。

六、废弃字段和方法怎么迁移

废弃 Builder 方法时，不要立刻删除。可以保留旧方法，标记 @Deprecated，内部映射到新字段，并在文档中说明迁移方式。

@Deprecated
public Builder connectTimeout(int timeoutMs) {
    return connectTimeoutMs(timeoutMs);
}

public Builder connectTimeoutMs(int timeoutMs) {
    this.connectTimeoutMs = timeoutMs;
    return this;
}

如果旧字段和新字段不能完全等价，要明确优先级。比如同时设置 timeout() 和 connectTimeoutMs() 时，是后设置覆盖前设置，还是新字段优先，必须稳定。否则调用链顺序会变成隐含规则，排查成本很高。

建议:
  同义迁移 -> 旧方法代理到新方法
  语义拆分 -> build() 检测冲突并给明确异常
  删除旧方法 -> 放到大版本

七、Builder 演进需要哪些测试

Builder 的测试要覆盖新行为，也要覆盖旧调用链。尤其是公共模块，要把典型旧链式调用保留下来，作为兼容性测试。

兼容性测试清单:
1. 旧调用链不设置新字段 -> build 成功且行为不变
2. 新可选字段显式设置 -> 新行为生效
3. 默认值未变 -> 断言 timeout/retry/gzip 等默认值
4. 废弃方法 -> 仍能映射到新字段
5. 新旧字段同时设置 -> 优先级或冲突异常稳定
6. 非法组合 -> 异常类型和提示清晰
7. 序列化/反序列化 -> 兼容旧配置文件

这些测试的价值在于让 Builder API 的“看不见契约”变成可执行约束。没有测试时，维护者很容易觉得只是改了一个默认值，实际上已经改了线上行为。

八、常见误区与追问

误区：新增字段只要给个 setter 就不会影响旧代码。 如果默认值改变行为，旧代码即使不调用 setter 也会受影响。
误区：新增必填字段可以直接在 build() 抛异常。 对公共 API 来说这可能破坏大量旧调用点，需要迁移策略。
误区：废弃方法应该马上删除。 立刻删除会破坏源码和二进制兼容，通常要先标记废弃并保留一段周期。
追问：Builder API 的兼容性包括哪些？ 包括源码兼容、二进制兼容、行为兼容和语义兼容。
追问：默认值变更怎么发布？ 最好大版本或新 Builder 引入，并提供回归测试和迁移说明。
追问：分阶段 Builder 新增必填字段有什么影响？ 旧调用点会编译失败，适合大版本强迁移，不适合静默小版本变更。
追问：如何处理新旧字段同时设置？ 明确代理、优先级或冲突异常，不能让调用顺序变成不可见规则。

九、加强记忆

Builder 演进记住“加可选要保默认，加必填要给迁移，改默认要当行为变更”。公共 Builder 不是内部小工具，而是调用方依赖的构建契约；测试里保留旧调用链，是防止兼容性退化的最好办法。

简化版

详细版