Documentation
¶
Overview ¶
Package middleware 提供服务器中间件链构建工具。
Package middleware provides HTTP/gRPC middleware implementations.
Index ¶
- 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 ¶
This section is empty.
Types ¶
type ChainBuilder ¶
type ChainBuilder struct {
// contains filtered or unexported fields
}
ChainBuilder 构建标准中间件链。
中间件顺序（按 Build 输出顺序）：
- Recovery - 捕获 panic，防止服务崩溃
- Tracing - 分布式链路追踪（可选，需调用 WithTrace）
- Logging - 请求/响应日志
- RateLimit - 限流保护（默认启用，可调用 WithoutRateLimit 禁用）
- Validate - Proto 参数校验
- Metrics - 指标收集（可选，需调用 WithMetrics）
使用示例：
import (
"github.com/Servora-Kit/servora/security/authn/jwt"
pkgmw "github.com/Servora-Kit/servora/transport/server/middleware"
)
httpLogger := logger.With(l, "http/server/my-service")
ms := pkgmw.NewChainBuilder(httpLogger).
WithTrace(trace).
WithMetrics(mtc).
Build()
// 业务通过 builtin append 追加 authn/authz/audit wrapper
ms = append(ms, jwt.Server(jwt.WithVerifier(v)), authz.Server(fgaAuth))
自实现 Authenticator 的高级用法（非 jwt 载体或自定义引擎）：
// 单引擎：直接传给 authn.Server
ms = append(ms, authn.Server(myCustomAuth))
// 多引擎并存：用 authn.Named + authn.Multi 包一层
ms = append(ms, authn.Server(authn.Multi(authn.Named("custom", myCustomAuth))))
注意：
- HTTP 和 gRPC 共享同一个 ChainBuilder，通过传入不同的 Logger 区分
- 返回的切片可以通过 builtin `append` 追加业务特定的中间件（如 authn / authz / selector）；ChainBuilder 不提供 fluent `Append` 方法
- 如果需要完全自定义中间件顺序，请不要使用此 Builder，手动构建切片
func NewChainBuilder ¶
func NewChainBuilder(l *slog.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 追加业务特定的中间件（如 authn / authz / audit）。 审计中间件由业务代码通过 audit.Middleware 自行挂载。
func (*ChainBuilder) WithMetrics ¶
func (b *ChainBuilder) WithMetrics(m *telemetry.Metrics) *ChainBuilder
WithMetrics 启用指标收集。
如果 m 为 nil，则跳过 metrics 中间件。 metrics 中间件会记录请求计数和延迟分布。
func (*ChainBuilder) WithTrace ¶
func (b *ChainBuilder) WithTrace(t *corev1.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