title: JWT令牌如何在FastAPI中实现安全又高效的生成与验证？
date: 2025/06/10 09:02:35
updated: 2025/06/10 09:02:35
author: cmdragon

excerpt:
JWT（JSON Web Token）是一种用于安全传递声明信息的开放标准，由头部、载荷和签名三部分组成。在FastAPI中，JWT常用于用户身份认证、API授权和跨服务通信。通过python-jose库生成和验证JWT，核心步骤包括配置安全参数、生成访问令牌、实现登录接口和验证机制。令牌生成时需设置过期时间以防止长期盗用，验证时通过中间件检查令牌的有效性。此外，可通过刷新令牌机制更新访问令牌，确保系统的安全性和用户体验。

categories:

后端开发
FastAPI

tags:

JWT
FastAPI
令牌生成
令牌验证
身份认证
安全通信
无状态会话

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

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

第四章：JWT 令牌的生成与验证机制

1. JWT 基础概念

JSON Web Token（JWT）是一种开放标准（RFC 7519），用于在双方之间安全地传递声明信息。它由三部分组成：

Header（头部）：描述算法和令牌类型
Payload（载荷）：携带用户数据（如用户ID）和声明（如过期时间）
Signature（签名）：用于验证令牌完整性的加密字符串

JWT 在 FastAPI 中的典型应用场景：

用户身份认证
API 接口授权
跨服务的安全通信
无状态会话管理

2. 环境准备

安装所需依赖库（推荐使用虚拟环境）：

pip install fastapi==0.95.2 python-jose[cryptography]==3.3.0 passlib==1.7.4 bcrypt==4.0.1 uvicorn==0.22.0

3. 生成 JWT 令牌

3.1 核心配置类

from datetime import datetime, timedelta
from jose import JWTError, jwt
from passlib.context import CryptContext
from pydantic import BaseModel

# 安全配置
SECRET_KEY = "your-secret-key-here"  # 生产环境应从环境变量获取
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

# 密码哈希配置
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")


class Token(BaseModel):
    access_token: str
    token_type: str


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

3.2 令牌生成函数

def create_access_token(data: dict, expires_delta: timedelta | None = None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.utcnow() + expires_delta
    else:
        expire = datetime.utcnow() + timedelta(minutes=15)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt

3.3 登录接口实现

from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm

router = APIRouter()


@router.post("/token", response_model=Token)
async def login_for_access_token(form_data: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(fake_users_db, form_data.username, form_data.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
            headers={"WWW-Authenticate": "Bearer"},
        )
    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    access_token = create_access_token(
        data={"sub": user.username}, expires_delta=access_token_expires
    )
    return {"access_token": access_token, "token_type": "bearer"}

4. JWT 验证机制

4.1 令牌验证中间件

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


async def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
        token_data = TokenData(username=username)
    except JWTError:
        raise credentials_exception
    user = get_user(fake_users_db, username=token_data.username)
    if user is None:
        raise credentials_exception
    return user

4.2 受保护路由示例

@router.get("/users/me/")
async def read_users_me(current_user: User = Depends(get_current_user)):
    return current_user

5. 令牌刷新机制

实现令牌刷新接口：

@router.post("/refresh")
async def refresh_token(refresh_token: str):
    try:
        payload = jwt.decode(refresh_token, SECRET_KEY, algorithms=[ALGORITHM])
        username = payload.get("sub")
        if username is None:
            raise HTTPException(status_code=400, detail="Invalid token")

        # 检查用户是否存在（需要实现具体数据库查询）
        user = get_user(username)
        if not user:
            raise HTTPException(status_code=404, detail="User not found")

        new_token = create_access_token(data={"sub": user.username})
        return {"access_token": new_token}

    except JWTError:
        raise HTTPException(status_code=401, detail="Invalid token")

课后Quiz

为什么JWT需要设置过期时间？
A) 减少服务器内存占用
B) 防止令牌被长期盗用
C) 提高加密强度
D) 简化开发流程
以下哪个做法会破坏JWT的安全性？
A) 使用HTTPS传输令牌
B) 将敏感数据存储在Payload中
C) 定期轮换加密密钥
D) 验证签名算法
如何处理令牌过期的情况？
A) 返回500错误
B) 要求用户重新登录
C) 使用refresh token获取新令牌
D) 自动延长过期时间

答案：

B - 设置过期时间可限制令牌有效期，降低被盗用后的风险
B - Payload内容虽然被加密但可被解码，不应存储敏感信息
C - 最佳实践是通过refresh token机制更新访问令牌

常见报错解决方案

401 Unauthorized: Could not validate credentials
- 原因：无效的令牌格式或签名不匹配
- 解决：检查请求头的Bearer token格式，验证密钥一致性
422 Validation Error
- 原因：请求体与Pydantic模型不匹配
- 预防：使用精确的模型定义，添加字段验证规则
500 Internal Server Error: JWTError
- 原因：令牌解码失败或算法不匹配
- 处理：捕获JWTError异常，返回401状态码
- 检查：确保服务端使用的算法与生成令牌时一致
AttributeError: 'NoneType' has no attribute 'username'
- 原因：数据库查询返回空值
- 修复：在数据库查询后添加空值检查
- 优化：使用Optional类型注解和空值处理

最佳实践建议：

生产环境使用RSA非对称加密（RS256算法）
将密钥存储在环境变量或密钥管理服务中
设置合理的令牌有效期（通常访问令牌15分钟，刷新令牌7天）
实现令牌撤销清单（黑名单机制）

余下文章内容请点击跳转至个人博客页面或者扫码关注或者微信搜一搜：编程智域前端至全栈交流与成长，阅读完整的文章：JWT令牌如何在FastAPI中实现安全又高效的生成与验证？ | 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令牌如何在FastAPI中实现安全又高效的生成与验证？