三周精通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"}