常见问题与排错

本章汇总模块开发过程中的常见问题和解决方案。

后端问题

Q1: 启动报错 Table 'xxx.tornado_position' doesn't exist

原因：模型定义后未执行建表。

解决：

# 方式一：脚本自动建表
python scripts/init_db.py

# 方式二：Alembic 迁移
alembic revision --autogenerate -m "add position table"
alembic upgrade head

# 方式三：手动建表（参考 model.md 中的 DDL）

Q2: 接口返回 {"code": 1, "msg": "权限不足"}

原因：权限节点未配置或未分配给当前用户角色。

排查步骤：

1. 确认菜单管理中已添加权限节点，权限标识与代码中 @permission_required 完全一致
2. 确认权限节点已分配给当前用户的角色
3. 使用 admin 账号（ID=1）测试，admin 自动跳过权限校验

Q3: 唯一性校验不生效

原因：unique_fields 配置错误。

排查步骤：

1. 确认 key 是模型字段名（如 name），不是中文名
2. 确认 Service 类中声明了 unique_fields
3. 确认调用的是 service.add() 或 service.update()，而非直接操作 repo

Q4: 分页查询返回空数据

原因：分页参数名不匹配或字段配置错误。

排查步骤：

1. 前端传参名应为 pageNo 和 pageSize（驼峰）
2. 确认 page_like_fields 和 page_eq_fields 中的字段名与模型一致
3. 检查数据库中是否有数据（is_delete=0 的记录）

Q5: 删除时报错 "存在引用"

原因：_before_delete 钩子检测到关联数据。

解决：先调整引用该记录的其他数据，再执行删除。如岗位被用户引用时，需先修改用户的岗位字段。

Q6: batch_delete 端点报 500 错误

原因：Handler 方法未正确继承 BaseHandler。

解决：批量删除 Handler 必须继承 BaseHandler 并使用 async def：

class PositionBatchDeleteHandler(BaseHandler):
    @permission_required("sys:position:delete")
    @check_demo
    async def post(self):
        return await position_service.batch_delete(self)

前端问题

Q7: 页面白屏，控制台报 Failed to fetch dynamically imported module

原因：路由组件路径配置错误。

排查步骤：

1. 确认路由中的 component 路径与实际文件路径一致
2. 确认后端菜单的 component 字段值正确（如 system/position/index）
3. 检查文件名大小写是否匹配

Q8: 搜索功能不生效

原因：搜索表单的 submit 事件未正确绑定。

排查步骤：

1. 确认 BasicForm 绑定了 @submit="handleSearch" 事件
2. 确认 handleSearch 中调用了 reload({ searchInfo: values })
3. 确认后端 page_like_fields 和 page_eq_fields 配置了对应字段

Q9: 编辑弹窗不回填数据

原因：openModal 未传入记录数据。

解决：

// 正确：第一个参数 true 表示编辑模式，第二个参数是记录数据
openModal(true, record);

Q10: 操作按钮不显示

原因：v-perm 权限标识与后端不一致。

排查步骤：

1. 确认 v-perm 中的权限字符串与后端 @permission_required 完全一致
2. 确认当前用户拥有对应权限
3. 检查 TableAction 中的 auth 字段是否正确

通用问题

Q11: 接口返回 401 Unauthorized

原因：JWT Token 过期或未携带。

解决：

1. 确认请求头包含 Authorization: Bearer <token>
2. Token 过期后需调用刷新接口或重新登录
3. 前端 defHttp 自动处理 Token 注入，检查是否正确引入

Q12: 接口返回 403 Forbidden（演示模式）

原因：演示模式下写操作被拦截。

解决：将 .env 中的 TORNADO_DEMO 设为 False，或移除端点上的 @check_demo 装饰器（仅开发阶段）。

Q13: 数据库字段中文乱码

原因：数据库或表的字符集不是 UTF-8。

解决：

• MySQL：确保数据库和表使用 utf8mb4 字符集
• PostgreSQL：建库时指定 ENCODING 'UTF8'

开发调试技巧

查看 SQL 日志

在 .env 中开启 SQL 调试：

DB_DEBUG=True

重启后所有 SQL 查询都会输出到控制台。

使用 curl 调试

使用 curl 或 Postman 等工具直接测试接口：

# 登录获取 Token
curl -X POST http://127.0.0.1:8041/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456","code":"xxxx","key":"xxxx"}'

# 携带 Token 调用业务接口
curl http://127.0.0.1:8041/api/v1/position/page \
  -H "Authorization: Bearer <token>"

检查权限配置

如果不确定权限是否配置正确，可以用 admin 账号测试。admin（ID=1）自动跳过所有权限校验。

总结

模块开发常见问题主要集中在：字段类型不匹配、唯一性校验遗漏、软删除过滤缺失、分页参数命名不一致、权限节点未配置等。遇到问题时优先检查后端日志，确认接口入参和返回值是否符合预期。