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

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

2025-05-15 03:59: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

关键点解析

  1. 插件优先级:必须设置低于request-id插件的优先级(12015),确保UUID已经生成并添加到请求头中。

  2. 执行阶段选择:使用rewrite阶段而非access阶段,可以更早地拦截请求并返回响应。

  3. 核心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!

技术要点总结

  1. 插件开发规范:遵循APISIX插件开发规范,包括schema定义和导出结构。

  2. 执行阶段选择:根据业务需求选择合适的执行阶段,rewrite阶段适合早期拦截。

  3. 优先级管理:合理设置插件优先级,确保依赖关系正确。

  4. 错误处理:对异常情况应有明确的日志记录和处理逻辑。

  5. 响应构建:使用标准HTML格式构建响应体,确保良好的可读性。

扩展思考

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

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

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

登录后查看全文
热门项目推荐
相关项目推荐

热门内容推荐

最新内容推荐

项目优选

收起
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
C++
176
261
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot,Spring Security,JWT,Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
860
511
ShopXO开源商城ShopXO开源商城
🔥🔥🔥ShopXO企业级免费开源商城系统,可视化DIY拖拽装修、包含PC、H5、多端小程序(微信+支付宝+百度+头条&抖音+QQ+快手)、APP、多仓库、多商户、多门店、IM客服、进销存,遵循MIT开源协议发布、基于ThinkPHP8框架研发
JavaScript
93
15
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
129
182
openHiTLSopenHiTLS
旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件,通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求,让密码技术应用更简单,同时探索后量子等先进算法创新实践,构建密码前沿技术底座!
C
259
300
kernelkernel
deepin linux kernel
C
22
5
cherry-studiocherry-studio
🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端
TypeScript
596
57
CangjieCommunityCangjieCommunity
为仓颉编程语言开发者打造活跃、开放、高质量的社区环境
Markdown
1.07 K
0
HarmonyOS-ExamplesHarmonyOS-Examples
本仓将收集和展示仓颉鸿蒙应用示例代码,欢迎大家投稿,在仓颉鸿蒙社区展现你的妙趣设计!
Cangjie
398
371
Cangjie-ExamplesCangjie-Examples
本仓将收集和展示高质量的仓颉示例代码,欢迎大家投稿,让全世界看到您的妙趣设计,也让更多人通过您的编码理解和喜爱仓颉语言。
Cangjie
332
1.08 K