FastAPI之响应状态码

使用FastAPI自定义响应状态码

FastAPI 是一个现代、快速的 web 框架，用于构建API服务，它允许你通过Python 3.6及以上版本进行编程。一个重要的API设计是返回合适的响应状态码，这可以使得客户端理解服务端的处理结果。本教程将向你展示如何在FastAPI中使用和自定义响应状态码。

状态码概览

HTTP状态码是服务器用来告知客户端关于请求的处理情况的3位数字代码。这些状态码分为五个类别：

• 1xx (信息): 请求已被接受，继续处理。
• 2xx (成功): 请求已成功被服务器接收、理解、并接受。
• 3xx (重定向): 需要后续操作才能完成这一请求。
• 4xx (客户端错误): 请求包含语法错误或无法被执行。
• 5xx (服务器错误): 服务器在处理请求的时候发生了错误。

FastAPI中设置响应状态码

FastAPI 允许在路径操作中设置响应状态码。以下是一些基本示例。

设置默认响应状态码

你可以为路径操作设置默认的响应状态码，如下：

from fastapi import FastAPI, status

app = FastAPI()

@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

在上述示例中，当你向 /items/ 端点发送 POST 请求时，无论何时，只要没有异常，它都会返回 201 Created 状态码。

使用响应参数设置状态码

也可以在函数内部动态设置状态码，通过 Response 对象的 status_code 属性：

from fastapi import FastAPI, Response, status

app = FastAPI()

@app.post("/items/")
async def create_item(name: str, response: Response):
    response.status_code = status.HTTP_202_ACCEPTED
    return {"name": name}

在这个例子中，我们将响应状态码设置为 202 Accepted。
测试结果

使用HTTPException定义错误状态码

你可能需要通知客户端错误发生，比如用户请求一个不存在的项。在FastAPI中，你可以通过抛出 HTTPException 来实现。

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

fake_db = {"foo": "bar"}

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

在这个例子中，如果请求的 item_id 不存在于数据库中，我们抛出一个 HTTPException，状态码为 404 Not Found。
测试结果：

结论

使用合适的响应状态码是API设计的一个重要方面，它可以提升API的可用性并且帮助客户端理解请求的处理情况。FastAPI提供了简单直观的方式来设置和自定义响应状态码。通过本教程的示例，你现在应该能够在你的API中有效管理响应状态码了。

注意：务必记住，正确使用状态码可以帮助客户端更好地处理不同情况，改善用户体验。