Documentation
¶
Overview ¶
Package middleware 提供服务器中间件链构建工具。
Package middleware provides HTTP/gRPC middleware implementations.
Index ¶
- func GetAllowedOrigins(corsConfig *conf.CORS) []string
- func IsEnabled(corsConfig *conf.CORS) bool
- func Middleware(corsConfig *conf.CORS) func(http.Handler) http.Handler
- func NewTokenContext(ctx context.Context, token string) context.Context
- func TokenFromContext(ctx context.Context) (string, bool)
- type ChainBuilder
- type MatcherMode
- type WhiteList
- func (w *WhiteList) Add(ops ...string) *WhiteList
- func (w *WhiteList) Clear() *WhiteList
- func (w *WhiteList) IsWhitelisted(op string) bool
- func (w *WhiteList) MatchFunc() selector.MatchFunc
- func (w *WhiteList) Merge(other *WhiteList) *WhiteList
- func (w *WhiteList) Set(ops []string) *WhiteList
- func (w *WhiteList) Snapshot() []string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetAllowedOrigins ¶
GetAllowedOrigins 获取配置的允许源列表（用于日志等场景）
func Middleware ¶
Middleware 创建 CORS 中间件，直接接受 conf.CORS 配置 如果 corsConfig 为 nil 或 Enable 为 false，返回透传中间件
func NewTokenContext ¶
NewTokenContext 将原始 Bearer token 存储到 context 中。
Types ¶
type ChainBuilder ¶
type ChainBuilder struct {
// contains filtered or unexported fields
}
ChainBuilder 构建标准中间件链。
中间件顺序（按 Build 输出顺序）：
- Recovery - 捕获 panic，防止服务崩溃
- Tracing - 分布式链路追踪（可选，需调用 WithTrace）
- Logging - 请求/响应日志
- RateLimit - 限流保护（默认启用，可调用 WithoutRateLimit 禁用）
- Validate - Proto 参数校验
- Metrics - 指标收集（可选，需调用 WithMetrics）
使用示例：
httpLogger := logger.With(l, "http/server/my-service")
ms := middleware.NewChainBuilder(httpLogger).
WithTrace(trace).
WithMetrics(mtc).
Build()
ms = append(ms, authMiddleware...)
注意：
- HTTP 和 gRPC 共享同一个 ChainBuilder，通过传入不同的 Logger 区分
- 返回的切片可以通过 append 追加业务特定的中间件（如 auth、selector）
- 如果需要完全自定义中间件顺序，请不要使用此 Builder，手动构建切片
func NewChainBuilder ¶
func NewChainBuilder(l log.Logger) *ChainBuilder
NewChainBuilder 创建中间件链构建器。
logger 参数是必须的，用于 logging 中间件。 建议使用 logger.With(l, "http/server/xxx") 或 logger.With(l, "grpc/server/xxx") 来区分协议。
func (*ChainBuilder) Build ¶
func (b *ChainBuilder) Build() []middleware.Middleware
Build 构建并返回中间件切片。
中间件按以下固定顺序添加：
- Recovery - 必须第一个，捕获所有后续中间件的 panic
- Tracing - 在 logging 之前，确保日志可以关联 trace ID
- Logging - 记录请求/响应
- RateLimit - 在业务逻辑之前进行限流
- Validate - Proto 参数校验
- Metrics - 记录请求指标
返回的切片可以通过 append 追加业务特定的中间件。
func (*ChainBuilder) WithMetrics ¶
func (b *ChainBuilder) WithMetrics(m *telemetry.Metrics) *ChainBuilder
WithMetrics 启用指标收集。
如果 m 为 nil，则跳过 metrics 中间件。 metrics 中间件会记录请求计数和延迟分布。
func (*ChainBuilder) WithTrace ¶
func (b *ChainBuilder) WithTrace(t *conf.Trace) *ChainBuilder
WithTrace 启用分布式链路追踪。
如果 t 为 nil 或 t.Endpoint 为空，则跳过 tracing 中间件。 这允许在未配置 trace endpoint 的环境中优雅降级。
func (*ChainBuilder) WithoutRateLimit ¶
func (b *ChainBuilder) WithoutRateLimit() *ChainBuilder
WithoutRateLimit 禁用限流中间件。
默认情况下限流是启用的，这是生产环境的推荐配置。 仅在以下场景考虑禁用：
- 本地开发/测试环境
- 内部服务间调用（已有上游限流）
- 性能压测
type MatcherMode ¶
type MatcherMode int
MatcherMode controls matching strategy
const ( // Exact matches the full operation string or method-only fallback Exact MatcherMode = iota // Prefix matches any operation with given prefix Prefix )
type WhiteList ¶
type WhiteList struct {
// contains filtered or unexported fields
}
WhiteList holds whitelist data and provides selector helpers. Operations in the whitelist will SKIP the auth middleware.
func NewWhiteList ¶
func NewWhiteList(mode MatcherMode, ops ...string) *WhiteList
NewWhiteList creates a WhiteList with optional initial ops and mode.
func (*WhiteList) IsWhitelisted ¶
IsWhitelisted returns true if operation is whitelisted
func (*WhiteList) MatchFunc ¶
MatchFunc returns a selector.MatchFunc that returns true to execute middleware. It will return false (skip middleware) when op is whitelisted.
Source Files