如何快速扩展业务模块:go-admin-core 订单应用 app-order 从 0 到集成完整实战

原创2026-09-21 21:05:311,362 阅读
文章标签:后端认证鉴权企业应用

如何快速扩展业务模块: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) 注册迁移,在一个事务里完成三件事:

  1. AutoMigrate 建出 app_order、app_order_item 两张表;
  2. 种子菜单与 API:目录 → 列表页 → 两个按钮(新建/付款),以及 4 条 API(列表/详情/创建/付款)。宿主 Seeder 会把这些规格翻译成 sys_menu / sys_api / sys_menu_api_rule 行,管理员在后台授权给角色后自动生成 casbin 规则;
  3. 写入迁移版本记录(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% 的坑。

登录后查看全文
go-admin