title: JWT令牌：从身份证到代码防伪的奇妙之旅
date: 2025/06/03 23:14:07
updated: 2025/06/03 23:14:07
author: cmdragon

excerpt:
JWT（JSON Web Token）是一种用于安全传输信息的开放标准，由Header、Payload和Signature三部分组成。Header描述算法和令牌类型，Payload存放实际数据，Signature通过密钥和算法生成，确保数据未被篡改。PyJWT库可用于生成和验证JWT令牌，FastAPI框架中可通过OAuth2PasswordBearer实现身份验证。常见问题包括签名验证失败和令牌过期，需确保密钥一致并定期轮换。JWT适用于身份认证和信息交换，但需避免在Payload中存储敏感数据。

categories:

后端开发
FastAPI

tags:

JWT令牌
签名机制
PyJWT库
FastAPI集成
身份认证
安全传输
报错解决方案

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

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

第七章：JWT令牌集成方案

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

1.1 什么是JWT令牌？

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

结构解析：

Header（头部）：描述算法和令牌类型

{
  "alg": "HS256",  // 签名算法（如HS256）
  "typ": "JWT"     // 令牌类型
}

Payload（载荷）：存放实际数据（如用户ID、过期时间）

{
  "sub": "user123",   // 主题（Subject）
  "exp": 1717020000   // 过期时间（Unix时间戳）
}

Signature（签名）：对前两部分的签名，防止数据篡改

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret_key
)

1.2 签名机制的工作原理

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

类比理解：

将JWT想象为一张身份证：

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

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

2.1 环境配置与依赖安装

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

2.2 核心代码实现

步骤1：定义Pydantic模型

from pydantic import BaseModel


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

步骤2：JWT工具类封装

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路由

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

JWT的Signature部分有什么作用？
A. 存放用户数据
B. 防止数据篡改
C. 定义令牌类型
答案：B
解析：签名通过哈希算法验证数据的完整性，确保令牌未被修改。
以下哪种情况会导致ExpiredSignatureError？
A. 使用错误的密钥
B. 令牌的exp字段已过期
C. 令牌格式不正确
答案：B
解析：当当前时间超过exp字段的值时，会触发过期异常。

四、常见报错解决方案

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

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

密钥不匹配
令牌被篡改
解决：

检查SECRET_KEY是否一致
验证令牌是否来自可信来源

问题2：`jwt.exceptions.ExpiredSignatureError`

原因：令牌已过期
解决：

重新获取新令牌
调整ACCESS_TOKEN_EXPIRE_MINUTES的值

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

余下文章内容请点击跳转至个人博客页面或者扫码关注或者微信搜一搜：编程智域前端至全栈交流与成长，阅读完整的文章：JWT令牌：从身份证到代码防伪的奇妙之旅 | cmdragon’s Blog

往期文章归档：

ASCII编码的影响与作用：数字化时代的不可或缺之物

二月 25, 2024

一、ASCII编码的起源 ASCII（American Standard Code for Information Interchange）编码是一种最早用于将字符转换为数字的编码系统。它诞生于20世纪60年代，旨在解决计算机系统之间的字符传输和存储问题。在ASCII编码出现之前，不同的计算机系统使用不同的字符编码，导致字符在系统之间的传输和处理变得困难。 Ascii编码解码 | 一个覆盖广泛主题工具的高效在线平台(amd794.com) https://amd794.com/asciiencordec 二、ASCII编码解决了什么问题 ASCII编码的出现解决了字符传输和存储的标准化问题。它将字符映射为固定的7位二进制数，共计128个字符，包括英文字母、数字、标点符号和控制字符等。这种标准化的编码方式使得不同计算机系统之间可以准确地传输和处理字符数据，大大简化了字符处理的复杂性。三、ASCII编码对现在的影响和作用文本处理：ASCII编码在文本处理中起着重要作用，包括文件存储、数据传输、网络通信等。它成为了计算机系统中最基本的字符表示方式，被广泛应用于各种文本处理场景。编程语言：ASCII编码是大多数编程语言中字符表示的基础。程序员可以使用ASCII编码来处理和操作文本数据，实现各种字符处理的功能。数据库存储：ASCII编码可以用于将文本数据存储在数据库中，方便数据的检索和处理。它提供了一种标准的字符表示方式，使得数据的存储和查询更加方便和高效。跨平台兼容性：ASCII编码是一种标准化的字符编码系统，可以在不同的计算机和操作系统中使用。这种跨平台兼容性使得文本数据能够在不同的环境中无缝传输和处理。多语言处理：尽管ASCII编码只能表示英文字母、数字和一些基本符号，但它为后续的字符编码系统奠定了基础。ASCII编码的发展促使了后续的字符编码系统的出现，满足了多语言文本处理的需求。四、ASCII编码的应用领域电信通信：ASCII编码在电报和传真等通信方式中起着关键作用，实现了字符数据的传输和处理。网络通信：ASCII编码是互联网通信的基础，HTTP协议、电子邮件和网页等都使用ASCII编码来传输和处理文本数据。数据存储与处理：ASCII编码可以用于将文本数据存储在文件和数据库中，方便后续的数据检索和处理。编程语言与脚本：ASCII编码是大多数编程...

阅读全文

搜索此博客

cmdragon's Blog

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

第七章：JWT令牌集成方案

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

1.1 什么是JWT令牌？

结构解析：

1.2 签名机制的工作原理

类比理解：

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

2.1 环境配置与依赖安装

2.2 核心代码实现

步骤1：定义Pydantic模型

步骤2：JWT工具类封装

步骤3：集成到FastAPI路由

三、课后Quiz

四、常见报错解决方案

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

问题2：`jwt.exceptions.ExpiredSignatureError`

往期文章归档：

评论

发表评论

此博客中的热门博文

深入理解 Nuxt.js 中的 app：error 钩子

ASCII编码的影响与作用：数字化时代的不可或缺之物

Nuxt 使用指南：掌握 useNuxtApp 和运行时上下文

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

第七章：JWT令牌集成方案

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

1.1 什么是JWT令牌？

结构解析：

1.2 签名机制的工作原理

类比理解：

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

2.1 环境配置与依赖安装

2.2 核心代码实现

步骤1：定义Pydantic模型

步骤2：JWT工具类封装

步骤3：集成到FastAPI路由

三、课后Quiz

四、常见报错解决方案

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

问题2：jwt.exceptions.ExpiredSignatureError

往期文章归档：

评论

发表评论

此博客中的热门博文

深入理解 Nuxt.js 中的 app：error 钩子

ASCII编码的影响与作用：数字化时代的不可或缺之物

Nuxt 使用指南：掌握 useNuxtApp 和运行时上下文

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

问题2：`jwt.exceptions.ExpiredSignatureError`