猫德实战避坑指南：3天搞定全栈项目，告别报错

刚接手新项目，一跑代码就是满屏红色 StackTrace？别慌，这通常是环境配置或依赖冲突惹的祸。本文用真实案例带你搭建“猫德”项目，附带避坑指南，3小时落地。

项目目标与背景

“猫德”不是宠物行为学，而是某开源社区的代号，指代一套轻量级全栈模板。它解决的是中小团队快速搭建管理后台的痛点。

核心目标很明确：

前端用 Vue3 + TypeScript
后端用 Go + Gin 框架
数据库 MySQL 8.0
部署支持 Docker

为什么选这个组合？Go 的高并发特性适合业务接口，Vue3 的组合式 API 比 Vue2 更灵活，TypeScript 能在编译期抓出类型错误。这套技术栈在 GitHub 开源仓库 golang/gin-vue-admin 等项目中被广泛验证，稳定性经过了大规模生产环境考验。

你不需要精通每门语言，只要会看报错、会改配置，就能跑通整个流程。

目录结构设计

清晰的目录结构是项目可维护性的基础。别像新手那样把代码全堆在根目录，那样改个配置都要翻半天。

推荐结构如下：

cat-de-project/
├── frontend/          # 前端项目
│   ├── src/
│   │   ├── api/       # 接口封装
│   │   ├── views/     # 页面组件
│   │   ├── store/     # 状态管理
│   │   └── main.ts    # 入口文件
│   └── package.json
├── backend/           # 后端项目
│   ├── cmd/           # 启动入口
│   ├── internal/      # 核心业务逻辑
│   │   ├── handler/   # HTTP 处理器
│   │   ├── service/   # 业务服务层
│   │   └── model/     # 数据模型
│   ├── config/        # 配置文件
│   └── go.mod         # Go 模块定义
├── docker/            # Docker 部署文件
│   ├── Dockerfile.frontend
│   ├── Dockerfile.backend
│   └── docker-compose.yml
└── README.md

几个关键细节：

internal 包在 Go 中是私有包，外部项目无法引用，强制你遵守分层架构
前端 api 目录单独抽离，方便后续做接口 Mock 或切换环境
Docker 文件独立存放，避免污染代码目录

这个结构参考了 GitHub 开源仓库 go-zero 的项目规范，在团队协作中能显著降低沟通成本。

核心代码实现

后端：Go + Gin 用户登录接口

先看后端最核心的登录接口。很多新手在这里栽跟头，要么是 CORS 跨域问题，要么是 JWT 生成失败。

// internal/handler/auth.go
package handlerimport ("github.com/gin-gonic/gin""github.com/golang-jwt/jwt/v5""your-project/internal/model"
)// LoginRequest 登录请求参数
type LoginRequest struct {Username string `json:"username" binding:"required"`Password string `json:"password" binding:"required"`
}// LoginHandler 处理登录请求
func LoginHandler(ctx *gin.Context) {var req LoginRequest// 绑定并验证请求参数if err := ctx.ShouldBindJSON(&req); err != nil {ctx.JSON(400, gin.H{"error": "参数错误: " + err.Error()})return}// 这里省略密码验证逻辑，实际项目中应查数据库比对if req.Password != "admin123" {ctx.JSON(401, gin.H{"error": "密码错误"})return}// 生成 JWT Tokentoken := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{"username": req.Username,"exp":      time.Now().Add(time.Hour * 24).Unix(),})tokenString, _ := token.SignedString([]byte("your-secret-key"))ctx.JSON(200, gin.H{"token": tokenString,"msg":   "登录成功",})
}

逐行讲解：

binding:"required" 是 Gin 的参数验证标签，缺少必填字段直接返回 400
JWT 的 exp 字段设置过期时间，避免 Token 永久有效带来的安全风险
密钥 your-secret-key 在生产环境必须从环境变量读取，绝不能硬编码

前端：Vue3 + Axios 请求封装

前端最容易出问题的地方是 Axios 拦截器配置不当。很多新手直接 axios.get()，结果 Token 过期后页面白屏。

// src/api/request.ts
import axios from 'axios'
import { ElMessage } from 'element-plus'const service = axios.create({baseURL: import.meta.env.VITE_API_BASE_URL,timeout: 10000,
})// 请求拦截器：自动携带 Token
service.interceptors.request.use(config => {const token = localStorage.getItem('token')if (token) {config.headers.Authorization = `Bearer ${token}`}return config
})// 响应拦截器：统一处理错误
service.interceptors.response.use(response => response.data,error => {if (error.response?.status === 401) {// Token 过期，跳转登录页localStorage.removeItem('token')window.location.href = '/login'} else {ElMessage.error(error.response?.data?.error || '请求失败')}return Promise.reject(error)}
)export default service

关键点：

import.meta.env.VITE_API_BASE_URL 从 .env 文件读取，开发环境和生产环境 URL 不同
401 状态码统一处理，避免每个页面都写一遍跳转逻辑
错误提示用 Element Plus 的 ElMessage，用户体验更一致

前端：登录页面组件

<!-- src/views/Login.vue -->
<template><div class="login-container"><el-form ref="formRef" :model="form" :rules="rules"><el-form-item prop="username"><el-input v-model="form.username" placeholder="用户名" /></el-form-item><el-form-item prop="password"><el-input v-model="form.password" type="password" placeholder="密码" /></el-form-item><el-button type="primary" @click="handleLogin">登录</el-button></el-form></div>
</template><script setup lang="ts">
import { ref, reactive } from 'vue'
import { useRouter } from 'vue-router'
import loginApi from '@/api/auth'const router = useRouter()
const form = reactive({username: '',password: '',
})const rules = {username: [{ required: true, message: '请输入用户名', trigger: 'blur' }],password: [{ required: true, message: '请输入密码', trigger: 'blur' }],
}const handleLogin = async () => {try {const res = await loginApi(form)localStorage.setItem('token', res.token)router.push('/dashboard')} catch (e) {// 错误已在拦截器中处理}
}
</script>

注意 router.push('/dashboard') 这一步，登录后必须跳转，否则用户会停留在登录页。

运行与测试

本地环境搭建

很多新手卡在这一步：Go 版本不对、Node 版本冲突、MySQL 字符集问题。

避坑清单：

Go 1.21+ 支持泛型，但 1.22 有些库还没适配，建议用 1.21.x
Node.js 用 18.x LTS 版本，Vue3 官方推荐
MySQL 建库时指定 utf8mb4 字符集，否则中文乱码

# 初始化数据库
CREATE DATABASE cat_de DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;# 启动后端
cd backend
go run cmd/main.go# 启动前端
cd frontend
npm install
npm run dev

常见问题排查

问题1：前端请求 404

原因：Vite 代理配置错误。

// vite.config.js
export default {server: {proxy: {'/api': {target: 'http://localhost:8080',changeOrigin: true,rewrite: path => path.replace(/^\/api/, ''),},},},
}

问题2：JWT 验证失败

原因：前后端密钥不一致，或 Token 过期时间设置太短。

检查后端 go run 时传入的环境变量，确保和前端 .env 中的配置匹配。

问题3：CORS 跨域错误

Gin 中间件配置：

// cmd/main.go
r.Use(cors.New(cors.Config{AllowOrigins:     []string{"http://localhost:5173"},AllowMethods:     []string{"GET", "POST", "PUT", "DELETE"},AllowHeaders:     []string{"Authorization", "Content-Type"},AllowCredentials: true,
}))

优化扩展与避坑指南

性能优化

数据库连接池

// 设置最大连接数
db.SetMaxOpenConns(100)
db.SetMaxIdleConns(10)
db.SetConnMaxLifetime(time.Hour)

前端路由懒加载

// router/index.ts
const routes = [{path: '/dashboard',component: () => import('@/views/Dashboard.vue'),},
]

接口缓存

对不变的数据（如字典表）加 Redis 缓存，减少数据库查询。

安全加固

SQL 注入：使用 GORM 的参数化查询，禁止字符串拼接
XSS 攻击：前端渲染用户输入时，Vue 默认转义，但自定义指令要注意
CSRF：API 接口使用 JWT，天然免疫 CSRF

避坑指南汇总

问题	原因	解决方案
StackTrace 看不懂	日志格式混乱	使用 zap 日志库，统一格式
接口超时	数据库慢查询	加索引，分析执行计划
内存泄漏	Gin 上下文未释放	检查 `ctx.Done()`
前端白屏	静态资源路径错误	Vite `base` 配置为相对路径