Apache APISIX 中使用 response-rewrite 插件修改响应体字段

在 API 网关的实际应用中，我们经常需要对上游服务的响应进行修改和增强。Apache APISIX 提供了多种方式来实现这一需求，其中 response-rewrite 插件和 serverless 函数是两种常用的解决方案。

响应体修改的需求场景

在实际业务中，我们可能需要：

1. 保留原始响应体的大部分内容
2. 修改某些特定字段的值
3. 添加新的字段到响应体中
4. 使用 Nginx 变量（如 $http_*）的值来填充新字段

这种需求常见于 API 标准化、添加追踪信息、注入环境相关数据等场景。

解决方案对比

response-rewrite 插件

response-rewrite 插件是 APISIX 内置的用于修改响应头和响应体的插件。它简单易用，适合简单的响应修改场景。

serverless 函数

对于更复杂的响应体修改需求，可以使用 serverless 函数（特别是 serverless-post-function）。这种方式提供了完全的灵活性，可以在 Lua 代码中自由处理响应体。

使用 serverless 函数修改响应体

下面是一个完整的示例，展示如何使用 serverless-post-function 在 body_filter 阶段修改响应体：

{
  "uri": "/get",
  "plugins": {
    "serverless-post-function": {
      "phase": "body_filter",
      "functions": [
        "return function (conf, ctx)
          local core = require(\"apisix.core\")
          local body = core.response.hold_body_chunk(ctx)
          -- 将响应体解析为 Lua table
          local data = core.json.decode(body)
          
          -- 修改现有字段
          if data and data.some_field then
            data.some_field = \"new value\"
          end
          
          -- 添加新字段
          data.new_field = ngx.var.http_user_agent
          data.another_field = ngx.var.remote_addr
          
          -- 将修改后的数据设置回响应体
          ngx.arg[1] = core.json.encode(data)
          ngx.arg[2] = true
        end"
      ]
    }
  },
  "upstream": {
    "nodes": {
      "httpbin.org:80": 1
    },
    "type": "roundrobin"
  }
}

实现细节解析

1. body_filter 阶段：这是处理响应体的最佳阶段，此时我们已经获得了完整的响应内容。

2. hold_body_chunk：APISIX 核心方法，用于获取完整的响应体内容。

3. JSON 处理：使用 core.json 模块解码和编码 JSON 数据，确保正确处理各种 JSON 格式。

4. Nginx 变量：可以通过 ngx.var 访问各种 Nginx 变量，如：

   • ngx.var.http_*：请求头信息
   • ngx.var.remote_addr：客户端 IP
   • ngx.var.request_uri：请求 URI

5. 响应体设置：通过设置 ngx.arg[1] 为新的响应体内容，ngx.arg[2] 为 true 表示这是最后一个数据块。

性能考虑

1. 对于大响应体，JSON 解码/编码操作可能会影响性能，应考虑是否有必要处理整个响应体。

2. 如果只需要修改少量字段，可以考虑使用字符串操作而非完整的 JSON 解析。

3. 在高并发场景下，应测试这种操作的性能影响。

最佳实践

1. 对于简单的字段添加/修改，优先考虑 response-rewrite 插件。

2. 对于复杂逻辑，使用 serverless 函数，但应将复杂逻辑尽量简化。

3. 添加的错误处理机制，确保在 JSON 解析失败时能优雅降级。

4. 考虑将通用处理逻辑封装为自定义插件，提高复用性。

通过这种灵活的方式，APISIX 可以满足各种响应体修改需求，为 API 网关提供强大的响应处理能力。