BFF 模式

Backend for Frontend（BFF） 为 特定客户端（Web、iOS、Admin）提供 量身定制的 API，而不是强迫所有端消费同一套通用微服务 DTO。常与 API 组合、GraphQL 一起出现。

学习目标

• 区分 BFF 与通用 API Gateway 的职责
• 理解「按端拆分聚合层」的收益与成本
• 对照 gql-rest 与 ip-api-composition

为什么需要 BFF

客户端	需求差异
Web 课程页	SEO 友好、字段多、可 SSR
移动 App	包体小、列表轻量、离线缓存
Admin 控制台	批量操作、审计字段、权限细

一个 course-service 的 REST 资源很难同时满足；在 BFF 层裁剪、聚合、鉴权 更干净。

典型拓扑

┌─────────┐     ┌─────────────┐     ┌─────────────────────────────┐
│ Web App │────►│  Web BFF    │────►│ course / user / progress svc │
└─────────┘     └─────────────┘     └─────────────────────────────┘
┌─────────┐     ┌─────────────┐              ▲
│ iOS App │────►│ Mobile BFF  │──────────────┘
└─────────┘     └─────────────┘
                       │
              API Gateway（sc-gateway）统一入口、JWT、限流

BFF 可以 是独立 Spring Boot 服务；Gateway 负责横切，BFF 负责 端专属编排。

BFF 做什么 / 不做什么

做：

• 调用多个下游（Feign / WebClient）
• 合并 DTO、适配分页与错误码
• 端专属缓存（Redis）与 ip-circuit 降级

不做：

• 承载核心领域规则（订单计价仍在 order-svc）
• 直接访问多个服务的 写库（写操作应下沉到领域服务）

BFF + GraphQL

Admin 控制台字段多变时，BFF 可暴露 GraphQL（gql-spring），由 Resolver 调微服务；公开 Web 仍 REST + nextjs-essentials RSC。GraphQL 不是 BFF 必需，只是 一种实现。

反模式预警

• 胖 BFF：业务逻辑堆满，变成新单体 → 见 ip-anti
• BFF 爆炸：每个小功能一个 BFF → 合并按 而非按