BFF 的接口适配与职责边界

根据页面需要调整 BFF 的响应字段,并区分接口适配和核心业务规则。

🎯 引言

上一篇《用 Node.js 实现接口聚合》中,我们让 BFF 先查询订单,再查询用户和商品,最后把三份数据合并成订单详情。这样,前端不用再自行安排多个请求。

不过,拿到完整数据,不代表每个页面都需要全部数据。例如,移动端订单卡片只显示订单编号、用户名、商品名和金额;桌面端订单详情还需要购买数量和用户链接。如果把内部接口返回的对象原样交给页面,两端都会收到不需要的字段,还可能依赖不应该暴露的信息。

本篇继续使用同一份订单数据,让 BFF 为不同页面返回合适的结构,并解释:哪些工作属于 BFF,哪些业务判断应该交给业务服务?


🧱 为什么不同页面需要接口适配

例如,订单接口原本返回:

{
  "id": "o1",
  "userId": "u1",
  "productId": "p1",
  "quantity": 2,
  "totalCents": 59800
}

这些字段记录了订单信息,但没有页面要显示的用户名与商品名称。上一篇已经通过接口聚合获取了这些信息。现在还要考虑:不同页面究竟需要哪些字段?

字段来源移动端卡片桌面端详情
idorder.id需要需要
customerNameuser.name需要需要
productNameproduct.name需要需要
totalCentsorder.totalCents需要需要
quantityorder.quantity不需要需要
user.id、user.nameuser不需要需要,用于用户链接

接口适配就是按照页面约定,筛选字段、调整字段名称或组织数据结构。这个约定也叫接口契约:前端和 BFF 事先确定响应有哪些字段、各是什么含义。

比如业务接口叫 name,页面希望叫 customerName,BFF 可以负责重命名。用户邮箱不在页面的需求中,就不返回它。字段裁剪既能减少不必要的数据,也能降低前端对内部接口结构的依赖;但字段裁剪不能代替访问权限检查。


🛠 使用 BFF 实现接口适配

沿用上一篇的项目和模拟业务接口。先确保 mock.mjs 仍运行在 4100 端口,再修改 minimal-bff.mjs。

我们约定用查询参数 view 表示页面需要哪种响应:

  • view=mobile:移动端卡片,只返回四个通用字段。
  • view=desktop:桌面端详情,在通用字段之外增加购买数量和用户信息;不传 view 时默认使用它。

如果传入其他值,BFF 直接返回 HTTP 400,避免无效请求继续查询业务接口。

下面是修改后的 minimal-bff.mjs 完整代码,可以直接替换上一篇的文件:

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) => {
    // 1. 先确定页面需要哪种响应
    const view = req.query.view ?? 'desktop';
    if (!['desktop', 'mobile'].includes(view)) {
        return res.status(400).json({ error: 'INVALID_VIEW' });
    }

    // 2. 聚合订单、用户和商品数据(与上一篇相同)
    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)}`),
    ]);

    // 3. 整理两端共用的字段
    const summary = {
        id: order.id,
        customerName: user.name,
        productName: product.name,
        totalCents: order.totalCents,
    };

    // 4. 根据页面需要选择响应结构
    if (view === 'mobile') {
        return res.json(summary);
    }

    res.json({
        ...summary,
        quantity: order.quantity,
        user: { id: user.id, name: user.name },
    });
});

// 延用上一篇的简化错误处理;正式项目需要更细致的错误分类
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'));

这段代码主要增加了两件事:

  1. 校验 view:req.query.view 读取 URL 的查询参数。无效值返回 400;合法值才继续查询订单。
  2. 按页面返回字段:summary 保存两端共用的数据;移动端直接返回它,桌面端通过 ...summary 展开通用字段,再增加 quantity 和 user。

注意,桌面端既有 customerName,又有 user.name:前者供订单摘要显示,后者和 user.id 一起供用户链接使用。这是本例特意设计的页面约定,并非所有项目都必须重复姓名。

不管选择哪个 view,BFF 都还是查询同一份订单、用户和商品数据;改变的是返回给页面的结构,不是订单本身。


🧪 验证不同页面的接口响应

保持模拟后端运行,修改文件后重启 BFF:

node minimal-bff.mjs

在另一个终端请求移动端数据:

curl 'http://127.0.0.1:4000/bff/orders/o1?view=mobile'

预期响应:

{
  "id": "o1",
  "customerName": "小林",
  "productName": "机械键盘",
  "totalCents": 59800
}

再请求桌面端数据:

curl 'http://127.0.0.1:4000/bff/orders/o1?view=desktop'

预期响应:

{
  "id": "o1",
  "customerName": "小林",
  "productName": "机械键盘",
  "totalCents": 59800,
  "quantity": 2,
  "user": {
    "id": "u1",
    "name": "小林"
  }
}

最后验证不合法的参数:

curl -i 'http://127.0.0.1:4000/bff/orders/o1?view=unknown'

应返回 HTTP 400,响应正文为:

{
  "error": "INVALID_VIEW"
}

还可以省略 view 再请求一次,确认默认返回桌面端结构。对比两份成功响应:移动端只拿到需要的四个字段,桌面端拿到额外详情,两者都没有用户邮箱。

本篇为了方便验证,用一个 view 参数区分页面。实际项目也可以设计不同路由;不要为了支持越来越多的页面,让同一个接口积累大量难以维护的分支。


⚖️ BFF 与业务服务的职责边界

BFF 已经能够调整响应结构,那么它能不能顺便计算优惠后的订单价格,或判断订单是否允许取消?

不能因为代码写在 BFF 中很方便,就把核心业务规则搬过来。

判断标准是:这段逻辑只是在组织页面数据,还是在决定业务行为是否成立?

操作适合放在哪里原因
把 name 改成 customerNameBFF改变字段表达方式
合并订单、用户和商品数据BFF组织页面需要的响应
给移动端裁剪不需要的字段BFF适配页面数据结构
判断优惠券是否有效、计算应付金额业务服务统一交易规则
判断订单能否取消订单服务统一订单状态规则
校验用户是否有权操作订单负责授权的服务端逻辑,业务服务需把关不能只靠页面或字段裁剪保护操作
把 canCancel: false 显示成禁用按钮前端(BFF 可适配字段)展示业务服务已经给出的结果

例如,订单服务返回 canCancel: false,前端可以禁用“取消订单”按钮;BFF 可以把这个字段整理到页面响应里,但不应该自己复制一套订单状态规则。用户真正发起取消请求时,业务服务仍要重新判断,因为订单状态可能已经变化。

同样,totalCents 使用订单中保存的金额,不能按商品当前价格重新计算:是否收取多少钱属于交易规则,不属于页面字段适配。

在本课程的架构中,BFF 通过业务接口取得数据,不直接访问各业务服务的数据库。这样业务服务调整内部存储方式时,不必让页面适配层跟着修改数据库查询。


❓ 知识问答

Q1:既然前端也能筛选字段,为什么还需要 BFF 适配?

如果需求简单,前端自行处理完全可以。使用 BFF 的价值在于:多个页面或客户端可以复用服务端的数据组织逻辑,且不必把所有内部字段都发给浏览器。但增加 BFF 也有维护成本,不是每个项目都必须使用。

Q2:BFF 裁剪了敏感字段,是否就不需要权限检查了?

不是。字段裁剪决定返回哪些字段,权限检查决定这个用户能不能访问这份数据或执行操作。即使响应里没有邮箱,也不能让任何人随意查询别人的订单。


🧪 小练习

现在新增一种页面需求:订单收据摘要。请在 BFF 中支持 view=receipt,让它只返回订单 ID、购买数量和订单金额。

要求:修改 view 的允许值,并增加对应的响应分支;保留原有 mobile、desktop 和默认响应的行为。

完成后请求:

curl 'http://127.0.0.1:4000/bff/orders/o1?view=receipt'

预期结果:

{
  "id": "o1",
  "quantity": 2,
  "totalCents": 59800
}

再验证 view=unknown 仍返回 400。最后想一想:为什么这里的 totalCents 必须来自订单,而不能使用商品当前价格重新计算?

本练习中的“收据摘要”只用于练习字段裁剪,不代表正式发票或完整交易凭证。


🎉 恭喜你!已经学会根据不同页面需要适配 BFF 响应,并能区分数据展示逻辑与核心业务规则!