Skip to content

依赖倒置与 API 稳定性:让业务规则不依赖实现细节 ​

依赖倒置要求高层业务策略通过自身定义的抽象使用外部能力,而不是直接依赖请求库、浏览器存储或 UI 套件。API 稳定性来自语义清晰的契约、兼容演进和自动化契约测试,不来自永远不改接口。

前置知识与能力边界 ​

本文处理前端模块内的依赖方向、端口与适配器、公开 API 演进;不把微服务 API 网关或数据库兼容策略展开为主线。

1. 定义、所有权与数据流 ​

依赖倒置要求高层业务策略通过自身定义的抽象使用外部能力,而不是直接依赖请求库、浏览器存储或 UI 套件。API 稳定性来自语义清晰的契约、兼容演进和自动化契约测试,不来自永远不改接口。 这里的“依赖”既包括 import 关系,也包括高层代码对某个错误码、默认值、回调时序或对象形状的假设。倒置之后,业务模块拥有这份假设,基础设施只能实现它。

mermaid
flowchart LR
    A0["业务用例"] --> A1
    A1["领域端口"] --> A2
    A2["适配器"] --> A3
    A3["第三方 SDK"] --> A4
    A4["外部系统"]

业务用例只认识 OrderGateway 等领域端口;适配器单向依赖端口并翻译外部协议;组合根知道两侧并负责实例化。删除某个适配器后,业务用例及其测试仍应编译和运行。

2. 关键机制 ​

2.1 高层策略 ​

订单提交、权限判定等业务规则定义需要什么能力,不引用 fetch 或厂商类型。

若边界缺失,业务测试必须启动真实网络。

验证:用内存适配器执行用例测试。

2.2 端口 ​

用最小 TypeScript 接口表达业务所需语义、输入、输出和错误。

若边界缺失,接口照抄第三方 SDK 后无法替换。

验证:禁止端口暴露 AxiosResponse 等类型。

2.3 适配器 ​

把 HTTP、Storage、Analytics 的返回值转换为领域对象。

若边界缺失,外部字段变化穿透全部页面。

验证:契约测试固定转换与错误映射。

2.4 组合根 ​

在应用入口选择真实或测试实现并注入用例。

若边界缺失,模块内部到处 new 客户端。

验证:依赖图只在组合根指向具体实现。

2.5 公开 API ​

每个模块通过 index.ts 暴露稳定入口,内部文件不承诺兼容。

若边界缺失,深层导入锁定目录结构。

验证:静态检查禁止跨模块深层导入。

2.6 语义版本 ​

破坏调用方式或语义才是 breaking change;类型可赋值不代表行为兼容。

若边界缺失,默认值悄悄改变导致线上行为变更。

验证:变更日志和契约 fixture 覆盖默认值。

2.7 能力接口 ​

调用方依赖窄接口而非万能 service,读写能力可分离。

若边界缺失,巨型接口使测试桩实现无关方法。

验证:统计每个实现实际使用的方法。

2.8 错误契约 ​

适配器把传输错误归一为可判定的领域错误联合。

若边界缺失,页面按 status 文本猜错误。

验证:类型穷尽处理 retryable、unauthorized、validation。

2.9 取消与时序 ​

异步端口显式接受 AbortSignal 和关联 ID。

若边界缺失,旧请求完成覆盖新请求。

验证:延迟适配器测试取消与乱序。

2.10 兼容层 ​

迁移期用旧 API 包装新 API,并设置移除条件。

若边界缺失,双接口无限共存增加维护面。

验证:构建日志统计旧入口调用并设截止版本。

3. 从第三方调用提炼端口 ​

不要从“给 axios 包一层”开始。先列出业务用例实际需要的操作:

业务问题端口应表达不应泄漏
提交当前购物车submit({ cartId, idempotencyKey }, signal)URL、HTTP method、Axios config
区分可修正与可重试失败判别联合 OrderErrorstatusText、厂商错误类
取消已经过时的提交标准 AbortSignalCancelToken 或 SDK request handle
取得新订单身份{ orderId }完整响应 header、DTO 包装层

端口参数必须足以执行用例,但不能为了“以后可能用到”暴露整个请求配置。若调用方可以任意改 URL、header 或重试次数,基础设施策略事实上仍由页面控制。

3.1 先定义领域错误 ​

temporary 表示同一逻辑操作在满足幂等条件时可以重试;validation 要把稳定字段路径交给表单;unauthorized 触发重新认证而不是指数退避。适配器需要保存原错误作为受控的诊断 cause,但页面不按 cause 的类名分支。

3.2 再实现传输映射 ​

Fetch 适配器负责 JSON 编码、状态码判断、响应 schema 校验和 AbortSignal 传递。HTTP 409 只有在接口契约定义为版本冲突时才映射为领域 conflict;不能把所有接口的 409 机械解释成同一业务含义。

3.3 最后在组合根注入 ​

浏览器入口创建带当前会话的适配器,测试入口创建内存适配器,SSR 每个请求创建独立实例。领域文件不能自行读取全局 token,也不能在模块顶层构造带用户信息的单例。

4. API 稳定性的四个维度 ​

4.1 类型形状 ​

删除必填字段、收窄允许值或改变返回联合会让消费者无法编译。新增可选字段通常保持结构兼容,但如果调用方必须处理它才能保证正确,仍需要迁移说明。

4.2 行为语义 ​

把默认超时从 30 秒改成 3 秒、把空数组改成 undefined、或从“按调用顺序完成”改成并发完成,都可能在类型不变时破坏消费者。契约测试必须覆盖默认值、错误与时序,而不只是 TypeScript 声明。

4.3 副作用与资源 ​

同一个函数如果新增遥测、缓存或自动重试,会改变请求数量、隐私面和卸载行为。公开契约需说明是否缓存、是否可能重试、怎样取消以及回调最多执行几次。

4.4 兼容演进 ​

迁移期可以保留旧函数并转调新用例。旧入口发出开发期弃用警告,仓库扫描统计调用点;当调用归零且约定版本到达后删除。兼容层不得长期双向同步两套状态。

5. 案例一:把订单模块从 Axios 迁移到 Fetch ​

原模块的 27 个页面直接读取 AxiosResponse.data,并用 error.response?.status 决定提示。目标不是逐处把 axios.post 换成 fetch,而是让业务用例与传输实现分离。

  1. 搜索订单域中的 axios、AxiosError、response.data 和深层客户端导入,保存基线清单。
  2. 定义 OrderGateway、输入命令、成功结果和 OrderError,用内存实现先跑通用例测试。
  3. 写 Axios 适配器,把已有行为冻结成契约 fixture,包括 400 字段错误、401、409 与网络中断。
  4. 写 Fetch 适配器,消费 AbortSignal,校验成功响应后再构造领域结果。
  5. 在组合根切换实现;业务用例的源码和测试 fixture 不修改。
  6. 删除订单域对 Axios 包的依赖并重新执行 TypeScript 编译。若仍出现 AxiosError,说明类型已经越过端口。

成功证据包括:两个适配器通过同一组契约测试;慢请求切换页面后被取消;相同幂等键不会生成两个订单;移除 Axios 后订单业务包仍可构建。

失败注入把第一次请求延迟 800ms,随后发送第二次请求并取消第一次。第一次响应即使到达也不能更新第二次操作的 UI。仅依赖 React 卸载警告不足以证明竞态被处理。

6. 案例二:稳定分析事件而不稳定供应商 SDK ​

分析供应商升级时把 track(name, properties) 改成另一个初始化和批处理接口。业务真正关心的是“商品被查看”和“结算完成”,而不是供应商事件队列。

  1. 定义只允许 ProductViewed 与 CheckoutCompleted 的领域事件联合。
  2. 给每个事件定义字段白名单;邮件、姓名、地址与完整搜索词不能进入适配器输入。
  3. 旧 SDK 与新 SDK 各实现 AnalyticsPort,用相同 fixture 检查事件名和字段。
  4. 未同意追踪、脚本被内容拦截器阻止、发送队列满时,适配器降级但不阻止结算。
  5. 组合根按同意状态选择真实或 no-op 实现;业务组件不读取供应商全局对象。

契约测试额外注入一个包含 email 的非法对象,并断言运行时 schema 拒绝它。TypeScript 只能约束仓库内的静态调用,无法保证从 JSON 或旧 JavaScript 传入的数据安全。

SDK 的批量、重试和 flush 时机属于适配器运维策略。若这些策略需要影响业务流程,应提升为明确端口结果,不能让业务通过等待隐藏的 SDK Promise 猜测是否完成。

7. TypeScript 核心实现 ​

下面代码把领域用例依赖收敛为端口,并用适配器承接 HTTP 与存储细节。验证时应替换为内存适配器,确认用例测试不会加载具体 SDK。

tsx
type OrderError =
  | { kind: "validation"; fields: Record<string, string> }
  | { kind: "unauthorized" }
  | { kind: "temporary"; retryAfterMs?: number };

type Result<T> = { ok: true; value: T } | { ok: false; error: OrderError };

export interface OrderGateway {
  submit(input: { cartId: string; idempotencyKey: string }, signal: AbortSignal):
    Promise<Result<{ orderId: string }>>;
}

export async function placeOrder(
  gateway: OrderGateway,
  cartId: string,
  signal: AbortSignal,
): Promise<Result<{ orderId: string }>> {
  return gateway.submit({ cartId, idempotencyKey: crypto.randomUUID() }, signal);
}

端口类型只能约束编译期调用者;适配器仍要校验外部响应、归一化错误,并测试超时、缺字段和版本不兼容。接口稳定性的证据是替换适配器后用例语义不变。

8. 方案选择 ​

方案适用条件成本与限制
直接依赖短期原型、依赖稳定且迁移成本可接受速度快但测试与替换成本扩散
本地适配器单模块需要隔离一个外部库增加一层转换和契约测试
共享端口多个业务模块需要同一能力语义要防止接口膨胀成万能服务

只有依赖变化频率高、测试需要替身或领域层不能接受设施语义时才抽象端口。若接口只是原 SDK 的逐字转发,新增抽象不会形成稳定边界。

9. 调试与失败注入 ​

现象检查修正
换库需改几十处搜索第三方类型的传播路径先在边界建立适配器再逐步迁移
测试桩很巨大端口是否包含无关方法按能力拆分接口
升级后编译通过但行为错默认值、错误、时序是否改变加入行为契约 fixture
循环依赖领域层是否导入适配器移动组合到入口层
取消无效端口是否传递 signal模拟慢请求并断言 aborted
旧 API 不会消失是否有调用统计与截止条件弃用警告升级为 CI 失败
错误判断靠字符串是否定义判别联合在适配器归一化错误
SSR 串用户是否共享带会话的单例每请求创建依赖容器

先确认用例实际解析到哪个端口实现,再比对端口参数与适配器发送的请求,最后检查外部响应到领域错误的映射。失败信号是领域测试必须启动真实设施、调用方判断供应商错误字符串,或替换适配器后返回语义改变;用契约测试和内存适配器复现。

10. 性能、安全与运维边界 ​

  • 端口不暴露第三方类、HTTP 状态或浏览器全局对象。
  • 适配器记录依赖版本、延迟、失败种类和取消率。
  • 认证令牌由受控会话层注入,业务输入不能任意覆盖。
  • 幂等性、授权和金额校验仍由服务端保证。
  • 公开 API 删除前需要弃用期、迁移说明和调用扫描。
  • 模块包启用 exports 限制可导入入口。
  • 契约测试同时运行真实适配器和内存适配器。
  • 组合根按 SSR 请求或浏览器会话隔离有状态实例。

生产验证至少记录一次正常路径和一次故障路径;对“依赖倒置与 API 稳定性”的结论必须能关联到日志、Profile、网络记录或自动化测试。

11. 与其他架构模块集成 ​

  • 与模块分层结合:领域层定义端口,基础设施层实现,入口层组合。
  • 与统一错误模型结合:传输细节在适配器消失。
  • 与 ADR 结合:记录为何引入边界及其退出条件。
  • 与循环依赖检查结合:禁止领域反向导入基础设施。

集成时让组合根创建具体适配器,并只把端口传给用例层;领域模块不导入供应商包。用依赖图和契约测试同时验证方向与行为,避免“类型上抽象、运行时仍耦合”。

12. 综合练习 ​

选择一个同时直接依赖请求库、Web Storage 和分析 SDK 的结算模块。为三种能力分别定义窄端口,保留一个真实适配器和一个内存适配器,并在组合根完成注入。

验收标准 ​

  • [ ] 业务目录不再导入第三方包、HTTP DTO 或浏览器存储全局对象。
  • [ ] 请求端口覆盖取消、幂等、字段错误和迟到响应。
  • [ ] 存储端口区分不存在、损坏与配额失败,不返回裸字符串。
  • [ ] 分析端口用事件联合和字段白名单拒绝个人信息。
  • [ ] 替换任一真实适配器时,业务用例及其测试无需修改。
  • [ ] 公开旧 API 有弃用路径、调用扫描和明确删除条件。

来源 ​

从前端走向软件产品工程的长期路线图。