通用后台管理框架手册
这是一份框架级手册 —— 讲的是"这个框架提供了哪些模块、每个模块怎么配、怎么用", 不讲业务。你把自己的业务模块接上来,就是你的后台。
开源地址
本项目已开源: github.com/leapar/rapid-admin —— 包含 Go 后端、React 管理端、JS SDK 与这本手册的完整源码,欢迎 Star / Issue / PR。
这份手册是什么
server/ 下的后台 API 是一套通用后台管理框架:鉴权、权限、缓存、审计、通知、
定时任务、可观测性这些"每个后台都要有、又每个后台都要重写一遍"的东西,
框架层已经写好并且配好了默认值。
框架层一共有 51 个模块(internal/pkg/ 下一级目录),本文档给每个模块一份
功能 / 配置 / 使用方法三段式说明,外加 51 个可以直接跑起来的示例。
主要功能
51 个模块归成八组:
| 组 | 覆盖的能力 | 章节 |
|---|---|---|
| 基础设施(17) | 统一响应体 / 错误码 / 参数校验 / 分页 / 分布式 ID / 时间 / 日志 / 指标 / 链路 / 版本协商 / 灰度 | 基础设施 |
| 存储与缓存(5) | 两级缓存(L1 LRU + L2 Redis)、KV 计数与滑动窗口、加密字段盲索引、对象存储、音视频转码 | 存储与缓存 |
| 安全与合规(14) | JWT 签发与吊销、资源级鉴权、Casbin 策略、字段级加密、KMS、请求脱敏、HMAC 防重放、幂等键、限流、登录锁定、异常登录检测、登录二次验证(MFA)、数据范围(行级权限)、字段级可见性 | 安全与合规 |
| 审计(3) | PII 访问审计(谁看了完整手机号)、密钥使用审计、短信发送审计 | 审计 |
| 消息与通知(9) | 站内信与通知中心、SSE 推送、App 推送、短信、邮件、权限失效广播、模板审核、发送限流 | 消息与通知 |
| 调度与可观测(3) | 定时任务(代码注册 + DB 覆盖 + 分布式锁)、平台内置任务、慢 SQL 报警 | 调度与可观测 |
| 业务扩展(1) | 动态业务集合:用户自己设计业务表,菜单 / 接口 / 权限码 / 列表页全自动 | dynx |
| 接口文档(2) | OpenAPI 3.0 自动生成 + Swagger UI、这一本手册的构建与内嵌 | Swagger UI / 手册 |
落到日常开发里,它替你把这些"每个后台都要有、又每个后台都要重写一遍"的东西做完了:
- 登录态 —— JWT 签发 / 续期 / 吊销 / 强制下线;access 与 refresh 类型隔离 (refresh token 拿到业务接口上会被拒);改密码即踢下线。
- 权限 —— 接口级 RBAC + 资源级 ReBAC + 多身份切换;权限码从数据库下发, 前端按同一份数据渲染按钮与菜单,不必两边各写一遍。
- 数据安全 —— 手机号 / 身份证 / 银行卡字段级 AES-256-GCM 加密; 盲索引让加密字段也能精确查询与模糊搜索;日志与响应按需脱敏。
- 合规 —— 谁在什么时候看了完整手机号,有审计记录可查。
- 可靠性 —— 幂等键防重复提交、滑动窗口限流、短信三道闸、登录失败锁定、 熔断与超时(中间件链自带)。
- 可观测 —— 分天分级别日志、Prometheus 指标、OpenTelemetry 链路、慢 SQL 报警; 一个 trace id 把请求、SQL、日志串起来。
- 交付形态 —— OpenAPI 自动生成;Swagger UI 与这一本手册都
go:embed进二进制, 部署不需要额外进程、不需要外网。
优势
- 不接业务就能用。 框架层不 import 任何业务包(有测试守着这条硬约束): 你把自己的业务包删掉,框架层照样编译得过、跑得起来。
- 配错会响。 每个配置项要么有安全默认值,要么漏配即报错 / 显式降级 ——
没有"静默走一条你不知道的路"的开关(
job.timezone这种影响时间语义的除外, 它有"必须显式配"的检查)。 - 每个模块都有能跑的示例。 51 个
go run ./examples/<模块名>直接看效果, 不用读源码拼初始化顺序;手册里引用的代码段就是这些示例。 - 机械化的"文档不撒谎"。 手册结构漂移有
scripts/check_docs_links.py守着 (SUMMARY 收录 / 链接可解析 / 引用的包与示例都真实存在); 框架原语的可达性有internal/guard守着(写了但没人调用的包会红)。 - 换名字就能用。 品牌名、文档标题从
branding:配置下发,不在代码里写死 —— 这个框架的设计前提就是"改个 yaml 就能变成你的平台"。 - 不装中间件也能跑。 Redis 可选(自动降级到进程内实现)、MySQL 可换 SQLite、 测试与示例用内存库;单机开发、跑示例、跑单测都不需要额外服务。
- 嵌入式交付。 Swagger UI 与手册都进二进制:离线可读、版本由仓库说了算, 不多一个第三方 Go 依赖。
怎么读
| 你是谁 | 从哪读起 |
|---|---|
| 第一次接触这个框架 | 快速开始 → 框架约定 |
| 要接一个新业务模块 | 框架约定 → 权限 → 审计 |
| 要改某个框架模块的行为 | 直接跳到该模块那一章 |
| 只是想知道"有没有我要的东西" | 包速查表 |
| 想看代码怎么跑 | 示例目录 |
文档与代码的关系
文档里出现的每一段代码,都是能跑的。
- 每章的「使用方法」小节引用的完整示例在
server/examples/<模块名>/main.go,go run ./examples/<模块名>就能看到输出。 - 本手册写作时的纪律:先有能跑的示例,再有文档。示例本身由
server/examples/examples_test.go守着(新增框架模块却忘了写示例 ⇒ 测试红)。
server/
├── internal/pkg/<模块名>/ # 框架模块本体
├── examples/<模块名>/main.go # 该模块的最小可运行示例(本文档引用它)
└── docs/ # ← 你正在读的手册
三个贯穿全书的前提
- 配置全部有默认值。 不配也能跑;配错了会显式报错或显式降级,
不会静默走一条你不知道的路。(例外:
job.timezone这种,配错会让任务在 错误的时间跑 —— 所以它有"必须显式配"的检查。) - 框架模块不依赖业务。
internal/pkg/里没有任何一个包 importinternal/service/internal/model/internal/api/cmd—— 这是examples/examples_test.go里的漂移网在守的硬约束。 你把自己的业务包删掉,框架层照样编译得过、跑得起来。 - 平台名是配置项,不是常量。 品牌名、Swagger 标题都从
branding:配置下发,不在代码里写死 —— 这个框架是要被"换个名字就能用"的。
环境要求
| 项 | 版本 |
|---|---|
| Go | 1.22+ |
| 数据库 | MySQL 8(示例与测试用 SQLite,不真连) |
| 缓存 | Redis 7+(没有也能跑,框架层自动降级到进程内) |
| 媒体处理 | ffmpeg / ffprobe(只有 media 模块需要) |
怎么本地读这本手册
cd server/docs
npm ci # 装 honkit 与插件(第一次要装)
npm run build # = honkit build . site → 产物在 site/
npm run serve # 本地预览,带热重载 → http://localhost:4000
在 server/ 下还有一层封装(源变了才重建、跟二进制联动):
make docs # 源变了才重建(honkit);没变直接跳过
make docs-force # 强制重建
make docs-check # 只检查产物是否与源同步(落后则退出码 1)
不想装工具也行 —— 这些 .md 就是普通 Markdown,任何编辑器都能读。
服务跑起来之后,手册也在 http://127.0.0.1:8888/docs/index.html:
它是用 go:embed 打进二进制的,部署时不需要 node 也不需要外网。
细节见 框架手册。