第2章环境搭建与项目初始化

第2章：环境搭建与项目初始化

说实话，很多初学者容易忽略环境搭建这一步。他们觉得写代码才是正经事，配环境就是浪费时间。我当年也这么想，结果呢？项目做到一半，依赖冲突、版本不兼容，折腾了两天才搞定。从那以后，我养成了一个习惯：开工之前，先把环境收拾利索。

这一章，我们就来把「地基」打牢。我会带着你一步步配置Python虚拟环境、搭建FastAPI项目骨架、管理依赖，最后设计一个清晰的目录结构。嗯，这些活儿看着琐碎，但做好了，后面几十章你会感谢自己的。

2.1 Python虚拟环境：为什么必须用？

你想想看，一个项目用Django 4.2，另一个项目用Django 3.2。如果都装到系统全局的Python里，那不乱套了？虚拟环境就是干这个的——每个项目拥有独立的Python解释器和包空间。

我个人习惯用 venv，它是Python 3自带的，不需要额外安装。当然，也有人喜欢 conda 或 pipenv，这个看个人喜好。但作为课程，我选最通用的方案。

2.1.1 创建虚拟环境

打开终端，进入你的项目根目录（比如 inventory-system），然后执行：

python -m venv venv

这条命令会在当前目录下生成一个 venv 文件夹。里面包含了独立的Python解释器和pip。注意，venv 这个名字是约定俗成的，你也可以叫 .venv 或 env，但我建议用 venv，因为很多工具默认会忽略它。

小提示： 如果你用的是Windows，记得把 python 换成 py 或 python3。macOS/Linux用户直接用 python3 更稳妥。

2.1.2 激活虚拟环境

创建好之后，需要激活它：

Windows (CMD/PowerShell): venv\Scripts\activate
macOS/Linux (bash/zsh): source venv/bin/activate

激活成功后，终端前面会出现 (venv) 字样。这时候你安装的所有包，都只会进到这个虚拟环境里，不会污染全局。

注意： 我曾经见过有人忘了激活虚拟环境，直接 pip install 装了一堆包到系统Python里。后来项目迁移时，依赖列表完全对不上，那叫一个头疼。所以，每次打开终端，第一件事就是检查有没有 (venv) 前缀。

2.2 FastAPI项目骨架搭建

FastAPI 是一个现代、高性能的Web框架。它基于Python类型提示，自动生成API文档，而且异步支持非常好。说白了，它就是为构建API而生的。

安装FastAPI和它的服务器（Uvicorn）：

pip install fastapi uvicorn

然后，创建一个 main.py 文件，写一个最简单的入口：

from fastapi import FastAPI

app = FastAPI(title="库存管理系统")

@app.get("/")
def read_root():
    return {"message": "Hello, Inventory System!"}

启动服务：

uvicorn main:app --reload

打开浏览器，访问 http://127.0.0.1:8000，你会看到 {"message": "Hello, Inventory System!"}。再访问 http://127.0.0.1:8000/docs，哇，自动生成的Swagger文档就出来了。是不是很爽？

  核心要点： --reload 参数让服务器在代码变更时自动重启。开发时必开，但生产环境千万别用。

2.3 依赖管理：requirements.txt

项目做大了，依赖的包会越来越多。你不可能每次都手动记录。这时候 requirements.txt 就派上用场了。

生成当前环境的依赖列表：

pip freeze > requirements.txt

打开这个文件，你会看到类似这样的内容：

fastapi==0.104.1
uvicorn==0.24.0
pydantic==2.5.2
...

别人拿到你的项目后，只需要执行：

pip install -r requirements.txt

就能一键安装所有依赖。注意，这里有个坑：pip freeze 会把所有包都列出来，包括那些间接依赖。我个人习惯是只保留直接依赖，然后手动加上版本号。比如：

fastapi>=0.100.0
uvicorn>=0.20.0
sqlalchemy>=2.0.0
pydantic>=2.0.0

这样更灵活，也更容易维护。为什么？因为间接依赖可能会变化，你锁死了反而容易出问题。

避坑指南： 我曾经在 requirements.txt 里写死了 pydantic==1.10.0，结果FastAPI新版本要求2.x，一升级就崩了。所以，用 >= 而不是 ==，除非你有特殊原因。

2.4 项目目录结构设计

一个好的目录结构，能让项目清晰、可扩展。我见过太多「所有代码塞一个文件夹」的项目，后期维护简直是噩梦。下面是我个人比较推荐的结构：

inventory-system/
├── app/
│   ├── __init__.py
│   ├── main.py              # 应用入口
│   ├── config.py            # 配置文件
│   ├── database.py          # 数据库连接
│   ├── models/              # 数据模型
│   │   ├── __init__.py
│   │   └── product.py
│   ├── schemas/             # Pydantic 模型（请求/响应）
│   │   ├── __init__.py
│   │   └── product.py
│   ├── api/                 # 路由层
│   │   ├── __init__.py
│   │   ├── v1/              # API版本控制
│   │   │   ├── __init__.py
│   │   │   └── products.py
│   │   └── deps.py          # 依赖注入
│   ├── services/            # 业务逻辑层
│   │   ├── __init__.py
│   │   └── product_service.py
│   └── utils/               # 工具函数
│       ├── __init__.py
│       └── helpers.py
├── tests/                   # 测试代码
│   ├── __init__.py
│   └── test_products.py
├── venv/                    # 虚拟环境（不提交到Git）
├── requirements.txt         # 依赖清单
├── .gitignore               # Git忽略规则
└── README.md                # 项目说明

这个结构遵循了「关注点分离」的原则。每一层各司其职：

models：数据库表结构（ORM模型）
schemas：API的请求/响应格式（Pydantic模型）
api：路由定义，只负责接收请求和返回响应
services：核心业务逻辑，比如库存计算、订单校验
utils：通用工具函数，比如日期格式化、加密

为什么要分这么细？举个例子：假如你要把数据库从SQLite换成PostgreSQL，你只需要改 database.py 和 models 里的内容，api 和 services 完全不用动。这就是解耦的好处。

  我的建议： 刚开始别追求完美，先按这个结构搭起来。随着项目变大，你自然会知道哪里需要调整。但千万别把所有代码都塞进 main.py，那是一条不归路。

2.5 本章知识体系一览

为了让你更直观地理解本章的内容，我画了一张图。它展示了从环境搭建到项目初始化的完整流程：

这张图把本章的四个核心步骤串起来了。你可以把它当作一个检查清单：每完成一步，就在心里打个勾。

2.6 小结

这一章我们干了四件事：

创建并激活了Python虚拟环境，让项目依赖独立
搭建了FastAPI项目骨架，写了一个能跑起来的Hello World
生成了requirements.txt，学会了依赖的导出和安装
设计了项目目录结构，为后续开发铺好了路

这些工作看似基础，但它们是整个课程的基石。你想想看，如果连环境都没配好，后面写再多代码也是白搭。嗯，现在地基已经打好了，接下来我们就可以开始真正写业务逻辑了。

最后提醒一句： 把 venv 文件夹加到 .gitignore 里，别把它提交到Git仓库。还有，每次安装新包后，记得更新 requirements.txt。这些小习惯，能帮你省下大把时间。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录