如何快速扩展业务模块:go-admin-core 订单应用 app-order 从 0 到集成完整实战
如何快速扩展业务模块:go-admin-core 订单应用 app-order 从 0 到集成完整实战
使用 go-admin-core 扩展业务模块,比想象中简单:照着仓库里的
app-order订单示例,从模型、迁移到路由接线,30 分钟就能把一个可上线的订单应用集成进 go-admin。
go-admin 是基于 Gin + Vue 的前后端分离权限管理系统脚手架,内置多租户、JWT 鉴权、RBAC、代码生成器与定时任务。而从 v2 开始,更值得关注的变化是:业务模块可以脱离主仓库、只依赖 go-admin-core 独立开发,再像"插件"一样装回宿主系统。
仓库里就放了一个完整示范——example/app-order/(下称 app-order 订单应用),它自带两张表、一套菜单种子、四个接口,从建表到管理后台露出全流程可跑通。本文带你从零读懂它、再到集成的关键三步。
🧩 为什么用 app-order 学扩展,而不是抄代码生成器?
代码生成器能生成标准 CRUD,但真实业务往往有:
- 跨表事务(下单时订单行 + 明细必须同时写入)
- 状态机 + 并发防护(付款只能对"待支付"订单生效,且不能被并发重复支付)
- 数据权限(不同角色只能看到自己部门/本人的数据)
app-order 恰好把这三类"生成器给不了"的逻辑都手写了出来,是最有参考价值的扩展模板。
模块结构一览(每个目录职责清晰):
example/app-order/
├── models/ # 数据模型:订单 + 订单明细
├── service/ # 业务逻辑:事务、并发防护、数据权限
├── apis/ # HTTP 接口层(4 个手写 handler)
├── router/ # 路由注册 + 鉴权/角色/数据权限中间件
├── migration/ # 数据库迁移 + 菜单/API 种子
└── go.mod # 只依赖 go-admin-core,不依赖主仓库
注意 go.mod 里只 require 了 go-admin-core/v2 与 Gin、GORM——这就是"独立应用"的核心含义:你的模块不需要知道 go-admin 主仓的任何内部结构。
1️⃣ 应用清单:先告诉宿主"我是谁"
扩展的第一步不是写表,而是 migration/manifest.go。它在包 init() 里向 core 注册一份 app.Manifest:
Code: "order"—— 应用唯一编码,后端路由、前端菜单、迁移命名空间全靠它;Version—— 宿主安装器用它判断"升级还是降级",并在migrate status中展示;Requires—— 可声明依赖的其他应用,宿主会拒绝安装未满足依赖的应用。
💡 一句话记忆:manifest 是应用的"身份证",迁移版本是"病历",两者各自独立演进。
2️⃣ 数据模型:三个容易踩的坑都替你踩了
看 models/order.go,两个字段设计值得新手直接抄:
坑 1:表名千万别叫 order
Order 模型的 TableName() 固定返回 app_order。因为 SQL 里 order 是保留字,而数据权限拼 WHERE 时是直接字符串拼接表名的,叫 order 会导致所有数据权限查询直接报语法错误——core 不会帮你检查,这是调用者的责任。
坑 2:ControlBy 不是装饰,是数据权限的"钩子"
模型内嵌了 contractmodels.ControlBy。go-admin 的五档数据权限(全部 / 本部门 / 本部门及子部门 / 仅本人等)全部基于 create_by 字段过滤,这个机制的完整语义见 docs/architecture.md 的 DataScope 一节。不参与数据权限的表可以不加;想让角色"只看到自己的订单",就必须加。
坑 3:状态用窄字符串而非 int 枚举
StatusPending = "1" / StatusPaid = "2",与 core 中 sys_role.data_scope 的约定保持一致,未来加"已取消"等状态不需要改表结构。
3️⃣ 服务层:事务与并发防护的标准写法
service/order.go 是全文含金量最高的文件,两个模式建议新手重点学习:
✅ 跨表事务:订单行 + 明细同生共死
err := e.Orm.Transaction(func(tx *gorm.DB) error {
if err := tx.Create(order).Error; err != nil { return err }
if err := tx.Create(&items).Error; err != nil { return err } // 一次批量写
return nil
})
用 GORM 的闭包式 Transaction,panic 时也会自动回滚再重新抛出;且明细是一次批量写入,任一行冲突整单回滚,不会出现"订单写了一半"的脏数据。
✅ 并发付款:把防线放在 WHERE 里
付款接口不是"先查再改",而是一条条件更新:
Where("id = ? AND status = ?", id, StatusPending).
Updates(map[string]interface{}{"status": StatusPaid})
然后看 RowsAffected:等于 1 才算成功,等于 0 就返回"订单不可支付"。两个请求同时付款,只有一个能翻动这一行——不加锁也能防重复支付。更巧妙的是,"订单不存在"、"已支付"、"不在你的数据权限内"三种情况统一返回同一个 409 错误,避免向越权者泄露订单号是否存在。
4️⃣ 迁移:建表 + 菜单/API 种子一次完成
example/app-order/migration/migration.go 通过 contractmigration.ForApp("order").SetVersion(version, createOrderSchema) 注册迁移,在一个事务里完成三件事:
- AutoMigrate 建出
app_order、app_order_item两张表; - 种子菜单与 API:目录 → 列表页 → 两个按钮(新建/付款),以及 4 条 API(列表/详情/创建/付款)。宿主 Seeder 会把这些规格翻译成
sys_menu/sys_api/sys_menu_api_rule行,管理员在后台授权给角色后自动生成 casbin 规则; - 写入迁移版本记录(
order-<version>,应用级命名空间,不会和框架自己的迁移撞车)。
两条新手必看的规则:
- 迁移版本号是 13 位毫秒时间戳,按文件名升序执行、只执行一次,已执行的迁移文件不可修改,要改就新建一个迁移;
- 前端菜单的
Component必须以apps/<code>/开头(示例中是apps/order/order/index),写成/order/index会让前端去src/views/下找组件,页面直接落到"应用未安装"占位页,而控制台报错信息还会误导你——这条规则详见 docs/contract.md。
5️⃣ 路由:三层中间件,一层都不能少
example/app-order/router/router.go 的 RegisterRouter(v1, authMiddleware) 把四条路由挂到 /api/v1/order 下:
| 路由 | 方法 | 中间件 |
|---|---|---|
GET /order |
分页列表 | JWT + Casbin 角色 + 数据权限 |
GET /order/:id |
订单详情(含明细) | 同上 |
POST /order |
创建订单 | JWT + Casbin 角色 |
PUT /order/:id/pay |
付款 | 同上 |
三层防护各有分工:JWT 确认"你是谁",Casbin 角色校验确认"你的角色能不能调这个接口",actions.PermissionAction() 把当前用户的数据权限档位存进上下文、供 Service 查询时拼 WHERE。
还有个值得学习的防御性细节:如果宿主没注册角色校验中间件,RegisterRouter 会直接 panic 拒绝启动,而不是静默地给所有登录用户开放订单接口——"宁可启动失败,不可越权放行"。
6️⃣ 集成到 go-admin:两处空导入 + 一次验证
把 app-order 装进宿主,后端只需要接两处线(详见 docs/contract.md 的"装一个应用要接两处线"):
① 路由:在 cmd/api/ 下新建一个文件,空导入 router 包并把其注册函数加入 AppRouters。主仓自带模块的写法可参照 cmd/api/demo.go:
import _ "example/app-order/router"
func init() {
AppRouters = append(AppRouters, router.RegisterRouter)
}
② 迁移:在 cmd/migrate/server.go 的 import 块里空导入 migration 包:
import _ "example/app-order/migration"
⚠️ 漏掉第 ② 处是"静默失败":不报错、migrate 照常打印成功,但建表和种子数据就是不会执行,直到第一个请求打过来才看到"表不存在"。
③ 验证(最快且只读,可直接对生产库跑):
go run main.go migrate --dry-run -c config/settings.yml
你的迁移应该出现在待执行列表里。正式执行后再登录管理后台:Order Example 目录和 Orders 菜单已由种子生成,把菜单授权给角色即可看到按钮权限生效。
④ 前端接线(带界面的应用才有第三处):在 go-admin-ui 的 apps.config.mjs 加一条 { code: 'order', source: '...' } 指向你的页面目录,构建脚本会自动同步,无需手工操作。
7️⃣ 顺手白拿的能力:多租户与数据权限
很多新手不知道,上面的写法已经"免费"获得了两项高级能力:
- 多租户:Service 里用的
e.Orm来自api.Api.MakeOrm(),它按请求上下文解析出当前租户的数据库连接,天然绕开全局 DB 变量带来的租户串号问题(见 docs/architecture.md "多数据源"一节); - 数据权限:只要模型内嵌
ControlBy、Service 查询加上actions.Permission(tableName, p)这个 GORM Scope,角色配的"本部门 / 仅本人"等档位就自动生效,一行业务代码都不用改。
📦 小结:30 分钟集成清单
| 步骤 | 你要做的事 | 参考文件 |
|---|---|---|
| 1 | 声明应用身份(Code/Version/依赖) | manifest.go |
| 2 | 建模型:表名避开保留字、内嵌 ControlBy |
order.go |
| 3 | 写业务:闭包事务 + WHERE 并发防护 | service/order.go |
| 4 | 注册迁移:AutoMigrate + 菜单/API 种子 | migration.go |
| 5 | 注册路由:JWT + 角色 + 数据权限三层 | router.go |
| 6 | 宿主两处空导入,migrate --dry-run 验证 |
cmd/api/demo.go |
| 7 | 前端 apps.config.mjs 加一条 source |
docs/contract.md |
模式掌握后,把"订单"换成"库存、工单、报表"……模块结构完全一样。更多设计动机(为什么通用 CRUD Action 留在主仓不下沉、应用间调用目前如何取舍等),推荐精读 docs/contract.md 与 docs/architecture.md——它们会帮你避开扩展路上 90% 的坑。