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服务。
登录后查看全文
相关内容推荐
热门项目推荐
相关项目推荐
atomcodeClaude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get StartedRust0231
GLM-5.2智谱开源 GLM-5.2，这是针对长文本任务的最新旗舰模型。相较于前代产品 GLM-5.1，它在长文本任务处理能力上实现了显著飞跃，并且首次在稳定的 100 万 token 上下文中提供这一能力。Jinja00
JoyAI-VL-Interaction-Preview京东开源首个开源、视觉驱动的实时交互模型——它能实时监控视频流，并自主决定何时发言、保持沉默或委托任务。Jinja00
cann-learning-hubCANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。Jupyter Notebook0151
kornia🐍 空间人工智能的几何计算机视觉库Python02
PaddleParallel Distributed Deep Learning: Machine Learning Framework from Industrial Practice （『飞桨』核心框架，深度学习&机器学习高性能单机、分布式训练和跨平台部署）C++02
热门内容推荐
最新内容推荐
项目优选
收起
docs暂无描述
Dockerfile
782
5.11 K
ops-transformer本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
892
2.06 K
kernelopenEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
471
473
pytorchAscend Extension for PyTorch
Python
764
972
ops-nn本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
710
1.43 K
kerneldeepin linux kernel
C
32
16
cann-learning-hubCANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
432
151
ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.11 K
1.15 K
jiuwenswarmJiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
2.27 K
681
flutter_flutter本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本，由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用，3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。
Dart
1.04 K
272