Python使用requests库调用API接口的基础教程

在 Python 开发中，与网络上的各类 Web API 进行通信是一项基础且频繁的需求。第三方库 requests 以其直观且符合人类直觉的 API 设计，成为了处理 HTTP/HTTPS 请求的事实标准。无论是向天气服务查询气象数据、调用开放平台获取结构化资源，还是向内部系统推送业务表单，requests 都能用极少的代码行数完成连接建立、参数编码、报文传输与结果解析。本文将从运行环境准备开始，由浅入深介绍如何使用 requests 库发起 GET 与 POST 请求、组织参数和标头、提取响应数据，并建立基础的异常防护机制。

一、准备工作与 HTTP 基础交互模型

调用 API 的本质是客户端与服务端之间遵循 HTTP/HTTPS 协议进行网络报文交换。客户端向指定的 URL 发送一个带有请求方法、头部字段和参数载荷的请求，服务端处理后返回包含状态码和业务数据的响应包。

在编写 Python 代码前，需要确保本地环境中已安装 requests。由于 requests 属于第三方模块，需要通过 Python 包管理工具进行安装。在终端或命令行中执行以下命令：

pip install requests

安装完成后，可以在 Python 脚本或交互式解释器中导入该模块，并打印其版本号以确认环境正常：

import requests

print("requests 库版本号:", requests.__version__)

二、发送 GET 请求与解析响应内容

GET 请求用于从指定的接口地址拉取资源数据。调用 requests.get() 会向目标地址发起请求，并返回一个 Response 对象，所有关于服务器回复的数据都封装在该对象中。

1. 获取响应状态码与文本内容

以下示例向公共测试接口发送 GET 请求，并读取基本信息：

import requests

url = "https://httpbin.org/get"
response = requests.get(url)

# 获取 HTTP 状态码
print("状态码:", response.status_code)

# 获取服务器返回的纯文本内容
print("响应文本前100字符:\n", response.text[:100])

2. 使用 response.json() 直接反序列化数据

绝大多数现代 Web API 都会将数据序列化为 JSON 字符串返回。虽然可以通过 Python 标准库中的 json.loads(response.text) 手动解析，但 requests 提供了更直接的内置方法 response.json()，它会自动检测字符编码并将 JSON 字符串转化为 Python 原生的字典或列表对象：

data = response.json()
print("数据类型:", type(data))
print("客户端IP来源:", data.get("origin"))

3. 传递 URL 查询参数 (Query Parameters)

在调用带有分页、关键词搜索或条件过滤的 GET 接口时，参数通常需要拼接在 URL 问号之后（例如 https://api.example.com/items?page=1&limit=10）。直接通过字符串手动拼接容易遗漏符号，或者因为特殊字符未转义导致 URL 格式非法。requests 允许使用 params 参数传入一个字典，内部会自动完成 URL 编码转换：

import requests

api_url = "https://httpbin.org/get"
query_params = {
    "keyword": "python 教程",
    "page": 2,
    "format": "json"
}

# requests 会自动将字典编码拼接到 URL 后
res = requests.get(api_url, params=query_params)
print("实际请求的完整 URL:", res.url)
# 实际输出将自动完成空格与中文转义: https://httpbin.org/get?keyword=python+%E6%95%99%E7%A8%8B&page=2&format=json

三、发送 POST 请求与提交数据载荷

与主要用于获取数据的 GET 请求不同，POST 请求常用于向服务端提交新数据、触发具有副作用的操作（如用户登录、下单购买、新建记录等）。POST 请求的数据通常承载于 HTTP 报文体（Body）中，而不是直接显式挂在 URL 上。

1. 提交 JSON 格式数据（最常用）

在 RESTful API 开发中，JSON 是最通用的数据交换格式。使用 requests.post() 时，只需将 Python 字典传入 json 参数，库会自动执行以下两件事：

• 将字典序列化为合法的 JSON 字符串放在请求体中；
• 在请求标头中自动添加 Content-Type: application/json。

import requests

post_url = "https://httpbin.org/post"
payload = {
    "title": "requests入门",
    "author": "Python学习者",
    "tags": ["python", "api", "tutorial"]
}

# 提交 JSON 数据
res = requests.post(post_url, json=payload)
result = res.json()

print("服务端接收到的 JSON 数据:", result.get("json"))

2. 提交表单格式数据 (Form-encoded)

某些传统的 Web 接口或用户登录接口要求以表单格式（application/x-www-form-urlencoded）接收数据。此时应使用 data 参数代替 json 参数：

form_data = {
    "username": "user_demo",
    "password": "secret_password"
}

# 提交表单数据
res = requests.post(post_url, data=form_data)
result = res.json()

print("服务端接收到的表单字段:", result.get("form"))

四、定制请求头与身份验证 (Headers & Auth)

许多线上公开接口或私有服务都会对请求头进行校验。常见的情况包括：为了防止爬虫爬取，接口可能校验 User-Agent；为了确认调用方权限，接口要求携带 Authorization 令牌（如 Token、API Key）。

在 requests 中，可以通过 headers 传入字典来自定义任何 HTTP 请求标头：

import requests

custom_headers = {
    # 模拟常见浏览器或声明自身客户端标识
    "User-Agent": "MyApiClient/1.0.0",
    # 声明可接收的响应数据类型
    "Accept": "application/json",
    # 身份令牌（Bearer Token 是目前最常见的授权方式）
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

response = requests.get("https://httpbin.org/headers", headers=custom_headers)
print("服务端识别到的标头信息:\n", response.json())

五、异常处理机制与超时防护

真实的网络环境充满不确定性：域名解析失败、目标服务器宕机、网络丢包抖动或者接口处理缓慢等问题随时可能发生。如果直接裸写网络请求而不进行防御性编码，一旦外部接口出现异常，程序就可能卡死或直接崩溃退出。

1. 强制配置 timeout 超时

在默认情况下，requests 不设置超时时间，这意味着如果目标服务器因假死未能关闭连接，Python 进程可能会无限期挂起。在生产环境与日常脚本中，建议始终显式传入 timeout 参数（单位为秒）：

# timeout=5 表示连接与读取若超过 5 秒未响应则抛出 Timeout 异常
try:
    response = requests.get("https://httpbin.org/delay/2", timeout=5)
except requests.exceptions.Timeout:
    print("错误：请求目标接口超时，请稍后重试。")

2. 使用 raise_for_status() 主动拦截 HTTP 错误

当服务器返回诸如 404（页面不存在）或 500（内部错误）时，requests 并不会主动抛出 Python 异常，而是正常生成 Response 对象。为了避免后续代码盲目解析错误的 HTML 内容，可以调用 response.raise_for_status()：

response = requests.get("https://httpbin.org/status/404")

try:
    # 如果状态码是 4xx 或 5xx，将主动抛出 requests.exceptions.HTTPError
    response.raise_for_status()
    data = response.json()
except requests.exceptions.HTTPError as err:
    print(f"HTTP 请求失败，状态码: {response.status_code}，原因: {err}")

3. 稳健的通用调用模板

将网络连接错误、超时错误、HTTP 状态异常以及 JSON 反序列化错误综合起来，可以得到一个结构严密的标准调用模式：

import requests
from requests.exceptions import ConnectionError, Timeout, HTTPError, RequestException

def fetch_api_data(url, params=None):
    try:
        # 发送请求，限定 5 秒超时
        res = requests.get(url, params=params, timeout=5)
        # 检验状态码是否在 200~299 范围内
        res.raise_for_status()
        # 尝试反序列化 JSON
        return res.json()
    except Timeout:
        print("[错误] 连接目标服务器超时。")
    except ConnectionError:
        print("[错误] 无法连接到服务器，请检查网络或 URL 拼写。")
    except HTTPError as e:
        print(f"[错误] 服务器返回错误状态码: {res.status_code}")
    except ValueError:
        print("[错误] 响应内容非合法 JSON 数据。")
    except RequestException as e:
        print(f"[错误] requests 发生未知网络异常: {e}")
    return None

# 测试调用
data = fetch_api_data("https://httpbin.org/get", {"lang": "zh"})
if data:
    print("成功获取数据:", data.get("args"))

六、常见问题与调试建议

在实际调用 API 时，经常会遇到非预期的错误，以下列出三个最高频的问题及排查方法：

1. 执行 response.json() 抛出 JSONDecodeError 错误

原因分析：这通常意味着服务端返回的内容不是有效的 JSON 格式。最常见的情况是服务端发生了 502 Bad Gateway、504 Gateway Timeout 或 404 Not Found 错误，返回了 HTML 格式的错误提示页，此时尝试将其按 JSON 解析必然失败。

排查方法：在调用 .json() 之前先打印 response.status_code，并查看 response.text[:200]，直接观察返回的原始前缀内容。

2. 接口返回 403 Forbidden 错误

原因分析：403 意味着服务器理解了请求但拒绝执行。通常有两种原因：一是目标网站配置了反爬策略，拦截了 requests 默认的 python-requests/x.x.x 请求头；二是未在请求头中携带有效的认证 Token，或者 Token 已过期。

排查方法：在 headers 中显式补充常见的 User-Agent 标头模拟常规客户端，同时对照官方文档检查 Authorization 的拼写与有效性。

3. 中文响应内容出现乱码

原因分析：requests 会尝试根据 HTTP 标头推断响应编码。如果 HTTP 标头中未指定 charset，它通常会默认按照 ISO-8859-1 解码，从而导致 UTF-8 编码的中文显示为乱码。

排查方法：在读取 response.text 之前，手动指定编码：

response.encoding = "utf-8"
print(response.text)