3. 环境搭建：Python虚拟环境配置、FastAPI框架安装、Postman与curl工具准备、数据库选型（PostgreSQL）

在开始编写接口代码之前，必须搭建一套稳定、可复现的开发环境。本章将指导你完成从Python虚拟环境配置到数据库选型的全流程，确保后续的合同发票匹配与付款风险控制接口能够在隔离、可控的环境中运行。

3.1 Python虚拟环境配置

虚拟环境用于隔离项目依赖，避免不同项目之间的包版本冲突。推荐使用Python内置的venv模块或conda进行管理。

3.1.1 使用venv创建虚拟环境

# 创建项目目录并进入
mkdir contract-payment-api
cd contract-payment-api

# 创建虚拟环境（Windows）
python -m venv venv

# 创建虚拟环境（macOS/Linux）
python3 -m venv venv

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

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

# 验证环境
which python   # macOS/Linux
where python   # Windows
提示：激活后终端提示符前会出现 (venv) 标识，表示当前处于虚拟环境中。后续所有 pip install 操作都会安装到该环境内，不会污染系统全局Python。

3.1.2 使用requirements.txt管理依赖

# 生成当前环境的依赖清单
pip freeze > requirements.txt

# 在新环境中一键安装所有依赖
pip install -r requirements.txt

3.2 FastAPI框架安装

FastAPI是一个现代、高性能的Python Web框架，基于Starlette和Pydantic构建，天然支持异步、自动生成OpenAPI文档，非常适合工程合同API的开发场景。

3.2.1 安装FastAPI与ASGI服务器

# 安装FastAPI核心库
pip install fastapi

# 安装ASGI服务器（推荐uvicorn，性能优异）
pip install uvicorn[standard]

# 安装数据库驱动（后续章节使用）
pip install sqlalchemy psycopg2-binary alembic

3.2.2 验证安装

# 创建最小启动文件 main.py
from fastapi import FastAPI

app = FastAPI(title="合同发票匹配API")

@app.get("/")
def root():
    return {"message": "环境搭建成功，API服务已启动"}

# 启动服务
uvicorn main:app --reload --host 0.0.0.0 --port 8000

启动后访问 http://localhost:8000/docs 即可看到自动生成的Swagger交互式文档页面。

关键配置说明：
  • --reload：开发模式下启用热重载，代码修改后自动重启服务
  • --host 0.0.0.0：允许局域网内其他设备访问（调试时方便Postman连接）
  • --port 8000：默认端口，可根据需要修改

3.3 Postman与curl工具准备

接口调试工具是API开发者的“听诊器”。Postman提供图形化界面，适合复杂请求构造与集合管理；curl是命令行利器，适合脚本化测试与CI/CD集成。

3.3.1 Postman安装与配置

步骤 操作说明
1 访问 Postman官网 下载对应操作系统版本
2 安装后注册/登录（支持免费账号）
3 创建新集合（Collection），命名为 合同发票匹配API
4 添加环境变量：base_url = http://localhost:8000
5 导入课程配套的Postman预置集合文件（.json）

3.3.2 curl常用命令速查

# GET请求
curl -X GET "http://localhost:8000/contracts" -H "accept: application/json"

# POST请求（JSON体）
curl -X POST "http://localhost:8000/invoices/match" \
  -H "Content-Type: application/json" \
  -d '{"contract_id": "CT2024001", "invoice_amount": 150000.00}'

# 带认证的请求
curl -X GET "http://localhost:8000/payments/risk-check" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# 保存响应到文件
curl -o response.json "http://localhost:8000/contracts/export"
注意：Windows系统使用curl时，JSON字符串中的双引号需要转义，建议使用单引号包裹整个JSON（Git Bash或WSL环境），或使用Postman替代。

3.4 数据库选型：PostgreSQL

工程合同数据具有结构化强、关联复杂、事务要求高的特点。PostgreSQL作为企业级关系型数据库，在以下方面与我们的业务场景高度匹配：

特性 PostgreSQL优势 合同场景价值
ACID事务 完全支持，隔离级别可配置 确保合同-发票-付款三表状态一致性
JSON/JSONB 原生支持，可索引 存储合同条款、发票明细等半结构化数据
窗口函数 支持复杂分析查询 累计付款进度、风险评分排名
并发控制 MVCC机制，读写不阻塞 多用户同时录入合同与发票
扩展生态 PostGIS、pg_stat_statements等 地理位置分析、性能监控

3.4.1 安装与初始化

# macOS (Homebrew)
brew install postgresql@16
brew services start postgresql@16

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

# Windows
# 下载安装包：https://www.postgresql.org/download/windows/
# 安装时勾选 pgAdmin 4 和 Stack Builder

3.4.2 创建数据库与用户

# 切换到postgres系统用户
sudo -u postgres psql

# 创建数据库
CREATE DATABASE contract_payment_db;

# 创建专用用户
CREATE USER api_user WITH PASSWORD 'SecurePass123!';

# 授权
GRANT ALL PRIVILEGES ON DATABASE contract_payment_db TO api_user;

# 退出
\q

3.4.3 连接配置（FastAPI侧）

# config/database.py
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "postgresql://api_user:SecurePass123!@localhost:5432/contract_payment_db"

engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()
生产环境建议：使用环境变量或.env文件管理数据库连接字符串，避免硬编码密码。推荐使用 python-dotenv 库加载配置。

3.5 环境架构总览

下图展示了开发环境的整体组件关系与数据流向：

开发环境架构图 开发环境组件架构图 开发者 / IDE FastAPI 服务 uvicorn ASGI 服务器 | 端口 8000 Postman 图形化调试 curl 命令行调试 PostgreSQL 数据库 contract_payment_db | 端口 5432 contracts 合同表 合同编号、金额、状态 invoices 发票表 发票编号、金额、匹配状态 payments 付款表 付款单、风险等级、审批 环境验证要点 ① 虚拟环境激活 ② FastAPI服务启动 ③ Postman/curl连通性测试 ④ 数据库连接成功 开发工具链：Python 3.10+ → FastAPI + uvicorn → PostgreSQL 16 → Postman/curl

3.6 环境验证清单

完成上述步骤后，请逐项确认以下检查点，确保环境就绪：

序号 检查项 验证方法 预期结果
1 虚拟环境激活 终端执行 which python 路径指向项目目录下的 venv/bin/python
2 FastAPI服务 访问 http://localhost:8000/docs 显示Swagger UI页面
3 Postman连通性 发送GET请求到 / 返回 {"message": "环境搭建成功"}
4 curl连通性 执行 curl http://localhost:8000/ 返回JSON响应
5 数据库连接 执行 psql -U api_user -d contract_payment_db -c "\l" 列出数据库列表
6 依赖完整性 执行 pip list | grep -E "fastapi|uvicorn|sqlalchemy|psycopg2" 所有包均显示版本号
常见问题排查：
  • 端口被占用：使用 lsof -i :8000（macOS/Linux）或 netstat -ano | findstr :8000（Windows）查找占用进程，更换端口或终止冲突进程。
  • 数据库认证失败：检查 pg_hba.conf 文件中是否允许密码认证（md5/scram-sha-256），修改后执行 pg_ctl reload。
  • Postman SSL错误：本地开发使用HTTP协议，确保请求URL为 http:// 而非 https://。
← 上一章 📖 返回目录 下一章 →