---
url: https://qiwuadmin.com/features/codegen.md
description: 代码生成器按表名生成后端、前端、zod 规则、菜单权限和 e2e 测试，支持单表、树表、主子表及可选的移动端页面，并说明数字精度和零手改模块。
---

# 代码生成器

代码生成器是这个模板保持一致性的核心：平台里大部分标准模块本身就是生成出来的，所以你生成的代码和平台代码是同一种写法。

![代码生成器的表列表](/screenshots/zh-codegen.webp)

## 能生成什么

| 模板 | 适用场景 | 示例 |
| --- | --- | --- |
| 单表 `crud` | 普通列表 + 表单 | 岗位、图书示例 |
| 树表 `tree` | 有上下级关系的数据 | 知识主题示例 |
| 主子表 `master_sub` | 一张单据带多行明细 | 发票示例（发票 + 明细行） |

每个模块会生成：

* **后端**：实体、服务、控制器（带权限、操作日志和 Swagger 文档）、模块、菜单和权限种子
* **共享包**：zod 规则（新增、修改、查询、返回）和权限常量
* **前端**：列表页（查询、分页、排序、列设置，日期范围筛选带"今天""最近 7 天""最近 30 天"快捷选项）、表单弹框、详情抽屉、导入弹框、接口封装、中英文翻译
* **测试**：e2e 测试，覆盖成功、无权限（403）、校验失败（400）等情况
* **移动端**（可选）：员工手机端的列表、详情和表单页，见下一节

## 移动端页面

**系统工具 → 代码生成** 的编辑页里，"生成信息"页签有一个开关 **移动端页面**，默认关闭，每张表单独设置。打开后，预览、下载和命令行生成都会多出这个模块的移动端文件：

* 接口封装；
* 列表页、详情页和表单页（只读模块没有表单页）；
* 中英文翻译片段。

页面的样子：

* **列表**：只有一个关键字搜索框，可以上拉加载更多。只有拥有"查看"权限时，点一行才会进入详情；只有"浏览"权限的人停在列表上；
* **树表**：一层一层点进下级，调整上下级关系要到电脑端；
* **主子表**：子表每行一张卡片，可以添加、删除行。

几点说明：

* 只有仓库里还有移动端（`mobile/` 目录）时才会生成。删掉移动端的项目，打开这个开关也不会多出任何文件；
* 子表自己的配置里没有这个开关，也不单独生成页面：子表的明细行显示在主表的详情页里，在主表的表单页里添加、删除；
* 生成器不改已有的文件。预览里的"注册代码"（命令行生成时打印在最后）会列出要加进移动端页面配置 `pages.json` 的几行，手工粘贴进去；从哪里进入这些页面（比如工作台上的快捷入口）也由你自己加；
* 移动端页面没有生成密文列和关键字以外的筛选，详情里的部门和用户显示编号而不是名称，需要时自己补。

::: warning 发布前删除示例页
图书、知识主题、发票三个示例模块打开了这个开关，它们的 9 个移动端页面已经登记在 `pages.json` 里。这些页面没有入口，只能通过地址打开，但登记过的页面会随小程序和 App 一起上线。正式发布前，从 `pages.json` 里删掉这 9 个页面的登记（每个页面一条），同时删掉专门测这些示例页的移动端端到端测试 `mobile/e2e/mobile-codegen.spec.ts`，否则移动端的自动测试会失败。示例的源码建议留着，生成器的一致性检查会逐字比对它们。
:::

## 表名决定模块名

生成器只根据表名推导模块的名字，不需要配置文件：`crm_customer` → 领域 `crm`、业务名 `customer`，代码生成到 `modules/crm/customer/`，接口是 `/api/crm/customers`，权限点是 `crm.customer.*`。生成的页面会自动挂到名字匹配的菜单分组下（比如 `crm`），也可以在配置中改选。详见[新增业务模块](/guide/new-module#表名决定了什么)。

平台和工作流自己的表前缀（比如 `iam_`、`wf_`）不要用在项目表上。`im_` 前缀和领域名 `im` 留给平台将来的聊天功能，项目也不能使用。

## 两种使用方式

* **页面**：系统工具 → 代码生成。可以导入表、编辑配置、预览代码、下载 zip（支持多张表批量下载），也可以从数据库同步表结构。
* **命令行**：`pnpm gen import` 导入表并保存默认配置，`pnpm gen render … --out <目录>` 输出到仓库外的目录，`pnpm gen write` 写入仓库（需要开发环境，并设置 `CODEGEN_WRITE=true`）。

![代码生成器的字段配置](/screenshots/zh-codegen-fields.webp)

![生成代码的预览](/screenshots/zh-codegen-preview.webp)

完整步骤见[新增业务模块](/guide/new-module)。

## 安全保证

* **从不覆盖已经存在的文件**。如果文件已存在且内容不同，只打印差异，一个文件都不写。
* 只写到约定的源码目录下，不会经过符号链接写到其他地方。
* 表名、列名等标识符有白名单校验，模板里的数据库值都会转义。
* 不支持"粘贴 DDL 建表"，建表只能通过迁移，避免 SQL 注入风险。

## 数字的精度

生成的代码用 JavaScript 的数字处理数值列，所以有两个上限：

* **整数列**（包括 `bigint`）：只能可靠地表示到 9007199254740991（2 的 53 次方减 1）。生成的接口会拒绝写入更大的值，编号、计数这类列不要超过它；
* **小数列**（`decimal`、`numeric`）：总位数（整数位加小数位）不超过 15 位时按数字处理，比如 `decimal(12,2)`；超过 15 位时（比如 `decimal(20,2)`）自动改按文本处理，表单用文本框，Excel 用文本单元格，保留完整的精度；
* `float`、`double` 本来就是近似值，不保证十进制计算精确。

金额这类需要精确计算的业务，要自己定好舍入规则，或者用文本形式的十进制数来计算。精度规则的完整说明见仓库的[代码生成文档](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/codegen.md#数值精度边界)。

## 零手改模块

如果把一个模块的生成配置保存成种子文件（`*.cg.ts`），这个模块就成了"零手改模块"：检查命令 `pnpm gen:check-golden` 会重新生成它，并和仓库里的代码逐字节比较，有文件缺少、不同或多余时报错。模板自带的零手改模块是岗位，以及图书、知识主题、发票三个示例。

好处是**模板升级后可以一键同步**：运行 `pnpm gen:check-golden --write` 写入新版生成结果，查看改动后再运行一次 `pnpm gen:check-golden` 确认没有差异（命令见[命令 · 代码生成](/reference/commands#代码生成)）。这条命令会先构建服务端，再清空并重建隔离测试库（`qiwu_test` + Redis 15 号库），不要和服务端测试同时运行；写入前的检查和失败后的恢复见仓库的[代码生成文档](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/codegen.md#g0-与检查边界)。

这类模块的额外逻辑要写在相邻的新文件里，不能改动生成的文件。
