API 与集成

这一课你将能做到

1. 按 REST 规范设计一套课程资源 API，包含版本、分页、错误码和幂等设计
2. 说清楚 REST、GraphQL、gRPC 三者的适用场景，并为本站的内部服务通信选型
3. 用消息队列改造本站的「下单 → 开课 → 通知」链路，并解决重复消费问题

为什么要学

系统变多之后，「服务之间怎么说话」就成了架构的核心问题。API 设计是一次性投入、长期负债——一个糟糕的 API 上线后，改也不是（有调用方依赖），不改也不是（天天被吐槽）。

人话：API 是服务之间的合同。签合同时稀里糊涂，后面扯皮无穷无尽。好的 API 让调用方「不看文档也能猜对」，坏的 API 让维护者「天天在群里答疑」。

先建立图像

本站集成方式的演进：

【阶段一：内部直接调用】
OrderService ──方法调用──→ CourseService（同一个 JVM）

【阶段二：REST 同步调用】
前端 ──REST──→ API 服务 ──REST──→ 第三方（支付/短信）

【阶段三：同步 + 异步混合】
                 ┌──REST──→ 支付网关
前端 ──REST──→ 订单服务
                 └──MQ──→ RocketMQ ──┬──→ 开课服务（消费）
                                      ├──→ 通知服务（消费）
                                      └──→ 积分服务（消费）

跟着做

步骤 1：设计本站课程 REST API

GET    /api/v1/courses?page=1&size=20&track=java    # 列表（分页+过滤）
GET    /api/v1/courses/sarch-intro                  # 详情（slug 而非自增 id）
POST   /api/v1/orders                               # 创建订单
GET    /api/v1/orders/{id}                          # 订单详情
PATCH  /api/v1/orders/{id}                          # 部分更新（如取消）

设计要点逐一落实：

// 1. 统一响应结构
public record ApiResponse<T>(int code, String message, T data) {}

// 2. 错误码分层：2xx 成功 / 4xx 客户端错 / 5xx 服务端错
//    业务错误用 4xx + 业务码，不要一律 200 然后在 body 里塞 success:false

// 3. 幂等：创建订单用幂等键防重复提交
@PostMapping("/orders")
public ApiResponse<Order> create(
        @RequestHeader("Idempotency-Key") String idemKey,
        @RequestBody CreateOrderReq req) {
    // 先查 idemKey 是否已处理，是则直接返回上次结果
    return orderService.createIdempotent(idemKey, req);
}

步骤 2：三种 API 风格对比选型

维度	REST	GraphQL	gRPC
协议	HTTP/JSON	HTTP/JSON	HTTP2/Protobuf
数据获取	固定结构	客户端指定字段	固定结构
性能	中	中	高（二进制、多路复用）
适用	对外公开 API	多端聚合查询	内部服务间
本站用法	开放 API	管理后台聚合页	订单↔库存内部调用

步骤 3：消息队列改造下单链路