📚 课程目录第4章 API开发环境搭建

4. API 开发环境搭建：Python Flask/FastAPI 框架选择、虚拟环境配置、依赖管理

在开始编写车辆门窗控制 API 之前，必须搭建一个稳定、可复现的开发环境。本章将指导你完成三个核心步骤：选择适合车载场景的 Web 框架、配置隔离的 Python 虚拟环境、以及通过 requirements.txt 管理项目依赖。一个规范的环境是后续所有接口开发的基础，也是团队协作和持续集成的保障。

4.1 框架选型：Flask vs FastAPI

Python 生态中，Flask 和 FastAPI 是构建 RESTful API 最主流的两个轻量级框架。对于车辆门窗控制这类对实时性、并发性和文档规范性有较高要求的场景，两者的差异非常关键。

对比维度	Flask (2.x / 3.x)	FastAPI (0.100+)
异步支持	原生同步，需额外安装 `quart` 或 `asyncio` 扩展	原生异步，基于 Starlette + Pydantic，天然支持 `async/await`
性能（并发）	同步阻塞，高并发需配合 Gunicorn + 多 worker	异步非阻塞，单进程即可处理大量长连接或 I/O 密集型请求
数据校验	需手动校验或集成 Marshmallow	内置 Pydantic 模型，自动校验请求/响应，生成 JSON Schema
API 文档	需手动集成 Flasgger 或 Flask-RESTx	自动生成 OpenAPI (Swagger) 和 ReDoc 交互文档
学习曲线	低，文档丰富，社区庞大	中等，需理解类型注解和异步编程
适用场景	原型验证、简单 CRUD、传统同步服务	高并发实时控制、微服务、需要严格接口契约的车载系统

  课程选型结论： 本课程采用 FastAPI 作为主要开发框架。原因在于：车辆门窗控制涉及多个车窗、门锁的并发状态查询与操作，异步模型能更高效地处理 I/O 等待；Pydantic 的自动校验可大幅减少参数错误导致的接口异常；自动生成的 Swagger 文档便于测试和集成。

4.2 虚拟环境配置

虚拟环境用于隔离不同项目的 Python 依赖，避免全局包冲突。推荐使用 Python 3.10+ 内置的 venv 模块，无需额外安装。

4.2.1 创建与激活虚拟环境

# 1. 在项目根目录创建虚拟环境（命名为 venv 或 .venv）
python -m venv venv

# 2. 激活虚拟环境
# Windows (CMD/PowerShell)
venv\Scripts\activate

# macOS / Linux (bash/zsh)
source venv/bin/activate

# 3. 验证激活成功（应显示 (venv) 前缀）
which python   # macOS/Linux
where python   # Windows

4.2.2 虚拟环境目录结构

激活后，所有通过 pip install 安装的包都会被放置在 venv/Lib/site-packages（Windows）或 venv/lib/python3.x/site-packages（Linux/macOS）中，与系统全局 Python 完全隔离。

最佳实践： 将 venv/ 目录添加到项目的 .gitignore 文件中，避免将虚拟环境提交到版本控制。团队成员应通过 requirements.txt 重建自己的虚拟环境。

4.3 依赖管理与 requirements.txt

requirements.txt 是 Python 项目标准的依赖清单文件，记录了项目运行所需的所有第三方包及其版本号。使用 pip freeze 命令可以自动生成当前虚拟环境的依赖列表。

4.3.1 生成 requirements.txt

# 确保虚拟环境已激活，且已安装必要的包
pip install fastapi uvicorn[standard] pydantic

# 冻结当前环境的所有依赖（包括子依赖）
pip freeze > requirements.txt

4.3.2 标准 requirements.txt 示例

fastapi==0.115.0
uvicorn[standard]==0.30.6
pydantic==2.9.2
pydantic-core==2.23.4
starlette==0.38.6
sniffio==1.3.1
anyio==4.4.0
typing_extensions==4.12.2

4.3.3 从 requirements.txt 重建环境

# 在新机器或 CI 环境中
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

版本锁定原则： 生产环境必须锁定所有依赖的精确版本号（如 fastapi==0.115.0），避免使用 >= 或 ~= 等模糊匹配。版本不一致是导致“在我机器上能跑”问题的首要原因。

4.4 开发环境架构总览

下图展示了本课程搭建的 API 开发环境整体架构，从虚拟环境隔离到 FastAPI 应用启动，再到依赖管理的完整链路。

4.5 环境验证与快速启动

完成上述配置后，通过以下步骤验证环境是否正常工作：

确认虚拟环境激活：终端提示符前显示 (venv)。
检查已安装包：执行 pip list 查看是否包含 fastapi、uvicorn、pydantic。
创建最小化应用：在项目根目录新建 main.py，写入以下代码：

# main.py
from fastapi import FastAPI

app = FastAPI(title="Car Door & Window Control API")

@app.get("/health")
async def health_check():
    return {"status": "ok", "service": "car-api"}

启动开发服务器：

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

访问验证：浏览器打开 http://localhost:8000/health，应返回 JSON {"status":"ok","service":"car-api"}。同时访问 http://localhost:8000/docs 可查看自动生成的 Swagger 文档。

开发效率提示： --reload 参数使 Uvicorn 在代码文件发生变更时自动重启服务器，无需手动停止再启动，大幅提升开发迭代速度。

4.6 本章小结

至此，你已完成 Car API 开发环境的搭建：

选择了 FastAPI + Uvicorn 作为异步 Web 框架组合，为后续高并发门窗控制接口奠定性能基础。
使用 venv 创建了隔离的 Python 虚拟环境，避免与系统全局包冲突。
通过 pip freeze > requirements.txt 锁定了所有依赖版本，确保团队和 CI 环境的一致性。
验证了最小化应用可正常启动并返回健康检查响应。