BFF 的接口适配与职责边界
🎯 引言
上一篇《用 Node.js 实现接口聚合》中,我们让 BFF 先查询订单,再查询用户和商品,最后把三份数据合并成订单详情。这样,前端不用再自行安排多个请求。
不过,拿到完整数据,不代表每个页面都需要全部数据。例如,移动端订单卡片只显示订单编号、用户名、商品名和金额;桌面端订单详情还需要购买数量和用户链接。如果把内部接口返回的对象原样交给页面,两端都会收到不需要的字段,还可能依赖不应该暴露的信息。
本篇继续使用同一份订单数据,让 BFF 为不同页面返回合适的结构,并解释:哪些工作属于 BFF,哪些业务判断应该交给业务服务?
🧱 为什么不同页面需要接口适配
例如,订单接口原本返回:
{
"id": "o1",
"userId": "u1",
"productId": "p1",
"quantity": 2,
"totalCents": 59800
}
这些字段记录了订单信息,但没有页面要显示的用户名与商品名称。上一篇已经通过接口聚合获取了这些信息。现在还要考虑:不同页面究竟需要哪些字段?
| 字段 | 来源 | 移动端卡片 | 桌面端详情 |
|---|---|---|---|
id | order.id | 需要 | 需要 |
customerName | user.name | 需要 | 需要 |
productName | product.name | 需要 | 需要 |
totalCents | order.totalCents | 需要 | 需要 |
quantity | order.quantity | 不需要 | 需要 |
user.id、user.name | user | 不需要 | 需要,用于用户链接 |
接口适配就是按照页面约定,筛选字段、调整字段名称或组织数据结构。这个约定也叫接口契约:前端和 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'));
这段代码主要增加了两件事:
- 校验
view:req.query.view读取 URL 的查询参数。无效值返回 400;合法值才继续查询订单。 - 按页面返回字段:
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 改成 customerName | BFF | 改变字段表达方式 |
| 合并订单、用户和商品数据 | 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 响应,并能区分数据展示逻辑与核心业务规则!
