用 Node.js 实现接口聚合

使用 Express 和 Promise.all 为订单详情页聚合数据。

🎯 引言

假设你正在开发订单详情页,需要显示订单金额、下单用户和商品名称。但后端把这些信息放在三个接口里:订单接口只返回 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 完成订单详情接口聚合。