2. 接口开发环境搭建：Python虚拟环境配置、FastAPI框架安装、项目目录结构设计

搭建一个干净、可复现的开发环境是接口开发的第一步。本节将指导你完成从 Python 虚拟环境创建、FastAPI 框架安装到项目目录结构设计的全过程，确保后续开发过程依赖隔离、结构清晰。

2.1 Python 虚拟环境配置

虚拟环境可以为每个项目创建独立的 Python 运行环境，避免不同项目间的依赖冲突。推荐使用 Python 内置的 venv 模块或 conda 进行管理。

2.1.1 使用 venv 创建虚拟环境

# 创建项目目录并进入
mkdir ops-data-api
cd ops-data-api

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

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

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

# 验证环境
which python
# 输出应指向项目目录下的 venv/bin/python

2.1.2 使用 conda 创建虚拟环境（备选）

# 创建 conda 虚拟环境，指定 Python 版本
conda create -n ops-data-api python=3.10 -y

# 激活环境
conda activate ops-data-api

# 验证环境
python --version

2.2 FastAPI 框架安装

激活虚拟环境后，使用 pip 安装 FastAPI 及其生产级 ASGI 服务器 Uvicorn。

# 安装 FastAPI 和 Uvicorn
pip install fastapi uvicorn

# 安装常用辅助库（后续章节会用到）
pip install sqlalchemy pydantic alembic python-dotenv

# 验证安装
pip list | grep -E "fastapi|uvicorn|sqlalchemy|pydantic"

2.2.1 依赖管理：生成 requirements.txt

# 冻结当前环境依赖
pip freeze > requirements.txt

# 查看生成的依赖文件
cat requirements.txt

2.3 项目目录结构设计

合理的目录结构能提升代码可维护性、团队协作效率和后续扩展能力。以下是针对运维数据移交接口设计的标准目录结构：

ops-data-api/
├── app/                          # 应用主目录
│   ├── __init__.py
│   ├── main.py                   # FastAPI 应用入口
│   ├── config.py                 # 全局配置（数据库、日志等）
│   ├── database.py               # 数据库连接与会话管理
│   ├── models/                   # SQLAlchemy 数据模型
│   │   ├── __init__.py
│   │   ├── device.py             # 设备模型
│   │   ├── document.py           # 文档模型
│   │   └── relation.py           # 关联关系模型
│   ├── schemas/                  # Pydantic 请求/响应模型
│   │   ├── __init__.py
│   │   ├── device.py
│   │   ├── document.py
│   │   └── relation.py
│   ├── api/                      # API 路由层
│   │   ├── __init__.py
│   │   ├── v1/                   # API 版本 v1
│   │   │   ├── __init__.py
│   │   │   ├── devices.py        # 设备相关接口
│   │   │   ├── documents.py      # 文档相关接口
│   │   │   └── relations.py      # 关联关系接口
│   │   └── deps.py               # 依赖注入（认证、数据库会话）
│   ├── services/                 # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── device_service.py
│   │   ├── document_service.py
│   │   └── relation_service.py
│   └── utils/                    # 工具函数
│       ├── __init__.py
│       ├── logger.py             # 日志配置
│       └── exceptions.py         # 自定义异常
├── tests/                        # 单元测试与集成测试
│   ├── __init__.py
│   ├── test_devices.py
│   ├── test_documents.py
│   └── test_relations.py
├── migrations/                   # Alembic 数据库迁移脚本
│   ├── versions/
│   ├── env.py
│   └── alembic.ini
├── logs/                         # 运行时日志输出目录
├── .env                          # 环境变量（不提交到版本控制）
├── .gitignore
├── requirements.txt              # 项目依赖清单
└── README.md                     # 项目说明文档

2.3.1 目录结构设计原则

2.4 环境搭建与目录结构总览

下图展示了从虚拟环境创建到项目目录落地的完整流程，以及各组件之间的依赖关系：

2.5 验证环境：启动 Hello World 接口

在 app/main.py 中编写最小化 FastAPI 应用，验证环境搭建是否成功：

# app/main.py
from fastapi import FastAPI

app = FastAPI(title="运维数据移交接口", version="0.1.0")

@app.get("/")
def root():
    return {"message": "运维数据移交接口服务已启动"}

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

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

# 访问验证
# curl http://localhost:8000/
# 预期输出：{"message":"运维数据移交接口服务已启动"}

# curl http://localhost:8000/health
# 预期输出：{"status":"ok","service":"ops-data-api"}

# 交互式 API 文档
# 浏览器访问 http://localhost:8000/docs

2.6 环境搭建清单