logo cmdragon's Blog

JWT令牌：从身份证到代码防伪的奇妙之旅

avatar
cmdragon 大乘
  2025-06-03 23:14:07   2025-06-03 23:14:07   1.7k 字  7 分钟
image image

扫描二维码
关注或者微信搜一搜：编程智域 前端至全栈交流与成长

探索数千个预构建的 AI 应用，开启你的下一个伟大创意：https://tools.cmdragon.cn/

第七章：JWT令牌集成方案

一、JWT令牌的结构与签名机制

1.1 什么是JWT令牌？

JWT（JSON Web Token）是一种开放标准（RFC
7519），用于在各方之间安全地传输信息。它由三部分组成，格式为 Header.Payload.Signature，常用于身份认证和信息交换。

结构解析：

  • Header（头部）：描述算法和令牌类型
    1
    2
    3
    4
    {
      "alg": "HS256",  // 签名算法（如HS256）
      "typ": "JWT"     // 令牌类型
    }
  • Payload（载荷）：存放实际数据（如用户ID、过期时间）
    1
    2
    3
    4
    {
      "sub": "user123",   // 主题（Subject）
      "exp": 1717020000   // 过期时间（Unix时间戳）
    }
  • Signature（签名）：对前两部分的签名，防止数据篡改
    1
    2
    3
    4
    HMACSHA256(
      base64UrlEncode(header) + "." + base64UrlEncode(payload),
      secret_key
    )

1.2 签名机制的工作原理

签名通过密钥（secret_key）和指定算法（如HS256）生成。服务端用密钥验证签名是否合法，确保令牌未被篡改。

类比理解：

将JWT想象为一张身份证：

  • Header = 证件类型（身份证）
  • Payload = 证件信息（姓名、有效期）
  • Signature = 防伪标识（公安局的盖章）

二、PyJWT库的编码/解码实践

2.1 环境配置与依赖安装

1
2
# 安装依赖库（指定版本避免兼容性问题）
pip install fastapi==0.95.0 pydantic==1.10.7 pyjwt==2.7.0

2.2 核心代码实现

步骤1：定义Pydantic模型

1
2
3
4
5
from pydantic import BaseModel


class TokenData(BaseModel):
    username: str | None = None

步骤2：JWT工具类封装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
from datetime import datetime, timedelta
from typing import Optional
import jwt
from jwt.exceptions import ExpiredSignatureError, JWTError

# 配置常量
SECRET_KEY = "your-secret-key-123"  # 生产环境应使用环境变量存储
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30


def create_jwt_token(data: dict) -> str:
    """生成JWT令牌"""
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)


def validate_jwt_token(token: str) -> Optional[TokenData]:
    """验证并解析JWT令牌"""
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if not username:
            return None
        return TokenData(username=username)
    except ExpiredSignatureError:
        raise HTTPException(status_code=401, detail="Token expired")
    except JWTError:
        raise HTTPException(status_code=401, detail="Invalid token")

步骤3：集成到FastAPI路由

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.post("/token")
async def login_for_token(username: str, password: str):
    # 伪代码：实际应查询数据库验证用户
    if not authenticate_user(username, password):
        raise HTTPException(401, "Invalid credentials")
    return {"access_token": create_jwt_token({"sub": username})}


@app.get("/users/me")
async def read_current_user(token: str = Depends(oauth2_scheme)):
    user_data = validate_jwt_token(token)
    if not user_data:
        raise HTTPException(401, "Authentication failed")
    return {"username": user_data.username}

三、课后Quiz

  1. JWT的Signature部分有什么作用？
    A. 存放用户数据
    B. 防止数据篡改
    C. 定义令牌类型
    答案：B
    解析：签名通过哈希算法验证数据的完整性，确保令牌未被修改。

  2. 以下哪种情况会导致ExpiredSignatureError？
    A. 使用错误的密钥
    B. 令牌的exp字段已过期
    C. 令牌格式不正确
    答案：B
    解析：当当前时间超过exp字段的值时，会触发过期异常。

四、常见报错解决方案

问题1：jwt.exceptions.DecodeError: Invalid signature

原因：签名验证失败，可能因为：

  • 密钥不匹配
  • 令牌被篡改
    解决：
  1. 检查SECRET_KEY是否一致
  2. 验证令牌是否来自可信来源

问题2：jwt.exceptions.ExpiredSignatureError

原因：令牌已过期
解决：

  1. 重新获取新令牌
  2. 调整ACCESS_TOKEN_EXPIRE_MINUTES的值

通过本章学习，您已掌握JWT的核心原理和FastAPI集成方法。关键点：始终使用HTTPS传输令牌、避免在Payload中存储敏感数据、定期轮换密钥。

余下文章内容请点击跳转至 个人博客页面 或者 扫码关注或者微信搜一搜：编程智域 前端至全栈交流与成长，阅读完整的文章：

往期文章归档：

JWT令牌：从身份证到代码防伪的奇妙之旅
posts/ec3aa76fc0de/
作者
cmdragon
发布于
2025-06-03 23:14
许可
  1. 1. 第七章：JWT令牌集成方案
    1. 1.1. 一、JWT令牌的结构与签名机制
      1. 1.1.1. 1.1 什么是JWT令牌？
        1. 1.1.1.1. 结构解析：
      2. 1.1.2. 1.2 签名机制的工作原理
        1. 1.1.2.1. 类比理解：
    2. 1.2. 二、PyJWT库的编码/解码实践
      1. 1.2.1. 2.1 环境配置与依赖安装
      2. 1.2.2. 2.2 核心代码实现
        1. 1.2.2.1. 步骤1：定义Pydantic模型
        2. 1.2.2.2. 步骤2：JWT工具类封装
        3. 1.2.2.3. 步骤3：集成到FastAPI路由
    3. 1.3. 三、课后Quiz
    4. 1.4. 四、常见报错解决方案
      1. 1.4.1. 问题1：jwt.exceptions.DecodeError: Invalid signature
      2. 1.4.2. 问题2：jwt.exceptions.ExpiredSignatureError
    5. 1.5. 往期文章归档：
  1. 1. 第七章：JWT令牌集成方案
    1. 1.1. 一、JWT令牌的结构与签名机制
      1. 1.1.1. 1.1 什么是JWT令牌？
        1. 1.1.1.1. 结构解析：
      2. 1.1.2. 1.2 签名机制的工作原理
        1. 1.1.2.1. 类比理解：
    2. 1.2. 二、PyJWT库的编码/解码实践
      1. 1.2.1. 2.1 环境配置与依赖安装
      2. 1.2.2. 2.2 核心代码实现
        1. 1.2.2.1. 步骤1：定义Pydantic模型
        2. 1.2.2.2. 步骤2：JWT工具类封装
        3. 1.2.2.3. 步骤3：集成到FastAPI路由
    3. 1.3. 三、课后Quiz
    4. 1.4. 四、常见报错解决方案
      1. 1.4.1. 问题1：jwt.exceptions.DecodeError: Invalid signature
      2. 1.4.2. 问题2：jwt.exceptions.ExpiredSignatureError
    5. 1.5. 往期文章归档：