本章概要

代码生成器使用过程中常见问题的原因分析和解决方案。

常见问题

生成报错 "模块 xxx 已存在"

原因：生成器会校验目标目录不存在，避免覆盖已有模块。

解决方式：

# 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. 确认后端已重启：新路由需要重启后端服务才能生效

如何重新生成？

完整清理流程：

# 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 的目录）执行：

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 自定义模板。

修改模板后重新生成即可生效，不影响已有模块。

生成速度慢

可能原因：

• 数据库连接延迟高
• 表字段数量非常多（50+ 字段）
• 同时生成大量表（批量生成）

解决：

• 检查数据库网络连接
• 减少单次批量生成的表数量
• 使用 CLI 单表生成替代批量生成

生成器支持哪些数据库？

数据库限制

代码生成器通过查询 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. 重启后端服务