216 lines
14 KiB
Plaintext
216 lines
14 KiB
Plaintext
================================================================================
|
||
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 <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 / 数据库）
|