go-admin

基于golang的后台管理系统，力求适中简化后台开发过程，满足中小项目开发需要。 使用到的主要技术框架： Gin、TypeScript、React18、Ant-design5等

备注：本文档中，如果没有特殊明确，app目录均是指app/app/的第二层目录

关于前端技术我解释下：

1. 由于业务和环境的变化，原本vue2.0前端的维护压力越来越大。再三考虑后，使用React对前端进行了重构，借此也对golang接口端的各种问题进行了集中处理。
2. vue2.0版的最终完整版本，我单独设置了一个分支，该分支仅做永久备份，不再进行更新和维护。后续将只会迭代新的react版
3. react版分为内部版和开源版，内部版源码不对外开放，但为了开源版的完整性，我借用了第三方开源项目框架Hooks-Admin 来实现。
   1. 所有涉及业务接口的页面，都是从内部版完整迁移到这个框架，这些页面一行代码也没改
   2. 该框架原本使用的是ant-design4.x，为了兼容业务页面，我变更为5.x，框架本身针对性的做了一些调整
   3. 最终目的是让迁移的页面能在不改代码的情况下正常运行，而框架本身的基础功能非必要我不做调整
   4. 该开源框架本身其实已经很老，很多细节实现上也需要完善或者重构，由于个人精力有限，这个只能是使用者根据自身情况自行迭代完善了。

初衷：
有很多开源的go-admin，但其实都是在别的开源项目的基础上各种迭代的，代码冗余，功能冗余，结构上也不尽人意。
为了满足个人日常需要（统计数据、中小单体项目开发等），我经过多个项目的磨合，对该项目做了大量的精简和调整，也对很多功能做了重新规划和设计。
对很多人而言，仅仅需要最基础的功能，剩下的根据需要自行迭代，而这套框架也刚好满足你。

我的开发准则：
大道至简

在线体验：
go-admin react开源版入口

go-admin vue2.0版入口(不再更新)

内置两个默认账户：
账户：admin 密码：123456 顶级账户
账户：test 密码：123456 菜单权限受限的账户

注：：该项目没有任何商业行为，只作为公开分享和交流，请友善体验，不要非法攻击该在线地址。所有功能对外开放，期间可能有小伙伴无意间操作导致页面显示异常，我发现后会及时恢复数据库，或者可以发Issues提醒我处理。

项目本身功能细节很多，这里我把我认为需要表述的功能介绍下，剩下的大家进一步看代码来逐步理解吧

1. 项目结构

前后端都放在一个项目了，对于中小项目，这个管理反而会很方便。
其实它本质还是前后端分离。
这里我解释下几个主要目录

1. 后端（golang端）：
   1. 所有业务内容，均在app根目录下完成，而该目录下，分为3个子目录：
      1. admin子目录：后台管理系统通用功能，能够确保框架正常运行的基础业务，如登录、日志、系统管理、菜单等等
      2. app子目录：个性化业务层，也就是你具体业务均放在该目录下，大多数情况下，你的所有业务都是在该目录下完成的，
      3. plugins子目录：存放一些独立插件功能，方便根据自身需要选择删掉或者增加。如消息管理、文章管理等等
   2. 上面虽然说，一般情况下都是在第二层app子目录中完成业务，但一些业务常量和国际化为了方便统一管理，我将其归纳到config/base目录中，自己根据已有的内容，根据业务需要在其中添加就行。
      1. 国际化默认都是中文的，要对不同语言翻译，就得在config/lang目录中多语言翻译了
      2. 目前框架多语言只支持中英文，如果需要根多语言，只需要在core/lang/lang.go中添加需要的语言就行
2. 前端(ts+react18+ant5+vite+xxx)
   1. web目录是前端根目录，完全独立，可以独立开发和部署。除了该目录，剩下的都属于后台接口的
   2. 同后端目录功能类似，前端的业务目录主要有两个：
      1. src/api目录：用于存放和后端交互的业务接口，其中也分为三个子目录：admin、app、plugins
      2. src/views目录：存放所有业务页面，其中也分为三个子目录：admin、app、plugins
   3. 前面我提到过，目前我开源的react版，业务页面是原封不动的迁移进来的，也就是说，src/api目录中的内容和我内部版是完全一样的，而src/views目录除了其中的/admin/sys/login，其余也是完全一样的

2. 当前主要功能

基础功能：

• 登录身份鉴权，支持session和jwt两种方式、支持单点登录
• 部门、岗位、角色（子账户）、管理员等基本通用功能
• 数据权限管理，该功能虽已完成，因使用频率低，暂未调试 [后续完善]
• 字典管理、业务参数管理、登录日志、操作日志等
• 根据模板一键生成/下载/预览前端页面以及后端相应业务代码，满足常用的增删改
• 插件化管理，尽可能独立化每个功能
• 支持mysql
• 接口支持多语言i18n
• 支持后端接口自动扫描及录入

扩展业务功能（我简单实现的一些基础业务功能，可进行二次开发）

• app用户管理，包括对应配置管理里
• 等级管理
• 账变记录
• 国际区号
• 插件（基本的CMS内容管理、App安装包管理、消息管理）

备注：截止目前，我也不打算提供定时任务和swagger功能，对我而言，我认为完全没必要。首先定时任务和后台耦合，每次后台发布，很容易引起定时任务的异常，定时任务完全可以搞成一个独立的脚本去运行彻底解耦。而swagger我只感觉鸡肋，除了给自己增加工作量，眼前还没发现任何优势。这两个功能谁如果需要，完全可以自行在现有框架中加进去。

3. 遵守规则

1. 数据库表
   1. 分为3类表：
      1. 系统基础表，以admin_子业务名_xxx为前缀，后面衔接模块业务名
      2. 插件表，以plugins_子业务名_xxx为前缀，后面衔接模块业务名
      3. 主业务项目，以app_子业务名_xxx为前缀，后面衔接模块业务名
   2. 这里我简单举例说明下，比如app_user_level，表示我是要开发自己的业务，需要用app标记，而具体的子业务是user，具体功能是level，直到子业务的命名一定要规范，这是为了后续一键生成代码体验更好
2. 尽可能按照已有功能的文件结构和命名方式来开发项目，模板本身就是按照该规则实现的，尽量约束自己的开发范围
3. 注释规范：因为接口同步需要录入接口功能说明，每个方法前都需要按规范写上注释（功能说明），尤其路由接口上，规范是：// 方法名 功能说明
4. 按钮权限规范：菜单管理中，会涉及到按钮的权限配置，此时你配置的权限内容要和页面中permission属性配置内容保持一致，命名规则最好按我这样：业务名:包名:作用，同样以app_user_level表为例，新增按钮权限命名为：app:user_level:add；删除按钮权限命名为：app:user_level:del``更新按钮权限命名为：app:user_level:edit；查询权限命名为：app:user_level:query。权限这个很灵活，你根据自己实际场景来尝试，比如有时候你可以不用在页面设置permisson，一样能达到权限控制效果
5. 菜单管理中，新添加的目录或菜单，其路由路径一定要满足目录/菜单层级逻辑，这牵涉到后面主页面左侧的体验，这个其实也是目前此类功能的通用规则。

4. 部署

分为数据库、后端、前端部署

4.1 数据库部署

1. 我亲测的环境：10.7.3-MariaDB 或者 8.0.40-Mysql
2. 直接自建数据库，用字符集：utf8_mb4、排序规则：utf8_mb4_bin
3. 建好数据库后，直接把我根目录的sql脚本app.sql导入即可

4.2 后台接口部署与启动

1. 环境：golang版本-1.23.2
2. 编译项目，项目根目录执行如下：

go mod tidy

# 直接编译
go generate && go build -a -o go-admin-api main.go

# 交叉编译为linux amd64：
go generate && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -o go-admin-api main.go

注⚠️：go generate命令一定要执行（无论打包前还是本地运行），它可以扫描保存你新增的路由，用于后续接口同步
3. 项目根目录，找到conf/，可以直接再settings.yml中配置数据库，或者可以拷贝一份，重新命名，比如：settings.dev.yml，具体的配置信息，请自行去文件中参考，里面写的很详细，我这里就不再解释了 4. 启动项目，参考如下两种方式：

# 将会默认读取conf/目录中settings.yml配置，并启动接口
./admin server

# 读取自定义配置
./admin server -c=config/settings.dev.yml

4.3 web页面编译和部署

1. 依赖安装：

cd ./web
# 常规安装
npm install

# 上面不灵的话，加上--force 或者 --legacy-peer-deps
npm install --force
npm install --legacy-peer-deps

# 注：由于开源版新旧包依赖问题，导致依赖安装时，需要始终使用--legacy-peer-deps,比如安装md5：
npm install --legacy-peer-deps md5

2. 本地启动：

npm run dev

浏览器打开：http://127.0.0.1:1688

3. 生产编译：

npm run build:prod

6. 代码生成功能

1. 该功能用好了可以极大减少代码开发效率
2. 整体上的使用步骤就是，先把数据库表导入到系统，然后编辑每个字段的规则，保存。接着就是你下载代码还是直接生成到你代码里都行
3. 前端生成位置，需要你在配置中指定
4. 生成的golang文件中，会有一个router.go.bk文件，具体我还是用例子说明吧：
   1. 比如你要针对app_user_level表
   2. 当你第一次在app子目录中生成第一个子业务user时，也就是说原先app目录下没有user目录
   3. 你生成代码后，会自动产生个user目录，该目录下的router目录中会有个router.go.bk文件，这时，你把.bk后缀去掉
   4. 然后回到app目录下，在init.go文件中，按照已有的样例，把自己的业务路由append加上去，也就是注入路由
   5. 至此你的业务模块就能和项目框架关联上了

7. 接口数据同步

1. 接口数据同步，可以将当前程序中的所有接口录入数据库，方便后续从后台绑定菜单，具体可以查看下一节讲述
2. 我的目的是能够自动扫描注释，然后将接口和注释自动录入库中，但这会衍生一个问题，注释的扫描需要源码文件，但程序发布后是没法扫的。为了解决这个问题，我目前是使用go generate命令在每次打包、运行前，生成一个接口常量文件。
3. 有了最新接口常量文件后，即可参与到程序编译，程序启动后，后台点击接口数据同步即可完成和库的对接。
4. 具体和权限相关的操作，请查看下文

8. 子账户权限分配功能

如果你想让某个管理员只能操作指定的菜单，那就需要该功能了，具体这样逻辑：

1. 先角色管理菜单中，创建一个角色，并指定该角色能操控哪些菜单
2. 给你指定的管理员分配上刚创建的角色
3. 这时，那个管理员登录后，就只能看到你刚分配的菜单了
4. 你会发现，此时点击菜单会提示无权限，这是因为还没给菜单分配对应的接口，无法获取相应数据
5. 为了安全，我后台服务端是需要根据角色判断该管理员是否有权限访问接口的，因此，接口需要和菜单绑定，具体需要这样操作
   1. 在接口管理中，你点击接口数据同步，此时服务端会通过Handler将所有接口信息录入到表中
   2. 你在菜单管理中，将接口绑定到对应菜单/按钮上，
   3. 此时，那个管理员就能访问他的菜单了，而其余菜单，哪怕他跳过页面去调试接口，也会提示无权限的。
6. 之所以要点击接口数据同步是因为，新发布的项目，可能程序中新增了接口，但库中没有捕获到；也有可能新部署的程序删掉了某些接口。这时候点击同步，可以自动删除表中无效接口并增加程序新增的接口。这样就方便你绑定菜单了。
7. 我没有在程序启动时，自动去录入接口，是因为不喜欢那种方式，总感觉那样耦合度太高，容易出问题。还是直接在页面上操作，不论成功还是失败，一目了然。

9. 总结

说实话，这个开源的react前端无论体验和代码实现上，都还有很大提升空间，包括需要使用的技术等等都有很多地方可以替代下，这些更改只能是留给使用者来酌情调整了，我也会抽时间尽量把一些严重的页面问题给完善下。

这里只是大概讲了下基本情况，具体更多内容，还是需要大家在使用中一点点去发现。

感谢

go-admin-team
flipped-aurora
Hooks-Admin