Manba插件系统深度解析：从JWT认证到自定义过滤器的终极指南

焦滨庄Jessie

930人浏览 · 2026-03-24 00:34:13

焦滨庄Jessie · 2026-03-24 00:34:13 发布

Manba插件系统深度解析：从JWT认证到自定义过滤器的终极指南

【免费下载链接】manba HTTP API Gateway 项目地址: https://gitcode.com/gh_mirrors/ma/manba

Manba是一个功能强大的HTTP API网关，其插件系统提供了灵活的扩展能力，让开发者可以轻松实现JWT认证、限流、缓存等关键功能。本文将深入解析Manba插件系统的核心架构，从JWT认证实现到自定义过滤器的开发，为您提供完整的插件开发指南。

为什么选择Manba插件系统？

Manba的插件系统采用过滤器（Filter）机制，每个过滤器都是一个独立的处理单元，可以在请求转发前后执行特定的逻辑。这种设计让系统具备了极高的可扩展性，您可以根据业务需求自由组合各种过滤器。

默认过滤器配置在 pkg/proxy/filter.go 中实现，系统内置了白名单、黑名单、缓存、流量分析、限流、熔断、HTTP访问控制、请求头处理、X-Forwarded-*头处理、参数验证和JavaScript插件扩展等多种过滤器。

JWT认证过滤器深度剖析

JWT（JSON Web Token）是现代API认证的黄金标准，Manba通过JWT过滤器实现了完整的认证方案。JWT过滤器的完整实现在 pkg/proxy/filter_jwt.go 中。

JWT过滤器的核心功能

令牌验证：支持HS256、HS384、HS512等多种签名算法
多位置获取：可以从Header、Query参数、Cookie中获取JWT令牌
Redis集成：支持与Redis集成进行令牌存储和验证
CSRF保护：提供CSRF令牌双重验证机制
令牌续期：支持自动续期和Redis中的令牌更新

JWT配置示例

JWT过滤器通过JSON配置文件进行配置，支持以下关键参数：

{
  "secret": "your_jwt_secret_key",
  "method": "HS256",
  "tokenLookup": "header:Authorization",
  "authSchema": "Bearer",
  "csrfHeaderName": "X-CSRF-Token",
  "actions": [
    {
      "method": "token_in_redis",
      "params": {
        "prefix": "jwt:"
      }
    }
  ]
}

认证流程详解

当请求到达Manba网关时，JWT过滤器的处理流程如下：

令牌提取：根据配置从Header、Query或Cookie中提取JWT令牌
签名验证：使用配置的密钥和算法验证令牌签名
Redis验证：检查令牌是否在Redis中（如果配置了Redis集成）
CSRF验证：验证CSRF令牌（如果需要）
字段提取：从JWT Claims中提取用户信息并添加到请求头
令牌续期：自动续期即将过期的令牌

自定义过滤器开发指南

过滤器接口定义

所有过滤器都必须实现 pkg/filter/filter.go 中定义的Filter接口：

type Filter interface {
    Name() string
    Init(cfg string) error
    Pre(c Context) (statusCode int, err error)
    Post(c Context) (statusCode int, err error)
    PostErr(c Context, code int, err error)
}

开发自定义过滤器的5个步骤

1. 创建过滤器结构体

package proxy

import (
    "github.com/fagongzi/gateway/pkg/filter"
)

type CustomFilter struct {
    filter.BaseFilter
    // 添加您的配置字段
}

2. 实现Name方法

func (f *CustomFilter) Name() string {
    return "CustomFilter"
}

3. 实现Init方法

func (f *CustomFilter) Init(cfg string) error {
    // 解析配置，初始化资源
    return nil
}

4. 实现Pre方法（请求前处理）

func (f *CustomFilter) Pre(c filter.Context) (statusCode int, err error) {
    // 在请求转发前执行逻辑
    return filter.BaseFilter.Pre(c)
}

5. 实现Post方法（响应后处理）

func (f *CustomFilter) Post(c filter.Context) (statusCode int, err error) {
    // 在请求转发后执行逻辑
    return filter.BaseFilter.Post(c)
}

过滤器上下文详解

过滤器上下文提供了丰富的API访问能力：

OriginRequest()：获取原始HTTP请求
ForwardRequest()：获取转发到后端的请求
Response()：获取后端响应
API()：获取当前API配置信息
SetAttr()/GetAttr()：在过滤器间传递数据

内置过滤器功能详解

1. 限流过滤器（FilterRateLimiting）

限流过滤器基于令牌桶算法实现，可以防止API被过度调用。配置参数包括：

最大QPS限制
突发请求处理策略
限流后的响应策略

2. 缓存过滤器（FilterCaching）

缓存过滤器可以显著提升API响应速度，支持：

基于请求路径和参数的缓存键生成
TTL配置
缓存失效策略
内存和Redis缓存后端

3. 熔断器过滤器（FilterCircuitBreaker）

熔断器保护后端服务免受过载影响：

基于错误率的熔断触发
半开状态自动恢复
超时控制和重试机制

4. 白名单/黑名单过滤器

提供基于IP、用户ID等维度的访问控制：

动态更新黑白名单
CIDR格式的IP范围支持
基于用户角色的访问控制

插件配置与管理

Web管理界面

Manba提供了直观的Web管理界面，您可以在其中轻松配置和管理所有插件：

通过Web界面，您可以：

查看API、集群、服务器、路由和插件的统计信息
动态启用/禁用过滤器
实时调整过滤器配置
监控过滤器性能指标

配置文件管理

除了Web界面，Manba还支持通过配置文件管理插件：

全局配置文件：在 pkg/proxy/cfg.go 中定义
API级别配置：每个API可以单独配置过滤器链
动态热更新：支持不重启服务的配置更新

最佳实践与性能优化

1. 过滤器链优化

顺序安排：将高频检查的过滤器放在前面（如白名单检查）
资源重用：在Init方法中初始化昂贵资源
并发安全：确保过滤器实例是线程安全的

2. JWT性能优化

使用HS256算法：相比RS256有更好的性能
合理设置TTL：平衡安全性和用户体验
Redis连接池：合理配置连接池参数减少连接开销

3. 监控与日志

集成Prometheus：通过 pkg/util/metric_push.go 推送指标
结构化日志：使用context传递请求ID实现全链路追踪
性能分析：利用 pkg/util/analysis.go 进行性能分析

实战案例：构建自定义认证过滤器

假设我们需要为内部系统开发一个基于API Key的认证过滤器：

package proxy

import (
    "strings"
    "github.com/fagongzi/gateway/pkg/filter"
    "github.com/valyala/fasthttp"
)

type APIKeyFilter struct {
    filter.BaseFilter
    validKeys map[string]bool
}

func (f *APIKeyFilter) Name() string {
    return "APIKeyFilter"
}

func (f *APIKeyFilter) Init(cfg string) error {
    // 从配置文件或数据库加载有效的API Keys
    f.validKeys = make(map[string]bool)
    keys := strings.Split(cfg, ",")
    for _, key := range keys {
        f.validKeys[strings.TrimSpace(key)] = true
    }
    return nil
}

func (f *APIKeyFilter) Pre(c filter.Context) (int, error) {
    apiKey := string(c.OriginRequest().Request.Header.Peek("X-API-Key"))
    if apiKey == "" || !f.validKeys[apiKey] {
        return fasthttp.StatusUnauthorized, nil
    }
    return f.BaseFilter.Pre(c)
}