📚 课程目录第2章服务化API基础概念

服务化API基础概念：RESTful与gRPC对比，API网关作用，同步/异步调用模型

这一章我们聊聊服务化API的那些基础概念。说实话，很多同学一上来就追着问“gRPC比REST快多少”，但我觉得先搞清楚设计哲学和适用场景更重要。我早期在做一个推荐系统服务化项目时，就因为选错了通信协议，后来改得焦头烂额…先从最核心的对比开始吧。

RESTful vs gRPC：两个世界的碰撞

为什么要对比这两个协议？说白了，它们代表了两种完全不同的设计思路。RESTful是基于HTTP/1.1的资源导向设计，强调“无状态”和“统一接口”。而gRPC是基于HTTP/2的RPC框架，强类型、高性能，天生适合微服务间通信。

我用一个表格把关键差异列出来，这在我做技术选型时是必看清单：

对比维度	RESTful	gRPC
传输协议	HTTP/1.1，最近也开始支持HTTP/2	HTTP/2，强制使用
数据格式	JSON / XML / YAML 等文本格式	Protobuf 二进制格式
接口定义	隐式约定，通常看文档或Swagger	显式定义，通过 .proto 文件
性能	中等，序列化/反序列化开销大	高，二进制 + 多路复用
流式支持	不原生支持，需轮询或SSE	原生支持四种流模式
浏览器兼容	天然兼容	需要gRPC-Web网关
工具生态	curl、Postman、浏览器直接调试	需要protoc、grpcurl等专用工具
典型场景	外部API、Web应用、CRUD操作	微服务内调、实时通信、低延迟场景

我个人习惯这样选：如果接口要暴露给外部客户端，或者团队前端资源多，选RESTful。如果服务间调用频繁，对延迟敏感，比如AI推理的编排层，gRPC是更好的选择。

一个小技巧： 有些项目会同时用两者。我见过一种模式——外部用RESTful，内部微服务间用gRPC，通过一个API网关做协议转换。这样既照顾了易用性，又保住了性能。

API网关：服务化架构的守门人

当服务多起来之后，你会遇到一系列问题：认证鉴权怎么做？限流在哪里做？如何统一处理跨域？API网关就是来解决这些共性的。

我画了一个简单的架构图，展示网关在服务化体系中的位置：

嗯，这里要注意：API网关不是简单的反向代理。它承担了所有横切关注点。我见过不少团队一开始图省事，直接用Nginx做转发，后来认证、限流、灰度发布这些需求一来，代码全散落在各个服务里，维护成本爆炸。

我曾经踩过的坑： 有一个项目因为网关层没做超时控制，下游推理服务被长尾请求占满了连接池，导致正常请求全被阻塞。那次故障让我意识到，网关必须要配熔断降级——不能因为一个慢服务拖垮整个集群。

同步与异步调用模型

同步模型很好理解：客户端发请求，服务端处理完返回响应，客户端等在那里。gRPC的Unary调用就是典型的同步模式。

// 同步 gRPC 调用示例
// 客户端代码
async function predictSync(client, request) {
  const response = await client.predict(request);
  // 这里会等待服务端返回结果
  return response.output;
}

但如果你做过AI推理服务，你会发现一个痛点：推理耗时不稳定。有时模型热缓存了，50ms就返回；有时冷启动，要5秒。这时候全用同步模型，客户端很容易超时或堆积连接。

异步模型就灵活很多。gRPC原生支持客户端流、服务端流、双向流三种异步模式。再说白一点，就是不用死等，发完请求去做别的事，结果准备好再通知你。

// 异步 gRPC 调用示例（服务端流）
// 客户端发起请求后，持续接收流式结果
async function predictStream(client, requests) {
  const call = client.predictStream();
  for (const req of requests) {
    call.write(req);
  }
  call.end();
  
  for await (const result of call) {
    // 每收到一个结果就处理，不用等全部完成
    console.log('partial result:', result);
  }
}

实际选型建议：

长耗时推理（比如大模型生成、视频分析）：强烈推荐异步+回调或流式返回。我习惯用Redis Stream或Kafka做结果中转。
短时延推理（比如OCR、人脸检测）：同步gRPC就够了，延迟一般在几十ms以内。
批量推理：用客户端流模式，累积到一定数量或时间再发送。

另外说一个实践技巧：在多GPU推理场景下，我经常会在API网关层做“同步转异步”。

外部客户端通过RESTful发来的推理请求，经过网关后转为gRPC异步请求发给后端，网关立即返回“请求已接收（202）”，同时附上一个task_id。客户端轮询或通过WebSocket拿结果。这样外部接口还是简单易用的RESTful，内部服务却能享受gRPC异步的高吞吐。

# 网关配置示例（简化版）
gateway:
  routes:
    - path: /v1/predict
      method: POST
      backend: grpc://inference-cluster:50051
      call_mode: async
      response_mode: polling
      polling_endpoint: /v1/tasks/{task_id}
      timeout: 300s  # 推理任务最长等待5分钟

我个人的经验： 如果后端是GPU推理服务，请务必把异步调用的并发数控制好。我曾经没做限制，结果100个异步请求同时涌入，GPU显存直接OOM。后来加了个信号量，把并发数控制在GPU显存能承受的范围，类似这样：semaphore.acquire() → 推理 → semaphore.release()。

最后总结一下知识点脉络：

RESTful vs gRPC：一个面向资源，一个面向服务调用；一个文本协议，一个二进制协议。选型看场景，不是谁替代谁。
API网关：统一入口，做认证限流协议转换。别小看它，很多生产问题都是网关层没做好的锅。
同步/异步：同步简单但容易阻塞，异步复杂但吞吐高。多GPU推理服务，我最推荐“外部同步转内部异步”的架构。