title: FastAPI认证系统：从零到令牌大师的奇幻之旅

date: 2025/06/06 16:13:06

updated: 2025/06/06 16:13:06

excerpt:

FastAPI认证系统的基础架构包括用户注册、登录认证、权限验证和令牌刷新机制。实现步骤涵盖环境准备、数据库模型定义、安全工具函数、路由实现及API端点保护。通过Swagger UI可测试注册、登录和受保护端点。常见报错如422验证错误和401未授权，可通过检查请求参数和令牌有效性解决。JWT令牌由Header、Payload和Signature组成，密码存储使用哈希函数确保安全性。

categories:

后端开发
FastAPI

tags:

FastAPI
认证系统
JWT
用户注册
权限验证
Swagger UI
安全工具函数

扫描二维码

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

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

第一章：构建FastAPI完整认证系统

1. 认证系统基础架构

现代Web应用的认证系统通常包含以下核心组件：

用户注册模块（处理密码哈希存储）
登录认证流程（JWT令牌颁发）
权限验证中间件（保护API端点）
令牌刷新机制（维护会话有效性）

认证流程示意图：

客户端 → 注册 → 登录获取令牌 → 携带令牌访问API → 服务端验证令牌 → 返回资源

2. 完整实现步骤

2.1 环境准备

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

bash 复制代码

pip install fastapi==0.78.0 uvicorn==0.18.2 python-jose[cryptography]==3.3.0 passlib[bcrypt]==1.7.4 python-multipart==0.0.5

2.2 数据库模型定义

python 复制代码

from pydantic import BaseModel, EmailStr
from typing import Optional


class UserCreate(BaseModel):
    email: EmailStr
    password: str


class UserInDB(UserCreate):
    hashed_password: str


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


class TokenData(BaseModel):
    email: Optional[EmailStr] = None

2.3 安全工具函数

python 复制代码

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

SECRET_KEY = "your-secret-key-here"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")


def verify_password(plain_password: str, hashed_password: str):
    return pwd_context.verify(plain_password, hashed_password)


def get_password_hash(password: str):
    return pwd_context.hash(password)


def create_access_token(data: dict):
    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)

2.4 路由实现

python 复制代码

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

router = APIRouter()

# 模拟数据库
fake_users_db = {}


@router.post("/register", response_model=UserInDB)
async def register(user: UserCreate):
    if user.email in fake_users_db:
        raise HTTPException(status_code=400, detail="Email already registered")

    hashed_password = get_password_hash(user.password)
    user_db = UserInDB(**user.dict(), hashed_password=hashed_password)
    fake_users_db[user.email] = user_db.dict()
    return user_db


@router.post("/login", response_model=Token)
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    user_data = fake_users_db.get(form_data.username)
    if not user_data or not verify_password(form_data.password, user_data["hashed_password"]):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials",
            headers={"WWW-Authenticate": "Bearer"},
        )

    access_token = create_access_token(data={"sub": user_data["email"]})
    return {"access_token": access_token, "token_type": "bearer"}

2.5 保护API端点

python 复制代码

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="login")


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])
        email: str = payload.get("sub")
        if email is None:
            raise credentials_exception
    except JWTError:
        raise credentials_exception

    user = fake_users_db.get(email)
    if user is None:
        raise credentials_exception
    return user


@router.get("/protected")
async def protected_endpoint(current_user: UserInDB = Depends(get_current_user)):
    return {
        "message": f"Hello {current_user['email']}",
        "protected_data": "Sensitive information here"
    }

3. 使用Swagger UI测试

3.1 启动应用

创建main.py：

python 复制代码

from fastapi import FastAPI

app = FastAPI()
app.include_router(router, prefix="/api")

if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8000)

3.2 测试流程

访问 http://localhost:8000/docs
测试注册接口：
- 请求体：
测试登录接口获取令牌
点击"Authorize"按钮，输入获取的JWT令牌
测试/protected端点

成功响应示例：

json 复制代码

{
  "message": "Hello [email protected]",
  "protected_data": "Sensitive information here"
}

4. 常见报错解决方案

4.1 422 Validation Error

现象：请求参数不符合验证规则
解决方案：

检查请求体是否符合定义的Pydantic模型
验证email格式是否正确（必须包含@符号）
确保密码字段存在且长度合适

4.2 401 Unauthorized

原因：

缺失Authorization头
令牌过期
无效的签名
处理步骤：

检查请求头是否包含Authorization: Bearer <token>
重新获取有效令牌
验证密钥和算法是否匹配

课后Quiz

Q1：为什么在用户注册时要存储密码哈希而不是明文？

A：防止数据库泄露导致用户密码暴露，哈希函数不可逆，提高系统安全性

Q2：JWT令牌包含哪三个主要组成部分？

A：Header（元数据）、Payload（有效载荷）、Signature（签名验证）

Q3：如何实现自动刷新令牌？

A：可以通过以下两种方式实现：

在令牌payload中添加refresh_token字段
单独提供/refresh端点，使用长期有效的刷新令牌获取新的访问令牌

Q4：访问/protected端点时出现403错误可能是什么原因？

A：可能原因包括：

令牌已过期（超过30分钟）
令牌签名与服务端密钥不匹配
令牌中的用户信息不存在于数据库

余下文章内容请点击跳转至个人博客页面或者扫码关注或者微信搜一搜：编程智域前端至全栈交流与成长，阅读完整的文章：FastAPI认证系统：从零到令牌大师的奇幻之旅 | cmdragon's Blog

FastAPI认证系统：从零到令牌大师的奇幻之旅

第一章：构建FastAPI完整认证系统

1. 认证系统基础架构

2. 完整实现步骤

2.1 环境准备

2.2 数据库模型定义

2.3 安全工具函数

2.4 路由实现

2.5 保护API端点

3. 使用Swagger UI测试

3.1 启动应用

3.2 测试流程

4. 常见报错解决方案

4.1 422 Validation Error

4.2 401 Unauthorized

课后Quiz

往期文章归档：