Python语言JWT应用

jwt 库是用于 JSON Web Token（JWT）编码与解码 的 Python 库，常用于实现认证和授权功能。最常用的是第三方库 PyJWT，全名是 PyJWT（不要和名称相似的其他库混淆）。它是一个纯 Python 编写的 JWT 实现，兼容 JWT 标准（RFC 7519）。

一、安装

pip install PyJWT

如果需要使用 cryptography（用于非对称加密），可以这样安装：

pip install "PyJWT[crypto]"

二、基本用法

1. 生成（编码）Token

import jwt
import datetime

# 密钥（可以是字符串，也可以是 RSA 私钥）
secret = 'your-secret-key'

# 创建payload（负载）
payload = {
    'user_id': 123,
    'exp': datetime.datetime.utcnow() + datetime.timedelta(hours=1)  # 1小时后过期
}

# 编码成JWT
token = jwt.encode(payload, secret, algorithm='HS256')
print(token)

注意：PyJWT 在 v2.0.0 之后返回的是 str 类型（以前是 bytes）。

2. 解码（验证）Token

decoded = jwt.decode(token, secret, algorithms=['HS256'])
print(decoded)

如果 token 已过期或者签名不正确，会抛出异常（见下方“异常处理”）。

三、常用算法

• 对称加密（简单，密钥一致）： HS256（最常用） HS384 HS512
• 非对称加密（适用于更复杂场景）： RS256（需要公钥/私钥对） RS512 ES256（椭圆曲线）

四、使用非对称加密（RSA）示例

with open('private.pem', 'r') as f:
    private_key = f.read()

with open('public.pem', 'r') as f:
    public_key = f.read()

# 编码
token = jwt.encode(payload, private_key, algorithm='RS256')

# 解码
decoded = jwt.decode(token, public_key, algorithms=['RS256'])

五、异常处理

PyJWT 提供了一系列异常，推荐使用来做安全校验：

import jwt
from jwt import ExpiredSignatureError, InvalidTokenError

try:
    decoded = jwt.decode(token, secret, algorithms=['HS256'])
except ExpiredSignatureError:
    print("Token 已过期")
except InvalidTokenError:
    print("无效的 Token")

六、常见 payload 字段（JWT 标准）

你可以在 payload 中自行添加自定义字段（如 user_id、role）。

七、与 Flask / FastAPI 集成（简略示意）

在 Flask 中作为认证机制：

from flask import request, jsonify
import jwt

def verify_token():
    token = request.headers.get('Authorization', '').replace('Bearer ', '')
    try:
        payload = jwt.decode(token, secret, algorithms=['HS256'])
        return payload
    except jwt.ExpiredSignatureError:
        return jsonify({'error': 'Token expired'}), 401
    except jwt.InvalidTokenError:
        return jsonify({'error': 'Invalid token'}), 401

八、常见问题

• token过期报错？ 需要在 payload 里正确设置 exp，并在 decode 时捕获 ExpiredSignatureError。
• 想设置刷新机制？ 建议将 access_token 设置短期有效，另设 refresh_token（更长有效期），用于获取新 token。
• 不能反解 token？ 需要确保： 解码时算法匹配 密钥一致 Token 没有被篡改 没有过期