1 项目说明
1.1 简介
01.常用信息
a.介绍
Gin-Vue-Admin 是一个全栈管理框架，专为快速开发Web应用程序而设计，具有完整的前后端分离架构。
基于Go (Gin) 和Vue.js构建，提供了一个全面的开发平台，具备自动化代码生成、AI辅助开发和企业级安全特性。
b.线上部署
GitHub地址: https://github.com/flipped-aurora/gin-vue-admin
GitCode地址: https://gitCode.com/flipped-aurora/gin-vue-admin
Gitee地址: https://gitee.com/pixelmax/gin-vue-admin
在线演示: http://demo.gin-vue-admin.com/
用户名：admin
密码：123456
c.项目定位
Gin-Vue-Admin 作为企业级管理系统的基础框架，专注于为开发者提供：
🚀 快速开发: AutoCode生成系统，可在1分钟内生成完整的CRUD功能
🔒 企业安全: JWT认证 + Casbin RBAC授权的双重安全保障
🔧 高度灵活: 动态路由、菜单管理和API配置
📚 完整文档: Swagger API文档自动生成
☁️ 云原生: 多云文件存储支持(七牛云、阿里云、AWS S3)
🗄️ 多数据库: 支持MySQL、PostgreSQL、SQLite和MSSQL
该系统主要面向构建管理后台、内容管理系统和需要用户管理及权限控制的业务应用的开发者。
02.常用信息
a.环境要求
Node.js: ≥ 18.16.2
Go: ≥ 1.22
MySQL: ≥ 5.7 (引擎必须为 InnoDB)
Git: 版本控制工具
推荐使用 Docker 创建 MySQL 数据库以确保环境一致性
b.前端技术栈
技术 版本 描述
Vue.js 3.3.4 渐进式JavaScript框架
Element Plus 2.3.8 Vue 3 UI组件库
Pinia Latest 状态管理(替代Vuex)
Vue Router Latest SPA路由与动态路由
Vite Latest 构建工具和开发服务器
c.后端技术栈
技术 版本 描述
Go ≥ 1.22 编程语言
Gin 1.9.1 高性能Web框架
GORM 1.25.2 ORM库，支持自动迁移
Casbin Latest 访问控制库(RBAC)
d.数据库支持
数据库 版本要求 说明
MySQL ≥ 5.7 主数据库，InnoDB引擎
PostgreSQL ≥ 9.6 关系型数据库替代方案
SQLite Latest 嵌入式数据库选项
MS SQL Server Latest 微软数据库支持
Oracle Latest 企业级数据库支持
e.缓存与存储
Redis: 缓存和会话管理
七牛云: 对象存储服务
阿里云OSS: 阿里巴巴云存储
AWS S3: 亚马逊Web服务存储
f.开发工具
Swagger: API文档自动生成
Viper: 配置管理
Zap: 结构化日志记录
fsnotify: 文件系统通知
g.AI集成
LLM APIs: AI辅助代码生成
MCP Protocol: 模型上下文协议，用于AI代理
03.核心功能
a.安全认证系统
JWT认证: 无状态的用户身份验证
Casbin RBAC: 基于角色的访问控制
多点登录控制: 支持单点登录限制
API权限管理: 细粒度的接口访问控制
b.用户权限管理
用户管理: 系统管理员分配用户角色和权限
角色管理: 创建权限控制对象，支持API、菜单、按钮权限分配
菜单管理: 动态菜单配置，实现不同角色不同菜单
按钮权限: 页面级别的操作权限控制
c.快速开发工具
AutoCode生成器: 1分钟生成完整CRUD功能的代码生成器
表单生成器: 基于 Variant Form 的可视化表单设计
API自动文档: Swagger自动生成API文档
RESTful示例: 标准的RESTful API设计参考
d.文件存储系统
多云存储: 支持本地、七牛云、阿里云、腾讯云存储
分片上传: 大文件分片上传功能
断点续传: 文件上传中断后可继续上传
文件管理: 完整的文件上传下载管理
e.系统管理
配置管理: 前台可视化配置文件修改
日志管理: 系统操作日志记录和查询
监控面板: 系统运行状态监控
数据字典: 系统数据字典管理
f.用户界面
富文本编辑器: 内置MarkDown编辑器
条件搜索: 高级搜索功能示例
数据导入导出: Excel数据处理功能
响应式设计: 适配多种设备屏幕
g.插件生态
插件中心 NEW: 基于GVA设计的Go插件中心
微信集成: 微信支付、登录等功能插件
K8s操作: Kubernetes相关操作插件
第三方登录: 多种第三方登录方式支持
04.系统设计
a.图示
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 前端层 (Vue) │ │ 后端层 (Go) │ │ 数据层 (DB) │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ • Vue 3 + Vite │ │ • Gin Framework │ │ • MySQL/PG/... │
│ • Element Plus │◄──►│ • JWT + Casbin │◄──►│ • Redis Cache │
│ • Pinia Store │ │ • GORM ORM │ │ • File Storage │
│ • Vue Router │ │ • Swagger Docs │ │ • Cloud Storage │
└─────────────────┘ └─────────────────┘ └─────────────────┘
b.前端架构 (Vue.js + Vite)
应用启动: main.js - 应用程序引导
路由系统: Vue Router - 动态路由管理
状态管理: Pinia Stores - 全局状态管理
布局系统: Header, Aside, Tabs - 页面布局组件
权限控制: 菜单权限、API权限、按钮权限
组件库: Upload, Select, Export - 通用业务组件
c.后端架构 (Go + Gin)
服务启动: main.go - 服务器引导程序
配置系统: core.Viper - 配置管理系统
认证中间件: middleware.JWT - JWT身份验证
授权中间件: middleware.Casbin - 权限控制处理
API处理器: api.v1 - REST API处理程序
业务服务: service.* - 业务逻辑服务
代码生成: service.AutoCode - 自动代码生成引擎
d.数据架构
主数据库: global.GVA_DB - 主要数据存储
缓存系统: global.GVA_REDIS - 缓存和会话
文件存储: 本地/云端对象存储服务
权限存储: system.CasbinRule - 策略存储
e.认证授权流程
sequenceDiagram
participant U as 用户
participant F as 前端
participant A as API网关
participant S as 业务服务
participant D as 数据库
U->>F: 登录请求
F->>A: POST /base/login
A->>S: 验证用户凭据
S->>D: 查询用户信息
D-->>S: 返回用户数据
S->>A: 生成JWT Token
A-->>F: 返回Token
F->>F: 存储Token
U->>F: 访问受保护资源
F->>A: 请求 + JWT Header
A->>A: JWT验证
A->>S: Casbin权限检查
S-->>A: 权限结果
A-->>F: 返回数据/拒绝访问
f.初始化流程
配置初始化: core.Viper - 加载配置文件
日志初始化: core.Zap - 设置日志系统
数据库连接: initialize.Gorm - 建立数据库连接
数据表注册: initialize.RegisterTables - 注册数据模型
Redis连接: initialize.Redis - 建立缓存连接
路由初始化: initialize.Routers - 设置API路由
服务启动: core.RunWindowsServer - 启动HTTP服务
1.2 环境配置
01.环境准备
a.环境要求
Git: 用于代码版本管理。
Node.js: >= 18.16.2 (推荐使用 LTS 版本)。
Go: >= 1.22 (推荐使用最新稳定版)。
MySQL: >= 8.0，存储引擎必须为 InnoDB。
Redis: >= 6.0 (可选，用于缓存)。
b.分支状态说明
main：🟢 活跃维护，主分支，生产环境推荐。
i18n-dev-new：🟡 更新中，组合式API多语言版本。
v2.4.x：🔴 停止维护，声明式API版本。
i18n-dev：🔴 停止维护，声明式API多语言版本。
c.默认管理员账号
用户名：admin
密码：123456
d.2.4.5版本之前
闭源项目：无任何限制
开源项目：需保留原始协议声明
商业使用：无需额外授权
e.2.4.5版本及以后
个人学习项目：完全免费
企业内部系统（不对外开放，不接入公网）：完全免费
外包项目/对外开放系统：必须获得商业授权
商业盈利项目：必须获得商业授权
02.Node.js 环境安装
a.下载安装 Node.js
访问 Node.js 官网下载并安装 LTS 版本。
推荐版本: Node.js 18.x 或更高版本。
b.验证安装
# 检查 Node.js 版本
node -v
# 检查 npm 版本
npm -v
c.配置 npm 镜像源（可选）
# 设置淘宝镜像源
npm config set registry https://registry.npmmirror.com
# 验证配置
npm config get registry
03.Go 环境安装
a.下载安装 Go
根据您的网络环境选择下载地址：
国际用户: https://golang.org/dl/
国内用户: https://golang.google.cn/dl/
推荐版本: Go 1.22 或更高版本。
b.验证安装
# 检查 Go 版本
go version
# 查看 Go 环境信息
go env
c.配置 Go 模块代理（推荐）
# 启用 Go Modules
go env -w GO111MODULE=on
# 配置模块代理
go env -w GOPROXY=https://goproxy.cn,direct
# 配置私有模块跳过代理
go env -w GOPRIVATE=*.corp.example.com
04.数据库环境
a.MySQL 安装
a.macOS
# 使用 Homebrew 安装
brew install mysql
# 启动 MySQL 服务
brew services start mysql
b.Ubuntu/Debian
# 更新包列表
sudo apt update
# 安装 MySQL
sudo apt install mysql-server
# 启动 MySQL 服务
sudo systemctl start mysql
sudo systemctl enable mysql
c.Windows
访问 MySQL 官网下载安装包。
b.Redis 安装（可选）
a.macOS
brew install redis
brew services start redis
b.Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server
05.开发工具配置
a.VS Code 推荐插件
{
"recommendations": [
"golang.go",
"vue.volar",
"bradlc.vscode-tailwindcss",
"esbenp.prettier-vscode",
"ms-vscode.vscode-typescript-next",
"formulahendry.auto-rename-tag",
"christian-kohler.path-intellisense"
]
}
b.GoLand 配置建议
Go Modules: 确保启用 Go Modules 支持。
代码格式化: 配置 gofmt 和 goimports。
代码检查: 启用 golint 和 go vet。
06.环境验证
a.完成环境安装后，请运行以下命令验证环境是否正确配置：
# 检查 Git
git --version
# 检查 Node.js 和 npm
node -v && npm -v
# 检查 Go
go version
# 检查 MySQL（需要先启动服务）
mysql --version
# 检查 Redis（如果安装了）
redis-cli --version
b.验证结果
如果所有命令都能正常输出版本信息，说明环境配置成功！
1.3 项目初始化
01.快速启动
a.克隆项目
# 克隆主分支代码
git clone https://github.com/flipped-aurora/gin-vue-admin.git
# 进入项目目录
cd gin-vue-admin
b.项目结构概览
gin-vue-admin/
├── server/ # 后端 Go 项目
│ ├── main.go # 程序入口
│ ├── config.yaml # 配置文件
│ └── ...
├── web/ # 前端 Vue 项目
│ ├── src/ # 源代码
│ ├── package.json # 依赖配置
│ └── ...
└── README.md # 项目说明
02.后端服务启动
a.打开后端项目
# 进入后端目录
cd server
# 使用 GoLand 打开（如果已安装）
goland .
# 或使用 VS Code 打开
code .
b.安装依赖
# 添加缺失的模块依赖，移除未使用的依赖
# 该命令会根据 go.mod 文件下载所需的第三方包
go mod tidy
c.启动后端服务
方式一：命令行启动
# 在 server 目录下运行
go run main.go
-----------------------------------------------------------------------------------------------------
方式二：GoLand 启动
在 GoLand 中打开 main.go 文件
点击行号旁的绿色三角形按钮
或使用快捷键 Ctrl+Shift+F10 (Windows/Linux) 或 Cmd+Shift+R (macOS)
-----------------------------------------------------------------------------------------------------
方式三：VS Code 启动
按 F5 或点击调试按钮
选择 "Go: Launch Package"
d.验证后端启动
如果看到以下输出，说明后端服务启动成功：
[GIN-debug] Listening and serving HTTP on :8888
访问 http://localhost:8888/health 检查服务状态。
03.前端应用启动
a.打开前端项目
# 进入前端目录
cd web
# 使用 VS Code 打开
code .
b.安装依赖
# 安装项目依赖
npm install
# 或使用 yarn（如果已安装）
yarn install
# 或使用 pnpm（推荐，速度更快）
pnpm install
c.启动开发服务器
# 启动开发服务器
npm run serve
# 或使用其他包管理器
yarn serve
pnpm serve
d.验证前端启动
如果看到以下输出，说明前端应用启动成功：
App running at:
- Local: http://localhost:8080/
- Network: http://192.168.1.100:8080/
04.数据库初始化
a.访问初始化页面
在浏览器中访问：http://localhost:8080/#/init
b.配置数据库信息
在初始化页面填写数据库连接信息：
数据库类型: 选择 MySQL
主机地址: 127.0.0.1
端口: 3306
用户名: root
密码: 您的数据库密码
数据库名: gva（如果不存在会自动创建）
c.执行初始化
确认所有信息无误
点击 "立即初始化" 按钮
等待初始化完成
d.初始化完成
初始化成功后，系统会：
✅ 创建所有必要的数据表
✅ 插入基础数据（管理员账号、菜单、权限等）
✅ 自动跳转到登录页面
e.默认管理员账号
用户名：admin
密码：123456
1.4 AI助手集成
01.MCP AI助手集成
a.功能说明
通过MCP（Model Context Protocol）让AI编辑工具深度理解GVA项目结构，实现智能化的代码生成和项目管理。
b.版本要求
使用MCP功能需要GVA版本 ≥ 2.8.4。
推荐使用模型：claude > gemini > gpt = kimi。
c.核心特性
智能代码生成：AI自动创建完整的CRUD模板。
智能文件搜索：自动定位相关文件并提供精准修改建议。
自动化流程：一键生成API接口和菜单配置。
上下文理解：AI深度理解项目架构，提供更准确的代码联动。
02.AI编辑工具配置
a.支持的AI编辑工具
Trae
Cursor
Claude Code
Windsurf
Codebubby
其他支持MCP协议的AI编辑器
b.第一步：启动GVA项目
确保你的GVA项目正在运行，MCP服务会自动在 http://127.0.0.1:8888/sse 启动。
c.第二步：配置AI编辑器
在你的AI编辑工具的配置文件中添加以下MCP配置：
{
"mcpServers": {
"GVA Helper": {
"url": "http://127.0.0.1:8888/sse"
}
}
}
d.第三步：重启编辑器
保存配置后重启你的AI编辑工具，等待MCP连接建立，MCP状态显示绿色即表示连接成功。
03.AI助手新能力
a.配置完成后，AI助手将获得以下超能力：
深度理解项目：自动识别GVA项目结构和代码模式。
智能代码生成：根据需求自动生成完整的功能模块。
精准文件定位：快速找到相关文件并提供修改建议。
全栈开发：同时处理前端、后端、数据库的代码生成。
UI自动化：自动配置路由、菜单和权限系统。
b.使用示例
只需要告诉AI："我想创建一个用户管理模块"，AI就会：
自动生成用户表结构。
创建完整的CRUD API。
生成前端管理页面。
配置菜单和路由。
设置权限控制。
06.配置文件说明
a.yaml
mcp:
name: GVA_MCP # MCP服务名称
version: v1.0.0 # 版本号
sse_path: /sse # SSE路径
message_path: /message # 消息路径
url_prefix: '' # URL前缀
## v2.8.6后可用
addr: 8889 # 监听地址 在separate为true时有效 （暂时未实现独立运行功能，敬请期待）
separate: false # 是否隔离 开启以后mcp将不会跟随gva本体启动 建议在生产环境开启
b.自动填写页面参数示例
点击生成后后端会获得MCP模板。
在模板的handle函数中书写业务逻辑即可实现一个简单的mcp工具。
1.5 Swagger
01.Swagger API 文档
a.功能说明
Swagger 是一个用于设计、构建、记录和使用 RESTful Web 服务的开源软件框架。
Gin-Vue-Admin 集成了 Swagger 来自动生成和维护 API 文档。
b.核心功能
API 文档自动生成：从代码注释自动生成文档。
在线测试：直接在浏览器中测试 API。
可视化界面：清晰的 API 结构展示。
实时更新：代码变更时文档自动同步。
02.安装 Swagger
a.方式一：直接安装（推荐）
# 安装最新版本的 swag 工具
go install github.com/swaggo/swag/cmd/swag@latest
b.方式二：使用代理安装
如果遇到网络问题，建议配置 Go 模块代理：
# 启用 Go Modules
go env -w GO111MODULE=on
# 配置国内代理（选择其一）
go env -w GOPROXY=https://goproxy.cn,direct
# 或者使用
# go env -w GOPROXY=https://goproxy.io,direct
# 安装 swag 工具
go install github.com/swaggo/swag/cmd/swag@latest
c.验证安装
安装完成后，验证 swag 工具是否正确安装：
# 检查 swag 版本
swag --version
# 查看帮助信息
swag --help
03.配置 Swagger 注释
a.主程序注释
在 main.go 文件中添加 API 基本信息：
// @title Gin-Vue-Admin API
// @version 1.0
// @description This is a sample server for Gin-Vue-Admin.
// @termsOfService https://github.com/flipped-aurora/gin-vue-admin
// @contact.name API Support
// @contact.url https://github.com/flipped-aurora/gin-vue-admin/issues
// @contact.email [email protected]
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8888
// @BasePath /
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name x-token
func main() {
// 应用程序代码
}
b.API 接口注释
为每个 API 接口添加详细注释：
// CreateUser 创建用户
// @Tags 用户管理
// @Summary 创建用户
// @Description 创建新的用户账号
// @Security ApiKeyAuth
// @accept application/json
// @Produce application/json
// @Param data body request.CreateUserReq true "用户信息"
// @Success 200 {object} response.Response{data=response.UserResponse} "创建成功"
// @Failure 400 {object} response.Response "请求参数错误"
// @Failure 500 {object} response.Response "内部服务器错误"
// @Router /user [post]
func (u *UserApi) CreateUser(c *gin.Context) {
// 接口实现代码
}
c.数据模型注释
为数据结构添加注释：
// User 用户信息
type User struct {
ID uint `json:"id" example:"1"` // 用户ID
Username string `json:"username" example:"admin"` // 用户名
Email string `json:"email" example:"[email protected]"` // 邮箱
Phone string `json:"phone" example:"13800138000"` // 手机号
Status int `json:"status" example:"1"` // 状态：1-启用，0-禁用
}
04.生成 API 文档
a.生成文档
# 在项目根目录（包含 main.go 的目录）下运行，生成 Swagger 文档
swag init
b.生成成功
命令执行成功后，会在项目中生成以下文件：
server/
├── docs/
│ ├── docs.go # 文档数据
│ ├── swagger.json # JSON 格式文档
│ └── swagger.yaml # YAML 格式文档
└── main.go
c.自动化生成
a.您也可以在 main.go 中添加 go:generate 指令来自动化文档生成
//go:generate swag init
package main
b.然后使用 go generate 命令
go generate
05.访问 Swagger 文档
a.启动服务
# 后端服务正在运行：
go run main.go
b.访问文档
# 在浏览器中访问 Swagger UI：
本地访问: http://localhost:8888/swagger/index.html
c.文档功能
Swagger UI 提供以下功能：
API 列表: 查看所有可用的 API 接口。
接口详情: 查看每个接口的参数、响应等详细信息。
在线测试: 直接在页面中测试 API 接口。
下载文档: 下载 JSON 或 YAML 格式的 API 文档。
06.使用技巧
a.接口分组
使用 @Tags 注释对接口进行分组：
// @Tags 用户管理
// @Tags 权限管理
// @Tags 系统设置
b.参数验证
结合 binding 标签进行参数验证：
type CreateUserReq struct {
Username string `json:"username" binding:"required" example:"admin"` // 用户名（必填）
Password string `json:"password" binding:"required,min=6" example:"123456"` // 密码（必填，最少6位）
Email string `json:"email" binding:"email" example:"[email protected]"` // 邮箱（邮箱格式）
}
c.响应示例
提供详细的响应示例：
// @Success 200 {object} response.Response{data=[]model.User} "获取成功"
// @Success 200 {object} response.PageResult{list=[]model.User} "分页获取成功"
d.错误处理
定义常见的错误响应：
// @Failure 400 {object} response.Response "请求参数错误"
// @Failure 401 {object} response.Response "未授权"
// @Failure 403 {object} response.Response "权限不足"
// @Failure 404 {object} response.Response "资源不存在"
// @Failure 500 {object} response.Response "内部服务器错误"
07.高级配置
a.自定义配置
创建 .swaggo 配置文件：
# .swaggo
dir: ./
general_info: main.go
output_dir: ./docs
parse_vendor: false
parse_dependency: false
parse_internal: false
generate_types: false
b.排除特定文件
使用 --exclude 参数排除不需要解析的文件：
swag init --exclude ./vendor
c.指定输出目录
指定输出目录：
swag init --output ./api-docs
08.最佳实践
1.及时更新文档：每次修改 API 后都要重新生成文档。
2.详细注释：为每个接口提供清晰的描述和示例。
3.统一规范：团队内部统一注释格式和命名规范。
4.版本管理：为不同版本的 API 维护对应的文档。
5.测试验证：使用 Swagger UI 测试接口确保文档准确性。
1.6 VsCode
01.快速开始
a.打开工作区
a.推荐使用 VS Code 的工作区功能来管理整个项目
# 进入项目根目录
cd gin-vue-admin
# 使用 VS Code 打开整个项目
code .
b.或者打开预配置的工作区文件
VS Code 工作区。
b.工作区配置
a.创建 .vscode/gin-vue-admin.code-workspace 文件：
{
"folders": [
{
"name": "🔧 Server (Go)",
"path": "./server"
},
{
"name": "🎨 Web (Vue)",
"path": "./web"
},
{
"name": "📚 Docs",
"path": "./docs"
}
],
"settings": {
"go.gopath": "",
"go.goroot": "",
"go.toolsManagement.autoUpdate": true,
"typescript.preferences.importModuleSpecifier": "relative",
"eslint.workingDirectories": ["web"],
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
}
},
"extensions": {
"recommendations": [
"golang.go",
"vue.volar",
"bradlc.vscode-tailwindcss",
"esbenp.prettier-vscode",
"ms-vscode.vscode-typescript-next"
]
}
}
02.必备插件安装
a.Go 开发插件
Go (golang.go)：Go 语言官方插件，提供语法高亮、智能提示、调试等功能。
Go Outliner (766b.go-outliner)：显示 Go 文件的结构大纲。
b.Vue 开发插件
Vue Language Features (Volar) (vue.volar)：Vue 3 官方语言支持，替代 Vetur，提供更好的 TypeScript 支持。
TypeScript Vue Plugin (Volar) (vue.vscode-typescript-vue-plugin)：Vue 文件的 TypeScript 支持。
c.通用开发插件
Prettier - Code formatter (esbenp.prettier-vscode)：代码格式化工具。
ESLint (dbaeumer.vscode-eslint)：JavaScript/TypeScript 代码检查。
Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)：Tailwind CSS 智能提示。
Auto Rename Tag (formulahendry.auto-rename-tag)：自动重命名配对的 HTML/XML 标签。
Path Intellisense (christian-kohler.path-intellisense)：文件路径智能提示。
d.安装插件
使用命令行安装推荐插件：
code --install-extension golang.go
code --install-extension vue.volar
code --install-extension vue.vscode-typescript-vue-plugin
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint
code --install-extension bradlc.vscode-tailwindcss
code --install-extension formulahendry.auto-rename-tag
code --install-extension christian-kohler.path-intellisense
03.运行和调试配置
a.创建调试配置
在项目根目录创建 .vscode/launch.json 文件：
-----------------------------------------------------------------------------------------------------
{
"version": "0.2.0",
"configurations": [
{
"name": "🔧 Launch Server (Go)",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/server/main.go",
"cwd": "${workspaceFolder}/server",
"env": {
"GIN_MODE": "debug"
},
"args": [],
"showLog": true,
"console": "integratedTerminal"
},
{
"name": "🎨 Launch Web (Node)",
"type": "node",
"request": "launch",
"cwd": "${workspaceFolder}/web",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "serve"]
}
],
"compounds": [
{
"name": "🚀 Launch Both (Server + Web)",
"configurations": [
"🔧 Launch Server (Go)",
"🎨 Launch Web (Node)"
],
"stopAll": true
}
]
}
b.创建任务配置
创建 .vscode/tasks.json 文件：
-----------------------------------------------------------------------------------------------------
{
"version": "2.0.0",
"tasks": [
{
"label": "🔧 Build Server",
"type": "shell",
"command": "go",
"args": ["build", "-o", "gin-vue-admin", "main.go"],
"options": {
"cwd": "${workspaceFolder}/server"
},
"group": "build",
"presentation": {
"echo": true,
"reveal": "always",
"focus": false,
"panel": "shared"
}
},
{
"label": "🎨 Build Web",
"type": "shell",
"command": "npm",
"args": ["run", "build"],
"options": {
"cwd": "${workspaceFolder}/web"
},
"group": "build",
"presentation": {
"echo": true,
"reveal": "always",
"focus": false,
"panel": "shared"
}
},
{
"label": "📝 Generate Swagger",
"type": "shell",
"command": "swag",
"args": ["init"],
"options": {
"cwd": "${workspaceFolder}/server"
},
"group": "build",
"presentation": {
"echo": true,
"reveal": "always",
"focus": false,
"panel": "shared"
}
}
]
}
c.运行项目
a.方式一：使用调试面板
按 Ctrl+Shift+D (Windows/Linux) 或 Cmd+Shift+D (macOS) 打开调试面板。
选择要运行的配置：
Launch Server (Go): 仅启动后端服务。
Launch Web (Node): 仅启动前端应用。
Launch Both (Server + Web): 同时启动前后端。
b.方式二：使用终端
# 启动后端（在 server 目录）
cd server
go run main.go
# 启动前端（在 web 目录）
cd web
npm run serve
c.方式三：使用任务
按 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS)。
输入 "Tasks: Run Task"。
选择要执行的任务。
04.Go 环境配置
a.配置 Go 模块代理
为了提高依赖下载速度，建议配置 Go 模块代理：
# 启用 Go Modules
go env -w GO111MODULE=on
# 配置模块代理
go env -w GOPROXY=https://goproxy.cn,direct
# 配置校验和数据库
go env -w GOSUMDB=sum.golang.google.cn
b.VS Code Go 插件配置
在 VS Code 设置中添加以下配置：
{
"go.toolsManagement.autoUpdate": true,
"go.useLanguageServer": true,
"go.gocodeAutoBuild": false,
"go.lintOnSave": "package",
"go.vetOnSave": "package",
"go.buildOnSave": "package",
"go.testOnSave": false,
"go.coverOnSave": false,
"go.formatTool": "goimports",
"go.gotoSymbol.includeImports": true,
"go.gotoSymbol.includeGoroot": true,
"gopls": {
"experimentalWorkspaceModule": true,
"completeUnimported": true,
"usePlaceholders": true,
"deepCompletion": true
}
}
c.安装 Go 工具
在 VS Code 中按 Ctrl+Shift+P，输入 "Go: Install/Update Tools"，选择所有工具进行安装。
05.前端开发配置
a.Prettier 配置
在 web 目录创建 .prettierrc 文件：
{
"semi": false,
"singleQuote": true,
"tabWidth": 2,
"trailingComma": "none",
"printWidth": 100,
"bracketSpacing": true,
"arrowParens": "avoid"
}
b.ESLint 配置
确保 web 目录有正确的 .eslintrc.js 配置文件。
c.VS Code 前端设置
在 VS Code 设置中添加以下配置：
{
"typescript.preferences.importModuleSpecifier": "relative",
"typescript.suggest.autoImports": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},
"eslint.workingDirectories": ["web"],
"vetur.validation.template": false,
"vetur.validation.script": false,
"vetur.validation.style": false
}
06.实用技巧
a.代码片段
创建 Go 代码片段 .vscode/go.code-snippets：
{
"Gin Handler": {
"prefix": "ginhandler",
"body": [
"// $1 $2",
"// @Tags $3",
"// @Summary $2",
"// @Security ApiKeyAuth",
"// @accept application/json",
"// @Produce application/json",
"// @Success 200 {object} response.Response \"成功\"",
"// @Router /$4 [$5]",
"func (a *$6Api) $1(c *gin.Context) {",
"\t$0",
"}"
],
"description": "Create a Gin handler with Swagger annotations"
}
}
b.快捷键配置
在 keybindings.json 中添加自定义快捷键：
[
{
"key": "ctrl+shift+r",
"command": "workbench.action.tasks.runTask",
"args": "🔧 Build Server"
},
{
"key": "ctrl+shift+w",
"command": "workbench.action.tasks.runTask",
"args": "🎨 Build Web"
}
]
c.文件关联
在设置中添加文件关联：
{
"files.associations": {
"*.vue": "vue",
"*.go": "go",
"*.yaml": "yaml",
"*.yml": "yaml"
}
}
07.调试技巧
a.Go 调试
在代码行号左侧点击设置断点。
使用 F5 开始调试。
使用 F10 单步执行，F11 步入函数。
在调试控制台查看变量值。
b.前端调试
使用浏览器开发者工具。
在 VS Code 中安装 "Debugger for Chrome" 插件。
配置浏览器调试。
c.日志查看
使用集成终端查看应用日志。
配置输出面板显示不同类型的日志。
08.性能优化
a.排除文件
在 .vscode/settings.json 中排除不必要的文件：
{
"files.exclude": {
"**/node_modules": true,
"**/dist": true,
"**/.git": true,
"**/vendor": true
},
"search.exclude": {
"**/node_modules": true,
"**/dist": true,
"**/vendor": true
}
}
b.禁用不需要的插件
在工作区中禁用不相关的插件以提高性能。
2 代码生成
2.1 创建包名
01.创建package
点击左侧菜单栏的自动化Package进入页面，点击新增打开抽屉
02.填写信息
抽屉中关键属性为包名，此处填写小写字母开头的驼峰式命名单词，这是你自动化代码的基础包，
所有在创建自动化代码时候选择本package的代码，都会创建在由本功能自动创建出的文件夹下。
此处展示以showGva为例，自动生成的文件目录。
03.完成创建
创建完成后，会在web和server下创建对应的package文件夹，
如下所示 web/src/api/showGva web/src/view/showGva server/api/showGva
内含文件 enter.go server/router/showGva
内含文件 enter.go server/service/showGva
内含文件 enter.go
2.2 使用指南
01.代码生成器
a.功能说明
通过代码生成器可以从现有数据库创建代码，选择数据库中的表，然后生成对应的代码。
b.界面名称与生成结构体
Struct名称（StructName）：结构体名称，位于 server/model 文件夹下，首字母必须大写。
TableName：指定表名（非必填），数据库中生成的与结构体对应的数据表名。
Struct简称（Abbreviation）：简称会作为入参对象名和路由 group。
Struct中文名称（Description）：中文描述作为自动api描述。
文件名称（PackageName）：生成文件的默认名称，使用小驼峰形式命名。
Package（包）：生成的目标包，必选。
业务库（BusinessDB）：选择业务库，可选。
使用GVA结构（GvaModel）：建议选中。
创建资源标识（AutoCreateResource）：可选。
自动创建api（AutoCreateApiToSql）：建议选中。
自动创建菜单（AutoCreateMenuToSql）：建议选中。
自动移动文件（AutoMoveFile）：建议选中。
02.字段界面说明
a.组件内容名称与生成结构体
Field名称（FieldName）：结构体名称，首字母大写。
Field中文名（FieldDesc）：结构体中文名称。
FieldJSON（FieldJson）：golang struct tag json。
数据库字段名（ColumnName）：数据库字段名。
Field数据类型（FieldType）：字段对应golang数据类型。
数据库字段长度（DataTypeLong）：字段数据类型长度。
数据库字段描述（Comment）：数据库字段描述。
默认值（DefaultValue）：数据库字段默认值。
是否必填（Require）：自动创建前后端必填校验。
校验失败文案（ErrorText）：必填校验失败的文案。
是否排序（Sort）：自动创建前后端排序代码。
前端可见（Front）：前端是否创建本字段。
主键（PrimaryKey）：数据库主键。
是否可清空（Clearable）：前端输入框右侧是否出现X。
Field查询条件（FieldSearchType）：搜索类型。
关联字典（DictType）：关联字典标记。
数据源配置（dataSource:{table,label,value}）：数据源配置。
03.生成一步到位代码包
a.自行设计业务基础结构体模型
点击左侧菜单中的 系统工具 → 代码生成器。
填写好 Struct名称、TableName、Struct简称、Struct中文名称、文件名称。
选择好 自动创建api、自动移动文件 按钮。
点击 新增Field 按钮，为数据表、struct结构体创建字段。
b.从数据库的选择表进行生成结构体
点击左侧菜单中的系统工具 > 代码生成器。
点击 点这里从现有数据库创建代码。
选择 数据库名 以及 表名。
点击使用此表创建。
自行编辑好各个Filed的所需的搜索条件。
c.点击生成代码按钮
完成1.1或1.2步骤操作。
代码会自动移动到前后端你所创建的package文件夹下。
提示：在创建自动化代码时候会自动创建enter.go。
04.注册路由和数据库表
a.注册路由
server/initialize/router.go
初始化总路由。
b.注册数据库表
server/initialize/gorm.go
将你的model结构配置进入 db.AutoMigrate()内部即可。
06.配置目录菜单
a.进入系统 超级管理员 → 菜单管理 菜单，点击 新增根菜单 按钮，配置菜单信息。
略
b.配置项说明
路由name：对应进入列表显示页面时的访问路径。
路由path：选中后边的“添加参数”后才可以输入。
是否隐藏：是否在系统左侧目录菜单显示时，隐藏掉该目录菜单。
父节点Id：该目录菜单的父级目录菜单。
文件路径：对应前端项目中 /view/ PackageName (自建)/StructName.vue 文件。
展示名称：该目录菜单显示在系统左侧目录菜单中的名称。
图标：该目录菜单显示在系统左侧目录菜单中的图标。
排序标记：用于调整该目录菜单在系统左侧目录菜单中显示的上下位置。
keepAlive：是否使用keepAlive缓存。
07.配置后端接口
a.如果在第一步的自动创建api打钩了即可跳过此步。
略
b.进入系统 超级管理员 → api管理 菜单，点击 新增api 按钮，配置接口信息。
略
c.配置项说明
路径：接口路径。
请求：根据接口实际选择。
api分组：对应 struct 简称。
api简介：对api的简要说明。
08.配置角色权限
a.进入系统 超级管理员 → 角色管理 菜单，找到需要设置权限的角色，点击对应的 设置权限 按钮，配置角色相关权限。
略
b.配置项说明
角色菜单：勾选该角色可以访问的目录菜单。
角色api：勾选该角色可以访问的接口。
09.完善新增表单弹窗/页面
a.注意
在 v2.3.5 版本后,不再需要手动创建表单。
b.进入系统 系统工具 → 表单生成器 菜单，根据自己的实际需求，将左侧组件拖拽至中间画布区域，并在右侧设置组件属性。
略
c.配置项说明
组件类型：默认是左侧选中的组件类型。
字段名：对应 Step3 中的 FieldJSON 字段。
标题：即组件label。
占位提示：占位提示。
d.复制代码
点击画布上方的 复制代码 按钮。
选择 生成类型 是 页面 还是 弹窗。
点击 确定 按钮，复制表单代码。
e.代码应用
取出 <el-form>……</el-form> 部分代码，覆盖掉前端项目中 src → view → PackageName(自建) → StructName.vue 中的表单。
将 js 部分data方法里返回的对象复制到前端项目中对应的 .vue 文件的 js 部分。
2.3 常见问题
01.127.0.0.1拒绝连接
a.出现这种情况
旧版本，请到 web/src/view/systemTools/formCreate/index.vue 找到 127.0.0.1 替换为本机或服务器ip
新版本，请前往相对应的环境变量中修改 制定参数 path : VITE_BASE_PATH port :VITE_SERVER_PORT
b.修改对应IP
server项目默认端口是 8888 ,如果你修改,那也要把 127.0.0.1:8888 相应的端口修改 ip:自定义端口
02.生产使用表单生成器
a.需修改web/src/view/systemTools/formCreate/index.vue
<template>
<div style="height:80vh">
<iframe width="100%" height="100%" :src="`${basePath}:${basePort}/form-generator/#/`" frameborder="0" />
</div>
</template>
-----------------------------------------------------------------------------------------------------
修改为
-----------------------------------------------------------------------------------------------------
<template>
<div style="height:80vh">
<iframe width="100%" height="100%" :src="`${basePath}/form-generator/#/`" frameborder="0" />
</div>
</template>
b.添加修改nginx配置
location /form-generator {
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:8888;
}
c.同时web/.env.production配置为
ENV = 'production'
VITE_CLI_PORT = 8080
VITE_SERVER_PORT = 8888
VITE_BASE_API = /api
#下方修改为你的线上域名
VITE_BASE_PATH = https://你的线上域名
2.4 开发规范指南
01.Go代码规范
a.命名规范
// 包名：小写，简短，有意义
package user
package system
// 常量：大写，下划线分隔
const (
MAX_RETRY_COUNT = 3
DEFAULT_TIMEOUT = 30
API_VERSION = "v1"
)
// 变量：驼峰命名
var (
userService *UserService
configFilePath string
isDebugMode bool
)
// 函数：大写开头（公开），小写开头（私有）
func GetUserList() []User {}
func createUser() error {}
// 结构体：大写开头，驼峰命名
type UserService struct {
db *gorm.DB
redis *redis.Client
}
// 接口：以 -er 结尾或描述性名称
type UserRepository interface {
Create(user *User) error
GetByID(id uint) (*User, error)
}
type Validator interface {
Validate() error
}
b.注释规范
// Package user 提供用户管理相关功能
// 包括用户的增删改查、权限验证等操作
package user
// UserService 用户服务，负责处理用户相关的业务逻辑
type UserService struct {
db *gorm.DB
redis *redis.Client
}
// NewUserService 创建用户服务实例
// 参数:
// db: 数据库连接
// redis: Redis连接
// 返回:
// *UserService: 用户服务实例
func NewUserService(db *gorm.DB, redis *redis.Client) *UserService {
return &UserService{
db: db,
redis: redis,
}
}
// GetUserByID 根据用户ID获取用户信息
// 该方法会先从缓存中查找，如果缓存中不存在则从数据库查询
// 参数:
// id: 用户ID
// 返回:
// *User: 用户信息，如果用户不存在则返回nil
// error: 错误信息
func (s *UserService) GetUserByID(id uint) (*User, error) {
// 实现逻辑...
}
c.错误处理规范
// 自定义错误类型
type UserError struct {
Code int `json:"code"`
Message string `json:"message"`
Data string `json:"data,omitempty"`
}
func (e *UserError) Error() string {
return e.Message
}
// 错误常量定义
var (
ErrUserNotFound = &UserError{Code: 1001, Message: "用户不存在"}
ErrUserExists = &UserError{Code: 1002, Message: "用户已存在"}
ErrInvalidPassword = &UserError{Code: 1003, Message: "密码格式不正确"}
ErrPermissionDenied = &UserError{Code: 1004, Message: "权限不足"}
)
// 错误处理示例
func (s *UserService) CreateUser(user *User) error {
// 验证用户是否已存在
exists, err := s.userExists(user.Username)
if err != nil {
return fmt.Errorf("检查用户是否存在失败: %w", err)
}
if exists {
return ErrUserExists
}
// 验证密码强度
if err := s.validatePassword(user.Password); err != nil {
return fmt.Errorf("密码验证失败: %w", err)
}
// 创建用户
if err := s.db.Create(user).Error; err != nil {
return fmt.Errorf("创建用户失败: %w", err)
}
return nil
}
d.结构体标签规范
type User struct {
ID uint `json:"id" gorm:"primarykey;comment:用户ID"`
Username string `json:"username" gorm:"uniqueIndex;size:64;not null;comment:用户名" validate:"required,min=3,max=64"`
Password string `json:"-" gorm:"size:255;not null;comment:密码" validate:"required,min=8"`
Email string `json:"email" gorm:"uniqueIndex;size:128;comment:邮箱" validate:"email"`
Phone string `json:"phone" gorm:"size:20;comment:手机号" validate:"phone"`
Status int `json:"status" gorm:"default:1;comment:状态(1:启用 0:禁用)"`
CreatedAt time.Time `json:"createdAt" gorm:"comment:创建时间"`
UpdatedAt time.Time `json:"updatedAt" gorm:"comment:更新时间"`
DeletedAt gorm.DeletedAt `json:"-" gorm:"index;comment:删除时间"`
}
// TableName 指定表名
func (User) TableName() string {
return "sys_users"
}
02.JavaScript/Vue 代码规范
a.命名规范
// 常量：大写，下划线分隔
const API_BASE_URL = 'http://localhost:8888'
const MAX_FILE_SIZE = 10 * 1024 * 1024
// 变量：驼峰命名
const userName = 'admin'
const isLoggedIn = true
const userList = []
// 函数：驼峰命名，动词开头
function getUserList() {}
function createUser() {}
function validateForm() {}
function handleSubmit() {}
// 类：大写开头，驼峰命名
class UserService {
constructor() {}
async getUsers() {}
async createUser(userData) {}
}
// 组件：大写开头，驼峰命名
const UserList = {
name: 'UserList',
// ...
}
b.Vue 组件规范
<template>
<!-- 使用语义化的HTML标签 -->
<div class="user-list-container">
<!-- 条件渲染使用 v-if/v-show -->
<div v-if="loading" class="loading-wrapper">
<el-loading />
</div>
<!-- 列表渲染使用 v-for，必须添加 key -->
<div
v-for="user in userList"
:key="user.id"
class="user-item"
@click="handleUserClick(user)"
>
{{ user.username }}
</div>
<!-- 事件处理使用方法名，不使用内联表达式 -->
<el-button @click="handleAddUser">添加用户</el-button>
</div>
</template>
<script>
import { ref, reactive, computed, onMounted } from 'vue'
import { ElMessage } from 'element-plus'
import { getUserList, createUser } from '@/api/user'
export default {
name: 'UserList',
// Props 定义要详细
props: {
departmentId: {
type: [String, Number],
required: true,
validator: (value) => value > 0
},
showActions: {
type: Boolean,
default: true
}
},
// Emits 声明
emits: ['user-selected', 'user-created'],
setup(props, { emit }) {
// 响应式数据
const loading = ref(false)
const userList = ref([])
const searchForm = reactive({
keyword: '',
status: 1
})
// 计算属性
const filteredUsers = computed(() => {
return userList.value.filter(user =>
user.username.includes(searchForm.keyword)
)
})
// 方法
const fetchUserList = async () => {
try {
loading.value = true
const { data } = await getUserList({
departmentId: props.departmentId,
...searchForm
})
userList.value = data.list
} catch (error) {
ElMessage.error('获取用户列表失败')
console.error('获取用户列表失败:', error)
} finally {
loading.value = false
}
}
const handleUserClick = (user) => {
emit('user-selected', user)
}
const handleAddUser = () => {
// 处理添加用户逻辑
}
// 生命周期
onMounted(() => {
fetchUserList()
})
return {
loading,
userList,
searchForm,
filteredUsers,
fetchUserList,
handleUserClick,
handleAddUser
}
}
}
</script>
<style lang="scss" scoped>
// 使用 BEM 命名规范
.user-list-container {
padding: 20px;
.loading-wrapper {
display: flex;
justify-content: center;
align-items: center;
height: 200px;
}
.user-item {
padding: 10px;
border: 1px solid #e4e7ed;
border-radius: 4px;
margin-bottom: 10px;
cursor: pointer;
transition: all 0.3s;
&:hover {
background-color: #f5f7fa;
border-color: #409eff;
}
&--active {
background-color: #ecf5ff;
border-color: #409eff;
}
}
}
</style>
c.API 调用规范
// api/user.js
import request from '@/utils/request'
// API 函数命名：动词 + 资源名
export function getUserList(params) {
return request({
url: '/user/getUserList',
method: 'post',
data: params
})
}
export function createUser(data) {
return request({
url: '/user/register',
method: 'post',
data
})
}
export function updateUser(id, data) {
return request({
url: `/user/setUserInfo`,
method: 'put',
data: { ...data, ID: id }
})
}
export function deleteUser(id) {
return request({
url: '/user/deleteUser',
method: 'delete',
data: { ID: id }
})
}
// 在组件中使用
import { getUserList, createUser } from '@/api/user'
export default {
setup() {
const fetchUsers = async () => {
try {
const response = await getUserList({ page: 1, pageSize: 10 })
if (response.code === 0) {
userList.value = response.data.list
} else {
ElMessage.error(response.msg || '获取用户列表失败')
}
} catch (error) {
ElMessage.error('网络错误，请稍后重试')
console.error('API调用失败:', error)
}
}
return { fetchUsers }
}
}
03.Git工作流
a.分支管理
# 主要分支
main/master # 主分支，用于生产环境
develop # 开发分支，用于集成开发
# 功能分支
feature/user-management # 功能开发分支
feature/api-optimization # 功能开发分支
# 修复分支
hotfix/login-bug # 紧急修复分支
bugfix/user-validation # 普通修复分支
# 发布分支
release/v1.2.0 # 发布准备分支
b.提交规范
a.提交信息格式
<type>(<scope>): <subject>
<body>
<footer>
b.类型说明
# 功能相关
feat: 新功能
fix: 修复bug
perf: 性能优化
# 代码相关
refactor: 重构代码
style: 代码格式调整
# 文档和测试
docs: 文档更新
test: 测试相关
# 构建和配置
build: 构建系统或依赖更新
ci: CI配置更新
chore: 其他杂项
# 版本相关
revert: 回滚提交
c.提交示例
# 新功能
git commit -m "feat(user): 添加用户批量导入功能
- 支持Excel文件导入
- 添加数据验证
- 支持导入进度显示
Closes #123"
# 修复bug
git commit -m "fix(auth): 修复JWT token过期时间计算错误
修复了token过期时间计算不准确的问题，
现在使用UTC时间进行计算。
Fixes #456"
# 重构
git commit -m "refactor(api): 重构用户API响应结构
BREAKING CHANGE: 用户API响应格式发生变化
- 将user_info改为userInfo
- 添加了权限信息字段"
c.分支操作流程
a.功能开发流程
# 1. 从develop分支创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/user-management
# 2. 开发功能
# ... 编写代码 ...
# 3. 提交代码
git add .
git commit -m "feat(user): 添加用户管理功能"
# 4. 推送到远程
git push origin feature/user-management
# 5. 创建Pull Request
# 在GitHub/GitLab上创建PR，请求合并到develop分支
# 6. 代码审查通过后合并
# 删除功能分支
git checkout develop
git pull origin develop
git branch -d feature/user-management
git push origin --delete feature/user-management
b.紧急修复流程
# 1. 从main分支创建hotfix分支
git checkout main
git pull origin main
git checkout -b hotfix/login-bug
# 2. 修复问题
# ... 修复代码 ...
# 3. 提交修复
git add .
git commit -m "fix(auth): 修复登录验证失败问题"
# 4. 合并到main和develop
git checkout main
git merge hotfix/login-bug
git push origin main
git checkout develop
git merge hotfix/login-bug
git push origin develop
# 5. 删除hotfix分支
git branch -d hotfix/login-bug
git push origin --delete hotfix/login-bug
# 6. 创建版本标签
git tag -a v1.1.1 -m "修复登录验证问题"
git push origin v1.1.1
04.团队协作
a.代码审查
a.Pull Request 模板
## 变更描述
简要描述本次变更的内容和目的。
## 变更类型
- [ ] 新功能
- [ ] Bug修复
- [ ] 性能优化
- [ ] 重构
- [ ] 文档更新
- [ ] 测试相关
## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试通过
- [ ] 性能测试通过（如适用）
## 检查清单
- [ ] 代码符合项目规范
- [ ] 添加了必要的注释
- [ ] 更新了相关文档
- [ ] 没有引入新的安全风险
- [ ] 向后兼容（或已标记为破坏性变更）
## 相关Issue
Closes #123
Related to #456
## 截图（如适用）
<!-- 添加截图或GIF来展示变更效果 -->
## 额外说明
<!-- 任何需要审查者注意的特殊说明 -->
b.代码审查要点
### 功能性审查
- [ ] 功能是否按需求实现
- [ ] 边界条件是否处理
- [ ] 错误处理是否完善
- [ ] 性能是否可接受
### 代码质量审查
- [ ] 代码结构是否清晰
- [ ] 命名是否规范
- [ ] 注释是否充分
- [ ] 是否有代码重复
### 安全性审查
- [ ] 输入验证是否充分
- [ ] 权限控制是否正确
- [ ] 敏感信息是否保护
- [ ] SQL注入等安全问题
### 测试审查
- [ ] 测试覆盖率是否足够
- [ ] 测试用例是否合理
- [ ] 集成测试是否通过
b.项目管理
a.Issue 模板1
## Bug报告
### 环境信息
- 操作系统：
- 浏览器：
- 项目版本：
### 问题描述
简要描述遇到的问题。
### 复现步骤
1. 打开页面
2. 点击按钮
3. 查看结果
### 期望行为
描述期望的正确行为。
### 实际行为
描述实际发生的行为。
### 截图
如果适用，添加截图来帮助解释问题。
### 额外信息
添加任何其他有助于解决问题的信息。
b.Issue 模板2
## 功能需求
### 需求描述
详细描述新功能的需求。
### 用户故事
作为 [用户角色]，我希望 [功能描述]，以便 [价值/目的]。
### 验收标准
- [ ] 标准1
- [ ] 标准2
- [ ] 标准3
### 设计稿
<!-- 如果有设计稿，请添加链接或图片 -->
### 技术要求
- 前端技术栈：
- 后端技术栈：
- 数据库变更：
### 优先级
- [ ] 高
- [ ] 中
- [ ] 低
05.开发工具配置
a.VS Code 配置
a.settings.json
{
"go.formatTool": "goimports",
"go.lintTool": "golangci-lint",
"go.testFlags": ["-v"],
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.organizeImports": true
},
"eslint.validate": [
"javascript",
"javascriptreact",
"vue"
],
"vetur.format.defaultFormatter.html": "prettier",
"vetur.format.defaultFormatter.js": "prettier",
"vetur.format.defaultFormatter.css": "prettier"
}
b.推荐扩展
{
"recommendations": [
"golang.go",
"vue.volar",
"esbenp.prettier-vscode",
"dbaeumer.vscode-eslint",
"bradlc.vscode-tailwindcss",
"ms-vscode.vscode-json",
"redhat.vscode-yaml"
]
}
b.Git Hooks
a.pre-commit
#!/bin/sh
# .git/hooks/pre-commit
echo "Running pre-commit checks..."
# 检查Go代码格式
if ! gofmt -l . | grep -q '^$'; then
echo "Go code is not formatted. Please run 'gofmt -w .'"
exit 1
fi
# 运行Go测试
if ! go test ./...; then
echo "Go tests failed"
exit 1
fi
# 检查前端代码格式
cd web
if ! npm run lint; then
echo "Frontend linting failed"
exit 1
fi
echo "Pre-commit checks passed!"
b.commit-msg
#!/bin/sh
# .git/hooks/commit-msg
commit_regex='^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(:markdown-math{encoded=".%2B"})?: .{1,50}'
if ! grep -qE ":markdown-math{single="true" encoded="commit_regex%22%20%22"}1"; then
echo "Invalid commit message format!"
echo "Format: <type>(<scope>): <subject>"
echo "Example: feat(user): add user registration"
exit 1
fi
06.代码质量工具
a.golangci.yml
linters-settings:
govet:
check-shadowing: true
golint:
min-confidence: 0
gocyclo:
min-complexity: 15
maligned:
suggest-new: true
dupl:
threshold: 100
goconst:
min-len: 2
min-occurrences: 2
misspell:
locale: US
lll:
line-length: 140
goimports:
local-prefixes: github.com/flipped-aurora/gin-vue-admin
linters:
enable:
- bodyclose
- deadcode
- depguard
- dogsled
- dupl
- errcheck
- gochecknoinits
- goconst
- gocyclo
- gofmt
- goimports
- golint
- gosec
- gosimple
- govet
- ineffassign
- interfacer
- lll
- misspell
- nakedret
- scopelint
- staticcheck
- structcheck
- stylecheck
- typecheck
- unconvert
- unparam
- unused
- varcheck
- whitespace
run:
timeout: 5m
b.eslintrc.js
module.exports = {
root: true,
env: {
node: true,
browser: true,
es2021: true
},
extends: [
'plugin:vue/vue3-essential',
'@vue/standard'
],
parserOptions: {
ecmaVersion: 2021,
sourceType: 'module'
},
rules: {
'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'vue/multi-word-component-names': 'off',
'space-before-function-paren': ['error', 'never'],
'comma-dangle': ['error', 'never']
}
}
07.质量保证
a.测试规范
a.单元测试
// user_service_test.go
package service
import (
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/mock"
)
func TestUserService_CreateUser(t *testing.T) {
// 准备测试数据
user := &User{
Username: "testuser",
Email: "[email protected]",
Password: "password123",
}
// 创建mock
mockDB := new(MockDB)
mockDB.On("Create", mock.AnythingOfType("*User")).Return(nil)
// 创建服务实例
service := NewUserService(mockDB, nil)
// 执行测试
err := service.CreateUser(user)
// 断言结果
assert.NoError(t, err)
mockDB.AssertExpectations(t)
}
func TestUserService_CreateUser_UserExists(t *testing.T) {
user := &User{
Username: "existinguser",
Email: "[email protected]",
Password: "password123",
}
mockDB := new(MockDB)
mockDB.On("First", mock.AnythingOfType("*User"), mock.Anything).Return(nil)
service := NewUserService(mockDB, nil)
err := service.CreateUser(user)
assert.Error(t, err)
assert.Equal(t, ErrUserExists, err)
}
b.集成测试
// integration_test.go
package test
import (
"bytes"
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"github.com/gin-gonic/gin"
"github.com/stretchr/testify/assert"
)
func TestUserAPI_CreateUser(t *testing.T) {
// 设置测试环境
gin.SetMode(gin.TestMode)
router := setupRouter()
// 准备测试数据
userData := map[string]interface{}{
"username": "testuser",
"email": "[email protected]",
"password": "password123",
}
jsonData, _ := json.Marshal(userData)
// 创建请求
req, _ := http.NewRequest("POST", "/user/register", bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
// 执行请求
w := httptest.NewRecorder()
router.ServeHTTP(w, req)
// 验证响应
assert.Equal(t, http.StatusOK, w.Code)
var response map[string]interface{}
err := json.Unmarshal(w.Body.Bytes(), &response)
assert.NoError(t, err)
assert.Equal(t, float64(0), response["code"])
}
b.性能测试
// benchmark_test.go
package service
import (
"testing"
)
func BenchmarkUserService_GetUserByID(b *testing.B) {
service := setupUserService()
b.ResetTimer()
for i := 0; i < b.N; i++ {
_, err := service.GetUserByID(1)
if err != nil {
b.Fatal(err)
}
}
}
func BenchmarkUserService_GetUserList(b *testing.B) {
service := setupUserService()
b.ResetTimer()
for i := 0; i < b.N; i++ {
_, _, err := service.GetUserList(PageInfo{Page: 1, PageSize: 10})
if err != nil {
b.Fatal(err)
}
}
}
2.5 常见问题解答
01.安装和启动问题
a.后端启动问题
a.问题：数据库连接失败
a.错误信息
failed to initialize database, got error dial tcp 127.0.0.1:3306: connect: connection refused
b.解决方案
a.检查数据库服务是否启动
# MySQL
sudo systemctl status mysql
# 或
brew services list | grep mysql
# PostgreSQL
sudo systemctl status postgresql
# 或
brew services list | grep postgresql
b.检查配置文件 config.yaml
mysql:
path: 127.0.0.1
port: "3306"
config: charset=utf8mb4&parseTime=True&loc=Local
db-name: gin_vue_admin
username: root
password: "your_password"
prefix: ""
singular: false
engine: ""
max-idle-conns: 10
max-open-conns: 100
log-mode: ""
log-zap: false
c.测试数据库连接
mysql -h 127.0.0.1 -P 3306 -u root -p
d.创建数据库
CREATE DATABASE gin_vue_admin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
b.问题：Redis 连接失败
a.错误信息
failed to ping redis, got error dial tcp 127.0.0.1:6379: connect: connection refused
b.解决方案
a.启动 Redis 服务
# Linux
sudo systemctl start redis
# macOS
brew services start redis
# 手动启动
redis-server
b.检查 Redis 配置
redis:
db: 0
addr: 127.0.0.1:6379
password: ""
c.测试 Redis 连接
redis-cli ping
c.问题：端口被占用
a.错误信息
listen tcp :8888: bind: address already in use
b.解决方案
a.查找占用端口的进程
# Linux/macOS
lsof -i :8888
netstat -tulpn | grep 8888
# Windows
netstat -ano | findstr 8888
b.终止占用进程
# Linux/macOS
kill -9 <PID>
# Windows
taskkill /PID <PID> /F
c.或修改配置文件中的端口
system:
addr: 8889 # 修改为其他端口
b.前端启动问题
a.问题：依赖安装失败
a.错误信息
npm ERR! code ERESOLVECONFLICT
npm ERR! ERESOLVECONFLICT unable to resolve dependency tree
b.解决方案
a.清理缓存和依赖
# 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json
# 清理 npm 缓存
npm cache clean --force
# 重新安装
npm install
b.使用 yarn 替代 npm
# 安装 yarn
npm install -g yarn
# 使用 yarn 安装依赖
yarn install
c.使用 --legacy-peer-deps 参数
npm install --legacy-peer-deps
b.问题：Node.js 版本不兼容
a.错误信息
engine "node" is incompatible with this module
b.解决方案
a.检查 Node.js 版本
node --version
b.安装推荐版本（Node.js 16+）
# 使用 nvm 管理 Node.js 版本
nvm install 18
nvm use 18
c.或修改 package.json 中的引擎要求
{
"engines": {
"node": ">=14.0.0"
}
}
c.问题：Vite 开发服务器启动失败
a.错误信息
Error: Cannot find module '@vitejs/plugin-vue'
b.解决方案
a.重新安装 Vite 相关依赖
npm install @vitejs/plugin-vue @vitejs/plugin-vue-jsx --save-dev
b.检查 vite.config.js 配置
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
'@': resolve(__dirname, 'src')
}
},
server: {
port: 8080,
proxy: {
'/api': {
target: 'http://localhost:8888',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
})
02.开发问题
a.API 请求问题
a.问题：跨域请求被阻止
a.错误信息
Access to XMLHttpRequest at 'http://localhost:8888/api/login' from origin 'http://localhost:8080' has been blocked by CORS policy
b.解决方案
a.后端配置 CORS 中间件
// middleware/cors.go
func Cors() gin.HandlerFunc {
return gin.HandlerFunc(func(c *gin.Context) {
method := c.Request.Method
origin := c.Request.Header.Get("Origin")
c.Header("Access-Control-Allow-Origin", origin)
c.Header("Access-Control-Allow-Headers", "Content-Type,AccessToken,X-CSRF-Token, Authorization, Token,X-Token,X-User-Id")
c.Header("Access-Control-Allow-Methods", "POST, GET, OPTIONS, PUT, DELETE,UPDATE")
c.Header("Access-Control-Expose-Headers", "Content-Length, Access-Control-Allow-Origin, Access-Control-Allow-Headers, Content-Type")
c.Header("Access-Control-Allow-Credentials", "true")
if method == "OPTIONS" {
c.AbortWithStatus(204)
return
}
c.Next()
})
}
b.前端配置代理
// vite.config.js
export default defineConfig({
server: {
proxy: {
'/api': {
target: 'http://localhost:8888',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
})
b.问题：Token 验证失败
a.错误信息
{
"code": 7,
"data": {},
"msg": "token过期"
}
b.解决方案
a.检查 Token 是否正确设置
// utils/request.js
service.interceptors.request.use(
config => {
const token = store.getters['user/token']
if (token) {
config.headers['x-token'] = token
}
return config
},
error => {
return Promise.reject(error)
}
)
b.实现 Token 自动刷新
// utils/request.js
service.interceptors.response.use(
response => {
const res = response.data
if (res.code === 7) {
// Token 过期，尝试刷新
return store.dispatch('user/refreshToken').then(() => {
// 重新发送原请求
return service(response.config)
}).catch(() => {
// 刷新失败，跳转登录页
store.dispatch('user/logout')
router.push('/login')
return Promise.reject(new Error('Token 过期'))
})
}
return response
},
error => {
return Promise.reject(error)
}
)
b.权限问题
a.问题：权限验证失败
a.错误信息
{
"code": 7,
"data": {},
"msg": "权限不足"
}
b.解决方案
a.检查用户角色权限配置
-- 查看用户权限
SELECT u.username, a.authority_name, ar.authority_id, ar.path, ar.method
FROM sys_users u
JOIN sys_authorities a ON u.authority_id = a.authority_id
JOIN sys_authority_menus am ON a.authority_id = am.sys_authority_authority_id
JOIN sys_base_menus m ON am.sys_base_menu_id = m.id
JOIN casbin_rule ar ON a.authority_id = ar.v0
WHERE u.username = 'your_username';
b.添加权限规则
// 在系统管理 -> 角色管理 -> API权限中添加对应的权限
// 或通过代码添加
casbinService := service.ServiceGroupApp.SystemServiceGroup.CasbinService
casbinService.UpdateCasbin(authorityId, casbinInfos)
c.检查 Casbin 配置
// config/casbin.go
func (c *Casbin) TableName() string {
return c.CasbinRule
}
c.数据库问题
a.问题：数据库迁移失败
a.错误信息
Error 1071: Specified key was too long; max key length is 767 bytes
b.解决方案
a.修改 MySQL 配置
-- 设置 innodb_large_prefix
SET GLOBAL innodb_large_prefix = 1;
SET GLOBAL innodb_file_format = 'Barracuda';
SET GLOBAL innodb_file_per_table = 1;
b.修改表结构
// 在模型中指定索引长度
type SysUser struct {
Username string `gorm:"index:idx_username,length:191;comment:用户登录名"`
Email string `gorm:"index:idx_email,length:191;comment:用户邮箱"`
}
b.问题：外键约束错误
a.错误信息
Error 1452: Cannot add or update a child row: a foreign key constraint fails
b.解决方案
a.检查外键关联的数据是否存在
-- 检查关联数据
SELECT * FROM sys_authorities WHERE authority_id = 'your_authority_id';
b.临时禁用外键检查
SET FOREIGN_KEY_CHECKS = 0;
-- 执行你的操作
SET FOREIGN_KEY_CHECKS = 1;
c.修改 GORM 配置
// config/gorm.go
func GormConfig() *gorm.Config {
return &gorm.Config{
DisableForeignKeyConstraintWhenMigrating: true,
// 其他配置...
}
}
03.前端问题
a.路由问题
a.问题：路由跳转失败
a.错误信息
Uncaught (in promise) NavigationDuplicated: Avoided redundant navigation to current location
b.解决方案
a.检查路由跳转逻辑
// 避免重复跳转
if (this.$route.path !== '/target-path') {
this.$router.push('/target-path')
}
b.使用 replace 替代 push
this.$router.replace('/target-path')
b.问题：动态路由不生效
a.解决方案
a.检查路由注册顺序
// router/index.js
// 确保动态路由在静态路由之后注册
const routes = [
// 静态路由
{ path: '/login', component: Login },
// 动态路由
...asyncRoutes
]
b.检查权限验证逻辑
// store/modules/router.js
const actions = {
async GenerateRoutes({ commit }, roles) {
const accessedRoutes = filterAsyncRoutes(asyncRoutes, roles)
commit('SET_ROUTES', accessedRoutes)
return accessedRoutes
}
}
b.组件问题
a.问题：Element Plus 组件样式异常
a.解决方案：
a.检查样式导入
// main.js
import 'element-plus/dist/index.css'
b.检查主题配置
// styles/element-variables.scss
@forward 'element-plus/theme-chalk/src/common/var.scss' with (
$colors: (
'primary': (
'base': #409eff,
),
)
);
b.问题：组件响应式失效
a.解决方案
a.检查数据响应式声明
// Vue 3 Composition API
import { ref, reactive } from 'vue'
export default {
setup() {
const count = ref(0)
const state = reactive({
name: 'test'
})
return {
count,
state
}
}
}
b.检查数组/对象更新方式
// 错误方式
this.list[0] = newItem
// 正确方式
this.$set(this.list, 0, newItem)
// 或
this.list.splice(0, 1, newItem)
04.部署问题
a.Docker 部署问题
a.问题：Docker 镜像构建失败
a.错误信息
failed to solve with frontend dockerfile.v0: failed to read dockerfile
b.解决方案
a.检查 Dockerfile 语法
# 确保 Dockerfile 格式正确
FROM golang:1.19-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download
RUN go build -o main .
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/main .
COPY --from=builder /app/config.yaml .
CMD ["./main"]
b.检查 .dockerignore 文件
node_modules
.git
.gitignore
README.md
Dockerfile
.dockerignore
b.问题：容器启动失败
a.错误信息
standard_init_linux.go: exec user process caused: no such file or directory
b.解决方案
a.检查可执行文件权限
RUN chmod +x ./main
b.使用正确的基础镜像
# 对于 Go 程序，使用 alpine 或 scratch
FROM alpine:latest
# 或
FROM scratch
b.Nginx 配置问题
a.问题：前端路由 404
a.解决方案
server {
listen 80;
server_name your-domain.com;
root /var/www/html;
index index.html;
# 处理前端路由
location / {
try_files $uri $uri/ /index.html;
}
# API 代理
location /api {
proxy_pass http://backend:8888;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
b.问题：静态资源加载失败
a.解决方案
server {
# 静态资源缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 1y;
add_header Cache-Control "public, immutable";
try_files $uri =404;
}
# 字体文件
location ~* \.(woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public";
add_header Access-Control-Allow-Origin "*";
}
}
05.调试技巧
a.后端调试
a.启用详细日志
# config.yaml
zap:
level: 'debug' # 设置为 debug 级别
format: 'console'
prefix: '[gin-vue-admin]'
director: 'log'
show-line: true
encode-level: 'LowercaseColorLevelEncoder'
stacktrace-key: 'stacktrace'
log-in-console: true
b.使用 Delve 调试器
# 安装 Delve
go install github.com/go-delve/delve/cmd/dlv@latest
# 启动调试
dlv debug main.go
# 在代码中设置断点
(dlv) break main.main
(dlv) continue
b.前端调试
a.使用 Vue DevTools
安装浏览器扩展
在开发环境中启用
// main.js
if (process.env.NODE_ENV === 'development') {
app.config.devtools = true
}
b.网络请求调试
// utils/request.js
service.interceptors.request.use(
config => {
console.log('Request:', config)
return config
}
)
service.interceptors.response.use(
response => {
console.log('Response:', response)
return response
},
error => {
console.error('Request Error:', error)
return Promise.reject(error)
}
)
06.性能问题
a.后端性能优化
a.数据库查询优化
// 使用索引
db.Where("username = ?", username).First(&user)
// 预加载关联数据
db.Preload("Authorities").Find(&users)
// 分页查询
db.Limit(pageSize).Offset(offset).Find(&users)
// 只查询需要的字段
db.Select("id, username, email").Find(&users)
b.缓存优化
// 使用 Redis 缓存
func GetUserFromCache(userID uint) (*system.SysUser, error) {
key := fmt.Sprintf("user:%d", userID)
cached := global.GVA_REDIS.Get(context.Background(), key).Val()
if cached != "" {
var user system.SysUser
err := json.Unmarshal([]byte(cached), &user)
return &user, err
}
// 从数据库查询并缓存
var user system.SysUser
err := global.GVA_DB.First(&user, userID).Error
if err != nil {
return nil, err
}
userJSON, _ := json.Marshal(user)
global.GVA_REDIS.Set(context.Background(), key, userJSON, 30*time.Minute)
return &user, nil
}
b.前端性能优化
a.组件懒加载
// 路由懒加载
const routes = [
{
path: '/dashboard',
component: () => import('@/views/dashboard/index.vue')
}
]
// 组件懒加载
export default {
components: {
HeavyComponent: () => import('@/components/HeavyComponent.vue')
}
}
b.虚拟滚动
<template>
<el-table
v-loading="loading"
:data="visibleData"
height="400"
@scroll="handleScroll"
>
<!-- 表格列定义 -->
</el-table>
</template>
<script>
export default {
data() {
return {
allData: [],
visibleData: [],
scrollTop: 0,
itemHeight: 50,
containerHeight: 400
}
},
computed: {
startIndex() {
return Math.floor(this.scrollTop / this.itemHeight)
},
endIndex() {
const visibleCount = Math.ceil(this.containerHeight / this.itemHeight)
return Math.min(this.startIndex + visibleCount, this.allData.length)
}
},
watch: {
startIndex() {
this.updateVisibleData()
},
endIndex() {
this.updateVisibleData()
}
},
methods: {
updateVisibleData() {
this.visibleData = this.allData.slice(this.startIndex, this.endIndex)
},
handleScroll(event) {
this.scrollTop = event.target.scrollTop
}
}
}
</script>
07.获取帮助
a.提交 Bug 报告
a.环境信息
操作系统版本
Go 版本
Node.js 版本
数据库版本
b.错误描述
详细的错误信息
复现步骤
期望行为
c.相关代码
最小复现代码
配置文件
日志信息
b.常用调试命令
# 查看 Go 版本
go version
# 查看 Node.js 版本
node --version
npm --version
# 查看数据库版本
mysql --version
redis-server --version
# 查看端口占用
lsof -i :8888
netstat -tulpn | grep 8888
# 查看进程
ps aux | grep gin-vue-admin
# 查看日志
tail -f log/server.log
journalctl -u gin-vue-admin -f
# Docker 相关
docker ps
docker logs container_name
docker exec -it container_name /bin/sh
3 前端管理
3.1 操作指南
3.2 环境变量
3.3 按钮权限
3.4 字典方法
3.5 自定义全局皮肤
3.6 自定义图标
3.7 开启TypeScript
3.8 导出Excel
3.9 开发指导文档
4 后端管理
4.1 操作指南
4.2 配置文件
4.3 认证系统
4.4 权限系统
4.5 代码生成器
4.6 对象存储
4.7 多数据库支持
4.8 严格角色模式
4.9 viper
4.10 zap
4.11 gorm
4.12 定时任务
4.13 AI助手集成
4.14 数据库设计
4.15 开发指导文档
5 部署指南
5.1 项目上线
5.2 docker
5.3 docker-compose
5.4 kubernetes