知识小屋

    常见错误排查

    本节整理初学 Gin 时最常见的问题。

    一、go get 失败

    命令：

    go get github.com/gin-gonic/gin

    如果下载失败，先检查代理：

    go env GOPROXY

    国内网络可以设置：

    go env -w GOPROXY=https://goproxy.cn,direct

    然后重新执行：

    go mod tidy

    二、访问接口 404

    常见原因：

    • 路径写错。
    • HTTP 方法写错。
    • 路由分组前缀忘了。

    例如注册的是：

    api := router.Group("/api/v1")
api.GET("/users", listUsers)

    实际访问路径应该是：

    GET /api/v1/users

    不是：

    GET /users

    三、JSON 绑定拿不到值

    检查三点：

    1. 请求头是否是 Content-Type: application/json。
    2. 结构体字段是否首字母大写。
    3. JSON 标签是否写对。

    错误示例：

    type User struct {
	name string `json:"name"`
}

    name 是小写字段，Gin 无法写入。

    正确：

    type User struct {
	Name string `json:"name"`
}

    四、ShouldBindJSON 报 EOF

    EOF 通常表示请求体为空。

    如果接口需要 JSON 请求体，请确认前端真的传了 body。

    例如 curl：

    curl -X POST http://127.0.0.1:8080/users ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"张三\"}"

    PowerShell 里也可以使用：

    Invoke-RestMethod -Method Post `
  -Uri "http://127.0.0.1:8080/users" `
  -ContentType "application/json" `
  -Body '{"name":"张三"}'

    五、端口被占用

    错误类似：

    bind: address already in use

    说明 8080 端口已经被别的程序占用。

    可以换端口：

    router.Run(":8081")

    或者关闭占用端口的进程。

    六、中间件没有生效

    检查中间件注册位置。

    只对分组生效：

    admin := router.Group("/admin")
admin.Use(AuthMiddleware())

    这不会影响 /api/users。

    如果要全局生效：

    router.Use(AuthMiddleware())

    七、生产环境仍是 debug 模式

    如果启动时看到 debug 提示，说明还在开发模式。

    生产环境设置：

    GIN_MODE=release

    或者代码里设置：

    gin.SetMode(gin.ReleaseMode)

    更推荐用环境变量控制，不要把生产配置写死在代码里。