Golang实现简单API接口服务_从零搭建RESTful项目

选 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 混在同一个路由树里，等于给后续加鉴权、日志、限流埋雷。从第一天就用分组隔离关注点。

立即学习“go 语言免费学习笔记（深入）”；

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 成本远高于初期多花两分钟理清。