FastAPI 介绍和入门核心知识点

一、框架概述

定义：FastAPI 是一个基于 Python 的高性能 Web 框架，专注于快速构建 API 接口服务。
核心优势 ：
- 异步性能高：原生支持异步编程，能有效提升并发处理能力和资源利用率。
- 开发效率高：结合 Pydantic 和类型提示，实现自动数据验证与序列化，减少手动编写校验代码。
- 自动生成文档 ：自动生成可交互式 API 文档（访问 http://127.0.0.1:8000/docs），便于调试和测试。

二、同步与异步对比

类型	处理方式	示例（处理10个1秒I/O任务）
同步	请求按顺序执行，在 I/O 等待时，CPU 空闲，资源利用率较低。	总耗时约 10秒
异步	通过 `async/await` 语法，在 I/O 等待期间切换处理其他任务，实现并发。	总耗时约 1秒

三、项目基础

项目搭建与运行
- 创建项目 ：需指定项目存储位置和名称，并创建虚拟环境。虚拟环境的核心作用是隔离项目依赖，避免不同项目间的包版本冲突，保持全局 Python 环境的稳定。
- 运行命令 ：uvicorn main:app --reload。
  - main：Python 文件名（不含 .py 后缀）。
  - app：FastAPI 应用实例名。
  - --reload：开启热重载，代码修改后服务器自动重启，便于开发调试。
路由定义
- 概念：路由是 URL 路径与处理函数之间的映射关系，决定了服务器对请求的响应逻辑。
- 实现方式 ：通过 Python 装饰器定义。
  python 复制代码
```
@app.get("/book/{id}")
async def get_book(id: int):
    return {"id": id, "title": f"这是第{id}本书"}
```

四、参数处理

路径参数
- 位置：URL 路径的一部分，例如 /book/{id}，用于指向唯一的、特定的资源。
- 类型注解 ：
  - Python 原生注解 ：id: int
  - Path 注解 ：提供额外的校验和元数据，如 gt（大于）、ge（大于等于）、description（描述）等。
    python 复制代码
```
from fastapi import Path
@app.get("/book/{id}")
async def get_book(id: int = Path(gt=0, description="图书ID")):
    return {"id": id}
```
查询参数
- 位置：URL 中 ? 之后，格式为 key1=value1&key2=value2，用于对资源集合进行过滤、排序或分页。
- 类型注解 ：
  - Python 原生注解 ：skip: int, limit: int = 10
  - Query 注解 ：提供校验和默认值。
    python 复制代码
```
from fastapi import Query
@app.get("/items/")
async def read_items(price: float = Query(gt=50, le=100)):
    return {"price": price}
```
请求体参数
- 位置：HTTP 请求的消息体（body）中，通常用于 POST、PUT 等创建或更新资源的操作。
- 定义与使用 ：
  1. 继承 pydantic.BaseModel 定义数据模型。
  2. 在路径操作函数中声明模型类型的参数。
  python 复制代码
```
from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(min_length=2, max_length=20)
    price: float = Field(gt=0)

@app.post("/books/")
async def create_book(book: Book):
    return book
```

五、响应处理

响应类型 ：FastAPI 默认返回 JSONResponse，也支持多种其他响应类型。

响应类型	用途	示例
`JSONResponse`	返回 JSON 数据（默认）	`return {"key": "value"}`
`HTMLResponse`	返回 HTML 内容	`return HTMLResponse("<h1>标题</h1>")`
`PlainTextResponse`	返回纯文本	`return PlainTextResponse("text")`
`FileResponse`	返回文件作为下载响应	`return FileResponse("path/to/file")`
`StreamingResponse`	适用于大文件或实时数据流式传输	返回生成器函数
`RedirectResponse`	重定向到其他URL	`return RedirectResponse("/new-url")`

自定义响应格式 ：

使用 response_model 参数，通过 Pydantic 模型来约束和过滤输出数据，确保数据格式的稳定和安全。

python 复制代码

from pydantic import BaseModel

class News(BaseModel):
    id: int
    title: str
    # content: str  # 如果模型中定义了但实际未返回，则不会出现在响应中

@app.get("/news/{id}", response_model=News)
async def get_news(id: int):
    # 实际返回了 id, title, content 三个字段
    return {"id": id, "title": f"新闻{id}", "content": "详情"}
    # 但由于 response_model=News，最终响应只会包含 id 和 title

六、异常处理

使用 HTTPException 来处理客户端错误（如 4xx），中断正常流程并返回标准的错误信息。

python 复制代码

from fastapi import HTTPException

@app.get('/news/{id}')
async def get_news(id: int):
    id_list = [1, 2, 3]
    if id not in id_list:
        raise HTTPException(status_code=404, detail="当前id不存在")
    return {"id": id}