FastAPI自学教程（20） - 响应状态码

1. 基础声明方式

from fastapi import FastAPI

app = FastAPI()

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

status_code是路径操作装饰器参数，不是函数参数
支持所有HTTP方法（GET/POST/PUT/DELETE等）
默认状态码为200（成功响应）
状态码会写入OpenAPI文档并展示在Swagger UI

2. HTTP状态码分类

状态码范围	类别说明	常见示例
1xx	信息响应（无响应体）	100 Continue
2xx	成功响应	200 OK / 201 Created
3xx	重定向响应	301 Moved Permanently
4xx	客户端错误	400 Bad Request / 404 Not Found
5xx	服务端错误（自动返回）	500 Internal Server Error

3. 状态码快捷方式

from fastapi import status

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

使用fastapi.status模块预定义常量（兼容starlette.status）
优势：
- 代码可读性强（如HTTP_201_CREATED比201直观）
- 编辑器支持自动补全
- 包含所有标准HTTP状态码（如HTTP_422_UNPROCESSABLE_ENTITY）

4. 动态修改状态码

from fastapi import Response, status

@app.put("/tasks/{task_id}")
async def update_task(task_id: str, response: Response):
    if task_id not in tasks:
        response.status_code = status.HTTP_201_CREATED
    return tasks[task_id]

通过Response参数在函数内部修改状态码
优先级：函数内设置的status_code > 装饰器默认值
适用场景：
- 资源创建时返回201
- 条件失败时返回4xx错误

5. 特殊状态码说明

1
2
3

@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: str):
    return  # 204响应不能包含响应体

204 No Content：无响应体，必须返回空
304 Not Modified：禁止包含响应体
422 Unprocessable Entity：数据验证错误