FastAPI入门教程：响应状态码与响应头

引言

欢迎来到FastAPI世界！如果你刚接触Web开发，可能会觉得HTTP响应很神秘。别担心，今天我们用生活化的类比来轻松理解响应状态码和响应头。想象一下，当你发送一个请求给网站（比如访问一个页面），就像寄出一封信；网站回复时，会附上一张“回复纸条”，上面写着状态码（比如“200 OK”表示一切顺利）和响应头（比如回复的时间和类型）。FastAPI让这个过程变得超级简单！

通过这个教程，你将亲手操作，看到代码运行成功，建立信心。让我们开始吧！

什么是响应状态码和响应头？

响应状态码：HTTP的“回复情绪”

响应状态码是HTTP响应的一部分，用三位数字表示请求的结果。把它想象成回复的情绪：

• 200 OK：请求成功，就像你问路时对方愉快地指了方向。
• 404 Not Found：请求的资源不存在，就像你找的书在图书馆里找不到。
• 500 Internal Server Error：服务器内部错误，就像厨师在厨房里搞砸了菜。

在FastAPI中，你可以指定状态码来告诉客户端发生了什么事。

响应头：响应的“附加信息”

响应头是响应的附加信息，帮助客户端正确处理内容。例如：

• Content-Type：告诉浏览器响应的数据类型，如"application/json"表示JSON格式。
• Cache-Control：控制缓存行为，比如"no-cache"让浏览器不要缓存这个响应。

响应头就像回复纸条上的寄件人姓名和日期，提供额外细节。

在FastAPI中设置响应状态码和响应头

FastAPI提供了简单的方法来控制响应。我们将创建一个简单的应用来演示，让你动手实践，体验“成功时刻”。

准备工作

确保你已经安装了FastAPI和Uvicorn。打开终端或命令提示符，输入：

pip install fastapi uvicorn

如果你看到安装成功的消息，恭喜！第一步完成。

创建FastAPI应用

新建一个Python文件，比如 main.py。用你喜欢的代码编辑器打开它（比如VS Code或PyCharm），然后添加以下代码：

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!"} 显示。在浏览器开发者工具中（按F12打开），查看网络标签，你会发现响应状态码默认是200。这是你的第一个“成功时刻”：成功运行一个FastAPI应用！

示例1：指定状态码

现在，让我们自定义状态码。修改 read_root 函数，添加 status_code 参数：

from fastapi import FastAPI

app = FastAPI()

@app.get("/", status_code=201)  # 指定状态码为201 Created
def read_root():
    return {"message": "Resource created successfully!"}

保存文件并刷新浏览器页面。在开发者工具中查看网络标签，你会看到状态码变成了201。又一个“成功时刻”：你学会了自定义状态码！

示例2：设置响应头

接下来，我们设置响应头。使用 response 参数来添加自定义头部：

from fastapi import FastAPI
from fastapi.responses import Response

app = FastAPI()

@app.get("/headers/")
def set_headers():
    # 创建一个响应对象并设置头部
    content = {"info": "Custom headers example"}
    headers = {"X-Custom-Header": "FastAPI", "Cache-Control": "no-cache"}
    return Response(content=content, media_type="application/json", headers=headers)

访问 http://127.0.0.1:8000/headers/，查看开发者工具中的网络标签。在响应头部分，你会看到 X-Custom-Header: FastAPI 和 Cache-Control: no-cache。惊喜吧？你的自定义头部生效了！

示例3：处理错误状态码

有时需要返回错误状态码。使用 HTTPException 来模拟错误情况：

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id < 1:
        raise HTTPException(status_code=400, detail="Item ID must be positive")  # 状态码400 Bad Request
    return {"item_id": item_id, "message": "Item found"}

访问 http://127.0.0.1:8000/items/0，你会收到一个400错误响应，显示 {"detail":"Item ID must be positive"}。再试试 http://127.0.0.1:8000/items/1，返回200成功。看到错误和成功如何切换了吗？这是Web开发的关键部分！

总结

通过这个教程，你学会了在FastAPI中控制响应状态码和响应头。状态码告诉客户端请求的结果，响应头提供额外信息。记住类比：状态码是回复的情绪，响应头是回复的细节。我们动手实践了三个简单示例，每个都带来了“成功时刻”，让你建立信心。

继续探索FastAPI，它会让Web开发变得有趣又简单。如果你遇到问题，随时查阅官方文档或社区资源。加油，未来的开发者！