mirror
/
gin
mirror of https://github.com/gin-gonic/gin.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

Updates README

This commit is contained in:
Manu Mtz-Almeida 2015-05-31 05:00:47 +02:00
parent dcb5553a9b
commit 43bcac2031
1 changed files with 115 additions and 203 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

310
README.md
View File

@ -1,4 +1,4 @@
#Gin Web Framework [![Build Status](https://travis-ci.org/gin-gonic/gin.svg)](https://travis-ci.org/gin-gonic/gin) [![Coverage Status](https://coveralls.io/repos/gin-gonic/gin/badge.svg?branch=develop)](https://coveralls.io/r/gin-gonic/gin?branch=develop) #Gin Web Framework [![Build Status](https://travis-ci.org/gin-gonic/gin.svg)](https://travis-ci.org/gin-gonic/gin) [![Coverage Status](https://coveralls.io/repos/gin-gonic/gin/badge.svg?branch=master)](https://coveralls.io/r/gin-gonic/gin?branch=master)
[![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) [![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)
@ -12,105 +12,57 @@ $ cat test.go
```go ```go
package main package main
import ( import "github.com/gin-gonic/gin"
"net/http"
"github.com/gin-gonic/gin"
)
func main() { func main() {
router := gin.Default() r := gin.Default()
router.GET("/", func(c *gin.Context) { r.GET("/ping", func(c *gin.Context) {
c.String(http.StatusOK, "hello world") c.String(200, "pong")
}) })
router.GET("/ping", func(c *gin.Context) { r.Run(":8080") // listen and serve on 0.0.0.0:8080
c.String(http.StatusOK, "pong")
})
router.POST("/submit", func(c *gin.Context) {
c.String(http.StatusUnauthorized, "not authorized")
})
router.PUT("/error", func(c *gin.Context) {
c.String(http.StatusInternalServerError, "an error happened :(")
})
router.Run(":8080")
} }
``` ```
##Gin is new, will it be supported? ##Gin v1. released
- [x] Zero allocation router.
Yes, Gin is an internal tool of [Manu](https://github.com/manucorporat) and [Javi](https://github.com/javierprovecho) for many of our projects/start-ups. We developed it and we are going to continue using and improve it. - [x] Still the fastest http router and framework. From routing to writing.
- [x] Complete suite of unit tests
- [x] Battle tested
##Roadmap for v1.0 - [x] API frozen, new releases will not break your code.
- [ ] Ask our designer for a cool logo
- [ ] Add tons of unit tests
- [ ] Add internal benchmarks suite
- [ ] More powerful validation API
- [ ] Improve documentation
- [ ] Add Swagger support
- [x] Stable API
- [x] Improve logging system
- [x] Improve JSON/XML validation using bindings
- [x] Improve XML support
- [x] Flexible rendering system
- [x] Add more cool middlewares, for example redis caching (this also helps developers to understand the framework).
- [x] Continuous integration
- [x] Performance improments, reduce allocation and garbage collection overhead
- [x] Fix bugs
## Start using it ## Start using it
Obviously, you need to have Git and Go already installed to run Gin. 1. Download and install it:
Run this in your terminal
``` ```sh
go get github.com/gin-gonic/gin go get github.com/gin-gonic/gin
``` ```
Then import it in your Go code: 2. Import it in your code:
``` ```go
import "github.com/gin-gonic/gin" import "github.com/gin-gonic/gin"
``` ```
##API Examples ##API Examples
#### Create most basic PING/PONG HTTP endpoint
```go
package main
import (
"net/http"
"github.com/gin-gonic/gin"
)
func main() {
r := gin.Default()
r.GET("/ping", func(c *gin.Context) {
c.String(http.StatusOK, "pong")
})
// Listen and serve on 0.0.0.0:8080
r.Run(":8080")
}
```
#### Using GET, POST, PUT, PATCH, DELETE and OPTIONS #### Using GET, POST, PUT, PATCH, DELETE and OPTIONS
```go ```go
func main() { func main() {
// Creates a gin router + logger and recovery (crash-free) middlewares // Creates a gin router with default middlewares:
r := gin.Default() // logger and recovery (crash-free) middlewares
router := gin.Default()
r.GET("/someGet", getting) router.GET("/someGet", getting)
r.POST("/somePost", posting) router.POST("/somePost", posting)
r.PUT("/somePut", putting) router.PUT("/somePut", putting)
r.DELETE("/someDelete", deleting) router.DELETE("/someDelete", deleting)
r.PATCH("/somePatch", patching) router.PATCH("/somePatch", patching)
r.HEAD("/someHead", head) router.HEAD("/someHead", head)
r.OPTIONS("/someOptions", options) router.OPTIONS("/someOptions", options)
// Listen and server on 0.0.0.0:8080 // Listen and server on 0.0.0.0:8080
r.Run(":8080") router.Run(":8080")
} }
``` ```
@ -118,26 +70,24 @@ func main() {
```go ```go
func main() { func main() {
r := gin.Default() router := gin.Default()
// This handler will match /user/john but will not match neither /user/ or /user // This handler will match /user/john but will not match neither /user/ or /user
r.GET("/user/:name", func(c *gin.Context) { router.GET("/user/:name", func(c *gin.Context) {
name := c.Params.ByName("name") name := c.Param("name")
message := "Hello "+name c.String(http.StatusOK, "Hello %s", name)
c.String(http.StatusOK, message)
}) })
// However, this one will match /user/john/ and also /user/john/send // However, this one will match /user/john/ and also /user/john/send
// If no other routers match /user/john, it will redirect to /user/join/ // If no other routers match /user/john, it will redirect to /user/join/
r.GET("/user/:name/*action", func(c *gin.Context) { router.GET("/user/:name/*action", func(c *gin.Context) {
name := c.Params.ByName("name") name := c.Param("name")
action := c.Params.ByName("action") action := c.Param("action")
message := name + " is " + action message := name + " is " + action
c.String(http.StatusOK, message) c.String(http.StatusOK, message)
}) })
// Listen and server on 0.0.0.0:8080 router.Run(":8080")
r.Run(":8080")
} }
``` ```
@ -158,78 +108,32 @@ func main() {
} }
``` ```
###Form parameters ### Multipart/Urlencoded Form
```go ```go
func main() { func main() {
r := gin.Default() router := gin.Default()
// This will respond to urls like search?firstname=Jane&lastname=Doe router.POST("/form_post", func(c *gin.Context) {
r.GET("/search", func(c *gin.Context) { message := c.PostForm("message")
// You need to call ParseForm() on the request to receive url and form params first nick := c.DefaultPostForm("nick", "anonymous")
c.Request.ParseForm()
firstname := c.Request.Form.Get("firstname") c.JSON(200, gin.H{
lastname := c.Request.Form.Get("lastname") "status": "posted",
"message": message,
message := "Hello "+ firstname + lastname
c.String(http.StatusOK, message)
}) })
r.Run(":8080")
}
```
###Multipart Form
```go
package main
import (
"github.com/gin-gonic/gin"
"github.com/gin-gonic/gin/binding"
)
type LoginForm struct {
User string `form:"user" binding:"required"`
Password string `form:"password" binding:"required"`
}
func main() {
r := gin.Default()
r.POST("/login", func(c *gin.Context) {
var form LoginForm
// you can bind multipart form with explicit binding declaration:
// c.BindWith(&form, binding.Form)
// or you can simply use autobinding with Bind method:
c.Bind(&form) // in this case proper binding will be automatically selected
if form.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")
r.Run(":8080")
} }
``` ```
Test it with:
```bash
$ curl -v --form user=user --form password=password http://localhost:8080/login
```
#### Grouping routes #### Grouping routes
```go ```go
func main() { func main() {
r := gin.Default() router := gin.Default()
// Simple group: v1 // Simple group: v1
v1 := r.Group("/v1") v1 := router.Group("/v1")
{ {
v1.POST("/login", loginEndpoint) v1.POST("/login", loginEndpoint)
v1.POST("/submit", submitEndpoint) v1.POST("/submit", submitEndpoint)
@ -237,15 +141,14 @@ func main() {
} }
// Simple group: v2 // Simple group: v2
v2 := r.Group("/v2") v2 := router.Group("/v2")
{ {
v2.POST("/login", loginEndpoint) v2.POST("/login", loginEndpoint)
v2.POST("/submit", submitEndpoint) v2.POST("/submit", submitEndpoint)
v2.POST("/read", readEndpoint) v2.POST("/read", readEndpoint)
} }
// Listen and server on 0.0.0.0:8080 router.Run(":8080")
r.Run(":8080")
} }
``` ```
@ -354,6 +257,50 @@ func main() {
} }
``` ```
###Multipart/Urlencoded binding
```go
package main
import (
"github.com/gin-gonic/gin"
"github.com/gin-gonic/gin/binding"
)
type LoginForm struct {
User string `form:"user" binding:"required"`
Password string `form:"password" binding:"required"`
}
func main() {
router := gin.Default()
router.POST("/login", func(c *gin.Context) {
// you can bind multipart form with explicit binding declaration:
// c.BindWith(&form, binding.Form)
// or you can simply use autobinding with Bind method:
var form LoginForm
c.Bind(&form) // in this case proper binding will be automatically selected
if form.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")
}
```
Test it with:
```bash
$ curl -v --form user=user --form password=password http://localhost:8080/login
```
#### XML and JSON rendering #### XML and JSON rendering
```go ```go
@ -390,48 +337,41 @@ func main() {
``` ```
####Serving static files ####Serving static files
Use Engine.ServeFiles(path string, root http.FileSystem):
```go ```go
func main() { func main() {
r := gin.Default() router := gin.Default()
r.Static("/assets", "./assets") router.Static("/assets", "./assets")
router.StaticFS("/more_static", http.Dir("my_file_system"))
router.StaticFile("/favicon.ico", "./resources/favicon.ico")
// Listen and server on 0.0.0.0:8080 // Listen and server on 0.0.0.0:8080
r.Run(":8080") router.Run(":8080")
} }
``` ```
Use the following example to serve static files at top level route of your domain. Files are being served from directory ./html.
```
r := gin.Default()
r.Use(static.Serve("/", static.LocalFile("html", false)))
```
Note: this will use `httpNotFound` instead of the Router's `NotFound` handler.
####HTML rendering ####HTML rendering
Using LoadHTMLTemplates() Using LoadHTMLTemplates()
```go ```go
func main() { func main() {
r := gin.Default() router := gin.Default()
r.LoadHTMLGlob("templates/*") router.LoadHTMLGlob("templates/*")
r.GET("/index", func(c *gin.Context) { //router.LoadHTMLFiles("templates/template1.html", "templates/template2.html")
obj := gin.H{"title": "Main website"} router.GET("/index", func(c *gin.Context) {
c.HTML(http.StatusOK, "index.tmpl", obj) c.HTML(http.StatusOK, "index.tmpl", gin.H{
"title": "Main website",
}) })
})
// Listen and server on 0.0.0.0:8080 router.Run(":8080")
r.Run(":8080")
} }
``` ```
```html ```html
<h1> <html><h1>
{{ .title }} {{ .title }}
</h1> </h1>
</html>
``` ```
You can also use your own html template render You can also use your own html template render
@ -440,41 +380,13 @@ You can also use your own html template render
import "html/template" import "html/template"
func main() { func main() {
r := gin.Default() router := gin.Default()
html := template.Must(template.ParseFiles("file1", "file2")) html := template.Must(template.ParseFiles("file1", "file2"))
r.SetHTMLTemplate(html) router.SetHTMLTemplate(html)
router.Run(":8080")
// Listen and server on 0.0.0.0:8080
r.Run(":8080")
} }
``` ```
#####Using layout files with templates
```go
var baseTemplate = "main.tmpl"
r.GET("/", func(c *gin.Context) {
r.SetHTMLTemplate(template.Must(template.ParseFiles(baseTemplate, "whatever.tmpl")))
c.HTML(200, "base", data)
})
```
main.tmpl
```html
{{define "base"}}
<html>
<head></head>
<body>
{{template "content" .}}
</body>
</html>
{{end}}
```
whatever.tmpl
```html
{{define "content"}}
<h1>Hello World!</h1>
{{end}}
```
#### Redirects #### Redirects