Manba项目Filter插件机制深度解析

Manba项目Filter插件机制深度解析

manba HTTP API Gateway 项目地址: https://gitcode.com/gh_mirrors/ma/manba

什么是Manba的Filter插件

Manba是一个高性能的API网关项目，其核心功能之一就是通过Filter（过滤器）机制来实现各种业务逻辑。Filter插件允许开发者在不修改Manba核心代码的情况下，通过插件方式扩展网关功能。

Filter插件机制基于Go语言的plugin包实现，为Manba提供了强大的可扩展性。开发者可以编写自定义Filter来处理请求和响应，实现诸如认证、限流、日志记录等各种功能。

Filter的工作原理

Manba的请求处理流程遵循清晰的Filter链式调用模型：

1. 请求预处理阶段：请求首先经过所有Filter的Pre方法
2. 请求转发阶段：将处理后的请求转发到后端服务
3. 响应后处理阶段：后端响应经过所有Filter的Post方法
4. 错误处理阶段：如遇错误则调用PostErr方法

这个流程中有几个关键规则需要注意：

• 如果任何Filter的Pre方法返回错误，处理流程立即终止，直接返回错误响应
• Post方法可以修改响应内容，如返回错误则使用该错误响应
• 当后端返回5xx错误时，会触发Filter的PostErr方法

Filter接口详解

要开发自定义Filter，需要实现以下核心接口：

type Filter interface {
    Name() string               // 返回Filter名称
    Init(cfg string) error      // 初始化Filter
    
    // 预处理方法
    Pre(c Context) (statusCode int, err error)
    
    // 后处理方法
    Post(c Context) (statusCode int, err error)
    
    // 错误处理方法
    PostErr(c Context)
}

Context接口说明

Filter通过Context接口与Manba核心交互，主要提供以下功能：

• 获取请求和响应对象
• 访问API元数据信息
• 记录请求处理时间
• 在Filter间共享数据的属性存储

type Context interface {
    StartAt() time.Time        // 请求开始时间
    EndAt() time.Time          // 请求结束时间
    
    // 获取请求和响应对象
    OriginRequest() *fasthttp.RequestCtx
    ForwardRequest() *fasthttp.Request
    Response() *fasthttp.Response
    
    // 获取API相关信息
    API() *metapb.API
    DispatchNode() *metapb.DispatchNode
    Server() *metapb.Server
    Analysis() *util.Analysis
    
    // 属性存储
    SetAttr(key string, value interface{})
    GetAttr(key string) interface{}
}

BaseFilter基类

Manba提供了BaseFilter作为基础实现，开发者可以继承它并只覆盖需要的方法：

type BaseFilter struct{}

func (f BaseFilter) Pre(c Context) (int, error) {
    return http.StatusOK, nil
}

func (f BaseFilter) Post(c Context) (int, error) {
    return http.StatusOK, nil
}

func (f BaseFilter) PostErr(c Context) {}

开发自定义Filter插件

插件开发步骤

1. 创建一个Go项目，导入Manba的filter包
2. 实现Filter接口
3. 暴露NewExternalFilter函数作为插件入口
4. 编译为.so共享库文件

插件示例代码

package main

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

type MyFilter struct {
    filter.BaseFilter
    // 自定义字段
}

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

func (f *MyFilter) Init(cfg string) error {
    // 解析配置并初始化
    return nil
}

func (f *MyFilter) Pre(c filter.Context) (int, error) {
    // 预处理逻辑
    return http.StatusOK, nil
}

// 必须导出的插件入口函数
func NewExternalFilter() (filter.Filter, error) {
    return &MyFilter{}, nil
}

编译注意事项

由于Go插件机制的限制，需要注意：

1. 插件必须使用与Manba相同的Go版本编译
2. 插件和主程序的依赖版本必须完全一致
3. 避免使用vendor目录，可能导致加载问题
4. 推荐使用Go 1.9.2及以上版本

部署自定义Filter

Manba通过启动参数加载Filter插件，格式为：

名称:插件文件路径:配置文件路径

例如：

--filter JWT:/plugins/jwt.so:/config/jwt.json

Manba默认加载的内置Filter顺序为：

1. WHITELIST（白名单）
2. ANALYSIS（分析）
3. RATE-LIMITING（限流）
4. CIRCUIT-BREAKER（熔断）
5. HTTP-ACCESS（HTTP访问控制）
6. HEADER（头部处理）
7. XFORWARD（X-Forwarded-For处理）
8. VALIDATION（参数验证）

最佳实践建议

1. 保持Filter轻量：Filter执行会影响整体性能，避免复杂计算
2. 合理使用属性存储：通过Context的SetAttr/GetAttr在Filter间传递数据
3. 完善错误处理：提供清晰的错误信息和状态码
4. 考虑并发安全：Filter实例可能被多个goroutine同时使用
5. 详细日志记录：便于问题排查和性能分析

通过理解Manba的Filter插件机制，开发者可以灵活扩展网关功能，满足各种业务场景需求，同时保持核心系统的稳定性和可维护性。

manba HTTP API Gateway 项目地址: https://gitcode.com/gh_mirrors/ma/manba