HTTP基础：RESTful API、请求方法、状态码、Headers、Body格式

说实话，很多刚接触 SDK 的同学，觉得 HTTP 就是调几个接口、传几个参数。但等到真的接入多语言 SDK 的时候，各种超时、鉴权失败、数据对不上，才会发现基础没打牢。

HTTP 是 SDK 通信的骨架。你绕不开它。

这一章，我就带你从头梳理一遍。不会讲太深，但都是干活时一定会碰到的点。

1. RESTful API —— 它到底长什么样？

RESTful 不是协议，是一种设计风格。说白了，就是把你的数据当作“资源”，然后用标准 HTTP 方法去操作它。

我在接入某海外翻译 SDK 时，对方给的文档里全是 RESTful 风格的路径。比如：

POST /v2/translate
GET  /v2/languages
DELETE /v2/glossary/{id}

每个路径代表一个资源，动作由请求方法决定。我建议你一开始就用这种风格来理解接口，后面对接任何 SDK 都会顺很多。

2. 请求方法 —— 你至少得用熟这四个

方法	作用	幂等	我遇到过的坑
GET	获取资源	是	参数过长被截断，改用 POST 反而更稳
POST	创建资源	否	多次点击导致重复订单，后来加了幂等键
PUT	整体更新	是	漏传字段导致其他字段被清空
DELETE	删除资源	是	删除后重复请求返回 404，正常现象

嗯，这里要注意：GET 请求不要带 body。有些同学习惯把所有东西塞进 JSON 里用 GET 发，结果服务端根本读不到。我在第一次对接 REST API 的时候就犯过这个错，排查了半天才发现是客户端把参数放错了位置。

3. 状态码 —— 别只记住 200 和 404

状态码是服务端给你的信号。看懂它，能省掉一堆日志分析工作。

• 2xx 成功：200 OK，201 Created。我最常用的是 200，但创建资源时建议用 201。
• 3xx 重定向：301/302。SDK 里很少遇到，但如果你发现 302，检查一下是否被中间件拦截了。
• 4xx 客户端错误：400 参数错误，401 未授权，403 禁止访问，404 不存在，429 请求太频繁。
• 5xx 服务端错误：500 内部错误，502 网关错误，503 服务不可用。

我曾经在对接某语音识别 SDK 时，连续收到 429 状态码。当时以为是 SDK 有问题，后来发现是我自己并发太高，没做限流。加了一个简单的令牌桶后就正常了。

4. Headers —— 那些你容易漏掉的字段

Headers 是请求和响应的“元数据”。有些字段不传，接口直接拒绝你。

Header 名称	说明	例子
Content-Type	告诉服务端 body 的格式	application/json
Authorization	鉴权，通常 Bearer	Bearer eyJhbGci...
Accept	告诉服务端你期望的返回格式	application/json
X-Request-ID	追踪请求，调试利器	uuid

5. Body 格式 —— 用 JSON 还是 Form？

现在大部分 SDK 都推荐 JSON。结构清晰，调试也方便。但我遇到过有些老系统只支持 XML 或表单格式。

• JSON：{"key":"value"}，嵌套友好，适合复杂结构。
• 表单：key1=value1&key2=value2，简单、体积小，但不支持数组。
• Multipart：上传文件时必须用这个。

你想想看，如果你用 JSON 而对方要求表单，服务端解析出来就是空。这种情况我一般先看文档，再写个 curl 测试一下，避免浪费时间。

6. 一张图串起 HTTP 核心流程

下面这张图是我自己总结的 —— 一次典型的请求-响应过程，标注了刚才讲的关键要素。

7. 写在后面

HTTP 基础说难不难，但一不留神就踩坑。我建议你在写 SDK 接入代码之前，先用 Postman 或 curl 手动调一遍接口，确认方法、Headers、Body 都对，再写代码。

嗯，别再问我为什么用 GET 传 JSON 没反应了 —— 先去查 Content-Type。