1. 模块边界定义：边界语义、职责隔离原则、接口契约
模块边界是架构的“第一刀”——它划定系统内各组件的能力范围、交互方式与信任假设。本章从三个维度建立边界定义的理论基础：边界语义解释“边界是什么”，职责隔离原则指导“边界如何切分”，接口契约规定“边界如何通信”。这三者共同构成所有后续埋点传递与状态同步方案的逻辑起点。
1.1 边界语义
边界语义回答“边界两侧的观察者如何看待对方”。在分布式与微服务架构中，每个模块对外呈现为“黑盒”或“灰盒”：
- 黑盒语义：外部只能通过接口获取结果，内部实现、缓存、临时状态均不可见。适用于核心领域模块及第三方集成。
- 灰盒语义：外部可读取部分状态元信息（如健康、版本、进度），但不能直接操作内部数据。常用于监控、治理及埋点采集。
- 白盒语义：不设边界，内部结构完全暴露。仅用于同一进程内高度耦合的子模块，本指南不推荐用于模块间交互。
选型权衡：过度黑盒会阻碍跨模块感知（例如无法获取上游处理进度）；过度灰盒则增加耦合与安全隐患。建议按“公共服务→灰盒、业务域→黑盒”的二分策略初始定义。
1.2 职责隔离原则
边界切分的根本依据是“单一职责”与“变化隔离”。以下原则可直接用于评审模块划分的合理性：
| 原则 | 含义 | 反例 |
|---|---|---|
| 单一职责 | 一个模块只对一类业务逻辑负责 | 认证模块同时处理支付订单查询 |
| 变化隔离 | 一个模块内部变化不应连锁扩散到其他模块 | 升级支付网关导致计费模块需要重新部署 |
| 数据归属 | 每个数据实体有且仅有一个“写主”模块 | 订单状态可由订单模块和物流模块同时更新（出现冲突） |
| 能力完整 | 模块提供的功能在业务上自成闭环，避免循环依赖 | 模块A调用B完成发货，B又调用A查询库存（循环） |
风险点：职责隔离不充分会导致“上帝模块”（God Object）——单模块承担过多职责，成为全局修改瓶颈。落地前建议使用依赖图扫描检测循环与高扇入/扇出。
1.3 接口契约
接口契约是边界上双方必须遵守的通信协议，包括类型、语义、质量与安全承诺。典型的契约形式：
- RESTful API 契约：OpenAPI/Swagger 规范 + 状态码定义 + 幂等性声明。
- 消息契约：Avro / Protobuf schema + Topic 命名规则 + 投递保证（at-least-once / at-most-once）。
- RPC 契约：gRPC service proto + 超时阈值 + 重试策略。
接口契约必须包含以下元数据（在接口定义中以注释或扩展字段标明）：
// 示例：OpenAPI 扩展契约元数据
post /api/orders
x-contract:
owner: order-service
version: "2.1.0"
stability: stable
sync-strategy: eventual // 最终一致
idempotency-key: x-idempotency-id
trace-passing: true
requestBody:
required: true
content:
application/json
responses:
"202": accepted (处理中)
"201": created (立即完成)
"429": throttled (请回退重试)
落地步骤：1) 由上游模块维护契约仓库；2) 双方共同评审并签署契约；3) 集成测试阶段加入契约一致性校验（如
pact框架）；4) 将契约版本纳入部署流水线门禁。
整体概念框架
下图展示了两个模块之间的边界组成：边界语义决定可见性等级，职责隔离原则指导切分方向，接口契约封装所有交互细节。埋点传递路径与状态同步策略均在此边界基础上构建。
验收标准（第1章）
完成本章学习后，应能对任意两个模块间的边界给出明确描述：
- 边界语义：黑盒/灰盒等级已定义，且知悉选用原因。
- 职责隔离：模块职责清单已列出，并通过“变化隔离”与“数据归属”原则检查无冲突。
- 接口契约：至少列出三种元数据（版本、稳定性、同步策略），且写入接口定义文件。
自测：你当前系统中最核心的两个模块之间的边界，是否存在“灰色地带”（如职责模糊、契约缺失）？试按本章框架补全边界定义文档。