第3章 RESTful API基础

第3章：RESTful API基础——HTTP协议核心概念

各位同学，今天我们来聊聊RESTful API。说实话，我在风电行业摸爬滚打这么多年，发现很多搞风电的工程师对API这块儿有畏难情绪。其实没那么复杂，你想想看，API说白了就是两个系统之间约定好的沟通方式。就像咱们风电场的中控系统和SCADA系统之间怎么说话，总得有个规矩吧？

我个人习惯把RESTful API比作一个快递系统。你寄快递、查快递、退快递，每个动作都有对应的操作方式。HTTP协议里的GET、POST、PUT、DELETE，就是这些操作方式。咱们一个一个来看。

3.1 HTTP方法：API的四种基本操作

先看个总览表格，心里有个底：

HTTP方法	对应操作	幂等性	典型场景
GET	查询/读取	是	获取风机实时数据
POST	创建/新增	否	提交故障报告
PUT	更新/替换	是	修改风机参数配置
DELETE	删除	是	删除过期告警记录

GET 是最常用的。比如你要查某台风机当前的发电功率，发个GET请求就行。我在项目中遇到过有人用POST去查数据，结果把数据库搞出了重复记录。记住：查数据就用GET，别整花活。

POST 用来创建新资源。比如风场新装了一台风机，你要把它的信息录入系统。这里有个坑——POST不保证幂等。什么意思？你连续点两次提交，可能会创建两条一模一样的记录。我曾经在调试某风电平台的API时，就因为网络重试机制没处理好，同一个告警事件被插入了三次。

PUT 是整体更新。比如你要把风机编号WF001的额定功率从2MW改成2.5MW，用PUT把整个资源对象传过去。注意，PUT要求你提供完整的资源数据，缺了某个字段，那个字段可能就被清空了。

DELETE 就是删除。嗯，这个没什么好说的，但要注意——很多风电系统的DELETE不是真删除，而是软删除（标记为已删除）。为什么？因为运维审计需要保留历史记录。

3.2 HTTP状态码：API的应答暗号

每次API调用，服务器都会返回一个状态码。这就像两个人对话，你问一句，对方得回一句「收到」或者「不行」。我整理了几个最常用的：

200 OK：一切正常。GET请求成功返回数据，PUT/DELETE操作成功。
201 Created：POST创建成功。通常响应头里会带一个Location字段，指向新资源的URL。
400 Bad Request：你发的东西有问题。比如JSON格式错了，或者缺少必填字段。
401 Unauthorized：没带认证信息，或者认证信息过期了。
403 Forbidden：认证通过了，但你没权限干这事儿。比如普通运维人员想删除核心配置。
404 Not Found：资源不存在。URL写错了，或者ID不对。
500 Internal Server Error：服务器炸了。这通常是后端代码的锅。

避坑指南：我曾经在对接某风电SCADA系统时，对方API文档写的是返回200表示成功，结果实际返回的是201。排查了半天，发现是文档没更新。所以，别完全信文档，用Postman或curl先试一把。

3.3 JSON数据格式：API的通用语言

JSON现在是API通信的事实标准。它轻量、易读，而且几乎所有编程语言都支持。看个风电场景的例子：

{
  "wind_turbine_id": "WF-001",
  "timestamp": "2025-03-15T14:30:00Z",
  "measurements": {
    "power_output_kw": 1850.5,
    "wind_speed_mps": 12.3,
    "rotor_speed_rpm": 14.2,
    "blade_pitch_deg": 8.7
  },
  "status": "running",
  "alarms": []
}

这里有几个要点：

键名用蛇形命名法（snake_case）还是驼峰命名法（camelCase）？我个人习惯用蛇形，因为JSON是从Python生态火起来的，但如果你对接的是Java写的系统，对方可能用驼峰。提前约定好。
时间戳一定要用ISO 8601格式，带时区信息。我见过有人用时间戳整数（毫秒数），结果不同系统间差了8小时。
布尔值用true/false，不要用1/0或者"yes"/"no"。

小技巧：写API时，如果某个字段可能为空，建议用null而不是空字符串""。因为null表示「没有值」，空字符串表示「值是一个空字符串」，语义完全不同。

3.4 API认证机制：谁在敲门？

API不能谁都能调，得有认证。风电系统的数据涉及电网安全，认证更是重中之重。常用的有两种：

API Key

最简单的方式。服务端给你一个字符串，你每次请求都带上它。通常放在请求头里：

GET /api/v1/turbines
Headers:
  X-API-Key: abc123def456

API Key的优点是简单，缺点是安全性一般。因为Key是静态的，一旦泄露，别人就能一直用。我建议只在内部网络或者测试环境用API Key。

Token（令牌）

更安全的方式。你先用用户名密码换取一个临时Token，后续请求都带这个Token。Token有过期时间，通常几小时到几天。看个流程：

// 第一步：获取Token
POST /api/v1/auth/login
Body: {"username": "admin", "password": "xxxx"}
Response: {"token": "eyJhbGciOiJIUzI1NiIs...", "expires_in": 3600}

// 第二步：使用Token
GET /api/v1/turbines/WF-001
Headers:
  Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

现在主流做法是用JWT（JSON Web Token）。它本身包含了用户信息和过期时间，服务器不需要存session，扩展性好。我在做某风电集控平台时，就用的JWT，单点登录、跨系统调用都很方便。

注意：Token一定要用HTTPS传输，否则中间人可以截获。另外，Token过期后要引导用户重新登录，别让用户莫名其妙地看到401错误。

3.5 知识体系总览

下面这张图把本章的核心内容串起来了。你可以把它当作一个速查地图：

好了，这一章的内容就这些。记住，API调用不是什么高深的技术，它就是两个系统之间规规矩矩地说话。你按照规范来，就不会出大问题。下一章咱们会拿一个真实的风电API来练手，到时候你就知道这些东西怎么用了。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录