README.md (8368B)
1 # Gin Web Framework 2 3 <img align="right" width="159px" src="https://raw.githubusercontent.com/gin-gonic/logo/master/color.png"> 4 5 [](https://github.com/gin-gonic/gin/actions?query=branch%3Amaster) 6 [](https://codecov.io/gh/gin-gonic/gin) 7 [](https://goreportcard.com/report/github.com/gin-gonic/gin) 8 [](https://pkg.go.dev/github.com/gin-gonic/gin?tab=doc) 9 [](https://sourcegraph.com/github.com/gin-gonic/gin?badge) 10 [](https://www.codetriage.com/gin-gonic/gin) 11 [](https://github.com/gin-gonic/gin/releases) 12 [](https://www.tickgit.com/browse?repo=github.com/gin-gonic/gin) 13 14 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. 15 16 **The key features of Gin are:** 17 18 - Zero allocation router 19 - Fast 20 - Middleware support 21 - Crash-free 22 - JSON validation 23 - Routes grouping 24 - Error management 25 - Rendering built-in 26 - Extendable 27 28 29 ## Getting started 30 31 ### Prerequisites 32 33 - **[Go](https://go.dev/)**: any one of the **three latest major** [releases](https://go.dev/doc/devel/release) (we test it with these). 34 35 ### Getting Gin 36 37 With [Go module](https://github.com/golang/go/wiki/Modules) support, simply add the following import 38 39 ``` 40 import "github.com/gin-gonic/gin" 41 ``` 42 43 to your code, and then `go [build|run|test]` will automatically fetch the necessary dependencies. 44 45 Otherwise, run the following Go command to install the `gin` package: 46 47 ```sh 48 $ go get -u github.com/gin-gonic/gin 49 ``` 50 51 ### Running Gin 52 53 First you need to import Gin package for using Gin, one simplest example likes the follow `example.go`: 54 55 ```go 56 package main 57 58 import ( 59 "net/http" 60 61 "github.com/gin-gonic/gin" 62 ) 63 64 func main() { 65 r := gin.Default() 66 r.GET("/ping", func(c *gin.Context) { 67 c.JSON(http.StatusOK, gin.H{ 68 "message": "pong", 69 }) 70 }) 71 r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080") 72 } 73 ``` 74 75 And use the Go command to run the demo: 76 77 ``` 78 # run example.go and visit 0.0.0.0:8080/ping on browser 79 $ go run example.go 80 ``` 81 82 ### Learn more examples 83 84 #### Quick Start 85 86 Learn and practice more examples, please read the [Gin Quick Start](docs/doc.md) which includes API examples and builds tag. 87 88 #### Examples 89 90 A number of ready-to-run examples demonstrating various use cases of Gin on the [Gin examples](https://github.com/gin-gonic/examples) repository. 91 92 93 ## Documentation 94 95 See [API documentation and descriptions](https://godoc.org/github.com/gin-gonic/gin) for package. 96 97 All documentation is available on the Gin website. 98 99 - [English](https://gin-gonic.com/docs/) 100 - [简体中文](https://gin-gonic.com/zh-cn/docs/) 101 - [繁體中文](https://gin-gonic.com/zh-tw/docs/) 102 - [日本語](https://gin-gonic.com/ja/docs/) 103 - [Español](https://gin-gonic.com/es/docs/) 104 - [한국어](https://gin-gonic.com/ko-kr/docs/) 105 - [Turkish](https://gin-gonic.com/tr/docs/) 106 - [Persian](https://gin-gonic.com/fa/docs/) 107 108 ### Articles about Gin 109 110 A curated list of awesome Gin framework. 111 112 - [Tutorial: Developing a RESTful API with Go and Gin](https://go.dev/doc/tutorial/web-service-gin) 113 114 ## Benchmarks 115 116 Gin uses a custom version of [HttpRouter](https://github.com/julienschmidt/httprouter), [see all benchmarks details](/BENCHMARKS.md). 117 118 | Benchmark name | (1) | (2) | (3) | (4) | 119 | ------------------------------ | ---------:| ---------------:| ------------:| ---------------:| 120 | BenchmarkGin_GithubAll | **43550** | **27364 ns/op** | **0 B/op** | **0 allocs/op** | 121 | BenchmarkAce_GithubAll | 40543 | 29670 ns/op | 0 B/op | 0 allocs/op | 122 | BenchmarkAero_GithubAll | 57632 | 20648 ns/op | 0 B/op | 0 allocs/op | 123 | BenchmarkBear_GithubAll | 9234 | 216179 ns/op | 86448 B/op | 943 allocs/op | 124 | BenchmarkBeego_GithubAll | 7407 | 243496 ns/op | 71456 B/op | 609 allocs/op | 125 | BenchmarkBone_GithubAll | 420 | 2922835 ns/op | 720160 B/op | 8620 allocs/op | 126 | BenchmarkChi_GithubAll | 7620 | 238331 ns/op | 87696 B/op | 609 allocs/op | 127 | BenchmarkDenco_GithubAll | 18355 | 64494 ns/op | 20224 B/op | 167 allocs/op | 128 | BenchmarkEcho_GithubAll | 31251 | 38479 ns/op | 0 B/op | 0 allocs/op | 129 | BenchmarkGocraftWeb_GithubAll | 4117 | 300062 ns/op | 131656 B/op | 1686 allocs/op | 130 | BenchmarkGoji_GithubAll | 3274 | 416158 ns/op | 56112 B/op | 334 allocs/op | 131 | BenchmarkGojiv2_GithubAll | 1402 | 870518 ns/op | 352720 B/op | 4321 allocs/op | 132 | BenchmarkGoJsonRest_GithubAll | 2976 | 401507 ns/op | 134371 B/op | 2737 allocs/op | 133 | BenchmarkGoRestful_GithubAll | 410 | 2913158 ns/op | 910144 B/op | 2938 allocs/op | 134 | BenchmarkGorillaMux_GithubAll | 346 | 3384987 ns/op | 251650 B/op | 1994 allocs/op | 135 | BenchmarkGowwwRouter_GithubAll | 10000 | 143025 ns/op | 72144 B/op | 501 allocs/op | 136 | BenchmarkHttpRouter_GithubAll | 55938 | 21360 ns/op | 0 B/op | 0 allocs/op | 137 | BenchmarkHttpTreeMux_GithubAll | 10000 | 153944 ns/op | 65856 B/op | 671 allocs/op | 138 | BenchmarkKocha_GithubAll | 10000 | 106315 ns/op | 23304 B/op | 843 allocs/op | 139 | BenchmarkLARS_GithubAll | 47779 | 25084 ns/op | 0 B/op | 0 allocs/op | 140 | BenchmarkMacaron_GithubAll | 3266 | 371907 ns/op | 149409 B/op | 1624 allocs/op | 141 | BenchmarkMartini_GithubAll | 331 | 3444706 ns/op | 226551 B/op | 2325 allocs/op | 142 | BenchmarkPat_GithubAll | 273 | 4381818 ns/op | 1483152 B/op | 26963 allocs/op | 143 | BenchmarkPossum_GithubAll | 10000 | 164367 ns/op | 84448 B/op | 609 allocs/op | 144 | BenchmarkR2router_GithubAll | 10000 | 160220 ns/op | 77328 B/op | 979 allocs/op | 145 | BenchmarkRivet_GithubAll | 14625 | 82453 ns/op | 16272 B/op | 167 allocs/op | 146 | BenchmarkTango_GithubAll | 6255 | 279611 ns/op | 63826 B/op | 1618 allocs/op | 147 | BenchmarkTigerTonic_GithubAll | 2008 | 687874 ns/op | 193856 B/op | 4474 allocs/op | 148 | BenchmarkTraffic_GithubAll | 355 | 3478508 ns/op | 820744 B/op | 14114 allocs/op | 149 | BenchmarkVulcan_GithubAll | 6885 | 193333 ns/op | 19894 B/op | 609 allocs/op | 150 151 - (1): Total Repetitions achieved in constant time, higher means more confident result 152 - (2): Single Repetition Duration (ns/op), lower is better 153 - (3): Heap Memory (B/op), lower is better 154 - (4): Average Allocations per Repetition (allocs/op), lower is better 155 156 157 ## Middlewares 158 159 You can find many useful Gin middlewares at [gin-contrib](https://github.com/gin-contrib). 160 161 162 ## Users 163 164 Awesome project lists using [Gin](https://github.com/gin-gonic/gin) web framework. 165 166 * [gorush](https://github.com/appleboy/gorush): A push notification server written in Go. 167 * [fnproject](https://github.com/fnproject/fn): The container native, cloud agnostic serverless platform. 168 * [photoprism](https://github.com/photoprism/photoprism): Personal photo management powered by Go and Google TensorFlow. 169 * [lura](https://github.com/luraproject/lura): Ultra performant API Gateway with middlewares. 170 * [picfit](https://github.com/thoas/picfit): An image resizing server written in Go. 171 * [dkron](https://github.com/distribworks/dkron): Distributed, fault tolerant job scheduling system. 172 173 174 ## Contributing 175 176 Gin is the work of hundreds of contributors. We appreciate your help! 177 178 Please see [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.