How do I use Bearer token with Python requests?

在当今的 API 开发与交互中，安全认证是不可忽视的一环。Bearer Token（持有者令牌）作为 OAuth 2.0 协议中最常见的认证方式之一，被广泛应用于 RESTful API 的请求授权。对于 Python 开发者而言，requests 库是 HTTP 请求的首选工具，那么如何正确地在 requests 中使用 Bearer Token 呢？本文将为您提供一份完整的操作指南。

什么是 Bearer Token？

Bearer Token 是一种访问令牌，通常由认证服务器在用户登录后颁发。客户端在请求 API 时，只需在 HTTP 请求头中携带该令牌，服务器便可根据令牌验证请求者的身份和权限。其名称 “Bearer” 意为“持有者”，即“持有令牌即可访问资源”，因此令牌的安全保管至关重要。

在 Python 的 requests 库中，实现 Bearer Token 认证主要有两种方式：手动设置请求头，或者使用内置的 HTTPBearerAuth 类（第三方库 requests-auth 或自定义实现）。最常用且推荐的方式是直接在请求头中添加 Authorization 字段。

基本用法：手动设置请求头

假设您已从认证服务获取到一个有效的 Bearer Token，例如 "your_token_here"。使用 requests 发送 GET 请求时，只需在 headers 参数中指定 Authorization 的值为 "Bearer <token>"：

import requests

token = "your_token_here"
headers = {
    "Authorization": f"Bearer {token}"
}
response = requests.get("https://api.example.com/user/profile", headers=headers)

这里的 f"Bearer {token}" 是 Python 3.6+ 的 f-string 写法，确保 token 正确拼接。如果您的 token 包含换行符或特殊字符，建议先对其进行处理（如 base64 编码），但通常标准 token 直接使用即可。

对于 POST、PUT 等其他 HTTP 方法，同样适用：

data = {"name": "John", "email": "john@example.com"}
response = requests.post("https://api.example.com/users", headers=headers, json=data)

更优雅的方式：使用 Session 对象

如果您的应用需要多次请求同一个 API 且都使用相同的 Bearer Token，建议使用 requests.Session。Session 对象可以跨请求保持某些参数，包括 headers，避免重复设置：

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {token}"})

# 后续所有请求自动携带 token
response1 = session.get("https://api.example.com/data1")
response2 = session.get("https://api.example.com/data2")

这种方式不仅减少了代码冗余，还能利用 Session 的 HTTP 连接池优化性能。注意，Session 对象不是线程安全的，如果有并发需求，请使用 requests.adapters.HTTPAdapter 或考虑使用 requests-threads 等辅助库。

异常处理与 Token 刷新

在实际生产环境中，Bearer Token 往往有时效性（例如 3600 秒后过期）。当使用过期 token 请求 API 时，服务器通常会返回 401 状态码（Unauthorized）。因此，我们需要编写代码检测此类错误并执行 Token 刷新逻辑。

以下是一个简洁的异常处理示例：

import requests

class APIClient:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({"Authorization": f"Bearer {token}"})

    def get_token(self):
        # 实际中此处应调用认证服务的刷新接口
        # 这里简化为返回模拟的新 token
        return "new_token_here"

    def request(self, method, endpoint, **kwargs):
        url = f"{self.base_url}{endpoint}"
        response = self.session.request(method, url, **kwargs)
        if response.status_code == 401:
            # Token 可能过期，尝试刷新
            new_token = self.get_token()
            self.session.headers.update({"Authorization": f"Bearer {new_token}"})
            # 重试请求
            response = self.session.request(method, url, **kwargs)
        response.raise_for_status()
        return response

上述代码中，APIClient 类封装了自动刷新 token 的逻辑。注意：刷新 token 时，通常需要原 token 的 refresh_token（刷新令牌），并且刷新后新 token 会替换旧 token。实际实现中还需要处理重试次数限制，避免死循环。

安全性注意事项

避免硬编码 Token：切勿将 Token 写在源代码中。推荐使用环境变量（如 os.environ.get("API_TOKEN")）、配置文件（需加入 .gitignore）或密钥管理服务（如 HashiCorp Vault）。
使用 HTTPS：始终通过 HTTPS 发送请求，防止 Token 被中间人截获。
Token 销毁：客户端不再使用时，应主动调用 API 销毁 Token（如果有这样的接口），并清空内存中的 Token 变量。
日志脱敏：记录日志时，不要打印完整的 Authorization 头，可用 "Bearer ****" 代替。

总结

在 Python requests 中使用 Bearer Token 认证并不复杂：核心就是设置 Authorization 请求头。通过 Session 对象可以简化重复操作，而额外的异常处理和 Token 刷新逻辑则让程序更健壮。无论您是开发 Web 应用、数据采集脚本还是自动化工具，掌握这一技巧都将帮助您更安全、高效地与 API 交互。随着 OAuth 2.0 和微服务架构的普及，Bearer Token 认证已成为开发者必备的技能之一。

什么是 Bearer Token？

基本用法：手动设置请求头

更优雅的方式：使用 Session 对象

异常处理与 Token 刷新

安全性注意事项

总结

相关阅读