三周精通FastAPI：13 响应状态码status_code

官网：https://fastapi.tiangolo.com/zh/tutorial/response-status-code/

响应状态码¶

与指定响应模型的方式相同，在以下任意路径操作中，可以使用 status_code 参数声明用于响应的 HTTP 状态码：

• @app.get()
• @app.post()
• @app.put()
• @app.delete()
• 等……

from fastapi import FastAPI

app = FastAPI()


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

"笔记"

注意，status_code 是（get、post 等）装饰器方法中的参数。与之前的参数和请求体不同，不是路径操作函数的参数。

status_code 参数接收表示 HTTP 状态码的数字。

"说明"

status_code 还能接收 IntEnum 类型，比如 Python 的 http.HTTPStatus。

它可以：

• 在响应中返回状态码
• 在 OpenAPI 概图（及用户界面）中存档：

"笔记"

某些响应状态码表示响应没有响应体（参阅下一章）。

FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。

关于 HTTP 状态码¶

"笔记"

如果已经了解 HTTP 状态码，请跳到下一章。

在 HTTP 协议中，发送 3 位数的数字状态码是响应的一部分。

这些状态码都具有便于识别的关联名称，但是重要的还是数字。

简言之：

• 100 及以上的状态码用于返回信息。这类状态码很少直接使用。具有这些状态码的响应不能包含响应体
• 200 及以上的状态码用于表示成功。这些状态码是最常用的
  • 200 是默认状态代码，表示一切正常
  • 201 表示已创建，通常在数据库中创建新记录后使用
  • 204 是一种特殊的例子，表示无内容。该响应在没有为客户端返回内容时使用，因此，该响应不能包含响应体
• 300 及以上的状态码用于重定向。具有这些状态码的响应不一定包含响应体，但 304未修改是个例外，该响应不得包含响应体
• 400 及以上的状态码用于表示客户端错误。这些可能是第二常用的类型
  • 404，用于未找到响应
  • 对于来自客户端的一般错误，可以只使用 400
• 500 及以上的状态码用于表示服务器端错误。几乎永远不会直接使用这些状态码。应用代码或服务器出现问题时，会自动返回这些状态代码

"提示"

状态码及适用场景的详情，请参阅 MDN 的 HTTP 状态码文档。

状态码名称快捷方式¶

再看下之前的例子：

from fastapi import FastAPI

app = FastAPI()


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

201 表示已创建的状态码。

但我们没有必要记住所有代码的含义。可以使用 fastapi.status 中的快捷变量。

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}

这只是一种快捷方式，具有相同的数字代码，但它可以使用编辑器的自动补全功能：

"技术细节"

也可以使用 from starlette import status。

为了让开发者更方便，FastAPI 提供了与 starlette.status 完全相同的 fastapi.status。但它直接来自于 Starlette。

更改默认状态码¶

高级用户指南中，将介绍如何返回与在此声明的默认状态码不同的状态码。

实践

代码

将以下代码存在responsecode.py文件

from fastapi import FastAPI

app = FastAPI()


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

运行服务

uvicorn responsecode:app --reload

浏览测试

还是使用curl命令就行测试

curl -X POST "http://127.0.0.1:8000/items/" -H "Content-Type: application/json" -d '{"name": "test_item"}'

上面这条测试命令报错，具体报错见调试部分。最终是用在地址栏里加参数解决的；

curl -X POST "http://127.0.0.1:8000/items/?name=test_item" -H "Content-Type: application/json"
{"name":"test_item"}

同时查看服务器的跟踪信息，发现确实是201状态码

INFO:     127.0.0.1:50968 - "POST /items/?name=test_item HTTP/1.1" 201 Created

总结

需要用到状态码的场合，除了200可能也就201这条会用一些，其它大部分不太常见。感觉响应状态码这里应该大约用设定好的就行了，大多时候应该不需要程序员去手动处理。

以后有了新的心得体会再来添加。

调试

curl浏览测试报错422 Unprocessable Entity

curl -X POST "http://127.0.0.1:8000/items/" -H "Content-Type: application/json" -d '{"name": "test_item"}'

{"detail":[{"type":"missing","loc":["query","name"],"msg":"Field required","input":null}]}

使用-v参数看更详细的输出：

curl -0.0.1:8000/items/" -H "Content-Type: application/json" -d '{"name": "test_item"}' -v
Note: Unnecessary use of -X or --request, POST is already inferred.
*   Trying 127.0.0.1:8000...
* Connected to 127.0.0.1 (127.0.0.1) port 8000 (#0)
> POST /items/ HTTP/1.1
> Host: 127.0.0.1:8000
> User-Agent: curl/8.1.1
> Accept: */*
> Content-Type: application/json
> Content-Length: 21
> 
< HTTP/1.1 422 Unprocessable Entity
< date: Sat, 26 Oct 2024 01:48:34 GMT
< server: uvicorn
< content-length: 90
< content-type: application/json
< 
* Connection #0 to host 127.0.0.1 left intact
{"detail":[{"type":"missing","loc":["query","name"],"msg":"Field required","input":null}]}

文心说大约是：

响应体：错误信息指出 "Field required"，并且位置是 ["query","name"]。这表明服务器期望在查询参数中找到一个名为 name 的字段，但实际上并没有找到。然而，这与您提供的 FastAPI 代码不符，因为您的代码是从请求体中获取 name 字段的。

于是用地址带参数?name=test_item的方法解决

curl -0.0.1:8000/items/?name=test_item" -H "Content-Type: application/json"
{"name":"test_item"}