Traefik 自定义中间件开发纪要

本篇只讨论HTTP中间件

中间件定义

https://doc.traefik.io/traefik/middlewares/overview/

Attached to the routers, pieces of middleware are a means of tweaking the requests before they are sent to your service (or before the answer from the services are sent to the clients).

实际上与http的中间件一致，核心是实现对http请求的修改和控制。

中间件配置

Traefik自带了许多中间件，可以直接通过配置进行使用。所有的中间件配置都在 http.middlewares 下，比如，下述配置实现了 “addPrefix”中间件（https://doc.traefik.io/traefik/middlewares/http/addprefix/）：

http:
  routers:
    router1:
      service: myService
      middlewares:
        - "foo-add-prefix"
      rule: "Host(`example.com`)"

  middlewares:
    foo-add-prefix:
      addPrefix:
        prefix: "/foo"

  services:
    service1:
      loadBalancer:
        servers:
          - url: "http://127.0.0.1:80"

中间件开发要点

主要是需要编写下述几点：

中间件配置。代码中表现为一个结构体，可以映射到配置文件中。
中间件Handler。作为实现中间件逻辑功能的结构提，实现 http.Handler 接口。
中间件的初始化代码。需要定义中间件的“构造函数”，用于读取配置并实例化中间件的Handler。

接下来，我们按照Traefik的开发思路，一步一步实现上述内容，最终实现一个中间件的开发。

1、定义中间件配置

参照Traefik已有的中间件配置，我们应将我们自己中间件的配置写在：/pkg/config/dynamic/middlewares.go

比如AddPrefix中间件的配置结构体如下：

type AddPrefix struct {
	Prefix string `json:"prefix,omitempty" toml:"prefix,omitempty" yaml:"prefix,omitempty" export:"true"`
}

通过 Tags 来确定其配置项在配置文件中的名称。

除了定义中间件的配置之外，还需要将配置添加到 Middleware 这个结构体中。在配置文件结构中所有的中间件配置都在 http.middlewares 下是因为代码中的配置结构就是如此。Middleware 也在 /pkg/config/dynamic/middlewares.go 中。

AddPrefix中间件在 Middleware 中就有一行：

type Middleware struct {
	AddPrefix         *AddPrefix         `json:"addPrefix,omitempty" toml:"addPrefix,omitempty" yaml:"addPrefix,omitempty" export:"true"`
        ......(其余部分在此省略)
}

同样是通过 Tags 来确定其配置项在配置文件中的名称。

上述结构就确定了中间件在配置文件中的配置：

http:
  middlewares:
    foo-add-prefix:
      addPrefix:
        prefix: "/foo"

其中 “foo-add-prefix” 是中间件的名字，可以自定义，但尽量使其有意义。

2、定义中间件的Handler

中间件的Handler是实际实现中间件功能的部分。按照Traefik已有中间件的代码，应该定义在 /pkg/middlewares/ 这个目录下，作为一个包存在。

我们先在 /pkg/middlewares/ 下创建目录，如：/pkg/middlewares/addprefix/，并在其中创建 add_prefix.go 文件来写代码。

既然是实现Handler，我们应先定义一个 Handler 结构体。结构体属性可以随便定义，看你需要什么就加什么，其中的值可以来自配置文件（初始化的时候可以获得配置项的内容）。其中有必要的选项是一个名为 next 的 http.Handler 类型的属性，其表示接下来要执行的中间件Handler，必不可少。

我们定义的Handler也需要实现 http.Handler 接口，即添加 ServeHTTP 函数。最终的实现如下：

type addPrefix struct {
	next   http.Handler
	prefix string
	name   string
}
func (a *addPrefix) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
	......(具体代码内容省略)
        a.next.ServeHTTP(rw, req)
}

可以看到，我们在实现了中间件自身的功能后，调用了 next.ServeHTTP(rw, req) 。这就是执行下一个中间件的语句。由此可见，我们可以通过此语句的调用与否，决定是否中断中间件的执行过程，来从一定程度上控制中间件的执行逻辑。

3、中间件的初始化

中间件的初始化，分为两部分：

中间件的“构造函数”
在上游初始化代码中调用“构造函数”

“构造函数”

虽然名为“构造函数”但是由于 Golang 没有传统意义上的构造函数，所以我们只是定义一个能够返回中间件Handler 实例的方法。

参照已有的Traefik中间件，此方法名为 New ，定义在中间件的Handler 的同一个包里。比如 AddPrefix 中间件的 New 函数：

// New creates a new handler.
func New(ctx context.Context, next http.Handler, config dynamic.AddPrefix, name string) (http.Handler, error) {
	var result *addPrefix
        ......(中间的初始化代码省略)
	return result, nil
}

New 函数的参数：

ctx：上下文，用于获取日志等通用信息。
next：下一个中间件的 Handler。这个是必要参数，中间件的执行流程必须的内容。
config：就是我们在配置定义中定义的配置实例，其中包含了来自于配置文件的数据。
name：配置文件中，中间件的名字。就是上面配置文件里的 foo-add-prefix 。

实际上，参数是可以自己增删的，因为调用 New 方法的部分，也是我们自己编写，故而我们可以完全控制 New 的定义和调用。不过，在没有什么特殊情况的时候，建议就按上述四个参数来定义，因为其中包含了我们中间件的充分信息。

返回值就是一个 Handler 实例，即我们定义的 addPrefix 结构体（需要注意的是，返回的 http.Handler 类型是个指针）。

调用“构造函数”

调用 New 函数的位置在：/pkg/server/middleware/middlewares.go 文件。其中的 buildConstructor 函数负责初始化所有中间件。

还是以 AddPrefix 中间件举例，它在 buildConstructor 中的代码如下：

func (b *Builder) buildConstructor(ctx context.Context, middlewareName string) (alice.Constructor, error) {
        ......(省略其它代码)
        var middleware alice.Constructor
        // AddPrefix
	if config.AddPrefix != nil {
		middleware = func(next http.Handler) (http.Handler, error) {
			return addprefix.New(ctx, next, *config.AddPrefix, middlewareName)
		}
	}
        ......(省略其它代码)
        return tracing.Wrap(ctx, middleware), nil
}

实际上，我们在此处，主要处理配置文件的数据，步骤如下：

确认中间件配置存在。如果不存在，则跳过初始化，后续会有容错处理。
确认中间件配置可用。如果不可用，可以直接返回 error，错误信息会显示在日志中。
调用中间件的 New 方法，并向 middleware 赋值，注意：middleware是一个函数，定义为 func(next http.Handler) (http.Handler, error) 我们New方法返回的内容作为其返回值即可。

需要注意的

中间件中如果不是处于控制流程的需要，一定要调用 next
尽量遵循Traefik已经有的开发逻辑，比如：代码结构，命名规范等。避免增加无意义的心智负担。

Traefik 自定义 中间件 开发纪要