template-vue3-gin-fullstack：Vue3 + Go Gin 前后端分离全栈项目模板

GitHub: https://github.com/wujichen252-crypto/template-vue3-gin-fullstack
技术栈: Vue 3 + Go Gin + PostgreSQL + Redis + TypeScript + Tailwind CSS
作者: 码农先森
标签: 全栈模板 / Vue3 / Go Gin / 前后端分离 / TypeScript / 项目架构

引言

前后端分离的全栈项目，每次新开都要从头搭架子：前端配路由、状态管理、API 封装；后端配分层、写 Controller、Service、Repository……这些事情做多了，真的很烦。

有没有一个开箱即用的全栈模板，能直接跑起来？

template-vue3-gin-fullstack 就是来解决这个问题的——基于 Vue3 + Go Gin 实现，前端后端目录分离，技术栈主流，分层清晰，CI/CD 配好，直接 clone 就能开始写业务代码。

一、技术栈概览

前端技术栈

后端技术栈

二、目录结构

template-vue3-gin-fullstack/
├── frontend/                 # Vue3 前端
│   ├── src/
│   │   ├── api/              # API 接口封装
│   │   ├── components/        # 通用组件
│   │   ├── composables/      # 组合式函数
│   │   ├── router/           # 路由配置
│   │   ├── stores/            # Pinia 状态
│   │   ├── types/             # TypeScript 类型定义
│   │   ├── utils/             # 工具函数
│   │   └── views/              # 页面组件
│   └── ...
├── backend/                  # Go 后端
│   ├── cmd/                  # 程序入口
│   ├── config/               # 配置管理
│   ├── internal/             # 内部包
│   │   ├── handler/          # 处理器层（对应 Controller）
│   │   ├── service/          # 业务逻辑层
│   │   ├── repository/       # 数据访问层
│   │   ├── model/            # 数据模型
│   │   └── middleware/       # 中间件
│   ├── pkg/                  # 公共包
│   └── ...
└── ...

分层设计

前端分层：

后端分层（经典 DDD 简化版）：

三、快速开始（10 分钟跑起来）

前置条件

• Node.js >= 18
• Go >= 1.22
• PostgreSQL >= 14
• Redis >= 6

第一步：克隆项目

git clone https://github.com/wujichen252-crypto/template-vue3-gin-fullstack
cd template-vue3-gin-fullstack

第二步：启动后端

cd backend

cp .env.example .env
# 编辑 .env，配置数据库和 Redis 连接信息

go mod tidy
go run cmd/main.go

后端启动后运行于 http://localhost:8080

第三步：启动前端

cd frontend

npm install
npm run dev

前端启动后访问 http://localhost:5173

第四步：初始化数据库

cd backend/scripts

psql -U postgres -f init_db.sql

四、环境变量配置

后端环境变量 (.env)

前端环境变量

五、API 接口一览

认证接口

JWT 认证流程

登录 → 拿到 Access Token + Refresh Token
  ↓
请求时 Header 带上 Authorization: Bearer <access_token>
  ↓
Token 过期 → 用 Refresh Token 换新 Token

六、CI/CD 自动化部署

工作流概览

部署配置步骤（5 分钟完成）

第一步：配置 GitHub Secrets

进入仓库 Settings → Secrets and variables → Actions → Secrets，添加：

第二步：配置 GitHub Variables

进入 Settings → Secrets and variables → Actions → Variables，添加：

第三步：服务器准备

# 生成 SSH 密钥对
ssh-keygen -t rsa -b 4096 -C "github-actions" -f ~/.ssh/github_actions

# 添加公钥到 authorized_keys
cat ~/.ssh/github_actions.pub >> ~/.ssh/authorized_keys

# 把私钥填到 GitHub Secrets：SSH_PRIVATE_KEY
cat ~/.ssh/github_actions

创建 systemd 服务文件 /etc/systemd/system/template-app.service：

[Unit]
Description=Template App API
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/www/template-app
ExecStart=/www/template-app/app
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload
sudo systemctl enable template-app

第四步：触发部署

git push origin main

然后前往 GitHub → Actions 查看部署状态。

一键配置脚本

不想手动配？可以运行项目提供的配置向导脚本：

bash scripts/setup-ci.sh

七、构建与部署

前端构建

cd frontend
npm run build

构建产物在 frontend/dist/ 目录。

后端构建

cd backend

# Linux 交叉编译
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o app-server ./cmd/main.go

# Windows
go build -o app-server.exe ./cmd/main.go

Docker 部署

cd backend

docker build -t template-backend .
docker run -p 8080:8080 --env-file .env template-backend

Nginx 配置

server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /path/to/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

八、Swagger API 文档

后端集成了 Swagger UI，开发模式下直接访问：

http://localhost:8080/swagger/index.html

所有 API 接口都有完整文档，不需要额外 Postman 或 Insomnia。

九、多环境支持

Deploy 工作流支持 workflow_dispatch 手动触发，可选择部署环境：

1. 进入 GitHub → Actions → Deploy
2. 点击 "Run workflow"
3. 选择环境（production / staging）

十、适合谁用

推荐场景

项目亮点

十一、和同类项目对比

十二、总结

一句话评价

一个开箱即用的 Vue3 + Go Gin 全栈模板，前端后端分离，分层清晰，JWT 认证、CI/CD 全部配好，clone 下来直接写业务代码。

使用建议

1. 首次使用：按照快速开始文档，10 分钟跑起来
2. 定制开发：在 backend/internal/ 下写业务逻辑，前端 views/ 下写页面
3. 部署上线：按照 CI/CD 配置文档，push 代码自动部署
4. 持续迭代：使用多环境支持，开发/测试/生产分离

GitHub: https://github.com/wujichen252-crypto/template-vue3-gin-fullstack

本文首发于「程序员茄子」博客，原文链接：https://chenxutan.com