API 组合

移动端一页「课程详情」可能需要 课程、作者、进度、评论 四个微服务的数据。API 组合（API Composition） 在 聚合层 并行调多个下游，拼成 一个响应 给客户端——避免浏览器 N 次往返。

学习目标

• 理解聚合器 vs 客户端编排的分工
• 识别并行调用与部分失败的降级策略
• 对照 gql-rest 与 BFF 边界

客户端编排的问题

App ──GET /courses/1──► course-svc
App ──GET /users/42────► user-svc      （4 次 RTT + 4 套错误处理）
App ──GET /progress────► progress-svc
App ──GET /comments────► comment-svc

移动网络下延迟叠加；各服务 DTO 版本不一致时 App 负担重。

API 组合器拓扑

                    ┌──────────────────┐
  App ──GET /pages/course-detail──► │ Composition API  │
                    │  (或 Gateway 内)  │
                    └────────┬─────────┘
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        course-svc     user-svc      progress-svc
              │              │              │
              └──────────────┴──────────────┘
                         并行 Feign / WebClient
                              │
                         合并 JSON 返回

实现常放在 独立聚合服务 或 sc-gateway 后的 BFF（下一课 ip-bff）。

Spring 侧直觉

public CourseDetailPage compose(String slug, Long userId) {
    CompletableFuture<Course> course = async(() -> courseClient.get(slug));
    CompletableFuture<User> author = async(() -> userClient.getByCourse(slug));
    CompletableFuture<Progress> prog = async(() -> progressClient.get(userId, slug));
    return merge(course.join(), author.join(), prog.join());
}

配合 sc-feign 与超时；单路失败走 ip-circuit fallback（缺进度则显示「未开始」）。

与 GraphQL 的关系

方式	谁选字段	谁调下游
REST 组合	服务端固定 DTO	Composition 服务
GraphQL	客户端 Query	Resolver 调下游（）