欢迎来到 FastAPI 的世界！我们将通过构建你的第一个 API 应用，在 5 分钟内体验 FastAPI 的核心魅力：极速开发、自动文档、类型安全。
🚀 第一步：环境准备
确保你已安装 Python 3.8+。打开终端，执行以下命令：
# 1. 创建项目文件夹并进入
mkdir my-first-api && cd my-first-api
# 2. 创建虚拟环境 (推荐)
python -m venv venv
# 3. 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# 4. 安装 FastAPI 和 Uvicorn (ASGI 服务器)
pip install fastapi uvicorn[standard]💻 第二步：编写代码
新建一个文件 main.py，输入以下代码：
from fastapi import FastAPI
# 1. 创建 FastAPI 实例
app = FastAPI(title="我的第一个 API", version="0.1.0")
# 2. 定义根路径路由 (GET 请求)
@app.get("/")
def read_root():
return {"message": "Hello, FastAPI!"}
# 3. 定义带参数的路由
@app.get("/items/{item_id}")
def get_item(item_id: int, q: str | None = None):
"""
获取特定 ID 的商品信息。
- **item_id**: 商品的唯一标识 (整数)
- **q**: 可选的查询关键词
"""
return {
"item_id": item_id,
"query": q,
"description": f"这是 ID 为 {item_id} 的商品详情"
}▶️ 第三步：运行服务
在终端中执行：
uvicorn main:app --reloadmain: 对应文件名main.pyapp: 对应文件中创建的FastAPI()实例名--reload: 开启热重载，修改代码后服务器会自动重启（开发必备）
你会看到类似输出：INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
🌐 第四步：测试与自动文档 (最爽的部分)
FastAPI 会根据你的代码自动生成交互式 API 文档，无需手写！
- Swagger UI: 打开浏览器访问 http://127.0.0.1:8000/docs
- 你可以直接在这里点击 “Try it out” 发送请求，查看响应结果。
- ReDoc: 访问 http://127.0.0.1:8000/redoc
- 提供更清晰、适合阅读的静态文档视图。
手动测试：
- 访问
http://127.0.0.1:8000/→ 看到{"message":"Hello, FastAPI!"} - 访问
http://127.0.0.1:8000/items/5?q=shoes→ 看到包含 ID 和查询词的 JSON。 - 尝试访问
http://127.0.0.1:8000/items/abc→ 你会看到一个漂亮的 422 错误，提示item_id必须是整数。这就是 FastAPI 基于类型提示的自动数据验证！
🔍 代码深度解析
| 代码片段 | 作用 |
|---|---|
@app.get("/") | 装饰器路由。告诉 FastAPI：当收到 / 的 GET 请求时，执行下面的函数。还有 @app.post(), @app.put() 等。 |
def read_root(): | 路径操作函数。负责处理逻辑并返回数据。 |
return {...} | FastAPI 会自动将字典转换为 JSON 格式返回给客户端。 |
item_id: int | 路径参数 + 类型提示。FastAPI 会自动从 URL 中提取 item_id 并尝试转为 int。如果转换失败，自动返回错误。 |
q: str | None = None | 查询参数 + 默认值。对应 URL 中的 ?q=xxx。None 表示该参数是可选的。 |
🛠️ 进阶小挑战
试着在你的 main.py 中添加一个 POST 请求，用于接收用户提交的数据：
from pydantic import BaseModel
# 1. 定义数据模型 (Pydantic)
class User(BaseModel):
name: str
age: int | None = None
# 2. 定义 POST 路由
@app.post("/users/")
def create_user(user: User):
# user 对象已经经过验证，可以直接使用
return {"msg": f"用户 {user.name} 创建成功", "age": user.age}保存文件（Uvicorn 会自动重启），然后去 http://127.0.0.1:8000/docs 找到 /users/ 接口，点击 “Try it out”，填入 JSON 数据并执行。你会发现 FastAPI 甚至为你生成了请求体的示例！
✅ 总结
你已经完成了：
- 安装了 FastAPI 和 Uvicorn。
- 编写了第一个包含路径参数和查询参数的 API。
- 利用了 FastAPI 最强大的特性：自动生成的 Swagger 文档和基于类型的自动验证。
接下来你想探索什么？
- 📦 连接数据库 (SQLAlchemy / SQLModel)
- 🔐 用户认证 (JWT Token)
- 📂 项目结构优化 (如何拆分路由和模型)
告诉我你的兴趣点，我们继续深入！