代码生成器

代码生成器是 Sz-Admin 提供的效率工具，旨在帮助开发者快速生成高质量的业务代码。通过自动化生成 Controller、Service、Mapper、PO / DTO / VO、前端页面、API 类型和菜单权限脚本，可以减少重复开发和低级错误，让开发者把更多精力放在业务规则与页面体验上。
原有“导入表 -> 配字段 -> 生成 CRUD”的使用方式仍然保留。随着 v2 主线引入后端多模块、前端模块注册、API 前缀拆分和 Liquibase 模块化，生成器也顺着这些工程结构补上了目标确认、代码预览和接入校验：你仍然可以像以前一样生成标准 CRUD，只是生成前能更清楚地看到代码会写到哪里、哪些文件会新增、哪些文件只做幂等修改。
代码生成器和 AI Coding 也可以放在同一个问题下思考，但不必急着判断谁会替代谁。生成器更像是先把稳定、重复、强约定的工程骨架铺好，例如目录、权限、Liquibase、API 前缀和模块接入；AI Coding 则更容易在具体业务上下文中继续补充复杂规则、交互细节、测试和重构。对开发者来说，这里真正值得追问的是：哪些约定应该由生成器固化，哪些判断仍需要回到业务现场确认。

本页会按日常使用顺序介绍生成器：先说明必要配置，再从导入表、编辑字段、确认生成目标、预览代码到生成后处理逐步展开。对于只想快速生成普通页面的场景，可以重点看“快速流程”和“编辑配置”；对于正在做 v2 升级、模块裁剪或新业务模块接入的场景，建议同时阅读“代码预览与生成”和“升级注意”。

在原有标准 CRUD 场景基础上，当前生成器还适合这些使用方式：

在已有模块中新增普通 CRUD，例如生成到 sz-module-admin、sz-module-audit 或已接入的自定义模块。
为边界清晰的新业务域创建独立 sz-module-*，同时补齐 POM、API 前缀、MapperScan、Excel 模板扫描和 Liquibase 接入。
先预览生成计划，确认新增文件、幂等修改项、跳过文件和初始化脚本，再决定直接生成或下载离线包。

IMPORTANT

如果只是使用官方默认工程体验生成器，可以先按页面流程操作；下面这些信息主要面向 v2 升级、模块裁剪和自定义业务模块接入场景。

v2.0.0 起，代码生成器后端模块已从 sz-common-generator 迁移到 sz-module-generator。如果启动服务未引入 sz-module-generator，生成器接口不会生效。

sz-module-admin 是官方核心模块。客户自有业务如果具备独立边界，建议新建自己的 sz-module-* 并按独立业务模块接入指南接入，避免把业务代码长期堆进官方核心模块。

一、参数配置

旧版文档中的生成器参数配置仍然有效。v2 重构后，配置重点从单一生成路径扩展为“API 前缀 + 模块扫描 + 默认路径候选”。后端核心配置位于 sz-service/sz-service-admin/src/main/resources/application.yml。

yaml

sz:
  api-prefix:
    modules:
      generator:
        enabled: true
        prefix: /generator
  generator:
    path:
      # 前端项目路径。需手动指定或在具体编辑Form中修改。
      web:
      # 后端项目路径。通常无需配置，页面会扫描 sz-module 下已接入模块。
      api:
    # 后端业务模块聚合目录，默认扫描 sz-module。
    module-name: sz-module
    # 默认后端目标模块兜底值。
    service-name: sz-module-admin
    global:
      author: sz-admin
      packages: com.sz.admin
      ignore-table-prefix:
        enabled: true
        prefixes:
          - test_

前端生成器接口通过 generatorHttp 访问 VITE_GENERATOR_API_BASE，默认是 /api/generator。生成出来的业务模块接口会根据目标模块选择内置 HTTP client，或使用 createModuleHttp(moduleCode, apiPrefix) 基于 VITE_API_CONTEXT_PATH 拼出自定义模块请求前缀。

二、快速流程

在“代码生成”列表点击“导入”，选择数据库表。
点击“编辑”，按“基本信息 -> 字段信息 -> 生成目标与行为”三步检查配置。
点击“预览”，通过目标树确认新增、修改、跳过和脚本。
点击“生成代码”直接写入本地项目，或下载完整离线包人工合并。
生成后先做后端编译/打包与 Maven 同步，再重启服务、配置角色权限并刷新前端页面。新建模块首次生成时不要跳过 Maven package 或项目重新加载。

导入目标表

三、编辑配置

编辑弹窗分为三步。前两步关注“表和字段怎么生成”，第三步关注“生成目标与行为”，也就是确认代码生成到哪里、生成后怎样被项目加载。

3.1 基本信息

基本信息用于确认表名、表描述、实体类名称、作者和备注。

表名称由导入表决定，通常不需要修改。
表描述会影响菜单、页面标题和接口文档展示。
实体类名称影响 PO、DTO、VO、Service、Controller 等类名。

3.2 字段信息

字段信息页是本次重构变化最大的区域。页面顶部提供生成类型和全局开关，中间是字段表格，右侧是当前字段详情面板。

生成类型

当前页面暴露三种生成类型：

类型	输出范围	适用场景
全栈	后端代码、前端页面、API 类型、菜单/权限脚本	标准业务 CRUD，需要页面直接可用。
后端	Controller、Service、Mapper、PO、DTO、VO、Mapper XML、导入导出相关后端代码	只需要后端接口，前端由其他项目或人工实现。
数据库	以数据库和 Mapper 相关产物为主	只需要数据库实体、Mapper 或迁移起点。

生成类型会联动字段表格：例如仅后端时不会展示弹窗/抽屉切换；关闭 Excel 导入或导出后，对应字段筛选和字段开关也会隐藏。

字段统计与批量操作

字段配置页会按用途统计字段数量，包括全部字段、表单字段、列表字段、查询字段、导入字段、导出字段和待处理字段。点击统计按钮可以快速定位字段集合。

表头的复选框只作用于当前筛选结果。例如先搜索 order，再勾选“查询”，只会把当前搜索结果中的字段加入查询条件，不会影响隐藏字段。

右侧详情面板

右侧详情面板用于编辑当前选中字段：

基础信息：字段描述、Java 类型。
数据库约束：主键、自增、唯一、必填、逻辑删除。
生成位置：新增、编辑、列表、查询。
Excel 字段：导入、导出。
前端展示：显示类型、字典类型、字典展示方式。
查询配置：查询方式。

当显示类型选择 select、radio、checkbox 等依赖字典的组件时，必须配置字典类型，否则进入下一步前会提示并阻止保存。radio-group 会统一规范为后端模板识别的 radio。

第二步-字段信息

字段智能推断

导入表时，后端会根据字段名、数据库类型、字段约束和字典信息做默认推断，并把解释信息返回到前端 smartHints 中。常见规则如下：

推断对象	说明
主键与自增	识别主键字段、自增字段，默认不参与新增表单。
Java / TS 类型	根据数据库类型推断 `Long`、`String`、`BigDecimal`、`LocalDateTime` 等类型。
字典字段	`status`、`type`、`sex`、`_cd` 等字段会提示疑似字典；如果控件依赖字典但未配置，会标记为待处理。
上传字段	`file`、`image`、`avatar`、`attachment`、`url` 等字段会倾向上传组件，并提示确认资源场景 `sceneCode`。
自动填充	`create_id`、`create_time`、`update_id`、`update_time` 等字段会按新增、更新或新增/更新自动填充处理。
逻辑删除	`del_flag`、`is_deleted` 等字段会识别为逻辑删除字段。
数据权限	`dept_scope`、`create_id` 等字段会关联数据权限校验，不建议作为普通表单字段。

智能推断只是降低初始配置成本，不等于业务规则已经完全确认。生成前仍建议逐项检查字段描述、字典、查询方式、上传场景和唯一校验。

上传字段与窗口展示

当字段显示类型选择 fileUpload 或 imageUpload 时，生成器会把 Java 类型推断为 List<ResourceRef>，并默认写入上传组件配置。常见配置包括：

配置项	默认值	说明
`upload-files.sceneCode`	`system.temp`	资源场景编码，对应 `oss.yml` / 资源场景配置中的 `code`。
`upload-files.pathSegments`	`your_biz_path`	业务路径片段，建议生成后按业务目录调整。
`upload-files.accept`	图片字段为 `image/*`，文件字段为空	上传文件类型限制。
`upload-files.limit`	图片字段 1，文件字段 5	最大上传数量。
`upload-files.fileSize`	3	单个文件大小限制，单位 MB。

生成后必须根据业务资源场景调整 sceneCode 和路径片段，不建议长期使用默认 system.temp。

全栈生成时，字段信息页顶部可以选择新增/编辑表单的展示方式：

方式	说明	适用场景
弹窗	在当前页面居中打开表单。	字段较少、操作简单的表单。
抽屉	从页面侧边滑出表单。	字段较多、需要更大编辑空间的表单。

3.3 生成目标与行为

第三步用于确认目标模块、路径、API 前缀、菜单权限和数据权限。可以把它理解为生成前的最后确认页：前面配置“生成什么”，这里确认“生成到哪里、生成后怎样接入项目”。

第三步-新建模块

后端目标选择

页面支持“现有模块”和“新建模块”两种后端目标。这里先完成目标、路径、API 模块和 API 前缀确认；具体如何判断该用哪一种，见下一节“现有模块与新建模块”。

API 项目路径与 Web 项目路径

选择现有模块时，API 项目路径来自扫描结果，通常不需要手写。
选择新建模块时，API 项目路径需要填写新模块完整目录，例如 E:\dev\Code\Github\sz-boot-parent\sz-module\sz-module-crm。
Web 项目路径填写前端项目根目录，例如 E:\dev\Code\Github\sz-admin。

页面会展示真实完整路径，而不是只展示“待补齐”。“待补齐”表示模块缺少必要接入项，例如：

sz-module/pom.xml 聚合模块声明。
根 pom.xml 依赖版本管理。
sz-service-admin/pom.xml 启动服务依赖。
模块 ApiPrefixRegister 配置。
模块 @MapperScan 配置。
模块 @EnableExcelTemplateScan 配置。
服务 Liquibase 主入口 include。
application.yml 中 sz.api-prefix.modules.<moduleCode> 配置。

API 模块与 API 前缀

API 模块用于标识当前业务模块，例如 admin、audit、smart、crm。API 前缀是后端接口最终挂载前缀，例如 /admin、/audit、/smart、/crm。

对于现有已接入模块，API 模块和 API 前缀会跟随后端扫描结果自动填充。对于新建模块，输入 sz-module-smart 时，页面会默认推断：

text

backendModuleName = sz-module-smart
apiPrefixModule   = smart
apiPrefix         = /smart
packageName       = com.sz.smart
frontendModuleName = smart

前端生成代码会优先复用内置 client：

adminHttp 对应 VITE_ADMIN_API_BASE。
auditHttp 对应 VITE_AUDIT_API_BASE。
generatorHttp 对应 VITE_GENERATOR_API_BASE。

自定义模块会使用 createModuleHttp(moduleCode, apiPrefix)。例如 moduleCode=smart、apiPrefix=/smart、VITE_API_CONTEXT_PATH=/api 时，最终请求 base 是 /api/smart。

菜单、按钮权限与数据权限

全栈生成时可以选择是否自动创建菜单。开启后，还可以选择是否生成按钮权限和数据权限。

生成菜单：把菜单路由写入菜单表，生成后需要给角色授权。
生成按钮权限：生成新增、修改、删除、查询、导入、导出等按钮权限数据，并与生成代码中的权限码保持一致。
自动创建数据权限：为菜单权限开启数据权限控制。

WARNING

数据权限会影响列表查询。生成前后端会检查当前数据权限最小单位：sz.data-scope.logic-min-unit=user 时表中需要 create_id 字段；logic-min-unit=dept 时表中需要 dept_scope 字段。缺少对应字段时，应补字段或关闭自动创建数据权限。

四、现有模块与新建模块

生成器同时支持写入现有模块和创建新模块，是为了贴合不同业务边界，不是鼓励把每个功能都拆成独立模块。选择前建议先判断业务边界、发布成本和后续维护成本。

WARNING

新建模块的判断和微服务拆分类似：先有清晰边界，再拆模块。不要为了“看起来更模块化”而拆。每增加一个模块，都会增加 POM 依赖、启动服务接入、API 前缀、包扫描、Liquibase include、前端模块注册和发布验证成本。

4.1 优先使用现有（旧有）模块

现有模块适合大多数日常 CRUD 生成场景：

功能属于已有业务域，只是补充一张表、一个页面或一个管理功能。
希望复用已有模块的 API 前缀、包扫描、Liquibase 入口、菜单分组和发布流程。
表之间关联紧密，后续会频繁调用同一模块内的 Service 或 Mapper。
团队暂时不希望增加新的 Maven 模块、前端模块注册和发布验证成本。

选择现有模块时，页面会从后端仓库 sz-module 下扫描可生成模块，下拉选择后同步路径、包名、API 模块和 API 前缀。现有已接入模块通常只生成业务代码和脚本；如果模块缺少少量接入项，预览会把缺失项展示为“修改文件”，生成时做幂等插入。

4.2 什么时候新建模块

新建模块适合边界已经比较清楚的新业务域：

业务域相对独立，后续会沉淀一组表、页面、接口、权限和定时任务。
希望拥有独立后端模块、前端模块、API 前缀和包路径，例如 sz-module-crm 对应 /crm。
与官方核心模块生命周期不同，后续可能单独裁剪、迁移或按业务域维护。
已经能说清楚模块职责，而不是只有一两张和现有功能强关联的表。

新建模块时，目标树通常包含四类内容：

模块骨架：模块 pom.xml、ApiPrefixRegister、MapperScan、EnableExcelTemplateScan、Liquibase 模块入口。
后端业务代码：Controller、Service、ServiceImpl、Mapper、Mapper XML、PO、DTO、VO、Excel Importer。
前端业务代码：src/modules/<domain>/api、types、views、register.ts。
接入修改：根 POM dependencyManagement、sz-module/pom.xml、启动服务 POM、启动服务 Liquibase 主入口、application.yml API 前缀配置。

如果只是一个普通后台管理页面，或功能明显属于 admin、audit 等既有模块，优先生成到现有模块。等业务边界、代码量和维护诉求真正出现后，再拆成独立模块会更稳。

4.3 模块状态与生成差异

目标	说明	推荐场景
现有模块	从后端仓库 `sz-module` 下扫描可生成模块，下拉选择后同步路径、包名、API 模块和 API 前缀。	模块已经存在，或只想在已有模块中新增 CRUD。
新建模块	输入新模块名和模块路径，生成器创建模块骨架并自动补齐接入项。	新业务域边界清晰，希望拥有独立后端模块、前端模块和 API 前缀。

现有模块下拉会展示接入状态：

状态	含义
已接入	POM、启动服务依赖、API 前缀、MapperScan、Liquibase include 等都已满足，可直接作为生成目标。
将自动补齐	模块存在但缺少部分接入项，预览和生成会展示对应“修改”项。
不可用	模块缺失关键结构，不建议作为当前生成目标。

生成器会排除 sz-module-common 和 sz-module-generator。前者只承载跨模块契约，后者是生成器自身，都不适合作为业务 CRUD 目标。

NOTE

现有模块：

现有模块

新建模块：

新建模块

五、代码预览与生成

点击“预览”后，生成器会构建一份生成计划，而不是直接写文件。新版预览窗口会按目标树展示真实影响范围。

NOTE

代码预览

预览顶部会统计：

类型	说明
新增文件	目标文件不存在，生成时会创建。
修改文件	对已有文件做幂等插入，例如 POM、Liquibase 主入口、`application.yml` 或前端模块 `register.ts`。
跳过	同名目标文件已存在，生成器不会覆盖。
脚本	菜单、按钮权限、数据权限等初始化脚本。

目标树会按后端、前端、脚本分组。点击任意文件可以查看相对路径、完整路径、操作说明和代码内容；修改项会展示 diff，跳过项会提示“目标文件已存在，生成器不会覆盖”。

5.1 生成前校验

点击“生成代码”前会先执行校验：

后端路径是否存在；新建模块允许路径尚不存在，但不能和已有模块冲突。
Web 路径是否存在；仅全栈生成时校验。
后端模块是否存在，是否缺少接入项。
后端包名是否在启动服务扫描范围内。
数据权限是否满足 create_id 或 dept_scope 字段要求。
已存在文件是否需要跳过。

如果存在错误，生成器会阻止生成并展示错误信息。如果只有提醒，会要求确认后继续。

5.2 离线包

“下载完整离线包”会基于预览计划打包：

新增文件进入对应目录。
脚本进入 scripts/<tableName>。
已存在文件不会覆盖进入目标目录。
修改项用于人工比对或后续合并，仍应以预览中的 diff 为准。

六、生成后处理

生成完成后不要只刷新页面。建议按“后端编译/打包与 Maven 同步 -> 重启服务 -> 权限授权 -> 前端刷新 -> 业务自查”的顺序处理。

6.1 编译、打包与 Maven 同步

现有模块新增普通 CRUD 时，通常先执行启动服务关联编译，确认 Java、Mapper XML、Liquibase include 和模板扫描没有问题：

bash

mvn -pl sz-service/sz-service-admin -am compile -DskipTests

新建模块首次生成后，建议在后端父工程执行一次 package，让 Maven 重新识别聚合模块、依赖管理和启动服务依赖：

bash

mvn -pl sz-service/sz-service-admin -am package -DskipTests

如果使用 IDE 启动服务，也建议重新加载 Maven 项目后再启动。否则运行配置可能仍使用旧依赖图或旧 classpath，直接重启后端服务时，新模块不一定会被加载。

6.2 重启后端服务

完成编译、打包或 Maven 重新加载后，再重启后端服务。生成的 Java 类、Mapper、API 前缀配置、MapperScan、Excel 模板扫描和 Liquibase 入口都需要重新启动后端服务才能被 JVM 加载。

生成成功

未重启时，前端可能已经有菜单，但接口、Mapper 或 Bean 还没有加载，会出现访问异常。

未重启异常

6.3 配置角色权限

生成菜单和按钮权限后，需要到角色管理中给对应角色授权，否则用户可能看不到新菜单或无法操作按钮。

角色权限分配

6.4 刷新前端页面

授权完成后刷新前端页面，动态路由会重新拉取菜单并注册页面。

刷新页面

6.5 业务自查

生成代码只是起点，提交前仍建议至少完成以下检查：

前端执行 pnpm type-check 或 pnpm build。
检查 DTO 校验、唯一校验、事务边界、数据权限、字典、上传 sceneCode、导入导出模板是否符合业务规则。
检查 Liquibase include 和 changeSet id 是否稳定。
如果是新建模块，确认启动服务 POM、API 前缀、MapperScan、Excel 扫描、Liquibase 和前端模块注册都已接入。

七、升级注意

从旧版迁移到当前生成器时，重点关注以下变化：

变化	影响
`sz-common-generator` 迁移为 `sz-module-generator`	启动服务必须引入 `sz-module-generator`，并在 Liquibase 主入口 include 生成器模块 changelog。
接口前缀拆分	生成器接口走 `/api/generator`，管理端接口走 `/api/admin`，前端使用 `generatorHttp` / `adminHttp` 等实例。
前端页面迁移到 `src/modules/toolbox`	菜单 `component` 仍可保持 `/toolbox/generator/index`，由模块注册表解析。
生成目标字段新增	`generator_table` 新增后端目标、API 前缀、前端布局等字段，存量库需执行 v2.0.1 增量脚本。
预览从 Tab 改为目标树	生成前应先查看新增、修改、跳过和脚本，尤其是新建模块会修改多个项目文件。
字段智能推断增强	默认配置更贴近常见 CRUD，但字典、上传、数据权限和唯一校验仍需人工确认。

代码生成器 ​

一、参数配置 ​

二、快速流程 ​

三、编辑配置 ​

3.1 基本信息 ​

3.2 字段信息 ​

生成类型 ​

字段统计与批量操作 ​

右侧详情面板 ​

字段智能推断 ​

上传字段与窗口展示 ​

3.3 生成目标与行为 ​

后端目标选择 ​

API 项目路径与 Web 项目路径 ​

API 模块与 API 前缀 ​

菜单、按钮权限与数据权限 ​

四、现有模块与新建模块 ​

4.1 优先使用现有（旧有）模块 ​

4.2 什么时候新建模块 ​

4.3 模块状态与生成差异 ​

五、代码预览与生成 ​

5.1 生成前校验 ​

5.2 离线包 ​

六、生成后处理 ​

6.1 编译、打包与 Maven 同步 ​

6.2 重启后端服务 ​

6.3 配置角色权限 ​

6.4 刷新前端页面 ​

6.5 业务自查 ​

七、升级注意 ​

八、相关文档 ​