zerx-backend

name	zerx-backend
description	zerxLabKit 后端开发规约(Go + connectRPC + GORM)。当新增/修改 RPC、实现 service handler、写数据访问、用 GORM 泛型 API、自定义 querier SQL、跑 codegen 时使用。Keywords: connectRPC, handler, service, GORM, gorm.G, 泛型, Count, FirstOrCreate, nilaway, getter, querier, 自定义 SQL, deleted_at, 软删, convert, proto, task gen, buf, 代码生成, JS 保留字, 后端, backend, Go

zerxLabKit 后端开发规约

Claude 已熟悉 Go / GORM / connectRPC;以下是 zerxLabKit 特有规则。

新增一个 RPC(流程)

1. 编辑 proto/zerx/v1/*.proto,加 message / rpc。方法名避开 JS 保留字。校验约束写在字段上:string email = 1 [(buf.validate.field).string.email = true];(亦有 min_len、pattern:"^[a-z][a-z0-9_]*$")。
2. task gen → 产出 Go handler 接口 + TS 类型 + connect-query hook。
3. 在 internal/service/ 实现 handler,照抄 user_service.go 范式但不写 RequireRole(授权交 Casbin,见 skill://zerx-authz)。
4. 注册:internal/server/server.go 用 reg(zerxv1connect.NewXxxServiceHandler(service.NewXxx(...), opts))。免认证 procedure 进 public,已登录即放行进 selfServe。注意 assertServicesRegistered 会校验所有 zerx.v1 service 都已挂载(漏挂会启动失败)。
5. 前端用 connect-query hook(见 skill://zerx-frontend)。

service 范式(以 internal/service/user_service.go 为模板转写)

• 结构:type XxxService struct { db *gorm.DB } + var _ zerxv1connect.XxxServiceHandler = (*XxxService)(nil) + NewXxxService(db)。
• 签名:func (s *XxxService) Method(ctx, req *connect.Request[zerxv1.XReq]) (*connect.Response[zerxv1.XResp], error)。