直接上手 gin 项目最常卡在三件事：模块初始化失败、路由注册后仍 404、json 中文乱码；根源是 go 环境配置（如 go≥1.16、goproxy 设置、go mod init 路径合理）、未显式注册路由及未调用 r.run()，以及结构体 json tag 缺失 string 或 time_format。
直接上手 Gin 项目，最常卡在三件事：模块初始化失败、路由注册后仍 404、中文返回乱码。这些问题基本和 Gin 本身无关，而是 Go 环境与配置细节没对齐。
go mod init 必须执行且路径要合理
Gin 是基于 Go modules 的框架，低于 Go 1.16 或没启用 module 模式时，go get github.com/gin-gonic/gin 会写入 $GOROOT/src，后续 import "github.com/gin-gonic/gin" 仍报未定义。
- 先确认 Go 版本：
go version输出应为go version go1.21.x或更高 - 设置国内代理（避免超时）：
go env -w GOPROXY=https://goproxy.cn,direct - 项目根目录下执行：
go mod init myapp（名字别用gin或main这类保留名） - 之后所有依赖都由
go mod tidy自动管理，不要手动改go.mod或删go.sum
gin.Default() 不等于服务就跑起来了
gin.Default() 只是创建了一个带日志和 panic 恢复的引擎实例，它本身不注册任何路由。没调 r.GET、r.POST 就启动，访问任何路径都是 404。
- 必须显式注册至少一个路由，例如：
r.GET("/ping", func(c *gin.Context) { c.String(200, "ok") }) - 路径匹配严格：
r.GET("/api/users")不会响应/api/users/（末尾斜杠不自动补全） - 启动前建议加一句
fmt.Println("Server starting on :8080")，避免黑屏无反馈误以为挂了 - 调试时可临时用
gin.SetMode(gin.DebugMode)（默认已开启），生产务必切到gin.ReleaseMode
JSON 返回中文乱码或时间格式不对
Gin 默认用 Go 原生 json.Marshal，中文会被转成 \u4f60\u597d，time.Time 字段默认序列化为 RFC3339（如 "2026-09-28T12:16:00+08:00"），前端很难直接用。
- 解决中文：不需要改 header，关键是结构体字段 tag 加
string，例如Name string `json:"name,string"`；更稳妥的是全局统一设 Content-Type：r.Use(func(c *gin.Context) { c.Header("Content-Type", "application/json; charset=utf-8") }) - 解决时间：定义字段时用
time.Time类型，并加time_formattag：CreatedAt time.Time `json:"created_at" time_format:"2006-01-02 15:04:05"` - 注意：Gin 不会自动识别
time_format，必须确保你用的是 v1.9.0+ 版本（旧版需自己写自定义 marshal）
真正容易被忽略的点是：Gin 项目里没有“脚手架生成文件”这回事——main.go、router.go、handlers/ 全靠手建，go mod init 和 go mod tidy 是唯二自动生成的文件。别等 gin create 命令，它不存在。
