Gear Save
A lightweight, composable and high performance web service framework for Go.
A lightweight, composable and high performance web service framework for Go.
Features
- Effective and flexible middlewares flow control, create anything by middleware
- Powerful and smart HTTP error handling
- Trie base gear.Router, as faster as HttpRouter, support regexp parameters and group routes
- Integrated timeout context.Context
- Integrated response content compress
- Integrated structured logging middleware
- Integrated request body parser
- Integrated signed cookies
- Integrated JSON, JSONP, XML and HTML renderer
- Integrated CORS, Secure, Favicon and Static middlewares
- More useful methods on gear.Context to manipulate HTTP Request/Response
- Run HTTP and gRPC on the same port
- Completely HTTP/2.0 supported
Documentation
Import
// package gear
import "github.com/teambition/gear"
Design
- Server 底层基于原生 net/http 而不是 fasthttp
- 通过 gear.Middleware 中间件模式扩展功能模块
- 中间件的单向顺序流程控制和级联流程控制
- 功能强大，完美集成 context.Context 的 gear.Context
- 集中、智能、可自定义的错误和异常处理
- After Hook 和 End Hook 的后置处理
- Any interface 无限的 gear.Context 状态扩展能力
- 请求数据的解析和验证
FAQ
Demo
Hello
https://github.com/teambition/gear/tree/master/example/hello
app := gear.New()
// Add logging middleware
app.UseHandler(logging.Default(true))
// Add router middleware
router := gear.NewRouter()
// try: http://127.0.0.1:3000/hello
router.Get("/hello", func(ctx *gear.Context) error {
return ctx.HTML(200, "<h1>Hello, Gear!</h1>")
})
// try: http://127.0.0.1:3000/test?query=hello
router.Otherwise(func(ctx *gear.Context) error {
return ctx.JSON(200, map[string]any{
"Host": ctx.Host,
"Method": ctx.Method,
"Path": ctx.Path,
"URI": ctx.Req.RequestURI,
"Headers": ctx.Req.Header,
})
})
app.UseHandler(router)
app.Error(app.Listen(":3000"))
HTTP2 with Push
https://github.com/teambition/gear/tree/master/example/http2
package main
import (
"net/http"
"github.com/teambition/gear"
"github.com/teambition/gear/logging"
"github.com/teambition/gear/middleware/favicon"
)
// go run example/http2/app.go
// Visit: https://127.0.0.1:3000/
func main() {
const htmlBody = `
<!DOCTYPE html>
<html>
<head>
<link href="/hello.css" rel="stylesheet" type="text/css">
</head>
<body>
<h1>Hello, Gear!</h1>
</body>
</html>`
const pushBody = `
h1 {
color: red;
}
`
app := gear.New()
app.UseHandler(logging.Default(true))
app.Use(favicon.New("./testdata/favicon.ico"))
router := gear.NewRouter()
router.Get("/", func(ctx *gear.Context) error {
ctx.Res.Push("/hello.css", &http.PushOptions{Method: "GET"})
return ctx.HTML(200, htmlBody)
})
router.Get("/hello.css", func(ctx *gear.Context) error {
ctx.Type("text/css")
return ctx.End(200, []byte(pushBody))
})
app.UseHandler(router)
app.Error(app.ListenTLS(":3000", "./testdata/out/test.crt", "./testdata/out/test.key"))
}
A CMD tool: static server
https://github.com/teambition/gear/tree/master/example/staticgo
Install it with go:
go install github.com/teambition/gear/example/staticgo@latest
It is a useful CMD tool that serve your local files as web server (support TLS).
You can build osx, linux, windows version with make build.
package main
import (
"flag"
"github.com/teambition/gear"
"github.com/teambition/gear/logging"
"github.com/teambition/gear/middleware/cors"
"github.com/teambition/gear/middleware/static"
)
var (
address = flag.String("addr", "127.0.0.1:3000", `address to listen on.`)
path = flag.String("path", "./", `static files path to serve.`)
certFile = flag.String("certFile", "", `certFile path, used to create TLS static server.`)
keyFile = flag.String("keyFile", "", `keyFile path, used to create TLS static server.`)
)
func main() {
flag.Parse()
app := gear.New()
app.UseHandler(logging.Default(true))
app.Use(cors.New())
app.Use(static.New(static.Options{Root: *path}))
logging.Println("staticgo v1.2.0, created by https://github.com/teambition/gear")
logging.Printf("listen: %s, serve: %s\n", *address, *path)
if *certFile != "" && *keyFile != "" {
app.Error(app.ListenTLS(*address, *certFile, *keyFile))
} else {
app.Error(app.Listen(*address))
}
}
A CMD tool: reverse proxy server
https://github.com/teambition/gear/tree/master/example/gearproxy
Install it with go:
go install github.com/teambition/gear/example/gearproxy@latest
gearproxy -help
HTTP2 & gRPC
https://github.com/teambition/gear/tree/master/example/grpc_server
https://github.com/teambition/gear/tree/master/example/grpc_client
About Router
gear.Router is a trie base HTTP request handler. Features:
- Support named parameter
- Support regexp
- Support suffix matching
- Support multi-router
- Support router layer middlewares
- Support fixed path automatic redirection
- Support trailing slash automatic redirection
- Automatic handle
405 Method Not Allowed - Automatic handle
OPTIONSmethod - Best Performance
The registered path, against which the router matches incoming requests, can contain six types of parameters:
| Syntax | Description |
|---|---|
:name |
named parameter |
:name(regexp) |
named with regexp parameter |
:name+suffix |
named parameter with suffix matching |
:name(regexp)+suffix |
named with regexp parameter and suffix matching |
:name* |
named with catch-all parameter |
::name |
not named parameter, it is literal :name |
Named parameters are dynamic path segments. They match anything until the next '/' or the path end:
Defined: /api/:type/:ID
/api/user/123 matched: type="user", ID="123"
/api/user no match
/api/user/123/comments no match
Named with regexp parameters match anything using regexp until the next '/' or the path end:
Defined: /api/:type/:ID(^\d+$)
/api/user/123 matched: type="user", ID="123"
/api/user no match
/api/user/abc no match
/api/user/123/comments no match
Named parameters with suffix, such as Google API Design:
Defined: /api/:resource/:ID+:undelete
/api/file/123 no match
/api/file/123:undelete matched: resource="file", ID="123"
/api/file/123:undelete/comments no match
Named with regexp parameters and suffix:
Defined: /api/:resource/:ID(^\d+$)+:cancel
/api/task/123 no match
/api/task/123:cancel matched: resource="task", ID="123"
/api/task/abc:cancel no match
Named with catch-all parameters match anything until the path end, including the directory index (the '/' before the catch-all). Since they match anything until the end, catch-all parameters must always be the final path element.
Defined: /files/:filepath*
/files no match
/files/LICENSE matched: filepath="LICENSE"
/files/templates/article.html matched: filepath="templates/article.html"
The value of parameters is saved on the Matched.Params. Retrieve the value of a parameter by name:
type := matched.Params("type")
id := matched.Params("ID")
More Middlewares
- Structured logging: github.com/teambition/gear/logging
- CORS handler: github.com/teambition/gear/middleware/cors
- Secure handler: github.com/teambition/gear/middleware/secure
- Static serving: github.com/teambition/gear/middleware/static
- Favicon serving: github.com/teambition/gear/middleware/favicon
- gRPC serving: github.com/teambition/gear/middleware/grpc
- JWT and Crypto auth: Gear-Auth
- Cookie session: Gear-Session
- Session middleware: https://github.com/go-session/gear-session
- Smart rate limiter: Gear-Ratelimiter
- CSRF: Gear-CSRF
- Opentracing with Zipkin: Gear-Tracing
License
Gear is licensed under the MIT license. Copyright © 2016-2023 Teambition.
Open Source Agenda Badge
