Golang搭建RESTfulAPI教程详解

本篇文章主要是结合我之前面试的各种经历和实战开发中遇到的问题解决经验整理的，希望这篇《Golang搭建RESTful API接口教程》对你有很大帮助！欢迎收藏，分享给更多的需要的朋友学习~

选gin而非net/http：路由分组、中间件、JSON绑定开箱即用且性能不输；net/http仅适用于极简场景或协议层调试；务必设超时与优雅退出，结构体JSON字段需显式tag。

用 net/http 还是 gin？选型要看这三点

直接上生产环境别硬刚 net/http，除非你明确要极简、无依赖、或做协议层调试。日常开发中，gin 是更务实的选择：路由分组、中间件、JSON绑定、错误处理都开箱即用，且性能不输原生。

• net/http 适合写 CLI 工具的 HTTP 客户端、测试 mock 服务、或嵌入式轻量 endpoint（比如健康检查 /health）
• gin 的 c.ShouldBindJSON(&v) 自动处理空体、类型错、字段缺失，而 net/http 得自己调 json.Decode + 检查 io.EOF 和 json.SyntaxError
• 别用 echo 或 fiber 除非团队已有约定——gin 的文档、生态、IDE 支持最稳，go mod tidy 后依赖干净，没隐藏的 cgo 或锁竞争风险

定义结构体时，JSON 字段名必须显式声明

Go 结构体字段默认不会被 JSON 序列化，除非首字母大写 + 显式加 json tag。漏掉 tag 是最常见 500 错误源头之一，尤其当字段名含下划线或想兼容前端驼峰命名时。

type User struct {
    ID       int    `json:"id"`
    UserName string `json:"user_name"` // 不写这行，前端收不到 user_name 字段
    Email    string `json:"email,omitempty"` // omitempty 在值为空时不输出该字段
}

• 所有 API 响应结构体统一加 json tag，别依赖默认行为
• 请求体（POST /users）和响应体（GET /users/1）建议用不同结构体，避免 omitempty 干扰必填校验
• 时间字段用 time.Time 没问题，但确保前端传的是 RFC3339 格式（如 "2024-05-20T14:23:15Z"），否则 ShouldBindJSON 直接报错

启动服务前务必设置超时和优雅退出

不设超时的 http.Server 会卡住长连接，导致重启时连接堆积；不处理信号则 kill -15 后进程僵死，K8s readiness probe 失败。

srv := &http.Server{
    Addr:         ":8080",
    Handler:      router,
    ReadTimeout:  10 * time.Second,
    WriteTimeout: 30 * time.Second,
    IdleTimeout:  60 * time.Second,
}
// 优雅退出
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
go func() {
<-quit
log.Println("shutting down server...")
if err := srv.Shutdown(context.Background()); err != nil {
log.Fatal("server shutdown error:", err)
}
}()
log.Println("server started on :8080")
log.Fatal(srv.ListenAndServe())

• ReadTimeout 防慢请求占满 worker，WriteTimeout 防后端慢导致响应发不出
• IdleTimeout 必须设，否则 keep-alive 连接永久挂起，连接数持续上涨
• 别用 log.Fatal(srv.ListenAndServe()) 独立启动——它不响应信号，必须包一层 srv.Shutdown()

路由分组 + 中间件 = 可维护性的起点

把 /api/v1/users 和 /health 混在同一个路由树里，等于给后续加鉴权、日志、限流埋雷。从第一天就用分组隔离关注点。

router := gin.Default()
// 公共路由（无需鉴权）
router.GET("/health", healthHandler)
// API 分组（带版本、可统一加中间件）
v1 := router.Group("/api/v1")
{
v1.Use(authMiddleware(), loggingMiddleware())
v1.GET("/users", listUsers)
v1.POST("/users", createUser)
v1.GET("/users/:id", getUser)
}

• router.Group() 返回新路由组，括号内是链式调用作用域，不是代码块作用域——变量依然可见
• 中间件函数必须以 c.Next() 结尾，否则后续 handler 不执行；想中断就 c.Abort()，比如鉴权失败时写 c.JSON(401, gin.H{"error": "unauthorized"})
• 别在中间件里 recover panic——gin.Default() 已内置 recovery 中间件，重复 recover 会导致日志重复或 panic 被吞掉

复杂点在于中间件顺序：日志要最外层，鉴权紧贴业务 handler，而跨域（CORS）一般放最外层或紧挨路由组。这些顺序一旦写错，debug 成本远高于初期多花两分钟理清。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~