gin

package module
v0.0.0-...-592af30 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 4, 2014 License: MIT Imports: 19 Imported by: 0

README

#Gin Web Framework

GoDoc Build Status

Gin is a web framework written in Golang. It features a martini-like API with much better performance, up to 40 times faster. If you need performance and good productivity, you will love Gin.
Check out the official web site

##Gin is new, will it be supported?

Yes, Gin is an internal project of my upcoming startup. We developed it and we are going to continue using and improve it.

##Roadmap

  • Performance improments, reduce allocation and garbage collection overhead
  • Fix bugs
  • Ask our designer for a cool logo
  • Add tons of unit tests and benchmarks
  • Improve logging system
  • Improve JSON/XML validation using bindings
  • Improve XML support
  • Improve documentation
  • Add more cool middlewares, for example redis catching (this also helps developers to understand the framework)
  • Continuous integration

Start using it

Run:

go get github.com/gin-gonic/gin

Then import it in your Golang code:

import "github.com/gin-gonic/gin"

##API Examples

Create most basic PING/PONG HTTP endpoint
package main

import "github.com/gin-gonic/gin"

func main() {
	r := gin.Default()
	r.GET("/ping", func(c *gin.Context) {
		c.String(200, "pong")
	})

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}
Using GET, POST, PUT, PATCH and DELETE
func main() {
	// Creates a gin router + logger and recovery (crash-free) middlewares
	r := gin.Default()

	r.GET("/someGet", getting)
	r.POST("/somePost", posting)
	r.PUT("/somePut", putting)
	r.DELETE("/someDelete", deleting)
	r.PATCH("/somePatch", patching)

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}
Parameters in path
func main() {
	r := gin.Default()

	r.GET("/user/:name", func(c *gin.Context) {
		name := c.Params.ByName("name")
		message := "Hello " + name
		c.String(200, message)
	})

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}
Grouping routes
func main() {
	r := gin.Default()

	// Simple group: v1
	v1 := r.Group("/v1")
	{
		v1.POST("/login", loginEndpoint)
		v1.POST("/submit", submitEndpoint)
		v1.POST("/read", readEndpoint)
	}

	// Simple group: v2
	v2 := r.Group("/v2")
	{
		v2.POST("/login", loginEndpoint)
		v2.POST("/submit", submitEndpoint)
		v2.POST("/read", readEndpoint)
	}

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}
Blank Gin without middlewares by default

Use

r := gin.New()

instead of

r := gin.Default()
Using middlewares
func main() {
	// Creates a router without any middleware by default
	r := gin.New()

	// Global middlewares
	r.Use(gin.Logger())
	r.Use(gin.Recovery())

	// Per route middlewares, you can add as many as you desire.
	r.GET("/benchmark", MyBenchLogger(), benchEndpoint)

	// Authorization group
	// authorized := r.Group("/", AuthRequired())
	// exactly the same than:
	authorized := r.Group("/")
	// per group middlewares! 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 group
		testing := authorized.Group("testing")
		testing.GET("/analytics", analyticsEndpoint)
	}

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}
JSON parsing and validation
type LoginJSON struct {
	User     string `json:"user" binding:"required"`
	Password string `json:"password" binding:"required"`
}

func main() {
	r := gin.Default()

	r.POST("/login", func(c *gin.Context) {
		var json LoginJSON

		// If EnsureBody returns false, it will write automatically the error
		// in the HTTP stream and return a 400 error. If you want custom error
		// handling you should use: c.ParseBody(interface{}) error
		if c.EnsureBody(&json) {
			if json.User == "manu" && json.Password == "123" {
				c.JSON(200, gin.H{"status": "you are logged in"})
			} else {
				c.JSON(401, gin.H{"status": "unauthorized"})
			}
		}
	})

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}
XML, and JSON rendering
func main() {
	r := gin.Default()

	// gin.H is a shortcup for map[string]interface{}
	r.GET("/someJSON", func(c *gin.Context) {
		c.JSON(200, gin.H{"message": "hey", "status": 200})
	})

	r.GET("/moreJSON", func(c *gin.Context) {
		// You also can use a struct
		var msg struct {
			Name    string `json:"user"`
			Message string
			Number  int
		}
		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(200, msg)
	})

	r.GET("/someXML", func(c *gin.Context) {
		c.XML(200, gin.H{"message": "hey", "status": 200})
	})

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}

####HTML rendering

Using LoadHTMLTemplates()

func main() {
	r := gin.Default()
	r.LoadHTMLTemplates("templates/*")
	r.GET("/index", func(c *gin.Context) {
		obj := gin.H{"title": "Main website"}
		c.HTML(200, "index.tmpl", obj)
	})

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}

You can also use your own html template render

import "html/template"

func main() {
	r := gin.Default()
	html := template.Must(template.ParseFiles("file1", "file2"))
	r.HTMLTemplates = html

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}
Custom Middlewares
func Logger() gin.HandlerFunc {
	return func(c *gin.Context) {
		t := time.Now()

		// Set example variable
		c.Set("example", "12345")

		// before request

		c.Next()

		// after request
		latency := time.Since(t)
		log.Print(latency)
	}
}

func main() {
	r := gin.New()
	r.Use(Logger())

	r.GET("/test", func(c *gin.Context) {
		example := r.Get("example").(string)

		// it would print: "12345"
		log.Println(example)
	})

	// Listen and server on 0.0.0.0:8080
	r.Run(":8080")
}
Custom HTTP configuration

Use http.ListenAndServe() directly, like this:

func main() {
	router := gin.Default()
	http.ListenAndServe(":8080", router)
}

or

func main() {
	router := gin.Default()

	s := &http.Server{
		Addr:           ":8080",
		Handler:        router,
		ReadTimeout:    10 * time.Second,
		WriteTimeout:   10 * time.Second,
		MaxHeaderBytes: 1 << 20,
	}
	s.ListenAndServe()
}

Documentation

Index

Constants

View Source 
const (
	AbortIndex = math.MaxInt8 / 2
)
View Source 
const (
	AuthUserKey = "user"
)

Variables

This section is empty.

Functions

func Validate 

func Validate(c *Context, obj interface{}) error

Types

type Account 

type Account struct {
	User     string
	Password string
}

type Accounts 

type Accounts []Account

type BasicAuthPair 

type BasicAuthPair struct {
	Code string
	User string
}

type Context 

type Context struct {
	Req    *http.Request
	Writer http.ResponseWriter
	Keys   map[string]interface{}
	Errors ErrorMsgs
	Params httprouter.Params
	// contains filtered or unexported fields
}

Context is the most important part of gin. It allows us to pass variables between middleware, manage the flow, validate the JSON of a request and render a JSON response for example.

func (*Context) Abort 

func (c *Context) Abort(code int)

Forces the system to do not continue calling the pending handlers. For example, the first handler checks if the request is authorized. If it's not, context.Abort(401) should be called. The rest of pending handlers would never be called for that request.

func (*Context) Data 

func (c *Context) Data(code int, data []byte)

Writes some data into the body stream and updates the HTTP code.

func (*Context) EnsureBody 

func (c *Context) EnsureBody(item interface{}) bool

Like ParseBody() but this method also writes a 400 error if the json is not valid.

func (*Context) Error 

func (c *Context) Error(err error, meta interface{})

Attaches an error to the current context. The error is pushed to a list of errors. It's a good idea to call Error for each error that occurred during the resolution of a request. A middleware can be used to collect all the errors and push them to a database together, print a log, or append it in the HTTP response.

func (*Context) Fail 

func (c *Context) Fail(code int, err error)

Fail is the same as Abort plus an error message. Calling `context.Fail(500, err)` is equivalent to: ``` context.Error("Operation aborted", err) context.Abort(500) ```

func (*Context) Get 

func (c *Context) Get(key string) interface{}

Returns the value for the given key. It panics if the value doesn't exist.

func (*Context) HTML 

func (c *Context) HTML(code int, name string, data interface{})

Renders the HTTP template specified by its file name. It also updates the HTTP code and sets the Content-Type as "text/html". See http://golang.org/doc/articles/wiki/

func (*Context) JSON 

func (c *Context) JSON(code int, obj interface{})

Serializes the given struct as JSON into the response body in a fast and efficient way. It also sets the Content-Type as "application/json".

func (*Context) LastError 

func (c *Context) LastError() error

func (*Context) Next 

func (c *Context) Next()

Next should be used only in the middlewares. It executes the pending handlers in the chain inside the calling handler. See example in github.

func (*Context) ParseBody 

func (c *Context) ParseBody(item interface{}) error

Parses the body content as a JSON input. It decodes the json payload into the struct specified as a pointer.

func (*Context) Set 

func (c *Context) Set(key string, item interface{})

Sets a new pair key/value just for the specified context. It also lazy initializes the hashmap.

func (*Context) String 

func (c *Context) String(code int, msg string)

Writes the given string into the response body and sets the Content-Type to "text/plain".

func (*Context) XML 

func (c *Context) XML(code int, obj interface{})

Serializes the given struct as XML into the response body in a fast and efficient way. It also sets the Content-Type as "application/xml".

type Engine 

type Engine struct {
	*RouterGroup

	HTMLTemplates *template.Template
	// contains filtered or unexported fields
}

Represents the web framework, it wraps the blazing fast httprouter multiplexer and a list of global middlewares.

func Default 

func Default() *Engine

Returns a Engine instance with the Logger and Recovery already attached.

func New 

func New() *Engine

Returns a new blank Engine instance without any middleware attached. The most basic configuration

func (*Engine) LoadHTMLTemplates 

func (engine *Engine) LoadHTMLTemplates(pattern string)

func (*Engine) NotFound404 

func (engine *Engine) NotFound404(handlers ...HandlerFunc)

Adds handlers for NotFound. It return a 404 code by default.

func (*Engine) Run 

func (engine *Engine) Run(addr string)

func (*Engine) ServeFiles 

func (engine *Engine) ServeFiles(path string, root http.FileSystem)

ServeFiles serves files from the given file system root. The path must end with "/*filepath", files are then served from the local path /defined/root/dir/*filepath. For example if root is "/etc" and *filepath is "passwd", the local file "/etc/passwd" would be served. Internally a http.FileServer is used, therefore http.NotFound is used instead of the Router's NotFound handler. To use the operating system's file system implementation, use http.Dir: 

router.ServeFiles("/src/*filepath", http.Dir("/var/www"))

func (*Engine) ServeHTTP 

func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP makes the router implement the http.Handler interface.

type ErrorMsg 

type ErrorMsg struct {
	Err  string      `json:"error"`
	Meta interface{} `json:"meta"`
}

Used internally to collect errors that occurred during an http request.

type ErrorMsgs 

type ErrorMsgs []ErrorMsg

func (ErrorMsgs) String 

func (a ErrorMsgs) String() string

type H 

type H map[string]interface{}

type HandlerFunc 

type HandlerFunc func(*Context)

func BasicAuth 

func BasicAuth(accounts Accounts) HandlerFunc

Implements a basic Basic HTTP Authorization. It takes as argument a map[string]string where the key is the user name and the value is the password.

func ErrorLogger 

func ErrorLogger() HandlerFunc

func Logger 

func Logger() HandlerFunc

func Recovery 

func Recovery() HandlerFunc

Recovery returns a middleware that recovers from any panics and writes a 500 if there was one. While Martini is in development mode, Recovery will also output the panic as HTML.

type Pairs 

type Pairs []BasicAuthPair

func (Pairs) Len 

func (a Pairs) Len() int

func (Pairs) Less 

func (a Pairs) Less(i, j int) bool

func (Pairs) Swap 

func (a Pairs) Swap(i, j int)

type RouterGroup 

type RouterGroup struct {
	Handlers []HandlerFunc
	// contains filtered or unexported fields
}

Used internally to configure router, a RouterGroup is associated with a prefix and an array of handlers (middlewares)

func (*RouterGroup) DELETE 

func (group *RouterGroup) DELETE(path string, handlers ...HandlerFunc)

DELETE is a shortcut for router.Handle("DELETE", path, handle)

func (*RouterGroup) GET 

func (group *RouterGroup) GET(path string, handlers ...HandlerFunc)

GET is a shortcut for router.Handle("GET", path, handle)

func (*RouterGroup) Group 

func (group *RouterGroup) Group(component string, handlers ...HandlerFunc) *RouterGroup

Creates a new router group. You should add all the routes that have common middlwares or the same path prefix. For example, all the routes that use a common middlware for authorization could be grouped.

func (*RouterGroup) Handle 

func (group *RouterGroup) Handle(method, p string, handlers []HandlerFunc)

Handle registers a new request handle and middlewares with the given path and method. The last handler should be the real handler, the other ones should be middlewares that can and should be shared among different routes. See the example code in github.

For GET, POST, PUT, PATCH and DELETE requests the respective shortcut functions can be used.

This function is intended for bulk loading and to allow the usage of less frequently used, non-standardized or custom methods (e.g. for internal communication with a proxy).

func (*RouterGroup) PATCH 

func (group *RouterGroup) PATCH(path string, handlers ...HandlerFunc)

PATCH is a shortcut for router.Handle("PATCH", path, handle)

func (*RouterGroup) POST 

func (group *RouterGroup) POST(path string, handlers ...HandlerFunc)

POST is a shortcut for router.Handle("POST", path, handle)

func (*RouterGroup) PUT 

func (group *RouterGroup) PUT(path string, handlers ...HandlerFunc)

PUT is a shortcut for router.Handle("PUT", path, handle)

func (*RouterGroup) Use 

func (group *RouterGroup) Use(middlewares ...HandlerFunc)

Adds middlewares to the group, see example code in github.

Source Files

View all Source files

Directories

Path Synopsis
app-engine

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.