269 lines
17 KiB
Plaintext
269 lines
17 KiB
Plaintext
================================================================================
|
||
EasyGoAdmin 后端开发者文档 · 01 系统架构设计
|
||
================================================================================
|
||
|
||
--------------------------------------------------------------------------------
|
||
1. 分层与调用链
|
||
--------------------------------------------------------------------------------
|
||
|
||
main.go（注册五数据库驱动 + Redis 适配器 + blank import internal/logic）
|
||
└─ internal/cmd.Run(ctx)
|
||
├─ 1) utility/cache.Init Redis 探测，失败降级进程内存
|
||
├─ 2) wireDependencies 校验中间件依赖是否已由业务包 init 接线
|
||
├─ 3) g.Server("easygoadmin") + router.Register(s)
|
||
│ 中间件链：CORS → Response → RateLimit → Demo → JWT → Tenant
|
||
│ → OperationLog → 处理器
|
||
│ 处理器 = Bind 反射包装层（权限校验 → 参数解析 → controller →
|
||
│ service 接口 → logic 实现）
|
||
├─ 4) go DaemonInit（延时 2s） 定时任务调度器加载 status=1 任务
|
||
├─ 5) gcron 注册 CleanTemp 每日 03:30 清理上传临时目录
|
||
└─ 6) s.Run() 阻塞运行 HTTP 服务
|
||
|
||
业务调用链（标准 CRUD）：
|
||
Bind 包装（gmeta 权限/日志元数据）
|
||
→ controller.CXxx（薄层，仅转发 service.Xxx()）
|
||
→ service.IXxx 接口（internal/service/{模块}.go，手维护）
|
||
→ logic.sXxx 实现（internal/logic/{模块}.go，ModuleSpec 基座或手写）
|
||
→ dao.Xxx.Ctx(ctx)（唯一查询入口：挂全局钩子 + 注入 del_flag/租户条件）
|
||
→ gdb → 数据库
|
||
|
||
关键设计决策：
|
||
* 目录平铺：api/v1、controller、logic、service 均为单包，每模块一个
|
||
snake_case 文件；跨模块直接同包调用（如 user 直接调用包级函数
|
||
ResolveCityNames，无需 import）。
|
||
* service 接口手维护：internal/service/{模块}.go 声明接口 + Register 注册函数 +
|
||
包级取用函数（如 service.City()）。禁止整体运行 gf gen service（会覆盖手工
|
||
重组的接口文件）。
|
||
* logic 同包 init() 注册：每个 logic 文件在 init() 里调用 service.RegisterXxx
|
||
完成依赖接线，无需 blank import，包内全量加载。
|
||
* 中间件不依赖业务层：身份/租户加载器与日志落地器以函数变量形式注册
|
||
（internal/middleware/wire.go），由 logic 的 init 注入（auth.go 的 init 注册
|
||
IdentityLoader=LoadIdentity、TenantLoader=LoadTenant；operation_log 的
|
||
LogSink 由日志模块注册）。cmd/wire.go 仅在启动期检查并告警缺失。
|
||
|
||
1.1 系统总架构图
|
||
|
||
┌───────────────────────────── 客户端 ─────────────────────────────┐
|
||
│ ui/（Vue3 + Element Plus，baseURL=/api） 其他 API 消费方 │
|
||
└──────────────────────────────────┬─────────────────────────────────┘
|
||
│ HTTP（Bearer JWT）
|
||
╔══════════════════════════════════▼═════════════════════════════════╗
|
||
║ ghttp Server(:8000) ║
|
||
║ ┌────────────────── 中间件链（顺序执行）──────────────────┐ ║
|
||
║ │ CORS → Response → RateLimit → Demo → JWT → Tenant │ ║
|
||
║ │ → OperationLog │ ║
|
||
║ └──────────────────────────┬──────────────────────────────┘ ║
|
||
║ ┌──────────────────────────▼──────────────────────────────┐ ║
|
||
║ │ Bind 反射包装层（gmeta）：权限校验 → 参数解析 → 分发 │ ║
|
||
║ │ 路由元数据表 meta（权限/日志 注解即事实，补注册 goai） │ ║
|
||
║ └──────────────────────────┬──────────────────────────────┘ ║
|
||
║ controller（薄）→ service 接口（手维护）→ logic（ModuleSpec 基座） ║
|
||
║ │ 侧路：utility/{jwt,captcha,cache,upload,excel,ip2region…} ║
|
||
║ │ 侧路：gcron 调度器（job daemon + CleanTemp） ║
|
||
║ ┌────▼─────────────────────────────────────────────────────┐ ║
|
||
║ │ dao.Xxx.Ctx(ctx) —— 唯一查询入口 │ ║
|
||
║ │ hooks.ApplyCtx：del_flag=0 + 租户级表 tenant_id IN(0,x) │ ║
|
||
║ │ hooks.Handler：Insert 盖章 / Update 盖章 / Delete→软删 │ ║
|
||
║ └────┬─────────────────────────────────────────────────────┘ ║
|
||
╚══════╪══════════════════════════════════════════════════════════════╝
|
||
│ gdb（五驱动运行时切换）
|
||
┌──────▼────────┐ ┌──────────────┐ ┌─────────────────────────────┐
|
||
│ MySQL/PgSQL/… │ │ Redis（缓存） │ │ 磁盘 resource/upload + xdb │
|
||
└───────────────┘ └──────────────┘ └─────────────────────────────┘
|
||
|
||
1.2 模块依赖方向图（允许 / 禁止）
|
||
|
||
api/v1 ◀── controller ◀── logic ──▶ service（接口注册）
|
||
│
|
||
├──▶ dao ──▶ model/entity · model/hooks ──▶ gdb
|
||
├──▶ utility/*（无业务依赖）
|
||
└──▶ consts
|
||
|
||
internal/task ──▶ internal/logic ✅ 允许（任务复用 base 能力）
|
||
internal/logic ──▶ internal/task ❌ 禁止（反向依赖）
|
||
internal/middleware ──▶ 业务包 ❌ 禁止（经 wire.go 函数变量接线）
|
||
internal/migrate ──▶ dao/logic ❌ 禁止（gdb 裸连，隔离钩子）
|
||
base.go ──▶ 模块文件 ❌ 禁止（只依赖 dao/utility/consts）
|
||
|
||
--------------------------------------------------------------------------------
|
||
2. 启动编排详解（internal/cmd/cmd.go）
|
||
--------------------------------------------------------------------------------
|
||
|
||
cache.Init(ctx)
|
||
g.Redis() PING 失败 → memFallback=true，进程内 gcache 兜底；
|
||
运行期 Redis 出错同样自动切换（见 utility/cache）。
|
||
wireDependencies(ctx)
|
||
IdentityLoader / TenantLoader / LogSink 任一为 nil 时输出警告日志，
|
||
不阻断启动（缺失的表现分别是：不加载角色权限、跳过租户校验、日志不落库）。
|
||
router.Register(s)
|
||
注册中间件、404/500 状态处理器（统一 JSON）、SetServerRoot("resource")、
|
||
/api/health、/swagger，随后逐个 Bind 全部控制器。
|
||
调度器：time.Sleep(2s) 后 DaemonInit（等 HTTP 监听就绪，任务可能是 HTTP 调自身）。
|
||
上传清理：gcron.AddSingleton("0 30 3 * * *") 每日 03:30 调 logic.CleanTemp，
|
||
保留天数取 file.tempExpireDays（默认 7），条目名 upload_temp_clean。
|
||
|
||
--------------------------------------------------------------------------------
|
||
3. 路由注册与 gmeta 注解（internal/router）
|
||
--------------------------------------------------------------------------------
|
||
|
||
3.1 Bind 反射绑定（bind.go）
|
||
|
||
Bind(s, new(controller.CXxx)) 扫描控制器全部导出方法，方法签名必须为：
|
||
|
||
func (c *Xxx) Page(ctx context.Context, req *v1.XxxReq) (*v1.XxxRes, error)
|
||
|
||
对每个方法读取请求结构体内嵌 gmeta.Meta 的扩展标签：
|
||
|
||
gmeta.Meta `method:"get" path:"/api/user/page" summary:"用户分页"
|
||
permission:"sys:user:page" log:"用户管理-查询分页记录" logType:"query"`
|
||
gmeta.Meta `method:"post" path:"/api/login" summary:"登录" public:"true"`
|
||
|
||
标签语义：
|
||
method HTTP 方法（get/post/put/delete）
|
||
path 完整路由模板（含 /api 前缀；:id 为路由参数）
|
||
summary OpenAPI 摘要
|
||
permission 权限节点，形如 sys:{module小驼峰}:{action}；空 = 登录即可
|
||
log 操作日志标题，形如 "{模块中文名}-{动作}"；空 = 不记录
|
||
logType 日志类型字符串（query/add/update/delete/import/export/reset/…），
|
||
见 consts/log_type.go 的 LogTypeMap
|
||
public "true" = 免登录（仍需与 middleware/public.go 白名单一致）
|
||
|
||
绑定层为每个路由做的事：
|
||
1) 写入路由元数据表 meta.Register(rm)，键 "METHOD /path"
|
||
2) 补注册进 gf goai（闭包路由 gf 不会自动收集）→ /api.json 原生 OpenAPI
|
||
3) 生成统一包装 handler：
|
||
- 路由元数据写入 ctx（操作日志中间件读取）
|
||
- 权限校验：rm.Permission != "" 且 consts.HasPerm(ctx, permission) 为假
|
||
→ 返回 code=403 信封（权限校验在包装层完成，不设独立 Permission 中间件）
|
||
- 参数解析：r.Parse(req)（路由参数+query+body，含 gvalid 校验）；
|
||
实现 BodyUnmarshaler 接口的请求对象走自定义解析逃生舱
|
||
- 调用业务方法，错误 → response.Fail；nil 出参 → Ok(nil)；否则 Ok(出参)
|
||
|
||
3.2 路由元数据表（meta/meta.go）
|
||
|
||
map["GET /api/user/page"] → RouteMeta{Method,Path,Summary,Permission,Log,LogType,Public}
|
||
读写锁保护；Lookup 供调试，All 供文档生成。权限校验与操作日志共用同一份元数据，
|
||
保证“注解即事实”。
|
||
|
||
3.3 路由注册表（router.go registerControllers）
|
||
|
||
按域顺序 Bind：auth → index → system7 → data7 → content3 → monitor7 →
|
||
tool4（含 CExample 代码生成器注册示例）。
|
||
新增模块时在最后一个 Bind 行后追加（代码生成器会自动写入该行，见 07 章）。
|
||
|
||
404/500 状态处理器：非 200 一律输出统一 JSON 信封，不返回 HTML。
|
||
|
||
3.4 URL 约定（与 architecture.md 的差异，务必注意）
|
||
|
||
* 路由 path 直接以 /api 开头，URL 中没有 /v1 版本段；
|
||
api/v1 只是 Go 包名，不代表 URL 版本。例：GET /api/user/page。
|
||
* 公开路由白名单（middleware/public.go，精确匹配）：
|
||
/api/login、/api/register（白名单已放行，路由未注册）、/api/captcha、
|
||
/api/oauth2/token、/api/health
|
||
另放行 /api.json 与 /swagger*。
|
||
* 前端 baseURL 为 /api，模块路径与 gmeta path 逐条对齐。
|
||
|
||
--------------------------------------------------------------------------------
|
||
4. 统一响应与错误码
|
||
--------------------------------------------------------------------------------
|
||
|
||
4.1 响应信封（utility/response）
|
||
|
||
成功：{"code":0, "ok":true, "msg":"操作成功", "data":{...}}
|
||
失败：{"code":1, "ok":false, "msg":"...", "data":{}}
|
||
未认证：HTTP 401 + {"code":401,...}（前端据此跳登录页）
|
||
|
||
Fail() 映射规则：gerror 码 == 401 原样保留；其余一律降级为 code=1
|
||
（前端 ResultEnum.ERROR=1 才弹 msg）。因此 consts 里的细分错误码
|
||
（1001 用户不存在、1003 密码错误……）主要用于日志与语义区分。
|
||
写出响应时把 code/body 记入 ctx（respCodeKey/respBodyKey），
|
||
供 OperationLog 中间件判断成功/失败与记录响应内容。
|
||
|
||
4.2 分页契约
|
||
|
||
分页接口 data 为 PageData[T]（api/v1/common.go NewPageData）：
|
||
{"records":[...], "total":n, "size":pageSize, "current":pageNo, "pages":n}
|
||
records 为空输出 [] 而非 null。
|
||
PageReq：pageNo 默认 1；pageSize 默认 10、上限 500（GetPageSize 截断）。
|
||
批量入参统一 IdsReq{ids:[...]}；新增返回统一 IdRes{id:n}。
|
||
|
||
4.3 业务错误码（consts/biz_err.go，gcode.Register 语义值）
|
||
|
||
1 CodeFailed 通用操作失败
|
||
400 CodeParamError 参数校验失败
|
||
401 CodeUnauthorized 登录已过期，请重新登录
|
||
403 CodeForbidden 没有该操作权限
|
||
429 CodeTooManyRequests 请求过于频繁
|
||
500 CodeServerError 服务器内部错误
|
||
1001 用户不存在 / 1002 账号禁用 / 1003 密码错误 / 1004 验证码错误
|
||
1005 租户过期 / 1006 租户禁用 / 1007 租户用户数上限 / 1008 Token 无效
|
||
1009 记录已存在 / 1010 记录不存在 / 1011 存在下级或关联
|
||
1012 原密码错误 / 1013 租户不存在 / 1014 记录已被引用 / 1015 演示环境禁止操作
|
||
|
||
--------------------------------------------------------------------------------
|
||
5. 数据访问与全局钩子（架构红线执行点）
|
||
--------------------------------------------------------------------------------
|
||
|
||
5.1 dao.Ctx 是唯一查询入口
|
||
|
||
dao/{模块}.go 由自定义模板（hack/tpl/dao_index.tpl）生成，做两件事：
|
||
1) 构造时 m.Hook(hooks.Handler()) —— 挂载 Insert/Update/Delete 全局钩子
|
||
2) Ctx 覆写 —— 进入 SQL 构建前注入条件：
|
||
所有表：del_flag = 0
|
||
租户级表且非平台上下文：tenant_id IN (0, 当前租户)
|
||
业务代码禁止绕过 dao 直连 g.DB()，禁止手写 del_flag/tenant_id 条件。
|
||
|
||
5.2 钩子行为（internal/model/hooks/hooks.go）
|
||
|
||
Insert：主键交数据库自增（int，不使用雪花）；补 del_flag=0、create_time、
|
||
create_user（取 ctx 用户名，回退真实姓名）；租户级表自动携带 tenant_id
|
||
（租户用户零值视为未指定→填自身；超管未指定→tenant.defaultId，
|
||
显式 0 可创建平台共享行）。
|
||
Update：自动盖章 update_time / update_user（仅 map 数据生效）。
|
||
Delete：物理删除一律改写为 UPDATE del_flag=1（软删）。
|
||
|
||
5.3 租户级表清单（tenantTables，共 9 张）
|
||
|
||
goframe_user / role / dept / level / position / article / category / notice / link
|
||
平台级（超管，ctx tenant_id=0）查询不过滤，全量可见。
|
||
|
||
5.4 上下文键（consts/context_key.go）
|
||
|
||
写入方：JWT 中间件写 UserID/TenantID/Username/Realname/TokenJTI/TokenExpire/
|
||
Roles/Perms/DataScope/DeptID（后两者来自身份缓存，见 03 章数据权限节）；
|
||
Response 中间件写 ClientIP/UserAgent/ReqMethod/ReqURL。
|
||
读取方：全链路 consts.GetXxx(ctx)。
|
||
注意两套租户读法：
|
||
CtxTenantID(ctx) 原始值（0=平台），仅供租户设施使用
|
||
GetTenantID(ctx) 业务归属值（租户返回自身，超管返回 tenant.defaultId），
|
||
新增/导入/唯一校验统一用它
|
||
数据范围读法：
|
||
GetDataScope(ctx) 角色数据范围档位（1-全部；未注入视为全部）
|
||
GetDeptID(ctx) 当前用户部门ID（0=未分配）
|
||
|
||
5.5 行级数据权限叠加位置（两层独立）
|
||
|
||
第一层（硬规则，不可配置）：租户隔离 —— dao.Ctx/hooks.ApplyCtx 注入
|
||
tenant_id IN(0,自身)，先于一切业务过滤，任何模块不可绕过。
|
||
第二层（可配置）：角色数据范围 —— ModuleSpec.DataScope 挂点，在
|
||
applyFilters 链末环（Like→Eq→Keyword→Filter→DataScope）叠加；
|
||
共享工厂 ApplyDataScope(deptColumn)（logic/data_scope.go），
|
||
模块一行声明即生效，机制详见 03 章第 6 节。
|
||
|
||
--------------------------------------------------------------------------------
|
||
6. 关键横切约定速查
|
||
--------------------------------------------------------------------------------
|
||
|
||
* 主键：int 数据库自增；新增后 result.LastInsertId() 回读。
|
||
* 软删：del_flag 0 正常 / 1 删除；删除接口全部软删。
|
||
* 表前缀：goframe_；文件命名 snake_case 对齐 dao（前端文件仍驼峰）。
|
||
* 入参/出参 json 驼峰；唯一例外：登录/令牌接口返回
|
||
access_token/refresh_token/expires_in/token_type（OAuth2 惯例，勿改）。
|
||
* 缓存键统一前缀 easygoadmin:（consts/cache_key.go）。
|
||
* 权限码 sys:{module小驼峰}:{action}；超管角色编码 ROLE_SUPER_ADMIN，
|
||
前端通配权限 *:*:*。
|
||
* 每张表统一审计列：id/create_user/create_time/update_user/update_time/del_flag
|
||
（租户表另有 tenant_id）。
|
||
* 命名规范补充：api 与 controller 同样使用 snake_case 文件名
|
||
（与早期“按域分目录”设计不同，以现状为准）。
|