7.1 FastAPI 安全模块概述

Python初学者必学：FastAPI入门教程，包含安全模块快速上手

FastAPI 教程

本教程专为有Python语法基础但无Web开发经验的初学者设计。通过生活化类比和简单示例，从Hello World开始，逐步学习FastAPI基础，包括路由、请求响应和安全模块概述，快速建立信心，轻松上手Web开发。

FastAPI 入门教程：从零到英雄，轻松掌握Web开发

引言：为什么选择FastAPI？

FastAPI 是一个现代、快速（高性能）的 Python Web 框架，专门用于构建 API。对于初学者来说，它非常友好，因为它：

简单易学：语法类似于标准Python，无额外学习曲线。
自动文档：代码写好，文档自动生成，让你少操心。
类型提示：利用Python的类型提示，代码更清晰，IDE支持更好。

想象一下，FastAPI就像一辆自动挡汽车——你只需专注于驾驶（写代码），它会帮你处理繁琐的操作（如验证、文档生成）。

快速上手：你的第一个API——Hello World

让我们从一个简单的例子开始，建立你的第一个“成功时刻”！

步骤1：安装FastAPI和Uvicorn

首先，确保你安装了Python（建议3.7+），然后打开终端或命令提示符，运行：

pip install fastapi uvicorn

Uvicorn是一个ASGI服务器，用于运行FastAPI应用。

步骤2：创建你的第一个应用

新建一个Python文件，比如 main.py，写入以下代码：

from fastapi import FastAPI

app = FastAPI()  # 创建一个FastAPI应用实例，就像启动一个Web服务

@app.get("/")  # 定义一个路由，当访问根路径（如 http://localhost:8000/）时触发
def read_root():
    return {"message": "Hello, World!"}  # 返回一个JSON响应

步骤3：运行应用

在终端中，导航到 main.py 所在目录，运行：

uvicorn main:app --reload

main:app 表示从 main 模块导入 app 对象。
--reload 开启热重载，代码修改后自动重启，适合开发。

成功时刻！

打开浏览器，访问 http://localhost:8000/，你会看到 {"message": "Hello, World!"} 显示在页面上。恭喜你，第一个API运行成功！这就像打开了Web开发的大门。

基础概念：用生活化类比理解FastAPI

路由：你的Web地址地图

想象一下，路由就像是地图上的地址。在FastAPI中，路由定义了URL路径和对应的函数。例如：

@app.get("/") 表示当有人访问主页时，执行 read_root 函数。
你可以添加更多路由，如 @app.get("/about") 来定义一个关于页面。

请求和响应：发送和接收邮件

请求：当你在浏览器输入URL或发送数据时，就像寄出一封信。
响应：FastAPI处理请求后返回数据，就像回信。在上面的例子中，响应是一个JSON对象。

动手实践：更多简单示例

让我们通过几个例子加深理解。每个例子都包含一个“成功时刻”，让你亲手操作。

示例1：GET请求带路径参数

更新 main.py，添加一个新路由：

from fastapi import FastAPI

app = FastAPI()

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

@app.get("/items/{item_id}")  # 路径参数 {item_id}，就像地址中的动态部分
def read_item(item_id: int):  # FastAPI会自动将 item_id 转换为整数
    return {"item_id": item_id, "message": f"You requested item {item_id}"}

运行并测试：

保持应用运行（如果已停止，重新运行 uvicorn main:app --reload）。
访问 http://localhost:8000/items/123，你会看到 {"item_id": 123, "message": "You requested item 123"}。尝试不同数字，观察变化！

示例2：POST请求发送数据

添加一个处理POST请求的路由，模拟用户提交数据：

from fastapi import FastAPI
from pydantic import BaseModel  # 导入Pydantic用于数据验证

app = FastAPI()

# 定义一个数据模型，就像填写表格
class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")  # POST路由，用于创建新项
def create_item(item: Item):  # FastAPI自动从请求体中解析数据
    return {"item_name": item.name, "item_price": item.price, "status": "created"}

测试POST请求：

打开浏览器或使用工具如 Postman（推荐初学者用浏览器扩展，如“REST Client”）。
发送一个POST请求到 http://localhost:8000/items/，请求体为JSON：{"name": "Laptop", "price": 999.99}。
你会收到响应：{"item_name": "Laptop", "item_price": 999.99, "status": "created"}。

成功时刻：你刚刚创建了一个能接收数据的API！这就像网上购物时提交订单一样简单。

安全模块概述：保护你的API

安全是Web开发的重要部分。FastAPI内置了强大的安全模块，让初学者也能轻松添加保护。让我们用简单的方式理解。

为什么需要安全？

想象你的API是一个房子——安全模块就像门锁，防止未经授权的人进入。常见的威胁包括：数据泄露、恶意攻击等。

FastAPI 安全基础

FastAPI 使用依赖注入系统来处理安全，核心概念：

认证：验证用户身份，比如检查用户名和密码。
授权：决定用户能做什么，比如只允许管理员访问某些数据。

FastAPI 支持多种安全方案，如 OAuth2、JWT（JSON Web Tokens）。对于初学者，我们从最简单的示例开始。

简单安全示例：使用依赖项进行基本认证

我们将创建一个需要API密钥才能访问的路由。

更新 main.py：

from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import APIKeyHeader  # 导入安全模块

app = FastAPI()

# 定义一个API密钥头部依赖
api_key_header = APIKeyHeader(name="X-API-Key")

# 假设有效的API密钥是 "secret123"
def get_api_key(api_key: str = Depends(api_key_header)):
    if api_key != "secret123":
        raise HTTPException(status_code=403, detail="Invalid API Key")  # 如果密钥无效，返回错误
    return api_key

@app.get("/secure/")  # 安全路由
def read_secure(api_key: str = Depends(get_api_key)):  # 依赖注入，确保只有有效密钥能访问
    return {"message": "Access granted! This is a secure endpoint."}

测试安全路由：

运行应用。
访问 http://localhost:8000/secure/，你会看到一个错误页面，提示缺少API密钥。
现在，添加API密钥：在请求头中设置 X-API-Key: secret123。在Postman中，在Headers标签添加键 X-API-Key 和值 secret123，然后发送GET请求。
成功时刻：你会收到 {"message": "Access granted! This is a secure endpoint."}。试试错误密钥，观察被拒绝的情况！

进阶安全：OAuth2 和 JWT

对于更复杂的场景，FastAPI 支持 OAuth2 和 JWT。简单解释：

OAuth2：一种授权框架，比如用Google或GitHub账号登录其他网站。
JWT：一种令牌，包含用户信息，用于在客户端和服务器间安全传递数据。

FastAPI 有内置工具简化这些，但作为初学者，先从上面的基本示例开始，建立信心。你可以逐步学习官方文档探索更多。

总结和下一步

通过这个教程，你已经：

安装了FastAPI并运行了第一个Hello World API。
理解了路由、请求和响应的基础概念。
实践了GET和POST请求，处理路径参数和数据。
初步接触了安全模块，学会了如何用API密钥保护路由。

每个“成功时刻”都设计来让你看到即时结果，建立学习信心。记住，Web开发并不难——FastAPI 让它变得简单有趣！

下一步建议：

探索FastAPI自动生成的交互式文档：访问 http://localhost:8000/docs，你会看到一个Swagger UI页面，可以测试所有API端点。
学习更多特性：如查询参数、请求体模型、错误处理等。
参考官方文档：https://fastapi.tiangolo.com/，它非常详细且适合初学者。

继续动手实践，很快你就能构建自己的Web应用了！

上一章 6.6 请求体大小限制与配置

下一章 7.2 OAuth2 密码流程（带 Bearer Token）