RFC：移除内置代码生成器，改为「工程规范 + AI Skill」

[wenjianzhang]

TL;DR — 代码生成模块（/dev-tools/gen、/dev-tools/build）已经跟不上项目本身了：它产出的前端代码在 Vue 3 下跑不起来，只支持 MySQL，官方 Docker 镜像里根本没打包它依赖的文件。与其继续维护约 6100 行模板与胶水代码，我想把它换成一份可被人和 AI 同时读懂的工程规范，外加官方维护的 AI coding skill。这是一个提案，不是已决定的事，想先听听大家怎么用它。

English: Proposing to remove the built-in code generator in favour of a documented convention set + officially maintained AI coding skills. The generator currently emits Vue 2 syntax (broken on our Vue 3 UI), supports MySQL only, and isn't shipped in the official Docker image. Scroll to "Options" — feedback wanted on A / B / C.

---

1. 为什么现在提这件事

go-admin 刚完成两件事：后端升到 Go 1.26 / v2.3.0，前端从 Vue 2 + Element UI 迁到 Vue 3 + Element Plus + Vite（v3.0.0）。迁移做完之后，代码生成器的状态就很尴尬了。

下面每一条我都核过代码，附了文件位置，欢迎复核。

1.1 生成器自己能跑，但它生成的东西跑不起来

/dev-tools/gen 这几个页面在迁移时被改成了 Vue 3 写法，能正常打开。但模板没人改——它吐出来的仍然是 Vue 2 语法：

文件	已在 Vue 3 / Element Plus 失效的写法	出现次数
go-admin/template/v4/vue.go.template	slot-scope	4
	:page.sync / :limit.sync / :visible.sync	3
	@keyup.enter.native	1
	size="mini"	7

也就是说：今天任何人点一下"生成代码"，拿到的前端页面在当前 UI 工程里是直接白屏的。 这是最难解释的一点——工具本身被维护了，工具的产出没有。

1.2 只支持 MySQL

// go-admin/app/other/apis/tools/db_tables.go:30
if config.DatabaseConfig.Driver == "sqlite3" || config.DatabaseConfig.Driver == "postgres" {
    err = errors.New("对不起，sqlite3 或 postgres 不支持代码生成！")

元数据读取硬依赖 information_schema（db_tables.go / db_columns.go），另外两种驱动直接报错。而 go-admin 三种数据库都是一等公民，Docker 官方镜像默认就是 SQLite。

1.3 官方 Docker 镜像里它是坏的

go-admin/Dockerfile 只 COPY 了三样东西：

COPY ./main /main
COPY ./config/settings.demo.yml /config/settings.yml
COPY ./go-admin-db.db /go-admin-db.db

template/ 和 static/form-generator/ 都没进镜像。而 NOActionsGen 用的是相对路径 template/v4/...（apis/tools/gen.go:169）。结论：用官方镜像部署的用户，点代码生成必然收到"模版读取失败"；点表单构建必然 404。 这个模块实际上只在"从源码目录直接跑二进制"的开发机上有效。

1.4 表单构建器是一个无源码的预编译包，且从第三方 CDN 远程加载 EOL 依赖

/dev-tools/build 是个 iframe，指向后端静态目录 go-admin/static/form-generator/（636 KB，仓库里没有对应源码，来自 JakHuang/form-generator）。它的 index.html 里写着：

<script src="https://lib.baomitu.com/vue/2.6.11/vue.min.js"></script>
<script src="https://lib.baomitu.com/vue-router/3.1.3/vue-router.min.js"></script>
<script src="https://lib.baomitu.com/element-ui/2.13.2/index.js"></script>
<link href="https://lib.baomitu.com/monaco-editor/0.19.3/..." rel="stylesheet">

四个问题叠在一起：

• Vue 2.6.11 / Element UI 2.13.2 均已 EOL（Vue 2 已于 2023-12-31 停止维护）
• 无 SRI（Subresource Integrity） —— 后台管理系统从外部 CDN 拉未校验的脚本
• 内网 / 离线部署直接白屏 —— 很多用 go-admin 的场景恰恰是内网
• 仓库里没有源码，没人能重新构建或打补丁

1.5 写盘接口的权限模型值得重新审视

GET /api/v1/gen/toproject/:tableId 会在服务端创建目录并写入文件（gen.go:219-224）。它注册在 sysNoCheckRoleRouter 里，只挂了 JWT 中间件，没有挂 Casbin 的 AuthCheckRole（app/other/router/gen_router.go:21-30）。

保守地说：这意味着任意已登录用户（不论角色）都能触发服务端文件系统写入，而路径的一部分来自数据库中同样可由登录用户写入的字段。我不打算在公开帖子里展开细节；如果有同学想深入，请走 Security Advisory 私下提。

说明：这不是"有人被打穿了"，而是"这个设计在今天不该出现在一个默认开启的菜单里"。删掉它，这个问题自然消失。

1.6 维护成本

部分	位置	规模
后端生成逻辑	app/other/{apis,models,router}/tools	~1,545 行 Go
代码模板	template/v4/ + api_migrate.template	~1,591 行
前端生成器页面	src/views/dev-tools/gen、src/api/tools	~1,236 行
前端表单渲染/解析	src/utils/generator、components/FormGen*	~1,763 行
表单构建器预编译包	go-admin/static/form-generator	636 KB，无源码
单元测试	app/other/**/*_test.go	0 个

约 6,100 行 + 636 KB，零测试覆盖。每次 Element Plus 大版本、每次 GORM 大版本、每次目录结构调整，这部分都要跟着改一遍——而实际能用到它的只有"从源码跑、用 MySQL、在开发机上"这一个交集。

---

2. 提案

删除

• 后端：app/other/apis/tools、app/other/models/tools、app/other/router/gen_router.go 中的 gen 相关路由、template/v4/、template/api_migrate.template、static/form-generator/

更正（原文写的是「template/ 整个目录」，那是错的）：template/ 下另有三个文件服务于与 Web 代码生成器无关的功能，删掉会打断正常命令——

• cmd_api.template、router.template ← cmd/app/server.go，即 go run main.go app -n <名称> 应用脚手架，它同时负责生成 cmd/api/<名称>.go 中的自动注册代码
• migrate.template ← 被 cmd/migrate/server.go 与 gen.go 共用，迁移文件生成依赖它

因此可删除的只有 template/v4/ 与 template/api_migrate.template。

• 前端：src/views/dev-tools/gen、src/views/dev-tools/build、src/api/tools、src/utils/generator、components/FormGenRender、components/FormGenParser
• 数据：菜单 261 / 262 / 264（代码生成、代码生成修改、表单构建）与对应 sys_api 记录；sys_tables / sys_columns 两张元数据表

保留

• /dev-tools/swagger（系统接口）——跟生成器无关，继续留着
• template/cmd_api.template、router.template、migrate.template——见上方更正，它们属于应用脚手架与迁移命令，与本提案无关
• template/v4/ 承载的"标准 CRUD 长什么样"这一信息不会丢失：它将由 app/demo/ 这个真实可编译、有测试、CI 会跑的参照模块承接。相比模板，样板模块的好处是过时会导致构建失败，而模板过时只会静默产出坏代码——本提案第 1.1 节描述的正是后者

---

3. 用什么替代

3.1 一份工程规范（对人、对 AI 都有效）

在两个仓库根目录各放一份 AGENTS.md（同时软链 CLAUDE.md / .cursorrules，这几个生态都在收敛到同一个文件），内容就是把现在藏在模板里的约定显式写出来：

• 后端分层：apis → service → service/dto → models，各层职责与错误处理约定
• 路由注册方式、Casbin 权限标识命名（模块:资源:操作）
• Swagger 注解规范
• 前端：BasicLayout + el-card 的列表页结构、src/api/ 的 RESTful 命名（list* / get* / add* / update* / del*）、v-permisaction 用法
• 一个完整的、能跑的参考模块（比如就用 sys-user 或新建一个 demo 模块），作为"照着这个写"的标准答案

这份东西的价值不依赖 AI——新人贡献者、写插件的人同样需要它。今天它不存在，只能靠读代码猜。

3.2 官方维护的 AI Skill

在 .claude/skills/ 下提供 skill（Claude Code 直接可用，Cursor / Copilot / Cline 等也能读 AGENTS.md 拿到同样的约定）：

Skill	做什么
go-admin-crud	从一张表 / 一段 schema 描述，生成后端 model + dto + service + apis + router + 前端页面 + API 层，直接写进正确目录
go-admin-menu	生成对应的菜单与权限种子数据 SQL
go-admin-review	按本项目规范审查 PR（分层、权限标识、Swagger 注解是否齐全）

相比模板引擎的实际好处：

• 三种数据库一视同仁——它读的是你的 schema，不是 information_schema
• 生成完能自己跑 go build / pnpm lint / 单测，发现问题当场改
• 字段是 status 就知道该配字典、是 created_at 就知道该格式化——模板做不到这种判断
• 跟着 Element Plus 版本走，不需要我们维护第二套 Vue 模板
• 你可以让它"参考 sys-user 但把分页改成游标"——模板只能全有或全无

必须说清楚的代价：

• 需要 AI 编码工具（可能要付费）
• 输出不是确定性的，两次生成结果可能不同
• 不联网 / 严格合规环境下用不了

这正是下面 Option B 存在的理由。

---

4. 三个选项 —— 这是我最想听意见的部分

Option A：完全删除，只留规范 + Skill
最干净，维护负担归零。代价：不用 AI 工具的人失去了脚手架能力。

Option B：删掉 Web UI，保留一个离线 CLI 子命令
./go-admin gen --table sys_user --package admin。模板留在二进制里（go:embed，顺便解决 1.3 的路径问题），砍掉 Web UI、sys_tables/sys_columns 两张表、写盘 HTTP 接口和表单构建器——1.2/1.3/1.4/1.5 全部解决，1.1 需要重写一遍 Vue 模板。确定性保留，离线可用。
代价：那 ~1,600 行模板还得继续跟着 Element Plus 走。

Option C：维持现状，只修模板
最小改动，但 1.2~1.6 一个都没解决，且每个大版本都要重付一次这个成本。

我个人倾向 A，但如果有相当数量的人是在内网/离线/合规环境下真的在用生成器，那 B 更负责任。

所以我想请大家回帖告诉我：

1. 你实际用过内置代码生成器吗？最近一次是什么时候？
2. 你在什么环境用的——源码开发机 / Docker / 内网离线？用的哪种数据库？
3. 表单构建器（/dev-tools/build）有人在用吗？（说实话我怀疑基本没有）
4. 如果换成 AI skill，你的团队用不上（合规/网络/成本）吗？
5. 你更想要 A、B 还是 C？

---

5. 对现有用户的影响

如果你从没点开过这两个菜单：升级后无感，除了二进制小一点、Docker 镜像小 636 KB。

如果你用生成器生成过业务模块：已经生成的代码完全不受影响——它们是普通的 Go/Vue 文件，早就在你的仓库里了，删的是"生成它们的工厂"，不是产物。

需要做的（会提供一键迁移 SQL）：

• 删除菜单 261 / 262 / 264 与对应 sys_api 记录
• sys_tables / sys_columns 两张表可以 drop（只存生成器的元数据，不影响业务）

不会做的：不会在任何补丁版本里删。按下面的节奏走。

---

6. 时间线（可调整）

阶段	版本	动作
现在	—	本讨论收集意见（至少 2 周）
第一步	v2.4.0 / v3.1.0	菜单标记「已废弃」，页面顶部加提示；发布 AGENTS.md 与第一版 skill；生成器仍可用
第二步	v2.5.0 / v3.2.0	默认隐藏菜单（配置项可开回来）
第三步	v3.0.0 / v4.0.0	正式移除，提供迁移 SQL

如果讨论结果倾向 Option B，第三步就换成"上线 CLI 子命令"。

---

7. 相关

• 前端 Vue 3 迁移：go-admin-ui v3.0.0
• 表单构建器上游：JakHuang/form-generator（感谢原作者，这里讨论的是它在本项目中的集成方式，与上游项目本身无关）

欢迎直接反对——尤其是如果你正在生产环境依赖这个模块。我更怕的是没人说话然后删了才发现有人在用。

/cc @go-admin-team