soul-yongping/开发文档/2、架构/Gin技术栈-Go1.25依赖清单.md

Gin 技术栈依赖清单（适配 Go 1.25.7）

目标版本：Go 1.25.7
原则：精简、高效、易上手、好用、安全；所有依赖均兼容 Go 1.25，无需更换或移除。

---

一、Go 版本说明

• Go 1.25 于 2025 年 8 月发布，遵守 Go 1 兼容性承诺，现有主流库均可使用。
• Gin 官方要求 Go 1.24+，1.25.7 满足要求。
• golang.org/x/*（crypto、time 等）随 Go 工具链维护，支持当前稳定版。
• 若某依赖未显式声明支持 1.25，只要其 go.mod 为 go 1.21 或更高，在 1.25 下均可正常编译使用。

---

二、依赖列表（均适配 Go 1.25.7）

1. 核心与数据库

依赖	版本建议	说明
github.com/gin-gonic/gin	最新 v1.x	要求 Go 1.24+，1.25.7 兼容。
gorm.io/gorm	最新 v1.31.x	无对高版本 Go 的限制。
gorm.io/driver/mysql	最新	与 GORM 配套。

2. 安全

依赖	版本建议	说明
github.com/unrolled/secure	v1.17+	标准 net/http 中间件，兼容 Go 1.25。
golang.org/x/crypto	最新	使用 bcrypt 等，随 Go 生态更新。
golang.org/x/time	最新	使用 rate 限流，兼容 Go 1.25。

3. 配置

依赖	版本建议	说明
github.com/joho/godotenv	v1.5.x	仅读 .env，无高版本 Go 要求。
或 github.com/caarlos0/env/v11	v11.x	解析 env 到结构体，兼容当前 Go。

4. 跨域与鉴权

依赖	版本建议	说明
github.com/gin-contrib/cors	v1.6+（务必 ≥1.6，修复 CVE）	与 Gin 1.24+ / Go 1.25 兼容。
github.com/golang-jwt/jwt/v5	最新 v5.x	推荐 v5，与 Go 1.25 兼容。

5. 接口文档（可选）

依赖	版本建议	说明
github.com/swaggo/swag/cmd/swag	最新（CLI 工具）	代码生成，使用最新 CLI 即可。
github.com/swaggo/gin-swagger	最新	与 Gin 配套。
github.com/swaggo/files	最新	Swagger UI 静态资源。

6. 开发工具（仅开发环境）

依赖	版本建议	说明
github.com/cosmtrek/air	最新	热重载，与 Go 1.25 兼容。

---

三、无需更换或移除

• 上述依赖在 Go 1.25.7 下均无需更换或移除。
• 未列入的冗余依赖（如单独再引入 validator、Viper、zap 等）按此前「精简版」建议已不纳入，无需因 Go 1.25 再改。

---

四、推荐 go.mod 片段（Go 1.25）

在项目根目录执行：

go mod init soul-server
go mod edit -go=1.25

然后按需拉取依赖（示例）：

go get github.com/gin-gonic/gin
go get gorm.io/gorm gorm.io/driver/mysql
go get github.com/unrolled/secure
go get golang.org/x/crypto golang.org/x/time
go get github.com/gin-contrib/cors
go get github.com/golang-jwt/jwt/v5
go get github.com/joho/godotenv
# 可选
go get github.com/swaggo/gin-swagger github.com/swaggo/files
# 开发
go install github.com/cosmtrek/air@latest
go install github.com/swaggo/swag/cmd/swag@latest

---

五、验证方式

在 soul-server 目录下执行：

go mod tidy
go build ./...

若通过，则当前依赖与 Go 1.25.7 兼容。若某库报错，优先升级该库至最新 minor/patch 再试。

---

六、小结

项目	结论
Go 1.25.7	支持，所有推荐依赖均适用。
需要更换的依赖	无。
需要移除的依赖	无（按本清单与精简原则已不包含不必要项）。
建议	使用 go 1.25，定期 go get -u ./... 与 go mod tidy 保持依赖健康。