Dujiao-Next 架构深度剖析:垂直切片模块化单体与五层依赖规则完整指南
Dujiao-Next 架构深度剖析:垂直切片模块化单体与五层依赖规则完整指南
Dujiao-Next 是一套开源的数字商品电商平台,包含 Go 后端、用户商城前台和管理后台。本文带你做一次 Dujiao-Next 架构深度剖析:它的垂直切片模块化单体是如何组织的、五层依赖规则如何工作,以及这些规则是如何被架构守护测试强制执行的。无论你是想读懂大型 Go 项目,还是想为自己的项目设计分层规范,这份指南都能直接套用。
Dujiao-Next 是什么:一张架构图就能看懂的业务面
Dujiao-Next 覆盖数字商品电商的完整链路:商品目录与 SKU、购物车与下单、多渠道支付、礼品卡、分销/联盟、代理(reseller)体系、钱包与对账,外加一个功能完整的管理后台。
技术栈选型非常务实(摘自 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/ |
应用层依赖的端口接口 + 模块对外表面 | 无 |
翻译成大白话就是五条铁律:
- domain 是最纯净的:不能反向依赖 application、infrastructure、transport,保证业务规则可独立测试;
- 用例里不许出现框架:application 层禁止 import Gin 和 asynq,HTTP 细节和任务调度细节统统留在外面;
- GORM 只能存在于
infrastructure/gormstore:其他任何位置出现gorm.io/都是违规; - Handler 只面向契约:transport 依赖 application 契约接口,绝不直接引用具体 Store;
- 底座不反向依赖:
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 架构
- 看地图:从 README.md 的 "Architecture" 一节开始,再对照
internal/modules/下的 35 个目录; - 拆一个模块:挑最简单的 internal/modules/sitemap/(只有 5 个文件)走一遍五层结构,再回头看复杂的 internal/modules/order/;
- 跑守护测试:
go test ./internal/architecture/...,然后翻 internal/architecture/dependencies_test.go 里的用例表——它等于这份项目的"架构说明书",每条违规理由都是一句可读的人话。
总结:这套架构给你三件事
- 可预测的目录结构:任何模块打开都是同样的五层,新人零学习成本;
- 机器可验证的纪律:依赖规则是测试而不是文档注释,CI 跑一遍就知道谁在"抄近道";
- 单体成本、微服务潜力:垂直切片让模块随时可拆,而今天只需维护一个二进制。
如果你的团队正在把单体项目拆出模块边界,Dujiao-Next 的 internal/architecture/ 目录值得整段抄走——让规则活下来最可靠的方式,就是让它成为每次构建的一部分。
