利用 Nginx sub_request 机制实现单次请求聚合多个后端接口数据-Nginx-PHP中文网

subrequest是nginx内部提供的轻量级非阻塞子请求机制，通过ngx_http_subrequest api实现，用于将主请求分解为多个独立子请求协同处理，常用于api聚合、内容拼接等场景，需依赖openresty或c模块扩展使用。

利用 nginx sub_request 机制实现单次请求聚合多个后端接口数据

使用 Nginx 的 sub_request 机制，可以在一次客户端请求中并行（或串行）发起多个子请求到不同后端服务，再将结果合并后统一返回。这避免了前端多次请求、减少网络开销，也绕开了浏览器同源策略限制，适合做轻量级 API 聚合层。

sub_request 是什么？

Nginx 内部提供的一种非阻塞子请求能力，由 ngx_http_subrequest API 实现，常用于：
– echo_exec / echo_subrequest（需 echo 模块）
– proxy_pass + subrequest 配合 lua-resty-http（OpenResty 场景）
– 原生 Nginx C 模块开发（如自定义模块中调用）
注意：标准 Nginx 不直接暴露 sub_request 给配置文件，必须依赖扩展模块（最常用的是 OpenResty + lua-nginx-module）。

用 OpenResty + Lua 实现聚合（推荐方案）

这是目前最实用、可维护性最强的方式。示例逻辑如下：

客户端访问 /api/summary
Nginx 执行 Lua 脚本，用 resty.http 并发调用 /backend/user、/backend/order、/backend/profile
收集响应体，JSON 合并为 {"user":{...},"order":[...],"profile":{...}}
设置响应头 Content-Type: application/json，返回聚合结果

关键配置片段（nginx.conf）：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

location /api/summary {
    content_by_lua_block {
        local http = require "resty.http"
        local httpc = http.new()
<pre class="brush:php;toolbar:false;">    -- 并发发起子请求
    local res1, res2, res3 = ngx.thread.wait(
        ngx.thread.spawn(function() return httpc:request_uri("http://user-svc/user", { method = "GET" }) end),
        ngx.thread.spawn(function() return httpc:request_uri("http://order-svc/order", { method = "GET" }) end),
        ngx.thread.spawn(function() return httpc:request_uri("http://profile-svc/profile", { method = "GET" }) end)
    )

    -- 解析并组装
    local data = {}
    if res1 and res1.status == 200 then data.user = json.decode(res1.body) end
    if res2 and res2.status == 200 then data.order = json.decode(res2.body) end
    if res3 and res3.status == 200 then data.profile = json.decode(res3.body) end

    ngx.header.content_type = "application/json"
    ngx.say(json.encode(data))
}

}

注意事项与限制

超时控制必须显式设置：每个子请求都要配 timeout（connect/read/send），否则可能阻塞整个 worker
错误需降级处理：某个子服务不可用时，建议记录日志并填充默认值（如空对象），而非整体失败
不支持跨域子请求的 Cookie/认证头透传：子请求是 Nginx 发起的，与客户端上下文隔离；若需带鉴权，得在 Lua 中手动添加 headers["Authorization"]
内存与连接数有上限：大量并发 sub_request 可能耗尽 worker_connections 或触发 lua_socket_pool_size 限制，需压测调优