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

2025-05-15 17:42:02作者：咎竹峻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

Apisix是一个基于Nginx的API网关，主要用于微服务架构中的API管理和服务发现。它的特点是高性能、轻量级、易于配置等。适用于API管理和负载均衡场景。

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

登录后查看全文

项目优选

收起

kernel

deepin linux kernel

docs

OpenHarmony documentation | OpenHarmony开发者文档

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

Java

leetcode

🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解

喝着茶写代码！最易用的自托管一站式代码托管平台，包含Git托管，代码审查，团队协作，软件包和CI/CD。

RuoYi-Vue3

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

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

150

rainbond

无需学习 Kubernetes 的容器平台，在 Kubernetes 上构建、部署、组装和管理应用，无需 K8s 专业知识，全流程图形化管理

cherry-studio

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

TypeScript

928