# 接口合并与数据聚合：BFF 层设计实践

去年接手一个电商项目，商品详情页在 App 端要连续发 9 个请求：商品基础信息、库存、价格、可用优惠券、店铺信息、评价摘要、物流模板、推荐商品、猜你喜欢。首屏 P95 接近 3 秒。产品的反馈是"太慢"，前端的反馈是"接口太碎"，后端的反馈是"接口都是现成的，你们自己拼一下"。

三方扯皮两周之后，我们花了三周给这个项目加了一层 BFF：请求数从 9 个降到 1 个，首屏 P95 落到 1.2 秒上下。这篇文章不讲概念史，只把过程里真正有用的东西整理出来，三个重点：

1. BFF 到底解决什么问题（以及它不解决什么）；
2. 聚合接口怎么设计才不踩坑，附 FastAPI + httpx 的可运行代码；
3. 我们后来用 GraphQL（Strawberry）重做一版的经验和教训，含 DataLoader 批量加载的实现。

代码都是 Python，基于 FastAPI，删掉了项目里的业务字段，核心逻辑原样保留。

## 一、先想清楚：BFF 解决的是什么问题

BFF（Backend for Frontend）这个词是 Sam Newman 在 2015 年前后带火的。一句话概括：**给每一类前端配一个专属的"后端门面"，由它来做接口的裁剪、合并和聚合。**

结构大概是这样：

```
┌────────┐   ┌────────┐   ┌────────┐
│  App   │   │  H5    │   │ PC 端  │
└───┬────┘   └───┬────┘   └───┬────┘
    │            │            │
┌───▼────────────▼────────────▼────┐
│        BFF 层（可按端拆分）        │
│   裁剪字段 / 合并请求 / 聚合数据   │
└───┬───────────┬───────────┬─────┘
    │           │           │
┌───▼───┐   ┌───▼────┐   ┌──▼─────┐
│商品服务│   │库存服务 │   │推荐服务 │
└───────┘   └────────┘   └────────┘
```

很多人会把 BFF 和 API 网关混为一谈，其实两者管的事情完全不同：

- **网关管横切关注点**：鉴权、限流、路由、协议转换。它不理解业务，也不应该理解。
- **BFF 管业务组装**：详情页需要哪几个服务的数据、App 端要哪些字段、H5 端要哪些字段。它非常懂业务，而且只为某一类前端服务。

还有一个常见误解是把 BFF 当成"又一个通用 API 层"。不是的。BFF 的精髓恰恰在于**不通用**——App 的 BFF 返回 App 要的精确结构，H5 的 BFF 返回 H5 要的精确结构，谁也别迁就谁。一旦你开始把 BFF 做成"所有端共用的聚合层"，它就退化成那个你本来想逃离的臃肿中台。

什么时候**不要**上 BFF？我的经验是两条：

- 前端就调一两个接口，硬加一层纯属给自己找活干；
- 团队里没有明确归属。BFF 最大的风险从来不是技术，是归属——这层代码谁来写、谁来改、挂了谁背锅。我们当时定的规矩是 BFF 归前端同学维护（用 Python 是因为组里前端都会写），后端只对下游服务的 SLA 负责。没有这个共识，BFF 迟早变成三不管的泥潭。

## 二、聚合接口设计：难点全在"失败的时候"

聚合接口本身十分钟就能写完，真正要花心思的是这些：

**1. 必须真并行，不能假并行。** 串行调 4 个各耗时 200ms 的服务，总耗时 800ms；并行调，总耗时取决于最慢的那个，200ms 出头。这是聚合接口存在的意义，写成串行就白干了。

**2. 每个下游单独设超时，别用一个全局值糊弄。** 商品、库存是核心数据，可以给到 1.5s；推荐、优惠券是增强数据，800ms 不返回就算了，页面少一块比整个页面打不开好得多。

**3. 允许部分失败，并且把失败显式告诉前端。** 这是最容易被忽略的一点。聚合接口不能是"一个挂了全挂"，也不能是"悄悄把失败那块吞掉返回个 null"——前端分不清"没有优惠券"和"优惠券服务挂了"，UI 就会渲染出误导性的内容。

**4. 把异常收口在分片函数内部。** 这样 `asyncio.gather` 永远拿到干净的结果类型，不用到处写 `isinstance(r, Exception)` 的判断。

下面是核心代码。先是分片调用部分（`services.py`）：

```python
# services.py
import logging
from dataclasses import dataclass, field

import httpx

logger = logging.getLogger("bff")

# 每个下游服务单独设超时，别用一个全局值糊弄
SERVICE_TIMEOUTS = {
    "product": 1.5,     # 核心数据，多等一会儿
    "stock": 1.0,
    "recommend": 0.8,   # 增强数据，给少点，慢了就降级
    "coupon": 0.8,
}


@dataclass
class Section:
    """聚合结果的一个分片。ok=False 时前端走兜底 UI。"""
    ok: bool
    data: dict = field(default_factory=dict)
    error: str | None = None


async def call_service(
    client: httpx.AsyncClient, name: str, path: str
) -> Section:
    """调一个下游服务，所有异常都在这里收口，返回值类型永远是 Section。"""
    try:
        resp = await client.get(path, timeout=SERVICE_TIMEOUTS[name])
        resp.raise_for_status()
        return Section(ok=True, data=resp.json())
    except Exception as exc:  # 超时、5xx、JSON 解析失败，统一处理
        logger.warning("bff upstream failed: %s %s, err=%r", name, path, exc)
        return Section(ok=False, error=f"{name}_unavailable")
```

然后是聚合入口（`main.py`）：

```python
# main.py
import asyncio
from contextlib import asynccontextmanager

import httpx
from fastapi import FastAPI, HTTPException, Request

from services import call_service

CORE_SECTIONS = {"product", "stock"}            # 挂了就直接 502
EXTRA_SECTIONS = {"recommend", "coupon"}        # 挂了降级，页面照常出


@asynccontextmanager
async def lifespan(app: FastAPI):
    # 复用连接池。每次请求新建 client 是压测里最常见的翻车点
    limits = httpx.Limits(max_connections=200, max_keepalive_connections=50)
    async with httpx.AsyncClient(
        base_url="http://internal-api", limits=limits
    ) as client:
        app.state.client = client
        yield


app = FastAPI(lifespan=lifespan)


@app.get("/bff/app/product/{sku_id}")
async def product_detail(sku_id: str, request: Request):
    client = request.app.state.client

    tasks = {
        "product":   call_service(client, "product",   f"/product/{sku_id}"),
        "stock":     call_service(client, "stock",     f"/stock/{sku_id}"),
        "recommend": call_service(client, "recommend", f"/recommend?sku={sku_id}"),
        "coupon":    call_service(client, "coupon",    f"/coupon/usable?sku={sku_id}"),
    }
    # 异常已在分片内部收口，gather 拿到的全是 Section，不用 return_exceptions
    results = dict(zip(tasks.keys(), await asyncio.gather(*tasks.values())))

    # 核心分片失败 → 整体失败，没必要返回一个空壳页面让前端猜
    for name in CORE_SECTIONS:
        if not results[name].ok:
            raise HTTPException(status_code=502, detail=f"{name} unavailable")

    return {
        "sku_id": sku_id,
        "product": results["product"].data,
        "stock": results["stock"].data,
        # 增强分片：失败返回 None，由前端渲染兜底模块
        "recommend": results["recommend"].data if results["recommend"].ok else None,
        "coupon": results["coupon"].data if results["coupon"].ok else None,
        # 关键设计：显式告诉前端哪几块挂了
        "degraded": [n for n, r in results.items() if not r.ok],
    }
```

几个值得多说一句的地方：

- **`degraded` 字段是协议的正式成员，不是临时补丁。** 前端拿到它可以做两件很有用的事：给兜底模块打上"数据加载失败，点击重试"的标记；把降级情况上报埋点，这样 BFF 的可用性数据在前端也有交叉验证。
- **监控要按分片维度打。** "聚合接口成功率 99%"是没有意义的数字，必须拆成 product 成功率、recommend 成功率分别看。推荐服务挂三天，主接口成功率可能一动不动。
- **警惕"假并行"。** 如果你在分片函数里用了任何同步阻塞调用（比如 `requests`、没加 `await` 的 redis 客户端），`asyncio.gather` 会安静地退化成串行，而且本地自测根本发现不了，压测才现形。上线前用 `asyncio` 的 debug 模式或慢回调日志扫一遍。
- **别让 BFF 调 BFF。** 链路里出现第二跳聚合时，超时预算就没人算得清了。

这套结构上线后，详情页接口的 P95 稳定在 300ms 左右（最慢的下游决定的），推荐服务抖动时对主流程零影响。

## 三、GraphQL 做 BFF：香，但别神化

REST 聚合跑顺之后，新的问题来了：端越来越多，字段差异越来越大。App 的详情页要 20 个字段，H5 只要 8 个，运营后台又要另一组。按第一节的思路，就得给每个端、每个页面维护一个聚合接口，接口数量开始失控，而且任何一个端加字段都要发版。

这正是 GraphQL 的适用场景：**让前端自己声明要什么，BFF 只负责把"取数能力"标准化地暴露出去。** 我们用 Strawberry + FastAPI 重写了一版，核心代码如下。

先定义 schema 和批量加载函数（`schema.py`）：

```python
# schema.py
import strawberry

# 这两个函数由 services 层实现，这里只示意签名：
# 批量接口是 GraphQL BFF 的命脉，没有它们 DataLoader 就是摆设
from services import batch_get_products, batch_get_stocks


@strawberry.type
class Product:
    sku_id: str
    title: str
    price: str


@strawberry.type
class Stock:
    sku_id: str
    available: int
    locked: int


@strawberry.type
class Query:
    @strawberry.field
    async def product(self, info, sku_id: str) -> Product | None:
        # 注意：这里不是直接单查，而是走 DataLoader 合并批量请求
        return await info.context["product_loader"].load(sku_id)

    @strawberry.field
    async def stock(self, info, sku_id: str) -> Stock | None:
        return await info.context["stock_loader"].load(sku_id)


schema = strawberry.Schema(query=Query)
```

挂载到 FastAPI（`main.py`）：

```python
# main.py
from fastapi import FastAPI
from strawberry.dataloader import DataLoader
from strawberry.fastapi import GraphQLRouter

from schema import schema
from services import batch_get_products, batch_get_stocks


async def get_context():
    # 关键：DataLoader 必须按请求新建。
    # 它内置缓存，跨请求复用会把用户 A 的数据喂给用户 B
    return {
        "product_loader": DataLoader(load_fn=batch_get_products),
        "stock_loader": DataLoader(load_fn=batch_get_stocks),
    }


app = FastAPI()
app.include_router(GraphQLRouter(schema, context_getter=get_context), prefix="/graphql")
```

前端一个查询拿走自己要的字段，App 和 H5 各取所需，BFF 零改动：

```graphql
query ProductDetail($skuId: String!) {
  product(skuId: $skuId) {
    title
    price
  }
  stock(skuId: $skuId) {
    available
  }
}
```

**DataLoader 是这套方案里唯一不能省的东西。** 没有它，列表页渲染 20 个商品、每个商品再查一次库存，就是 1 + 20 次下游调用（经典的 N+1 问题）。DataLoader 把同一 tick 里的 `.load()` 调用合并成一次批量请求，`batch_get_stocks` 收到 20 个 key 一次查完，下游压力和串行单查完全不是一个量级。前提是下游服务得提供批量接口——所以我说批量接口是命脉，没有批量接口的下游，套 DataLoader 也救不了。

用了一年多，GraphQL 版 BFF 的教训也攒了几条，都是踩过坑的：

- **HTTP 缓存基本告别。** 请求全走 POST `/graphql`，CDN 和浏览器缓存都用不上，缓存要么下沉到数据层，要么用 persisted query（把查询预注册成 ID，走 GET）绕回来。我们是后者，顺带还解决了"前端乱写查询"的管控问题。
- **必须限制查询深度和复杂度。** 不限制的话，一个嵌套十层的查询能把下游打穿。Strawberry 生态里有现成的 query depth limiter 扩展，上线第一天就该配上。
- **错误模型其实和 REST 聚合是同一个思路。** GraphQL 天生支持"部分数据 + errors 数组"——product 取到了、recommend 挂了，响应里两者都如实呈现。第二节里 `degraded` 字段想解决的问题，在 GraphQL 里是协议自带的，这点确实优雅。
- **schema 即合同，治理要趁早。** 字段废弃用 `@deprecated` 标记而不是直接删，给前端留迁移期。我们第一版没立这条规矩，后来收拾旧字段花了两个月。

## 收尾：怎么选

| 场景 | 建议 |
| --- | --- |
| 端少、接口稳定 | 前端直连或极简聚合，别急着上 BFF |
| 多端、字段差异大、前端迭代快 | BFF + REST 聚合（本文第二节的方案） |
| 聚合接口开始爆炸、前端要自助取数 | BFF + GraphQL + DataLoader + persisted query |

最后说句实话：BFF 不是什么高深技术，它本质上就是"把拼装数据的工作从前端挪到一个离前端更近的地方"。真正决定成败的从来不是选 REST 还是 GraphQL，而是超时预算、部分失败、按分片监控这些脏活有没有做到位。概念一天就能讲完，细节要踩一个季度——希望这篇文章能帮你少踩几个。

---

*本文所有代码基于 Python 3.11+ / FastAPI / Strawberry GraphQL，已脱敏，可直接运行验证。*

去年接手一个电商项目，商品详情页在 App 端要连续发 9 个请求：商品基础信息、库存、价格、可用优惠券、店铺信息、评价摘要、物流模板、推荐商品、猜你喜欢。首屏 P95 接近 3 秒。产品的反馈是"太慢"，前端的反馈是"接口太碎"，后端的反馈是"接口都是现成的，你们自己拼一下"。

BFF层设计实践

后端

架构设计

开发工具

电商项目通过BFF层优化接口性能，将商品详情页请求从9个减少到1个，首屏P95从3秒降至1.2秒。文章分享BFF层设计实践，包括接口聚合、GraphQL应用及DataLoader批量加载等核心优化方案，提供Python代码示例，帮助解决多端数据聚合难题。

代码解释

GraphQL

路由

Python

JSON

CDN免费试用


2026上云采购 | AI焕新·智启新局

cngw

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

BFF层设计实践-腾讯云开发者社区-腾讯云

BFF层设计实践

BFF层设计实践

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐