subrequest是Nginx内部提供的轻量级非阻塞子请求机制，通过ngx_http_subrequest API实现，用于将主请求分解为多个独立子请求协同处理，常用于API聚合、内容拼接等场景，需依赖OpenResty或C模块扩展使用。
使用 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）：
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限制，需压测调优
替代思路对比
- 前端聚合：简单但受 CORS、性能、首屏延迟制约
- 专用 BFF 层（Node.js/Go）：更灵活，适合复杂编排和业务逻辑，但增加部署与运维成本
- Nginx + SSI（Server Side Include）：仅支持简单 HTML 片段拼接，不适用于 JSON API 聚合
- proxy_pass + mirror + 自定义模块：过于重量级，开发门槛高，一般不推荐
对中小规模、低延迟敏感、无复杂逻辑的聚合场景，OpenResty sub_request 是平衡性能、简洁性与可控性的优选方案。
