软件设计

围绕“公开接口先行、helper 以契约占位、实现围绕不变量展开”这条主线，系统讲解如何从算法题过渡到中型程序设计，并用 LRUCache 与下单流程示例说明它和 DDD 的分工关系。

标题 先定不变量与契约，再写实现：Evans/Fowler 实战法 副标题 / 摘要 很多人理解“先定不变量与契约”时，会觉得只是“多写几行校验”。这篇文章给出更精确的答案：它的本质是固定责任归属，让调用方可以依赖行为语义，而不是猜测实现细节。 目标读者 正在做业务系统设计、代码评审的工程师 觉得“代码能跑，但改需求总出坑”的团队 想把 DDD/契约思想落到日常开发的人 背景 / 动机 常见开发顺序是“先把功能跑通，再补规则”。短期看速度快，长期会出现三个问题： 业务规则散落在多个 service/controller 里 调用方只能通过读实现猜行为 改一个需求会牵动大量分支判断 Evans/Fowler 这一脉的核心不是“写得更学术”，而是先明确系统必须成立的事实，再让实现为这些事实服务。 核心概念 不变量（Invariant）：无论任何路径，始终为真的业务规则。 例如：已支付订单不能再次支付。 契约（Contract）：对外可依赖的行为承诺，至少包含前置条件、后置条件、失败语义。 例如：cancel(order) 只接受可取消状态，成功后状态必须是 CANCELLED，否则抛明确异常。 接口 vs 契约：接口是签名，契约是语义保证。 同一个函数签名，可以有强契约，也可以完全没有契约。 契约分层（建议团队统一术语） 前面的 cancel(order) 示例主要覆盖了行为契约与失败契约。 在真实项目里，建议把契约至少拆成下面 6 类，一起设计： 数据契约：输入/输出的数据形状、类型、取值范围、单位、精度、是否可空。 例：金额必须 > 0，币种必须是 ISO 4217，时间必须是 UTC。 状态契约：状态机允许哪些迁移，不允许哪些迁移。 例：订单只能 CREATED -> PAID -> SHIPPED，不能 SHIPPED -> CREATED。 不变式契约：跨方法、跨状态始终成立的事实。 例：订单总额 = 明细金额之和 + 运费 - 优惠；库存不可为负。 行为契约：调用成功时，调用方可以依赖什么结果与语义。 例：reserve_stock() 成功后，一定返回预留记录 ID，且库存已被占用。 失败契约：违约/异常时返回什么错误、错误是否可重试、是否有副作用残留。 例：重复请求返回 409；超时返回 503 且标记 retryable=true。 副作用契约：方法会修改哪些外部状态（DB、缓存、消息、文件），顺序如何，失败如何补偿。 例：先写 DB 再写 outbox；缓存删除失败不影响主事务提交。 实践指南 / 步骤 先写目的，不写实现 明确本次功能要改变什么业务结果。 列不变量清单 逐条写出“绝对不能被破坏”的规则。 定义契约 为核心行为定义前置条件、后置条件、失败语义，并补齐数据/状态/副作用契约。 再落实现 数据库、框架、缓存、消息等实现细节后置。 用测试锁契约 测试验证的是契约，不是某一版实现细节。 可运行示例 示例 1：无契约（可运行，但语义模糊） class Order: def __init__(self, status): self.status = status def cancel(order: Order) -> Order: if order.status != "CREATED": return order order.status = "CANCELLED" return order if __name__ == "__main__": order = Order("PAID") after = cancel(order) print(after.status) 问题：失败是“静默返回”，调用方必须自己猜“这次到底算成功还是失败”。 ...

副标题 / 摘要 测试不是开发的附属品，而是设计的反馈机制。本文说明“可测试性”如何影响模块边界、依赖方向与结构选择。 目标读者 负责设计模块结构的工程师 想提升测试覆盖与稳定性的开发者 需要制定工程规范的技术负责人 背景 / 动机 当代码难以测试时，往往意味着设计存在强耦合或隐藏依赖。 可测试性是一面镜子，能直接暴露设计问题。 核心概念 可测试性：代码是否能在隔离环境中被验证 依赖注入：把依赖显式传入，便于替换 边界分层：把 IO 与业务逻辑分离 实践指南 / 步骤 把 IO 与业务逻辑拆开 用函数参数或构造函数注入依赖 对外部系统做抽象接口 让核心逻辑保持纯粹、可复用 测试用例优先覆盖核心逻辑 可运行示例 class Repo: def get(self, user_id): return {"id": user_id, "name": "Alice"} class UserService: def __init__(self, repo): self.repo = repo def greeting(self, user_id): user = self.repo.get(user_id) return f"Hello, {user['name']}" class FakeRepo: def get(self, user_id): return {"id": user_id, "name": "Test"} if __name__ == "__main__": service = UserService(FakeRepo()) print(service.greeting(1)) 解释与原理 如果依赖都被隐藏在内部，测试无法替换外部依赖。 通过依赖注入与分层设计，测试可以只关注业务逻辑。 ...

副标题 / 摘要 内聚关注“模块内部是否紧密相关”，耦合关注“模块之间是否依赖过多”。本文给出区别与改进方法。 目标读者 需要评估设计质量的工程师 负责重构与模块划分的开发者 做架构与代码评审的团队 背景 / 动机 很多系统难维护的原因不是“功能太多”，而是模块内聚低、耦合高。 理解内聚与耦合，是设计优化的基础。 核心概念 内聚（Cohesion）：模块内部的相关性 耦合（Coupling）：模块之间的依赖程度 高内聚、低耦合：可维护性最佳 实践指南 / 步骤 识别“职责过多”的模块 拆分低内聚模块 减少跨模块直接依赖 用接口隔离依赖 引入依赖注入 可运行示例 # 低内聚示例：一个类做太多事 class OrderManager: def calculate(self): pass def save(self): pass def send_email(self): pass # 改进：拆分职责 class OrderCalculator: def calculate(self): pass class OrderRepository: def save(self): pass class OrderNotifier: def send_email(self): pass 解释与原理 内聚高意味着模块职责单一、变化集中； 耦合低意味着模块之间依赖少、替换成本低。 常见问题与注意事项 模块越小内聚就越高吗？ 不一定，小但职责混杂仍然低内聚。 完全无耦合可能吗？ 不可能，关键是控制依赖方向与数量。 怎么衡量？ 看模块修改是否牵连多处。 最佳实践与建议 一个模块只解决一个问题 把依赖集中到边界层 用接口隔离变化 小结 / 结论 内聚与耦合是判断设计质量的核心指标。 高内聚、低耦合是长期可维护系统的基础。 ...

副标题 / 摘要 设计关心方案与体验，架构关心结构与演进，功能关心“能做什么”，美学关心“好不好看、好不好用”。本文给出清晰区分与落地方法。 目标读者 负责产品与工程协作的开发者 需要做系统设计的工程师 希望减少沟通成本的团队负责人 背景 / 动机 很多团队在沟通时把“功能、设计、架构、美学”混在一起，导致讨论失焦。 明确它们的职责边界，是跨职能协作的前提。 核心概念 功能（Functionality）：系统能做什么，输出什么结果 设计（Design）：满足需求的方案与交互流程 架构（Architecture）：系统结构、组件边界与可演进性 美学（Aesthetic）：视觉与体验层面的感知质量 实践指南 / 步骤 先定义功能边界：输入/输出与业务规则 再做设计方案：交互流程与用户路径 确定架构结构：模块划分、接口与扩展方式 补齐美学细节：视觉层级与一致性 建立协作节奏：设计评审与架构评审分开 可运行示例 下面用一个简单例子展示“功能 vs 美学”的分离： def calc_total(items): return sum(price for _, price in items) def render_receipt(total, theme="minimal"): if theme == "minimal": return f"Total: {total}" return f"*** TOTAL ***\n{total}\n***********" if __name__ == "__main__": items = [("apple", 3), ("milk", 5)] total = calc_total(items) # 功能 print(render_receipt(total, theme="minimal")) # 美学 解释与原理 功能是“正确性”，设计是“可用性”，架构是“可演进性”，美学是“感知质量”。 把它们混在一起会造成目标冲突、决策混乱。 常见问题与注意事项 美学是不是不重要？ 不是，它影响使用意愿与信任感。 架构是不是过度设计？ 不是，架构关注长期演进与成本控制。 ...

副标题 / 摘要 封装不是“把字段设为 private”，而是建立稳定边界，让变化被隔离。本文解释封装的工程价值与落地方法。 目标读者 写业务系统但经常“改一处坏一片”的工程师 希望提升模块边界设计的开发者 负责代码评审和架构演进的技术负责人 背景 / 动机 没有封装，系统就像没有隔间的办公室：任何一个变化都会影响到其他部分。 封装能让变化局部化、减少耦合、提高可读性与可测试性。 核心概念 信息隐藏：内部实现细节不暴露给外部 稳定边界：对外只暴露行为和契约 高内聚、低耦合：模块内紧密相关，模块间依赖最小 实践指南 / 步骤 先定义对外行为：先有接口，再有实现。 隐藏数据结构：不要让外部直接依赖内部表示。 用方法维护不变量：禁止外部绕过规则直接改数据。 把变化集中在模块内部：外部只看到稳定契约。 为封装加测试：通过行为测试保证边界稳定。 可运行示例 class BankAccount: def __init__(self, balance: int): self._balance = balance def deposit(self, amount: int) -> None: if amount <= 0: raise ValueError("amount must be positive") self._balance += amount def withdraw(self, amount: int) -> None: if amount <= 0: raise ValueError("amount must be positive") if amount > self._balance: raise ValueError("insufficient balance") self._balance -= amount def balance(self) -> int: return self._balance if __name__ == "__main__": acc = BankAccount(100) acc.deposit(50) acc.withdraw(30) print(acc.balance()) 解释与原理 封装的本质是 把“规则”放到模块内部。 外部只调用方法，不触碰内部状态，这样就能保证不变量始终成立。 当实现方式变化时，只要接口不变，外部代码无需调整。 ...