# Gin Web Framework [![Build Status](https://travis-ci.org/gin-gonic/gin.svg)](https://travis-ci.org/gin-gonic/gin) [![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) [![GoDoc](https://godoc.org/github.com/gin-gonic/gin?status.svg)](https://godoc.org/github.com/gin-gonic/gin) [![Join the chat at https://gitter.im/gin-gonic/gin](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/gin-gonic/gin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Sourcegraph](https://sourcegraph.com/github.com/gin-gonic/gin/-/badge.svg)](https://sourcegraph.com/github.com/gin-gonic/gin?badge) [![Open Source Helpers](https://www.codetriage.com/gin-gonic/gin/badges/users.svg)](https://www.codetriage.com/gin-gonic/gin) [![Release](https://img.shields.io/github/release/gin-gonic/gin.svg?style=flat-square)](https://github.com/gin-gonic/gin/releases) Gin is a web framework written in Go (Golang). It features a martini-like API with much better performance, up to 40 times faster thanks to [httprouter](https://github.com/julienschmidt/httprouter). If you need performance and good productivity, you will love Gin. **The key features of Gin are:** - Zero allocation router - Fast - Middleware support - Crash-free - JSON validation - Routes grouping - Error management - Rendering built-in - Extendable For more feature details, please see the [Gin website introduction](https://gin-gonic.com/docs/introduction/). ## Getting started ### Getting Gin The first need [Go](https://golang.org/) installed (**version 1.6+ is required**), then you can use the below Go command to install Gin. ```sh $ go get -u github.com/gin-gonic/gin ``` For more installation guides such as vendor tool, please check out [Gin quickstart](https://gin-gonic.com/docs/quickstart/). ### Running Gin First you need to import Gin package for using Gin, one simplest example likes the follow `example.go`: ```go package main import "github.com/gin-gonic/gin" func main() { r := gin.Default() r.GET("/ping", func(c *gin.Context) { c.JSON(200, gin.H{ "message": "pong", }) }) r.Run() // listen and serve on 0.0.0.0:8080 } ``` And use the Go command to run the demo: ``` # run example.go and visit 0.0.0.0:8080/ping on browser $ go run example.go ``` ## Benchmarks Please see all benchmarks details from [Gin website](https://gin-gonic.com/docs/benchmarks/). Benchmark name | (1) | (2) | (3) | (4) --------------------------------------------|-----------:|------------:|-----------:|---------: **BenchmarkGin_GithubAll** | **30000** | **48375** | **0** | **0** BenchmarkAce_GithubAll | 10000 | 134059 | 13792 | 167 BenchmarkBear_GithubAll | 5000 | 534445 | 86448 | 943 BenchmarkBeego_GithubAll | 3000 | 592444 | 74705 | 812 BenchmarkBone_GithubAll | 200 | 6957308 | 698784 | 8453 BenchmarkDenco_GithubAll | 10000 | 158819 | 20224 | 167 BenchmarkEcho_GithubAll | 10000 | 154700 | 6496 | 203 BenchmarkGocraftWeb_GithubAll | 3000 | 570806 | 131656 | 1686 BenchmarkGoji_GithubAll | 2000 | 818034 | 56112 | 334 BenchmarkGojiv2_GithubAll | 2000 | 1213973 | 274768 | 3712 BenchmarkGoJsonRest_GithubAll | 2000 | 785796 | 134371 | 2737 BenchmarkGoRestful_GithubAll | 300 | 5238188 | 689672 | 4519 BenchmarkGorillaMux_GithubAll | 100 | 10257726 | 211840 | 2272 BenchmarkHttpRouter_GithubAll | 20000 | 105414 | 13792 | 167 BenchmarkHttpTreeMux_GithubAll | 10000 | 319934 | 65856 | 671 BenchmarkKocha_GithubAll | 10000 | 209442 | 23304 | 843 BenchmarkLARS_GithubAll | 20000 | 62565 | 0 | 0 BenchmarkMacaron_GithubAll | 2000 | 1161270 | 204194 | 2000 BenchmarkMartini_GithubAll | 200 | 9991713 | 226549 | 2325 BenchmarkPat_GithubAll | 200 | 5590793 | 1499568 | 27435 BenchmarkPossum_GithubAll | 10000 | 319768 | 84448 | 609 BenchmarkR2router_GithubAll | 10000 | 305134 | 77328 | 979 BenchmarkRivet_GithubAll | 10000 | 132134 | 16272 | 167 BenchmarkTango_GithubAll | 3000 | 552754 | 63826 | 1618 BenchmarkTigerTonic_GithubAll | 1000 | 1439483 | 239104 | 5374 BenchmarkTraffic_GithubAll | 100 | 11383067 | 2659329 | 21848 BenchmarkVulcan_GithubAll | 5000 | 394253 | 19894 | 609 - (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 ## Middlewares You can find many useful Gin middlewares at [gin-contrib](https://github.com/gin-contrib). ## Documentation See [API documentation and descriptions](https://godoc.org/github.com/gin-gonic/gin) for package. All documentation is available on the Gin website. - [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/) ## Examples A number of ready-to-run examples demonstrating various use cases of Gin on the [Gin examples](https://github.com/gin-gonic/examples) repository. ## Users [Gin website](https://gin-gonic.com/docs/users/) lists some awesome projects made with Gin web framework. ## Contributing Gin is the work of hundreds of contributors. We appreciate your help! Please see [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.