第 1 章 模块边界、分层与架构设计
来自《系统架构与工程化学习》 · 原稿更新 2026-11-09 · 服务器只读阅读视图
1.1 高内聚与低耦合
高内聚:因同一业务原因变化的代码聚在一起。低耦合:模块之间只知道必要的接口。
正确理解
- 认证规则集中在认证模块,订单模块只依赖“当前用户及权限”这个契约。换 Token 机制时,不用改所有业务模块。
- 两者是不同维度,没有必然因果。职责集中的模块也可能重度依赖外部系统;外部依赖很少的“上帝类”,内部也可能一团乱。
- 判断重构时分开看:同一变更要改几个内部职责,接口变化牵动多少外部调用方。
1.2 分层与依赖倒置
分层不是多建目录,而是业务核心不直接依赖 SDK、数据库驱动或 Web 框架。
正确理解
- 网页、微信、CLI 共用 Agent Core:各入口先转成统一输入,再调用同一份核心逻辑。
- 依赖倒置不等于每个 Helper 都写 Interface。外部依赖有真实变化和替换价值时才抽象。
- 单例要看三件事:共享可变状态、初始化副作用、生命周期。带请求状态的单例会让并发任务互相污染;构造时偷偷连数据库、MQ 的单例隐藏依赖,难测难换。无状态纯函数直接做模块函数即可。
- 稳定依赖原则是方向,不是硬规则。被依赖越多的契约越要谨慎变化,但只凭“底层更稳定”“引用多就不会改”去抽象,会过度设计。
1.3 最小契约与防腐层
最小契约解决“模块知道太多”,防腐层解决“外部格式污染内部”。
正确理解
- 通知系统只需要 user_id、message、channel,就不该拿整份 User ORM 对象。外部复杂 JSON 由 Adapter 映射成内部需要的少量字段。
- 2026-07-23 的一次接口兼容:旧客户端仍传业务实体 ID,边界层先接收,只提取核心真正需要的参数,避免核心逻辑、缓存键和 Provider 调用继续耦合上游 ID。接收旧字段只是协议兼容,不代表信任其身份或授权,迁移期限要明确。
- 新旧 API 主流程相同、只在分块、部分成功、错误降级上不同时,可由 Adapter 选择中性命名的执行策略,Core 只按策略工作,不必复制两套 Service。差异扩展到数据模型和生命周期时,就别再堆布尔开关。
- 兼容的真正难点是字段类型统一不等于语义统一:空字符串、null、-1、未提供、查询失败要分别约定。先定义新契约,在 API 边界把旧入口转成内部模型;已有下游依赖时用适配层或受控版本演进,不直接改旧响应。不同入口用同一组转换和缺失用例验证。
1.4 DRY 与单一事实来源
合并的依据是“同一件事实、因同一原因变化”。文字相似不算。
我踩过的坑
- 语言列表:YAML 已定义“语言代码 → 展示名称”,Python 又写了一份 allowlist,新增语言时两边容易不一致。
正确理解
- 同一业务分组在接口、模型、查询里手写三份,新增时容易漏改。但“系统支持的全部分组”和“某功能当前允许的分组”是两件事。
- 语言列表能共用真源时,服务端校验用映射 Key,Prompt 或前端展示用 Value。不同 Provider 支持的子集不同,要单独表达,不能为了去重强行合并。
- 先确认重复在哪一层再动手:计算结果重复、数据库记录重复还是 UI 展示重复。业务允许多条时,只在展示层聚合,不改业务算法;发现判断错了及时停下。
1.5 抽象与微服务的时机
先做模块化。确有独立部署、扩容、团队或故障隔离需求,再考虑服务化。
我踩过的坑
- Code Review 建议“抽 Helper、加判空、把三个分支改成映射表”,我分不清这是在修缺陷,还是只让代码看着更专业。
- 拍照识别、食品口述、营养估算、账单分类四种 AI 解析都很慢,我第一反应是新开一个后端服务。
正确理解
- 一次性逻辑写清楚就行,不必提前造工厂和策略注册表。模块职责没理清就拆服务,只是把函数调用变成网络调用。
- 任何新抽象都要回答:它减少了未来哪些真实改动?
- 判断 Review 建议看证据:可复现的错误、字段真实类型契约、第二个实际复用场景、项目当前 MVP 规范。给不存在的分支加吞错兜底会降低可读性。不同意时也要拿出代码和证据,不能只说“不想改”。
- AI 解析慢,先分段测前端防抖、网络、模型推理、JSON 解析、重试与落库的耗时。复用输入校验和结构化结果规范,能用确定性规则分类的先走本地逻辑;几次慢请求不足以支撑新建微服务。
- 真要拆时,先拆发布边界再拆仓库:按“输出是业务判断还是通用结果”判断代码归属;先做到独立镜像、独立部署,接口稳定后再拆仓库。案例见服务拆分与发布。
通用服务的迁移细节(待复习):旧路径、默认值和错误格式可以留在兼容适配层,业务身份不继续渗进通用核心;独立发布与旧调用方迁移分别验收。语言、向量、媒体的具体差异见契约与验收边界。
1.6 设计前确认约束
动手前先问清约束,而不是写完代码再对照原则。关键问题没答案时,先记下来核实。
我踩过的坑
- 2026-09-14:我原先偏重架构与工程判断,说得像“技术不用深学”。现在的想法是技术也要学,重点学为什么这样设计、代价和失效边界。
- 只是想要固定默认参数,却差点做成“实时跨服务自动同步”。
正确理解
- 动手前问清六件事:
- 容量:多少流量、多少数据?
- 数据归属:以哪里为准,哪些不能丢?
- 成本:调用量翻倍,费用和资源扛得住吗?
- 失败与恢复:哪里会出错,怎么恢复或回滚?
- 版本演进:怎样升级不影响老用户?
- 责任边界:谁维护,怎么交接?
- 默认值和实时同步按收益选:只需固定默认参数时,显式设默认值就够;必须实时跨服务一致时,才加同步和失败恢复。先问变化频率、允许延迟和维护成本。
1.7 None 的双重语义
接口不能用同一个值同时表示“没传”和“关闭”。
正确理解
- 陷阱:
schema=None原本表示“没指定,用默认 Schema”,后来又被解释成“明确关闭 Schema”。调用方没变,行为却反了。 - 区分三种状态:使用默认、明确禁用、自定义 Schema。简单情况加显式开关,如
use_default_schema=False;要区分“未传”和“显式传 None”时,用 sentinel 默认值,如_UNSET = object()。参数与开关冲突时的优先级写进契约。 - 兼容测试覆盖三种调用:旧调用不传
schema、新调用显式传None、只换模型或 Provider。格式校验通过,不代表业务语义没变。
来源
旧 Wiki 10-wiki/personal/wiki/concepts/none双重语义与显式开关.md 和历史草稿“Python 中 None 的双重语义与显式开关”。属于通用接口兼容原则,不是特定项目的现行 API。
本章原始笔记
《架构设计原始笔记》 · 架构原则 · 编码规范与最小契约
1.8 AI 可以换操作入口,数据与规则仍须独立(待学习)
我想把饮食、健身交给对话操作,页面看趋势;入口改变不应复制真源。多端整包写入会覆盖 AI 刚记的内容,要一起设计条件写、版本、去重和写后回读。“只吃一半”保留原份量与当前份量,重复请求不能再减半。交付工具不代表客户端身份和执行环境已接通,端到端仍待验收。