3、数据源分析与接口设计：常见数据源类型、接口设计原则、数据格式解析、接口文档编写

说实话，做数据采集这么多年，我踩过最大的坑就是——没搞清楚数据源长什么样，就开始写代码。

你想想看，数据源千奇百怪，有的藏在API里，有的躺在数据库里，有的就是个破网页。每种数据源的脾气都不一样，你得顺着它的性子来。今天我就把这几类常见数据源，以及接口设计的门道，一次性给你讲透。

3.1 常见数据源类型

我习惯把数据源分成四大类：API、数据库、文件、Web页面。每一类我都亲手折腾过，下面说说我的体会。

3.1.1 API 数据源

API 是目前最主流的数据源。说白了，就是别人把数据封装好，给你一个 URL，你发个请求，它返回数据。我在项目中遇到过最典型的场景——对接第三方支付平台的对账接口，每天凌晨拉取前一天的交易流水。

• RESTful API：基于 HTTP 协议，用 GET/POST/PUT/DELETE 操作资源。返回格式通常是 JSON 或 XML。
• GraphQL API：可以按需查询，只拿你想要的字段。适合数据模型复杂的场景。
• WebSocket API：长连接，实时推送。比如股票行情、聊天消息。

3.1.2 数据库数据源

数据库是数据采集的「老本行」。你直接从业务库拉数据，但要注意——别把生产库搞崩了。

• 关系型数据库：MySQL、PostgreSQL、Oracle。用 SQL 查询，适合结构化数据。
• NoSQL 数据库：MongoDB（文档型）、Redis（缓存型）、Elasticsearch（搜索型）。
• 时序数据库：InfluxDB、TimescaleDB。专门存时间序列数据，比如 IoT 传感器数据。

3.1.3 文件数据源

文件是最古老的数据源，但也是最容易出幺蛾子的。我见过有人把 10GB 的 CSV 文件直接塞进内存，结果 OOM 了。

• CSV/TSV：最通用的表格格式。注意编码问题（UTF-8 vs GBK），还有引号转义。
• JSON/XML：半结构化数据，适合嵌套结构。
• Excel：.xlsx 和 .xls。注意单元格合并、公式、宏这些坑。
• Parquet/ORC：列式存储格式，适合大数据场景。压缩率高，查询快。

3.1.4 Web 页面数据源

Web 页面是最「野」的数据源。没有 API 怎么办？只能爬。但要注意法律风险，别乱爬。

• 静态页面：HTML 直接渲染，用 XPath 或 CSS 选择器提取数据。
• 动态页面：数据通过 JavaScript 异步加载。需要模拟浏览器（Selenium、Playwright）或直接抓 XHR 请求。
• 反爬策略：IP 封禁、验证码、User-Agent 检测。嗯，这里要注意——尊重 robots.txt。

3.2 接口设计原则（RESTful）

如果你是自己设计数据采集接口，我强烈建议遵循 RESTful 风格。为什么？因为它简单、直观、好维护。

3.2.1 RESTful 核心原则

• 资源导向：每个 URL 代表一个资源。比如 /api/users 代表用户集合，/api/users/123 代表单个用户。
• 使用 HTTP 动词：GET（查）、POST（增）、PUT（全量更新）、PATCH（部分更新）、DELETE（删）。
• 无状态：每次请求都包含所有必要信息，服务端不保存客户端状态。
• 统一接口：所有资源用同样的方式操作。

GET    /api/orders              # 获取订单列表
GET    /api/orders/{id}         # 获取单个订单
POST   /api/orders              # 创建新订单
PUT    /api/orders/{id}         # 全量更新订单
PATCH  /api/orders/{id}         # 部分更新订单
DELETE /api/orders/{id}         # 删除订单

3.2.2 接口设计避坑

• 版本控制：URL 里带版本号，比如 /v1/orders。我见过没版本号的接口，改一次前端就崩一次。
• 分页：大数据量必须分页。用 ?page=1&size=20 或 ?offset=0&limit=20。
• 错误处理：返回统一的错误格式，比如 {"code": 400, "message": "参数错误"}。
• 认证：用 Token 或 API Key，别裸奔。

3.3 数据格式解析

数据格式解析，说白了就是把字符串变成程序能理解的结构。我处理过几十种格式，最常用的就这三种。

3.3.1 JSON 解析

JSON 是目前最流行的数据交换格式。轻量、易读、几乎所有语言都支持。

// JSON 示例
{
  "order_id": "20240301001",
  "user": {
    "name": "张三",
    "age": 28
  },
  "items": [
    {"product": "手机", "price": 2999},
    {"product": "耳机", "price": 199}
  ]
}

解析时注意：字段名大小写敏感，数字不要带引号，日期用 ISO 8601 格式。

3.3.2 XML 解析

XML 虽然老了，但在金融、医疗行业依然坚挺。结构严谨，但啰嗦。

<order>
  <order_id>20240301001</order_id>
  <user>
    <name>张三</name>
    <age>28</age>
  </user>
  <items>
    <item>
      <product>手机</product>
      <price>2999</price>
    </item>
  </items>
</order>

解析方式：DOM（加载整个文档）、SAX（流式解析）、XPath（路径查询）。我建议用 XPath，最灵活。

3.3.3 CSV 解析

CSV 看着简单，其实坑最多。我遇到过字段里带逗号、换行符、引号没转义的情况，解析结果直接乱掉。

order_id,user_name,product,price
20240301001,张三,手机,2999
20240301002,李四,"耳机,充电器",199

3.4 接口文档编写（Swagger/OpenAPI）

写接口文档，我个人的血泪教训是——不写文档的接口，三个月后连你自己都看不懂。

3.4.1 为什么用 OpenAPI

OpenAPI（原名 Swagger）是目前最流行的接口文档标准。它用 JSON 或 YAML 描述接口，可以自动生成文档、客户端 SDK、甚至测试用例。

• 自动生成文档：写一次，前端、测试、运维都能看。
• 可交互：直接在文档页面里测试接口。
• 代码生成：自动生成 Java、Python、JavaScript 的客户端代码。

3.4.2 OpenAPI 示例

openapi: 3.0.0
info:
  title: 订单数据采集接口
  version: 1.0.0
paths:
  /orders:
    get:
      summary: 获取订单列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: size
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回订单列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      properties:
        order_id:
          type: string
        user_name:
          type: string
        total_price:
          type: number

3.4.3 文档编写要点

• 描述清楚每个字段：类型、是否必填、取值范围、示例值。
• 列出所有错误码：400（参数错误）、401（未认证）、404（资源不存在）、500（服务器错误）。
• 提供请求/响应示例：让调用方一目了然。
• 标注版本变更：每次修改都要更新版本号，并记录变更日志。

下一章，我们会聊到数据采集框架选型——到底用 Scrapy、Flume 还是自研？到时候我会把各框架的优缺点掰开揉碎了讲给你听。