Python FastAPI入门教程：OAuth2密码流程（带Bearer Token）

欢迎！如果你有基础Python语法知识，但没接触过Web开发，别担心。本教程将带你一步步用FastAPI构建一个简单的Web应用，并实现OAuth2密码流程和Bearer Token认证。我们避免枯燥理论，侧重动手实践，用生活化类比解释概念，确保你每一步都有“成功时刻”！

什么是FastAPI和OAuth2？

• FastAPI：想象成一个超级快捷的“服务生”，帮你快速搭建Python Web服务，它易于使用，性能优秀。
• OAuth2：这是一种授权协议，类比为进入办公楼的门禁系统：你需要用户名和密码（密码流程）获取一个临时通行证（Bearer Token），然后凭此通行证进入不同房间（访问受保护资源）。

先决条件

• 已安装Python（建议3.7+）。
• 基本Python语法知识（如函数、变量）。

第一步：安装FastAPI和相关库

打开终端或命令提示符，运行以下命令。这就像准备工具箱，方便我们后续工作。

pip install fastapi uvicorn passlib python-multipart

解释：

• fastapi：核心框架。
• uvicorn：服务器，用来运行我们的应用。
• passlib：处理密码哈希，就像加密你的密码，更安全。
• python-multipart：用于处理表单数据（如登录信息）。

成功时刻：看到“Successfully installed”消息，你就准备好啦！

第二步：创建一个简单的FastAPI应用

我们先建一个基础应用，感受FastAPI的快速响应。创建一个新文件 main.py，添加以下代码：

from fastapi import FastAPI

app = FastAPI()  # 创建一个FastAPI实例，就像启动我们的“服务生”

@app.get("/")  # 定义一个GET路由，当访问网站根目录时触发
async def home():
    return {"message": "欢迎来到FastAPI世界！你的第一个应用已成功运行！"}

运行应用：在终端中，进入 main.py 所在目录，运行：

uvicorn main:app --reload

打开浏览器访问 http://127.0.0.1:8000，你会看到JSON消息。恭喜，你刚创建了第一个Web服务！

第三步：引入OAuth2密码流程概念

OAuth2密码流程允许用户用用户名和密码直接获取Token。类比：你想进办公楼，前台检查你的身份证（用户名/密码），然后发一个临时通行证（Token）。

在FastAPI中，我们用 OAuth2PasswordBearer 来处理这个流程。

第四步：实现OAuth2密码流程

现在，我们来增强应用，添加用户认证。更新 main.py 代码：

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from pydantic import BaseModel
from passlib.context import CryptContext
from datetime import datetime, timedelta
import jwt  # 需要安装：pip install pyjwt

# 创建FastAPI应用
app = FastAPI()

# 设置密码哈希上下文，类似加密机
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

# 定义OAuth2密码Bearer，就像门禁系统的读卡器
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

# 模拟用户数据库（实际应用中应使用数据库）
fake_users_db = {
    "alice": {
        "username": "alice",
        "hashed_password": pwd_context.hash("secretpassword"),  # 哈希化密码
    }
}

# 用户模型，用于表示用户数据
class User(BaseModel):
    username: str

# Token模型，表示返回的Token
class Token(BaseModel):
    access_token: str
    token_type: str

# 辅助函数：验证密码
async def verify_password(plain_password, hashed_password):
    return pwd_context.verify(plain_password, hashed_password)

# 辅助函数：获取用户
async def get_user(username: str):
    if username in fake_users_db:
        user_dict = fake_users_db[username]
        return User(**user_dict)
    return None

# 生成Token的函数（简单示例，实际应更安全）
def create_access_token(data: dict, expires_delta: timedelta = 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="HS256")
    return encoded_jwt

# 定义Token路由：用户登录获取Token
@app.post("/token", response_model=Token)
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    user = await get_user(form_data.username)
    if not user or not await verify_password(form_data.password, fake_users_db[form_data.username]["hashed_password"]):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="用户名或密码错误",
            headers={"WWW-Authenticate": "Bearer"},
        )
    access_token = create_access_token(data={"sub": form_data.username})
    return {"access_token": access_token, "token_type": "bearer"}

# 受保护的路由：需要Token访问
@app.get("/protected")
async def read_protected(token: str = Depends(oauth2_scheme)):
    # 这里可以添加Token验证逻辑（如解码JWT），但为简化，我们只检查Token存在
    return {"message": "恭喜！你已成功用Bearer Token访问受保护页面！", "token": token}

成功时刻：代码已更新，现在我们来测试。

第五步：测试应用

1. 运行应用：在终端中，确保在 main.py 目录，运行 uvicorn main:app --reload。
2. 打开浏览器或使用工具如Postman测试：
   • 先访问 http://127.0.0.1:8000/protected，你会看到错误，因为需要Token。这模拟了门禁系统拒绝无通行证的人。
   • 然后，发送POST请求到 http://127.0.0.1:8000/token 获取Token。使用表单数据：username=alice, password=secretpassword。
     • 在Postman中，选择Body -> form-data，添加键值对。
     • 响应示例：{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...","token_type":"bearer"}
3. 用获取的Token访问受保护路由：在请求头中添加 Authorization: Bearer <token>，访问 http://127.0.0.1:8000/protected。
   • 成功响应：{"message":"恭喜！你已成功用Bearer Token访问受保护页面！","token":"<token>"}

看！你刚实现了OAuth2密码流程，用Bearer Token保护了路由。就像一个真实的认证系统在工作。

总结

在本教程中，你学会了：

• 安装FastAPI并创建基础应用。
• 理解OAuth2密码流程和Bearer Token的类比（如门禁系统）。
• 实现用户登录、Token生成和保护路由的完整示例。

动手实践是关键——尝试修改代码，比如添加更多用户或延长Token有效期。如果有问题，查阅FastAPI官方文档或社区支持。

继续探索，Web开发不再神秘！通过这个简单起点，你已经建立了信心，可以进一步学习更复杂功能。