FastAPI 入门：HTTPException 错误处理教程

欢迎来到FastAPI的世界！如果你已经掌握了基础Python语法，但没有Web开发经验，别担心。这个教程将带你一步步学会如何处理错误，特别是使用HTTPException。我们将通过简单的生活类比和大量实践示例，让你轻松上手。

为什么需要错误处理？

想象一下，你去餐厅点餐，但如果菜单上没有某个菜，服务员会说“抱歉，这个菜没有了”，而不是直接不理你。在Web开发中，当用户请求错误或服务器出问题时，我们也需要类似的处理方式：返回友好的错误信息，而不是让用户感到困惑。这就是HTTPException的作用——它帮助你在API中抛出HTTP错误，告诉用户哪里出了问题。

前置条件

在开始之前，确保你具备以下条件：

• Python 3.7或更高版本已安装。
• 安装FastAPI和Uvicorn（一个运行FastAPI的服务器）：打开命令行，运行 pip install fastapi uvicorn。
• 基本了解Python函数和if语句。

一切准备就绪后，让我们一起动手吧！

快速开始：创建你的第一个FastAPI应用

首先，我们创建一个简单的API，并添加错误处理。这将让你立即看到成果，增强信心。

示例1：基本HTTPException——验证输入

在这个例子中，我们将创建一个API，当用户请求负数时返回错误。

1. 创建一个新文件，比如命名为 main.py。
2. 粘贴以下代码：

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id < 0:
        raise HTTPException(status_code=400, detail="Item ID must be positive")
    return {"item_id": item_id}

解释：

• FastAPI() 创建一个应用实例。
• @app.get("/items/{item_id}") 定义一个GET请求的路由，其中{item_id}是路径参数。
• 函数 read_item 接收 item_id 作为参数。
• 如果 item_id 小于0，使用 raise HTTPException(status_code=400, detail="...") 抛出一个HTTP 400错误（Bad Request），并附带详细信息。
• 否则，返回一个JSON响应。

3. 运行应用：在命令行中，进入 main.py 所在目录，运行 uvicorn main:app --reload。
4. 打开浏览器，访问 http://127.0.0.1:8000/items/-1。

成功时刻： 你会看到一个错误页面，显示“Item ID must be positive”。恭喜！你已经成功创建了第一个带有错误处理的API。尝试访问 http://127.0.0.1:8000/items/5，看看正常响应是什么。

处理常见HTTP错误

现在，我们扩展一下，处理更常见的错误，比如当用户请求一个不存在的资源时。

示例2：404 Not Found 错误

假设我们有一个存储物品的字典，用户请求不存在的物品时返回404错误。

在 main.py 中更新代码：

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {1: "apple", 2: "banana"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

解释：

• 我们定义了一个字典 items 来模拟数据存储。
• 如果 item_id 不在字典中，抛出HTTP 404错误（Not Found）。

再次运行应用，访问 http://127.0.0.1:8000/items/3。

成功时刻： 你会得到404错误页面，显示“Item not found”。访问 http://127.0.0.1:8000/items/1，则会看到正常响应。这让你学会了如何处理资源不存在的情况。

自定义错误消息和状态码

有时，你需要更具体的错误。让我们看看如何自定义错误消息和状态码。

示例3：403 Forbidden 错误

假设我们有一个API，只允许特定用户访问，否则返回403错误。

在 main.py 中添加新路由：

@app.get("/users/{user_id}")
def get_user(user_id: int):
    if user_id == 0:
        raise HTTPException(status_code=403, detail="Access denied for user 0")
    return {"user_id": user_id, "message": "Welcome"}

解释：

• 当 user_id 为0时，抛出HTTP 403错误（Forbidden），并给出具体原因。

运行应用，访问 http://127.0.0.1:8000/users/0。

成功时刻： 看到403错误页面，信息更具体。这让你掌握了如何根据不同场景调整错误。

进阶：在依赖项中使用HTTPException

FastAPI支持依赖项，这可以用来处理验证等逻辑。让我们简单尝试一下。

示例4：验证请求

创建一个依赖项来检查用户是否为管理员。

更新 main.py：

from fastapi import FastAPI, HTTPException, Depends

app = FastAPI()

def check_admin(admin: bool = False):
    if not admin:
        raise HTTPException(status_code=401, detail="Not authorized")

@app.get("/admin")
def admin_page(admin: bool = Depends(check_admin)):
    return {"message": "Admin access granted"}

解释：

• check_admin 是一个依赖项函数，它检查 admin 参数是否为True。
• 如果 admin 为False，抛出HTTP 401错误（Unauthorized）。
• 在 /admin 路由中使用 Depends(check_admin) 来应用这个依赖项。

运行应用，访问 http://127.0.0.1:8000/admin（不带参数）。

成功时刻： 你会得到401错误，显示“Not authorized”。尝试访问 http://127.0.0.1:8000/admin?admin=true，则会看到正常响应。这个例子展示了如何将错误处理集成到更复杂的逻辑中。

总结

通过这个教程，你已经学会了：

• HTTPException 是FastAPI中处理HTTP错误的核心工具。
• 如何抛出不同状态的错误，如400、404、403和401。
• 通过简单的生活类比（如餐厅点餐），理解错误处理的重要性。
• 多个动手示例，每个都有明确的“成功时刻”，帮助你建立信心。

记住，实践是最好的老师。多写代码、多测试，你会越来越熟练。FastAPI文档（https://fastapi.tiangolo.com/）有更多高级功能，等你探索。

如果你遇到问题，回顾这些示例或搜索在线社区。祝你学习愉快！