2017-04-28 13:59:23 +03:00
# Gin Web Framework
2017-03-16 18:54:00 +03:00
2017-07-07 10:21:44 +03:00
< img align = "right" width = "159px" src = "https://raw.githubusercontent.com/gin-gonic/logo/master/color.png" >
2017-04-28 13:59:23 +03:00
2021-06-23 08:10:49 +03:00
[![Build Status ](https://github.com/gin-gonic/gin/workflows/Run%20Tests/badge.svg?branch=master )](https://github.com/gin-gonic/gin/actions?query=branch%3Amaster)
2018-08-07 08:49:31 +03:00
[![codecov ](https://codecov.io/gh/gin-gonic/gin/branch/master/graph/badge.svg )](https://codecov.io/gh/gin-gonic/gin)
[![Go Report Card ](https://goreportcard.com/badge/github.com/gin-gonic/gin )](https://goreportcard.com/report/github.com/gin-gonic/gin)
2024-06-06 12:10:03 +03:00
[![Go Reference ](https://pkg.go.dev/badge/github.com/gin-gonic/gin?status.svg )](https://pkg.go.dev/github.com/gin-gonic/gin?tab=doc)
2018-08-07 08:49:31 +03:00
[![Sourcegraph ](https://sourcegraph.com/github.com/gin-gonic/gin/-/badge.svg )](https://sourcegraph.com/github.com/gin-gonic/gin?badge)
2018-02-22 16:28:50 +03:00
[![Open Source Helpers ](https://www.codetriage.com/gin-gonic/gin/badges/users.svg )](https://www.codetriage.com/gin-gonic/gin)
2018-09-22 06:37:28 +03:00
[![Release ](https://img.shields.io/github/release/gin-gonic/gin.svg?style=flat-square )](https://github.com/gin-gonic/gin/releases)
2020-02-21 11:33:36 +03:00
[![TODOs ](https://badgen.net/https/api.tickgit.com/badgen/github.com/gin-gonic/gin )](https://www.tickgit.com/browse?repo=github.com/gin-gonic/gin)
2015-02-21 14:24:57 +03:00
2024-05-13 06:12:55 +03:00
Gin is a web framework written in [Go ](https://go.dev/ ). It features a martini-like API with performance that is up to 40 times faster thanks to [httprouter ](https://github.com/julienschmidt/httprouter ).
If you need performance and good productivity, you will love Gin.
2014-09-13 22:37:27 +04:00
2024-05-13 06:12:55 +03:00
**Gin's key features are:**
2018-04-20 04:54:00 +03:00
2023-01-02 05:40:25 +03:00
- Zero allocation router
2024-05-13 06:12:55 +03:00
- Speed
2023-01-02 05:40:25 +03:00
- Middleware support
- Crash-free
- JSON validation
2024-05-13 06:12:55 +03:00
- Route grouping
2023-01-02 05:40:25 +03:00
- Error management
2024-05-13 06:12:55 +03:00
- Built-in rendering
- Extensible
2018-04-20 04:54:00 +03:00
2023-01-02 05:40:25 +03:00
## Getting started
2018-06-26 13:56:43 +03:00
2023-01-02 05:40:25 +03:00
### Prerequisites
2018-06-26 13:56:43 +03:00
2024-05-13 06:12:55 +03:00
Gin requires [Go ](https://go.dev/ ) version [1.21 ](https://go.dev/doc/devel/release#go1.21.0 ) or above.
2018-06-26 13:56:43 +03:00
2023-01-02 05:40:25 +03:00
### Getting Gin
2018-06-26 13:56:43 +03:00
2024-05-13 06:12:55 +03:00
With [Go's module support ](https://go.dev/wiki/Modules#how-to-use-modules ), `go [build|run|test]` automatically fetches the necessary dependencies when you add the import in your code:
2023-01-02 05:40:25 +03:00
2024-05-09 08:45:03 +03:00
```sh
2019-04-06 16:48:33 +03:00
import "github.com/gin-gonic/gin"
```
2024-05-13 06:12:55 +03:00
Alternatively, use `go get` :
2021-01-27 04:58:21 +03:00
2019-04-06 16:48:33 +03:00
```sh
2024-05-09 08:45:03 +03:00
go get -u github.com/gin-gonic/gin
2019-04-06 16:48:33 +03:00
```
2017-03-16 18:38:30 +03:00
2023-01-02 05:40:25 +03:00
### Running Gin
2024-05-13 06:12:55 +03:00
A basic example:
2023-01-02 05:40:25 +03:00
2015-07-03 21:12:01 +03:00
```go
2014-09-13 22:37:27 +04:00
package main
2022-06-02 06:52:28 +03:00
import (
2022-08-01 04:23:45 +03:00
"net/http"
2022-06-02 06:52:28 +03:00
2022-08-01 04:23:45 +03:00
"github.com/gin-gonic/gin"
2022-06-02 06:52:28 +03:00
)
2014-09-13 22:37:27 +04:00
func main() {
2022-08-01 04:23:45 +03:00
r := gin.Default()
r.GET("/ping", func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{
"message": "pong",
})
})
r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080")
2014-09-13 22:37:27 +04:00
}
```
2024-05-13 06:12:55 +03:00
To run the code, use the `go run` command, like:
2023-01-02 05:40:25 +03:00
2024-05-09 08:45:03 +03:00
```sh
2017-07-05 05:42:56 +03:00
$ go run example.go
```
2024-05-13 06:12:55 +03:00
Then visit [`0.0.0.0:8080/ping` ](http://0.0.0.0:8080/ping ) in your browser to see the response!
### See more examples
2023-01-02 05:40:25 +03:00
#### Quick Start
2024-05-13 06:12:55 +03:00
Learn and practice with the [Gin Quick Start ](docs/doc.md ), which includes API examples and builds tag.
2023-01-02 05:40:25 +03:00
#### Examples
2024-05-13 06:12:55 +03:00
A number of ready-to-run examples demonstrating various use cases of Gin are available in the [Gin examples ](https://github.com/gin-gonic/examples ) repository.
2015-06-01 02:39:08 +03:00
2023-01-02 05:40:25 +03:00
## Documentation
2024-06-06 12:10:03 +03:00
See the [API documentation on go.dev ](https://pkg.go.dev/github.com/gin-gonic/gin ).
2023-01-02 05:40:25 +03:00
2024-05-13 06:12:55 +03:00
The documentation is also available on [gin-gonic.com ](https://gin-gonic.com ) in several languages:
2023-01-02 05:40:25 +03:00
- [English ](https://gin-gonic.com/docs/ )
- [简体中文 ](https://gin-gonic.com/zh-cn/docs/ )
- [繁體中文 ](https://gin-gonic.com/zh-tw/docs/ )
- [日本語 ](https://gin-gonic.com/ja/docs/ )
- [Español ](https://gin-gonic.com/es/docs/ )
- [한국어 ](https://gin-gonic.com/ko-kr/docs/ )
- [Turkish ](https://gin-gonic.com/tr/docs/ )
- [Persian ](https://gin-gonic.com/fa/docs/ )
2024-10-25 04:08:11 +03:00
- [Português ](https://gin-gonic.com/pt/docs/ )
2023-01-02 05:40:25 +03:00
2024-05-13 06:12:55 +03:00
### Articles
2023-01-02 05:40:25 +03:00
- [Tutorial: Developing a RESTful API with Go and Gin ](https://go.dev/doc/tutorial/web-service-gin )
## Benchmarks
2024-05-13 06:12:55 +03:00
Gin uses a custom version of [HttpRouter ](https://github.com/julienschmidt/httprouter ), [see all benchmarks ](/BENCHMARKS.md ).
2015-06-04 03:49:14 +03:00
2020-05-05 11:37:40 +03:00
| 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 |
2017-07-19 10:40:05 +03:00
2017-10-30 05:38:38 +03:00
- (1): Total Repetitions achieved in constant time, higher means more confident result
- (2): Single Repetition Duration (ns/op), lower is better
- (3): Heap Memory (B/op), lower is better
- (4): Average Allocations per Repetition (allocs/op), lower is better
2015-06-01 02:39:08 +03:00
2024-05-13 06:12:55 +03:00
## Middleware
2019-04-06 16:48:33 +03:00
2023-01-02 05:40:25 +03:00
You can find many useful Gin middlewares at [gin-contrib ](https://github.com/gin-contrib ).
2019-04-06 16:48:33 +03:00
2024-05-13 06:12:55 +03:00
## Uses
2019-04-06 16:48:33 +03:00
2024-05-13 06:12:55 +03:00
Here are some awesome projects that are using the [Gin ](https://github.com/gin-gonic/gin ) web framework.
2022-08-01 04:23:45 +03:00
2024-05-13 06:12:55 +03:00
- [gorush ](https://github.com/appleboy/gorush ): A push notification server.
- [fnproject ](https://github.com/fnproject/fn ): A container native, cloud agnostic serverless platform.
- [photoprism ](https://github.com/photoprism/photoprism ): Personal photo management powered by Google TensorFlow.
- [lura ](https://github.com/luraproject/lura ): Ultra performant API Gateway with middleware.
- [picfit ](https://github.com/thoas/picfit ): An image resizing server.
2024-05-09 08:45:03 +03:00
- [dkron ](https://github.com/distribworks/dkron ): Distributed, fault tolerant job scheduling system.
2019-04-06 16:48:33 +03:00
2023-01-02 05:40:25 +03:00
## Contributing
2019-04-06 16:48:33 +03:00
2023-01-02 05:40:25 +03:00
Gin is the work of hundreds of contributors. We appreciate your help!
2019-04-06 16:48:33 +03:00
2024-05-13 06:12:55 +03:00
Please see [CONTRIBUTING.md ](CONTRIBUTING.md ) for details on submitting patches and the contribution workflow.