流批一体架构实现API数据融合 - 第2节

API 数据源剖析：RESTful 与 GraphQL 的实战选择

做数据集成，第一关就是搞懂数据源长什么样。我见过太多团队，上来就写代码，结果被 API 的认证、限流折腾得死去活来。这一章，咱们就把 API 数据源扒开来看清楚。

说白了，你面对的无非两类：RESTful API 和 GraphQL API。它们不是谁替代谁的关系，而是各有各的脾气。

RESTful API：老牌劲旅，资源为王

REST 的核心思想是什么？把一切都抽象成资源。用户、订单、商品，每个资源都有唯一的 URL。你用 GET 拿数据，用 POST 创建，用 PUT 更新，用 DELETE 删除。

我在项目中遇到过最典型的场景：对接一个电商平台的订单系统。要拿订单详情，先调 /orders 拿到订单列表，再遍历调 /orders/{id} 拿每个订单的明细。如果还要查买家信息，得再调 /users/{userId}。

嗯，这里要注意。REST 的「无状态」对水平扩展很友好，但对数据集成来说，意味着你要自己维护调用链的状态。比如分页，你得自己记着 page 和 size 参数。

GraphQL API：灵活查询，按需索取

GraphQL 的出现，说白了就是为了解决 REST 的「过度获取」和「多次请求」问题。你想想看，一个前端页面可能需要用户信息、订单列表、商品详情，用 REST 你得调三个接口。用 GraphQL，一次查询搞定。

我曾经帮一个团队优化数据管道，他们用 REST 接口拉取报表数据，每次返回 50 多个字段，实际只用 5 个。换成 GraphQL 后，网络传输量直接降了 70%。

但 GraphQL 也有坑。它的查询复杂度很难控制，一个嵌套很深的查询可能把数据库打挂。我建议在生产环境一定要做深度限制和查询成本分析。

REST vs GraphQL：一张表说清楚

对比维度	RESTful API	GraphQL API
数据获取方式	固定结构，服务端决定返回字段	客户端声明，按需获取
端点数量	多个端点，每个资源一个	单个端点，所有操作统一入口
缓存机制	天然支持 HTTP 缓存	需要额外实现缓存层
学习曲线	低，HTTP 基础即可	中，需要理解 Schema 和 Resolver
适用场景	简单 CRUD、文件上传、CDN 友好	复杂关联查询、移动端、实时数据

怎么选？我的经验是：如果数据源是内部系统，且查询模式多变，优先 GraphQL。如果是对接第三方公开 API，REST 更稳妥，因为生态成熟，工具链完善。

API 认证机制：别让数据裸奔

搞数据集成，认证是第一道防线。我见过最离谱的事：有人直接把 写在代码里，然后提交到 GitHub 公开仓库。嗯，后果你懂的。

：简单粗暴，但别滥用

就是一个字符串，相当于你的身份证。每次请求带上它，服务端校验通过就放行。

# 请求头中携带 
GET /api/v1/orders
Headers:
  X-: abc123def456ghi789

优点很明显：实现简单，适合服务端到服务端的通信。缺点也很致命：Key 一旦泄露，别人就能冒充你。我曾经在项目中用 对接天气数据服务，结果 Key 被爬虫盗用，一天跑了 10 万次请求，账单直接爆了。

OAuth 2.0：企业级认证的标配

OAuth 2.0 不是一种认证协议，而是一种授权框架。它解决了「第三方应用如何安全地访问用户资源」的问题。

最常见的流程是授权码模式（Authorization Code Flow）。我拿对接钉钉开放平台举个例子：

1. 用户点击「钉钉登录」，跳转到钉钉授权页面
2. 用户确认授权，钉钉返回一个临时授权码
3. 后端用授权码 + Client Secret 换取 Access
4. 后续请求都带上 Access 访问资源
5. 过期后，用 Refresh 刷新

# 获取 Access  的请求示例
POST /oauth/
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "temp_auth_code_xyz",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://yourapp.com/callback"
}

# 响应
{
  "access_": "eyJhbGciOiJSUzI1NiIs...",
  "_type": "Bearer",
  "expires_in": 7200,
  "refresh_": "def456..."
}

我建议在流批一体架构中，优先使用 OAuth 2.0 的客户端凭证模式（Client Credentials）。为什么？因为服务端之间通信，没有用户交互，直接拿 Client ID 和 Secret 换 就行，流程最简洁。

API 限流与重试策略：别被踢出局

你想想看，API 提供方凭什么让你随便调？人家有成本，有负载。限流就是保护机制。我见过太多数据管道因为没处理限流，直接被封 IP，导致数据延迟几个小时。

常见的限流算法

算法	原理	优缺点
令牌桶	固定速率往桶里放令牌，请求消耗令牌	允许突发流量，实现简单
漏桶	请求先进桶，以固定速率流出	流量平滑，但无法应对突发
滑动窗口	统计时间窗口内的请求数	精确控制，但内存开销大

实际项目中，API 提供方通常会在响应头里告诉你限流信息：

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000       # 每小时允许 1000 次
X-RateLimit-Remaining: 342    # 还剩 342 次
X-RateLimit-Reset: 1623456789 # 重置时间戳

我曾经对接一个金融数据 API，对方限流策略很严格：每分钟 60 次，超了直接返回 429。我一开始没处理，结果管道跑了 20 分钟就断了。后来我加了本地令牌桶，配合响应头的 Retry-After 字段做自适应等待，再也没出过问题。

重试策略：优雅地处理失败

网络请求不可能 100% 成功。超时、限流、服务端错误，都是家常便饭。关键是怎么重试。

# Python 示例：带指数退避的重试
import time
import random

def call_api_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url)
            if response.status_code == 429:
                # 被限流了，等一会再试
                wait = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(wait)
                continue
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise e
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
    return None

本章知识体系总览

下面这张图，把本章的核心知识点串起来了。你可以把它当作 API 数据源接入的检查清单。

这张图把 API 数据源接入拆成了三个维度：类型选择、认证机制、可靠性保障。你在实际项目中，可以拿它当 checklist，每接入一个 API，都过一遍这三个维度，基本不会漏东西。