好的，这是一个超详细的 FastAPI 入门教程，专为新手设计，力求“保姆级”讲解，手把手带你入门。

---

🚀 Python FastAPI 入门：写给新手的“保姆级”教程

FastAPI 是一个现代化、高性能的 Python Web 框架，用于构建 API。它基于 Python 3.6+ 的类型注解，具有自动生成交互式文档、极高的性能（基于 Starlette 和 Pydantic）等优点。非常适合快速开发 RESTful API。

你将学到：

1. 安装 FastAPI 及必要组件
2. 创建第一个 API 接口
3. 理解路由（Routes）和路径操作（Path Operations）
4. 处理路径参数（Path Parameters）和查询参数（Query Parameters）
5. 使用 Pydantic 模型定义请求体和响应体
6. 运行开发服务器并测试接口
7. 利用自动生成的交互式文档（Swagger UI 和 ReDoc）

---

🛠 第一步：环境准备

1. 确保已安装 Python： 打开终端（命令提示符或 PowerShell），输入 python --version 或 python3 --version。如果看到 Python 3.6 或更高版本，则已安装。如果没有，请先安装 Python。

2. （强烈推荐）创建虚拟环境： 虚拟环境可以隔离项目依赖，避免冲突。

   • 在项目文件夹中打开终端。
   • 创建虚拟环境：

     python -m venv venv
     

   • 激活虚拟环境：
     • Windows:

       venv\Scripts\activate
       

     • macOS/Linux:

       source venv/bin/activate
       

     激活后，你的命令行提示符前面通常会显示 (venv)。

3. 安装 FastAPI 和 Uvicorn：

   • Uvicorn 是一个 ASGI 服务器，用于运行 FastAPI 应用。
   • 在激活的虚拟环境中运行：

     pip install fastapi uvicorn
     

---

📝 第二步：创建你的第一个 FastAPI 应用

1. 在项目文件夹中，创建一个 Python 文件，例如 main.py。

2. 用文本编辑器或 IDE（如 VS Code、PyCharm）打开 main.py。

3. 输入以下代码：

   # 导入 FastAPI 类
   from fastapi import FastAPI
   
   # 创建一个 FastAPI 应用实例。通常命名为 `app`
   app = FastAPI()
   
   # 定义一个路径操作装饰器：告诉 FastAPI 下面的函数处理哪个路径的哪个 HTTP 方法
   # 路径：根路径 "/"
   # HTTP 方法：GET
   @app.get("/")
   async def read_root():
       # 这个函数处理到达根路径的 GET 请求
       # 它返回一个简单的 JSON 响应
       return {"message": "Hello, FastAPI World!"}
   
   # 另一个例子：带路径参数的 GET 请求
   @app.get("/items/{item_id}")
   async def read_item(item_id: int):  # 使用类型注解声明 `item_id` 应为整数
       # 函数返回一个 JSON 对象，包含传入的 item_id
       return {"item_id": item_id}
   

   代码解释：

   • from fastapi import FastAPI: 导入核心的 FastAPI 类。
   • app = FastAPI(): 创建你的 FastAPI 应用实例。这是所有操作的核心对象。
   • @app.get("/"): 这是一个路径操作装饰器。它告诉 FastAPI：当收到一个指向路径 / 的 GET HTTP 请求时，应该调用紧挨着它下面的函数 (read_root) 来处理。
   • async def read_root():: 定义处理函数。async 表示这是一个异步函数（FastAPI 天生支持异步）。
   • return {"message": "..."}: 函数直接返回一个 Python dict。FastAPI 会自动将其转换为 JSON 格式作为 HTTP 响应。
   • @app.get("/items/{item_id}"): 定义了另一个路径 /items/{item_id}。{item_id} 是一个路径参数。它的值会被传递给函数 read_item 的参数 item_id。
   • item_id: int: 使用 Python 类型注解声明 item_id 应为整数类型。FastAPI 会自动进行类型检查和转换（如果客户端传字符串 "5"，会转换成整数 5；如果传 "abc"，会返回错误）。

---

⚙ 第三步：运行开发服务器

在终端（确保在激活了虚拟环境的项目目录下），运行以下命令启动服务器：

uvicorn main:app --reload

命令解释：

• main: 指你的 Python 文件 main.py。
• app: 指在 main.py 文件中创建的 FastAPI 应用实例（app = FastAPI()）。
• --reload: 使服务器在检测到代码更改后自动重启。仅在开发时使用。

看到类似这样的输出，说明服务器已启动：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

---

🔍 第四步：测试你的 API

1. 访问根路径：

   • 打开浏览器，访问 http://127.0.0.1:8000/。
   • 你应该看到 JSON 响应：{"message":"Hello, FastAPI World!"}。

2. 访问带路径参数的路径：

   • 访问 http://127.0.0.1:8000/items/42。
   • 你应该看到：{"item_id":42}。尝试将 42 换成其他数字或字符串（如 abc），观察 FastAPI 的类型检查和错误处理。

3. 使用 curl (命令行测试)：

   curl http://127.0.0.1:8000/
   curl http://127.0.0.1:8000/items/999
   

---

📄 第五步：处理查询参数（Query Parameters）

查询参数出现在 URL 的 ? 之后，通常用于过滤、分页等。修改 main.py，添加一个新函数：

from fastapi import FastAPI

app = FastAPI()

# ... 之前的 root 和 item_id 路由 ...

@app.get("/users/")
async def read_users(skip: int = 0, limit: int = 10):  # 声明两个带默认值的查询参数
    # 假设我们这里模拟从数据库获取用户列表
    # 使用 skip 和 limit 进行分页
    # 实际应用中，这里会查询数据库
    return {
        "skip": skip,
        "limit": limit,
        "users": [{"id": i, "name": f"User {i}"} for i in range(skip, skip + limit)]
    }

代码解释：

• @app.get("/users/"): 定义一个路径 /users/。
• async def read_users(skip: int = 0, limit: int = 10):: 函数参数 skip 和 limit 不是路径的一部分，它们会被 FastAPI 识别为查询参数。
  • skip: int: 声明 skip 应为整数。
  • = 0: 设置默认值为 0。如果客户端不提供 skip 参数，将使用 0。
  • limit: int = 10: 同理，默认值为 10。

测试：

• 访问 http://127.0.0.1:8000/users/。将使用默认值：skip=0, limit=10。
• 访问 http://127.0.0.1:8000/users/?skip=20&limit=5。将跳过前 20 个用户，返回接下来的 5 个用户。

---

📦 第六步：使用 Pydantic 模型处理请求体（Request Body）

当你需要客户端发送复杂数据（如创建新项目）时，使用请求体。FastAPI 深度集成 Pydantic 来定义数据模型并验证数据。

1. 定义 Pydantic 模型： 在 main.py 中添加导入和模型定义：

   from pydantic import BaseModel  # 导入 BaseModel
   
   # 定义一个 Pydantic 模型，代表一个 Item
   class Item(BaseModel):
       name: str  # 必填字段，字符串类型
       description: str | None = None  # 可选字段，字符串或 None，默认 None
       price: float  # 必填字段，浮点数
       tax: float | None = None  # 可选字段，浮点数或 None，默认 None
   

   模型解释：

   • 继承自 BaseModel。
   • 使用类型注解定义字段及其类型（str, float）。
   • | None = None: 表示该字段是可选的，如果不提供，默认值为 None。str | None 是 Python 3.10+ 的联合类型写法（Union type）。在 3.9 及以下，可以用 Optional[str] = None。

2. 创建处理 POST 请求的路由：

   @app.post("/items/")  # 处理 POST 请求到 /items/
   async def create_item(item: Item):  # 参数 `item` 的类型是 Item 模型
       # FastAPI 会自动：
       #   1. 读取请求体（JSON）
       #   2. 转换成 Item 类型的对象（如果 JSON 不符合模型定义，会返回错误）
       #   3. 验证数据（确保 name 是字符串，price 是数字等）
       #   4. 将 `item` 对象传递给这个函数
       # 我们直接返回接收到的 item 对象（FastAPI 会自动转 JSON）
       # 通常这里会保存到数据库
       return item
   

   代码解释：

   • @app.post("/items/"): 处理 /items/ 路径的 POST HTTP 请求。
   • async def create_item(item: Item):: 函数参数 item 声明为 Item 类型。FastAPI 会知道：
     • 这个路由期望一个请求体。
     • 请求体应该是一个 JSON 对象。
     • 这个 JSON 对象应该符合 Item 模型的结构。
     • 自动将 JSON 数据解析并验证成 Item 实例，然后传递给 item 参数。

测试： 我们需要一个工具来发送带 JSON 请求体的 POST 请求。最简单的方法是使用 FastAPI 自动生成的交互式文档（下一节介绍），或者使用 curl：

curl -X POST "http://127.0.0.1:8000/items/" \
  -H "Content-Type: application/json" \
  -d '{"name":"Foo", "description":"An optional description", "price":45.99, "tax":3.2}'

你应该会收到一个 JSON 响应，内容和你发送的请求体一致。

---

📚 第七步：神奇的自动文档

FastAPI 基于 OpenAPI 和 JSON Schema 标准自动生成交互式 API 文档。这是它的一大亮点！

1. 访问 Swagger UI： 浏览器访问 http://127.0.0.1:8000/docs。你会看到一个漂亮的、可交互的文档界面（由 Swagger UI 提供）。

   • 它列出了你定义的所有路由（/, /items/{item_id}, /users/, /items/）。
   • 你可以展开每个路由，查看它接受的参数（路径参数、查询参数、请求体模型）。
   • 你可以直接在页面上点击 "Try it out" 按钮，填写参数，然后点击 "Execute" 来测试 API！无需离开浏览器。

2. 访问 ReDoc： 浏览器访问 http://127.0.0.1:8000/redoc。这是另一种风格的文档（由 ReDoc 提供），更侧重于渲染和展示。

文档的好处：

• 开发者（包括你自己）可以立即了解 API 的使用方法。
• 无需手动编写和维护大量文档。
• 方便测试接口。

---

🧩 总结与下一步

恭喜！你已经完成了 FastAPI 的入门，学会了：

• 安装和设置环境
• 创建基本应用和路由
• 处理路径参数、查询参数
• 使用 Pydantic 模型处理请求体
• 运行开发服务器
• 测试 API
• 利用自动生成的交互式文档

接下来可以学习：

• 依赖注入（Dependency Injection）: 管理共享逻辑（如数据库连接、认证）。
• 数据库集成: 使用 SQLAlchemy ORM 或 Tortoise-ORM 等连接数据库。
• 认证和授权: 实现用户登录、权限控制（如 OAuth2 with JWT）。
• 中间件（Middleware）: 在请求处理前后添加自定义逻辑。
• 后台任务（Background Tasks）: 处理耗时操作，不阻塞主请求。
• 部署: 使用 Gunicorn 配合 Uvicorn 部署到生产环境（如 Linux 服务器、Docker、云服务）。
• 更复杂的 Pydantic 模型: 嵌套模型、自定义验证器。
• OpenAPI 高级定制: 添加更多元数据到文档。

FastAPI 的官方文档非常优秀：https://fastapi.tiangolo.com/。它是深入学习的最佳资源。

动手实践是最好的学习方式！尝试创建一个简单的待办事项列表（Todo List）API 来巩固知识吧！祝你学习愉快！😊