3.12 常见问题与排错

:::tip 概述本页汇总模块开发高频问题。核心口诀：新接口只加 RouteSpec 声明 + handler 方法，数据访问只走 Ctx，业务错误原样上抛。 :::

路由与注册

Q：加了 handler 方法但接口 404？

方法签名不匹配。必须是 func (c *CXxx) Method(ctx context.Context, req *dto.XxxReq) (*dto.XxxRes, error)，且 RouteSpec 表中有同名键。反射扫描按签名识别，不匹配的方法静默跳过。

Q：改了 router.go 需要重启吗？

需要。路由注册发生在启动时，改动后重启服务（make run）。

Q：新模块忘记在 registerControllers 加 Bind？

所有控制器必须在 internal/router/router.go 的 registerControllers 中有一条 Bind 声明，否则整个控制器不注册。代码生成器会自动追加。

Q：查询能搜到已删除的数据？

说明绕过了 Ctx。检查是否用了 Raw() 或裸 *gorm.DB——一切查询走 NewXxxRepo().Ctx(ctx)。

Q：租户 A 看到了租户 B 的数据？

两个检查点：表是否在 internal/model/hooks 的租户白名单中（必须含 tenant_id 列）；写入时 Create 钩子是否正常补齐 tenant_id。

Q：物理删除报错"被拦截"？

设计如此。业务删除用 SoftDelete；定时清理等场景用 hooks.WithPhysicalDelete(ctx) 显式放行。

Q：Update 后某些字段变回零值？

Update 是全量表单语义：未提交的字段按零值落库。前端必须回传全部业务字段（未修改的传原值）。

Q：字典字段没有 statusText？

检查三点：SerializeMaps 键是 snake 字段名（status）、字典编码正确（example_status）、DTO 中声明了 StatusText 字段。字典本身需在字典管理中有对应项。

Q：文件上传后访问 404？

上传先进 temp，保存记录时才经 saveTransform 转正到 FileSaveDir。只调上传接口不保存记录，文件不会出现在正式目录。域名问题见 7.2 上传配置详解。

Q：钩子里能做 HTTP 请求 / append 吗？

不能。钩子禁 HTTP/文件 IO、禁 append（可就地改元素），错误原样上抛。

Q：事务里查到的还是旧数据？

事务内必须用回调入参的 ctx：db.WithTrans(ctx, func(ctx context.Context) error { ... })——内层 ctx 才携带事务连接。