3. API 开发环境搭建与项目初始化

在开始编写信用评分特征服务 API 之前，必须建立一套隔离、可复现的开发环境。本章将引导你完成从 Python 虚拟环境配置到 FastAPI 项目骨架搭建的全过程，确保后续开发不污染系统级 Python，且团队成员能通过依赖文件快速同步环境。

3.1 Python 虚拟环境配置

虚拟环境为每个项目创建独立的 Python 解释器与包安装目录，避免不同项目间的依赖版本冲突。推荐使用 Python 3.10+ 内置的 venv 模块，无需额外安装。

3.1.1 创建与激活虚拟环境

# 在项目根目录下执行
python -m venv venv

# Windows (CMD/PowerShell)
venv\Scripts\activate

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

激活后，终端提示符前会出现 (venv) 标识，表示当前已进入隔离环境。

3.1.2 验证环境隔离

# 查看当前 Python 解释器路径
which python   # macOS/Linux
where python   # Windows

# 预期输出应指向项目目录下的 venv 文件夹

3.2 FastAPI 框架安装

FastAPI 是一个现代、高性能的 Python Web 框架，专为构建 API 而生。它基于 Starlette（网络层）和 Pydantic（数据校验层），天然支持异步、自动生成 OpenAPI 文档。

3.2.1 安装核心库

确保虚拟环境已激活，执行以下命令安装 FastAPI 及其生产级 ASGI 服务器 Uvicorn：

pip install fastapi uvicorn[standard]

安装完成后，可通过 pip list 验证关键依赖版本：

3.2.2 验证安装

python -c "import fastapi; print(fastapi.__version__)"

若正常输出版本号，则安装成功。

3.3 项目目录结构设计

良好的目录结构是 API 可维护性的基石。针对信用评分特征服务，推荐采用分层架构，将路由、业务逻辑、数据模型、配置与工具类清晰分离。

3.3.1 标准目录树

credit_score_api/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 应用入口
│   ├── config.py               # 配置管理（环境变量、数据库连接等）
│   ├── api/
│   │   ├── __init__.py
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── router.py       # 主路由聚合
│   │       └── endpoints/
│   │           ├── __init__.py
│   │           └── features.py # 特征服务接口
│   ├── models/
│   │   ├── __init__.py
│   │   ├── request.py          # 请求体 Pydantic 模型
│   │   └── response.py         # 响应体 Pydantic 模型
│   ├── services/
│   │   ├── __init__.py
│   │   └── feature_engine.py   # 特征计算核心逻辑
│   └── utils/
│       ├── __init__.py
│       └── logger.py           # 日志工具
├── tests/
│   ├── __init__.py
│   ├── conftest.py             # pytest 共享夹具
│   └── test_features.py        # 特征接口测试
├── venv/                       # 虚拟环境（已加入 .gitignore）
├── .gitignore
├── requirements.txt            # 生产依赖
└── README.md

3.3.2 各模块职责说明

3.4 依赖管理（requirements.txt）

requirements.txt 是 Python 项目最通用的依赖锁定文件，确保所有开发者和部署环境安装完全一致的包版本。

3.4.1 生成依赖文件

在虚拟环境激活状态下，安装完所有必要包后执行：

pip freeze > requirements.txt

生成的 requirements.txt 内容示例：

annotated-types==0.6.0
anyio==4.2.0
click==8.1.7
fastapi==0.108.0
h11==0.14.0
idna==3.6
pydantic==2.5.3
pydantic_core==2.14.6
sniffio==1.3.0
starlette==0.32.0
typing_extensions==4.9.0
uvicorn==0.25.0

3.4.2 从依赖文件恢复环境

新成员克隆项目后，只需两步即可复现环境：

python -m venv venv
source venv/bin/activate   # Windows 使用 venv\Scripts\activate
pip install -r requirements.txt

3.5 环境搭建流程总览

下图展示了从创建项目目录到成功启动开发服务器的完整步骤与组件关系：

3.6 快速启动验证

完成上述步骤后，在项目根目录创建 app/main.py 并写入最小化应用：

from fastapi import FastAPI

app = FastAPI(title="信用评分特征服务 API", version="0.1.0")

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

启动开发服务器：

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

访问 http://localhost:8000/health 应返回 JSON 响应 {"status":"ok","service":"credit-score-feature-api"}，同时 http://localhost:8000/docs 可查看自动生成的 Swagger 文档。