Easegress项目：从v1.x到v2.0的过滤器迁移指南

Easegress项目：从v1.x到v2.0的过滤器迁移指南

easegress A Cloud Native traffic orchestration system 项目地址: https://gitcode.com/gh_mirrors/eas/easegress

概述

Easegress v2.0版本带来了重大架构升级，包括协议无关的管道设计、多请求/响应支持等新特性。这些改进虽然提升了系统的灵活性和扩展性，但也导致了与v1.x版本的不兼容性。本文将详细介绍如何将v1.x版本的过滤器迁移到v2.0版本，以Mock过滤器为例，提供完整的迁移路线图。

迁移步骤详解

1. 定义过滤器类型(Kind)

在v2.0中，每个过滤器都需要定义一个Kind对象，它包含了过滤器的元信息：

var kind = &filters.Kind{
    Name:        Kind,  // 过滤器类型名称
    Description: "Mock mocks the response.",  // 功能描述
    Results:     []string{resultMocked},  // 可能返回的结果
    DefaultSpec: func() filters.Spec {
        return &Spec{}  // 默认规格创建函数
    },
    CreateInstance: func(spec filters.Spec) filters.Filter {
        return &Mock{spec: spec.(*Spec)}  // 实例创建函数
    },
}

关键点说明：

• Description字段通常直接取自v1.x中的Description()方法
• Results字段来自v1.x中的Results()方法返回的切片
• DefaultSpec函数体通常与v1.x中的DefaultSpec()方法相同
• CreateInstance函数需要创建新实例并设置spec字段

2. 移除过时方法

完成Kind定义后，可以安全移除以下不再需要的方法：

• Description()
• Results()
• DefaultSpec()

3. 更新过滤器及其规格定义

规格(Spec)结构体更新：

type Spec struct {
    filters.BaseSpec `yaml:",inline"`  // 新增基类
    Rules []*Rule `yaml:"rules"`       // 原有字段
}

过滤器结构体更新：

type Mock struct {
    // filterSpec *httppipeline.FilterSpec  // 移除该字段
    spec *Spec  // 保留规格引用
}

4. 添加Name方法

新增Name()方法返回过滤器实例名称：

func (m *Mock) Name() string {
    return m.spec.Name()  // 从规格中获取名称
}

5. 更新Kind方法

v1.x中该方法返回类型名称字符串，v2.0中需要返回完整的Kind对象：

func (m *Mock) Kind() *filters.Kind {
    return kind  // 返回第一步定义的kind对象
}

6. 更新Init和Inherit方法

方法签名变更：

func (m *Mock) Init()
func (m *Mock) Inherit(previousGeneration filters.Filter)

重要变更：

• 规格已在创建时设置，无需在Init中重复处理
• Inherit中不再需要调用previousGeneration.Close()
• 通过m.spec直接访问规格信息

7. 更新Handle方法

方法签名变更：

func (m *Mock) Handle(ctx *context.Context) string

关键修改：

• 上下文类型从context.HTTPContext变为*context.Context
• 不再使用责任链模式，直接返回结果而非调用ctx.CallNextHandler()

8. 清理导入包

移除不再需要的httppipeline包导入：

// 移除该导入
// "github.com/megaease/easegress/v2/pkg/object/httppipeline"

9. 其他代码更新

请求/响应访问方式变更：

• ctx.Request() 需要替换为：

  • ctx.GetInputRequest()
  • ctx.GetOutputRequest()
  • ctx.SetInputRequest()
  • ctx.SetOutputRequest()

• 对于协议特定请求，需要类型断言：

  req := ctx.GetInputRequest().(*httpprot.Request)
  

迁移注意事项

1. 协议处理：v2.0支持多协议，确保你的过滤器能正确处理不同类型的请求

2. 状态管理：如果过滤器维护状态，需要在Inherit中正确处理状态转移

3. 性能考量：v2.0的架构变化可能影响性能特征，建议进行基准测试

4. 错误处理：新的上下文API可能有不同的错误处理机制

5. 测试覆盖：迁移后应全面测试过滤器的各种使用场景

常见问题解决

1. 类型转换问题：当处理特定协议请求时，确保类型断言安全

   if req, ok := ctx.GetInputRequest().(*httpprot.Request); ok {
       // 处理HTTP请求
   }
   

2. 多响应处理：v2.0支持多响应，确保你的过滤器能正确处理这种情况

3. 生命周期管理：注意资源初始化和清理的时机变化

总结

将过滤器从Easegress v1.x迁移到v2.0需要系统性地更新代码结构，但大多数变更都是机械性的。理解v2.0的新架构理念是关键，特别是协议无关性和请求/响应处理模型的变化。完成上述步骤后，你的过滤器将能充分利用v2.0的新特性，同时保持原有的功能特性。

对于复杂的过滤器实现，可能需要额外的适配工作。建议参考Easegress官方提供的其他v2.0过滤器实现作为范例，确保迁移的正确性和完整性。

easegress A Cloud Native traffic orchestration system 项目地址: https://gitcode.com/gh_mirrors/eas/easegress