用 Node.js 实现接口聚合
🎯 引言
假设你正在开发订单详情页,需要显示订单金额、下单用户和商品名称。但后端把这些信息放在三个接口里:订单接口只返回 userId 和 productId,前端还得用这两个 ID 查询用户和商品。
不使用 BFF 时,前端可能这样编排请求(这里省略了错误处理):
const order = await fetch('/orders/o1').then(res => res.json());
const user = await fetch(`/users/${order.userId}`).then(res => res.json());
const product = await fetch(`/products/${order.productId}`).then(res => res.json());
订单页面不仅要发起多个请求,还需要知道三类数据如何关联。使用 BFF 后,可以把这些步骤交给服务端,前端只请求一个聚合接口:
const detail = await fetch('/bff/orders/o1').then(res => res.json());
接口聚合就是由一个接口请求多个数据源,再把结果整理成调用方需要的数据。它减少了前端需要编排的请求,但并不意味着后端只访问一次数据源。
本篇用 Node.js、Express 和 Promise.all 完成订单详情接口聚合,重点学习:先查询有依赖的数据、并发查询相互独立的数据、最终返回页面直接可用的 JSON。
🧰 准备模拟业务接口
解压课程示例,进入项目目录。本篇使用 Node.js 22、Express 5.1.0,项目依赖版本由 package-lock.json 锁定:
cd backend-architecture-course
node --version
npm ci
我们只使用 data.mjs、mock.mjs 和 minimal-bff.mjs 三个文件。先看 data.mjs 中的模拟数据:
export const users = [{ id: 'u1', name: '小林', email: 'lin@example.test' }];
export const products = [{ id: 'p1', name: '机械键盘', priceCents: 29900 }];
export const orders = [{ id: 'o1', userId: 'u1', productId: 'p1', quantity: 2, totalCents: 59800 }];
订单 o1 中的 userId: 'u1' 对应用户小林,productId: 'p1' 对应机械键盘。priceCents 和 totalCents 表示以“分”为单位的金额,例如 59800 表示 598 元。
接着用 mock.mjs 提供三个模拟业务接口:
import express from 'express';
import { users, products, orders } from './data.mjs';
const app = express();
for (const [resource, rows] of Object.entries({ users, products, orders })) {
app.get(`/${resource}/:id`, (req, res) => {
const row = rows.find(item => item.id === req.params.id);
res.status(row ? 200 : 404).json(row ?? { error: 'NOT_FOUND' });
});
}
app.listen(4100, '127.0.0.1', () => console.log('mock on 4100'));
这里的循环只是为了少写重复代码:它分别创建用户、商品和订单的详情路由,根据 URL 中的 :id 找到记录并返回 JSON;查不到时返回 404。
| 请求地址 | 返回的数据 |
|---|---|
GET /orders/o1 | 订单:用户 ID、商品 ID、数量、金额 |
GET /users/u1 | 用户:姓名、邮箱 |
GET /products/p1 | 商品:名称、单价 |
打开终端 A,启动模拟后端:
node mock.mjs
再用另一个终端检查订单接口:
curl http://127.0.0.1:4100/orders/o1
响应正文应为:
{
"id": "o1",
"userId": "u1",
"productId": "p1",
"quantity": 2,
"totalCents": 59800
}
注意,这个接口还没有返回用户姓名和商品名称。接下来由 BFF 使用订单中的两个 ID,补齐页面需要的数据。
🛠 创建 BFF 并查询订单
在 minimal-bff.mjs 中创建 BFF。先看完整代码,随后按照执行顺序理解关键步骤:
import express from 'express';
const app = express();
async function read(path) {
const response = await fetch(`http://127.0.0.1:4100${path}`);
if (!response.ok) throw new Error(`upstream status ${response.status}`);
return response.json();
}
app.get('/bff/orders/:id', async (req, res) => {
const order = await read(`/orders/${encodeURIComponent(req.params.id)}`);
const [user, product] = await Promise.all([
read(`/users/${encodeURIComponent(order.userId)}`),
read(`/products/${encodeURIComponent(order.productId)}`),
]);
res.json({
id: order.id,
customerName: user.name,
productName: product.name,
totalCents: order.totalCents,
});
});
app.use((error, req, res, next) => {
res.status(502).json({ error: 'UPSTREAM_ERROR' });
});
app.listen(4000, '127.0.0.1', () => console.log('minimal bff on 4000'));
打开终端 B运行:
node minimal-bff.mjs
此时要保持两个服务都在运行:模拟后端监听 4100,BFF 监听 4000。前端请求 BFF,BFF 再通过 HTTP 请求模拟后端。
先关注这一行:
const order = await read(`/orders/${encodeURIComponent(req.params.id)}`);
当请求 /bff/orders/o1 时,req.params.id 是 o1。BFF 先调用模拟后端的 /orders/o1,取得订单。encodeURIComponent 用于编码放入 URL 路径的 ID,避免特殊字符干扰路径结构。
read(path) 是一个简单的公共请求函数:fetch 负责发请求,response.ok 检查 HTTP 状态,response.json() 解析 JSON。只有拿到订单,我们才知道接下来要查询哪个用户和商品。
⚡ 使用 Promise.all 并发查询用户和商品
订单查询必须先完成,因为用户 ID 和商品 ID 都来自订单。但拿到这两个 ID 后,查询用户与查询商品没有先后依赖。
如果串行请求:
const user = await read(`/users/${order.userId}`);
const product = await read(`/products/${order.productId}`);
第二个请求需要等待第一个完成。可以改成并发请求:
const [user, product] = await Promise.all([
read(`/users/${encodeURIComponent(order.userId)}`),
read(`/products/${encodeURIComponent(order.productId)}`),
]);
两次 read() 会先后被调用并各自发起请求,Promise.all 等待两次查询全部成功后,再把结果交给 user 和 product。即使商品先返回,结果数组仍按传入的顺序排列:第一个是用户,第二个是商品。
假设用户查询需要 100 毫秒,商品查询需要 150 毫秒:串行等待约 250 毫秒,而并发阶段通常接近 150 毫秒。这只是方便理解的示例时间,实际耗时还与网络和服务器有关;前面获取订单的耗时仍需要另外计算。
这里还需要知道两个失败规则:
Promise.all中任何一个请求失败,整个等待过程就会失败,但它不会自动取消其他正在执行的请求。fetch收到 HTTP 404 或 500 时,不会仅因为状态码而抛错。因此read()必须检查response.ok,再决定是否抛错。
本篇要求用户和商品数据都获取成功才返回订单详情,不把缺失数据当作正常值。有关 fetch 的更多说明可查看 Node.js 官方文档。
🧩 整理页面需要的 JSON
到这里,BFF 已经拿到三份数据。接下来只需选出页面需要的字段:
res.json({
id: order.id,
customerName: user.name,
productName: product.name,
totalCents: order.totalCents,
});
最终接口响应为:
{
"id": "o1",
"customerName": "小林",
"productName": "机械键盘",
"totalCents": 59800
}
对比前面的原始订单 JSON:原本只有 userId 和 productId,聚合后变成页面可以直接显示的 customerName 和 productName。订单金额仍来自订单接口,不需要重复计算。用户接口中的邮箱没有返回,因为当前页面不需要它。
这就是 BFF 在本例中的职责:由服务端处理数据关联与组合,让前端拿到更适合页面使用的数据结构。
🧪 验证聚合结果与失败响应
在第三个终端执行:
curl -i http://127.0.0.1:4000/bff/orders/o1
应看到 HTTP 状态码 200,以及上一节展示的聚合 JSON(curl -i 还会显示响应头)。前端只需请求 /bff/orders/o1,不再自己发起订单、用户和商品的三次调用;但 BFF 内部仍访问了三个业务接口。
再请求一张不存在的订单:
curl -i http://127.0.0.1:4000/bff/orders/missing
此时模拟后端的订单接口返回 404,read() 因为 response.ok 为 false 而抛错。示例中的错误处理中间件会统一返回 502,响应正文为:
{
"error": "UPSTREAM_ERROR"
}
在 Express 5 中,异步路由抛出的错误会自动交给错误处理中间件。这里 app.use((error, req, res, next) => ...) 的四个参数用于让 Express 识别错误处理中间件,即使暂时没有用到 next 也需要保留。
注意:返回 502 是本篇为了简化代码而采用的统一处理,并不表示“不存在的订单”应该一律返回 502。 正式服务需要区分资源不存在、上游服务故障等情况,并补充超时与日志。后续《服务调用失败时怎么办》会专门处理这些问题,这里先聚焦接口聚合。
❓ 知识问答
Q1:为什么不能把订单、用户和商品三个请求一起放入 Promise.all?
因为本例中用户和商品的 ID 必须先从订单里取得。应该先查询订单,再并发查询互不依赖的用户与商品。
Q2:为什么不直接把整个用户对象返回给前端?
因为订单页只需要用户姓名,不需要邮箱等其他字段。聚合时只返回所需字段,可以让接口更贴合页面需求,也避免无意暴露多余信息。下一篇会进一步介绍输出字段的筛选。
🧪 小练习
在 data.mjs 的 orders 数组中增加一张订单 o2,要求:userId 为 u1、productId 为 p1、quantity 为 1、totalCents 为 29900。
修改后只需重启模拟后端 mock.mjs,BFF 无须重启。然后执行:
curl http://127.0.0.1:4000/bff/orders/o2
验收标准:响应中 id 为 o2、totalCents 为 29900,用户姓名仍为“小林”,商品名称仍为“机械键盘”。再请求一个不存在的订单 ID,观察当前示例为什么会返回 502。
🎉 恭喜你!已经使用 Express 和 Promise.all 完成订单详情接口聚合。
