18.1 入口

为什么 18.1 入口值得单独学习

订单系统通常要发邮件、调用支付 API 或写入消息队列。若每个领域服务都直接拼接 URL、处理供应商错误并解释协议状态，外部变化会沿着调用链扩散，测试也不得不启动真实基础设施。Gateway 的价值是给内部代码一个稳定的语义入口，把外部协议留在边界对象里。

不是“把所有依赖藏起来”的万能包装，而是一条有责任范围的边界：它可以翻译协议和错误，却不应替领域服务作出价格、权限或订单状态等业务决定。好的入口让变化局部可见，坏的入口只是把复杂度换了一个文件名。

本章只覆盖 2024 年中文版公开目录中的 18.1 入口，依据作者图书页和公开模式目录独立重写。案例、实验、代码、练习和答案均为本课程原创，不复现原书正文、插图或代码。

先建立直觉：稳定契约隔离易变协议

把一次通知拆成“调用者 → 内部契约 → Gateway → 外部协议 → 结果”五个观察点。稳定契约描述“发送订单确认”，而不是暴露 SMTP 状态码、HTTP header 或某家 SDK 的异常类型。

Gateway 还承担错误翻译。外部系统返回 429 时，调用者需要知道“可稍后重试”；返回无效收件人时，需要知道“不可重试并记录业务原因”。如果 Gateway 直接把第三方异常透传，调用者仍然被供应商绑定。

边界的另一面是依赖方向。接口放在哪里、实现由谁组装、测试替身如何注入，都是设计证据。只有当外部变化真实存在、调用者足够多或测试隔离有收益时，间接层才值得付出维护成本。

目录单元到教学证据

18.1 入口

本章精确对应 manifest 单元 poeaa24-pattern-41-gateway。学习边界是：用一个专属 Gateway 封装订单系统的外部通知，并通过稳定契约、错误翻译和可替换实现证明依赖方向。

完成本单元要交出三样证据：一张调用者、Gateway 和外部系统的责任图；一段可测试的 TypeScript 契约与适配实现；一个故障样本，证明超时、限流或供应商错误不会穿透成调用者必须理解的 SDK 细节。

专属案例：订单确认通知

订单服务只应提出“发送订单确认”这一内部意图。EmailGateway 负责把它转换为 SMTP 或第三方邮件 API 的请求，统一处理超时、限流和无效地址，并返回 sent、retryable 或 rejected 三类结果。订单服务仍负责决定是否允许发送、是否记录订单事件，以及重复发送是否幂等。

评审卡记录如下：单元键为 poeaa24-pattern-41-gateway；模式族为 base；采用条件是“外部协议易变、调用者超过一个且需要测试替身”；观测项包括外部错误分类、超时率、重试次数、调用者依赖数量和替身覆盖率；拒绝条件是“没有变化轴、入口开始承载业务规则，或只增加一层转发却没有隔离证据”。

专属可视化实验：看依赖停在哪里

先预测：当 SMTP 改成 HTTP 邮件 API 时，领域代码应不应修改？点击主图观察稳定契约如何停在 Gateway 左侧、协议细节如何被限制在右侧，以及测试替身为什么能在不启动外部系统的情况下验证调用者行为。

代码实践：翻译协议而不是泄漏协议

下面的 TypeScript 草图把外部客户端作为注入依赖。Gateway 只返回内部结果，不把供应商异常类型传给订单服务；重试策略仍应由明确的可靠性策略和幂等键约束。

type SendConfirmation = {
  orderId: string;
  email: string;
  idempotencyKey: string;
};
 
type DeliveryResult =
  | { kind: "sent"; providerId: string }
  | { kind: "retryable"; reason: "timeout" | "rate-limited" }
  | { kind: "rejected"; reason: "invalid-address" | "blocked" };
 
type MailClient = {
  send(input: { to: string; body: string; idempotencyKey: string }): Promise<{
    status: number;
    providerId?: string;
  }>;
};
 
export class EmailGateway {
  constructor(private readonly client: MailClient) {}
 
  async sendConfirmation(input: SendConfirmation): Promise<DeliveryResult> {
    try {
      const response = await this.client.send({
        to: input.email,
        body: renderConfirmation(input.orderId),
        idempotencyKey: input.idempotencyKey,
      });
      if (response.status === 202 && response.providerId) {
        return { kind: "sent", providerId: response.providerId };
      }
      if (response.status === 408 || response.status === 429) {
        return {
          kind: "retryable",
          reason: response.status === 408 ? "timeout" : "rate-limited",
        };
      }
      return { kind: "rejected", reason: "blocked" };
    } catch {
      return { kind: "retryable", reason: "timeout" };
    }
  }
}

这里有四个可验收边界：内部方法不暴露 SMTP 或 SDK 类型；外部状态被翻译为有限结果；请求带幂等键；Gateway 不决定订单是否已付款。若调用者开始捕获 VendorRateLimitError，或 Gateway 为了“方便”直接读取订单数据库，就应把它标成越界样本。

选择与拒绝矩阵

常见误区

本章小结

• Gateway 用稳定内部契约隔离外部协议、供应商错误和基础设施变化。
• 它可以翻译错误和处理可靠性边界，但不应接管订单、权限或库存等业务决定。
• Fake/Stub、有限结果类型、超时分类和幂等键是可验证的工程证据。
• 没有变化轴或没有测试隔离收益时，应拒绝额外间接层；透传 SDK 也不算完成隔离。

可验证练习

名词解释

前后导航

• 上一页：第18章 基本模式
• 下一页：18.2 映射器

参考资料

• Martin Fowler 作者图书页：核对全书主题、章节范围和模式参考结构。
• Martin Fowler 模式目录：核对入口模式的公开定位与模式族。
• Pearson 出版社页面：交叉核对英文版出版信息与目录范围。