Web开发实战：Gin + GORM 构建企业级 API 项目
🚀 Web开发实战：Gin + GORM 构建企业级 API 项目
Gin 是当下最受欢迎的 Golang Web 框架之一，GORM 是使用最广泛的 ORM 框架。两者组合可快速开发高性能、结构清晰、维护方便的 API 项目。本文将带你从 0 到 1 构建一个完整的 Web 后端服务，适用于管理后台、微服务、BFF 等场景。
🧱 一、项目目标：构建一个用户管理 API
实现接口功能包括：
- 用户注册
- 用户登录（JWT）
- 用户列表查询（分页）
- 用户详情、更新与删除
- 权限接口预留
📦 二、技术栈
| 类别 | 技术 | 说明 |
|---|---|---|
| Web框架 | Gin | 路由、请求处理 |
| ORM | GORM | 数据库访问 |
| 数据库 | MySQL/PostgreSQL | 关系型数据库 |
| 配置管理 | Viper | 支持配置文件/env参数等 |
| 日志记录 | Zap | 高性能结构化日志 |
| 鉴权 | JWT | Token登录鉴权 |
| 热重载工具 | Air | 本地开发体验提升 |
📁 三、项目结构设计
go-gin-api/
├── config/ # 配置相关
├── controller/ # 控制器层
├── middleware/ # 中间件
├── model/ # 数据模型
├── router/ # 路由注册
├── service/ # 业务逻辑处理
├── utils/ # 通用工具类
├── main.go # 程序入口
└── go.mod
✅ 强烈推荐分层架构（Controller → Service → Model），便于单测和扩展。
🔧 四、环境初始化
1. 初始化 Go 模块
go mod init go-gin-api
2. 安装依赖
go get -u github.com/gin-gonic/gin
go get -u gorm.io/gorm
go get -u gorm.io/driver/mysql
go get -u github.com/spf13/viper
go get -u go.uber.org/zap
go get -u github.com/golang-jwt/jwt/v5
🗃️ 五、数据库配置 & GORM初始化
// config/database.go
package configimport ("gorm.io/driver/mysql""gorm.io/gorm""log"
)var DB *gorm.DBfunc InitDB() {dsn := "root:password@tcp(127.0.0.1:3306)/test_db?charset=utf8mb4&parseTime=True&loc=Local"var err errorDB, err = gorm.Open(mysql.Open(dsn), &gorm.Config{})if err != nil {log.Fatal("连接数据库失败：", err)}
}
👤 六、数据模型定义（User）
// model/user.go
package modelimport "gorm.io/gorm"type User struct {gorm.ModelUsername string `gorm:"unique"`Password stringEmail string
}
🔐 七、注册与登录接口（JWT鉴权）
注册接口
// controller/user.go
func Register(c *gin.Context) {var user model.Userif err := c.ShouldBindJSON(&user); err != nil {c.JSON(400, gin.H{"msg": "参数错误"})return}// 密码加密可使用 bcryptif err := config.DB.Create(&user).Error; err != nil {c.JSON(500, gin.H{"msg": "注册失败"})return}c.JSON(200, gin.H{"msg": "注册成功"})
}
登录接口（签发JWT）
func Login(c *gin.Context) {var input model.Uservar user model.Userif err := c.ShouldBindJSON(&input); err != nil {c.JSON(400, gin.H{"msg": "参数错误"})return}config.DB.Where("username = ? AND password = ?", input.Username, input.Password).First(&user)if user.ID == 0 {c.JSON(401, gin.H{"msg": "用户名或密码错误"})return}token, _ := utils.GenerateToken(user.Username) // 自定义方法生成JWTc.JSON(200, gin.H{"token": token})
}
📜 八、分页查询接口示例
func ListUsers(c *gin.Context) {var users []model.Userpage, _ := strconv.Atoi(c.DefaultQuery("page", "1"))pageSize := 10offset := (page - 1) * pageSizeconfig.DB.Offset(offset).Limit(pageSize).Find(&users)c.JSON(200, users)
}
🧱 九、中间件：JWT 鉴权中间件
func JWTAuthMiddleware() gin.HandlerFunc {return func(c *gin.Context) {tokenStr := c.GetHeader("Authorization")// 解析 token，验证签名claims, err := utils.ParseToken(tokenStr)if err != nil {c.AbortWithStatusJSON(401, gin.H{"msg": "未登录或令牌无效"})return}c.Set("username", claims.Username)c.Next()}
}
🔀 十、路由注册
// router/router.go
func InitRouter() *gin.Engine {r := gin.Default()r.POST("/register", controller.Register)r.POST("/login", controller.Login)auth := r.Group("/api", middleware.JWTAuthMiddleware()){auth.GET("/users", controller.ListUsers)// 其他增删改查}return r
}
🚀 十一、启动项目
// main.go
func main() {config.InitDB()r := router.InitRouter()r.Run(":8080")
}
✅ 十二、项目运行效果预览
使用 [Postman] 或 [curl] 调用如下接口：
POST /register注册POST /login登录获取 JWTGET /api/users使用 JWT 鉴权获取分页用户列表
🧠 十三、可拓展方向
- 接入 Casbin 做 RBAC 权限管理
- 接入 Swagger 生成接口文档
- 接入 Redis 做缓存与限流
- 部署：打包成 Docker 镜像，发布到 K8s
- 接入 go-zero 构建微服务架构
📚 学完你能收获什么？
- 掌握 Gin + GORM 的完整开发流程
- 理解分层架构，增强代码可维护性
- 掌握 JWT 鉴权机制、分页、热重载等常见功能
- 拥有一个完整、可拓展的 Golang 后端项目模板