边界与接口：定义清晰才能协作顺畅

第 10 章 · 架构师成长

「这个需求到底归谁做？」「上游改了个字段没通知，我们全挂了。」 边界模糊，协作就靠扯皮；接口随意改，联调就崩。好的架构在组织、系统与代码各层都有清晰的边界：边界内高内聚、对外通过稳定、可演进的接口协作，依赖方向一致、不循环。本章讲如何识别与划定边界、接口设计的三个原则（稳定、可演进、可观测），以及契约与兼容性怎么保障协作顺畅。

一、好的边界：内聚、接口稳定、依赖方向清晰

「边界」不是为画而画，而是为了内聚（边界内变化相对集中）、接口稳定（对外承诺少变、变则可控）、依赖方向清晰（例如只依赖下层或同层，避免循环）。这三件事做好了，改一处不会到处炸、协作方有稳定契约可依。

边界存在于多个层次，从组织到系统到代码，可以统一看待：组织边界（团队/部门职责）、系统边界（服务/应用）、代码边界（模块/包/类）。每一层都有「边界内是什么、对外暴露什么接口、依赖谁」的问题。下图概括三层及其关系。

三层边界：组织（团队职责）→ 系统（服务/应用）→ 代码（模块）；依赖单向、边界清晰

在组织层：每个团队有明确负责的领域与系统，跨团队协作通过「谁提供接口、谁消费」约定清楚，避免职责重叠或空白。在系统层：每个服务有清晰的职责边界，通过 API/消息与上下游交互，不跨边界直接读库或乱调内部接口。在代码层：模块/包按职责划分，对外只暴露少量稳定接口，依赖方向一致（如都指向 domain，不循环）。

组织边界

谁负责哪块业务/系统；跨团队需求通过接口与契约对接，不越界改对方代码。

Owner 清晰
接口人/契约

系统边界

服务间通过 API/消息通信，不共享库表；变更通过版本与兼容性管理。

API / 消息契约
不跨库、不穿透

代码边界

模块内高内聚，对外稳定 API；依赖指向稳定方向，避免循环依赖。

公开 API 最小化
依赖方向一致

组织、系统、代码三层边界的关注点

要点： 边界划定的目的不是「多几道墙」，而是内聚 + 稳定接口 + 清晰依赖。这样改内部实现时，只要不破坏对外契约，协作方不受影响；出了问题也容易定位在边界内。

二、接口设计原则：稳定、可演进、可观测

边界之间的协作靠接口。接口设计不好，要么不敢改（一改就崩），要么乱改（兼容性事故频发）。三个原则能大幅降低这类问题：稳定、可演进、可观测。

稳定

对外承诺的入参、出参、语义尽量少变；必须变时通过版本或扩展字段，不破坏已有调用方。稳定不是「永远不改」，而是「改法可控、可兼容」。

可演进

通过版本号、可选字段、向后兼容策略（如只增不删、废弃先标记）支持演进。新能力用新端点或新版本，旧调用方继续可用。

可观测

接口要有可观测性：日志、指标、链路 ID。调用方和提供方都能排查「谁在调、成功失败、延迟如何」，便于定位与 SLA 管理。

接口设计三原则：稳定、可演进、可观测

案例：某支付网关对外提供「下单」接口。团队约定：同一大版本内只增字段不删、不改语义；新能力用 v2 路径；所有请求带 X-Request-Id，响应和日志都带上，便于对账与排查。结果上游商户升级时无需大改，问题排查时间明显缩短。这就是把稳定、可演进、可观测落到具体约定。

三、契约与兼容性

「契约」即双方（或多方）对接口的共识：请求/响应格式、错误码、语义、版本策略。把契约写清楚（OpenAPI、Protobuf、或文档 + 示例），并遵守兼容性规则，协作才能顺畅。

契约与兼容性要点

契约显式化：用 API 规范（如 OpenAPI）、IDL（如 Protobuf）或至少文档 + 示例定义请求/响应；避免口头约定或隐式依赖。
向后兼容：在同一版本或兼容策略下，不删除必填字段、不改变字段语义、不随意改错误码含义；新增字段用可选或默认值。
版本策略：不兼容的变更走新版本（如 URL 路径 /v1/、/v2/，或请求头 Accept-Version）；旧版本约定废弃时间与迁移路径。
兼容性测试：契约变更时跑兼容性测试（如新旧客户端对同一服务的兼容），防止「以为兼容实际不兼容」。

实践中常见做法：对外 API 用 OpenAPI 描述并纳入 CI 校验；内部服务用 Protobuf 或共享契约包，生成多语言客户端；每次发布前用契约测试或消费者契约（Pact 等）验证，避免上线后才发现不兼容。

反例：边界模糊、接口随意改，联调崩溃。

某次「订单服务」和「库存服务」归属两个小组，但订单组图方便直接连了库存的库表「查一下库存」，没有经过库存的 API。后来库存要拆库、改表结构，订单组完全不知情，上线后订单侧查询报错，两边互相推责。再如：上游把返回里的 amount 从「分」改成「元」却没通知下游，下游按「分」算钱，结果对账全错。这两类问题的根因都是边界被穿透（跨库访问）或接口契约被破坏（改语义不通知、不版本化）。正确做法：系统间只通过明确定义的 API 交互、契约变更走版本与通知、兼容性在发布前验证。

小结： 好的架构边界内聚、接口稳定、依赖方向清晰。在组织、系统、代码三层都要识别与划定边界，并通过稳定、可演进、可观测的接口协作。契约要显式化（API 规范/IDL/文档），遵守向后兼容与版本策略，并用兼容性测试保障。边界清晰、契约稳定，协作才能顺畅、变更才能可控。

自检： 你负责的系统，对外接口有没有成文契约（OpenAPI/IDL/文档）？最近一次「不兼容变更」是否走了版本或废弃流程并通知了调用方？若没有，从「列出现有接口 + 写清请求/响应与语义」开始，再逐步加上版本与兼容性规则。

四、小结

边界与接口是协作顺畅的基础：边界内聚、接口稳定、依赖方向清晰。在组织、系统、代码三层识别与划定边界；接口设计遵循稳定、可演进、可观测；用契约与兼容性（显式契约、向后兼容、版本策略、兼容性测试）保障变更可控。下一章进入问题定义与需求澄清：很多失败源于解决错误的问题，如何把需求与方案厘清。