Apache APISIX 中实现请求UUID返回至响应体的技术方案

2025-05-15 12:07:57作者：咎竹峻Karen

背景介绍

在现代API网关应用中，请求追踪和错误处理是核心功能之一。Apache APISIX作为高性能API网关，提供了灵活的插件机制来实现各种定制化需求。本文将详细介绍如何在APISIX中实现将请求UUID返回至403错误响应体的技术方案。

技术实现原理

该功能的核心是通过自定义插件拦截请求，在特定条件下（如403错误）将请求头中的UUID信息嵌入到响应体中返回给客户端。这种设计既保持了API网关的标准错误处理流程，又增加了请求追踪信息的透明性。

详细实现步骤

1. 创建自定义插件

首先需要创建一个名为page-403的自定义插件，主要功能包括：

从请求头中获取UUID信息
构造包含UUID的自定义403响应
在特定条件下触发响应

插件代码示例：

local core = require("apisix.core")

local plugin_name = "page-403"

local schema = {
  type = "object",
  properties = {},
}

local _M = {
  version = 0.1,
  priority = 0,   -- 优先级需低于request-id插件(12015)
  name = plugin_name,
  schema = schema,
}

function _M.rewrite(conf, ctx)
  -- 从请求头获取UUID
  local uuid = core.request.header(ctx, "x-coraza-uuid")

  if uuid then
    -- 构造包含UUID的403响应
    core.response.exit(403, [[
<html>
  <body>
    <h1>403 Forbidden</h1>
    <p>请求UUID: ]] .. uuid .. [[</p>
  </body>
</html>
]])
  else
    core.log.warn("未找到请求ID!")
  end
end

return _M

2. 配置APISIX

在APISIX的配置文件中需要做以下调整：

确保插件列表包含自定义插件
设置正确的插件优先级
配置路由规则启用该插件

配置示例：

plugins:
  - request-id
  - page-403

routes:
  - id: request-uuid
    uri: /api/test
    upstream:
      nodes:
        "httpbin.org": 1
      type: roundrobin
    plugins:
      proxy-rewrite:
        uri: /get
        method: GET
      request-id:
        header_name: x-coraza-uuid
      page-403:

3. 部署与测试

使用Docker部署APISIX并测试功能：

docker run --name apache-apisix --rm \
  -p 9080:9080 \
  -e APISIX_STAND_ALONE=true \
  -v "$(pwd)/conf/config.yaml:/usr/local/apisix/conf/config.yaml" \
  -v "$(pwd)/conf/apisix.yaml:/usr/local/apisix/conf/apisix.yaml" \
  -v "$(pwd)/plugins/page-403.lua:/usr/local/apisix/apisix/plugins/page-403.lua" \
  apache/apisix

测试请求示例：

curl -i localhost:9080/api/test

预期响应：

HTTP/1.1 403 Forbidden
...

<html>
  <body>
    <h1>403 Forbidden</h1>
    <p>请求UUID: a5f51a39-ad95-45b6-881c-41694019abf0</p>
  </body>
</html>

技术要点解析

插件优先级：自定义插件优先级需低于request-id插件(12015)，确保先生成UUID再处理响应
请求处理阶段：选择在rewrite阶段处理，可以尽早拦截请求，减少不必要的后端处理
错误处理：当未找到UUID时记录警告日志，但仍允许请求继续处理
响应构造：使用core.response.exit直接返回完整响应，包括状态码和内容

应用场景

这种技术方案适用于以下场景：

API安全防护系统需要向客户端返回详细错误信息
需要增强API错误响应的可追踪性
实现自定义的错误页面和错误处理逻辑
开发调试阶段需要更多请求上下文信息

扩展思考

基于此方案可以进一步扩展功能：

动态错误页面：根据不同的错误类型返回不同的错误页面模板
多语言支持：根据请求头Accept-Language返回对应语言的错误信息
错误日志关联：将错误响应与系统日志关联，便于问题排查
错误信息加密：对敏感错误信息进行加密处理，提高安全性

总结

通过APISIX的插件机制，我们可以灵活地实现请求UUID返回至响应体的功能。这种方案不仅提高了API的可观测性，也为客户端提供了更多上下文信息，便于问题诊断和处理。APISIX强大的插件系统使得这类定制化需求可以轻松实现，而无需修改核心代码。

apisix

The Cloud-Native API Gateway and AI Gateway

项目地址：https://gitcode.com/gh_mirrors/api/apisix

登录后查看全文