跳到主要内容

request-id

request-id 插件为通过网关代理的每个请求分配唯一 ID，可用于请求追踪和调试。如果请求中已通过 header_name 指定的请求头包含 ID，插件会使用该值，而不生成新 ID。

默认情况下，网关日志中会包含请求 ID。启用该插件后，请求 ID 还会添加到响应头中。

示例​

以下示例展示了如何在不同场景下配置 request-id 插件。

了解网关日志中的请求 ID​

从 Apache APISIX 3.15.0 和 API7 企业版 3.3.0 起，无论是否启用该插件，访问日志和错误日志中都会包含请求 ID。

  • 禁用该插件时，请求 ID 默认为 Nginx 内置的 $request_id。
  • 启用该插件时，请求 ID 设置为插件生成的唯一 ID。

这可确保请求追踪始终可用，并在启用插件后提供增强功能。

以下示例演示了禁用和启用插件时，请求 ID 在网关日志中的显示方式。

创建一条未配置 request-id 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该会收到 HTTP/1.1 200 OK 响应。在网关日志中，你应该会看到类似以下的条目，其中最后一个值是 NGINX 内置 $request_id 生成的请求 ID：

192.168.215.1 - - [30/Jan/2026:07:21:31 +0000] localhost:9080 "GET /anything HTTP/1.1" 200 391 1.657 "-" "curl/8.6.0" 3.210.41.225:80 200 1.608 "http://localhost:9080" "8a14012e5d0414aff4f15f04b0bd8cb9"

更新路由并配置 request-id 插件：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该会收到 HTTP/1.1 200 OK 响应。在网关日志中，你应该会看到类似以下的条目，其中最后一个值是插件生成的请求 ID：

192.168.215.1 - - [30/Jan/2026:07:36:24 +0000] localhost:9080 "GET /anything HTTP/1.1" 200 391 0.685 "-" "curl/8.6.0" 52.20.30.6:80 200 0.653 "http://localhost:9080" "8c0ac818-f9d6-4160-be60-8fc74e76be73"

将请求 ID 附加到默认响应头​

以下示例展示了如何在路由上配置 request-id，如果请求中未传递请求 ID，则生成一个请求 ID 并将其附加到默认的 X-Request-Id 响应头中。当请求中已设置 X-Request-Id 请求头时，插件将使用请求头中的值作为请求 ID。

使用默认配置（显式定义）在路由上创建 request-id 插件：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "X-Request-Id",
        "include_in_response": true,
        "algorithm": "uuid"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到 HTTP/1.1 200 OK 响应，并看到响应头包含带有生成 ID 的 X-Request-Id：

X-Request-Id: b9b2c0d4-d058-46fa-bafc-dd91a0ccf441

向路由发送带有自定义请求 ID 的请求：

curl -i "http://127.0.0.1:9080/anything" -H 'X-Request-Id: some-custom-request-id'

你应该收到 HTTP/1.1 200 OK 响应，并看到响应包含带有自定义请求 ID 的 X-Request-Id 头：

X-Request-Id: some-custom-request-id

将请求 ID 附加到自定义响应头​

以下示例展示了如何在路由上配置 request-id，将生成的请求 ID 附加到指定的响应头。

创建带有 request-id 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "X-Req-Identifier",
        "include_in_response": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ 定义携带请求 ID 的自定义请求头。

❷ 在响应头中包含请求 ID。

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到 HTTP/1.1 200 OK 响应，并看到响应包含带有生成 ID 的 X-Req-Identifier 头：

X-Req-Identifier: 1c42ff59-ee4c-4103-a980-8359f4135b21

在响应头中隐藏请求 ID​

以下示例展示了如何在路由上配置 request-id，将生成的请求 ID 附加到指定请求头。包含请求 ID 的请求头应转发到上游服务，但不返回在响应头中。

创建带有 request-id 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "X-Req-Identifier",
        "include_in_response": false
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ 定义携带请求 ID 的自定义请求头。

❷ 不在响应头中包含请求 ID。

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到 HTTP/1.1 200 OK 响应，并且在响应头中没有看到 X-Req-Identifier 头。在响应体中，你应该看到：

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "127.0.0.1", 
    "User-Agent": "curl/8.6.0", 
    "X-Amzn-Trace-Id": "Root=1-6752748c-7d364f48564508db1e8c9ea8", 
    "X-Forwarded-Host": "127.0.0.1",
    "X-Req-Identifier": "268092bc-15e1-4461-b277-bf7775f2856f"
  }, 
  ...
}

这表明请求 ID 已转发到上游服务，但未在响应头中返回。

使用 nanoid 算法​

以下示例展示了如何在路由上配置 request-id 并使用 nanoid 算法生成请求 ID。

创建带有 request-id 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "algorithm": "nanoid"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该会收到 HTTP/1.1 200 OK 响应，并看到响应中包含 X-Request-Id 响应头，其值为使用 nanoid 算法生成的 ID：

X-Request-Id: kepgHWCH2ycQ6JknQKrX2

在全局和路由上附加请求 ID​

以下示例展示了如何将 request-id 配置为全局插件，并在路由上配置它以附加两个 ID。

创建一个全局规则，使用 request-id 插件将请求 ID 添加到自定义请求头：

curl -i "http://127.0.0.1:9180/apisix/admin/global_rules" -X PUT -d '{
  "id": "rule-for-request-id",
  "plugins": {
    "request-id": {
      "header_name": "Global-Request-ID"
    }
  }
}'

创建一个带有 request-id 插件的路由，将请求 ID 添加到另一个自定义请求头：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "Route-Request-ID"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到 HTTP/1.1 200 OK 响应，并看到响应包含以下头：

Global-Request-ID: 2e9b99c1-08ed-4a74-b347-49c0891b07ad
Route-Request-ID: d755666b-732c-4f0e-a30e-a7a71ace4e26