267 lines
10 KiB
Markdown
267 lines
10 KiB
Markdown
# 10.3 Web 管理界面
|
||
|
||
:::tip 概述
|
||
代码生成器提供 Web 管理界面，通过可视化操作完成代码生成，无需命令行。支持表选择、配置生成选项、预览代码和一键生成。界面位于「开发工具 → 代码生成」菜单。
|
||
:::
|
||
|
||
## 操作流程
|
||
|
||
```text
|
||
1. 登录管理后台
|
||
2. 进入「开发工具 → 代码生成」菜单
|
||
3. 查看可生成的数据库表列表（自动读取当前数据库的所有表）
|
||
4. 选择目标表，点击「配置」
|
||
5. 配置生成选项（模板类型、生成菜单、覆盖文件等）
|
||
6. 点击「预览」查看生成代码（不写入文件，可安全查看）
|
||
7. 确认无误后点击「生成」创建文件
|
||
8. 检查 routes/api.php 中的路由（通常已自动插入）
|
||
9. 在菜单管理中配置菜单权限
|
||
10. 重新登录或刷新前端动态菜单，新模块即可使用
|
||
```
|
||
|
||
## 界面说明
|
||
|
||
### 表列表页
|
||
|
||
进入「开发工具 → 代码生成」后，首先进入表列表页：
|
||
|
||
| 列 | 说明 |
|
||
|----|------|
|
||
| 表名 | 数据库表名（不含前缀） |
|
||
| 表注释 | 表的 COMMENT 字段（显示为中文说明） |
|
||
| 引擎 | 存储引擎（InnoDB / MyISAM） |
|
||
| 行数 | 表中的数据行数 |
|
||
| 操作 | 配置 / 预览 / 生成 |
|
||
|
||
### 配置弹窗
|
||
|
||
点击「配置」按钮后，可设置以下生成选项：
|
||
|
||
| 配置项 | 参数名 | 说明 | 示例 |
|
||
|--------|--------|------|------|
|
||
| 表名 | `tableNames` | 选择要生成的表（自动带入，格式 `"表名\|注释"`） | `["laravel_example\|案例演示"]` |
|
||
| 模板类型 | `templateType` | `ui` 普通列表 或 `ui2` 树形（含 parent_id 时自动切换） | `ui` |
|
||
| 生成菜单 | `generateMenu` | 是否自动创建菜单和权限节点 | `true` |
|
||
| 覆盖文件 | `overwrite` | 是否覆盖已存在的文件 | `false` |
|
||
|
||
### 预览功能
|
||
|
||
点击「预览」按钮，可查看即将生成的所有文件代码：
|
||
|
||
- 预览模式**不会写入文件**，可安全查看
|
||
- 支持切换查看不同文件（Controller / Service / Model / Request / API / Vue / columns.ts / querySchemas.ts）
|
||
- 确认无误后再点击「生成」实际创建文件
|
||
|
||
### 批量生成
|
||
|
||
在表列表页勾选多张表，点击「批量生成」：
|
||
|
||
- 批量生成会为每张表分别生成完整的 CRUD 模块（含文件、菜单、字典、路由）
|
||
- 单张表失败不影响其它表继续生成
|
||
- 生成结果会显示每张表的成功/失败状态和文件统计
|
||
|
||
## 配置选项详解
|
||
|
||
### 模块名（自动推导）
|
||
|
||
模块名由表名去掉前缀自动推导，影响以下内容：
|
||
|
||
| 影响范围 | 规则 | 示例（模块名=example） |
|
||
|----------|------|----------------------|
|
||
| 后端路由前缀 | `/api/{模块名}/` | `/api/example/page` |
|
||
| 前端 API 文件 | `ui/src/api/{app}/{模块名}.ts` | `ui/src/api/tool/example.ts` |
|
||
| 前端视图目录 | `ui/src/views/{app}/{模块名}/` | `ui/src/views/tool/example/` |
|
||
| 权限码前缀 | `sys:{模块名}:` | `sys:example:page` |
|
||
| 字典编码前缀 | `{模块名}_{字段名}` | `example_status` |
|
||
|
||
### 树形结构（自动检测）
|
||
|
||
当表中包含 `parent_id` 或 `pid` 字段时，引擎自动切换为 `ui2/` 树形模板：
|
||
|
||
- 前端使用 Tree + Table 左右布局
|
||
- 支持拖拽排序、展开/折叠
|
||
- 自动处理父子关系的新增和编辑
|
||
- 树形模板不生成 `columns.ts` 和 `querySchemas.ts`
|
||
- 注册路由时不含 `page` 路由
|
||
|
||
### 导入导出（默认生成）
|
||
|
||
默认生成 `import()` 和 `export()` 方法：
|
||
|
||
- 后端基于 `ExcelService` 实现分批导入导出
|
||
- 枚举字段自动做正向/反向映射（值 ↔ 文本，反向映射用 `DictCacheService::getValue()`）
|
||
- 前端生成导入/导出按钮
|
||
|
||
### 字典自动创建
|
||
|
||
带选项（choices）的字段会自动创建字典：
|
||
|
||
- 在 `laravel_dict` 和 `laravel_dict_item` 表中创建记录（`create_user = 'system'`）
|
||
- Service 中自动生成 `$serializeMaps` 映射
|
||
- 查询时自动补 `{字段名}Text` 翻译字段（`HasSerializeMaps` Trait）
|
||
- 幂等：字典编码已存在则跳过
|
||
|
||
### 路由自动注册
|
||
|
||
在 `routes/api.php` 中自动插入 CRUD 路由组（`GeneratorService::registerRoute()`）：
|
||
|
||
- 包含 list / detail / add / update / delete / batchDelete / import / export
|
||
- 非树形结构额外包含 page 路由
|
||
- 插入位置为文件末尾中间件组闭合 `});` 之前，分组注释取表注释（如 `// --- 案例演示 ---`），表注释为空时回退模块名
|
||
- 幂等：同模块路由已存在则跳过（以路由路径判断）
|
||
|
||
## API 接口
|
||
|
||
| 方法 | 路径 | 权限码 | 说明 |
|
||
|------|------|--------|------|
|
||
| GET | `/api/generator/page` | sys:generator:page | 获取可生成的表列表（分页） |
|
||
| GET | `/api/generator/preview` | sys:generator:generate | 预览生成代码（不写入文件） |
|
||
| POST | `/api/generator/generate` | sys:generator:generate | 一键生成（写入文件） |
|
||
| POST | `/api/generator/batchGenerate` | sys:generator:generate | 批量生成（多表） |
|
||
|
||
:::tip 演示模式
|
||
预览接口（preview）标注了 `#[DemoAllow]`，演示环境下也可使用（且本身是 GET 请求）。生成接口（generate / batchGenerate）为写操作，演示环境下会被 `DemoMiddleware` 拦截（`config('app.demo_mode')` 开启时）。
|
||
:::
|
||
|
||
### 请求参数
|
||
|
||
```json
|
||
{
|
||
"tableNames": ["laravel_example|案例演示"],
|
||
"templateType": "ui",
|
||
"generateMenu": true,
|
||
"overwrite": false
|
||
}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 | 默认值 |
|
||
|------|------|------|------|--------|
|
||
| `tableNames` | string[] | 是 | 表名数组，格式为 `"表名\|注释"` | - |
|
||
| `templateType` | string | 否 | 模板类型：`ui`（普通列表）或 `ui2`（树形） | `ui` |
|
||
| `generateMenu` | bool | 否 | 是否自动创建菜单和权限节点 | `true` |
|
||
| `overwrite` | bool | 否 | 是否覆盖已存在的文件 | `false` |
|
||
|
||
:::info 树形结构自动切换
|
||
当表中包含 `parent_id` 或 `pid` 字段时，即使传入 `templateType: "ui"`，也会自动切换为 `ui2` 树形模板。
|
||
:::
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 预览生成代码（不写入文件）
|
||
# -----------------------------------------------------------------------------
|
||
# GET /api/generator/preview
|
||
# Content-Type: application/json
|
||
# Authorization: Bearer <token>
|
||
curl -X GET http://localhost:8000/api/generator/preview \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer <token>" \
|
||
-d '{
|
||
"tableNames": ["laravel_example|案例演示"],
|
||
"templateType": "ui"
|
||
}'
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"ok": true,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"files": [
|
||
{
|
||
"path": "app/Http/Controllers/Api/ExampleController.php",
|
||
"content": "<?php\nnamespace App\\Http\\Controllers\\Api;\n// ...",
|
||
"exists": false,
|
||
"type": "backend"
|
||
},
|
||
{
|
||
"path": "app/Services/ExampleService.php",
|
||
"content": "<?php\nnamespace App\\Services;\n// ...",
|
||
"exists": false,
|
||
"type": "backend"
|
||
},
|
||
{
|
||
"path": "ui/src/views/tool/example/columns.ts",
|
||
"content": "import { h } from 'vue';\n// ...",
|
||
"exists": false,
|
||
"type": "frontend"
|
||
}
|
||
],
|
||
"vars": {
|
||
"app_name": "tool",
|
||
"module_name": "example",
|
||
"module_comment": "案例",
|
||
"model_class_name": "Example",
|
||
"template_type": "ui",
|
||
"is_tree": false
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
:::tip 响应结构说明
|
||
- `files`：待生成文件数组，每项含 `path`（相对路径）、`content`（渲染后内容）、`exists`（是否已存在）、`type`（backend/frontend）
|
||
- `vars`：模板变量，供调试和导出配置使用
|
||
- 一键生成接口的 `msg` 为多行统计消息：📄 文件（生成/跳过/失败数量）、📋 菜单、📖 字典、🔀 路由
|
||
:::
|
||
|
||
## 生成后操作清单
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 第 1 步：检查生成的文件
|
||
# -----------------------------------------------------------------------------
|
||
ls app/Http/Controllers/Api/Example* # 控制器
|
||
ls app/Services/Example* # 业务服务
|
||
ls app/Models/Example* # 数据模型
|
||
ls app/Http/Requests/Example* # FormRequest 验证器
|
||
ls ui/src/api/tool/example* # 前端 API
|
||
ls ui/src/views/tool/example/ # 前端页面（含 index.vue / edit.vue / detail.vue / columns.ts / querySchemas.ts）
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 第 2 步：检查 routes/api.php 中的路由（通常已自动插入，带 // --- 案例演示 --- 表注释）
|
||
# -----------------------------------------------------------------------------
|
||
grep -n "// --- 案例演示 ---" routes/api.php
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 第 3 步：在菜单管理中配置菜单权限
|
||
# -----------------------------------------------------------------------------
|
||
# 菜单已自动创建：案例（路径：/tool/example，组件：tool/example/index）
|
||
# 权限节点已自动创建：sys:example:page / list / detail / add / update / delete / batchDelete / import / export
|
||
# 只需为角色勾选相应权限
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 第 4 步：根据业务需求调整 Service 属性配置
|
||
# -----------------------------------------------------------------------------
|
||
# 可调整：fileFields（文件字段）、serializeMaps（字典映射）、
|
||
# pageLikeFields（模糊查询）、uniqueFields（唯一校验）等
|
||
```
|
||
|
||
:::warning 生产环境注意
|
||
- 路由写入后，若执行过 `php artisan route:cache`，需重新缓存
|
||
- 新菜单需重新登录（刷新 Redis 中的 JWT 权限缓存）或刷新动态菜单后生效
|
||
:::
|
||
|
||
## 与 CLI 命令对比
|
||
|
||
| 特性 | Web 界面 | CLI 命令 |
|
||
|------|----------|----------|
|
||
| 使用方式 | 浏览器可视化操作 | 命令行 |
|
||
| 适用场景 | 日常开发、单表生成 | 批量生成、CI/CD 集成 |
|
||
| 预览功能 | ✅ 支持（不写入文件） | ✅ 支持（--dry-run） |
|
||
| 批量生成 | ✅ 支持（多选表） | ✅ 支持（--batch） |
|
||
| 配置选项 | 更多（树形、导入导出等） | 基础配置 |
|
||
| 权限限制 | 受权限和演示模式限制 | 不受限制 |
|
||
| 导出配置 | ❌ 不支持 | ✅ 支持（--output） |
|
||
|
||
## 相关文档
|
||
|
||
- [10.1 概述与架构](/zh/generator/overview.html)
|
||
- [10.2 CLI 命令行使用](/zh/generator/cli.html)
|
||
- [10.4 表结构解析引擎](/zh/generator/parser.html)
|
||
- [10.8 实战案例](/zh/generator/demo.html)
|