gin-gonic/gin
GitHub: gin-gonic/gin
Gin 是一个用 Go 语言编写的高性能 HTTP Web 框架，专为快速构建 REST API、Web 应用和微服务而设计。
Stars: 88172 | Forks: 8560
# Gin Web Framework
[](https://github.com/gin-gonic/gin/actions/workflows/gin.yml)
[](https://github.com/gin-gonic/gin/actions/workflows/trivy-scan.yml)
[](https://codecov.io/gh/gin-gonic/gin)
[](https://goreportcard.com/report/github.com/gin-gonic/gin)
[](https://pkg.go.dev/github.com/gin-gonic/gin?tab=doc)
[](https://sourcegraph.com/github.com/gin-gonic/gin?badge)
[](https://www.codetriage.com/gin-gonic/gin)
[](https://github.com/gin-gonic/gin/releases)
## 📰 Gin 1.12.0 现已发布！
我们很高兴地宣布 **[Gin 1.12.0](https://gin-gonic.com/en/blog/news/gin-1-12-0-release-announcement/)** 的发布！此版本带来了新功能、性能改进和重要的错误修复。请查看我们官方博客上的[发布公告](https://gin-gonic.com/en/blog/news/gin-1-12-0-release-announcement/)了解完整详情。
Gin 是一个用 [Go](https://go.dev/) 编写的高性能 HTTP web framework。它提供了类似 Martini 的 API，但由于 [httprouter](https://github.com/julienschmidt/httprouter)，其性能显著更好——快达 40 倍。Gin 专为构建 REST API、web 应用程序和 microservices 而设计，在这些场景中速度和开发人员效率至关重要。
**为什么选择 Gin？**
Gin 结合了 Express.js 风格路由的简洁性与 Go 的性能特征，非常适合：
- 构建高吞吐量的 REST API
- 开发需要处理大量并发请求的 microservices
- 创建需要快速响应时间的 web 应用程序
- 以最少的样板代码快速原型化 web 服务
**Gin 的主要特性：**
- **零分配路由** - 极其节省内存的路由，无堆分配
- **高性能** - 基准测试显示，与其他 Go web frameworks 相比，其速度具有显著优势
- **中间件支持** - 可扩展的中间件系统，用于身份验证、日志记录、CORS 等
- **防止崩溃** - 内置的恢复中间件可防止 panic 导致服务器崩溃
- **JSON 验证** - 自动化的请求/响应 JSON 绑定和验证
- **路由分组** - 组织相关路由并应用通用中间件
- **错误管理** - 集中的错误处理和日志记录
- **内置渲染** - 支持 JSON、XML、HTML 模板等
- **可扩展** - 庞大的社区中间件和插件生态系统
## 入门指南
### 前置条件
- **Go 版本**：Gin 要求 [Go](https://go.dev/) 版本为 [1.25](https://go.dev/doc/devel/release#go1.25.0) 或更高
- **Go 基础知识**：熟悉 Go 语法和包管理会有所帮助
### 安装
借助 [Go 的 module 支持](https://go.dev/wiki/Modules#how-to-use-modules)，只需在你的代码中导入 Gin，Go 会在构建期间自动获取它：
```
import "github.com/gin-gonic/gin"
```
### 你的第一个 Gin 应用程序
这是一个展示 Gin 简洁性的完整示例：
```
package main
import (
"log"
"net/http"
"github.com/gin-gonic/gin"
)
func main() {
// Create a Gin router with default middleware (logger and recovery)
r := gin.Default()
// Define a simple GET endpoint
r.GET("/ping", func(c *gin.Context) {
// Return JSON response
c.JSON(http.StatusOK, gin.H{
"message": "pong",
})
})
// Start server on port 8080 (default)
// Server will listen on 0.0.0.0:8080 (localhost:8080 on Windows)
if err := r.Run(); err != nil {
log.Fatalf("failed to run server: %v", err)
}
}
```
**运行应用程序：**
1. 将上面的代码保存为 `main.go`
2. 运行应用程序：
go run main.go
3. 打开浏览器并访问 [`http://localhost:8080/ping`](http://localhost:8080/ping)
4. 你应该会看到：`{"message":"pong"}`
**此示例演示了：**
- 使用默认中间件创建 Gin 路由
- 使用简单的处理函数定义 HTTP endpoint
- 返回 JSON 响应
- 启动 HTTP 服务器
### 后续步骤
运行你的第一个 Gin 应用程序后，请探索这些资源以了解更多信息：
#### 📚 学习资源
- **[Gin 快速入门指南](docs/doc.md)** - 包含 API 示例和构建配置的综合教程
- **[示例仓库](https://github.com/gin-gonic/examples)** - 即开即用的示例，展示了各种 Gin 用例：
- REST API 开发
- 身份验证与中间件
- 文件上传和下载
- WebSocket 连接
- 模板渲染
## 📖 文档
### API 参考
- **[Go.dev API 文档](https://pkg.go.dev/github.com/gin-gonic/gin)** - 包含示例的完整 API 参考
### 用户指南
综合文档可在 [gin-gonic.com](https://gin-gonic.com) 上获取，支持多种语言：
- [English](https://gin-gonic.com/en/docs/) | [简体中文](https://gin-gonic.com/zh-cn/docs/) | [繁體中文](https://gin-gonic.com/zh-tw/docs/)
- [日本語](https://gin-gonic.com/ja/docs/) | [한국어](https://gin-gonic.com/ko-kr/docs/) | [Español](https://gin-gonic.com/es/docs/)
- [Turkish](https://gin-gonic.com/tr/docs/) | [Persian](https://gin-gonic.com/fa/docs/) | [Português](https://gin-gonic.com/pt/docs/)
- [Russian](https://gin-gonic.com/ru/docs/) | [Indonesian](https://gin-gonic.com/id/docs/)
### 官方教程
- [Go.dev 教程：使用 Go 和 Gin 开发 RESTful API](https://go.dev/doc/tutorial/web-service-gin)
## ⚡ 性能基准测试
与其他 Go web frameworks 相比，Gin 展示了卓越的性能。它使用自定义版本的 [HttpRouter](https://github.com/julienschmidt/httprouter) 以实现最高效率。[查看详细基准测试 →](/BENCHMARKS.md)
**Gin 与其他 Go 框架对比**（GitHub API 路由基准测试）：
| Benchmark name | (1) | (2) | (3) | (4) |
| ------------------------------ | --------: | --------------: | -----------: | --------------: |
| BenchmarkGin_GithubAll | **43550** | **27364 ns/op** | **0 B/op** | **0 allocs/op** |
| BenchmarkAce_GithubAll | 40543 | 29670 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkAero_GithubAll | 57632 | 20648 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkBear_GithubAll | 9234 | 216179 ns/op | 86448 B/op | 943 allocs/op |
| BenchmarkBeego_GithubAll | 7407 | 243496 ns/op | 71456 B/op | 609 allocs/op |
| BenchmarkBone_GithubAll | 420 | 2922835 ns/op | 720160 B/op | 8620 allocs/op |
| BenchmarkChi_GithubAll | 7620 | 238331 ns/op | 87696 B/op | 609 allocs/op |
| BenchmarkDenco_GithubAll | 18355 | 64494 ns/op | 20224 B/op | 167 allocs/op |
| BenchmarkEcho_GithubAll | 31251 | 38479 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkGocraftWeb_GithubAll | 4117 | 300062 ns/op | 131656 B/op | 1686 allocs/op |
| BenchmarkGoji_GithubAll | 3274 | 416158 ns/op | 56112 B/op | 334 allocs/op |
| BenchmarkGojiv2_GithubAll | 1402 | 870518 ns/op | 352720 B/op | 4321 allocs/op |
| BenchmarkGoJsonRest_GithubAll | 2976 | 401507 ns/op | 134371 B/op | 2737 allocs/op |
| BenchmarkGoRestful_GithubAll | 410 | 2913158 ns/op | 910144 B/op | 2938 allocs/op |
| BenchmarkGorillaMux_GithubAll | 346 | 3384987 ns/op | 251650 B/op | 1994 allocs/op |
| BenchmarkGowwwRouter_GithubAll | 10000 | 143025 ns/op | 72144 B/op | 501 allocs/op |
| BenchmarkHttpRouter_GithubAll | 55938 | 21360 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkHttpTreeMux_GithubAll | 10000 | 153944 ns/op | 65856 B/op | 671 allocs/op |
| BenchmarkKocha_GithubAll | 10000 | 106315 ns/op | 23304 B/op | 843 allocs/op |
| BenchmarkLARS_GithubAll | 47779 | 25084 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkMacaron_GithubAll | 3266 | 371907 ns/op | 149409 B/op | 1624 allocs/op |
| BenchmarkMartini_GithubAll | 331 | 3444706 ns/op | 226551 B/op | 2325 allocs/op |
| BenchmarkPat_GithubAll | 273 | 4381818 ns/op | 1483152 B/op | 26963 allocs/op |
| BenchmarkPossum_GithubAll | 10000 | 164367 ns/op | 84448 B/op | 609 allocs/op |
| BenchmarkR2router_GithubAll | 10000 | 160220 ns/op | 77328 B/op | 979 allocs/op |
| BenchmarkRivet_GithubAll | 14625 | 82453 ns/op | 16272 B/op | 167 allocs/op |
| BenchmarkTango_GithubAll | 6255 | 279611 ns/op | 63826 B/op | 1618 allocs/op |
| BenchmarkTigerTonic_GithubAll | 2008 | 687874 ns/op | 193856 B/op | 4474 allocs/op |
| BenchmarkTraffic_GithubAll | 355 | 3478508 ns/op | 820744 B/op | 14114 allocs/op |
| BenchmarkVulcan_GithubAll | 6885 | 193333 ns/op | 19894 B/op | 609 allocs/op |
- (1): 在恒定时间内完成的重复总次数，越高表示结果越可信
- (2): 单次重复持续时间 (ns/op)，越低越好
- (3): 堆内存 (B/op)，越低越好
- (4): 每次重复的平均分配数 (allocs/op)，越低越好
## 🔌 中间件生态系统
Gin 拥有丰富的中间件生态系统，可满足常见的 web 开发需求。探索社区贡献的中间件：
- **[gin-contrib](https://github.com/gin-contrib)** - 官方中间件集合，包括：
- 身份验证 (JWT, Basic Auth, Sessions)
- CORS, 速率限制, 压缩
- 日志记录, 指标, 追踪
- 静态文件服务, 模板引擎
- **[gin-gonic/contrib](https://github.com/gin-gonic/contrib)** - 其他社区中间件
## 🏇 生产环境使用
Gin 为许多高流量的应用程序和服务提供支持：
- **[gorush](https://github.com/appleboy/gorush)** - 高性能推送通知服务器
- **[fnproject](https://github.com/fnproject/fn)** - Container-native, serverless 平台
- **[photoprism](https://github.com/photoprism/photoprism)** - AI 驱动的个人照片管理
- **[lura](https://github.com/luraproject/lura)** - 超高性能 API Gateway 框架
- **[picfit](https://github.com/thoas/picfit)** - 实时图像处理服务器
- **[dkron](https://github.com/distribworks/dkron)** - 分布式作业调度系统
## 🤝 贡献
Gin 是来自世界各地的数百名贡献者的成果。我们欢迎并感谢您的贡献！
### 如何贡献
- 🐛 **报告错误** - 帮助我们识别和修复问题
- 💡 **建议功能** - 分享您的改进想法
- 📝 **改进文档** - 帮助使我们的文档更清晰
- 🔧 **提交代码** - 修复错误或实现新功能
- 🧪 **编写测试** - 改进我们的测试覆盖率
### 开始贡献
1.查看我们的 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取详细指南
2. 加入我们的社区讨论并提出问题
**所有的贡献都受到重视，并帮助让 Gin 对每个人变得更好！**
[](https://github.com/gin-gonic/gin/actions/workflows/gin.yml)
[](https://github.com/gin-gonic/gin/actions/workflows/trivy-scan.yml)
[](https://codecov.io/gh/gin-gonic/gin)
[](https://goreportcard.com/report/github.com/gin-gonic/gin)
[](https://pkg.go.dev/github.com/gin-gonic/gin?tab=doc)
[](https://sourcegraph.com/github.com/gin-gonic/gin?badge)
[](https://www.codetriage.com/gin-gonic/gin)
[](https://github.com/gin-gonic/gin/releases)
## 📰 Gin 1.12.0 现已发布！
我们很高兴地宣布 **[Gin 1.12.0](https://gin-gonic.com/en/blog/news/gin-1-12-0-release-announcement/)** 的发布！此版本带来了新功能、性能改进和重要的错误修复。请查看我们官方博客上的[发布公告](https://gin-gonic.com/en/blog/news/gin-1-12-0-release-announcement/)了解完整详情。
Gin 是一个用 [Go](https://go.dev/) 编写的高性能 HTTP web framework。它提供了类似 Martini 的 API，但由于 [httprouter](https://github.com/julienschmidt/httprouter)，其性能显著更好——快达 40 倍。Gin 专为构建 REST API、web 应用程序和 microservices 而设计，在这些场景中速度和开发人员效率至关重要。
**为什么选择 Gin？**
Gin 结合了 Express.js 风格路由的简洁性与 Go 的性能特征，非常适合：
- 构建高吞吐量的 REST API
- 开发需要处理大量并发请求的 microservices
- 创建需要快速响应时间的 web 应用程序
- 以最少的样板代码快速原型化 web 服务
**Gin 的主要特性：**
- **零分配路由** - 极其节省内存的路由，无堆分配
- **高性能** - 基准测试显示，与其他 Go web frameworks 相比，其速度具有显著优势
- **中间件支持** - 可扩展的中间件系统，用于身份验证、日志记录、CORS 等
- **防止崩溃** - 内置的恢复中间件可防止 panic 导致服务器崩溃
- **JSON 验证** - 自动化的请求/响应 JSON 绑定和验证
- **路由分组** - 组织相关路由并应用通用中间件
- **错误管理** - 集中的错误处理和日志记录
- **内置渲染** - 支持 JSON、XML、HTML 模板等
- **可扩展** - 庞大的社区中间件和插件生态系统
## 入门指南
### 前置条件
- **Go 版本**：Gin 要求 [Go](https://go.dev/) 版本为 [1.25](https://go.dev/doc/devel/release#go1.25.0) 或更高
- **Go 基础知识**：熟悉 Go 语法和包管理会有所帮助
### 安装
借助 [Go 的 module 支持](https://go.dev/wiki/Modules#how-to-use-modules)，只需在你的代码中导入 Gin，Go 会在构建期间自动获取它：
```
import "github.com/gin-gonic/gin"
```
### 你的第一个 Gin 应用程序
这是一个展示 Gin 简洁性的完整示例：
```
package main
import (
"log"
"net/http"
"github.com/gin-gonic/gin"
)
func main() {
// Create a Gin router with default middleware (logger and recovery)
r := gin.Default()
// Define a simple GET endpoint
r.GET("/ping", func(c *gin.Context) {
// Return JSON response
c.JSON(http.StatusOK, gin.H{
"message": "pong",
})
})
// Start server on port 8080 (default)
// Server will listen on 0.0.0.0:8080 (localhost:8080 on Windows)
if err := r.Run(); err != nil {
log.Fatalf("failed to run server: %v", err)
}
}
```
**运行应用程序：**
1. 将上面的代码保存为 `main.go`
2. 运行应用程序：
go run main.go
3. 打开浏览器并访问 [`http://localhost:8080/ping`](http://localhost:8080/ping)
4. 你应该会看到：`{"message":"pong"}`
**此示例演示了：**
- 使用默认中间件创建 Gin 路由
- 使用简单的处理函数定义 HTTP endpoint
- 返回 JSON 响应
- 启动 HTTP 服务器
### 后续步骤
运行你的第一个 Gin 应用程序后，请探索这些资源以了解更多信息：
#### 📚 学习资源
- **[Gin 快速入门指南](docs/doc.md)** - 包含 API 示例和构建配置的综合教程
- **[示例仓库](https://github.com/gin-gonic/examples)** - 即开即用的示例，展示了各种 Gin 用例：
- REST API 开发
- 身份验证与中间件
- 文件上传和下载
- WebSocket 连接
- 模板渲染
## 📖 文档
### API 参考
- **[Go.dev API 文档](https://pkg.go.dev/github.com/gin-gonic/gin)** - 包含示例的完整 API 参考
### 用户指南
综合文档可在 [gin-gonic.com](https://gin-gonic.com) 上获取，支持多种语言：
- [English](https://gin-gonic.com/en/docs/) | [简体中文](https://gin-gonic.com/zh-cn/docs/) | [繁體中文](https://gin-gonic.com/zh-tw/docs/)
- [日本語](https://gin-gonic.com/ja/docs/) | [한국어](https://gin-gonic.com/ko-kr/docs/) | [Español](https://gin-gonic.com/es/docs/)
- [Turkish](https://gin-gonic.com/tr/docs/) | [Persian](https://gin-gonic.com/fa/docs/) | [Português](https://gin-gonic.com/pt/docs/)
- [Russian](https://gin-gonic.com/ru/docs/) | [Indonesian](https://gin-gonic.com/id/docs/)
### 官方教程
- [Go.dev 教程：使用 Go 和 Gin 开发 RESTful API](https://go.dev/doc/tutorial/web-service-gin)
## ⚡ 性能基准测试
与其他 Go web frameworks 相比，Gin 展示了卓越的性能。它使用自定义版本的 [HttpRouter](https://github.com/julienschmidt/httprouter) 以实现最高效率。[查看详细基准测试 →](/BENCHMARKS.md)
**Gin 与其他 Go 框架对比**（GitHub API 路由基准测试）：
| Benchmark name | (1) | (2) | (3) | (4) |
| ------------------------------ | --------: | --------------: | -----------: | --------------: |
| BenchmarkGin_GithubAll | **43550** | **27364 ns/op** | **0 B/op** | **0 allocs/op** |
| BenchmarkAce_GithubAll | 40543 | 29670 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkAero_GithubAll | 57632 | 20648 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkBear_GithubAll | 9234 | 216179 ns/op | 86448 B/op | 943 allocs/op |
| BenchmarkBeego_GithubAll | 7407 | 243496 ns/op | 71456 B/op | 609 allocs/op |
| BenchmarkBone_GithubAll | 420 | 2922835 ns/op | 720160 B/op | 8620 allocs/op |
| BenchmarkChi_GithubAll | 7620 | 238331 ns/op | 87696 B/op | 609 allocs/op |
| BenchmarkDenco_GithubAll | 18355 | 64494 ns/op | 20224 B/op | 167 allocs/op |
| BenchmarkEcho_GithubAll | 31251 | 38479 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkGocraftWeb_GithubAll | 4117 | 300062 ns/op | 131656 B/op | 1686 allocs/op |
| BenchmarkGoji_GithubAll | 3274 | 416158 ns/op | 56112 B/op | 334 allocs/op |
| BenchmarkGojiv2_GithubAll | 1402 | 870518 ns/op | 352720 B/op | 4321 allocs/op |
| BenchmarkGoJsonRest_GithubAll | 2976 | 401507 ns/op | 134371 B/op | 2737 allocs/op |
| BenchmarkGoRestful_GithubAll | 410 | 2913158 ns/op | 910144 B/op | 2938 allocs/op |
| BenchmarkGorillaMux_GithubAll | 346 | 3384987 ns/op | 251650 B/op | 1994 allocs/op |
| BenchmarkGowwwRouter_GithubAll | 10000 | 143025 ns/op | 72144 B/op | 501 allocs/op |
| BenchmarkHttpRouter_GithubAll | 55938 | 21360 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkHttpTreeMux_GithubAll | 10000 | 153944 ns/op | 65856 B/op | 671 allocs/op |
| BenchmarkKocha_GithubAll | 10000 | 106315 ns/op | 23304 B/op | 843 allocs/op |
| BenchmarkLARS_GithubAll | 47779 | 25084 ns/op | 0 B/op | 0 allocs/op |
| BenchmarkMacaron_GithubAll | 3266 | 371907 ns/op | 149409 B/op | 1624 allocs/op |
| BenchmarkMartini_GithubAll | 331 | 3444706 ns/op | 226551 B/op | 2325 allocs/op |
| BenchmarkPat_GithubAll | 273 | 4381818 ns/op | 1483152 B/op | 26963 allocs/op |
| BenchmarkPossum_GithubAll | 10000 | 164367 ns/op | 84448 B/op | 609 allocs/op |
| BenchmarkR2router_GithubAll | 10000 | 160220 ns/op | 77328 B/op | 979 allocs/op |
| BenchmarkRivet_GithubAll | 14625 | 82453 ns/op | 16272 B/op | 167 allocs/op |
| BenchmarkTango_GithubAll | 6255 | 279611 ns/op | 63826 B/op | 1618 allocs/op |
| BenchmarkTigerTonic_GithubAll | 2008 | 687874 ns/op | 193856 B/op | 4474 allocs/op |
| BenchmarkTraffic_GithubAll | 355 | 3478508 ns/op | 820744 B/op | 14114 allocs/op |
| BenchmarkVulcan_GithubAll | 6885 | 193333 ns/op | 19894 B/op | 609 allocs/op |
- (1): 在恒定时间内完成的重复总次数，越高表示结果越可信
- (2): 单次重复持续时间 (ns/op)，越低越好
- (3): 堆内存 (B/op)，越低越好
- (4): 每次重复的平均分配数 (allocs/op)，越低越好
## 🔌 中间件生态系统
Gin 拥有丰富的中间件生态系统，可满足常见的 web 开发需求。探索社区贡献的中间件：
- **[gin-contrib](https://github.com/gin-contrib)** - 官方中间件集合，包括：
- 身份验证 (JWT, Basic Auth, Sessions)
- CORS, 速率限制, 压缩
- 日志记录, 指标, 追踪
- 静态文件服务, 模板引擎
- **[gin-gonic/contrib](https://github.com/gin-gonic/contrib)** - 其他社区中间件
## 🏇 生产环境使用
Gin 为许多高流量的应用程序和服务提供支持：
- **[gorush](https://github.com/appleboy/gorush)** - 高性能推送通知服务器
- **[fnproject](https://github.com/fnproject/fn)** - Container-native, serverless 平台
- **[photoprism](https://github.com/photoprism/photoprism)** - AI 驱动的个人照片管理
- **[lura](https://github.com/luraproject/lura)** - 超高性能 API Gateway 框架
- **[picfit](https://github.com/thoas/picfit)** - 实时图像处理服务器
- **[dkron](https://github.com/distribworks/dkron)** - 分布式作业调度系统
## 🤝 贡献
Gin 是来自世界各地的数百名贡献者的成果。我们欢迎并感谢您的贡献！
### 如何贡献
- 🐛 **报告错误** - 帮助我们识别和修复问题
- 💡 **建议功能** - 分享您的改进想法
- 📝 **改进文档** - 帮助使我们的文档更清晰
- 🔧 **提交代码** - 修复错误或实现新功能
- 🧪 **编写测试** - 改进我们的测试覆盖率
### 开始贡献
1.查看我们的 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取详细指南
2. 加入我们的社区讨论并提出问题
**所有的贡献都受到重视，并帮助让 Gin 对每个人变得更好！**标签：API开发, DNS解析, EVTX分析, Gin, Golang, Go语言, httprouter, HTTP服务器, REST API, Syscall, Web开发, Web框架, 中间件, 后端开发, 安全编程, 开源项目, 快速开发, 日志审计, 程序破解, 路由