Python requests 库终极教程

requests 是 Python 中最流行、最优雅的 HTTP 库，它比 Python 内置的 urllib 库更简单、更人性化，让你能以极少的代码完成复杂的 HTTP 请求。

目录

1. 准备工作：安装 requests
2. 第一个请求：GET 请求
   • 发送请求
   • 响应对象 (Response)
   • 获取响应内容 (text, content, json())
3. 查询参数
4. 响应头与请求头
5. POST 请求：发送数据
   • 发送表单数据
   • 发送 JSON 数据
6. 处理响应状态码
7. 处理超时和错误
8. 高级主题
   • 会话 (Session) 对象
   • 身份验证
   • 代理设置
9. 最佳实践与总结

准备工作：安装 requests

requests 库不是 Python 的标准库，需要单独安装，打开你的终端或命令行，运行以下命令：

pip install requests

第一个请求：GET 请求

GET 请求是最常见的请求类型，用于从服务器获取数据。

发送请求

import requests
# 目标 URL
url = 'https://httpbin.org/get'
# 发送 GET 请求
response = requests.get(url)
# 打印响应对象
print(response)
# <Response [200]>
# [200] 是 HTTP 状态码，表示请求成功

响应对象 (Response)

当你调用 requests.get() 后，它会返回一个 Response 对象，这个对象包含了服务器对请求的所有响应信息。

• response.status_code: HTTP 状态码 (如 200, 404, 500)。
• response.headers: 响应头，是一个类字典对象。
• response.text: 响应体的文本内容。
• response.content: 响应体的二进制内容。
• response.json(): 如果响应体是 JSON 格式，这个方法会将其解析为 Python 字典。

让我们来获取并解析响应内容。

import requests
import json # 用于对比
url = 'https://httpbin.org/get'
response = requests.get(url)
# 1. 检查请求是否成功
if response.status_code == 200:
    print("请求成功！")
    # 2. 获取响应文本
    print("\n--- 响应文本 (text) ---")
    print(response.text)
    # 注意：response.text 是解码后的字符串，可能包含特殊字符
    # 3. 获取 JSON 内容 (推荐)
    # httpbin.org/get 返回的 JSON 中包含了请求的 URL 和参数
    print("\n--- 解析后的 JSON 内容 (json()) ---")
    response_data = response.json()
    print(response_data)
    # 这是一个标准的 Python 字典
    print(f"请求的 URL 是: {response_data['url']}")
    # 4. 获取二进制内容 (下载图片)
    # image_url = 'https://www.python.org/static/community_logos/python-logo-master-v3-TM.png'
    # img_response = requests.get(image_url)
    # if img_response.status_code == 200:
    #     with open('python_logo.png', 'wb') as f:
    #         f.write(img_response.content)
    #     print("\n图片下载成功！")
else:
    print(f"请求失败，状态码: {response.status_code}")

查询参数

当你需要向 URL 添加查询参数时（?key1=value1&key2=value2），手动拼接 URL 既麻烦又容易出错。requests 提供了简单的方法。

import requests
# 目标基础 URL
url = 'https://httpbin.org/get'
# 准备查询参数
params = {
    'name': 'John Doe',
    'age': 30,
    'is_student': False
}
# 发送带有查询参数的 GET 请求
# requests 会自动帮你将 params 字典拼接成正确的 URL 格式
response = requests.get(url, params=params)
if response.status_code == 200:
    # 查看实际请求的 URL
    print(f"请求的 URL: {response.url}")
    # 获取并打印 JSON 响应
    data = response.json()
    print("\n服务器收到的参数:")
    print(data['args'])
    # {'age': '30', 'is_student': 'False', 'name': 'John Doe'}

响应头与请求头

查看响应头

import requests
url = 'https://httpbin.org/get'
response = requests.get(url)
# 响应头是一个类似字典的对象
print("响应头:")
print(response.headers)
print("\nContent-Type 响应头:", response.headers['Content-Type'])

设置请求头

有些网站需要特定的请求头才能正常访问,例如模拟浏览器访问。

import requests
url = 'https://httpbin.org/get'
# 准备自定义请求头
headers = {
    'User-Agent': 'MyCoolApp/1.0',
    'Accept-Language': 'en-US,en;q=0.9'
}
# 发送带有自定义请求头的 GET 请求
response = requests.get(url, headers=headers)
if response.status_code == 200:
    data = response.json()
    print("服务器收到的请求头:")
    print(data['headers'])
    # 你会看到 'User-Agent' 和 'Accept-Language' 已经被发送

POST 请求：发送数据

POST 请求通常用于向服务器提交数据，例如提交表单或上传文件。

发送表单数据

表单数据通常以 application/x-www-form-urlencoded 格式发送。

import requests
url = 'https://httpbin.org/post'
# 准备要发送的表单数据 (字典格式)
payload = {
    'username': 'test_user',
    'password': '123456'
}
# 发送 POST 请求，data 参数用于表单数据
response = requests.post(url, data=payload)
if response.status_code == 200:
    data = response.json()
    print("服务器收到的表单数据:")
    print(data['form'])
    # {'password': '123456', 'username': 'test_user'}

发送 JSON 数据

在 API 交互中，更常见的是发送 JSON 格式的数据。

import requests
import json # 虽然requests可以自动处理，但明确写出是好习惯
url = 'https://httpbin.org/post'
# 准备要发送的 JSON 数据 (字典格式)
payload = {
    'name': 'Jane Doe',
    'email': 'jane.doe@example.com',
    'skills': ['Python', 'Data Analysis']
}
# 发送 POST 请求
# 1. json 参数：requests 会自动将字典序列化为 JSON 字符串，
#    并设置正确的请求头 'Content-Type: application/json'
response = requests.post(url, json=payload)
# 2. 手动方式 (效果相同):
# headers = {'Content-Type': 'application/json'}
# response = requests.post(url, data=json.dumps(payload), headers=headers)
if response.status_code == 200:
    data = response.json()
    print("服务器收到的 JSON 数据:")
    print(data['json'])
    # {'email': 'jane.doe@example.com', 'name': 'Jane Doe', 'skills': ['Python', 'Data Analysis']}

处理响应状态码

import requests
url = 'https://httpbin.org/status/404' # 这是一个会返回 404 的测试 URL
try:
    response = requests.get(url)
    response.raise_for_status() # 如果状态码不是 200，会抛出 HTTPError 异常
except requests.exceptions.HTTPError as err:
    print(f"HTTP 错误: {err}")
except requests.exceptions.ConnectionError as err:
    print(f"连接错误: {err}")
except requests.exceptions.Timeout as err:
    print(f"请求超时: {err}")
except requests.exceptions.RequestException as err:
    print(f"发生了一个错误: {err}")
else:
    print("请求成功！")
    print(response.text)

处理超时和错误

网络请求可能会因为各种原因失败,如连接超时、读取超时等。

import requests
# 设置超时时间 (秒)
# connect: 连接服务器的超时时间
# read: 从服务器读取数据的超时时间
try:
    # 请求一个不存在的网站，会触发超时或连接错误
    response = requests.get('http://example.com/nonexistent', timeout=5)
    print(response.text)
except requests.exceptions.Timeout:
    print("请求超时！")
except requests.exceptions.RequestException as e:
    print(f"其他请求错误: {e}")

高级主题

会话 (Session) 对象

当你需要向同一个主机发送多个请求时,使用 Session 对象非常有用，它会保持一个连接（connection pooling），并自动处理 cookies，这能显著提高性能。

import requests
# 创建一个 Session 对象
with requests.Session() as session:
    # 1. 设置会话级别的参数 (如 headers)
    session.headers.update({'User-Agent': 'MyApp/1.0'})
    # 2. 第一次请求，服务器可能会设置一个 cookie
    response1 = session.get('https://httpbin.org/cookies/set/sessioncookie/123456789')
    print(f"第一次请求的 Cookies: {response1.cookies.get_dict()}")
    # 3. 第二次请求到同一个主机，Session 会自动带上之前设置的 cookie
    response2 = session.get('https://httpbin.org/cookies')
    print("第二次请求的响应:")
    print(response2.json())
    # 你会看到 'sessioncookie': '123456789' 在返回的 cookies 中

身份验证

对于需要用户名/密码或 API Token 的网站，requests 提供了便捷的认证方式。

import requests
from requests.auth import HTTPBasicAuth
# --- 基本身份验证 ---
url = 'https://httpbin.org/basic-auth/user/pass'
username = 'user'
password = 'pass'
# 方法一：使用 auth 参数
# response = requests.get(url, auth=(username, password))
# 方法二：使用 HTTPBasicAuth
response = requests.get(url, auth=HTTPBasicAuth(username, password))
if response.status_code == 200:
    print("基本身份验证成功！")
    print(response.json())
else:
    print("基本身份验证失败。")
# --- API Token 认证 (常见于 REST API) ---
# 通常通过自定义请求头传递
api_url = 'https://api.github.com'
token = 'YOUR_GITHUB_TOKEN' # 替换成你的 token
headers = {
    'Authorization': f'token {token}',
    'Accept': 'application/vnd.github.v3+json'
}
response = requests.get(f"{api_url}/user", headers=headers)
if response.status_code == 200:
    print("\nAPI Token 认证成功！")
    print(f"用户名: {response.json()['login']}")
else:
    print(f"\nAPI Token 认证失败，状态码: {response.status_code}")
    print(response.text)

代理设置

如果你需要通过代理服务器发送请求,可以这样配置：

import requests
proxies = {
  'http': 'http://10.10.1.10:3128',
  'https': 'http://10.10.1.10:1080',
}
# requests.get('http://example.com', proxies=proxies)

最佳实践与总结

1. 总是检查状态码：使用 if response.status_code == 200: 或 response.raise_for_for_status() 来确保请求成功。
2. 使用 with 语句管理 Session：确保会话被正确关闭，释放资源。
3. 处理异常：将你的 requests 调用放在 try...except 块中，以应对网络问题。
4. 设置合理的超时：永远不要让你的请求无限期等待，为生产代码设置一个超时时间（如 timeout=10）。
5. 理解 data vs json：
   • data: 用于发送 application/x-www-form-urlencoded 编码的表单数据。
   • json: 用于发送 application/json 编码的 JSON 数据，requests 会自动处理序列化和请求头。
6. 为敏感信息使用环境变量：不要在代码中硬编码 API Key、密码等敏感信息，使用 os.getenv() 从环境变量中读取。

恭喜！你已经掌握了 Python requests 库的核心用法，从简单的数据获取到复杂的 API 交互，requests 都能让你轻松应对，现在你可以开始用它来构建自己的网络爬虫或与各种 Web 服务进行交互了！