161 lines
5.0 KiB
Markdown
161 lines
5.0 KiB
Markdown
:::tip 本章概要
|
||
代码生成器使用过程中常见问题的原因分析和解决方案。
|
||
:::
|
||
|
||
# 常见问题
|
||
|
||
## 生成报错 "模块 xxx 已存在"
|
||
|
||
**原因**：生成器会校验目标目录不存在，避免覆盖已有模块。
|
||
|
||
**解决方式**：
|
||
|
||
```bash
|
||
# 1. 删除已有模块目录
|
||
rm -rf src/modules/example
|
||
|
||
# 2. 删除已生成的端点文件
|
||
rm src/api/v1/endpoints/example.py
|
||
|
||
# 3. 从 router.py 中移除对应的导入和注册语句
|
||
# 删除这两行：
|
||
# from api.v1.endpoints.example import router as example_router
|
||
# v1.include_router(example_router, prefix="/example", tags=["案例"])
|
||
|
||
# 4. 删除数据库中对应的菜单记录
|
||
# DELETE FROM fastapi_menu WHERE path = '/tool/example';
|
||
|
||
# 5. 重新生成
|
||
python generator.py fastapi_example
|
||
```
|
||
|
||
## 生成后前端页面不显示
|
||
|
||
**排查步骤**：
|
||
|
||
1. **确认菜单已创建**：检查数据库 `fastapi_menu` 表中是否有 `path = '/tool/example'` 的记录
|
||
2. **确认路由组件路径**：菜单的 `component` 字段应为 `tool/example/index`
|
||
3. **确认权限已分配**：当前用户需要有对应菜单的访问权限
|
||
4. **清除缓存**：退出重新登录，或清除浏览器缓存
|
||
5. **确认后端已重启**：新路由需要重启后端服务才能生效
|
||
|
||
## 如何重新生成？
|
||
|
||
完整清理流程：
|
||
|
||
```bash
|
||
# 1. 删除后端模块
|
||
rm -rf src/modules/example
|
||
|
||
# 2. 删除端点
|
||
rm src/api/v1/endpoints/example.py
|
||
|
||
# 3. 清理 router.py 中的导入和注册
|
||
|
||
# 4. 删除前端文件
|
||
rm -rf ui/src/views/tool/example
|
||
rm ui/src/api/tool/example.ts
|
||
|
||
# 5. 删除数据库菜单
|
||
# DELETE FROM fastapi_menu WHERE path = '/tool/example';
|
||
|
||
# 6. 重新生成
|
||
python generator.py fastapi_example
|
||
```
|
||
|
||
## 批量生成有数量限制吗？
|
||
|
||
Web API 批量生成最多支持 50 个表（`MAX_BATCH_SIZE = 50`）。CLI 无限制，但建议逐表生成，便于排查问题。
|
||
|
||
## 树状列表是如何判断的？
|
||
|
||
当表中存在 `parent_id` 或 `pid` 字段时，自动切换为树状模板（`ui2/`），生成树形结构的增删改查页面。
|
||
|
||
树状列表与普通分页列表的区别：
|
||
|
||
| 维度 | 普通列表（ui/） | 树状列表（ui2/） |
|
||
|:----|:----|:----|
|
||
| 触发条件 | 无 parent_id/pid | 有 parent_id/pid |
|
||
| 模板数量 | 5 个组件 + 1 个 API | 3 个组件 + 1 个 API |
|
||
| 数据加载 | 分页请求 | 全量加载 + 前端 buildTree |
|
||
| 展开/折叠 | 无 | 支持 |
|
||
| 父子关系 | 无 | 自动识别 |
|
||
|
||
## CLI 报错 "No module named 'core'"
|
||
|
||
**原因**：未在项目根目录执行命令。
|
||
|
||
**解决**：确保在项目根目录（包含 `src/` 和 `generator.py` 的目录）执行：
|
||
|
||
```bash
|
||
cd /data/apps/djangoadmin
|
||
python generator.py fastapi_example
|
||
```
|
||
|
||
## 生成的代码有语法错误
|
||
|
||
**可能原因**：
|
||
- 表名或字段名包含特殊字符
|
||
- 字段注释包含未转义的引号
|
||
- 数据库连接异常导致解析不完整
|
||
|
||
**解决**：
|
||
1. 使用 `--dry-run` 检查解析结果
|
||
2. 导出配置文件检查字段内容：`python generator.py fastapi_example --dry-run --output config.json`
|
||
3. 手动修正配置文件后用 `--config` 重新生成
|
||
|
||
## 如何自定义生成的代码风格？
|
||
|
||
修改 `src/modules/generator/templates/` 下的模板文件。模板使用 Jinja2 语法，详见 [6.6 自定义模板](/zh/volume5/templates)。
|
||
|
||
修改模板后重新生成即可生效，不影响已有模块。
|
||
|
||
## 生成速度慢
|
||
|
||
**可能原因**：
|
||
- 数据库连接延迟高
|
||
- 表字段数量非常多（50+ 字段）
|
||
- 同时生成大量表（批量生成）
|
||
|
||
**解决**：
|
||
- 检查数据库网络连接
|
||
- 减少单次批量生成的表数量
|
||
- 使用 CLI 单表生成替代批量生成
|
||
|
||
## 生成器支持哪些数据库？
|
||
|
||
:::warning 数据库限制
|
||
代码生成器通过查询 MySQL 的 `information_schema` 获取表结构信息，**仅支持 MySQL 数据库**。`service.py` 中的 `_query_tables`、`_query_table_detail`、`_query_table_columns` 等函数使用了 MySQL 特有的 SQL 语法（如 `TABLE_SCHEMA = (SELECT DATABASE())`），在其他数据库中可能无法正常执行。
|
||
:::
|
||
|
||
代码生成器通过 `information_schema` 查询表元数据，支持以下数据库：
|
||
|
||
| 数据库 | 支持程度 |
|
||
|:----|:----|
|
||
| MySQL | 完全支持（主要开发和测试环境） |
|
||
| PostgreSQL | 支持（information_schema 兼容） |
|
||
| SQL Server | 支持（information_schema 兼容） |
|
||
| SQLite | 部分支持（information_schema 有限） |
|
||
| Oracle | 部分支持（需适配） |
|
||
|
||
## 模板语法错误如何排查？
|
||
|
||
**症状**：生成时报错 `jinja2.exceptions.TemplateSyntaxError`。
|
||
|
||
**排查步骤**：
|
||
1. 查看错误信息中的模板文件名和行号
|
||
2. 打开对应的 `.tpl` 文件检查语法
|
||
3. 常见错误：
|
||
- `{% if %}` 缺少 `{% endif %}`
|
||
- 变量名拼写错误（如 `f.nmae` 应为 `f.name`）
|
||
- 使用了未定义的变量（如字段对象中不存在的属性）
|
||
4. 修改模板后重新生成
|
||
|
||
## 总结
|
||
|
||
大部分问题可通过以下流程解决：
|
||
1. 使用 `--dry-run` 预览配置
|
||
2. 清理旧文件后重新生成
|
||
3. 确认数据库菜单和权限配置正确
|
||
4. 重启后端服务
|