7.5 HTTP Basic 认证

FastAPI入门教程：Python初学者学习Web开发与HTTP基本认证

FastAPI 教程

这份详细的FastAPI教程专为Python初学者设计，涵盖基础概念到HTTP基本认证实践，帮助您快速上手Web开发。通过生活化类比和简单示例，轻松掌握API构建和安全性。

FastAPI入门教程：从Python到Web开发

简介

欢迎来到FastAPI世界！如果你懂点Python，但还没碰过Web开发，那这里正是你的起点。FastAPI是一个现代、快速（高性能）的Web框架，用于构建API（应用程序编程接口）。别担心术语——想象API就像是餐厅的菜单：它告诉别人（比如其他程序）你可以提供什么服务（比如获取数据），而FastAPI就是帮你快速制作这个菜单的工具。

在这篇教程中，我们将一步步带你入门，最后你会学会如何用HTTP基本认证保护你的API，就像给门加把锁一样简单。目标是让你有成就感，所以每个部分都有小练习，能看到立即的效果。

先决条件：只需基础Python语法知识（比如知道变量、函数、列表）。不需要任何Web经验——我们从零开始！

第一部分：FastAPI初体验

1. 什么是FastAPI？

FastAPI是基于Python的Web框架，专为构建API设计。它快速、易用，并且有自动文档生成功能，省去你很多麻烦。类比一下：如果你要开个外卖店，FastAPI就是那个帮你快速搭建点餐系统（API）的工具，顾客（其他程序）可以通过它下单（请求数据）。

2. 安装和设置

首先，确保你安装了Python（建议3.7+）。然后打开终端或命令提示符，运行以下命令安装FastAPI和一个服务器（比如uvicorn，它负责运行你的API）：

pip install fastapi uvicorn

安装完成后，你就准备好了——就像买了新工具，可以开始动手了。

3. 创建第一个API：Hello World

让我们快速体验一下成功时刻！创建一个新文件，比如叫 main.py，并写入以下代码：

from fastapi import FastAPI

app = FastAPI()  # 创建一个FastAPI应用实例，就像初始化你的外卖店

@app.get("/")  # 定义一个GET路由，当访问根路径""时触发，类似菜单首页
def read_root():
    return {"message": "Hello, World!"}  # 返回一个简单的JSON响应

保存文件。然后在终端运行：

uvicorn main:app --reload

解释一下：uvicorn 是服务器，main:app 指定你的应用（从 main.py 导入 app），--reload 表示代码改动后自动重启，方便调试。

打开浏览器，访问 http://127.0.0.1:8000/，你会看到 {"message": "Hello, World!"} 显示出来！恭喜——你的第一个API运行成功了！这就是你的"成功时刻"：只需几行代码，你就创建了一个可访问的Web服务。

小贴士：访问 http://127.0.0.1:8000/docs 看看自动生成的交互式文档，像是个内置的用户手册，超级方便。

第二部分：扩展你的API

4. 添加更多路由

现在，加点内容到你的API菜单。在 main.py 中新增一个路由：

@app.get("/items/{item_id}")  # 定义一个带路径参数的路由，item_id 是变量
def read_item(item_id: int, q: str = None):  # 可以接受查询参数q
    return {"item_id": item_id, "q": q}

保存并刷新浏览器（因为 --reload 在运行）。访问 http://127.0.0.1:8000/items/42?q=test，你会看到 {"item_id": 42, "q": "test"}。看，你已经能处理动态数据了——就像顾客可以点特定菜品（item_id）并加备注（q）。

5. 处理POST请求

API不仅能读数据，还能写。添加一个POST路由来创建新项目：

from pydantic import BaseModel  # 导入Pydantic用于数据验证，FastAPI内置支持

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
def create_item(item: Item):  # FastAPI自动解析请求体为Item对象
    return item

使用工具如Postman或浏览器扩展测试POST请求，发送JSON数据 {"name": "Book", "price": 10.5} 到 http://127.0.0.1:8000/items/，它会返回相同数据。成就感满满——你现在能接收和处理用户输入了！

第三部分：引入安全——HTTP基本认证

6. 为什么需要安全？

想象你的API是家私人俱乐部，不能随便让人进。HTTP基本认证就是一种简单的方式：用户需要提供用户名和密码才能访问特定部分。它就像进门时出示会员卡（凭据），守护检查一下。

7. 实现HTTP基本认证

FastAPI让这变得简单。在 main.py 中添加以下代码：

from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

security = HTTPBasic()  # 创建一个安全实例，用于处理基本认证

def get_current_username(credentials: HTTPBasicCredentials = Depends(security)):
    # 这里模拟一个简单的用户验证，实际中应从数据库检查
    correct_username = "admin"
    correct_password = "password"
    if credentials.username != correct_username or credentials.password != correct_password:
        # 如果凭据错误，抛出HTTP异常，状态码401未授权
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username  # 验证成功，返回用户名

@app.get("/protected/")
def read_protected(username: str = Depends(get_current_username)):
    # 这个端点依赖get_current_username，只有认证用户能访问
    return {"message": f"Hello, {username}! This is a protected area."}

解释：

HTTPBasic 是FastAPI的安全工具，自动处理HTTP基本认证头。
Depends 表示这个端点依赖于 get_current_username 函数，只有它返回成功时才能执行。
在 get_current_username 中，我们检查用户名和密码是否匹配预设值（这里简单硬编码，实际应用应使用更安全的方式，如哈希和数据库）。
如果错误，抛出异常，否则允许访问。

8. 测试认证

运行你的应用（确保uvicorn还在运行）。

打开浏览器访问 http://127.0.0.1:8000/protected/，你会看到一个登录弹窗，要求输入用户名和密码。输入 admin 和 password，点击确定，就能看到 {"message": "Hello, admin! This is a protected area."}。
如果输入错误，比如 user 和 123，页面会显示错误信息。

成功时刻：现在你的API有了基本的安全保护！只需几行代码，你就实现了门禁系统。在实际中，你可以扩展这个来保护敏感数据。

小练习：尝试修改 correct_username 和 correct_password 为其他值，或者添加更多用户，看效果如何。

总结和下一步

你做到了！通过这个教程，你学会了：

安装和运行FastAPI。
创建基本路由和处理请求。
使用HTTP基本认证保护端点。

FastAPI还有更多功能等待探索，比如数据库集成、更复杂的认证（如OAuth2）、异步支持等。建议下一步：

查阅FastAPI官方文档（有中文版）。
尝试构建一个小项目，比如待办事项API。
学习更高级的安全特性，确保生产环境安全。

记住，Web开发就像搭积木——一步步来，每个小成功都会积累信心。快乐编码！

上一章 7.4 API Key 认证：查询参数、请求头、Cookie

下一章 7.6 CORS（跨域资源共享）配置