边界与接口隔离
§1摘要与结论
在模块、服务与层之间显式划定边界，并让跨边界交互仅通过窄而稳定的接口进行，把内部实现与外部契约隔离开。边界决定变更传播范围与理解成本。它要求把跨边界交互收敛为显式承诺。
别名：boundaries、interface segregation、stable interface | 英文：Boundaries and Interface Segregation | 类型：方法原则 / concept
§2局部关系图
§3原理 · 为什么
边界回答「什么被承诺、什么可自由变化」：清晰且稳定的接口使两侧可独立演化，一侧的内部重构只要不改变契约，就不会影响另一侧。反之，边界模糊会让内部细节被外部假设成事实上的公共契约，此后任何内部改动都成了破坏性变更，系统逐渐丧失演化能力。因此边界的核心不是物理隔离，而是契约与假设的管理——跨边界的一切交互都应被显式定义，包括数据格式、语义、错误行为与约束。边界同时是认知工具：它把系统切分为可分别理解的单元，缩小任一时刻需要同时掌握的范围。良好的边界还应对齐变化方向，让最常一起变化的元素落在同一侧，把最可能分道扬镳的部分分开，从而同时服务于变更隔离与认知切分两个目标。边界的价值还体现在故障隔离与替换成本上：契约清晰时，一侧的失败或升级不会无声地穿透到另一侧，替换实现也只需满足同一组外部可见承诺。边界的存在还使并行工作成为可能：只要契约稳定，两侧的团队或模块可以各自推进，而不必等待对方内部实现完成，从而降低协作的时序耦合。
§4机制 · 如何运作
以接口或契约而非实现来定义边界，明确暴露面与允许的依赖方向；边界内的元素可以自由重构，只要契约不变。接口隔离要求调用方不被迫依赖它用不到的能力——把庞大接口拆成按使用方视角定制的小接口，避免一个使用方的小需求变更迫使所有使用方重新编译或重新测试。边界的内容应以「外部可见属性」为准：其它元素可以据此做假设的部分才属于边界，私有实现不属于。数据穿越边界要经过显式映射，防止一方的内部模型直接泄漏到另一方的类型系统；错误与异常语义也应在契约中定义，而非由实现细节决定。跨边界的依赖最好单向，避免形成相互假设的循环；当两侧需要频繁互调时，往往说明边界划错了位置。边界两侧应各自拥有其内部模型，跨界只交换经过明确定义的契约数据；这既避免了类型系统相互渗透，也让两侧可独立选择实现技术与演进节奏。边界内的重构自由与边界外的契约稳定是一体两面：正因为外部只依赖承诺，内部才敢于持续调整；反之，越界访问一次，这份自由就被削弱一分。
§5工程 · 怎么落地
用领域边界、模块或包的公开接口、API 契约与适配器落地：对外只暴露稳定的公开表面，内部类型与实现不对外可见；用依赖方向检查、包结构与构建约束把「谁可以依赖谁」固化下来，使越界在构建时暴露。以架构适应度函数持续校验依赖方向与边界完整性，让约束不因日常改动而悄然失守。契约要版本化并有变更流程，破坏性变更须显式公告与迁移路径，允许新旧版本在一段窗口内共存。对跨团队边界，契约还需配拥有者与沟通机制，因为边界两侧的独立演化依赖清晰的接口约定。评审时检查是否有内部类型、临时字段或实现细节出现在公开接口上，这些通常是边界被悄悄穿透的信号，也是未来破坏性变更的隐患。当边界跨越团队或进程时，还需为契约建立变更协商与兼容窗口，并通过契约测试同时验证提供方与消费方，避免单侧改动造成不易察觉的不兼容。在接口设计中，应优先暴露表达意图的高层操作，而非内部数据结构的机械映射；后者会把实现细节固化为契约，使边界在实现变化时被迫破坏。
§6权衡卡
过窄的接口也可能把本应原子的操作拆成多次远程往返，带来新的耦合与不一致风险。
合理策略是只在变化方向不同、团队归属不同或需要独立部署的地方设边界，其余保持合并，并持续评估每条边界带来的隔离收益是否高于协调成本。
边界也需要演化：当两侧的变化方向逐渐趋同，或某条契约长期只服务于单一场景时，应重新评估是否合并，避免为形式上的隔离承担长期维护成本。
边界越多，跨边界的交互与映射成本越高，过度隔离会造成系统碎片化：每一处边界都要维护契约、处理序列化与版本兼容，调用从进程内变为跨进程时还会引入延迟、部分失败与一致性难题，最终可能拼出一个「分布式的单体」——逻辑上高度耦合，却被网络边界割得难以调试。
- 边界应沿真实的变化方向与团队认知对齐，并随需求演进而调整，而不是一次划定后僵化不动。
- 判断边界是否值得保留，可以看它是否降低了整体的跨边界协调量；若两条边界之间的协作远比边界内部更频繁，就说明边界没有切在真正的接缝上。
权衡原文仅按显式标记词归栏引用（收益 / 代价 / 反例），其余句子按原序列为「原文要点」；内容逐字引用未改写。
§7学习路径条
§8案例带
网申填写扩展逆向架构
对 Chrome MV3 网申自动填写扩展的逆向架构分析：梳理 popup、content、background、options 四模块职责，解剖 12 个站点适配器、双通道消息协议与隐私脱敏机制，并评估其零依赖零构建选型。
preset 通道耦合分析
对 harness「委派工具层→续用管理器→preset 服务→MCP 服务器」这条通道做耦合分析：识别契约、服务定位、数据契约、组合语义、路径与装配一致性六类耦合点，定位「静默丢弃特化」与「装配漂移」两处实质缝隙。
dsh-manager 插件深度分析
以「编译依赖、运行时注入、组合装配」三硬依据加源码行号，对第三方插件做依赖、功能、需求溯源与设计问题裁决，并复用上游 DAG 知识库节点标识，使分析结果可与主图互查。
去中心化聊天架构逆向
对一个仅有 58 份设计文档、尚未实现的开源去中心化聊天项目做架构逆向：从设计文本提炼 18 个模块及其依赖关系，重建模块依赖 DAG 与三条核心数据流 DAG，并输出全景理解与深度需求分析。
网申 v3 多模块解耦
一套面向高可扩展性的网申信息速查扩展架构：以 schema.js 为唯一数据驱动源，把数据模型、存储、纯函数与渲染组织为严格单向依赖的共享层，供 popup 与页面浮层双容器复用，并先立跨模块接口契约。
网申 v2 深度重构
一次由「改一处漏多处」症状触发的深度重构：定位到接口定义散落 12 个文件、存在 7 种接口形态的根因后，以单一契约源、dispatch 消息表与能力注册中心重建三层契约系统，恢复可审计与可校验性。
harness 源码架构解析
对 deepseek-harness 官方源码做分层解析：镜像官方架构文档，按九个层与九十余模块建立文档集群，产出跨层联动矩阵与七条关键路径，并钉住「模型可见即已记录」、能力缝三角等设计不变量。
dsh 插件依赖增量定位
以官方插件 DAG 为蓝本，对一个官方清单之外的全新社区插件做功能定位与依赖位置增量分析，产出可下钻交互依赖图与多形态文档的源码级架构逆向案例。
Hermes 七层架构总览
对八千余文件的工业级 AI Agent 项目做七层架构总览逆向，揭示其「越用越聪明」的自进化闭环如何在层间传导的控制型架构案例。
MCP 四件套选型对比
对四个同类 MCP 服务器做源码级能力与成本对比，并以常驻 token 预算为轴给出分级接入策略的技术选型实战案例。
Claude Code 架构逆向
以社区逆向源码、系统提示词与官方文档三源交叉验证，还原一个商业 Agent 的查询引擎、子Agent、工具与权限体系的逆向分析案例。
Open Code Review 图谱
对阿里开源 AI 代码审查 CLI 做源码级解析并构建「知识 + 实践资产 + AI 索引」三合一知识图谱的工程案例。
控制理论⊗Agent 设计
将控制理论五维（负反馈 / 状态估计 / PID / 鲁棒 / 分层）系统映射到 Agent 工程环节，并以真实产品案例验证的跨学科方法论案例。
AI Agent 架构 DAG 复盘
对四个工作日内独立完成三个异构对象 DAG 分析的方法论复盘，总结「采集→建模→生成→门控→交付」可复用管线与关键教训。
§9信源与核验
§10原始关系清单
展开：本节点的全部原始关系边（10 条，含边 ID 与方向）
| 关系 | 方向 | 对端节点 | 说明 |
|---|---|---|---|
| 案例印证 | ← CAS-X-02 | 网申填写扩展逆向架构 E-943 | 印证：以双通道与密钥隔离划清信任与能力边界 |
| 案例印证 | ← CAS-X-05 | preset 通道耦合分析 E-951 | 印证：特化标识由提供者构造期绑定，通用契约零扩展 |
| 案例印证 | ← CAS-X-08 | dsh-manager 插件深度分析 E-959 | 印证：双半边架构以同源接口维持清晰边界 |
| 组合 | ← ESS-G-06 | 视图与视角 E-106 | 视图记录边界与接口的外部可见属性 |
| 组合 | ← ESS-G-07 | 架构描述与对应关系 E-729 | 架构描述记录边界与接口的外部可见属性 |
| 依据推导 | ← MTH-G-04 | 领域驱动战略设计 E-204 | 限界上下文依边界与接口隔离原理 |
| 前置依赖 | → ESS-G-02 | 依赖倒置与依赖规则 E-06 | 先划定边界，才能约束依赖方向 |
| 前置依赖 | ← ESS-H-02 | 内聚与耦合 E-04 | 内聚耦合度量指导边界划分 |
| 前置依赖 | ← ESS-N-01 | 康威定律 E-05 | 组织沟通结构约束可行边界 |
| 前置依赖 | ← ESS-O-02 | 架构即权衡 E-11 | 边界划分是对多重质量属性的权衡 |