8000
GitHub - dooooooooinggggg/gin: Gin is a HTTP web framework written in Go (Golang). It features a Martini-like API with much better performance -- up to 40 times faster. If you need smashing performance, get yourself some Gin. · GitHub
You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Star0 (0)You must be signed in to star a repository
About
Gin is a HTTP web framework written in Go (Golang). It features a Martini-like API with much better performance -- up to 40 times faster. If you need smashing performance, get yourself some Gin.
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. If you need performance and good productivity, you will love Gin.
Gin use encoding/json as default json package but you can change to jsoniter by build from other tags.
$ go build -tags=jsoniter .
API Examples
Using GET, POST, PUT, PATCH, DELETE and OPTIONS
funcmain() {
// Disable Console Color// gin.DisableConsoleColor()// Creates a gin router with default middleware:// logger and recovery (crash-free) middlewarerouter:=gin.Default()
router.GET("/someGet", getting)
router.POST("/somePost", posting)
router.PUT("/somePut", putting)
router.DELETE("/someDelete", deleting)
router.PATCH("/somePatch", patching)
router.HEAD("/someHead", head)
router.OPTIONS("/someOptions", options)
// By default it serves on :8080 unless a// PORT environment variable was defined.router.Run()
// router.Run(":3000") for a hard coded port
}
Parameters in path
funcmain() {
router:=gin.Default()
// This handler will match /user/john but will not match neither /user/ or /userrouter.GET("/user/:name", func(c*gin.Context) {
name:=c.Param("name")
c.String(http.StatusOK, "Hello %s", name)
})
// However, this one will match /user/john/ and also /user/john/send// If no other routers match /user/john, it will redirect to /user/john/router.GET("/user/:name/*action", func(c*gin.Context) {
name:=c.Param("name")
action:=c.Param("action")
message:=name+" is "+actionc.String(http.StatusOK, message)
})
router.Run(":8080")
}
Querystring parameters
8
<
10BC8
div class="highlight highlight-source-go notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="func main() {
router := gin.Default()
// Query string parameters are parsed using the existing underlying request object.
// The request responds to a url matching: /welcome?firstname=Jane&lastname=Doe
router.GET("/welcome", func(c *gin.Context) {
firstname := c.DefaultQuery("firstname", "Guest")
lastname := c.Query("lastname") // shortcut for c.Request.URL.Query().Get("lastname")
c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
})
router.Run(":8080")
}">
funcmain() {
router:=gin.Default()
// Query string parameters are parsed using the existing underlying request object.// The request responds to a url matching: /welcome?firstname=Jane&lastname=Doerouter.GET("/welcome", func(c*gin.Context) {
firstname:=c.DefaultQuery("firstname", "Guest")
lastname:=c.Query("lastname") // shortcut for c.Request.URL.Query().Get("lastname")c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
})
router.Run(":8080")
}
// Default With the Logger and Recovery middleware already attachedr:=gin.Default()
Using middleware
funcmain() {
// Creates a router without any middleware by defaultr:=gin.New()
// Global middleware// Logger middleware will write the logs to gin.DefaultWriter even if you set with GIN_MODE=release.// By default gin.DefaultWriter = os.Stdoutr.Use(gin.Logger())
// Recovery middleware recovers from any panics and writes a 500 if there was one.r.Use(gin.Recovery())
// Per route middleware, you can add as many as you desire.r.GET("/benchmark", MyBenchLogger(), benchEndpoint)
// Authorization group// authorized := r.Group("/", AuthRequired())// exactly the same as:authorized:=r.Group("/")
// per group middleware! in this case we use the custom created// AuthRequired() middleware just in the "authorized" group.authorized.Use(AuthRequired())
{
authorized.POST("/login", loginEndpoint)
authorized.POST("/submit", submitEndpoint)
authorized.POST("/read", readEndpoint)
// nested grouptesting:=authorized.Group("testing")
testing.GET("/analytics", analyticsEndpoint)
}
// Listen and serve on 0.0.0.0:8080r.Run(":8080")
}
How to write log file
funcmain() {
// Disable Console Color, you don't need console color when writing the logs to file.gin.DisableConsoleColor()
// Logging to a file.f, _:=os.Create("gin.log")
gin.DefaultWriter=io.MultiWriter(f)
// Use the following code if you need to write the logs to file and console at the same time.// gin.DefaultWriter = io.MultiWriter(f, os.Stdout)router:=gin.Default()
router.GET("/ping", func(c*gin.Context) {
c.String(200, "pong")
})
router.Run(":8080")
}
Model binding and validation
To bind a request body into a type, use model binding. We currently support binding of JSON, XML and standard form values (foo=bar&boo=baz).
Note that you need to set the corresponding binding tag on all fields you want to bind. For example, when binding from JSON, set json:"fieldname".
Also, Gin provides two sets of methods for binding:
Type - Must bind
Methods - Bind, BindJSON, BindQuery
Behavior - These methods use MustBindWith under the hood. If there is a binding error, the request is aborted with c.AbortWithError(400, err).SetType(ErrorTypeBind). This sets the response status code to 400 and the Content-Type header is set to text/plain; charset=utf-8. Note that if you try to set the response code after this, it will result in a warning [GIN-debug] [WARNING] Headers were already written. Wanted to override status code 400 with 422. If you wish to have greater control over the behavior, consider using the ShouldBind equivalent method.
Behavior - These methods use ShouldBindWith under the hood. If there is a binding error, the error is returned and it is the developer's responsibility to handle the request and error appropriately.
When using the Bind-method, Gin tries to infer the binder depending on the Content-Type header. If you are sure what you are binding, you can use MustBindWith or ShouldBindWith.
You can also specify that specific fields are required. If a field is decorated with binding:"required" and has a empty value when binding, an error will be returned.
// Binding from JSONtypeLoginstruct {
Userstring`form:"user" json:"user" binding:"required"`Passwordstring`form:"password" json:"password" binding:"required"`
}
funcmain() {
router:=gin.Default()
// Example for binding JSON ({"user": "manu", "password": "123"})router.POST("/loginJSON", func(c*gin.Context) {
varjsonLoginiferr:=c.ShouldBindJSON(&json); err==nil {
ifjson.User=="manu"&&json.Password=="123" {
c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
} else {
c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
}
} else {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
}
})
// Example for binding a HTML form (user=manu&password=123)router.POST("/loginForm", func(c*gin.Context) {
varformLogin// This will infer what binder to use depending on the content-type header.iferr:=c.ShouldBind(&form); err==nil {
ifform.User=="manu"&&form.Password=="123" {
c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
} else {
c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
}
} else {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
}
})
// Listen and serve on 0.0.0.0:8080router.Run(":8080")
}
Sample request
$ curl -v -X POST \
http://localhost:8080/loginJSON \
-H 'content-type: application/json' \
-d '{ "user": "manu" }'> POST /loginJSON HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.51.0
> Accept: */*> content-type: application/json
> Content-Length: 18
>* upload completely sent off: 18 out of 18 bytes
< HTTP/1.1 400 Bad Request
< Content-Type: application/json; charset=utf-8
< Date: Fri, 04 Aug 2017 03:51:31 GMT
< Content-Length: 100
<
{"error":"Key: 'Login.Password' Error:Field validation for 'Password' failed on the 'required' tag"}
Custom Validators
It is also possible to register custom validators. See the example code.
$ curl "localhost:8085/bookable?check_in=2018-04-16&check_out=2018-04-17"{"message":"Booking dates are valid!"}
$ curl "localhost:8085/bookable?check_in=2018-03-08&check_out=2018-03-09"{"error":"Key: 'Booking.CheckIn' Error:Field validation for 'CheckIn' failed on the 'bookabledate' tag"}
package main
import"log"import"github.com/gin-gonic/gin"import"time"typePersonstruct {
Namestring`form:"name"`Addressstring`form:"address"`Birthday time.Time`form:"birthday" time_format:"2006-01-02" time_utc:"1"`
}
funcmain() {
route:=gin.Default()
route.GET("/testing", startPage)
route.Run(":8085")
}
funcstartPage(c*gin.Context) {
varpersonPerson// If `GET`, only `Form` binding engine (`query`) used.// If `POST`, first checks the `content-type` for `JSON` or `XML`, then uses `Form` (`form-data`).// See more at https://github.com/gin-gonic/gin/blob/master/binding/binding.go#L48ifc.ShouldBind(&person) ==nil {
log.Println(person.Name)
log.Println(person.Address)
log.Println(person.Birthday)
}
c.String(200, "Success")
}
Test it with:
$ curl -X GET "localhost:8085/testing?name=appleboy&address=xyz&birthday=1992-03-15"
package main
import (
"github.com/gin-gonic/gin"
)
typeLoginFormstruct {
Userstring`form:"user" binding:"required"`Passwordstring`form:"password" binding:"required"`
}
funcmain() {
router:=gin.Default()
router.POST("/login", func(c*gin.Context) {
// you can bind multipart form with explicit binding declaration:// c.ShouldBindWith(&form, binding.Form)// or you can simply use autobinding with ShouldBind method:varformLoginForm// in this case proper binding will be automatically selectedifc.ShouldBind(&form) ==nil {
ifform.User=="user"&&form.Password=="password" {
c.JSON(200, gin.H{"status": "you are logged in"})
} else {
c.JSON(401, gin.H{"status": "unauthorized"})
}
}
})
router.Run(":8080")
}
funcmain() {
r:=gin.Default()
// gin.H is a shortcut for map[string]interface{}r.GET("/someJSON", func(c*gin.Context) {
c.JSON(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
})
r.GET("/moreJSON", func(c*gin.Context) {
// You also can use a structvarmsgstruct {
Namestring`json:"user"`MessagestringNumberint
}
msg.Name="Lena"msg.Message="hey"msg.Number=123// Note that msg.Name becomes "user" in the JSON// Will output : {"user": "Lena", "Message": "hey", "Number": 123}c.JSON(http.StatusOK, msg)
})
r.GET("/someXML", func(c*gin.Context) {
c.XML(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
})
r.GET("/someYAML", func(c*gin.Context) {
c.YAML(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
})
// Listen and serve on 0.0.0.0:8080r.Run(":8080")
}
SecureJSON
Using SecureJSON to prevent json hijacking. Default prepends "while(1)," to response body if the given struct is array values.
funcmain() {
r:=gin.Default()
// You can also use your own secure json prefix// r.SecureJsonPrefix(")]}',\n")r.GET("/someJSON", func(c*gin.Context) {
names:= []string{"lena", "austin", "foo"}
// Will output : while(1);["lena","austin","foo"]c.SecureJSON(http.StatusOK, names)
})
// Listen and serve on 0.0.0.0:8080r.Run(":8080")
}
JSONP
Using JSONP to request data from a server in a different domain. Add callback to response body if the query parameter callback exists.
funcmain() {
r:=gin.Default()
r.GET("/JSONP?callback=x", func(c*gin.Context) {
data:=map[string]interface{}{
"foo": "bar",
}
//callback is x// Will output : x({\"foo\":\"bar\"})c.JSONP(http.StatusOK, data)
})
// Listen and serve on 0.0.0.0:8080r.Run(":8080")
}
Serving static files
funcmain() {
router:=gin.Default()
router.Static("/assets", "./assets")
router.StaticFS("/more_static", http.Dir("my_file_system"))
router.StaticFile("/favicon.ico", "./resources/favicon.ico")
// Listen and serve on 0.0.0.0:8080router.Run(":8080")
}
Both internal and external locations are supported.
Custom Middleware
funcLogger() gin.HandlerFunc {
returnfunc(c*gin.Context) {
t:=time.Now()
// Set example variablec.Set("example", "12345")
// before requestc.Next()
// after requestlatency:=time.Since(t)
log.Print(latency)
// access the status we are sendingstatus:=c.Writer.Status()
log.Println(status)
}
}
funcmain() {
r:=gin.New()
r.Use(Logger())
r.GET("/test", func(c*gin.Context) {
example:=c.MustGet("example").(string)
// it would print: "12345"log.Println(example)
})
// Listen and serve on 0.0.0.0:8080r.Run(":8080")
}
Using BasicAuth() middleware
// simulate some private datavarsecrets= gin.H{
"foo": gin.H{"email": "foo@bar.com", "phone": "123433"},
"austin": gin.H{"email": "austin@example.com", "phone": "666"},
"lena": gin.H{"email": "lena@guapa.com", "phone": "523443"},
}
funcmain() {
r:=gin.Default()
// Group using gin.BasicAuth() middleware// gin.Accounts is a shortcut for map[string]stringauthorized:=r.Group("/admin", gin.BasicAuth(gin.Accounts{
"foo": "bar",
"austin": "1234",
"lena": "hello2",
"manu": "4321",
}))
// /admin/secrets endpoint// hit "localhost:8080/admin/secretsauthorized.GET("/secrets", func(c*gin.Context) {
// get user, it was set by the BasicAuth middlewareuser:=c.MustGet(gin.AuthUserKey).(string)
ifsecret, ok:=secrets[user]; ok {
c.JSON(http.StatusOK, gin.H{"user": user, "secret": secret})
} else {
c.JSON(http.StatusOK, gin.H{"user": user, "secret": "NO SECRET :("})
}
})
// Listen and serve on 0.0.0.0:8080r.Run(":8080")
}
Goroutines inside a middleware
When starting new Goroutines inside a middleware or handler, you SHOULD NOT use the original context inside it, you have to use a read-only copy.
funcmain() {
r:=gin.Default()
r.GET("/long_async", func(c*gin.Context) {
// create copy to be used inside the goroutinecCp:=c.Copy()
gofunc() {
// simulate a long task with time.Sleep(). 5 secondstime.Sleep(5*time.Second)
// note that you are using the copied context "cCp", IMPORTANTlog.Println("Done! in path "+cCp.Request.URL.Path)
}()
})
r.GET("/long_sync", func(c*gin.Context) {
// simulate a long task with time.Sleep(). 5 secondstime.Sleep(5*time.Second)
// since we are NOT using a goroutine, we do not have to copy the contextlog.Println("Done! in path "+c.Request.URL.Path)
})
// Listen and serve on 0.0.0.0:8080r.Run(":8080")
}
manners: A polite Go HTTP server that shuts down gracefully.
graceful: Graceful is a Go package enabling graceful shutdown of an http.Handler server.
grace: Graceful restart & zero downtime deploy for Go servers.
If you are using Go 1.8, you may not need to use this library! Consider using http.Server's built-in Shutdown() method for graceful shutdowns. See the full graceful-shutdown example with gin.
// +build go1.8package main
import (
"context""log""net/http""os""os/signal""time""github.com/gin-gonic/gin"
)
funcmain() {
router:=gin.Default()
router.GET("/", func(c*gin.Context) {
time.Sleep(5*time.Second)
c.String(http.StatusOK, "Welcome Gin Server")
})
srv:=&http.Server{
Addr: ":8080",
Handler: router,
}
gofunc() {
// service connectionsiferr:=srv.ListenAndServe(); err!=nil&&err!=http.ErrServerClosed {
log.Fatalf("listen: %s\n", err)
}
}()
// Wait for interrupt signal to gracefully shutdown the server with// a timeout of 5 seconds.quit:=make(chan os.Signal)
signal.Notify(quit, os.Interrupt)
<-quitlog.Println("Shutdown Server ...")
ctx, cancel:=context.WithTimeout(context.Background(), 5*time.Second)
defercancel()
iferr:=srv.Shutdown(ctx); err!=nil {
log.Fatal("Server Shutdown:", err)
}
log.Println("Server exiting")
}
Build a single binary with templates
You can build a server into a single binary containing templates by using go-assets.
typeStructXstruct {
Xstruct {} `form:"name_x"`// HERE have form
}
typeStructYstruct {
YStructX`form:"name_y"`// HERE hava form
}
typeStructZstruct {
Z*StructZ`form:"name_z"`// HERE hava form
}
In a word, only support nested custom struct which have no form now.
Testing
The net/http/httptest package is preferable way for HTTP testing.
Gin is a HTTP web framework written in Go (Golang). It features a Martini-like API with much better performance -- up to 40 times faster. If you need smashing performance, get yourself some Gin.
