上一篇
http形式的api接口怎么用？http接口调用方法详解
HTTP API（应用程序编程接口）是目前互联网服务中最主流的数据交互方式，它基于请求-响应模型，利用标准的 HTTP 协议进行通信，具有跨平台、易调试、生态丰富等优势，以下是对 HTTP API 的详细解析，涵盖核心概念、常用方法、状态码、数据格式及最佳实践。
核心概念与工作原理
HTTP API 的本质是客户端（如浏览器、移动 App、其他服务器）向服务器发送 HTTP 请求，服务器处理请求后返回 HTTP 响应，这种交互是无状态的（Stateless），意味着每次请求都是独立的，服务器不会保留之前的会话信息（除非通过 Token 或 Session 机制显式管理）。
- 客户端：发起请求的一方。
- 服务器：接收请求并返回数据的一方。
- 端点（Endpoint）：API 的具体访问地址，通常由域名加路径组成（https://api.example.com/users）。
常用 HTTP 方法（动词）
HTTP 方法定义了客户端对资源执行的操作，在 RESTful API 设计中，通常遵循以下映射关系：
| HTTP 方法 | 语义 | 常见用途 | 幂等性 |
|---|---|---|---|
| GET | 获取 | 查询数据，如获取用户列表、文章详情，不应修改服务器状态。 | 是 |
| POST | 创建 | 提交新数据，如注册新用户、发布文章。 | 否 |
| PUT | 更新/替换 | 全量更新资源，或创建指定 ID 的资源，通常要求客户端提供完整资源数据。 | 是 |
| PATCH | 局部更新 | 部分更新资源，只发送需要修改的字段。 | 否 |
| DELETE | 删除 | 删除指定资源。 | 是 |
注意：虽然 HTTP 规范允许在 GET 请求中携带 Body，但在实际 API 设计中，强烈建议 GET 请求仅用于获取数据，且不带 Body，以避免兼容性问题和安全风险。
请求与响应结构
请求结构
一个标准的 HTTP 请求包含以下部分：
- 请求行：包含方法、URL 和 HTTP 版本。
- 请求头（Headers）：元数据，如 Content-Type（数据格式）、Authorization（认证信息）、Accept（期望返回的格式）。
- 请求体（Body）：仅 POST、PUT、PATCH 等方法通常包含，用于传输数据。
响应结构
- 状态码（Status Code）：三位数字，表示请求结果。
- 响应头（Headers）：如 Content-Type、Cache-Control、Set-Cookie。
- 响应体（Body）：实际返回的数据，通常为 JSON 或 XML。
常见 HTTP 状态码
状态码分为五类,API 开发者应重点关注 2xx 和 4xx/5xx 类：
| 类别 | 范围 | 含义 | 示例 |
|---|---|---|---|
| 2xx | 200-299 | 成功 | 200 OK（成功）、201 Created（资源创建成功）、204 No Content（成功但无返回体） |
| 3xx | 300-399 | 重定向 | 301 Moved Permanently、304 Not Modified（缓存命中） |
| 4xx | 400-499 | 客户端错误 | 400 Bad Request（参数错误）、401 Unauthorized（未认证）、403 Forbidden（无权限）、404 Not Found（资源不存在） |
| 5xx | 500-599 | 服务器错误 | 500 Internal Server Error（服务器内部错误）、502 Bad Gateway、503 Service Unavailable |
数据格式：JSON 与 XML
JSON（JavaScript Object Notation） 是 HTTP API 事实上的标准数据交换格式，因其轻量、易读且与 JavaScript 原生兼容。
JSON 示例：
{ "code": 200, "message": "success", "data": { "id": 1001, "username": "alice", "email": "alice@example.com" } }
XML 示例：
<response> <code>200</code> <message>success</message> <data> <id>1001</id> <username>alice</username> <email>alice@example.com</email> </data> </response>
API 设计最佳实践
- 使用名词复数表示资源：URL 应代表资源集合，如 /users 而不是 /getUser。
- 使用子资源表示关联：如获取特定用户的订单，使用 /users/1001/orders。
- 版本控制：在 URL 中嵌入版本号，如 /v1/users，以便在不破坏现有客户端的情况下迭代 API。
- 过滤、排序与分页：通过查询参数实现，如 /users?status=active&sort=-created_at&page=2&limit=20。
- 统一错误响应格式：所有错误应返回一致的结构，便于前端统一处理。
- 安全性：
- 始终使用 HTTPS 加密传输。
- 实施身份验证（如 JWT、OAuth 2.0）。
- 实施速率限制（Rate Limiting）防止滥用。
- 验证所有输入数据,防止载入攻破。
常见问题排查
- CORS 错误：浏览器出于安全考虑，禁止跨域请求，服务器需配置 Access-Control-Allow-Origin 等头信息。
- 401 vs 403：401 表示“你是谁？”（未认证），403 表示“我知道你是谁，但你没权限做这个”（已认证但无权限）。
- 幂等性误解：PUT 是幂等的（多次执行结果相同），POST 不是幂等的（多次执行会创建多个资源）。
相关问题与解答
问题 1：在 HTTP API 中，GET 请求和 POST 请求的主要区别是什么？为什么不建议在 GET 请求中发送敏感数据？
解答：
主要区别在于语义和安全性：
- 语义不同：GET 用于获取资源，不应改变服务器状态；POST 用于创建新资源或执行操作，通常会改变服务器状态。
- 数据位置不同：GET 请求的数据通常放在 URL 查询参数（Query String）中，而 POST 请求的数据放在请求体（Body）中。
- 安全性：GET 请求的 URL 会被浏览器历史记录、服务器日志、代理服务器缓存等记录，如果敏感数据（如密码、身份证号）放在 GET 参数中，这些日志中可能会明文存储敏感信息，造成泄露风险，URL 长度有限制，不适合传输大量数据，敏感数据必须通过 POST（或 PUT/PATCH）的请求体传输，并配合 HTTPS 加密。
问题 2：什么是 RESTful API？它与传统的 RPC（远程过程调用）风格 API 有什么区别？
解答：
RESTful API 是一种基于 REST（Representational State Transfer，表述性状态转移）架构风格的 API 设计范式，其核心特点包括：
- 资源导向：URL 代表资源（名词），HTTP 方法代表操作（动词）。
- 无状态：每次请求包含处理所需的所有信息，服务器不保存客户端上下文。
- 统一接口：使用标准的 HTTP 方法、状态码和数据格式。
与 RPC 风格 API 的主要区别：
- URL 设计：RPC 风格通常使用动词，如 /getUser、/createOrder；RESTful 使用资源名词，如 /users、/orders，并通过 HTTP 方法区分操作。
- 耦合度：RPC 往往更紧密地耦合于特定的编程语言或框架（如 gRPC、SOAP）；RESTful 基于标准 HTTP，具有更好的跨语言和跨平台兼容性。
- 缓存支持：RESTful API 天然支持 HTTP 缓存机制（通过 Cache-Control 等头），而 RPC 通常需要自定义缓存策略。
- 适用场景：RESTful 适合面向公众的 Web 服务、移动端后端；RPC 适合高性能、低延迟的内部微服务通信（如 gRPC）。
