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 config

import (
    "gorm.io/driver/mysql"
    "gorm.io/gorm"
    "log"
)

var DB *gorm.DB

func InitDB() {
    dsn := "root:password@tcp(127.0.0.1:3306)/test_db?charset=utf8mb4&parseTime=True&loc=Local"
    var err error
    DB, err = gorm.Open(mysql.Open(dsn), &gorm.Config{})
    if err != nil {
        log.Fatal("连接数据库失败：", err)
    }
}

---

👤 六、数据模型定义（User）

// model/user.go
package model

import "gorm.io/gorm"

type User struct {
    gorm.Model
    Username string `gorm:"unique"`
    Password string
    Email    string
}

---

🔐 七、注册与登录接口（JWT鉴权）

注册接口

// controller/user.go
func Register(c *gin.Context) {
    var user model.User
    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(400, gin.H{"msg": "参数错误"})
        return
    }
    // 密码加密可使用 bcrypt
    if 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.User
    var user model.User

    if 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) // 自定义方法生成JWT
    c.JSON(200, gin.H{"token": token})
}

---

📜 八、分页查询接口示例

func ListUsers(c *gin.Context) {
    var users []model.User
    page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
    pageSize := 10
    offset := (page - 1) * pageSize

    config.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 登录获取 JWT
• GET /api/users 使用 JWT 鉴权获取分页用户列表

---

🧠 十三、可拓展方向

• 接入 Casbin 做 RBAC 权限管理
• 接入 Swagger 生成接口文档
• 接入 Redis 做缓存与限流
• 部署：打包成 Docker 镜像，发布到 K8s
• 接入 go-zero 构建微服务架构

---

📚 学完你能收获什么？

• 掌握 Gin + GORM 的完整开发流程
• 理解分层架构，增强代码可维护性
• 掌握 JWT 鉴权机制、分页、热重载等常见功能
• 拥有一个完整、可拓展的 Golang 后端项目模板

Golang全栈开发，猛戳这里