企业官网建设流程全解析

ApiManager 是一款基于 Go + Gin 编写的在线 API 文档管理工具，帮助中小团队快速完成接口文档的编写、维护与存档。它的数据库设计非常值得新手学习：整个系统只用了4 张核心表，却通过一个「接口参数 JSON 存储」的巧妙方案，把任意数量的请求参数装进了单个字段里。这篇文章带你逐表拆解 db.sql 中的表结构，看懂这套轻量级数据库设计背后的取舍。

4张核心表一览：极简但不简陋

打开数据库初始化脚本 db.sql，你会看到完整的表结构只有 4 张：

整个库统一使用utf8字符集，表结构定义在 db.sql，配套的 Go 数据模型分别位于 app/models/api.go、app/models/cate.go 和 app/models/user.go。

api 表：一张表承载接口的全部信息

api表是 ApiManager 数据库设计的灵魂，一行记录就是一个接口。关键字段如下：

几个值得注意的实战细节 💡：

• 软删除：Delete()只是执行update api set isdel=1（见 app/models/api.go），数据不落地删除，随时可恢复，这也是所有查询都带WHERE isdel=0的原因。
• 操作留痕：列表查询时会LEFT JOIN user取login_name，界面上"Last modify: root 2021-03-07"正是来自lastuid+lasttime两个字段。
• 一条 SQL 批量排序：拖拽排序时通过CASE WHEN一条语句更新全部ord值，避免逐行 UPDATE（app/models/api.go）。

接口参数 JSON 存储方案：单字段替代参数明细表

这是全文最值得学习的部分。很多系统会为"参数"单独建一张明细表（一行一个参数），但 ApiManager 选择了用 JSON 把参数数组序列化后存进parameter单字段。

写入流程（后端）：前端提交 5 组平行数组，控制器用json.Marshal一次序列化后落库（app/controllers/api.go）：

pars := params{ ParamName: apiRequest.ParamName, // 参数名 ParamType: apiRequest.ParamType, // 参数类型 ParamCate: apiRequest.ParamCate, // 参数分类 ParamDefault: apiRequest.ParamDefault,// 默认值 ParamDes: apiRequest.ParamDes, // 参数描述 } jsonBytes, _ := json.Marshal(pars)

库里实际存的样子（以"用户注册"接口为例）：

{ "param_name": ["login_name", "password", "sms_code"], "param_type": ["string", "string", "string"], "param_cate": ["query", "query", "query"], "param_default": ["", "", ""], "param_des": ["用户登录名", "用户密码", "短信验证码"] }

5 个数组按下标一一对应，第 i 个元素拼起来就是参数表的一行。

读出流程（前端）：页面加载时JSON.parse还原数组，逐行渲染成 Request Parameters 表格（app/static/common.js）。编辑时走同一个函数getApiParamsViewForEdit，直接还原成表单输入框。

这种接口参数 JSON 存储方案的好处很明显：

• ✅表结构稳定：接口有 3 个还是 30 个参数，都不影响表结构，无需改表；
• ✅读写都只碰一行：新增/复制/编辑接口各只需一条 SQL，DuplicateApi甚至能直接INSERT...SELECT整行克隆（app/models/api.go）；
• ✅对文档工具足够：参数不需要被 SQL 条件检索，JSON 里的灵活性正好用上。

代价是无法用 SQL 直接查询"某个参数属于哪个接口"——但对于一个面向团队的文档系统，这是完全可以接受的取舍。用 JSON 换灵活性，是轻量工具数据库设计中非常经典的手法。

user 与 auth 表：三级角色的权限设计

user表用一个role字段区分三级角色：1超级管理员、2管理员、3游客；login_name上有唯一索引保证账号不重复。密码字段login_pwd为 32 位定长，存放的是 MD5 摘要（登录逻辑见 app/models/user.go）。

auth表只有两个字段：uid（用户）+aid（接口分类）。它解决的是普通管理员的细粒度授权——超级管理员天然拥有全部权限，而管理员登录后只读取auth表中属于自己的aid列表，就能限定其只能看到被授权的那几个分类。

快速上手：如何体验 ApiManager 的数据库结构

想亲手验证这套表结构，三步即可：

1. 获取源码

git clone https://gitcode.com/gh_mirrors/api/ApiManager

2. 建库并导入表结构：在 MySQL 中创建api_manager数据库，导入 db.sql，4 张表即刻就绪；
3. 配置连接后启动：修改 config/config.ini 中的数据库连接信息，执行./run.sh start，浏览器访问http://your_host:8000（默认账号root/ 密码123456）。

登录后新建一个分类和接口，再用客户端查询api表，你就能亲眼看到parameter字段里那份整齐的参数 JSON。

小结

ApiManager 用 4 张表撑起了一套完整的接口文档管理系统，三个设计点尤其值得借鉴：

• 📌api单表承载全量接口信息，配合isdel软删除与lastuid/lasttime留痕；
• 📌接口参数 JSON 存储：5 组平行数组序列化为 JSON 存入单字段，结构稳定、读写高效；
• 📌role+auth组合授权：粗粒度角色与细粒度分类权限各司其职。

这套"够用就好"的数据库设计，既是团队文档工具的合适形态，也很适合作为学习 Gin 框架时研究数据模型的入门样本。