Dujiao-Next 架构深度剖析:垂直切片模块化单体与五层依赖规则完整指南

原创2026-10-11 15:29:031,396 阅读

Dujiao-Next 架构深度剖析:垂直切片模块化单体与五层依赖规则完整指南

Dujiao-Next 是一套开源的数字商品电商平台,包含 Go 后端、用户商城前台和管理后台。本文带你做一次 Dujiao-Next 架构深度剖析:它的垂直切片模块化单体是如何组织的、五层依赖规则如何工作,以及这些规则是如何被架构守护测试强制执行的。无论你是想读懂大型 Go 项目,还是想为自己的项目设计分层规范,这份指南都能直接套用。

Dujiao-Next 是什么:一张架构图就能看懂的业务面

Dujiao-Next 覆盖数字商品电商的完整链路:商品目录与 SKU、购物车与下单、多渠道支付、礼品卡、分销/联盟、代理(reseller)体系、钱包与对账,外加一个功能完整的管理后台。

Dujiao-Next 数字商品电商平台业务总览:覆盖电商交易链路的数字服务平台

技术栈选型非常务实(摘自 README.md):

层 技术
后端 Go 1.26 · Gin · GORM · SQLite / PostgreSQL
认证 JWT(admin/user 双域分离)· Casbin RBAC · TOTP 二次验证
异步 asynq + Redis(可选,无 Redis 也能跑)
前端 Vue 3 · Vite · TypeScript · Tailwind CSS

单二进制部署是它的一大卖点:fullstack 构建标签会把两个前端 SPA 通过 go:embed 打进 Go 二进制,一个容器搞定整个站点(见 Dockerfile 与 config.yml.example)。

仓库全局视图:三大板块各司其职

先建立地图感。仓库顶层结构如下:

dujiao-next
├── cmd/server/          # 程序入口,含 admin 运维子命令
├── internal/
│   ├── app/             # 组合根:DI 容器、Gin 路由、asynq worker
│   ├── bootstrap/       # 每个模块的装配代码(wiring.go + adapters.go)
│   ├── modules/         # 35 个业务模块,一个领域一个垂直切片
│   ├── workflows/       # 跨模块用例(如礼品卡兑换)
│   ├── platform/        # 面向框架的基础设施:DB 连接、HTTP 响应封装
│   ├── shared/          # 零依赖原语:money、jsonmap、serial…
│   ├── authz/           # Casbin RBAC 策略与内置角色种子
│   └── architecture/    # 架构守护测试——只检查规则,不含生产代码
└── frontend/
    ├── user/            # 商城前台 SPA
    └── admin/           # 管理后台 SPA

关键点只有一个词:internal/modules/。数一下目录,里面正好有 35 个业务模块——order、payment、cart、catalog、reseller、wallet、giftcard、affiliate、auditlog……每个目录就是一个自成一体的垂直切片。

垂直切片:一个模块长什么样?

以订单模块 internal/modules/order/ 为例,它是教科书式的垂直切片结构:

internal/modules/order/
├── domain/             # Order、OrderItem 等实体与值对象,纯业务不变量
├── application/        # 用例:创建订单、退款、批发价计算等
├── contract/          # 端口接口 + 模块对外的公共表面
├── infrastructure/
│   ├── gormstore/      # GORM 存储适配器(整个模块里唯一能碰 GORM 的地方)
│   └── queueadapter/   # 队列适配器
├── integrationtest/    # 黑盒集成测试
└── transport/
    ├── http/           # Admin/User/Guest 等 HTTP Handler
    └── presenter/      # 响应模型转换

和常见的"全项目统一分 service 层 / repository 层"的横向分层不同,垂直切片把一个领域的所有代码纵向堆叠在一起:改订单退款逻辑时,domain、应用服务、存储、HTTP 入口全在同一个目录树下,新人不用在几个包之间来回跳。这也是"模块化单体"里"模块化"三字的真正含义——将来任何一个模块都能被原样拆出去成为独立服务,因为它没有横向渗透别人的内部实现。

五层依赖规则:谁可以依赖谁

每个垂直切片内部有五个"层"(目录),依赖方向被严格规定:

层 职责 允许 import
domain/ 实体、值对象、业务不变量 其他层一律不许
application/ 用例、端口接口 domain、contract
infrastructure/ GORM 存储、网关、队列适配器 domain、application 的端口
transport/ HTTP Handler、Presenter 仅 application 的契约
contract/ 应用层依赖的端口接口 + 模块对外表面 无

翻译成大白话就是五条铁律:

  1. domain 是最纯净的:不能反向依赖 application、infrastructure、transport,保证业务规则可独立测试;
  2. 用例里不许出现框架:application 层禁止 import Gin 和 asynq,HTTP 细节和任务调度细节统统留在外面;
  3. GORM 只能存在于 infrastructure/gormstore:其他任何位置出现 gorm.io/ 都是违规;
  4. Handler 只面向契约:transport 依赖 application 契约接口,绝不直接引用具体 Store;
  5. 底座不反向依赖:internal/platform 不许依赖业务模块,internal/shared 保持零依赖(不许碰 GORM、Gin、asynq 和任何模块)。

亮点:规则由测试强制执行,而非口头约定

这是 Dujiao-Next 最值得学习的设计:架构规则写成了测试。internal/architecture/ 目录下没有任何生产代码,只有一个"依赖警察"。

核心实现在 internal/architecture/dependencies_test.go:它用 Go 标准库解析 internal/modules、workflows、platform、shared 下每一个 .go 文件的 import 列表,逐条比对规则,发现违规就报测试失败。规则函数 validateImport 里的判断直接对应上面五条铁律,比如:

  • application 层 import 了 gin 或 asynq → 报 "application code must not depend on HTTP or job transport libraries"
  • 非 gormstore 文件 import 了 gorm.io/ → 报 "only a module's store/gormstore adapter may import GORM"
  • domain import 了 application/infrastructure/transport → 直接违规

这套测试还内置了大量用例表(TestValidateImportRules),用订单、内容、dashboard 等模块的真实路径做正反例验证;reseller_vertical_slice_test.go 甚至会检查 reseller 模块的目录与类型声明是否符合切片结构。

想亲眼验证?克隆仓库后一条命令:

git clone https://gitcode.com/gh_mirrors/du/dujiao-next
cd dujiao-next
go test ./internal/architecture/...

全绿,说明整棵代码树的依赖方向没有任何"走捷径"的地方。

模块之间怎么说话:contract 契约 + bootstrap 装配

垂直切片之间从不互相 import 内部实现,只通过各自的 contract/ 层交互。而把各方"接上线"的装配代码,集中放在 internal/bootstrap/,每个模块一个目录(如 internal/bootstrap/order/wiring.go)。

看订单的装配就能体会这个设计:New(c *container.Container) 里,Handler 拿到的不是别家模块的真实 Store,而是一层薄薄的适配器——orderAdminCouponAdapter 包着容器里的 CouponRepo,orderUserPaymentChannelAdapter 包着 PaymentService。依赖注入的总装点在 internal/app/container/,它在启动时按顺序构建所有服务并存进容器,bootstrap 再从容器里取料、注入到各模块的 Handler。

好处很直接:

  • 循环依赖无处发生:模块 A 只认识 A 自己 contract 里定义的端口接口;
  • 改实现不传染:换掉优惠券的存储实现,只有 bootstrap 一处要动;
  • 跨模块的复杂用例(如礼品卡兑换、结账)则放进 internal/workflows/,同样遵守"application 只依赖契约"的规则。

顺手一瞥:权限体系同样被"守护测试"盯住

架构治理不止管 import。所有 /api/v1/admin/... 路由都会经过 Casbin(策略模型与内置角色种子在 internal/authz/bootstrap.go),而 internal/app/httpserver/rbac_coverage_test.go 会校验每一条已注册路由都被角色权限覆盖——新增管理路由却忘了挂到任何角色,测试就会提醒你。规则和路由表一样,都是"以测试为准"。

上手清单:三步读懂 Dujiao-Next 架构

  1. 看地图:从 README.md 的 "Architecture" 一节开始,再对照 internal/modules/ 下的 35 个目录;
  2. 拆一个模块:挑最简单的 internal/modules/sitemap/(只有 5 个文件)走一遍五层结构,再回头看复杂的 internal/modules/order/;
  3. 跑守护测试:go test ./internal/architecture/...,然后翻 internal/architecture/dependencies_test.go 里的用例表——它等于这份项目的"架构说明书",每条违规理由都是一句可读的人话。

总结:这套架构给你三件事

  • 可预测的目录结构:任何模块打开都是同样的五层,新人零学习成本;
  • 机器可验证的纪律:依赖规则是测试而不是文档注释,CI 跑一遍就知道谁在"抄近道";
  • 单体成本、微服务潜力:垂直切片让模块随时可拆,而今天只需维护一个二进制。

如果你的团队正在把单体项目拆出模块边界,Dujiao-Next 的 internal/architecture/ 目录值得整段抄走——让规则活下来最可靠的方式,就是让它成为每次构建的一部分。

登录后查看全文
dujiao-next