gorouter

package module
v3.0.4+incompatible Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2018 License: MIT Imports: 4 Imported by: 2

README

Vardius - gorouter

Build Status Go Report Card codecov license Beerpay Beerpay

Go Server/API micro framwework, HTTP request router, multiplexer, mux.

ABOUT

Contributors:

Want to contribute ? Feel free to send pull requests!

Have problems, bugs, feature ideas? We are using the github issue tracker to manage them.

HOW TO USE

  1. GoDoc
  2. Documentation
  3. Benchmarks
  4. Go Server/API boilerplate using best practices DDD CQRS ES

Basic example

package main

import (
    "fmt"
    "log"
    "net/http"
	
    "github.com/vardius/gorouter"
)

func Index(w http.ResponseWriter, r *http.Request) {
    fmt.Fprint(w, "Welcome!\n")
}

func Hello(w http.ResponseWriter, r *http.Request) {
    params, _ := gorouter.FromContext(r.Context())
    fmt.Fprintf(w, "hello, %s!\n", params.Value("name"))
}

func main() {
    router := gorouter.New()
    router.GET("/", http.HandlerFunc(Index))
    router.GET("/hello/{name}", http.HandlerFunc(Hello))

    log.Fatal(http.ListenAndServe(":8080", router))
}

License

This package is released under the MIT license. See the complete license in the package:

LICENSE

Documentation

Overview

Package gorouter provide request router with middleware

Router

The router determines how to handle that request. GoRouter uses a routing tree. Once one branch of the tree matches, only routes inside that branch are considered, not any routes after that branch. When instantiating router, the root node of tree is created.

Route types

- Static `/hello` (will match requests matching given route)

- Named `/{name}` (will match requests matching given route scheme)

- Regexp `/{name:[a-z]+}` (will match requests matching given route scheme and its regexp)

Wildcards

The values of *named parameter* or *regexp parameters* are accessible via *request context* `params, ok := gorouter.FromContext(req.Context())`. You can get the value of a parameter either by its index in the slice, or by using the `params.Value(name)` method: `:name` or `/{name:[a-z]+}` can be retrieved by `params.Value("name")`.

Defining Routes

A full route definition contain up to three parts:

1. HTTP method under which route will be available

2. The URL path route. This is matched against the URL passed to the router, and can contain named wildcard placeholders *(e.g. {placeholder})* to match dynamic parts in the URL.

3. `http.HandleFunc`, which tells the router to handle matched requests to the router with handler.

Take the following example: 

router.GET("/hello/{name:r([a-z]+)go}", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
  params, _ := gorouter.FromContext(r.Context())
  fmt.Fprintf(w, "hello, %s!\n", params.Value("name"))
}))

In this case, the route is matched by `/hello/rxxxxxgo` for example, because the `:name` wildcard matches the regular expression wildcard given (`r([a-z]+)go`). However, `/hello/foo` does not match, because "foo" fails the *name* wildcard. When using wildcards, these are returned in the map from request context. The part of the path that the wildcard matched (e.g. *rxxxxxgo*) is used as value.

Example 
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/vardius/gorouter"
)

func main() {
	hello := func(w http.ResponseWriter, r *http.Request) {
		params, _ := gorouter.FromContext(r.Context())
		fmt.Printf("Hello, %s!\n", params.Value("name"))
	}

	router := gorouter.New()
	router.GET("/hello/{name}", http.HandlerFunc(hello))

	// Normally you would call ListenAndServe starting an HTTP server
	// with a given address and router as a handler
	// log.Fatal(http.ListenAndServe(":8080", router))
	// but for this example we will mock request

	w := httptest.NewRecorder()
	req, err := http.NewRequest(gorouter.GET, "/hello/guest", nil)
	if err != nil {
		return
	}

	router.ServeHTTP(w, req)

}

Output:

Hello, guest!

Index

Examples

Constants

View Source 
const (
	GET     = "GET"
	POST    = "POST"
	PUT     = "PUT"
	DELETE  = "DELETE"
	PATCH   = "PATCH"
	OPTIONS = "OPTIONS"
	HEAD    = "HEAD"
	CONNECT = "CONNECT"
	TRACE   = "TRACE"
)

HTTP methods constants

Variables

This section is empty.

Functions

This section is empty.

Types

type MiddlewareFunc 

type MiddlewareFunc func(http.Handler) http.Handler

MiddlewareFunc is a middleware function type. It accepts as a parameter http.Handler and returns http.Handler as well Long story - short: it is a http.Handler wrapper

Example 
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/vardius/gorouter"
)

func main() {
	// Global middleware example
	// applies to all routes
	hello := func(w http.ResponseWriter, r *http.Request) {
		params, _ := gorouter.FromContext(r.Context())
		fmt.Printf("Hello, %s!\n", params.Value("name"))
	}

	logger := func(next http.Handler) http.Handler {
		fn := func(w http.ResponseWriter, r *http.Request) {
			fmt.Printf("[%s] %q\n", r.Method, r.URL.String())
			next.ServeHTTP(w, r)
		}

		return http.HandlerFunc(fn)
	}

	// apply middlewares to all routes
	// can pass as many as you want
	router := gorouter.New(logger)
	router.GET("/hello/{name}", http.HandlerFunc(hello))

	// Normally you would call ListenAndServe starting an HTTP server
	// with a given address and router as a handler
	// log.Fatal(http.ListenAndServe(":8080", router))
	// but for this example we will mock request

	w := httptest.NewRecorder()
	req, err := http.NewRequest(gorouter.GET, "/hello/guest", nil)
	if err != nil {
		return
	}

	router.ServeHTTP(w, req)

}

Output:

[GET] "/hello/guest"
Hello, guest!
Example (Second) 
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/vardius/gorouter"
)

func main() {
	// Route level middleware example
	// applies to route and its lower tree
	hello := func(w http.ResponseWriter, r *http.Request) {
		params, _ := gorouter.FromContext(r.Context())
		fmt.Printf("Hello, %s!\n", params.Value("name"))
	}

	logger := func(next http.Handler) http.Handler {
		fn := func(w http.ResponseWriter, r *http.Request) {
			fmt.Printf("[%s] %q\n", r.Method, r.URL.String())
			next.ServeHTTP(w, r)
		}

		return http.HandlerFunc(fn)
	}

	router := gorouter.New()
	router.GET("/hello/{name}", http.HandlerFunc(hello))

	// apply middlewares to route and all it children
	// can pass as many as you want
	router.USE("GET", "/hello/{name}", logger)

	// Normally you would call ListenAndServe starting an HTTP server
	// with a given address and router as a handler
	// log.Fatal(http.ListenAndServe(":8080", router))
	// but for this example we will mock request

	w := httptest.NewRecorder()
	req, err := http.NewRequest(gorouter.GET, "/hello/guest", nil)
	if err != nil {
		return
	}

	router.ServeHTTP(w, req)

}

Output:

[GET] "/hello/guest"
Hello, guest!
Example (Third) 
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/vardius/gorouter"
)

func main() {
	// Http method middleware example
	// applies to all routes under this method
	hello := func(w http.ResponseWriter, r *http.Request) {
		params, _ := gorouter.FromContext(r.Context())
		fmt.Printf("Hello, %s!\n", params.Value("name"))
	}

	logger := func(next http.Handler) http.Handler {
		fn := func(w http.ResponseWriter, r *http.Request) {
			fmt.Printf("[%s] %q\n", r.Method, r.URL.String())
			next.ServeHTTP(w, r)
		}

		return http.HandlerFunc(fn)
	}

	router := gorouter.New()
	router.GET("/hello/{name}", http.HandlerFunc(hello))

	// apply middlewares to all routes with GET method
	// can pass as many as you want
	router.USE("GET", "", logger)

	// Normally you would call ListenAndServe starting an HTTP server
	// with a given address and router as a handler
	// log.Fatal(http.ListenAndServe(":8080", router))
	// but for this example we will mock request

	w := httptest.NewRecorder()
	req, err := http.NewRequest(gorouter.GET, "/hello/guest", nil)
	if err != nil {
		return
	}

	router.ServeHTTP(w, req)

}

Output:

[GET] "/hello/guest"
Hello, guest!

type Param 

type Param struct {
	Key   string
	Value string
}

Param object to hold request parameter

type Params 

type Params []Param

Params slice returned from request context

func FromContext 

func FromContext(ctx context.Context) (Params, bool)

FromContext extracts the request Params ctx, if present.

func (Params) Value 

func (p Params) Value(key string) string

Value of the request parameter by name

type Router 

type Router interface {
	// POST adds http.Handler as router handler
	// under POST method and given patter
	POST(pattern string, handler http.Handler)

	// GET adds http.Handler as router handler
	// under GET method and given patter
	GET(pattern string, handler http.Handler)

	// PUT adds http.Handler as router handler
	// under PUT method and given patter
	PUT(pattern string, handler http.Handler)

	// DELETE adds http.Handler as router handler
	// under DELETE method and given patter
	DELETE(pattern string, handler http.Handler)

	// PATCH adds http.Handler as router handler
	// under PATCH method and given patter
	PATCH(pattern string, handler http.Handler)

	// OPTIONS adds http.Handler as router handler
	// under OPTIONS method and given patter
	OPTIONS(pattern string, handler http.Handler)

	// HEAD adds http.Handler as router handler
	// under HEAD method and given patter
	HEAD(pattern string, handler http.Handler)

	// CONNECT adds http.Handler as router handler
	// under CONNECT method and given patter
	CONNECT(pattern string, handler http.Handler)

	// TRACE adds http.Handler as router handler
	// under TRACE method and given patter
	TRACE(pattern string, handler http.Handler)

	// USE adds middleware functions ([]MiddlewareFunc)
	// to whole router branch under given method and patter
	USE(method, pattern string, fs ...MiddlewareFunc)

	// Handle adds http.Handler as router handler
	// under given method and patter
	Handle(method, pattern string, handler http.Handler)

	// HandleFunc adds http.HandlerFunc as router handler
	// under given method and patter
	HandleFunc(method, pattern string, handler http.HandlerFunc)

	// Mount another handler as a subrouter
	Mount(pattern string, handler http.Handler)

	// ServeHTTP dispatches the request to the route handler
	// whose pattern matches the request URL
	ServeHTTP(http.ResponseWriter, *http.Request)

	// ServeFile replies to the request with the
	// contents of the named file or directory.
	ServeFiles(root http.FileSystem, path string, strip bool)

	// NotFound replies to the request with the
	// 404 Error code
	NotFound(http.Handler)

	// NotFound replies to the request with the
	// 405 Error code
	NotAllowed(http.Handler)
}

Router is a micro framwework, HTTP request router, multiplexer, mux

Example (Mount) 
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/vardius/gorouter"
)

func main() {
	hello := func(w http.ResponseWriter, r *http.Request) {
		params, _ := gorouter.FromContext(r.Context())
		fmt.Printf("Hello, %s!\n", params.Value("name"))
	}

	subrouter := gorouter.New()
	subrouter.GET("/{name}", http.HandlerFunc(hello))

	router := gorouter.New()
	router.Mount("/hello", subrouter)

	// Normally you would call ListenAndServe starting an HTTP server
	// with a given address and router as a handler
	// log.Fatal(http.ListenAndServe(":8080", router))
	// but for this example we will mock request

	w := httptest.NewRecorder()
	req, err := http.NewRequest(gorouter.GET, "/hello/guest", nil)
	if err != nil {
		return
	}

	router.ServeHTTP(w, req)

}

Output:

Hello, guest!
Example (Mount_second) 
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/vardius/gorouter"
)

func main() {
	subrouter := http.NewServeMux()
	subrouter.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		fmt.Println("Hello, guest!")
	})

	router := gorouter.New()
	router.Mount("/hello", subrouter)

	// Normally you would call ListenAndServe starting an HTTP server
	// with a given address and router as a handler
	// log.Fatal(http.ListenAndServe(":8080", router))
	// but for this example we will mock request

	w := httptest.NewRecorder()
	req, err := http.NewRequest(gorouter.GET, "/hello/guest", nil)
	if err != nil {
		return
	}

	router.ServeHTTP(w, req)

}

Output:

Hello, guest!

func New 

func New(fs ...MiddlewareFunc) Router

New creates new Router instance, return pointer

Source Files

View all Source files

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.