hyperf 业务架构与领域边界治理

业务架构与领域边界治理，就是先把“谁该做什么、谁不该做什么”切清楚，再用契约把服务之间的合作固定住。 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 技术选型再好，边界乱了，最后一定变成“互相调用、互相改库、互相背锅”。 --- 下面给你一套 Hyperf 场景可落地、最完整的“从0到1”方法。 ---1. 先理解你到底在治理什么（大白话版） 你要治理3件事：1. 领域拆分：业务按职责拆成块（订单、支付、库存、会员）2. 边界管理：每块只管自己的事，不越界3. 契约稳定：上下游怎么合作，规则写死，不能口头约定 可以把它理解成小区物业： - 每栋楼有自己的物业（领域） - 物业不能跑去管隔壁楼的电梯（边界） - 业主报修流程固定（契约） ---2. 先给系统画“业务地图”（不是先拆微服务） 先别急着拆服务，先做 领域地图： - 核心域：最能体现你公司竞争力的（比如定价引擎、风控） - 支撑域：支撑核心域（比如订单履约） - 通用域：大家都差不多的（短信、文件、通知） 输出物（必须有） - 业务能力清单（Capability List） - 每个能力的 Owner（业务 + 技术） - 能力之间输入输出（谁依赖谁） ---3. 边界怎么切才不烂（最实用的7条规则）1. 一个领域一个“真相源” 订单状态只能订单域说了算，别的域只能“引用”。2. 一个数据主权一个库 禁止跨域直接改别人表。只能走 API/事件。3. 跨域只传“结果”，不传“内部过程” 例如支付域告诉你“支付成功”，不要让订单域知道支付内部风控细节。4. 读写分离责任清晰 写操作只能打到所有者域，读可以做投影/缓存。5. 共享代码最小化 共享工具可以，共享业务逻辑不行。6. 跨域调用默认不信任 有超时、重试、幂等、熔断。7. 组织边界跟系统边界一致 谁负责哪个域，代码仓、告警、发布都对齐。 ---4. 上下游契约怎么定（稳定合作的核心） 契约有3种：1. 同步契约（HTTP/gRPC）：请求响应格式、错误码、时延目标2. 异步契约（MQ 事件）：事件名、字段、版本、幂等键3. 数据契约（报表/数据平台）：字段含义、口径、刷新时效 契约必须写清楚的字段 - version（版本） - required/optional 字段 - 语义（状态含义） - 错误码与重试语义 - SLA/SLO（可用性、延迟） - 变更兼容策略（向后兼容多久） ---5. Hyperf 里怎么落地到代码结构（最关键） 按 限界上下文（Bounded Context） 组织，不按技术层乱堆。 示例目录（单仓多上下文）： app/ Order/ Domain/# 实体、值对象、领域服务Application/# 用例编排Infrastructure/# Repo实现、RPC/MQ适配Interfaces/# Controller/ConsumerPayment/ Inventory/ 规则 - Order 不能直接importPayment.Domain - 跨域访问只能走 Interfaces 暴露的契约（API/事件） - 每个上下文自己的 migrations 和 repository - 共享只允许 SharedKernel 里的“无业务语义”组件（日志、ID、时间） ---6. 防腐层（ACL）一定要有 外部系统字段常常很脏、很乱。 不要把外部模型直接带进核心域。 做法： - 在 Infrastructure/Adapter 把外部 DTO 转成内部模型 - 外部字段变化只影响适配层，不污染核心域 这就是“隔离变化源”。 ---7. 边界治理流程（完整流程） 阶段 A：建模（1-2 周）1. 事件风暴（业务+技术一起）2. 列出核心命令、事件、聚合3. 划定上下文边界4. 定 Owner 和 SLA 产出：领域地图 + 上下文关系图 + 初版契约清单 阶段 B：契约固化（1-2 周）1. API 契约（OpenAPI/Proto）2. 事件契约（Schema Registry）3. 错误码规范4. 兼容策略（v1/v2 生命周期） 产出：契约仓库、版本策略、兼容检查规则 阶段 C：代码重构（2-6 周）1. 按上下文拆目录/模块2. 封禁跨域直连 DB3. 增加防腐层4. 补齐幂等、超时、重试、熔断 产出：边界内聚、跨域可控 阶段 D：治理上线（持续）1. PR 模板要求标明“影响上下文”2. 架构评审必须检查边界是否被破坏3. CI 做契约测试、兼容测试4. 每月边界健康巡检 ---8. CI/CD 门禁（不自动化就会失效） 发布前必须过： - 契约测试：消费者和提供者都通过 - 破坏性变更检查：字段删除、类型变更直接阻断 - 跨域依赖检查：禁止非法import/ 直连他域库 - 数据主权检查：跨域写库阻断 - SLO 检查：关键调用链性能退化阻断 ---9. 常见反模式（看到就改）1. “用户中心”变成万能中心（什么都放）2. 共用一套大表，所有服务都在改3. 同步调用链过长（A->B->C->D->E）4. 事件没有版本，改字段就炸5. 共享 SDK 塞业务逻辑6. 一个需求跨5个域都要改代码（边界明显有问题） ---10. 怎么判断边界切得好（量化指标） - 跨域同步调用次数下降 - 一次需求平均改动上下文数下降 - 跨团队联调时长下降 - 线上“字段变更导致故障”下降 - 核心域迭代速度上升 - 回滚影响范围变小 ---11. 给你一个最实用的90天执行计划0-30 天 - 完成领域地图与上下文划分 - 定3条核心链路契约 - 建立“禁止跨域改库”规则31-60 天 - 选1个最痛链路做试点重构（例如订单-支付） - 上契约测试和兼容检查 - 建防腐层，清理直连调用61-90 天 - 扩到核心服务群 - 评审流程和 CI 门禁固化 - 发布边界健康报告（每月） ---12. 最后一句大白话 边界治理不是“把服务拆小”，而是“把责任切清、把协作写成契约、把违规变成无法合并”。 在 Hyperf 里，只要你把“上下文目录 + 契约测试 + 跨域门禁”三件事做实，架构会稳定很多，后续扩展和重构都会轻松很多。