3.11 常见问题与排错

概述

本节收录模块开发阶段的高频问题，按「路由/编译/数据/权限/生成器」分组。更多通用排障见 附录 A。

路由与注册

Q：新增接口 404

排查顺序：

1. router.go 是否有 Bind(s, new(controller.CXxx)) 注册行（生成器会自动写）
2. 请求结构体是否内嵌 gmeta.Meta 且 method/path 标签正确
3. 控制器方法签名是否为 (ctx, *v1.XxxReq) (*v1.XxxRes, error)——签名不符静默跳过
4. 路径是否误带 /v1（本项目 URL 无版本段）

验证：curl http://127.0.0.1:8000/api.json | grep "xxx"——gmeta 会补注册进 OpenAPI。

Q：取用 service panic implement not found

logic 的 init() 未调用 service.RegisterXxx，或接口文件的取用函数名与注册函数名不匹配。检查三件套（接口/取用/注册）拼写一致。

编译与结构

Q：go build 报 logic 循环引用

logic 是单包，跨模块直接调用包级函数即可，不要在 logic 内 import 其他会 import logic 的包。依赖红线：task → logic 单向允许；logic → task 禁止；middleware 经 wire.go 函数变量接线（不 import 业务包）。

Q：改动 logic 方法签名后编译通过但运行 403/空响应

service 接口是手工维护的——签名变更必须同步 internal/service/{模块}.go，否则 controller 调用的是旧接口（编译期不报错的场景是接口方法恰好同签名但语义变化）。

Q：新增了字段但接口返回里没有

三处都要检查：entity 是否刷新（gf gen dao）→ Req/Res 结构体是否含该字段 → ToData 是否映射（写侧）。读侧展示字段在 Item/DetailRes 声明即可（Struct 自动映射）。

数据与隔离

Q：新增数据 tenant_id 为 0 或报错

租户级表必须把表名加入 internal/model/hooks/hooks.go 的 tenantTables 清单（生成器不自动维护）。插入行为：租户用户零值自动填自身；超管未指定填 tenant.defaultId；显式 0 建平台共享行。

Q：查询结果包含已删除数据

是否绕过了 dao.{X}.Ctx(ctx) 直连 g.DB()？红线：唯一查询入口是 dao.Ctx，它自动注入 del_flag=0。

Q：唯一校验漏报 1062 或跨租户误报

UniqueFields 的 Group 范围必须等于唯一索引范围：索引含 tenant_id 时必须 Group:"tenant_id"。手写检查（如 user 的 username/mobile）按"被改行现租户"校验。

Q：删除报"存在下级或关联"

模块 BeforeDelete 守卫（如 dept 有子级/用户、user 关联清理 user_role）。这是业务保护，需要先处理关联数据。

权限与日志

Q：新接口一直 403

1. gmeta permission 标签是否声明（空则仅需登录）
2. 菜单里权限节点是否存在（sys:{module小驼峰}:{action}）
3. 角色是否勾选该节点并保存（保存会清身份缓存）
4. 测试账号是否重新登录（身份缓存 300s；可 DEL easygoadmin:user:identity:{uid}）

Q：操作日志没记录

检查：gmeta log 标签是否为空（空不记录）；logType:"query" 且 operationLog.logQuery: false 时查询类跳过；operationLog.enable 总开关；通道满会丢弃（每丢 100 条告警一次）。

生成器

Q：生成器不创建字典

枚举注释格式不对——须为 字段名：1-正常 2-禁用 形式（-/—/＝/= 分隔）。非 MySQL 库内省不到注释，建议在 MySQL 上生成。

Q：生成的前端页面路由 404

菜单由生成器创建（path /{domain}/{moduleCamel}），但角色未勾选新菜单；或 component 路径与实际文件不符（domain 归属由 genDomainMap 决定）。

Q：重复生成会覆盖我的手工修改吗

默认不会——generator.overwrite: false 时已存在文件跳过（计入 Skipped）。overwrite: true 时全部覆盖（计入 Overwritten），批量覆盖前务必备份或临时改回 false。

Q：租户级新表生成后数据不隔离

生成器不维护 tenantTables 清单，需手工把表名加入 internal/model/hooks/hooks.go 后重启。