mirror of
https://github.com/gin-gonic/gin.git
synced 2025-10-16 05:16:35 +08:00
update doc
This commit is contained in:
thinkerou
parent
244e3002e4
commit
019177d335
@ -1,193 +1,66 @@
|
||||
# Gin Web Framework
|
||||
|
||||
<img align="right" width="159px" src="https://raw.githubusercontent.com/gin-gonic/logo/master/color.png">
|
||||
|
||||
[](https://github.com/gin-gonic/gin/actions?query=branch%3Amaster)
|
||||
[](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://gitter.im/gin-gonic/gin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
[](https://sourcegraph.com/github.com/gin-gonic/gin?badge)
|
||||
[](https://www.codetriage.com/gin-gonic/gin)
|
||||
[](https://github.com/gin-gonic/gin/releases)
|
||||
[](https://www.tickgit.com/browse?repo=github.com/gin-gonic/gin)
|
||||
|
||||
Gin is a web framework written in Go (Golang). 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.
|
||||
# Gin Quick Start
|
||||
|
||||
## Contents
|
||||
|
||||
- [Gin Web Framework](#gin-web-framework)
|
||||
- [Contents](#contents)
|
||||
- [Installation](#installation)
|
||||
- [Quick start](#quick-start)
|
||||
- [Benchmarks](#benchmarks)
|
||||
- [Gin v1. stable](#gin-v1-stable)
|
||||
- [Build with json replacement](#build-with-json-replacement)
|
||||
- [Build without `MsgPack` rendering feature](#build-without-msgpack-rendering-feature)
|
||||
- [API Examples](#api-examples)
|
||||
- [Using GET, POST, PUT, PATCH, DELETE and OPTIONS](#using-get-post-put-patch-delete-and-options)
|
||||
- [Parameters in path](#parameters-in-path)
|
||||
- [Querystring parameters](#querystring-parameters)
|
||||
- [Multipart/Urlencoded Form](#multiparturlencoded-form)
|
||||
- [Another example: query + post form](#another-example-query--post-form)
|
||||
- [Map as querystring or postform parameters](#map-as-querystring-or-postform-parameters)
|
||||
- [Upload files](#upload-files)
|
||||
- [Single file](#single-file)
|
||||
- [Multiple files](#multiple-files)
|
||||
- [Grouping routes](#grouping-routes)
|
||||
- [Blank Gin without middleware by default](#blank-gin-without-middleware-by-default)
|
||||
- [Using middleware](#using-middleware)
|
||||
- [Custom Recovery behavior](#custom-recovery-behavior)
|
||||
- [How to write log file](#how-to-write-log-file)
|
||||
- [Custom Log Format](#custom-log-format)
|
||||
- [Controlling Log output coloring](#controlling-log-output-coloring)
|
||||
- [Model binding and validation](#model-binding-and-validation)
|
||||
- [Custom Validators](#custom-validators)
|
||||
- [Only Bind Query String](#only-bind-query-string)
|
||||
- [Bind Query String or Post Data](#bind-query-string-or-post-data)
|
||||
- [Bind Uri](#bind-uri)
|
||||
- [Bind Header](#bind-header)
|
||||
- [Bind HTML checkboxes](#bind-html-checkboxes)
|
||||
- [Multipart/Urlencoded binding](#multiparturlencoded-binding)
|
||||
- [XML, JSON, YAML, TOML and ProtoBuf rendering](#xml-json-yaml-toml-and-protobuf-rendering)
|
||||
- [SecureJSON](#securejson)
|
||||
- [JSONP](#jsonp)
|
||||
- [AsciiJSON](#asciijson)
|
||||
- [PureJSON](#purejson)
|
||||
- [Serving static files](#serving-static-files)
|
||||
- [Serving data from file](#serving-data-from-file)
|
||||
- [Serving data from reader](#serving-data-from-reader)
|
||||
- [HTML rendering](#html-rendering)
|
||||
- [Custom Template renderer](#custom-template-renderer)
|
||||
- [Custom Delimiters](#custom-delimiters)
|
||||
- [Custom Template Funcs](#custom-template-funcs)
|
||||
- [Multitemplate](#multitemplate)
|
||||
- [Redirects](#redirects)
|
||||
- [Custom Middleware](#custom-middleware)
|
||||
- [Using BasicAuth() middleware](#using-basicauth-middleware)
|
||||
- [Goroutines inside a middleware](#goroutines-inside-a-middleware)
|
||||
- [Custom HTTP configuration](#custom-http-configuration)
|
||||
- [Support Let's Encrypt](#support-lets-encrypt)
|
||||
- [Run multiple service using Gin](#run-multiple-service-using-gin)
|
||||
- [Graceful shutdown or restart](#graceful-shutdown-or-restart)
|
||||
- [Third-party packages](#third-party-packages)
|
||||
- [Manually](#manually)
|
||||
- [Build a single binary with templates](#build-a-single-binary-with-templates)
|
||||
- [Bind form-data request with custom struct](#bind-form-data-request-with-custom-struct)
|
||||
- [Try to bind body into different structs](#try-to-bind-body-into-different-structs)
|
||||
- [Bind form-data request with custom struct and custom tag](#bind-form-data-request-with-custom-struct-and-custom-tag)
|
||||
- [http2 server push](#http2-server-push)
|
||||
- [Define format for the log of routes](#define-format-for-the-log-of-routes)
|
||||
- [Set and get a cookie](#set-and-get-a-cookie)
|
||||
- [Don't trust all proxies](#dont-trust-all-proxies)
|
||||
- [Testing](#testing)
|
||||
- [Users](#users)
|
||||
|
||||
## Installation
|
||||
|
||||
To install Gin package, you need to install Go and set your Go workspace first.
|
||||
|
||||
1. You first need [Go](https://go.dev/) installed (**version 1.16+ is required**), then you can use the below Go command to install Gin.
|
||||
|
||||
```sh
|
||||
go get -u github.com/gin-gonic/gin
|
||||
```
|
||||
|
||||
2. Import it in your code:
|
||||
|
||||
```go
|
||||
import "github.com/gin-gonic/gin"
|
||||
```
|
||||
|
||||
3. (Optional) Import `net/http`. This is required for example if using constants such as `http.StatusOK`.
|
||||
|
||||
```go
|
||||
import "net/http"
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```sh
|
||||
# assume the following codes in example.go file
|
||||
$ cat example.go
|
||||
```
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
func main() {
|
||||
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")
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
# run example.go and visit 0.0.0.0:8080/ping (for windows "localhost:8080/ping") on browser
|
||||
$ go run example.go
|
||||
```
|
||||
|
||||
## Benchmarks
|
||||
|
||||
Gin uses a custom version of [HttpRouter](https://github.com/julienschmidt/httprouter)
|
||||
|
||||
[See all benchmarks](/BENCHMARKS.md)
|
||||
|
||||
| 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): 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
|
||||
|
||||
## Gin v1. stable
|
||||
|
||||
- [x] Zero allocation router.
|
||||
- [x] Still the fastest http router and framework. From routing to writing.
|
||||
- [x] Complete suite of unit tests.
|
||||
- [x] Battle tested.
|
||||
- [x] API frozen, new releases will not break your code.
|
||||
- [Build with json replacement](#build-with-json-replacement)
|
||||
- [Build without `MsgPack` rendering feature](#build-without-msgpack-rendering-feature)
|
||||
- [API Examples](#api-examples)
|
||||
- [Using GET, POST, PUT, PATCH, DELETE and OPTIONS](#using-get-post-put-patch-delete-and-options)
|
||||
- [Parameters in path](#parameters-in-path)
|
||||
- [Querystring parameters](#querystring-parameters)
|
||||
- [Multipart/Urlencoded Form](#multiparturlencoded-form)
|
||||
- [Another example: query + post form](#another-example-query--post-form)
|
||||
- [Map as querystring or postform parameters](#map-as-querystring-or-postform-parameters)
|
||||
- [Upload files](#upload-files)
|
||||
- [Single file](#single-file)
|
||||
- [Multiple files](#multiple-files)
|
||||
- [Grouping routes](#grouping-routes)
|
||||
- [Blank Gin without middleware by default](#blank-gin-without-middleware-by-default)
|
||||
- [Using middleware](#using-middleware)
|
||||
- [Custom Recovery behavior](#custom-recovery-behavior)
|
||||
- [How to write log file](#how-to-write-log-file)
|
||||
- [Custom Log Format](#custom-log-format)
|
||||
- [Controlling Log output coloring](#controlling-log-output-coloring)
|
||||
- [Model binding and validation](#model-binding-and-validation)
|
||||
- [Custom Validators](#custom-validators)
|
||||
- [Only Bind Query String](#only-bind-query-string)
|
||||
- [Bind Query String or Post Data](#bind-query-string-or-post-data)
|
||||
- [Bind Uri](#bind-uri)
|
||||
- [Bind Header](#bind-header)
|
||||
- [Bind HTML checkboxes](#bind-html-checkboxes)
|
||||
- [Multipart/Urlencoded binding](#multiparturlencoded-binding)
|
||||
- [XML, JSON, YAML, TOML and ProtoBuf rendering](#xml-json-yaml-toml-and-protobuf-rendering)
|
||||
- [SecureJSON](#securejson)
|
||||
- [JSONP](#jsonp)
|
||||
- [AsciiJSON](#asciijson)
|
||||
- [PureJSON](#purejson)
|
||||
- [Serving static files](#serving-static-files)
|
||||
- [Serving data from file](#serving-data-from-file)
|
||||
- [Serving data from reader](#serving-data-from-reader)
|
||||
- [HTML rendering](#html-rendering)
|
||||
- [Custom Template renderer](#custom-template-renderer)
|
||||
- [Custom Delimiters](#custom-delimiters)
|
||||
- [Custom Template Funcs](#custom-template-funcs)
|
||||
- [Multitemplate](#multitemplate)
|
||||
- [Redirects](#redirects)
|
||||
- [Custom Middleware](#custom-middleware)
|
||||
- [Using BasicAuth() middleware](#using-basicauth-middleware)
|
||||
- [Goroutines inside a middleware](#goroutines-inside-a-middleware)
|
||||
- [Custom HTTP configuration](#custom-http-configuration)
|
||||
- [Support Let's Encrypt](#support-lets-encrypt)
|
||||
- [Run multiple service using Gin](#run-multiple-service-using-gin)
|
||||
- [Graceful shutdown or restart](#graceful-shutdown-or-restart)
|
||||
- [Third-party packages](#third-party-packages)
|
||||
- [Manually](#manually)
|
||||
- [Build a single binary with templates](#build-a-single-binary-with-templates)
|
||||
- [Bind form-data request with custom struct](#bind-form-data-request-with-custom-struct)
|
||||
- [Try to bind body into different structs](#try-to-bind-body-into-different-structs)
|
||||
- [Bind form-data request with custom struct and custom tag](#bind-form-data-request-with-custom-struct-and-custom-tag)
|
||||
- [http2 server push](#http2-server-push)
|
||||
- [Define format for the log of routes](#define-format-for-the-log-of-routes)
|
||||
- [Set and get a cookie](#set-and-get-a-cookie)
|
||||
- [Don't trust all proxies](#dont-trust-all-proxies)
|
||||
- [Testing](#testing)
|
||||
|
||||
## Build with json replacement
|
||||
|
||||
@ -2368,15 +2241,3 @@ func TestPingRoute(t *testing.T) {
|
||||
assert.Equal(t, "pong", w.Body.String())
|
||||
}
|
||||
```
|
||||
|
||||
## Users
|
||||
|
||||
Awesome project lists using [Gin](https://github.com/gin-gonic/gin) web framework.
|
||||
|
||||
* [gorush](https://github.com/appleboy/gorush): A push notification server written in Go.
|
||||
* [fnproject](https://github.com/fnproject/fn): The container native, cloud agnostic serverless platform.
|
||||
* [photoprism](https://github.com/photoprism/photoprism): Personal photo management powered by Go and Google TensorFlow.
|
||||
* [lura](https://github.com/luraproject/lura): Ultra performant API Gateway with middlewares.
|
||||
* [picfit](https://github.com/thoas/picfit): An image resizing server written in Go.
|
||||
* [brigade](https://github.com/brigadecore/brigade): Event-based Scripting for Kubernetes.
|
||||
* [dkron](https://github.com/distribworks/dkron): Distributed, fault tolerant job scheduling system.
|
||||
Loading…
x
Reference in New Issue
Block a user