FastAPI集成React：JWT匿名会话教程

知识点掌握了，还需要不断练习才能熟练运用。下面golang学习网给大家带来一个文章开发实战，手把手教大家学习《FastAPI与React集成：JWT匿名会话教程》，在实现功能的过程中也带大家重新温习相关知识点，温故而知新，回头看看说不定又有不一样的感悟！

本教程详细阐述了如何在FastAPI后端与React前端项目中实现匿名用户会话管理。通过巧妙利用FastAPI的JWT认证机制，将匿名访问者视为特殊类型的认证用户，生成并验证其专属访问令牌。文章涵盖了匿名用户的“注册”、后续请求识别、状态持久化及前端集成策略，旨在提供一套稳定且可追溯的匿名用户会话解决方案，避免传统Cookie的潜在问题。

理解匿名会话的需求与挑战

在现代Web应用中，为未登录用户提供个性化体验或追踪其行为是常见的需求。例如，记录购物车内容、浏览历史或推荐偏好。实现这一目标的核心是建立并维护一个“匿名会话”。

传统的会话管理常依赖于服务器端Session和基于Cookie的会话ID。然而，在前后端分离的架构（如FastAPI + React）中，尤其涉及跨域请求时，Cookie的SameSite策略、withCredentials选项以及浏览器对第三方Cookie的限制，都可能导致会话管理复杂化或出现“bad request”等错误。

JSON Web Token（JWT）提供了一种更灵活、无状态的认证机制，非常适合处理这类场景。通过将匿名用户的唯一标识嵌入到JWT中，并在每次API请求时携带该令牌，后端可以轻松识别并处理匿名用户的请求，同时避免了传统Cookie的诸多限制。

基于FastAPI JWT实现匿名会话

核心思路是将匿名访问者视为一种特殊的、无需密码验证的“认证用户”。我们利用FastAPI内置的JWT认证体系，为这些匿名用户颁发访问令牌，并在后续请求中通过该令牌识别他们。

1. FastAPI安全模块基础

FastAPI通过fastapi.security模块提供了强大的安全功能，包括OAuth2协议支持和JWT集成。实现匿名会话主要依赖于以下组件：

• JWT (JSON Web Token): 一种开放标准（RFC 7519），定义了如何在各方之间安全地传输信息作为JSON对象。它由三部分组成：Header（头部）、Payload（负载）和Signature（签名）。
• jose库: 用于JWT的编码和解码。
• OAuth2PasswordBearer: 虽然通常用于密码认证，但我们可以利用其解析Authorization: Bearer 头部的能力。

2. 步骤一：匿名用户“注册”与令牌生成

当用户首次访问应用或其匿名会话过期时，后端需要为其生成一个唯一的匿名ID，并基于此ID颁发一个JWT。这个过程类似于用户登录，但无需用户提供任何凭证。

首先，定义JWT相关的配置和辅助函数：

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError, jwt
from datetime import datetime, timedelta
from typing import Optional
import uuid

# JWT配置（在实际应用中，这些配置应从环境变量或配置文件加载）
SECRET_KEY = "your-super-secret-key-that-should-be-very-long-and-random" # 替换为强随机密钥
ALGORITHM = "HS256"
# 匿名会话令牌的有效期，例如30天
ACCESS_TOKEN_EXPIRE_MINUTES = 30 * 24 * 60

# OAuth2PasswordBearer 用于解析请求头中的Bearer Token
# tokenUrl可以是一个虚拟路径，因为匿名用户不通过传统登录获取token
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/token") 

def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
    """
    创建JWT访问令牌
    :param data: 包含要编码到令牌中的数据，通常是用户ID
    :param expires_delta: 令牌的有效期
    :return: 编码后的JWT字符串
    """
    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

app = FastAPI()

@app.post("/anonymous-login", summary="为匿名用户生成访问令牌")
async def anonymous_login():
    """
    当用户首次访问或需要新的匿名会话时，调用此接口生成匿名访问令牌。
    后端会生成一个唯一的匿名ID，并基于此ID创建JWT。
    """
    # 生成一个唯一的匿名用户ID，例如使用UUID
    anonymous_id = f"anonymous_{uuid.uuid4()}"

    # 设置匿名令牌的过期时间
    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)

    # 创建访问令牌，将匿名ID作为JWT的subject (sub)
    access_token = create_access_token(
        data={"sub": anonymous_id}, expires_delta=access_token_expires
    )

    return {"access_token": access_token, "token_type": "bearer"}

3. 步骤二：后续请求中的匿名用户识别

一旦前端获取到匿名用户的JWT，后续所有需要识别匿名身份的API请求都应在Authorization头部携带此令牌。后端通过依赖注入get_current_anonymous_user函数来解析并验证令牌，从而获取匿名用户的ID。

async def get_current_anonymous_user(token: str = Depends(oauth2_scheme)):
    """
    从请求头中解析并验证JWT，获取当前匿名用户的ID。
    如果令牌无效、过期或不包含有效的匿名ID，则抛出认证异常。
    """
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="无法验证凭据，请提供有效的匿名会话令牌",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        # 解码JWT
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])

        # 从payload中获取subject (sub)，即匿名ID
        username: str = payload.get("sub")

        # 验证是否为匿名ID格式（例如以"anonymous_"开头）
        if username is None or not username.startswith("anonymous_"):
            raise credentials_exception

        return username  # 返回匿名ID，如 "anonymous_a1b2c3d4-..."
    except JWTError:
        # JWT解码失败（如签名不匹配、过期等）
        raise credentials_exception

@app.get("/items/", summary="获取商品列表（需匿名或注册用户身份）")
async def read_items(current_anonymous_id: str = Depends(get_current_anonymous_user)):
    """
    一个示例API端点，演示如何使用get_current_anonymous_user来获取匿名用户ID。
    """
    # current_anonymous_id 将是类似 "anonymous_a1b2c3d4-e5f6-7890-abcd-ef1234567890" 的字符串
    # 您现在可以使用这个ID来检索或存储与该匿名用户相关的数据。
    print(f"当前匿名用户ID: {current_anonymous_id}")
    # 根据current_anonymous_id从数据库加载用户历史数据或执行其他逻辑
    return {"message": f"欢迎，匿名用户 {current_anonymous_id}！", "data": "您的个性化商品列表"}

# 示例：一个不需要匿名身份的公共接口
@app.get("/public-data", summary="获取公开数据")
async def get_public_data():
    return {"message": "这是公开数据，无需任何身份验证。"}

4. 步骤三：匿名用户状态的持久化

仅仅识别匿名用户ID是不够的，为了实现“根据用户之前的请求更新其请求”的目标，您需要将这些匿名用户及其相关的行为数据存储到数据库中。

• 数据库模型设计：
  • 创建一个AnonymousUser表，包含id（即JWT中的sub）、created_at、last_active_at等字段。
  • 所有与匿名用户行为相关的数据（如购物车项、浏览历史、收藏、偏好设置）都应通过外键关联到AnonymousUser表的id。
• 数据操作：
  • 在anonymous_login时，如果该anonymous_id首次出现，则在AnonymousUser表中创建一条记录。
  • 在处理read_items等受保护的API时，根据current_anonymous_id从数据库中加载该匿名用户的历史数据，并根据需要更新其last_active_at。

通过这种方式，每次请求时，您可以根据解析出的匿名ID从数据库中加载用户之前的状态，从而实现个性化体验和行为追踪。

前端（React）集成考量

在React应用中，处理匿名会话的关键在于：

1. 在用户首次访问时，或会话过期后，调用后端/anonymous-login接口获取JWT。
2. 将获取到的JWT安全地存储在客户端（例如localStorage）。
3. 在后续所有需要匿名身份的API请求中，将JWT作为Authorization: Bearer 头部发送给后端。

// src/api.js (或一个通用的Axios配置/工具文件)
import axios from 'axios';

const api = axios.create({
    baseURL: 'http://localhost:8000', // 替换为您的FastAPI后端URL
    timeout: 10000,
});

// 请求拦截器：在每次请求前，如果存在匿名令牌，则将其添加到Authorization头部
api.interceptors.request.use(
    config => {
        const token = localStorage.getItem('anonymous_access_token');
        if (token) {
            config.headers.Authorization = `Bearer ${token}`;
        }
        return config;
    },
    error => {
        return Promise.reject(error);
    }
);

// 响应拦截器：处理401（未授权）错误，可能意味着令牌过期或无效
api.interceptors.response.use(
    response => response,
    async error => {
        const originalRequest = error.config;
        if (error.response.status === 401 && !originalRequest._retry) {
            originalRequest._retry = true; // 标记已重试，防止无限循环
            console.warn("匿名会话令牌可能已过期或无效，尝试重新获取...");
            try {
                // 尝试重新获取匿名令牌
                await setupAnonymousSession();
                // 重新发送原始请求
                return api(originalRequest);
            } catch (refreshError) {
                console.error("重新获取匿名令牌失败:", refreshError);
                // 可以在这里重定向到首页或显示错误信息
                localStorage.removeItem('anonymous_access_token'); // 清除无效令牌
                // window.location.reload(); // 刷新页面
                return Promise.reject(refreshError);
            }
        }
        return Promise.reject(error);
    }
);

// 建立匿名会话的函数
export async function setupAnonymousSession() {
    try {
        const response = await api.post('/anonymous-login');
        const { access_token } = response.data;
        localStorage.setItem('anonymous_access_token', access_token);
        console.log('匿名会话已建立或更新:', access_token);
        return access_token;
    } catch (error) {
        console.error('建立匿名会话失败:', error);
        throw error; // 抛出错误以便调用方处理
    }
}

// 示例：获取商品列表
export async function fetchItems() {
    try {
        const response = await api.get('/items/');
        console.log('商品列表获取成功:', response.data);
        return response.data;
    } catch (error) {
        console.error('获取商品列表失败:', error);
        throw error;
    }

好了，本文到此结束，带大家了解了《FastAPI集成React：JWT匿名会话教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！