Serverless Functions
Serverless functions 由两个插件组成：serverless-pre-function 和 serverless-post-function。这些插件允许在函数挂钩的执行阶段的开始和结束时执行用户定义的逻辑。
编写函数提示
Serverless 插件中只允许使用 Lua 函数，不允许使用其他 Lua 代码。
例如，匿名函数是合法的：
return function()
ngx.log(ngx.ERR, 'one')
end
闭包也是合法的：
local count = 1
return function()
count = count + 1
ngx.say(count)
end
但除函数以外的代码是非法的：
local count = 1
ngx.say(count)
示例
以下示例演示了如何在不同场景下配置 serverless-pre-function 和 serverless-post-function 插件。
在阶段前后记录信息
以下示例演示了如何配置 serverless 插件以执行自定义逻辑，在 rewrite 阶段前后将信息记录到错误日志中。
创建一个路由如下：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H 'X-API-KEY: ${ADMIN_API_KEY}' \
-d '{
"id": "serverless-pre-route",
"uri": "/anything",
"plugins": {
"serverless-pre-function": {
// Annotate 1
"phase": "rewrite",
// Annotate 2
"functions" : [
"return function()
ngx.log(ngx.ERR, \"serverless pre function\");
end"
]
},
"serverless-post-function": {
// Annotate 3
"phase": "rewrite",
// Annotate 4
"functions" : [
"return function(conf, ctx)
ngx.log(ngx.ERR, \"match uri \", ctx.curr_req_matched and ctx.curr_req_matched._path);
end"
]
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
❶ 将 serverless pre-function 逻辑挂钩到 rewrite 阶段。
❷ 定义一个 Lua 函数，在错误日志中记录一条 serverless pre function 消息。
❸ 将 serverless post-function 逻辑挂钩到 rewrite 阶段。
❹ 定义一个 Lua 函数，在错误日志中记录匹配的 URI。conf 和 ctx 可以像其他插件一样作为前两个参数传递，其中 conf 是插件配置，ctx 是请求上下文。
发送请求到路由：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应，并在错误日志中看到以下条目：
2024/05/09 15:07:09 [error] 51#51: *3963 [lua] [string "return function() ngx.log(ngx.ERR, "serverles..."]:1: func(): serverless pre function, client: 172.21.0.1, server: _, request: "GET /test HTTP/1.1", host: "127.0.0.1:9080"
2024/05/09 15:16:58 [error] 50#50: *9343 [lua] [string "return function(conf, ctx) ngx.log(ngx.ERR, "..."]:1: func(): match uri /test, client: 172.21.0.1, server: _, request: "GET /test HTTP/1.1", host: "127.0.0.1:9080"
第一个条目由 pre-function 添加，第二个条目由 post-function 添加。
注册自定义变量
以下示例演示了如何使用 serverless 插件注册自定义内置变量，并在日志中使用新创建的变量。
在 Docker 中启动一个示例 rsyslog 服务器：
docker run -d -p 514:514 --name example-rsyslog-server rsyslog/syslog_appliance_alpine
创建一个带有 serverless 函数的服务以注册自定义变量 a6_route_labels，启用日志插件以稍后记录自定义变量，并配置上游：
curl "http://127.0.0.1:9180/apisix/admin/services" -X PUT \
-H 'X-API-KEY: ${ADMIN_API_KEY}' \
-d '{
"id":"srv_custom_var",
"plugins": {
"serverless-pre-function": {
"phase": "rewrite",
// Annotate 1
"functions": [
"return function()
local core = require \"apisix.core\"
core.ctx.register_var(\"a6_route_labels\", function(ctx)
local route = ctx.matched_route and ctx.matched_route.value
if route and route.labels then
return route.labels
end
return nil
end);
end"
]
},
"syslog": {
// Annotate 2
"host" : "172.0.0.1",
"port" : 514,
// Annotate 3
"flush_limit" : 1
}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
}
}
}'
❶ functions: 注册一个自定义变量 a6_route_labels 并从匹配路由的 labels 属性中获取变量值。
❷ host 和 port: 替换为你的 syslog 服务器的地址。
❸ flush_limit: 设置为 1 以立即将日志推送到 syslog 服务器。
接下来，通过配置插件元数据，使用新变量更新所有 syslog 实例的日志格式：
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/syslog" -X PUT \
-H 'X-API-KEY: ${ADMIN_API_KEY}' \
-d '{
"log_format": {
// Annotate 1
"host": "$host",
"client_ip": "$remote_addr",
// Annotate 2
"labels": "$a6_route_labels"
}
}'
❶ $host 和 $remote_addr: [NGINX 变量](#NGINX 变量)。
❷ $a6_route_labels: 自定义变量。
最后，在服务中创建一个路由：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H 'X-API-KEY: ${ADMIN_API_KEY}' \
-d '{
"id":"route_custom_var",
"uri":"/get",
// Annotate 1
"service_id": "srv_custom_var",
// Annotate 2
"labels": {
"key": "test_a6_route_labels"
}
}'
❶ service_id: 对应之前创建的服务。
❷ labels: 要与自定义变量一起记录的路由信息。
要验证变量注册，请发 送请求到路由：
curl "http://127.0.0.1:9080/get"
你应该在 syslog 服务器中看到类似于以下的日志条目：
{
"host":"127.0.0.1",
"route_id":"route_custom_var",
"client_ip":"172.19.0.1",
"labels":{
"key":"test_a6_route_labels"
},
"service_id":"srv_custom_var"
}
这验证了自定义变量已注册，并且它成功记录了路由中的 labels 信息。
修改响应体中的特定字段
以下示例演示了如何使用 serverless 插件从 JSON 响应体中删除特定字段。
在进行删除之前，首先配置如下路由以查看未修改的响应：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H 'X-API-KEY: ${ADMIN_API_KEY}' \
-d '{
"id":"serverless-remove-body-info",
"uri": "/get",
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org": 1
}
}
}'
发送请求到路由：
curl "http://127.0.0.1:9080/get"
你应该看到类似于以下的响应，其中包含你的主机和代理的 IP 信息：
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "127.0.0.1",
"User-Agent": "curl/8.4.0",
"X-Amzn-Trace-Id": "Root=1-663db30f-51448a1b635f2f4338a4fcfc",
"X-Forwarded-Host": "127.0.0.1"
},
"origin": "172.19.0.1, 123.456.122.90",
"url": "http://127.0.0.1/get"
}
要从响应中删除 origin 字段，请使用 serverless 插件更新路由：
curl "http://127.0.0.1:9180/apisix/admin/routes/serverless-remove-body-info" -X PATCH \
-H 'X-API-KEY: ${ADMIN_API_KEY}' \
-d '{
"plugins": {
"serverless-pre-function": {
// Annotate 1
"phase": "header_filter",
"functions" : [
"return function(conf, ctx)
local core = require(\"apisix.core\")
// Annotate 2
core.response.clear_header_as_body_modified()
end"
]
},
"serverless-post-function": {
// Annotate 3
"phase": "body_filter",
"functions" : [
"return function(conf, ctx)
local cjson = require(\"cjson\")
local core = require(\"apisix.core\")
// Annotate 4
local body = core.response.hold_body_chunk(ctx)
if not body then
return
end
// Annotate 5
body = cjson.decode(body)
// Annotate 6
body.origin = nil
body = cjson.encode(body)
ngx.arg[1] = body
end"
]
}
}
}'
❶ 在 header_filter 阶段执行 pre-function。
❷ 使用 clear_header_as_body_modified 方法清除与体相关的响应头（如 Content-Length），以帮助进行响应修改。
❸ 在 body_filter 阶段执行 post-function。
❹ 使用 hold_body_chunk 方法收集响应体。
❺ 解码 JSON 响应体。
❻ 将 origin 字段设置为 nil 以删除该字段。
再次发送请求到路由：
curl "http://127.0.0.1:9080/get"
你应该看到没有 origin 信息的响应：
{
"url":"http://127.0.0.1/get",
"args":{},
"headers":{
"X-Forwarded-Host":"127.0.0.1",
"Host":"127.0.0.1",
"Accept":"*/*",
"User-Agent":"curl/8.4.0",
"X-Amzn-Trace-Id":"Root=1-663db276-1c15276864294d963c6e1755"
}
}
对于更简单的响应修改，例如修改 HTTP 状态码、请求头或整个响应体，请使用 response-rewrite 插件。