================================================================================ EasyGoAdmin_GoFrame_EleVue 后端开发者文档 · 00 总览与目录索引 ================================================================================ 文档版本：1.1（封板版，2026-10-17；v1.0 全量编写 → v1.1 补图示/数据模型/FAQ/ 核心模块详解/缓存策略/测试质量/安全专题/变更管理，共 19 章） 适用范围：后端服务（GoFrame v2），前端 ui/ 仅在接口契约相关处提及 权威来源：本 wiki 以仓库最新代码为准；document/architecture.md 为早期设计 定稿，部分章节（目录分域、中间件顺序、/v1 版本段等）已被后续演进 取代，差异点在本文档各章中明确标注。 -------------------------------------------------------------------------------- 一、项目定位 -------------------------------------------------------------------------------- 企业级多租户后台管理基座，后端 GoFrame v2 + Element Plus 前端同仓库： * 25 张业务表 → 27 个业务模块，全部平铺实现（auth/index + system7 + data7 + content3 + monitor7 + tool4） * JWT 双令牌认证 + RBAC 权限 + 多租户数据隔离 + 角色行级数据权限（data_scope） * 代码生成器（HTTP + CLI 两种入口，一键产出前后端全套文件与菜单/字典/路由） * 整库迁移器（mysql/pgsql/sqlite/mssql/oracle 五方言互迁） * 常驻定时任务调度器（数据驱动、HTTP/本地处理器双形态、多实例执行锁） * 在线用户 / 服务器监控 / 缓存监控三个无表监控模块 * 操作日志（中间件异步落库）+ 登录日志 + IP 归属地 -------------------------------------------------------------------------------- 二、技术栈与版本（go.mod） -------------------------------------------------------------------------------- Go 1.27.2 GoFrame github.com/gogf/gf/v2 v2.10.3（框架核心） 数据库驱动 contrib/drivers/{mysql,pgsql,mssql,oracle,sqlite}/v2 v2.10.3 （五驱动全部 blank import，运行时按配置切换） Redis contrib/nosql/redis/v2 v2.10.3 + redis/go-redis/v9 JWT github.com/golang-jwt/jwt/v5 v5.3.1 密码 golang.org/x/crypto（bcrypt） Excel github.com/xuri/excelize/v2 v2.11.0 IP 归属地 lionsoul2014/ip2region xdb（IPv4，manifest/data/ip2region.xdb） 图片处理 golang.org/x/image（验证码渲染） 前端 ui/（Vue3 + Element Plus，接口统一 /api/*） -------------------------------------------------------------------------------- 三、顶层目录结构 -------------------------------------------------------------------------------- main.go 服务入口：注册五库驱动 + Redis 适配器 → cmd.Run Makefile run/build/test/vet/fmt/gen(gen-dao,gen-service)/clean api/v1/ 全部请求/响应结构体（单包 v1；注意：URL 中并无 /v1 版本段， 路由 path 直接写作 /api/xxx，见 01 章“路由与注解”） cmd/ generator/ 代码生成器 CLI（go run ./cmd/generator） migrator/ 整库迁移 CLI（go run ./cmd/migrator） internal/ cmd/ 启动编排：cache.Init → 依赖接线 → 路由注册 → 调度器 → 运行 consts/ 业务错误码 / 缓存键 / 上下文键 / 日志类型枚举 controller/ 控制器（单包 controller，薄层，仅转发 service） dao/ 数据访问层（gf gen dao 产物 + 自定义扩展模板挂全局钩子） internal/ dao 内部实现（自动生成，勿手改） logic/ 业务逻辑（单包 logic，每模块一文件 snake_case，同包 init 注册） middleware/ 7 个中间件 + 白名单 + 依赖接线（wire.go） migrate/ 整库迁移引擎（内省/翻译/DDL 渲染/搬运/序列修复） model/ entity/ 实体（gf gen dao 产物） do/ 数据对象 DO（gf gen dao 产物） hooks/ 全局模型钩子（审计盖章/软删改写/租户隔离执行点） router/ 路由注册（router.go）+ gmeta 反射绑定（bind.go）+ 元数据表（meta/） service/ 服务接口层（每模块一文件，手维护，勿整体运行 gf gen service） task/ 定时任务处理器实现（init 自注册到 logic.RegisterJobHandler） templates/ 代码生成器模板（后端 {{ }} 定界；ui/ui2 前端 [[ ]] 定界） utility/ 基础能力包（cache/captcha/crypto/excel/ip2region/jwt/ response/ua/upload） manifest/ config/config.yaml 运行时配置（唯一配置文件） data/ip2region.xdb IP 归属地库 resource/ sql/ 五方言定稿 DDL（mysql 为规范基准，后四份待人工校对） static/ 静态资源（swagger 页面、验证码字体等） swagger/ 本地托管的 API 文档页面 upload/ 上传文件静态服务根（SetServerRoot("resource")） hack/ config.yaml gf gen dao/service 配置（含自定义 dao_index 模板路径） tpl/ 自定义 dao 扩展模板（挂载全局钩子 + Ctx 覆写） golden/ after*/ 接口响应黄金样本（回归比对基线） ui/ 前端工程（Element Plus） document/ architecture.md 早期架构定稿（历史参考） *.sql / 迁移日志 DDL 定稿与迁移实测记录 wiki/ 本开发者文档 -------------------------------------------------------------------------------- 四、27 模块一览（文件名 = 表名去 goframe_ 前缀，snake_case） -------------------------------------------------------------------------------- 域 模块 表 路由前缀 -------- ------------- ---------------------- ---------------------- auth （无表） 写 goframe_login_log /api/login 等顶层 index （无表） 聚合 user/menu /api/index/* system user goframe_user /api/user role goframe_role(+role_menu)/api/role menu goframe_menu /api/menu dept goframe_dept /api/dept level goframe_level /api/level position goframe_position /api/position tenant goframe_tenant /api/tenant data config goframe_config /api/config config_item goframe_config_item /api/config/item param goframe_param /api/param dict goframe_dict /api/dict dict_item goframe_dict_item /api/dict/item notice goframe_notice /api/notice city goframe_city /api/city（别名 /api/area） content article goframe_article /api/article category goframe_category /api/category（树形） link goframe_link /api/link monitor operation_log goframe_operation_log /api/oper/log login_log goframe_login_log /api/login/log job goframe_job /api/job job_log goframe_job_log /api/job/log online_user （无表，Redis） /api/onlineUser server_monitor （无表） /api/server cache_monitor （无表，Redis INFO） /api/cache tool example goframe_example /api/example file_template goframe_file_template /api/file/template generator （information_schema） /api/generator upload （resource/upload） /api/upload 关联表不单列模块：user_role 归 user logic；role_menu 归 role logic。 -------------------------------------------------------------------------------- 五、常用命令 -------------------------------------------------------------------------------- go build ./... 编译 go test ./... 测试 go vet ./... && gofmt -l . 静态检查与格式化检查 go run main.go 本地运行（:8000） go build -o bin/admin-server.exe main.go 编译产物 gf gen dao -c hack/config.yaml 表结构变更后刷新 dao （service 手维护，勿运行 gf gen service） 代码生成（详见 07 章）： go run ./cmd/generator -tables "goframe_order|订单表" # 一键生成 go run ./cmd/generator -tables "goframe_order|订单表" -preview # 仅预览 go run ./cmd/generator -tables "goframe_order|订单表" -batch # 批量统计 整库迁移（详见 08 章）： go run ./cmd/migrator -src-type=mysql ... -dst-type=pgsql ... [-drop-target-first] 重启（Windows，端口 8000，见 document/启动命令.txt）： netstat -ano | findstr ":8000" | findstr LISTENING taskkill /F /PID go build -o bin/admin-server.exe main.go && ./bin/admin-server.exe -------------------------------------------------------------------------------- 六、环境依赖 -------------------------------------------------------------------------------- MySQL 127.0.0.1:3306 root/root 库 easygoadmin.goframe.elevue （库名含点；DDL 引用需反引号；定稿脚本 document/easygoadmin.goframe.elevue.sql） Redis 127.0.0.1:6379 （不可用时自动降级进程内存，见 02/06 章） 测试账号 admin / admin123（超管，角色 ROLE_SUPER_ADMIN） 静态访问 /upload/** 由 SetServerRoot("resource") 提供 API 文档 GET /swagger（本地 Redoc）；OpenAPI 原生 GET /api.json 健康检查 GET /api/health（免登录） -------------------------------------------------------------------------------- 七、文档索引 -------------------------------------------------------------------------------- 00_总览与目录索引.txt 本文件 01_系统架构设计.txt 分层调用链、启动流程、路由绑定、统一响应、全局钩子 02_中间件与请求处理链.txt 7 中间件逐一说明、白名单、限流、演示模式 03_认证授权与多租户.txt JWT 双令牌、登录闭环、RBAC、数据权限(data_scope)、 租户隔离、在线用户登记 04_模块开发规范与CRUD基座.txt 七件套、gmeta 注解、ModuleSpec 声明式基座、字典文本 05_共享能力层与文件富文本.txt base.go 能力清单、上传两段式、[IMG_URL] 契约 06_监控体系与在线用户.txt 在线用户/服务器/缓存监控、操作日志、登录日志 07_代码生成器.txt HTTP+CLI、模板体系、副作用（菜单/字典/路由）、保护策略 08_数据库迁移.txt migrator 五阶段、方言渲染器、数据搬运、序列修复 09_定时任务调度.txt 调度器、执行策略、执行锁、task 包、内置任务 10_配置参考.txt config.yaml 全键注释、环境变量覆盖、部署要点与拓扑图 11_API接口清单.txt 全部路由（方法/路径/权限/日志）按模块清单 12_数据模型与表清单.txt 25 表清单、ER 关系图、13 个唯一索引、枚举约定、 租户表清单、大表注意、建表变更工作流 13_开发FAQ与排障.txt 按主题分组的 34 个常见问题（路由/认证/数据/文件/ 任务/缓存/生成器/迁移/工程） 14_核心模块实现详解.txt index/role/menu/user/tenant/dict/city/config 等 高频模块的实现级细节（编码规则、缓存清理链、 开户事务、城市编解码等） 15_缓存键与失效策略.txt 缓存分层图、Redis 键全集（TTL/读写方）、主动失效 点清单、进程内缓存、TTL 设计原则 16_测试与质量保障.txt 静态门禁、黄金样本回归规范（录制参数/三类归因）、 运行期探针、测试补齐建议、变更回归映射、发布清单 17_安全设计专题.txt 威胁→控制总表、认证/授权/租户/文件安全链、 部署安全基线、已知边界与取舍 18_扩展开发与变更管理.txt 按变更类型的 checklist（新接口/字段/模块/中间件/ 任务/dao/配置）、逃生舱挂点、前端遗留与未启用项清单、 封板变更纪律 -------------------------------------------------------------------------------- 八、图示索引（ASCII 图分布在各章） -------------------------------------------------------------------------------- 01 §1.1 系统总架构图（分层 + 组件） 01 §1.2 模块依赖方向图（允许/禁止的依赖） 02 §12 请求处理时序图（中间件→业务→缓存/DB + 日志异步落库） 03 §3.1 登录时序图 03 §3.2 令牌生命周期状态图 03 §3.3 RBAC 授权链路图 04 §4.5 模块文件结构图（四件套职责） 04 §4.6 CRUD 流水线流程图（Page/Add/Update/Delete 落点） 05 §2.7 上传两段式流程图 05 §3.3 富文本 [IMG_URL] 转换流图 06 §1.5 在线会话生命周期图 07 §4.1 生成器 writeFile 落盘决策图 07 §4.2 生成器总体流水线图 08 §3.1 迁移五阶段流程图 08 §3.2 数据搬运循环图（主键游标分页） 09 §5.1 调度执行流程图 09 §5.2 任务状态机 10 §18.1 部署拓扑图 12 §2 ER 关系图（25 表逻辑关系） 15 §1 缓存分层图（进程内 / Redis / 数据库）