README
¶
middleware
gin middleware plugin.
Example of use
logging middleware
You can set the maximum length for printing, add a request id field, ignore print path, customize zap log
r := gin.Default()
r.Use(middleware.Logging())
r.Use(middleware.Logging(
middleware.WithMaxLen(400),
//WithRequestIDFromHeader(),
WithRequestIDFromContext(),
//middleware.WithIgnoreRoutes("/hello"),
))
log, _ := logger.Init(logger.WithFormat("json"))
r.Use(middlewareLogging(
middleware.WithLog(log),
))
Allow cross-domain requests middleware
r := gin.Default()
r.Use(middleware.Cors())
rate limiter middleware
Adaptive flow limitation based on hardware resources.
r := gin.Default()
// e.g. (1) use default
// r.Use(RateLimit())
// e.g. (2) custom parameters
r.Use(RateLimit(
WithWindow(time.Second*10),
WithBucket(100),
WithCPUThreshold(100),
WithCPUQuota(0.5),
))
Circuit Breaker middleware
r := gin.Default()
r.Use(CircuitBreaker())
jwt authorization middleware
common authorization
import "github.com/zhufuyi/sponge/pkg/jwt"
func main() {
r := gin.Default()
r.POST("/user/login", Login)
r.GET("/user/:id", middleware.Auth(), h.GetByID) // no verify field
// r.GET("/user/:id", middleware.Auth(middleware.WithVerify(adminVerify)), userFun) // with verify field
r.Run(serverAddr)
}
func adminVerify(claims *jwt.Claims) error {
if claims.Role != "admin" {
return errors.New("verify failed")
}
return nil
}
func Login(c *gin.Context) {
// login success
// generate token
token, err := jwt.GenerateToken("123", "admin")
// handle err
}
custom authorization
import "github.com/zhufuyi/sponge/pkg/jwt"
func main() {
r := gin.Default()
r.POST("/user/login", Login)
r.GET("/user/:id", middleware.AuthCustom(verify), userFun)
r.Run(serverAddr)
}
func verify(claims *jwt.CustomClaims) error {
err := errors.New("verify failed")
id, exist := claims.Get("id")
if !exist {
return err
}
foo, exist := claims.Get("foo")
if !exist {
return err
}
if int(id.(float64)) != fields["id"].(int) || foo.(string) != fields["foo"].(string) {
return err
}
return nil
}
func Login(c *gin.Context) {
// login success
// generate token
fields := jwt.KV{"id": 123, "foo": "bar"}
token, err := jwt.GenerateCustomToken(fields)
// handle err
}
tracing middleware
func InitTrace(serviceName string) {
exporter, err := tracer.NewJaegerAgentExporter("192.168.3.37", "6831")
if err != nil {
panic(err)
}
resource := tracer.NewResource(
tracer.WithServiceName(serviceName),
tracer.WithEnvironment("dev"),
tracer.WithServiceVersion("demo"),
)
tracer.Init(exporter, resource) // collect all by default
}
func NewRouter(
r := gin.Default()
r.Use(middleware.Tracing("your-service-name"))
// ......
)
// if necessary, you can create a span in the program
func SpanDemo(serviceName string, spanName string, ctx context.Context) {
_, span := otel.Tracer(serviceName).Start(
ctx, spanName,
trace.WithAttributes(attribute.String(spanName, time.Now().String())),
)
defer span.End()
// ......
}
Metrics middleware
r := gin.Default()
r.Use(metrics.Metrics(r,
//metrics.WithMetricsPath("/demo/metrics"), // default is /metrics
metrics.WithIgnoreStatusCodes(http.StatusNotFound), // ignore status codes
//metrics.WithIgnoreRequestMethods(http.MethodHead), // ignore request methods
//metrics.WithIgnoreRequestPaths("/ping", "/health"), // ignore request paths
))
Request id
r := gin.Default()
r.Use(RequestID())
// Customized request id key
//r.User(RequestID(
// middleware.WithContextRequestIDKey("your ctx request id key"), // default is request_id
// middleware.WithHeaderRequestIDKey("your header request id key"), // default is X-Request-Id
//))
// If you change the ContextRequestIDKey, you have to set the same key name if you want to print the request id in the mysql logs as well.
// example:
// db, err := mysql.Init(dsn,
// mysql.WithLogRequestIDKey("your ctx request id key"), // print request_id
// ...
// )
Documentation
¶
Overview ¶
Package middleware is gin middleware plugin.
Index ¶
- Constants
- Variables
- func Auth(opts ...JwtOption) gin.HandlerFunc
- func AuthCustom(verify VerifyCustomFn, opts ...JwtOption) gin.HandlerFunc
- func CircuitBreaker(opts ...CircuitBreakerOption) gin.HandlerFunc
- func Cors() gin.HandlerFunc
- func CtxRequestID(ctx context.Context) string
- func CtxRequestIDField(ctx context.Context) zap.Field
- func GCtxRequestID(c *gin.Context) string
- func GCtxRequestIDField(c *gin.Context) zap.Field
- func GetFromCtx(ctx context.Context, key string) interface{}
- func GetFromHeader(ctx context.Context, key string) string
- func GetFromHeaders(ctx context.Context, key string) []string
- func HeaderRequestID(c *gin.Context) string
- func HeaderRequestIDField(c *gin.Context) zap.Field
- func Logging(opts ...Option) gin.HandlerFunc
- func RateLimit(opts ...RateLimitOption) gin.HandlerFunc
- func RequestID(opts ...RequestIDOption) gin.HandlerFunc
- func Tracing(serviceName string, opts ...TraceOption) gin.HandlerFunc
- func WrapCtx(c *gin.Context) context.Context
- type CircuitBreakerOption
- type CtxKeyString
- type JwtOption
- type Option
- type RateLimitOption
- type RequestIDOption
- type TraceOption
- type VerifyCustomFn
- type VerifyFn
Constants ¶
const (
// HeaderAuthorizationKey http header authorization key
HeaderAuthorizationKey = "Authorization"
)
Variables ¶
var ( // ContextRequestIDKey request id for context ContextRequestIDKey = "request_id" // HeaderXRequestIDKey header request id key HeaderXRequestIDKey = "X-Request-Id" )
var ErrLimitExceed = rl.ErrLimitExceed
ErrLimitExceed is returned when the rate limiter is triggered and the request is rejected due to limit exceeded.
var ErrNotAllowed = circuitbreaker.ErrNotAllowed
ErrNotAllowed error not allowed.
var RequestHeaderKey = "request_header_key"
RequestHeaderKey request header key
var RequestIDKey = CtxKeyString(ContextRequestIDKey)
RequestIDKey request_id
Functions ¶
func AuthCustom ¶ added in v1.5.4
func AuthCustom(verify VerifyCustomFn, opts ...JwtOption) gin.HandlerFunc
AuthCustom custom authentication
func CircuitBreaker ¶
func CircuitBreaker(opts ...CircuitBreakerOption) gin.HandlerFunc
CircuitBreaker a circuit breaker middleware
func CtxRequestID ¶ added in v1.2.0
CtxRequestID get request id from context.Context
func CtxRequestIDField ¶ added in v1.2.0
CtxRequestIDField get request id field from context.Context
func GCtxRequestID ¶ added in v1.2.0
GCtxRequestID get request id from gin.Context
func GCtxRequestIDField ¶ added in v1.2.0
GCtxRequestIDField get request id field from gin.Context
func GetFromCtx ¶ added in v1.5.6
GetFromCtx get value from context
func GetFromHeader ¶ added in v1.5.6
GetFromHeader get value from header
func GetFromHeaders ¶ added in v1.5.6
GetFromHeaders get values from header
func HeaderRequestID ¶ added in v1.2.0
HeaderRequestID get request id from the header
func HeaderRequestIDField ¶ added in v1.2.0
HeaderRequestIDField get request id field from header
func RateLimit ¶
func RateLimit(opts ...RateLimitOption) gin.HandlerFunc
RateLimit an adaptive rate limiter middleware
func RequestID ¶
func RequestID(opts ...RequestIDOption) gin.HandlerFunc
RequestID is an interceptor that injects a 'request id' into the context and request/response header of each request.
func Tracing ¶
func Tracing(serviceName string, opts ...TraceOption) gin.HandlerFunc
Tracing returns interceptor that will trace incoming requests. The service parameter should describe the name of the (virtual) server handling the request.
Types ¶
type CircuitBreakerOption ¶
type CircuitBreakerOption func(*circuitBreakerOptions)
CircuitBreakerOption set the circuit breaker circuitBreakerOptions.
func WithGroup ¶
func WithGroup(g *group.Group) CircuitBreakerOption
WithGroup with circuit breaker group. NOTE: implements generics circuitbreaker.CircuitBreaker
func WithValidCode ¶ added in v1.4.2
func WithValidCode(code ...int) CircuitBreakerOption
WithValidCode http code to mark failed
type CtxKeyString ¶ added in v1.5.3
type CtxKeyString string
CtxKeyString for context.WithValue key type
type JwtOption ¶ added in v1.5.4
type JwtOption func(*jwtOptions)
JwtOption set the jwt options.
func WithSwitchHTTPCode ¶ added in v1.5.4
func WithSwitchHTTPCode() JwtOption
WithSwitchHTTPCode switch to http code
func WithVerify ¶ added in v1.5.4
WithVerify set verify function
type Option ¶
type Option func(*options)
Option set the gin logger options.
func WithIgnoreRoutes ¶
WithIgnoreRoutes no logger content routes
func WithRequestIDFromContext ¶
func WithRequestIDFromContext() Option
WithRequestIDFromContext name is field in context, default value is request_id
func WithRequestIDFromHeader ¶
func WithRequestIDFromHeader() Option
WithRequestIDFromHeader name is field in header, default value is X-Request-Id
type RateLimitOption ¶
type RateLimitOption func(*rateLimitOptions)
RateLimitOption set the rate limits rateLimitOptions.
func WithCPUQuota ¶
func WithCPUQuota(quota float64) RateLimitOption
WithCPUQuota with real cpu quota(if it can not collect from process correct);
func WithCPUThreshold ¶
func WithCPUThreshold(threshold int64) RateLimitOption
WithCPUThreshold with cpu threshold
type RequestIDOption ¶ added in v1.5.6
type RequestIDOption func(*requestIDOptions)
RequestIDOption set the request id options.
func WithContextRequestIDKey ¶ added in v1.5.6
func WithContextRequestIDKey(key string) RequestIDOption
WithContextRequestIDKey set context request id key, minimum length of 4
func WithHeaderRequestIDKey ¶ added in v1.5.6
func WithHeaderRequestIDKey(key string) RequestIDOption
WithHeaderRequestIDKey set header request id key, minimum length of 4
type TraceOption ¶
type TraceOption func(*traceConfig)
TraceOption specifies instrumentation configuration options.
func WithPropagators ¶
func WithPropagators(propagators propagation.TextMapPropagator) TraceOption
WithPropagators specifies propagators to use for extracting information from the HTTP requests. If none are specified, global ones will be used.
func WithTracerProvider ¶
func WithTracerProvider(provider oteltrace.TracerProvider) TraceOption
WithTracerProvider specifies a tracer provider to use for creating a tracer. If none is specified, the global provider is used.
type VerifyCustomFn ¶ added in v1.5.4
type VerifyCustomFn func(claims *jwt.CustomClaims) error
VerifyCustomFn verify custom function
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package metrics is gin metrics library, collect five metrics, "uptime", "http_request_count_total", "http_request_duration_seconds", "http_request_size_bytes", "http_response_size_bytes".
|
Package metrics is gin metrics library, collect five metrics, "uptime", "http_request_count_total", "http_request_duration_seconds", "http_request_size_bytes", "http_response_size_bytes". |