The Middleware API provides a unified middleware system for both HTTP and gRPC transports in Kratos.
Types
Handler
Defines the handler function invoked by Middleware.
type Handler func(ctx context.Context, req any) (any, error)
Error if the request failed
Middleware
HTTP/gRPC transport middleware function.
type Middleware func(Handler) Handler
Functions
Chain
Returns a Middleware that chains multiple middleware together.
func Chain(m ...Middleware) Middleware
Variable number of middleware to chain. Middleware are executed in the order provided.
A single middleware that executes all chained middleware in sequence
import (
"github.com/go-kratos/kratos/v2/middleware"
"github.com/go-kratos/kratos/v2/middleware/logging"
"github.com/go-kratos/kratos/v2/middleware/recovery"
"github.com/go-kratos/kratos/v2/middleware/tracing"
)
// Chain multiple middleware
mw := middleware.Chain(
recovery.Recovery(),
tracing.Server(),
logging.Server(logger),
)
Built-in Middleware
Kratos provides several built-in middleware packages:
Auth
Provides JWT authentication middleware.
import "github.com/go-kratos/kratos/v2/middleware/auth/jwt"
Circuit Breaker
Provides circuit breaker pattern implementation.
import "github.com/go-kratos/kratos/v2/middleware/circuitbreaker"
Logging
Logs request and response information.
import "github.com/go-kratos/kratos/v2/middleware/logging"
logging.Server(logger)
logging.Client(logger)
import "github.com/go-kratos/kratos/v2/middleware/metadata"
metadata.Server()
metadata.Client()
Metrics
Collects metrics for requests.
import "github.com/go-kratos/kratos/v2/middleware/metrics"
metrics.Server()
metrics.Client()
Rate Limit
Provides rate limiting functionality.
import "github.com/go-kratos/kratos/v2/middleware/ratelimit"
Recovery
Recovers from panics in handlers.
import "github.com/go-kratos/kratos/v2/middleware/recovery"
recovery.Recovery()
Selector
Conditionally applies middleware based on operation matching.
import "github.com/go-kratos/kratos/v2/middleware/selector"
Tracing
Provides distributed tracing support.
import "github.com/go-kratos/kratos/v2/middleware/tracing"
tracing.Server()
tracing.Client()
Validate
Validates request payloads.
import "github.com/go-kratos/kratos/v2/middleware/validate"
validate.Validator()
Custom Middleware Example
Creating a custom middleware:
package main
import (
"context"
"fmt"
"time"
"github.com/go-kratos/kratos/v2/middleware"
)
// Timing middleware measures request duration
func Timing() middleware.Middleware {
return func(handler middleware.Handler) middleware.Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
start := time.Now()
// Call the next handler
reply, err := handler(ctx, req)
// Log the duration
duration := time.Since(start)
fmt.Printf("Request took: %v\n", duration)
return reply, err
}
}
}
// Usage
func main() {
mw := middleware.Chain(
Timing(),
recovery.Recovery(),
)
// Apply to server
httpSrv := http.NewServer(
http.Middleware(mw),
)
}
Middleware with Configuration
func RateLimiter(maxRequests int) middleware.Middleware {
limiter := rate.NewLimiter(rate.Limit(maxRequests), maxRequests)
return func(handler middleware.Handler) middleware.Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
if !limiter.Allow() {
return nil, errors.New(429, "RATE_LIMIT", "too many requests")
}
return handler(ctx, req)
}
}
}
// Usage
mw := RateLimiter(100) // 100 requests per second
Server vs Client Middleware
Middleware can be applied on both server and client sides:
// Server-side middleware
httpSrv := http.NewServer(
http.Middleware(
recovery.Recovery(),
logging.Server(logger),
),
)
grpcSrv := grpc.NewServer(
grpc.Middleware(
recovery.Recovery(),
logging.Server(logger),
),
)
// Client-side middleware
conn, err := grpc.DialInsecure(
context.Background(),
grpc.WithEndpoint("127.0.0.1:9000"),
grpc.WithMiddleware(
logging.Client(logger),
tracing.Client(),
),
)