📚 课程目录第2章环境搭建

2. 环境搭建：安装 Python 3.10+、FastAPI、Uvicorn、Postman/cURL，创建基础项目结构

在开始编写鉴权拦截中间件之前，需要先搭建一套干净、可复现的本地开发环境。本章将指导你完成从 Python 版本选择到项目骨架创建的全过程，确保后续所有工程案例都能在统一的环境中运行。

2.1 技术栈版本选择与说明

本课程基于以下核心组件版本进行开发与测试，建议严格对齐以避免兼容性问题：

组件	推荐版本	用途	安装方式
Python	3.10 ~ 3.12	运行时基础	官网 / pyenv
FastAPI	0.110+	Web 框架	pip
Uvicorn	0.29+	ASGI 服务器	pip
Postman	最新稳定版	API 调试	官网下载
cURL	系统自带 / 7.68+	命令行测试	系统包管理器

版本对齐提示：Python 3.9 及以下版本已停止安全更新，且不支持部分类型注解语法；Python 3.13 目前部分第三方库尚未适配。本课程锁定 3.10~3.12 区间，兼顾稳定性与新特性。

2.2 安装 Python 3.10+

推荐使用 pyenv 管理多版本 Python，避免污染系统环境。以下是 macOS / Linux 的快速安装步骤：

# 安装 pyenv（macOS 使用 Homebrew）
brew install pyenv

# 安装 Python 3.11
pyenv install 3.11.9

# 设置全局版本
pyenv global 3.11.9

# 验证版本
python --version
# 输出: Python 3.11.9

Windows 用户建议直接使用 Python 官网安装包，安装时勾选 "Add Python to PATH"。

2.3 创建虚拟环境与安装依赖

每个项目使用独立的虚拟环境，是工程化部署的基本要求。以下命令在项目根目录下创建并激活环境：

# 创建项目目录
mkdir openapi-auth-project && cd openapi-auth-project

# 创建虚拟环境
python -m venv venv

# 激活环境（macOS/Linux）
source venv/bin/activate

# 激活环境（Windows PowerShell）
.\venv\Scripts\Activate.ps1

# 安装核心依赖
pip install fastapi uvicorn[standard] python-multipart

# 验证安装
pip list | grep -E "fastapi|uvicorn"
# 输出示例:
# fastapi           0.115.0
# uvicorn           0.30.6

注意：不要使用 pip install fastapi uvicorn 省略 [standard]，否则会缺少 uvicorn[standard] 包含的 watchfiles 热重载支持，影响开发效率。

2.4 基础项目结构设计

一个适合鉴权拦截工程的项目结构，应当将路由、中间件、模型、配置清晰分离。以下是本课程采用的标准骨架：

openapi-auth-project/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI 应用入口
│   ├── config.py            # 配置管理（密钥、算法等）
│   ├── middleware/
│   │   ├── __init__.py
│   │   └── auth_middleware.py  # 鉴权拦截中间件
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── public.py        # 公开接口（登录、注册）
│   │   └── protected.py     # 受保护接口（需鉴权）
│   ├── models/
│   │   ├── __init__.py
│   │   └── token.py         # Token 数据模型
│   └── utils/
│       ├── __init__.py
│       └── jwt_handler.py   # JWT 签发与验证工具
├── tests/
│   ├── __init__.py
│   └── test_auth.py         # 鉴权单元测试
├── requirements.txt         # 依赖锁定文件
└── .env                     # 环境变量（不提交到 Git）

  结构要点：
  main.py 只做应用初始化与路由挂载，不写业务逻辑。
middleware/ 目录独立存放鉴权、日志、CORS 等中间件。
routers/ 按公开/受保护拆分，便于后续添加权限粒度控制。
utils/ 封装 JWT 工具函数，保持中间件代码简洁。

2.5 编写最小化 FastAPI 应用

在 app/main.py 中写入以下代码，验证环境是否正常工作：

from fastapi import FastAPI

app = FastAPI(title="OpenAPI Auth Demo", version="0.1.0")

@app.get("/")
def root():
    return {"message": "环境搭建成功，鉴权拦截工程准备就绪"}

@app.get("/health")
def health_check():
    return {"status": "ok"}

2.6 启动 Uvicorn 并验证

使用以下命令启动开发服务器，开启热重载：

# 开发模式（热重载）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 输出示例:
# INFO:     Uvicorn running on http://0.0.0.0:8000
# INFO:     Application startup complete.

打开浏览器访问 http://localhost:8000/docs，应看到 FastAPI 自动生成的 Swagger 文档页面。访问 http://localhost:8000/health 应返回 JSON：{"status": "ok"}。

2.7 使用 Postman / cURL 测试接口

在终端或 Postman 中执行以下请求，确认服务响应正常：

# cURL 测试根路径
curl http://localhost:8000/
# 返回: {"message":"环境搭建成功，鉴权拦截工程准备就绪"}

# cURL 测试健康检查
curl http://localhost:8000/health
# 返回: {"status":"ok"}

Postman 操作步骤：

打开 Postman，点击 New Collection，命名为 OpenAPI Auth Demo。
添加 GET 请求，URL 填入 http://localhost:8000/，点击 Send。
添加第二个 GET 请求，URL 填入 http://localhost:8000/health，确认返回 200。
将两个请求保存到集合中，后续章节将在此基础上添加鉴权测试。

2.8 环境搭建流程总览

下图展示了从零开始到服务可用的完整链路，以及各工具在链路中的角色：

2.9 常见问题与避坑指南

问题现象	原因	解决方案
`pip: command not found`	Python 未加入 PATH	重新安装 Python 并勾选 "Add to PATH"
`uvicorn: command not found`	虚拟环境未激活	执行 `source venv/bin/activate`（Linux/macOS）
`ModuleNotFoundError: No module named 'fastapi'`	依赖安装到了系统环境而非虚拟环境	确认 `which python` 指向 venv 路径，重新 `pip install`
热重载不生效	未安装 `uvicorn[standard]`	`pip install uvicorn[standard]` 重新安装
端口 8000 被占用	其他进程占用端口	使用 `lsof -i :8000` 查找并 kill，或更换 `--port 8001`

生产环境提示：本课程开发阶段使用 --reload 热重载。生产部署时务必去掉 --reload 参数，并使用 gunicorn + uvicorn workers 多进程模式，具体配置将在第 28 章详细讲解。

2.10 本章小结

至此，你已经完成了以下关键步骤：

安装了 Python 3.10+ 并创建了隔离的虚拟环境。
通过 pip 安装了 FastAPI 与 Uvicorn 核心依赖。
搭建了适合鉴权拦截工程的标准项目目录结构。
编写并启动了最小化 FastAPI 应用，验证了 Swagger 文档与健康检查接口。
使用 Postman 和 cURL 完成了接口测试，确认开发环境就绪。