如何为 caddy 添写自定义插件
项目地址：https://github.com/yhyddr/quicksilver/tree/master/gosample/caddy-plugin
<a name="RVxtJ"></a>
前言
Caddy附带一个HTTP服务器，但是你可以实现其他服务器类型并将它们插入Caddy中。其他类型的服务器可以是SSH、SFTP、TCP、内部使用的其他东西等等。<br />
<br />对于Caddy来说，服务器的概念是任何可以Listen()和Serve()的东西。这意味着什么、如何运作都取决于你。你可以自由地发挥你的创造力去使用它。<br />
<br />那么怎样去扩展 Caddy 呢？<br />不同的服务器类型，可以根据自己的需要定制不同的插件。我们在这里，通过添加最简单的不做任何事的插件，来熟悉如何扩展 Caddy 服务器。<br />
<a name="bMjmJ"></a>
Plugin for HTTP
我们会一步一步构建出一个 HTTP Plugin 的框架，到时候你只需要填充自己处理逻辑即可！那还等什么，让我们开始吧。<br />
<br />构建一个 HTTP Plugin ，代码部分仅需要两步，注意事项也有两个。<br />
<a name="hyj6K"></a>
创建一个 Go Package
首先为 caddy 创建一个 插件的 Go Package ，你可以新建一个文件夹达到这个效果。比如
├── caddy-plugin
│ ├── gizmo.go
│ └── setup.go
这里分为了两个 Go 文件，接下来详细讲每一个 Go 文件的作用。
<a name="nmOnZ"></a>
代码🀙：注册 caddy plugin
首先我们看到 setup.go
<a name="HXIC2"></a>
setup.go
创建 setup.go 文件并写入以下信息
import "github.com/mholt/caddy"
func init() {
caddy.RegisterPlugin("gizmo", caddy.Plugin{
ServerType: "http",
Action: setup,
})
}
这里是 建立了一个新插件，caddy 包来做到插件的注册。
- 注意到 “gizmo” 这是 插件的名字，同时也是指令的名字，请为你的插件取一个独一无二的名字吧。（注意：名字需要是单词小写哦。）
- 因为是针对 HTTP 服务器的插件，所以 ServerType 字段值是 “http”
- 另一个设置的字段是 setup ，实际上，我们接下来会填充这个函数的逻辑。它的作用就是将我们插件的处理逻辑安装到 Caddy 中。
<a name="6sJEa"></a>
setup
现在我们来实现 setup 函数 <br />
<br />假如我们希望在Caddyfile中有一行这样的行：
gizmo foobar
<br />我们可以得到刚才所说的 c.Next() 第一个参数(“foobar”)的值，如下所示：
for c.Next() { // skip the directive name
if !c.NextArg() { // expect at least one value
return c.ArgErr() // otherwise it's an error
}
value := c.Val() // use the value
}
我们首先注意到， c.Next() 是真正我们读取 caddyfile 逻辑的地方，caddyfile 就是配置服务器的配置文件的名字。我们注意到，这里的操作实际上是使用 caddy.Controller 来实现的。它的存在 让编写插件的开发者只需要关注如何使用它来执行你的命令，这是一项优秀的设计，有兴趣可以看我的源码阅读部分关于 Plugin 的具体实现。
在 Caddy 解析了Caddyfile之后，它将迭代每个指令名(按照服务器类型规定的顺序)，并在每次遇到指令名时调用指令的setup函数。setup函数的职责是解析指令的标识并配置自己。<br />
<br />您可以通过遍历c.Next()来解析为指令提供的标识，只要有更多的标识需要解析，那么c.Next()就会返回true。由于一个指令可能出现多次，你必须遍历c.Next()以获得所有出现的指令并使用第一个标识(即指令名)。<br />有关caddyfile包，请参阅godoc以了解如何更充分地使用分发器，并查看任何其他现有插件。
<a name="fzu7b"></a>
代码 🀚：Handler 实现
<a name="iyY6W"></a>
gizmo.go：
查看httpserver包的godoc。最重要的两种类型是httpserver.Handler和httpserver.Middleware。
-
Handler是一个处理HTTP请求的函数。 -
Middleware是一种连接Handler的方式。
Caddy将负责为你设置HTTP服务器的所有簿记(bookkeeping)工作，但是你需要实现这两种类型。<br />
<a name="sPXzP"></a>
Struct
httpserver.Handler是一个几乎和http.Handler完全一样的接口，除了ServeHTTP方法返回(int, error)。<br />这个方法签名遵循Go语言博客中关于与中间件相关的错误处理的建议。<br />int是HTTP状态码，error应该被处理和/或记录。有关这些返回值的详细信息，请参阅godoc。<br />
<br />Handler通常是一个结构体，至少包含一个Next字段，用来链接下一个Handler：
type gizmoHandler struct {
next httpserver.Handler
}
<br />除了这些之外，可以添加一些自己使用的参数，考虑 grpc 的 plugin 实现，解释放在代码块中的注释中
type server struct {
backendAddr string // 监听地址
next httpserver.Handler // 作为中间件必须有的字段
backendIsInsecure bool // 是否启用 Insecure() 选项，是 grpc 的一项配置
backendTLS *tls.Config // 关于 TLS 的使用的证书文件
wrappedGrpc *grpcweb.WrappedGrpcServer // 通过 grpcweb 的 协议实现 HTTP 请求等
}
这就是参考的一个 字段的使用。可以根据自己的需要，调整在 caddyfile 中读取的指令应该如何配置。
<a name="K5EDA"></a>
httpserver.Handler
为了实现httpserver.Handler接口，我们需要编写一个名为ServeHTTP的方法。这个方法是实际的处理程序函数，除非它自己处理完毕请求，否则它应该调用链中的下一个Handler：即使用 g.next.ServeHTTP(w, r)
func (g gizmoHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error) {
return g.next.ServeHTTP(w, r)
}
这里只是框架，具体逻辑可以自行填充，可以参照已有的 Plugin 实现。<br />
<a name="RiOqc"></a>
第二步，注册 Middleware
然后我们可以进行第二步，将这个 handler 注册到整个 caddy 的 http 调用链上。
我们需要回到 刚才的 setup.go 文件中，<br />回到设置函数。你刚刚解析了标识并使用所有适当的配置设置了中间件处理程序：
func setup(c *caddy.Controller) error {
g := gizmoHandler{} // 用来实现 HTTPHandler 的 next 的结构，用来构建 中间件。也可以加入一些自己的字段
for c.Next() {
// 获取配置文件，并处理
}
// 现在开始注册中间件
httpserver.GetConfig(c).AddMiddleware(func(next httpserver.Handler) httpserver.Handler {
g.next = next
return g
})
return nil
}
这样，代码部分就全部完成了。
下面我们查看需要注意的事项。实际上是关乎于怎样将写好的插件集成在 caddy 中。
<a name="WTOo3"></a>
排序
要做的事情是告诉服务器类型在进程的什么地方执行你的指令。这一点很重要，因为其他指令可能会设置你所依赖的更原始的配置，因此执行指令的顺序不能是随意的。<br />
<br />每个服务器类型都有一个字符串列表，其中每个项都是一个指令的名称。例如，查看HTTP服务器支持的指令列表。将指令添加到适当的位置。<br />
<a name="c75IF"></a>
插入你的插件
最后，不要忘记导入你的插件包！Caddy必须导入插件来注册并执行它。这通常是在run.go的import部分的尾部完成的：<br />
_ "your/plugin/package/here"
请注意：包名前的_是必需的。
<a name="1aHEv"></a>
总结
就是这样！可以用你的插件来构建caddy，然后用你的新指令写一个Caddyfile来查看它的运行情况。<br />虽然还没完善的她只是一个框架，还不能做任何事情，但是她很简单，很美不是吗？她能帮你做任何事情。因为记住 caddy 的服务器是设置的非常抽象的。她就想 net 包中 conn 一样完美的 接口设计，能够兼容和扩展任何 需要 listen() 和 serve() 的东西，只要你的创造力足够。<br />
<br />现在，发挥你的想象力，填充这个框架吧，可以参考我的简单项目地址。<br />项目地址：https://github.com/yhyddr/quicksilver/tree/master/gosample/caddy-plugin<br />
<br />同时记得多多寻找别人的插件实现方式，你会找到让你耳目一新的实现。https://www.yuque.com/fengyfei/idznuk/sumapn<br />
<a name="jCZ1q"></a>
参考
image.png
<br />我刚编辑过哦<br />https://github.com/caddyserver/caddy/wiki/Writing-a-Plugin:-Directives<br />https://github.com/caddyserver/caddy/wiki/Writing-a-Plugin:-Server-Type<br />https://github.com/caddyserver/caddy/wiki/Writing-a-Plugin:-HTTP-Middleware
网友评论