Golang搭建RESTfulAPI入门教程

哈喽！今天心血来潮给大家带来了《Golang搭建简单API服务，RESTful项目入门》，想必大家应该对Golang都不陌生吧，那么阅读本文就都不会很困难，以下内容主要涉及到，若是你正在学习Golang，千万别错过这篇文章~希望能帮助到你！

选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搭建RESTfulAPI入门教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！