FastAPI 入门与环境搭建

第 1 章 · FastAPI 入门与环境搭建

本章目标：理解 FastAPI 现代异步 API 框架定位；在独立 venv 中安装 FastAPI 与 uvicorn，创建虚构练习项目 svc-demo；编写最小可运行应用并访问 Swagger 自动文档（/docs）；能用对照表说明 FastAPI 与 shop-demo（Django）、api-demo（Flask） 在路由、类型提示、文档、异步上的差异；掌握开发服务器启动与项目目录规划。

学时建议：3～4 小时（含 1 小时跟练）

前置：完成 python-dev ch10（python -m venv、pip 安装、激活虚拟环境）；学过 django-web 或 flask-web 更佳但非必须。

1.1 场景说明：为什么需要 svc-demo？

你在 django-web 中用 shop-demo 搭建了电商后台，在 flask-web 中用 api-demo 实现了轻量 REST。现在团队要交付一套高性能微服务 API，对外规划域名为虚构的 https://api.example.com（教学占位，非真实生产地址），项目代号 svc-demo（Service Demo）。

维度	shop-demo（Django）	api-demo（Flask）	svc-demo（FastAPI）
定位	全功能后台、Admin	轻量 API + 少量页面	纯 API、微服务优先
路由	`urls.py` + `path()`	`@app.route` / Blueprint	装饰器 + 类型提示
数据校验	Serializer / Form	Marshmallow / 手写	Pydantic v2 内置
API 文档	需 DRF + drf-spectacular	需 Flask-RESTX 等	OpenAPI 自动生成
异步	ASGI 支持（3.x）	同步为主	原生 async/await
适合场景	运营后台、内容站	内部 API、原型	高并发 API、BFF、网关
本章项目代号	shopdemo	api-demo	svc-demo

说明：本章所有路径、域名、密钥均为教学虚构，不涉及任何真实公司仓库、内部配置或生产密钥。

学习路径（fastapi-web）
  ch01 入门与环境  →  ch02 路由与依赖  →  ch03 Pydantic  →  ch04 请求响应
       ↑ 你在这里

1.2 三框架核心对照表

对比项	Django（shop-demo）	Flask（api-demo）	FastAPI（svc-demo）
哲学	全栈、batteries included	微框架、按需扩展	API 优先、类型驱动
启动命令	`python manage.py runserver`	`flask run`	`uvicorn main:app --reload`
默认服务器	WSGI（开发）	Werkzeug（开发）	ASGI uvicorn
请求体解析	`request.POST` / DRF	`request.get_json()`	自动绑定 Pydantic 模型
响应格式	`JsonResponse` / DRF	`jsonify()`	`return dict` 自动序列化
交互文档	需额外配置	需 Swagger 扩展	`/docs` 开箱即用
性能取向	中等	中等	高（异步 + Starlette）
学习曲线	概念多、路径清晰	先小后大	需熟悉类型提示与 async

何时选 FastAPI：对外 REST/GraphQL 网关、需要自动 OpenAPI 文档、高并发 I/O 密集（数据库、HTTP 调用）、与前端/移动端契约驱动开发。

何时仍选 Django/Flask：复杂后台页面、Admin、模板渲染为主；团队已有成熟 Django/Flask 基建且无需异步。

本课程采用 三项目对照：shop-demo 学全栈后台、api-demo 学轻量 API、svc-demo 学现代异步 API——便于你在真实选型时做理性权衡，而非「唯快不破」。

1.3 环境准备（venv + pip）

与 python-dev ch10 相同，在独立目录练习，勿与 shop-demo、api-demo 共用 venv。

cd ~/python-learn
mkdir svc-demo && cd svc-demo
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
# source .venv/bin/activate

pip install "fastapi[standard]>=0.115,<1" "uvicorn[standard]>=0.30"
python -c "import fastapi; print(fastapi.__version__)"

requirements.txt（建议尽早维护）：

fastapi[standard]>=0.115,<1
uvicorn[standard]>=0.30

包	作用
`fastapi`	Web 框架本体（基于 Starlette + Pydantic）
`uvicorn`	ASGI 服务器，生产可用
`fastapi[standard]`	附带 `uvicorn`、`httpx` 等常用依赖
`pydantic`	数据校验（随 fastapi 安装，v2）

安装完成后可用 pip freeze > requirements.txt 锁定版本，便于与队友或 CI 环境保持一致。

命令	作用
`python -m venv .venv`	创建隔离环境
`pip install -r requirements.txt`	安装依赖
`uvicorn main:app --reload`	开发热重载启动

版本提示：本教程基于 FastAPI 0.115+ 与 Pydantic v2。若 --version 显示 0.9x，请先 pip install -U "fastapi[standard]"。

1.4 最小 FastAPI 应用

1.4.1 目录结构（第 1 章版）

svc-demo/                          # 仓库根（练习用）
├── .venv/
├── requirements.txt
├── .env.example                   # 仅占位，不含真实密钥
├── main.py                        # 应用入口（本章单文件）
└── README.md

1.4.2 main.py 完整代码

"""svc-demo 最小入口 — FastAPI 入门示例"""
from fastapi import FastAPI

app = FastAPI(
    title="svc-demo API",
    description="贤紫技术学院 FastAPI 练习项目（虚构微服务）",
    version="0.1.0",
    docs_url="/docs",       # Swagger UI
    redoc_url="/redoc",     # ReDoc 备选文档
)

@app.get("/")
async def root():
  """根路径健康检查"""
  return {"service": "svc-demo", "status": "ok"}


@app.get("/health")
async def health():
  """部署探活端点（与 Django /accounts/health/ 对照）"""
  return {"status": "healthy"}


@app.get("/api/v1/info")
async def api_info():
  """返回 API 元信息，供 api.example.com 联调占位"""
  return {
      "name": "svc-demo",
      "domain": "api.example.com",
      "framework": "FastAPI",
      "docs": "/docs",
  }

浏览器访问 http://127.0.0.1:8000/，根路径返回 JSON 即表示 ASGI 栈工作正常；与 Django 欢迎页、Flask 默认页不同，svc-demo 从第一天起就是 API 优先。

1.4.3 启动与验证

# 方式一：命令行指定模块
uvicorn main:app --reload --host 127.0.0.1 --port 8000

# 方式二：在 main.py 末尾添加（开发用）
# if __name__ == "__main__":
#     import uvicorn
#     uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

URL	预期结果
`http://127.0.0.1:8000/`	`{"service":"svc-demo","status":"ok"}`
`http://127.0.0.1:8000/health`	`{"status":"healthy"}`
`http://127.0.0.1:8000/docs`	Swagger UI 交互页面
`http://127.0.0.1:8000/redoc`	ReDoc 文档
`http://127.0.0.1:8000/openapi.json`	OpenAPI 3.x JSON 规范

启动成功后，建议将上述 URL 存入浏览器书签，后续章节将频繁使用 /docs 验证新接口。

也可访问 /redoc 阅读更适合打印与交付的文档；/openapi.json 可导入 Postman 或用于生成 TypeScript SDK（ch14）。

在 Swagger UI 中点击 Try it out → Execute，可直接在浏览器内调试接口，无需 Postman。