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

登录后查看全文

项目优选

收起

kernel

deepin linux kernel

docs

OpenHarmony documentation | OpenHarmony开发者文档

Ascend Extension for PyTorch

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

🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端

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

openJiuwen agent-studio提供零码、低码可视化开发和工作流编排，模型、知识库、插件等各资源管理能力

TSX

986

248

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

背景介绍

核心需求分析

技术实现方案

自定义插件开发

关键点解析

配置部署方案

APISIX配置文件

路由配置示例

效果验证

成功场景

异常场景

技术要点总结

扩展思考

热门内容推荐

最新内容推荐

项目优选

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

背景介绍

核心需求分析

技术实现方案

自定义插件开发

关键点解析

配置部署方案

APISIX配置文件

路由配置示例

效果验证

成功场景

异常场景

技术要点总结

扩展思考

相关内容推荐

热门内容推荐

最新内容推荐

项目优选