4.3 后端分层架构
概述
后端五层：api / controller / service / logic / dao。分层不是形式主义——每层有明确的"允许/禁止"清单，组合起来构成依赖红线体系。本节逐层说明职责与边界。
分层与调用关系
text
api/v1（契约层）
▲ 依赖
controller（HTTP 薄层）
▲ 依赖接口
service（接口层，手维护）
▲ 实现
logic（业务层，ModuleSpec 基座 + 钩子 + 手写逃生舱）
▲ 唯一入口
dao（数据访问层，红线条件 + 全局钩子）
▲
model/entity · model/hooks · gdb侧路能力（横向复用）：utility/{cache,captcha,crypto,excel,ip2layer,jwt,response,ua,upload} 与 consts（错误码/缓存键/上下文键/日志类型）。
各层职责与边界
api/v1（契约层）
- 全部 Req/Res 结构体，单包 v1，每模块一文件（snake_case）
- gmeta 注解声明 method/path/summary/permission/log/logType/public
- gvalid 标签声明校验规则；
dc标签供 OpenAPI 文档 - 禁止：业务逻辑、数据库引用
controller（HTTP 薄层）
- 一行透传
return service.Xxx().Method(ctx, req) - 禁止：业务 if/for、import dao、手写响应信封、手写参数解析
service（接口层，手维护）
- 每模块一文件：接口
IXxx+ 实例变量 + 取用函数Xxx()+ 注册函数RegisterXxx() - 未注册时取用 panic（启动即暴露接线错误）
- 禁止：整体运行
gf gen service（会覆盖手工重组结构）
logic（业务层）
- 每模块一文件：
sXxx实现 +xxxSpec声明 +init()注册 + 标准委托 + 扩展手写 - 共享能力经
base.go（15 个导出上限）与module_spec.go基座 - 跨模块复用走同包包级函数（ResolveCityNames / LoadIdentity / ApplyDataScope / DictGetText…）
- 禁止：反向 import task；绕过 dao；在钩子里做 HTTP/文件 IO
dao（数据访问层）
- 自定义模板产出：构造时挂
hooks.Handler()；Ctx覆写注入红线条件 - 禁止：绕过直连
g.DB()；手写 del_flag/tenant_id 条件；手改 dao/internal/
上下文键（consts/context_key.go）
JWT 中间件写入身份，全链路 consts.GetXxx(ctx) 读取：
| 写入方 | 键 |
|---|---|
| JWT 中间件 | UserID / TenantID / Username / Realname / TokenJTI / TokenExpire / Roles / Perms / DataScope / DeptID |
| Response 中间件 | ClientIP / UserAgent / ReqMethod / ReqURL |
两套租户读法（易错点）
CtxTenantID(ctx) —— 原始值（0=平台），仅供租户设施（hooks/中间件）使用 GetTenantID(ctx) —— 业务归属值（租户返回自身，超管返回 tenant.defaultId），新增/导入/唯一校验统一用它
数据范围读法：GetDataScope(ctx) 档位（1-全部；未注入回退全部）；GetDeptID(ctx) 部门 ID（0=未分配）。
响应与错误码
统一信封（utility/response）：
text
成功：{"code":0, "ok":true, "msg":"操作成功", "data":{...}}
失败：{"code":1, "ok":false, "msg":"...", "data":{}}
未认证：HTTP 401 + {"code":401,...}Fail 映射规则：gerror 码 == 401 原样保留；其余一律降级 code=1（前端 ResultEnum.ERROR 才弹 msg）。consts 中的细分错误码（1001 用户不存在…）主要用于日志与语义区分。
分页契约：PageData[T] = {records, total, size, current, pages}，records 为空输出 [] 而非 null；pageNo 默认 1，pageSize 默认 10 上限 500。
横切约定速查
text
* 主键：int 数据库自增；新增后 result.LastInsertId() 回读
* 软删：del_flag 0 正常 / 1 删除；删除接口全部软删
* 表前缀：goframe_；文件命名 snake_case 对齐 dao（前端文件仍驼峰）
* 入参/出参 json 驼峰；唯一例外：登录/令牌接口返回
access_token/refresh_token/expires_in/token_type（OAuth2 惯例，勿改）
* 缓存键统一前缀 easygoadmin:
* 权限码 sys:{module小驼峰}:{action}；超管 ROLE_SUPER_ADMIN；前端通配 *:*:*
* 审计列：id/create_user/create_time/update_user/update_time/del_flag（租户表另有 tenant_id）