architecture-patternslisted

# 后端架构模式 架构模式是边界和依赖规则，不是固定目录名。先识别业务不变量、变化方向、外部依赖和团队约束，再选择能降低耦合并改善验证的最小结构。任何模式都必须用可检查的依赖、契约和测试证据证明价值。 ## 适用范围与安全门禁 开始前记录仓库 revision、模块/服务范围、业务目标、非功能约束、运行时和部署边界、现有测试、数据迁移限制以及决策人。 - 只读取获授权的代码、配置、架构图和运行证据；报告不复制秘密、客户数据或内部地址。 - 架构建议不等于实现、数据库迁移、依赖升级、流量切换或生产变更授权。 - 如果目标边界、关键调用链、数据所有权或回滚路径不可确认，标记 `BLOCKED`，不要用模式名称掩盖未知信息。 - 先记录现状和证据，再提出目标结构；不以“大规模重写”作为默认方案。 ## 模式选择 | 模式 | 适合解决 | 关键规则 | 常见误用 | | --- | --- | --- | --- | | Clean/Onion | 业务规则需要脱离框架、数据库和交付层验证 | 依赖指向领域/应用内层，外层实现内层定义的接口 | 只改目录，不改变依赖方向 | | Hexagonal | 外部系统多、替换成本高、需要测试替身 | 核心通过 driving/driven ports 与 adapters 交互 | 为每个类机械创建接口 | | DDD bounded context | 术语、规则和数据所有权在子域间不同 | 每个上下文维护自己的模型，通过明确映射协作 | 跨上下文共享实体和数据库表 | | Modular monolith | 需要先治理边界，暂不承担分布式成本 | 模块接口和数据所有权清晰，进程内调用也受契约约束 | 把包名当作边界，任意跨模块读写 | 选择时写出未选模式及原因。若真正问题是查询慢、发布流程或单个缺陷，先解决问题，不要为了“架构完整”引入额外层次。 ## 依赖方向 推荐的最小分层如下： ```text 外部系统 / HTTP / CLI / 消息 / 数据库 ↓ adapters ports + application use cases ↓ domain entities / value objects / policies ``` - **Domain**：实体、值对象、领域服务和不变量；不导入 HTTP、ORM、消息客户端或框架装饰器。 - **Application**：编排用例、事务边界和权限上下文；依赖领域和抽象端口，不依赖具体数据库/网络实现。 - **Ports**：由需要能力的一侧定义最小接口；命名契约、错误、幂等和超时，不隐藏重要副作用。 - **Adapters**：将 HTTP、SQL、队列、第三方 API 和序列化映射到端口；负责技术细节、重试和观测。 依赖必须向内。若内层直接导入外层，记录具体 import/call 证据、产生的耦合和最小隔离方案；不要把“禁止循环依赖”简化为全局静态规则而忽略合法的编译期类型引用。 ## 领域边界与模型 ### Bounded Context 为每个上下文写明：核心能力、拥有的数据、术语、外部协作者、公开契约和不变量。上下文之间通过 ID、DTO、事件或 anti-corruption layer 交换，不共享可变领域实体。 ### 领域对象 - **Entity**：有稳定身份，生命周期内状态可变；身份和不变量由领域负责。 -