Python初学者FastAPI入门：掌握安全依赖项与权限检查

引言

欢迎来到FastAPI入门教程！如果你有基础Python语法知识，但对Web开发感到陌生，别担心，我们会一步步带你上手。FastAPI是一个现代、快速（高性能）的Web框架，用于构建API。在本教程中，我们将重点学习安全依赖项和权限检查，确保你的API既强大又安全。

类比：想象一下你开了一家咖啡店（你的API）。顾客（客户端）来点咖啡（发送请求），你需要确保只有授权的顾客才能点特殊饮品（受保护的资源）。依赖项就像店里的员工，帮你检查顾客的ID（权限）。

第一步：设置环境

首先，确保你安装了Python（建议版本3.7+）。然后，使用pip安装FastAPI和Uvicorn（一个ASGI服务器，用于运行FastAPI应用）：

pip install fastapi uvicorn

成功时刻：运行命令后，看到安装成功信息（如“Successfully installed fastapi-0.104.1 uvicorn-0.24.0”），你就迈出了第一步！

第二步：创建你的第一个API

创建一个新文件，命名为 main.py，并添加以下代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

运行服务器：

uvicorn main:app --reload

打开浏览器，访问 http://127.0.0.1:8000，你会看到 {"message": "Hello, World!"} 显示在屏幕上。恭喜，你的第一个API运行成功！这是一个关键的“成功时刻”——你刚刚构建了一个简单的Web服务。

第三步：理解路由和请求

在FastAPI中，路由定义了URL路径和处理函数。类比：路由就像咖啡店的菜单，每个菜单项（路径）对应一个饮品（处理函数）。

添加另一个路由，使用路径参数：

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

现在，访问 http://127.0.0.1:8000/items/42，你会看到 {"item_id": 42}。这展示了如何使用路径参数来动态处理请求。

第四步：引入安全依赖项

FastAPI使用依赖注入来管理共享逻辑，如认证。依赖项是函数或类，可以被多个路由重用，让代码更模块化和易于测试。

创建一个简单的认证依赖项，检查请求头中的令牌：

from fastapi import Depends, HTTPException, Header

def verify_token(token: str = Header(...)):
    if token != "secret-token":
        raise HTTPException(status_code=401, detail="Invalid token")
    return token

@app.get("/secure")
def secure_endpoint(token: str = Depends(verify_token)):
    return {"message": "Access granted!", "token": token}

解释：verify_token 函数是一个依赖项，它检查传入的 token 头。如果令牌无效（不等于“secret-token”），它抛出一个HTTP异常（401错误）；否则返回令牌。在 /secure 端点中，我们使用 Depends(verify_token) 来调用这个依赖项。

测试：使用工具如curl或浏览器扩展（如Postman）发送GET请求到 http://127.0.0.1:8000/secure，并添加Header token: secret-token。你会看到 {"message": "Access granted!", "token": "secret-token"}。如果省略或使用错误令牌，你会收到401错误。这是另一个“成功时刻”——你实现了基本的权限检查！

第五步：权限检查更深入

权限检查可以更复杂，例如基于用户角色。我们来模拟一个简单的用户系统。

首先，定义用户模型和角色：

from pydantic import BaseModel
from enum import Enum

class UserRole(str, Enum):
    ADMIN = "admin"
    USER = "user"

class User(BaseModel):
    username: str
    role: UserRole

然后，创建一个依赖项来获取当前用户信息（基于令牌）：

def get_current_user(token: str = Header(...)) -> User:
    # 模拟从令牌中获取用户信息（实际应用中可能连接数据库）
    if token == "admin-token":
        return User(username="alice", role=UserRole.ADMIN)
    elif token == "user-token":
        return User(username="bob", role=UserRole.USER)
    else:
        raise HTTPException(status_code=401, detail="Invalid token")

接下来，创建一个依赖项来检查用户是否是管理员：

def require_admin(user: User = Depends(get_current_user)):
    if user.role != UserRole.ADMIN:
        raise HTTPException(status_code=403, detail="Admin access required")
    return user

现在，添加一个只有管理员才能访问的端点：

@app.get("/admin-only")
def admin_only(user: User = Depends(require_admin)):
    return {"message": f"Welcome admin {user.username}!"}

测试：

• 发送GET请求到 http://127.0.0.1:8000/admin-only 并添加Header token: admin-token，你会看到 {"message": "Welcome admin alice!"}。
• 使用Header token: user-token，你会收到403错误（禁止访问）。 这展示了如何分层管理权限，从简单令牌检查到基于角色的授权。每次测试成功都是一个“成功时刻”，增强你的信心。

第六步：实践练习

动手时间到了！创建一个新端点 /profile，只有认证用户才能访问，并返回用户的基本信息。

提示：使用 get_current_user 依赖项来验证用户并返回数据。

代码示例：

@app.get("/profile")
def user_profile(user: User = Depends(get_current_user)):
    return {"username": user.username, "role": user.role}

运行并测试：启动服务器后，使用不同令牌访问 /profile。例如，用 token: user-token 会返回 {"username": "bob", "role": "user"}。确保代码能正常工作——这是你的又一个“成功时刻”，巩固了所学内容。

总结

通过本教程，你学会了：

• 安装和运行FastAPI，创建基本API端点。
• 使用依赖注入实现安全检查和权限管理，让代码更清晰。
• 通过生活化类比（如咖啡店比喻）理解Web开发概念。

安全依赖项和权限检查是Web应用的关键部分，FastAPI的依赖系统让这变得简单直观。记住，每次成功运行代码都是一个胜利——保持实践，你会越来越熟练。

下一步建议：探索FastAPI官方文档，尝试添加数据库集成、更多端点或OAuth2认证。继续动手，享受编码的乐趣！