Go 实现类似 FastAPI 的后端服务：从入门到实战

🚀 Go 实现类似 FastAPI 的后端服务：从入门到实战

项目地址 ：https://gitee.com/futurelei/go_server_demo

推荐阅读顺序 ：先学习 master 分支（基础版），再学习 feat-orm-sqlite3 分支（进阶版）

---

一、项目概述

这是一个专为 Go 初学者设计的后端服务示例项目，旨在帮助您快速掌握：

• ✅ Gin Web 框架：高性能 HTTP 服务开发
• ✅ Swagger API 文档：自动生成接口文档
• ✅ GORM + SQLite3：ORM 数据库操作
• ✅ Logrus + Lumberjack：企业级日志管理
• ✅ 分页查询：行业规范的分页接口设计

---

二、两个分支的区别

特性	master 分支（基础版）	feat-orm-sqlite3 分支（进阶版）
数据库	内存存储	SQLite3 + GORM
日志	fmt.Println	Logrus + 自动轮转
分页查询	基础列表	完整分页（过滤器+排序）
学习难度	入门	进阶
适用场景	学习基础	生产环境

---

三、快速开始

3.1 克隆项目

# 克隆仓库
git clone https://gitee.com/futurelei/go_server_demo.git
cd go_server_demo

# 切换到基础版（推荐新手）
git checkout master

# 或切换到进阶版
git checkout feat-orm-sqlite3

3.2 一键运行

# 安装依赖（首次运行）
./scripts/install.sh

# 编译项目
./scripts/build.sh

# 启动服务
./scripts/run.sh

3.3 访问服务

服务	地址
API 服务	http://localhost:8080
Swagger UI	http://localhost:8080/swagger/index.html
健康检查	http://localhost:8080/api/health

• swagger界面 :
  

---

四、项目结构详解（重点）

go_server/
├── cmd/server/main.go      # 主入口（核心）
├── internal/              # 内部代码（不对外暴露）
│   ├── api/               # HTTP 控制器
│   ├── model/             # 数据模型
│   ├── service/           # 业务逻辑
│   ├── repository/        # 数据访问层
│   └── database/          # 数据库连接（进阶版）
├── pkg/                   # 公共组件（可复用）
│   ├── response/          # 统一响应处理
│   └── logger/            # 日志模块（进阶版）
├── data/                  # SQLite 数据库文件
├── logs/                  # 日志文件目录
├── docs/                  # Swagger 文档（自动生成）
└── scripts/               # 开发脚本

核心设计原则：

• cmd/：命令行入口，程序启动点
• internal/：内部业务逻辑，不对外暴露
• pkg/：可复用的公共组件，可被外部引用
• scripts/：开发运维脚本集合

---

五、核心代码讲解

5.1 主入口（cmd/server/main.go）

func main() {
    // 1. 初始化配置
    cfg := config.Load()
    
    // 2. 初始化日志（进阶版）
    logger.Init(&logger.LogConfig{
        Level: "info",
        Path:  "logs/app.log",
    })
    
    // 3. 初始化数据库（进阶版）
    database.InitDB("data/go_fastapi_demo.db")
    
    // 4. 创建路由
    r := gin.Default()
    
    // 5. 注册控制器
    userController := api.NewUserController(userService)
    r.GET("/api/users", userController.GetUsers)
    
    // 6. 启动服务
    r.Run(":8080")
}

5.2 API 控制器（internal/api/user.go）

// GetUsers godoc
// @Summary Get all users
// @Description Retrieve a list of all users
// @Tags users
// @Success 200 {object} response.Response{data=[]model.User}
// @Router /api/users [get]
func (u *UserController) GetUsers(c *gin.Context) {
    users, err := u.service.GetAllUsers()
    if err != nil {
        response.InternalServerError(c, err.Error())
        return
    }
    response.Success(c, users)
}

关键点：

• 使用 Swagger 注解自动生成文档
• 通过 response.Success() 统一响应格式

5.3 统一响应（pkg/response/response.go）

type Response struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data"`
}

func Success(c *gin.Context, data interface{}) {
    c.JSON(http.StatusOK, Response{
        Code:    200,
        Message: "success",
        Data:    data,
    })
}

5.4 分页查询（进阶版）

# 请求示例
GET /api/users/paginated?page=1&page_size=10&age_min=18&sort_by=name&order=asc

# 响应示例
{
    "code": 200,
    "message": "success",
    "data": {
        "data": [...],
        "total": 100,
        "page": 1,
        "page_size": 10,
        "total_pages": 10
    }
}

---

六、进阶特性（feat-orm-sqlite3 分支）

6.1 GORM 数据库操作

func (r *GormUserRepository) GetPaginated(req *model.PaginationReq) ([]*model.User, int64, error) {
    var users []*model.User
    var total int64
    
    // 应用过滤器
    q := model.ApplyFilters(r.db.Model(&model.User{}), req)
    
    // 获取总数
    q.Count(&total)
    
    // 分页查询
    q.Order(req.BuildOrderClause()).Offset(req.GetOffset()).Limit(req.GetLimit()).Find(&users)
    
    return users, total, nil
}

6.2 Logrus 日志配置

logger.Init(&logger.LogConfig{
    Level:      "info",
    Path:       "logs/app.log",
    MaxSize:    100,      // 单个文件最大 100MB
    MaxBackups: 30,      // 保留 30 个备份
    MaxAge:     30,      // 保留 30 天
    Compress:   true,    // 自动压缩
})

6.3 请求日志中间件

func requestLogger() gin.HandlerFunc {
    return func(c *gin.Context) {
        startTime := time.Now()
        c.Next()
        
        logger.RequestLog(startTime, 
            c.Writer.Status(),
            c.ClientIP(),
            c.Request.Method,
            c.Request.URL.Path,
            time.Since(startTime),
        )
    }
}

---

七、API 接口列表

方法	路径	描述
GET	/api/health	健康检查
GET	/api/users	获取用户列表
GET	/api/users/paginated	分页查询（进阶版）
GET	/api/users/:id	获取单个用户
POST	/api/users	创建用户
PUT	/api/users/:id	更新用户
DELETE	/api/users/:id	删除用户

---

八、实战练习

练习 1：创建用户

curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"张三","email":"zhangsan@example.com","age":25}'

练习 2：分页查询

# 查询第1页，每页10条，按年龄筛选
curl "http://localhost:8080/api/users/paginated?page=1&page_size=10&age_min=18&age_max=30"

练习 3：查看日志

# 实时查看日志
tail -f logs/app.log

# 查看请求日志
grep "Request" logs/app.log

---

九、常见问题

Q1：如何修改端口？

# 方式一：命令行参数
./bin/server --port 9090

# 方式二：修改配置文件
# internal/config/config.go

Q2：Swagger 文档不更新？

# 重新生成文档
swag init -g cmd/server/main.go -o docs

Q3：如何切换数据库？

项目默认使用 SQLite，如需切换到 MySQL/PostgreSQL，只需修改 internal/database/database.go：

// SQLite（当前）
db, err = gorm.Open(sqlite.Open(dbPath), config)

// MySQL
db, err = gorm.Open(mysql.Open(dsn), config)

// PostgreSQL
db, err = gorm.Open(postgres.Open(dsn), config)

---

十、总结

通过这个项目，您可以学习到：

1. 工程规范：Go 标准项目结构
2. Web 开发：Gin 框架的核心用法
3. API 文档：Swagger 自动生成
4. 数据库：GORM + SQLite3 实战
5. 日志管理：企业级日志解决方案
6. 分页查询：行业规范的实现方式

项目地址 ：https://gitee.com/futurelei/go_server_demo

学习路径 ：master → feat-orm-sqlite3

---

如果觉得有帮助，欢迎 Star 支持！⭐