Documentation
¶
Overview ¶
包 middleware 提供 LLM 请求处理的中间件链机制，支持在请求发送到 上游模型服务之前和响应返回之后插入可组合的横切逻辑。
概述 ¶
本包采用经典的 Handler / Middleware 函数式组合模式，将日志、超时、 重试、缓存、限流、追踪等横切关注点从业务逻辑中解耦。同时提供 RequestRewriter 改写器链，用于在请求发送前进行参数清理与转换。
核心接口 ¶
- Handler：func(ctx, *ChatRequest) (*ChatResponse, error)， 表示一个请求处理函数。
- Middleware：func(Handler) Handler，表示一个中间件装饰器。
- Chain：中间件链，支持 Use / UseFront / Then 组合与执行。
- RequestRewriter：请求改写器接口，包含 Rewrite 与 Name 方法。
- RewriterChain：改写器链，按顺序执行多个 RequestRewriter。
- MetricsCollector / Cache / BlockingRateLimiter / Validator： 各中间件依赖的辅助接口。
主要能力 ¶
- 日志记录：LoggingMiddleware 记录请求模型、耗时与 Token 用量。
- 超时控制：TimeoutMiddleware 为请求添加 context 超时。
- 自动重试：RetryMiddleware 支持指数退避重试。
- 响应缓存：CacheMiddleware 基于 Cache 接口缓存响应。
- 速率限制：RateLimitMiddleware 基于阻塞式限流器等待。
- 指标采集：MetricsMiddleware 收集请求耗时与 Token 统计。
- 分布式追踪：TracingMiddleware 集成 Tracer 接口。
- Panic 恢复：RecoveryMiddleware 捕获 panic 并转为错误。
- 请求验证：ValidatorMiddleware 在处理前校验请求合法性。
- 请求改写：EmptyToolsCleaner 等改写器清理无效参数。
Index ¶
- type BlockingRateLimiter
- type Cache
- type Chain
- type EmptyToolsCleaner
- type Handler
- type MetricsCollector
- type Middleware
- func CacheMiddleware(cache Cache) Middleware
- func HeadersMiddleware(headers map[string]string) Middleware
- func LoggingMiddleware(logger func(format string, args ...any)) Middleware
- func MetricsMiddleware(collector MetricsCollector) Middleware
- func RateLimitMiddleware(limiter BlockingRateLimiter) Middleware
- func RecoveryMiddleware(onPanic func(any)) Middleware
- func RetryMiddleware(maxRetries int, backoff time.Duration) Middleware
- func TimeoutMiddleware(timeout time.Duration) Middleware
- func TracingMiddleware(tracer llmpkg.Tracer) Middleware
- func TransformMiddleware(reqTransform func(*llmpkg.ChatRequest), ...) Middleware
- func ValidatorMiddleware(validators ...Validator) Middleware
- type PanicError
- type RequestRewriter
- type RewriterChain
- type Validator
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BlockingRateLimiter ¶
BlockingRateLimiter 定义阻塞式速率限制接口. 与 llm.RateLimiter（非阻塞式 Allow/AllowN/Reset）不同， BlockingRateLimiter 在超出速率时阻塞等待，适用于中间件链场景.
type Cache ¶
type Cache interface {
Key(req *llmpkg.ChatRequest) string
Get(key string) (*llmpkg.ChatResponse, bool)
Set(key string, resp *llmpkg.ChatResponse)
}
Cache 定义缓存接口.
type Chain ¶
type Chain struct {
// contains filtered or unexported fields
}
Chain 表示中间件链.
type EmptyToolsCleaner ¶
type EmptyToolsCleaner struct{}
EmptyToolsCleaner 空工具列表清理器 当请求的 Tools 为空时，清除 ToolChoice 字段 避免上游 API 返回 400 错误（OpenAI 不允许空 tools 数组时设置 tool_choice）
func NewEmptyToolsCleaner ¶
func NewEmptyToolsCleaner() *EmptyToolsCleaner
NewEmptyToolsCleaner 创建空工具清理器
func (*EmptyToolsCleaner) Rewrite ¶
func (r *EmptyToolsCleaner) Rewrite(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatRequest, error)
Rewrite 执行改写
type Handler ¶
type Handler func(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatResponse, error)
Handler 处理一个请求并返回一个响应.
type MetricsCollector ¶
type MetricsCollector interface {
RecordRequest(model string, duration time.Duration, success bool)
RecordTokens(model string, tokens int)
}
MetricsCollector 定义指标收集接口.
type Middleware ¶
Middleware 将处理器包裹并添加额外功能.
func HeadersMiddleware ¶
func HeadersMiddleware(headers map[string]string) Middleware
HeadersMiddleware 添加自定义头到请求元数据.
func LoggingMiddleware ¶
func LoggingMiddleware(logger func(format string, args ...any)) Middleware
LoggingMiddleware 记录请求/响应详情.
func MetricsMiddleware ¶
func MetricsMiddleware(collector MetricsCollector) Middleware
MetricsMiddleware 收集请求的指标.
func RateLimitMiddleware ¶
func RateLimitMiddleware(limiter BlockingRateLimiter) Middleware
RateLimitMiddleware 应用速率限制.
func RecoveryMiddleware ¶
func RecoveryMiddleware(onPanic func(any)) Middleware
RecoveryMiddleware 从 panic 中恢复.
func RetryMiddleware ¶
func RetryMiddleware(maxRetries int, backoff time.Duration) Middleware
RetryMiddleware 重试失败的请求. 只重试可重试的错误（*types.Error 且 Retryable=true），不可重试的错误立即返回。
func TimeoutMiddleware ¶
func TimeoutMiddleware(timeout time.Duration) Middleware
TimeoutMiddleware 对请求添加超时.
func TracingMiddleware ¶
func TracingMiddleware(tracer llmpkg.Tracer) Middleware
TracingMiddleware 添加分布式追踪.
func TransformMiddleware ¶
func TransformMiddleware(reqTransform func(*llmpkg.ChatRequest), respTransform func(*llmpkg.ChatResponse)) Middleware
TransformMiddleware 转换请求/响应.
func ValidatorMiddleware ¶
func ValidatorMiddleware(validators ...Validator) Middleware
ValidatorMiddleware 在处理前对请求进行验证.
type PanicError ¶
type PanicError struct {
Value any
}
RecoveredPanic 表示已恢复的 panic.
func (*PanicError) Error ¶
func (e *PanicError) Error() string
type RequestRewriter ¶
type RequestRewriter interface {
// Rewrite 改写请求
// 返回改写后的请求和错误（如果改写失败）
Rewrite(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatRequest, error)
// Name 返回改写器名称（用于日志和调试）
Name() string
}
RequestRewriter 请求改写器接口 用于在请求发送到上游 API 之前进行参数清理和转换
type RewriterChain ¶
type RewriterChain struct {
// contains filtered or unexported fields
}
RewriterChain 改写器链 按顺序执行多个改写器
func NewRewriterChain ¶
func NewRewriterChain(rewriters ...RequestRewriter) *RewriterChain
NewRewriterChain 创建改写器链
func (*RewriterChain) AddRewriter ¶
func (c *RewriterChain) AddRewriter(rewriter RequestRewriter)
AddRewriter 动态添加改写器
func (*RewriterChain) Execute ¶
func (c *RewriterChain) Execute(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatRequest, error)
Execute 执行改写器链 按顺序执行所有改写器，任何一个失败则中断并返回错误
func (*RewriterChain) GetRewriters ¶
func (c *RewriterChain) GetRewriters() []RequestRewriter
GetRewriters 获取所有改写器（用于调试）
type Validator ¶
type Validator interface {
Validate(req *llmpkg.ChatRequest) error
}
Validator 定义请求验证接口.
Source Files