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

2025-05-15 13:56:23作者：范靓好Udolf

背景介绍

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

核心需求分析

我们需要实现的功能是：当请求被拦截返回403状态码时，在响应体中包含请求的唯一标识符(UUID)。这个标识符通常由请求ID插件生成并存储在请求头中。

技术实现方案

自定义插件开发

在APISIX中，我们可以通过开发自定义插件来实现这一需求。以下是完整的插件实现代码：

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>Your UUID: ]] .. uuid .. [[</p>
  </body>
</html>
]])
  else
    core.log.warn("Request ID not found!")
  end
end

return _M

关键点解析

插件优先级：必须设置低于request-id插件的优先级(12015)，确保UUID已经生成并添加到请求头中。
执行阶段选择：使用rewrite阶段而非access阶段，可以更早地拦截请求并返回响应。
核心API使用：
- core.request.header：获取请求头信息
- core.response.exit：直接返回响应并终止请求处理流程

配置部署方案

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:

效果验证

成功场景

当请求包含UUID头时，将直接返回403响应：

HTTP/1.1 403 Forbidden
Content-Type: text/plain; charset=utf-8
x-coraza-uuid: a5f51a39-ad95-45b6-881c-41694019abf0

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

异常场景

当请求不包含UUID头时，会记录警告日志并继续处理请求：

2024/12/07 20:44:32 [warn] 166#166: *182451 [lua] page-403.lua:33: phase_func(): Request ID not found!

技术要点总结

插件开发规范：遵循APISIX插件开发规范，包括schema定义和导出结构。
执行阶段选择：根据业务需求选择合适的执行阶段，rewrite阶段适合早期拦截。
优先级管理：合理设置插件优先级，确保依赖关系正确。
错误处理：对异常情况应有明确的日志记录和处理逻辑。
响应构建：使用标准HTML格式构建响应体，确保良好的可读性。

扩展思考

这种技术方案不仅可以用于403错误页面，还可以扩展到其他HTTP状态码的自定义响应。通过修改插件逻辑，可以实现：

动态错误页面模板
多语言错误提示
详细的错误诊断信息
安全警告信息

这种灵活的响应定制能力是APISIX作为API网关的重要优势之一，能够帮助开发者构建更加健壮和用户友好的API服务。

apisix

The Cloud-Native API Gateway

项目地址：https://gitcode.com/GitHub_Trending/ap/apisix

登录后查看全文