第 12 章: 注解、省略号(…)表示法和返回类型

---

本章概述

学习FastAPI中的类型注解、Ellipsis表示法和返回类型声明。

---

12.1 Ellipsis表示法

... (Ellipsis) 表示必填参数：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
def read_items(q: str = Query(...)):  # q是必填的
    return {"q": q}

说明：使用...作为默认值表示这个参数是必需的，用户必须提供这个值。

---

12.2 Annotated类型

Python 3.9+ 支持Annotated：

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
def read_items(q: Annotated[str, Query(min_length=3)]):
    return {"q": q}

说明：Annotated允许你为类型添加元数据，FastAPI会读取这些元数据用于参数验证和文档生成。

---

12.3 返回类型

声明返回类型用于生成文档：

from typing import List
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

@app.get("/items/", response_model=List[Item])
def read_items():
    return [
        {"name": "Item 1", "price": 10.5},
        {"name": "Item 2", "price": 20.0}
    ]

---

12.4 response_model的作用

• 过滤返回数据：只返回模型中定义的字段
• 生成API文档：自动生成响应示例
• 验证返回数据：确保返回的数据符合模型定义

---

12.5 可选返回类型

from typing import Optional

@app.get("/items/{item_id}", response_model=Optional[Item])
def read_item(item_id: int):
    if item_id not in items:
        return None
    return items[item_id]

---

12.6 自定义响应

from fastapi.responses import JSONResponse

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id not in items:
        return JSONResponse(status_code=404, content={"message": "Not found"})
    return items[item_id]

---

小结

在本章中，我们学习了： - ✅ 使用Ellipsis (…) 表示必填参数 - ✅ 使用Annotated类型 - ✅ 声明返回类型用于文档生成 - ✅ 理解response_model的作用 - ✅ 自定义响应

在下一章中，我们将学习如何为FastAPI应用编写测试！