API接入基础：HTTP协议与请求规范

API（应用程序编程接口）接入的本质是客户端与服务端之间通过HTTP协议进行结构化数据交换。要正确接入一个后端API，必须透彻理解HTTP协议的四个核心要素：URL结构、HTTP方法、请求头和状态码。本章从原理出发，理清这些要素的定义、职责以及在实际开发中如何组合运用。

1.1 URL结构剖析

一个完整的RESTful API URL包含以下组成部分：

• 协议（Scheme）：https://，定义传输加密方式，生产环境必须使用HTTPS。
• 主机（Host）：域名或IP地址，例如 api.example.com。
• 端口（Port）：隐含于协议中（HTTPS默认443，HTTP默认80），显式指定时格式为 :8080。
• 路径（Path）：资源定位，例如 /v2/users。
• 查询参数（Query）：以 ? 开始，key=value 对，多个参数用 & 分隔。

1.2 HTTP方法语义对照表

1.3 请求头（Headers）关键字段

请求头传递元数据和身份凭证，常见的标准头部如下：

1.4 HTTP状态码分类与常见码

状态码指示请求处理结果，是重试决策的直接依据。代码中需要按码值范围区分处理逻辑：

1.5 API请求-响应核心流程

下图展示了一个标准API请求从构造到响应处理的完整链路，明确标出HTTP方法、请求头、URL参数和状态码在整个流程中的参与位置：

1.6 实际接入代码示例

以下是使用Python requests库发起一次标准API请求的完整示例，涵盖URL构造、请求头设置、方法选择和响应码处理：

import requests
import json

# 1. 构造URL与查询参数
base_url = "https://api.example.com/v2"
params = {"page": 1, "limit": 20}

# 2. 设置请求头
headers = {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
    "Content-Type": "application/json",
    "X-Request-ID": "req-20250407-xyz789",
    "Accept": "application/json"
}

# 3. 发起GET请求
response = requests.get(
    url=f"{base_url}/users",
    params=params,
    headers=headers,
    timeout=30
)

# 4. 根据状态码做不同处理
if response.status_code == 200:
    data = response.json()
    print("获取数据成功:", json.dumps(data, indent=2))
elif response.status_code == 429:
    retry_after = response.headers.get("Retry-After", "5")
    print(f"触发限流，建议 {retry_after} 秒后重试")
elif 500 <= response.status_code < 600:
    print(f"服务端错误 {response.status_code}，可触发指数退避重试")
else:
    print(f"客户端错误 {response.status_code}，不重试，检查请求参数")

1.7 调试与常见错误