# 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）

在项目根目录执行：

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

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

```bash
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 目录下执行：

```bash
go mod tidy
go build ./...
```

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

---

## 六、小结

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