技能介绍

要解决什么问题

在 Hertz + GORM Gen + MySQL/Redis 栈里，多人协作时最容易出现：API 里直接拼 SQL、Service 绕过 Repository 访问 DB、事务边界不清晰，以及手改 internal/models / internal/query 导致与 Gen 产物冲突。本技能把「新增 CRUD 模块」时的目录、调用链和硬性约束写死，让 AI 与人都按同一套四层结构落代码。

技能如何组织代码

Repository（internal/repository/*.go）：唯一数据访问层；方法首参必须是 tx *query.Query（nil 表示非事务）；只用 GORM Gen 类型安全查询（如 q.Field.Eq(value)），禁止 Raw SQL；软删除查询需 q.DeletedAt.IsNull()；上下文使用 r.ctx。
Service（internal/service/*/*Service.go）：只做业务聚合，数据操作全部委托 Repository；多表写用 q.Transaction；默认禁止直接操作数据库（文档提到的 AI 媒体等特殊场景除外）。
API（api/admin|user|public）：Get/Create/Update/Delete 命名，统一走 Base 的响应方法与约定响应格式。
Form（internal/form/*.go）：查询表单嵌入 form.Page（Page、PageSize、Offset()、GetPageSize()）；写入表单用 binding 校验。

新增模块时遵循固定流程：internal/models/ 与 internal/query/ 禁止手改，须等 Gen 生成后再写 Repository；在此之前不要引用新 model/query。质量侧强调批量查询防 N+1、context.Context 从 HTTP 逐层下传，分页默认 Page < 1 取 1、超大 PageSize 回落为 10。

适用边界与注意点

何时加载：新增功能模块（CRUD 接口、业务逻辑、数据层）时加载；与具体业务域无关。
不要提前写 Repository：Gen 步骤未完成前，新表对应的类型与 query 尚不存在。
跨层禁令：禁止跨层直接调用 DB；Repository 层不得 Raw SQL。
文档中关于软删除的表述有一处与「GORM 自带过滤」并存，落地时以你们项目里 Gen/Model 的实际软删除配置为准，查询条件与团队约定保持一致即可。

截图预览

使用场景

在现有 Hertz + MySQL 服务里为新业务表补齐 admin/user 侧的列表、详情与增删改接口，需要按 API→Service→Repository→Form 落文件。
用 GORM Gen 实现 Repository 层，方法首参统一为 `tx *query.Query`，并避免 Raw SQL 与在 Service/API 里直接访问数据库。
一次请求要更新多张关联表，需要在 Service 层用 `q.Transaction` 包事务，并把 HTTP 请求的 `context.Context` 传到 Repository。
新表刚加进 schema、尚未跑 Gen 生成 `internal/models` 与 `internal/query` 时，需要约束实现顺序，避免提前写引用新 query 的 Repository。