📚 课程目录第2章环境搭建与项目初始化

环境搭建与项目初始化：Python版本管理、虚拟环境、依赖安装、FastAPI与Uvicorn的配置、项目目录结构设计

在开始编写任何FastAPI代码之前，必须先建立一个干净、可复现且隔离的开发环境。很多初学者在项目初期图省事，直接在全局Python环境中安装依赖，结果在多个项目切换时遭遇版本冲突，甚至导致系统Python环境损坏。本章将系统性地讲解从Python版本管理到项目目录结构设计的完整流程，帮助你从一开始就建立起专业级的工程化基础。我们将依次解决“用哪个Python版本”“如何隔离依赖”“如何安装与配置FastAPI和Uvicorn”以及“项目文件如何组织”这四个核心问题。

上图展示了从Python版本管理到项目结构设计的完整链路。下面我们将逐一深入每个环节，确保你不仅知道“怎么做”，更理解“为什么这么做”。

2.1 Python版本管理：为什么需要pyenv或uv

核心原理：Python版本管理工具解决的是“多版本共存”问题。不同项目可能依赖不同版本的Python（例如项目A需要3.9，项目B需要3.11），而系统自带的Python通常只有一个版本。pyenv允许你在用户级别安装多个Python版本，并通过目录切换机制动态调整当前终端使用的Python版本。uv则是Rust编写的新一代包管理器，它同时集成了Python版本管理、虚拟环境和依赖安装功能，速度比pip快10-100倍。

操作流程：以pyenv为例，安装后通过以下命令管理版本：

# 安装pyenv（macOS）
brew install pyenv

# 查看可安装的Python版本
pyenv install --list

# 安装Python 3.11.7
pyenv install 3.11.7

# 设置全局版本（不推荐）或项目本地版本（推荐）
pyenv local 3.11.7

# 验证当前版本
python --version

实战场景：假设你同时维护一个旧版Django项目（需要Python 3.8）和一个新的FastAPI项目（需要Python 3.11）。使用pyenv，你可以在两个项目目录下分别执行pyenv local 3.8.18和pyenv local 3.11.7，进入哪个目录，终端就自动切换到对应的Python版本，互不干扰。

经验提醒：FastAPI官方要求Python 3.8+，但强烈建议使用Python 3.10或更高版本。3.10+引入了更清晰的类型提示语法（如X | Y联合类型），并且性能有所提升。如果你使用uv，一条命令uv python install 3.11.7即可完成版本安装。

2.2 虚拟环境：依赖隔离的基石

核心原理：虚拟环境为每个项目创建独立的Python解释器副本和site-packages目录。这意味着项目A安装的Django 4.2不会影响项目B的Django 3.2。Python 3.3+内置的venv模块是官方推荐的方式，它轻量且无需额外安装。

操作流程：创建并激活虚拟环境的标准步骤：

# 在项目根目录下创建虚拟环境
python -m venv venv

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

# 激活虚拟环境（Windows）
venv\Scripts\activate

# 检查当前Python路径，确认已进入虚拟环境
which python

# 退出虚拟环境
deactivate

案例拆解：某团队在开发一个FastAPI微服务时，最初没有使用虚拟环境，直接在全局环境安装了fastapi、uvicorn、sqlalchemy等包。两周后，他们需要开发另一个数据分析项目，安装了pandas 2.0，结果pandas的依赖numpy版本与FastAPI项目中的numpy冲突，导致FastAPI项目启动时报错ValueError: numpy.ndarray size changed。排查了整整一天才定位到是全局依赖污染问题。改用虚拟环境后，每个项目独立运行，此类问题彻底消失。

对比维度	全局环境	虚拟环境
依赖隔离	所有项目共享，易冲突	项目间完全隔离
版本控制	难以精确控制	可锁定精确版本
可复现性	差，换机器即失效	配合requirements.txt可完全复现
安全性	升级系统包可能破坏项目	不影响系统Python

风险提示：不要将虚拟环境目录（venv/）提交到Git仓库。它体积大且包含本机路径信息，其他开发者应通过requirements.txt自行创建。在项目根目录添加.gitignore文件，写入venv/、__pycache__/、.env等条目。

2.3 依赖安装：FastAPI与Uvicorn的配置

核心原理：FastAPI是一个现代Web框架，它依赖Pydantic进行数据验证，依赖Starlette处理HTTP协议。Uvicorn是一个基于uvloop和httptools的ASGI服务器，负责接收HTTP请求并将其传递给FastAPI应用。两者配合，才能提供高性能的异步Web服务。

操作流程：在激活虚拟环境后，安装依赖并生成requirements.txt：

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

# 安装开发依赖（可选，用于调试和测试）
pip install httpx pytest

# 导出依赖清单
pip freeze > requirements.txt

# 查看已安装的版本
pip list | grep -E "fastapi|uvicorn"

Uvicorn配置说明：Uvicorn支持多种启动参数，常用配置如下：

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

# 生产模式启动（多worker）
uvicorn app.main:app --workers 4 --host 0.0.0.0 --port 8000

# 通过Python代码启动
if __name__ == "__main__":
    import uvicorn
    uvicorn.run("app.main:app", host="0.0.0.0", port=8000, reload=True)

案例拆解：一个典型的FastAPI项目启动报错场景：ModuleNotFoundError: No module named 'uvicorn'。原因通常是用户忘记激活虚拟环境，或者激活了错误的虚拟环境。排查步骤：1) 执行which python确认当前解释器路径；2) 执行pip list检查uvicorn是否已安装；3) 如果未安装，执行pip install uvicorn[standard]。另一个常见问题是端口被占用，此时uvicorn会报OSError: [Errno 48] Address already in use，使用lsof -i :8000查找占用进程并处理。

  最佳实践：使用uvicorn[standard]而不是uvicorn，因为standard版本包含了websockets、httptools、uvloop等高性能组件，对WebSocket支持和并发性能有显著提升。在requirements.txt中，建议锁定精确版本号（如fastapi==0.115.6），避免未来版本更新带来的不兼容。

2.4 项目目录结构设计：从单体到模块化

核心原理：良好的目录结构是项目可维护性的基石。FastAPI官方推荐按“模块化”组织代码，将路由、模型、模式、服务等分离。这遵循了“关注点分离”原则，让每个文件职责单一，便于团队协作和单元测试。

推荐结构：以下是一个经过实践检验的FastAPI项目结构：

my_fastapi_project/
├── app/
│   ├── __init__.py
│   ├── main.py              # 应用入口，创建FastAPI实例
│   ├── config.py            # 配置管理（读取.env）
│   ├── routers/             # 路由模块
│   │   ├── __init__.py
│   │   ├── users.py         # 用户相关接口
│   │   └── items.py         # 商品相关接口
│   ├── models/              # SQLAlchemy ORM模型
│   │   ├── __init__.py
│   │   └── user.py
│   ├── schemas/             # Pydantic模型（请求/响应）
│   │   ├── __init__.py
│   │   └── user.py
│   ├── services/            # 业务逻辑层
│   │   ├── __init__.py
│   │   └── user_service.py
│   └── utils/               # 工具函数
│       ├── __init__.py
│       └── security.py
├── tests/                   # 单元测试
│   ├── __init__.py
│   └── test_users.py
├── .env                     # 环境变量（不入库）
├── .env.example             # 环境变量模板（入库）
├── .gitignore
├── requirements.txt
└── README.md

案例拆解：某初创公司开发一个电商API，初期将所有路由写在main.py中，文件迅速膨胀到2000多行。每次修改一个接口，都需要滚动很久才能找到对应代码，且合并代码时频繁冲突。重构为上述模块化结构后，每个路由文件控制在200行以内，团队按模块分工（A负责users，B负责items），Git冲突减少了80%，新成员上手时间从3天缩短到半天。

配置管理：使用pydantic-settings库管理配置，从.env文件读取：

# config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "My FastAPI App"
    database_url: str = "sqlite:///./test.db"
    debug: bool = False
    
    class Config:
        env_file = ".env"

settings = Settings()

常见误区：1) 将.env文件提交到Git仓库，导致数据库密码、密钥泄露。正确做法是提交.env.example模板，真实配置通过环境变量或本地文件注入。2) 在__init__.py中写业务逻辑，这个文件应保持为空或仅做包标记。3) 所有模型都放在一个models.py中，当模型超过5个时就应该拆分为独立模块。

总结复盘：环境搭建是FastAPI项目的第一道门槛，也是后续所有开发工作的基础。通过pyenv管理Python版本、venv隔离依赖、requirements.txt锁定版本、模块化组织代码，你构建的不仅是一个可运行的API，更是一个可维护、可扩展、可协作的工程。记住：环境搭建的投入产出比极高——前期多花30分钟做好隔离和结构设计，后期能节省数天的排障时间。建议在项目初始化时，就按照上述标准流程操作，并养成每次进入项目先激活虚拟环境的习惯。