模块化单体架构设计方案DDD六边形架构落地实践前言在业务快速迭代的中早期阶段微服务架构往往会带来过高的运维成本、团队协作成本与分布式一致性问题而传统单体架构又容易出现代码腐化、边界模糊、模块耦合严重等问题难以支撑多业务线并行发展。本文档提出模块化单体 DDD领域驱动 六边形架构的组合架构方案既保留单体架构的研发效率、部署简单、调试便捷等优势又通过严格的边界守护、领域划分与分层设计实现高内聚低耦合同时预留完整的演进式拆分路径可随业务规模平滑过渡到微服务架构全程成本可控、收益明确。一、架构总览1.1 核心架构风格本架构核心定位为模块化单体应用同时具备以下核心特性采用无状态设计天然支持单体应用多机部署可无缝适配Serverless部署模式同仓多模块业务域边界清晰支持按需启停与独立部署全程遵循演进式拆分理念无需一次性投入微服务的复杂基建1.2 整体架构模型DDD 六边形架构架构整体采用DDD分层架构与**六边形架构端口-适配器**组合设计以领域层为核心通过端口隔离内外交互所有外部依赖均通过适配器接入保证领域层的纯粹性与可测试性。┌───────────────────────────────────────────────────────────┐ │ 驱动端适配器 (Primary) │ 接入适配层 │ HTTP API / WebSocket / 管理后台 / 定时任务 / 事件订阅 │ 调用系统 ├─────────────┬─────────────────────────────┬───────────────┤ │ │ 应用层 (Application) │ │ │ │ 业务用例编排、事务边界 │ │ │ 端口 ├─────────────────────────────┤ 端口 │ 六边形内核 │ (接口) │ 领域层 (Domain) │ (接口) │ │ │ 实体/值对象/领域服务/事件 │ │ │ │ 仓储接口/外部依赖接口 │ │ ├─────────────┴─────────────────────────────┴───────────────┤ │ 被驱动端适配器 (Secondary) │ 基础设施层 │ 数据库 / 缓存 / 对象存储 / 消息队列 / 第三方SDK │ 被系统调用 └───────────────────────────────────────────────────────────┘1.3 核心设计原则领域优先以业务领域为核心划分边界而非以技术层划分模块单向依赖严格控制依赖方向领域层不依赖任何外部技术框架边界刚性没有自动化校验的边界等于没有边界通过工具强制守护架构边界演进友好所有设计预留拆分空间支持按业务规模逐步拆解不做过度设计高可测试性领域层可脱离框架独立单元测试业务规则验证成本极低二、分层架构详细设计2.1 分层职责与约束架构自上而下分为四层各层职责与约束严格定义如下分层核心职责关键约束接口层接入适配层请求路由、参数校验、DTO转换、权限校验、限流熔断仅作为请求入口禁止包含任何业务逻辑应用层流程编排、事务管理、跨领域模块协调、发布领域事件按业务线独立划分仅做业务流程组装与事务边界控制只编排不决策不包含领域逻辑与业务规则是业务用例的执行者领域层业务规则、领域模型、领域事件、领域服务纯技术无关层不依赖任何外部框架不依赖任何上下层是整个架构的核心基础设施层技术实现、外部服务适配、仓储数据持久化实现、消息发送等所有技术组件数据访问、中间件封装、第三方对接、通用工具的落地实现为领域层提供支持不含业务逻辑2.2 分层依赖规则架构依赖方向严格单向核心规则如下依赖方向唯一接口层 → 应用层 → 领域层 ← 基础设施层基础设施层反向实现领域层定义的接口不形成正向依赖领域层中心原则领域层是架构绝对中心不依赖任何层所有外部资源依赖均通过接口注入必须支持在无任何框架的环境下完成单元测试应用层纯编排应用层不得包含任何业务规则判断所有业务逻辑必须下沉至领域层或领域服务仓储依赖倒置领域层定义抽象仓储接口基础设施层负责仓储接口的具体实现三、架构边界刚性守护体系架构边界必须通过自动化手段强制守护避免人工约束失效导致架构腐化从静态校验、自动化测试、接口控制、流程保障四个维度落地。3.1 静态依赖校验在编译/运行前阻断非法依赖不同技术栈对应实现方案如下3.1.1 Python技术栈实现使用import-linter工具配置模块导入规则在代码提交/构建阶段静态检查模块依赖发现非法导入直接阻断。3.1.2 Java技术栈实现使用maven-enforcer-plugin插件在编译期直接阻断非法模块依赖Spring生态引入Spring Modulith模块验证能力在构建阶段自动验证模块访问合法性3.2 架构自动化测试通过单元测试阶段自动执行架构校验将架构规则融入测试流水线Python项目使用pytest-archon编写架构测试用例验证分层依赖、模块边界每次执行单测自动校验Java项目使用ArchUnit编写架构测试用例验证分层依赖、模块边界、循环依赖每次执行单测自动校验3.3 接口暴露控制每个模块仅暴露公共契约隐藏内部实现从代码层面限制跨模块非法访问Python项目每个模块通过__init__.py的__all__只导出公共接口隐藏内部实现其他模块禁止访问未暴露的内容Java项目每个模块仅暴露api包下的公共接口/DTO/事件internal/domain/infrastructure包下的所有类一律不对外暴露3.4 流程与流水线保障Code Review检查重点检查跨模块查表、绕过服务直接操作数据库、反向依赖等架构违规行为CI/CD集成部署流水线集成架构校验步骤所有架构检查不通过的代码禁止合并与部署四、模块划分规范与目录结构4.1 模块划分核心原则模块划分严格遵循限界上下文原则具体规则如下一个领域一个模块边界清晰高内聚低耦合例如用户、支付、商品、旅游、出行、外卖各为一个独立模块业务线完全隔离旅游、出行、外卖等业务线模块平级互相不可见禁止直接依赖公共能力下沉所有业务线共享的能力必须收敛到核心域模块禁止业务线各自实现核心域无业务感知通用核心模块只提供不可变的基础原子能力场景特定概念由各业务线模块在自己的领域内扩展通过关联字段引用核心实体核心域不感知业务线场景技术实现收敛所有底层技术组件统一收敛到基础设施层不允许业务模块自行实现数据库操作、第三方调用按限界上下文划分而非前后台分层每个模块都有自己的完整分层前台业务模块的领域层负责场景特定概念中台核心模块的领域层负责通用原子能力粒度适中避免过度拆分过细拆分模块会显著增加工程复杂度与协调成本若两个模块始终同步变更如用户与认证应允许合并为一个模块而非强行维持独立边界4.2 模块分类与定位模块分为两大类定位明确权责清晰业务线模块/前台业务模块面向具体业务场景包含完整的分层结构领域层聚焦场景特定业务规则例如旅游、出行、外卖、AI助手通用核心模块/中台能力模块提供通用原子能力领域层更厚被所有业务线模块依赖例如用户、支付、订单中心4.3 Python项目标准目录结构backend-python/ ├── framework/ # 公共框架统一响应、异常处理器、通用插件等 ├── server # 启动入口 │ ├── .env.example # 环境变量示例 │ ├── worker_main.py # 异步任务Worker独立入口同仓不同部署资源隔离 │ └── main.py # Web服务主入口路由聚合、模块加载、依赖注入容器初始化 ├── adapters/ # 【驱动端适配器 / 接入适配层】Primary Adapter │ │ # 业务线模块/前台业务模块完整模块有自己的领域层 ├── travel/ # 旅游业务 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── ride/ # 拼车业务 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── delivery/ # 外卖业务 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── ai_assistant/ # AI助手业务 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 │ │ # 通用核心模块/中台能力模块完整模块领域层更厚 ├── user/ # 用户领域模块业务中台中心域提供通用原子能力 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── payment/ # 支付领域模块业务中台中心域提供通用原子能力 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── order/ # 订单中心领域模块业务中台中心域提供通用原子能力 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 └── requirements.txt # Python 依赖4.4 Java项目标准目录结构backend-java/ ├── framework/ # 公共框架统一响应、异常处理器、通用插件等 ├── server/ # 启动入口 │ └── src/main/java │ └── com/company/platform/ │ └──Application.java ├── adapters/ # 【驱动端适配器 / 接入适配层】Primary Adapter │ │ # 业务线模块/前台业务模块完整模块有自己的领域层 ├── travel/ # 旅游业务 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── ride/ # 拼车业务 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── delivery/ # 外卖业务 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── ai_assistant/ # AI助手业务 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 │ │ # 通用核心模块/中台能力模块完整模块领域层更厚 ├── user/ # 用户领域模块业务中台中心域提供通用原子能力 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── payment/ # 支付领域模块业务中台中心域提供通用原子能力 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 ├── order/ # 订单中心领域模块业务中台中心域提供通用原子能力 │ ├── api/ # 模块唯一对外出口端口 │ │ ├── event/ # 本模块发布的领域事件 │ │ ├── dto/ # 接口交互实体定义 │ │ └── interface/ # 本模块暴露的接口供其他模块或适配器调用 │ └── internal/ # 内部实现外部禁止访问 │ ├── application/ # 领域内应用服务仅操作自身域 │ ├── domain/ # 领域实体、值对象、领域服务、仓储接口 │ └── infrastructure/ # 仓储实现、ORM、第三方对接 └── pom.xml # Maven依赖管理五、核心运行机制5.1 多维度按需启停架构支持三级粒度的按需启停适配多业务线差异化运营需求支持系统级、模块级、接口级别按需启停适配多业务线逐步上线、差异化部署、灰度发布等场景配置支持热加载启停无需重启服务5.2 异步任务设计异步任务采用同仓异构部署模式兼顾研发效率与资源隔离代码同仓异步任务代码与主应用在同一仓库共享应用层与领域层代码避免重复开发可独立部署计算密集型/耗时任务可独立部署实现资源隔离无需拆分服务自动按需启用根据关联模块启动配置自动按需启用对应任务无需单独配置控制主应用启动时可提示当前依赖的任务列表5.3 模块间交互规则5.3.1 交互总原则业务线模块之间一般情况下禁止横向调用完全隔离若需跨业务数据交互可通过公共核心域中转或通过领域事件解耦特殊场景下当页面组装逻辑过于复杂时允许业务线模块依赖其他业务线模块的Query Service只读服务但禁止调用任何命令/写操作且Query Service只能返回扁平DTO不能暴露领域实体5.3.2 模块依赖关系规范业务线模块/前台业务模块允许依赖通用核心模块/中台能力模块业务线模块/前台业务模块之间绝对禁止依赖通用核心模块/中台能力模块之间可以有向无环依赖禁止循环依赖模块之间只能依赖接口不能依赖具体实现领域实体禁止跨模块传递必须转换为DTO后交互5.3.3 通信方式选型同步调用API仅用于强依赖、强一致性场景异步事件通知用于弱依赖、最终一致性场景优先推荐5.3.4 领域事件规范事件Schema属于发布方的业务契约应放在发布方模块的api/event/目录下消费者只依赖事件Schema不依赖发布方的其他内部实现5.3.5 跨模块事务处理根据架构演进阶段采用不同方案L0-L1单库阶段允许通过共享事务管理器实现跨模块本地事务但必须在应用层显式声明禁止在领域层直接操作其他模块的表即使同事务L2多进程阶段强一致性场景必须使用 Saga 编排 / TCC 框架推荐优先使用异步事件实现最终一致性六、数据架构设计6.1 单库分域设计采用物理同库、逻辑隔离的数据库设计方案统一使用领域表前缀实现逻辑隔离例如user_xxx、order_xxx设计上严格按照分库标准执行预留未来拆库的所有条件避免跨域表关联、跨域外键等设计为后续物理拆库扫清障碍6.2 跨域数据查询规范禁止跨域操作数据表任何情况下不允许SQL层面跨域关联查询禁止绕过仓储直接写SQL所有数据库操作必须通过仓储层封装禁止在业务代码里直接写ORM查询小数据量场景应用层调用多个领域服务获取数据在内存中组装后返回大数据量/复杂查询/聚合统计场景通过冗余宽表实现例如订单统计、业务报表通过领域事件同步数据到独立的查询宽表/数仓专门用于查询高实时性大数据量场景采用物化视图或独立查询服务根据业务演进逐步引入性能优化手段读请求走只读实例热点数据走缓存从性能层面缓解单库压力无需急于拆库6.3 缓存设计规范缓存抽象层在framework或基础设施层提供统一缓存接口如CacheService屏蔽底层缓存实现缓存按域隔离按领域模块划分缓存命名空间例如travel:*、order:*避免key冲突缓存一致性策略优先采用 Cache-Aside 模式读时回源写时删除缓存禁止在领域层直接操作缓存必须通过仓储层封装跨模块缓存失效通过监听领域事件异步清除关联模块的相关缓存七、统一技术底座规范7.1 四大基础统一规范所有模块必须遵循统一技术底座避免各业务线重复造轮子与规范不一致统一异常体系统一日志规范统一配置管理统一接口返回格式7.2 安全与合规体系数据脱敏用户隐私数据手机号、身份证等入库加密、出参脱敏支持可搜索加密如确定性加密技术脱敏通过注解序列化器统一处理避免业务代码侵入支付合规支付域单独管控流水记录完整敏感操作全量日志留痕满足金融监管要求操作审计管理后台所有关键操作留痕核心数据变更记录操作人、操作时间、变更内容7.3 日志与可观测性日志按模块打标便于按域排查问题请求全链路日志支持一键开启/关闭全链路TraceId支持贯穿所有模块与异步任务可按模块、接口粒度开启/关闭日志灵活控制日志量级八、全链路测试体系8.1 测试分层策略单元测试聚焦领域层业务规则覆盖核心业务逻辑可脱离框架独立运行集成测试验证应用层流程编排合理性、事务边界正确性、仓储层数据访问正确性、领域事件发布时机准确性架构测试防止架构腐化通过自动化用例强制校验架构规则端到端测试覆盖核心业务主链路验证整体流程可用性8.2 架构测试检查清单架构测试必须覆盖以下核心校验项接口层不依赖领域层和基础设施层只能依赖应用层接口领域层不依赖任何外部框架、数据库、ORM组件业务线模块之间无任何依赖所有模块的internal包不被其他模块导入仓储实现仅存在于基础设施层禁止循环依赖包括通用核心模块之间应用层不包含领域逻辑可结合命名规范辅助检查如 ApplicationService 中不出现业务判断关键词事务注解只能出现在应用层权限注解只能出现在接口层九、工程落地最佳实践9.1 事务管理规范精挑细选事务隔离级别根据业务场景合理选择明智选择锁策略避免过度加锁导致性能问题严格控制事务范围事务要“短小精悍”避免长事务核心场景如库存扣减、支付流转事务逻辑必须严谨防止并发问题9.2 依赖注入实现Java技术栈Spring生态天然支持依赖注入通过注解完成Bean管理与注入Python技术栈使用dependency-injector框架实现依赖注入容器完成各层依赖的解耦与管理十、部署架构无状态设计所有服务实例无状态天然支持水平扩展多部署形态支持支持单/多Docker容器部署、ECS部署、Serverless部署按需部署支持按模块选择启用部署不同环境可部署不同模块组合十一、演进式拆分体系模块化单体的拆分不是「要么单体要么微服务」的二元选择而是按「部署维度 → 运行时维度 → 数据维度」逐层拆解哪一层出问题拆哪一层每一步都成本可控、收益明确且全程保留单体的研发效率优势。11.1 三维拆分路径拆分维度核心动作解决的核心问题架构复杂度增量部署维度同代码、同库按业务 / 模块拆分部署集群网关分流资源争抢、模块间互相影响、独立扩缩容极低纯运维操作零代码改动运行时维度同库按领域拆分为独立进程通过 RPC/HTTP 通信发布隔离、故障隔离、团队协作冲突中等需做接口改造无分布式事务难题数据维度按领域拆库服务完全独立数据源单库性能瓶颈、数据隔离合规要求高需解决分布式一致性、数据同步11.2 五级拆分阶梯阶梯架构形态核心特征适用阶段L0 模块化单体单部署集 单进程 单库所有模块跑在同一个实例共用数据库0-1 万日活业务验证期L1 部署集拆分多部署集 单代码 单库同一份代码部署多个集群按接口/模块分流资源隔离1-10 万日活出现模块资源争抢L2 进程级拆分分布式单体多进程 单库核心模块拆为独立进程通过轻量 RPC 通信数据库共用10-50 万日活发布 / 故障隔离需求强烈L3 数据级拆分多进程 多库核心领域拆独立数据库服务间数据物理隔离50 万 日活单库出现性能瓶颈L4 完整微服务全服务化 服务治理完整的注册中心、配置中心、链路追踪、分布式事务体系百万级日活团队规模 50十二、架构契约与落地保障架构设计需形成完整的契约文档作为所有研发人员的开发准则AI编码工具需严格按照架构契约执行开发保证代码生成符合架构规范架构契约迭代需经过评审同步更新所有自动化校验规则避免契约与实现脱节总结本架构方案的核心价值在于平衡当下研发效率与未来架构扩展性既避免了微服务早期的过度设计与高成本又通过严格的边界守护与领域划分解决了传统单体的腐化问题。对于多业务线并行发展、处于快速成长期的团队模块化单体是性价比极高的架构选型可伴随业务规模平滑演进始终匹配当前阶段的研发与运维能力。
)
