依赖倒置与 API 稳定性:让业务规则不依赖实现细节
依赖倒置要求高层业务策略通过自身定义的抽象使用外部能力,而不是直接依赖请求库、浏览器存储或 UI 套件。API 稳定性来自语义清晰的契约、兼容演进和自动化契约测试,不来自永远不改接口。
前置知识与能力边界
- 单一职责与组合
- Controlled 与 Uncontrolled
- React State、Context、Effect 与 TypeScript 判别联合
- 浏览器事件、HTTP 和可访问性基础
本文处理前端模块内的依赖方向、端口与适配器、公开 API 演进;不把微服务 API 网关或数据库兼容策略展开为主线。
1. 定义、所有权与数据流
依赖倒置要求高层业务策略通过自身定义的抽象使用外部能力,而不是直接依赖请求库、浏览器存储或 UI 套件。API 稳定性来自语义清晰的契约、兼容演进和自动化契约测试,不来自永远不改接口。 这里的“依赖”既包括 import 关系,也包括高层代码对某个错误码、默认值、回调时序或对象形状的假设。倒置之后,业务模块拥有这份假设,基础设施只能实现它。
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 |
| 区分可修正与可重试失败 | 判别联合 OrderError | statusText、厂商错误类 |
| 取消已经过时的提交 | 标准 AbortSignal | CancelToken 或 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,而是让业务用例与传输实现分离。
- 搜索订单域中的
axios、AxiosError、response.data和深层客户端导入,保存基线清单。 - 定义
OrderGateway、输入命令、成功结果和OrderError,用内存实现先跑通用例测试。 - 写 Axios 适配器,把已有行为冻结成契约 fixture,包括 400 字段错误、401、409 与网络中断。
- 写 Fetch 适配器,消费
AbortSignal,校验成功响应后再构造领域结果。 - 在组合根切换实现;业务用例的源码和测试 fixture 不修改。
- 删除订单域对 Axios 包的依赖并重新执行 TypeScript 编译。若仍出现
AxiosError,说明类型已经越过端口。
成功证据包括:两个适配器通过同一组契约测试;慢请求切换页面后被取消;相同幂等键不会生成两个订单;移除 Axios 后订单业务包仍可构建。
失败注入把第一次请求延迟 800ms,随后发送第二次请求并取消第一次。第一次响应即使到达也不能更新第二次操作的 UI。仅依赖 React 卸载警告不足以证明竞态被处理。
6. 案例二:稳定分析事件而不稳定供应商 SDK
分析供应商升级时把 track(name, properties) 改成另一个初始化和批处理接口。业务真正关心的是“商品被查看”和“结算完成”,而不是供应商事件队列。
- 定义只允许
ProductViewed与CheckoutCompleted的领域事件联合。 - 给每个事件定义字段白名单;邮件、姓名、地址与完整搜索词不能进入适配器输入。
- 旧 SDK 与新 SDK 各实现
AnalyticsPort,用相同 fixture 检查事件名和字段。 - 未同意追踪、脚本被内容拦截器阻止、发送队列满时,适配器降级但不阻止结算。
- 组合根按同意状态选择真实或 no-op 实现;业务组件不读取供应商全局对象。
契约测试额外注入一个包含 email 的非法对象,并断言运行时 schema 拒绝它。TypeScript 只能约束仓库内的静态调用,无法保证从 JSON 或旧 JavaScript 传入的数据安全。
SDK 的批量、重试和 flush 时机属于适配器运维策略。若这些策略需要影响业务流程,应提升为明确端口结果,不能让业务通过等待隐藏的 SDK Promise 猜测是否完成。
7. TypeScript 核心实现
下面代码把领域用例依赖收敛为端口,并用适配器承接 HTTP 与存储细节。验证时应替换为内存适配器,确认用例测试不会加载具体 SDK。
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 有弃用路径、调用扫描和明确删除条件。
来源
- TypeScript Handbook:Modules(访问日期:2026-07-18)
- Node.js:Packages exports(访问日期:2026-07-18)
- React:Scaling Up with Reducer and Context(访问日期:2026-07-18)
- Semantic Versioning 2.0.0(访问日期:2026-07-18)