FastAPI基础教程：路由、请求与响应的基础用法

1. 什么是FastAPI？¶

FastAPI是一个基于Python的现代、快速（高性能）的Web框架，用于构建API。它有几个突出的特点：

高性能：基于Starlette和Pydantic构建，性能接近Node.js和Go
自动生成API文档：自动生成交互式的Swagger UI和ReDoc文档
类型提示支持：利用Python的类型提示自动验证数据和生成文档
简单易用：代码简洁，学习曲线平缓，适合初学者快速上手

2. 安装FastAPI¶

要开始使用FastAPI，首先需要安装它和一个ASGI服务器（如Uvicorn）：

pip install fastapi uvicorn

3. 基础路由定义¶

路由是API中URL与处理函数的映射关系，FastAPI使用@app装饰器定义路由。

3.1 最基本的路由¶

from fastapi import FastAPI

# 创建FastAPI应用实例
app = FastAPI()

# 定义一个GET请求路由，路径为"/"
@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI!"}

@app.get("/")：这是一个路径操作装饰器，表示处理根路径/的GET请求
def read_root()：处理函数，返回一个字典（FastAPI会自动转为JSON响应）

3.2 带路径参数的路由¶

路径参数是URL中动态变化的部分，例如/items/123中的123。

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id, "message": f"你请求的商品ID是: {item_id}"}

{item_id}：路径参数，item_id是参数名
item_id: int：参数类型提示，FastAPI会自动验证类型并转换
当访问/items/5时，会返回{"item_id": 5, "message": "你请求的商品ID是: 5"}

3.3 带查询参数的路由¶

查询参数是URL中?后面的键值对，用于传递额外信息。

@app.get("/search")
def search_items(q: str = None, limit: int = 10):
    return {"query": q, "limit": limit}

q: str = None：查询参数q，默认值为None
limit: int = 10：查询参数limit，默认值为10
访问/search?q=test&limit=5时，返回{"query": "test", "limit": 5}

4. 请求处理¶

当需要接收客户端发送的数据（如POST请求的JSON数据）时，FastAPI使用请求体。

4.1 使用Pydantic模型定义请求体¶

Pydantic是一个数据验证库，FastAPI用它来定义请求数据结构：

from pydantic import BaseModel

# 定义数据模型
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None  # 可选字段，默认值为None

@app.post("/items/")
def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price}

Item类继承自BaseModel，定义了三个字段：name（字符串）、price（浮点数）、is_offer（布尔值，可选）
在create_item函数中，item: Item参数表示接收一个Item类型的请求体
FastAPI会自动解析请求体的JSON数据，并验证数据类型是否匹配

4.2 发送请求体测试¶

使用curl发送POST请求：

curl -X POST "http://localhost:8000/items/" \
  -H "Content-Type: application/json" \
  -d '{"name": "iPhone", "price": 999.99, "is_offer": true}'

5. 响应处理¶

FastAPI会自动将函数返回值转换为JSON响应。

5.1 返回Pydantic模型¶

@app.get("/items/{item_id}", response_model=Item)
def get_item(item_id: int):
    # 模拟数据库查询
    return {"name": "Example Item", "price": 100.0, "is_offer": None}

response_model=Item：指定响应数据的模型，FastAPI会自动将返回的字典转换为Item模型，并生成对应JSON结构
响应会包含name、price和is_offer字段，即使模型中某些字段为None

5.2 返回状态码¶

使用status_code参数指定HTTP状态码：

@app.post("/items/", status_code=201)  # 201表示"创建成功"
def create_item(item: Item):
    return item  # 返回创建的Item数据

常见状态码：
- 200 OK：默认状态码（GET/POST成功）
- 201 Created：资源创建成功（POST）
- 404 Not Found：资源不存在
- 400 Bad Request：请求参数错误

5.3 返回字典或简单类型¶

@app.get("/hello/{name}")
def say_hello(name: str):
    return {"message": f"Hello, {name}!"}  # 返回字典

或返回字符串：

@app.get("/version", response_class=str)
def get_version():
    return "1.0.0"  # 返回字符串

6. 完整示例¶

下面是一个包含路由、请求和响应的完整FastAPI应用：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title="FastAPI基础示例")

# 定义数据模型
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

# 1. 根路由
@app.get("/")
def read_root():
    return {"message": "欢迎使用FastAPI示例API！"}

# 2. 带路径参数的路由
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

# 3. 带请求体的路由
@app.post("/items/", response_model=Item, status_code=201)
def create_item(item: Item):
    return item  # 返回创建的Item对象

# 4. 另一个带参数的路由
@app.get("/search")
def search_items(q: str = None, limit: int = 10):
    return {"search_term": q, "limit": limit}

7. 运行和测试¶

保存代码到main.py文件
使用Uvicorn运行应用：

uvicorn main:app --reload

main:app：表示从main.py文件中导入app实例
--reload：自动重载代码，开发时方便调试

访问API文档：
- Swagger UI：http://localhost:8000/docs
- ReDoc：http://localhost:8000/redoc

8. 总结¶

通过本文，你应该已经掌握了FastAPI的基础用法：

使用@app装饰器定义路由
处理路径参数和查询参数
使用Pydantic模型接收请求体
返回响应数据和设置状态码
利用自动生成的API文档进行测试

FastAPI的核心优势在于它的简洁性和自动文档功能，这使得构建和维护API变得更加高效。接下来可以探索更多高级特性，如依赖注入、中间件和异步处理等。