Skip to content

代码生成器 ​

CLI php webman make:crud 与后台「开发工具 → 代码生成器」共用 GeneratorService。读取已有表,生成后端与 Admin 源码;不生成 PC 或 UniApp 页面,也不自动创建表、执行菜单 SQL 或构建前端。

开发开关与只读能力 ​

真实门闩是 config('app.debug')(来自 server/.env 的 APP_DEBUG),并不按域名、Docker 或环境名称判断。APP_DEBUG=false 时,数据表、字段与能力信息仍可读取;预览、生成、更新计划、增量更新、强制生成和基线导入均拒绝执行。

仅在独立开发环境设置 APP_DEBUG=true 后重启:手动部署在 server/ 执行 php start.php restart;Docker 在项目根执行 docker compose -f docker/docker-compose.yml restart webman。开发完成后恢复 false 并再次重启;reload 用于载入新代码和路由,环境配置切换使用重启。

命令与选项 ​

以下命令在 server/ 执行:

bash
php webman make:crud gen_articles --module=demo --model=GenArticle --comment="示例" --preview
php webman make:crud gen_articles --module=demo --model=GenArticle --comment="示例"
选项说明
--module必填;^[a-z][a-z0-9_]{0,30}$,不能使用保留名
--model^[A-Z][A-Za-z0-9]{0,40}$;默认只移除 DB_PREFIX 指定的前缀、末尾单个复数 s(ss 除外),再转大驼峰。gen_articles → GenArticle;不规则复数请显式指定
--comment模块说明,默认表 COMMENT;显式值最长 100 字符,不含换行或尖括号
--preview默认模式只打印产物清单,不写文件;与 --update 合用时显示增量计划
--force备份后替换已有后端、API、语言包与 SQL 等产物;列表页和表单不覆盖。与 --update 互斥
--reload写入完成后执行 php start.php reload;不导入菜单、不构建 Admin
--update以原始生成基线、当前源码、新模板进行三方合并;有冲突时不修改源文件
--plan-token执行 --update 时携带已审阅计划的 64 位 token;源码、模板或配置变化会使计划过期
--json仅与 --update --preview 合用,输出完整 JSON 计划和合并内容;存在冲突时退出码非零
--baseline-dir从原始生成快照的仓库根目录导入基线,当前源码不变;不能与更新、覆盖、预览、JSON、token 或 reload 混用

当前完整保留名:admin_log、agreement、announcement、apidoc、article、article_category、auth、business、dataimport、diy、feedback、generator、install、message、messages、mobile、operations、payment、region、system、validation、version、wechat。名单由固定核心保留名和 server/resource/lang/zh_CN/ 下顶层 PHP 文件名合并得到;新增语言分组后也会自动保留,以后台实时名单为准。

11 个产物与响应契约 ​

生成 Model、Repository、Service、Resource、Controller、中英文语言包、Admin API、列表页、表单及菜单 SQL。后端响应由 Resource 明确公开字段;筛选、分页、状态与批量 ID 规则使用 CommonRules。status_text 从模块语言包读取,不依赖数据库 COMMENT 作为状态文案。

控制器的路由注解由 reload 后重新扫描。需要导出接口定义时,在 server/ 执行 php webman api:export --type=admin --output=runtime/contracts 导出 OpenAPI 与 TypeScript 定义(--help 可查看选项);生成业务模块不会自动更新已导出的定义。

生成后必须完成 ​

完整可执行示例见 第一个业务模块,容器命令见 Docker 部署。顺序为:

  1. 审核 server/database/generated/{module}-{model_snake}-menu.sql,首次导入时使用 mysql --default-character-set=utf8mb4。SQL 自带 SET NAMES utf8mb4,不自动执行,也不能反复导入,否则产生重复菜单。需要放入已有目录时先调整 parent_id。
  2. 在当前运行方式中执行 Webman reload,使控制器及 API 路由生效。
  3. 在项目根执行 pnpm --dir admin build,使新增页面进入 server/public/admin/。admin/src/ 开发服务会加载源码,Docker/静态部署必须重新构建;PHP 镜像不提供 Node/pnpm,使用宿主机或 CI。
  4. 超管拥有 * 权限,导入菜单后重新登录;普通角色需在角色管理中授予菜单及按钮,再重新登录刷新权限。

生成页面使用 history 路由:/admin/demo/gen-article,不加 #。如果菜单不可见,检查菜单 SQL、菜单状态、角色授权和登录缓存;菜单可见但页面 404,检查前端 build、菜单 component 与 admin/src/views/;API 404 则检查 reload。源码不在构建机时,应将生成的后端和 Admin 源码交给构建流水线一起发布。

注释与编码 ​

创建表、修改 COMMENT 和执行菜单 SQL 的客户端连接均需 utf8mb4;仅设置表的默认字符集不能修复已经错误解码的文本。COMMENT 会成为菜单、表单和列表标签。生成前会阻止无效 UTF-8、替换字符、连续问号和可逆的常见中文乱码,并指出具体表/字段;不会猜测修复或修改数据库。该检测不能识别所有语义乱码,仍需人工核对。

用 SHOW CREATE TABLE、SHOW FULL COLUMNS 或 HEX(COLUMN_COMMENT) 检查,确认原始文字后再以正确连接执行 ALTER TABLE ... COMMENT。修复数据库不会自动修改已生成文件,需通过审阅后的增量更新或手工修正标签。

增量更新与基线 ​

bash
# server/ 中执行,先审阅每个产物的合并内容
php webman make:crud gen_articles --module=demo --model=GenArticle --update --preview --json > /tmp/gen-article-plan.json
# 从 JSON 读取 plan_token;选项须与预览保持一致
php webman make:crud gen_articles --module=demo --model=GenArticle --update --plan-token=替换为64位token

不提供 token 时命令会即时计算计划后执行;要保证执行的是自己审阅过的版本,显式传入 token。未指定说明或字段选项时,沿用已保存基线配置。计划中 unchanged 表示无变化、updated / merged 表示可更新或合并,preserved 表示保留现有改动,created 表示新增、conflict 表示需人工处理(以实际输出为准)。

基线位于 server/generator-state/{module}/{model_snake}/baseline.json,备份和冲突材料同样位于模块状态目录中。遇冲突时所有源文件保持原样,检查输出的 conflict_directory;备份路径由命令输出。不要删除生成文件后重跑,也不要把手工修改的当前源码当作原始生成基线。

旧模块有可信原始快照时,可单独导入:

bash
php webman make:crud gen_articles --module=demo --model=GenArticle --baseline-dir=/path/to/original-repository

快照必须镜像仓库目录(包含 server/ 与 admin/);没有可信快照时应人工迁移,不能用 --force 代替三方合并。

首次生成遇到已有文件或写入失败时,CLI 返回非零退出码,后台返回冲突结果,避免流水线把不完整生成当成成功。

基于 MIT 许可发布