4、FastAPI 快速入门：安装、第一个 Hello World 接口、自动文档生成（Swagger/ReDoc）
FastAPI 是一个现代、高性能的 Python Web 框架，专为构建 API 而生。它基于 Starlette（网络部分）和 Pydantic（数据验证部分），天然支持异步编程，并自动生成符合 OpenAPI 规范的交互式文档。本章将带你从零搭建 FastAPI 环境，编写第一个接口，并体验其标志性的自动文档生成能力。
4.1 环境准备与安装
FastAPI 要求 Python 3.8 及以上版本。建议在虚拟环境中进行安装，避免依赖冲突。
推荐环境：Python 3.10+，使用
venv 或 conda 创建隔离环境。
安装核心库与 ASGI 服务器：
# 安装 FastAPI 核心
pip install fastapi
# 安装 ASGI 服务器（推荐 uvicorn，性能优异）
pip install uvicorn[standard]安装完成后，可通过以下命令验证版本：
python -c "import fastapi; print(fastapi.__version__)"4.2 第一个 Hello World 接口
创建一个名为 main.py 的文件，写入以下代码：
from fastapi import FastAPI
# 创建 FastAPI 应用实例
app = FastAPI()
# 定义根路径的 GET 请求处理器
@app.get("/")
async def read_root():
return {"message": "Hello World"}
# 定义带路径参数的 GET 请求处理器
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q}启动服务：
# 启动命令：uvicorn 文件名:应用实例名 --reload
# --reload 表示热重载，代码修改后自动重启
uvicorn main:app --reload终端输出类似如下信息，表示服务已成功运行：
INFO: Uvicorn running on http://127.0.0.1:8000
INFO: Started reloader process [12345] using WatchFiles
INFO: Started server process [12346]
INFO: Waiting for application startup.此时，在浏览器中访问 http://127.0.0.1:8000，即可看到 JSON 响应：
{"message":"Hello World"}访问 http://127.0.0.1:8000/items/42?q=test，将返回：
{"item_id":42,"q":"test"}4.3 自动文档生成：Swagger UI 与 ReDoc
FastAPI 最受好评的特性之一，是无需额外配置即可自动生成两套交互式 API 文档。它们基于 OpenAPI 规范，所有路由、参数、返回类型都会被自动解析并展示。
| 文档类型 | 访问路径 | 特点 |
|---|---|---|
| Swagger UI | /docs |
交互式界面，可直接在浏览器中测试接口，支持参数填写与发送请求 |
| ReDoc | /redoc |
更侧重文档阅读体验，左侧导航清晰，适合团队查阅与分享 |
启动服务后，直接访问以下地址即可查看：
- Swagger UI：
http://127.0.0.1:8000/docs - ReDoc：
http://127.0.0.1:8000/redoc
核心优势：文档与代码同步。当你修改代码中的参数类型、添加描述或调整路由时，文档会自动更新，无需手动维护。
4.4 FastAPI 请求处理流程
下图展示了 FastAPI 从接收 HTTP 请求到返回 JSON 响应的核心流程：
4.5 核心概念速览
下表对比了 FastAPI 与传统 Flask 在关键特性上的差异，帮助你快速理解 FastAPI 的设计优势：
| 特性 | FastAPI | Flask |
|---|---|---|
| 异步支持 | 原生支持 async/await |
需额外安装扩展 |
| 数据验证 | 基于 Pydantic，自动校验请求体 | 需手动校验或使用第三方库 |
| 自动文档 | 内置 Swagger UI 与 ReDoc | 需集成 flasgger 等扩展 |
| 性能 | 接近 Node.js 和 Go 的高性能 | 同步框架，性能相对较低 |
| 类型提示 | 深度利用 Python 类型注解 | 不强制使用类型注解 |
4.6 常见问题与避坑指南
端口冲突：如果默认的 8000 端口被占用，启动时会报错
Address already in use。可通过 --port 参数指定其他端口，例如 uvicorn main:app --reload --port 8080。
- 热重载失效：确保启动命令中包含了
--reload参数，且代码文件位于当前工作目录下。 - 路径参数类型错误：如果访问
/items/abc而item_id声明为int，FastAPI 会自动返回 422 验证错误，并给出详细的错误信息。 - 文档无法访问：检查是否在
app = FastAPI()时传入了docs_url=None或redoc_url=None，这会禁用文档路由。