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

2025-05-15 08:44:40作者：范靓好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

登录后查看全文

项目优选

收起

kernel

deepin linux kernel

docs

OpenHarmony documentation | OpenHarmony开发者文档

本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。

Ascend Extension for PyTorch

Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用

Java

kernel

openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。

141

RuoYi-Vue3

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统

本项目是CANN开源社区的核心管理仓库，包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息

557

111