subrequest是Nginx内部提供的轻量级非阻塞子请求机制，通过ngx_http_subrequest API实现，用于将主请求分解为多个独立子请求协同处理，常用于API聚合、内容拼接等场景，需依赖OpenResty或C模块扩展使用。
使用 Nginx 的
机制，可以在一次客户端请求中并行（或串行）发起多个子请求到不同后端服务，再将结果合并后统一返回。这避免了前端多次请求、减少网络开销，也绕开了浏览器同源策略限制，适合做轻量级 API 聚合层。
sub_request 是什么？
Nginx 内部提供的一种非阻塞子请求能力，由
API 实现，常用于：
–
/
（需 echo 模块）
–
+
配合
（OpenResty 场景）
– 原生 Nginx C 模块开发（如自定义模块中调用）
注意：标准 Nginx 不直接暴露 sub_request 给配置文件，必须依赖扩展模块（最常用的是
OpenResty + lua-nginx-module
）。
用 OpenResty + Lua 实现聚合（推荐方案）
这是目前最实用、可维护性最强的方式。示例逻辑如下：
客户端访问
Nginx 执行 Lua 脚本，用
并发调用
、
、
收集响应体，JSON 合并为
设置响应头
，返回聚合结果
关键配置片段（
）：
多后端的PHP抽象库
多后端的PHP抽象库
下载
}
注意事项与限制
超时控制必须显式设置
：每个子请求都要配
（connect/read/send），否则可能阻塞整个 worker
错误需降级处理
：某个子服务不可用时，建议记录日志并填充默认值（如空对象），而非整体失败
不支持跨域子请求的 Cookie/认证头透传
：子请求是 Nginx 发起的，与客户端上下文隔离；若需带鉴权，得在 Lua 中手动添加
内存与连接数有上限
：大量并发 sub_request 可能耗尽
或触发
限制，需压测调优
替代思路对比
前端聚合
：简单但受 CORS、性能、首屏延迟制约
专用 BFF 层（Node.js/Go）
：更灵活，适合复杂编排和业务逻辑，但增加部署与运维成本
Nginx + SSI（Server Side Include）
：仅支持简单 HTML 片段拼接，不适用于 JSON API 聚合
proxy_pass + mirror + 自定义模块
：过于重量级，开发门槛高，一般不推荐
对中小规模、低延迟敏感、无复杂逻辑的聚合场景，OpenResty sub_request 是平衡性能、简洁性与可控性的优选方案。
sub_requestngx_http_subrequestecho_exececho_subrequestproxy_passsubrequestlua-resty-http/api/summaryresty.http/backend/user/backend/order/backend/profile{"user":{...},"order":[...],"profile":{...}}Content-Type: application/jsonnginx.conflocation /api/summary {
content_by_lua_block {
local http = require "resty.http"
local httpc = http.new()
-- 并发发起子请求
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))
}timeoutheaders["Authorization"]worker_connectionslua_socket_pool_size