Python 工程化开发

区别于写脚本：工程化 = 规范 + 模块化 + 依赖管理 + 可测试 + 可部署 + 可维护，适合后端服务、数据项目、爬虫、AI 项目。
脚本：单文件，随便写；工程：多人协作、长期迭代、线上运行。

一、目录结构（标准工程模板）

my_project/
├── src/                    # 源码目录
│   └── my_project/
│       ├── __init__.py
│       ├── main.py         # 程序入口
│       ├── api/            # 接口模块（FastAPI/Flask）
│       ├── service/        # 业务逻辑层
│       ├── dao/            # 数据访问层，操作数据库
│       ├── common/         # 公共工具：异常、日志、配置、工具函数
│       └── models/         # 数据模型、pydantic、ORM模型
├── tests/                  # 单元测试、集成测试
│   ├── test_api.py
│   └── test_service.py
├── config/                 # 配置文件：dev / test / prod
│   ├── dev.yaml
│   └── prod.yaml
├── .gitignore              # git忽略文件
├── pyproject.toml          # 项目元信息、依赖（现代Python推荐，替代requirements.txt）
├── requirements.txt        # 兼容旧环境
├── README.md               # 项目说明、部署步骤
├── Dockerfile              # 容器部署
└── docker-compose.yml

原则：源码放 src，测试单独目录；配置和代码分离。

二、依赖管理（工程化最基础）

1. pyproject.toml（推荐，现代标准）

搭配工具：poetry / pdm，自动管理虚拟环境、锁定依赖版本。

• poetry：poetry add xxx，生成 poetry.lock（锁定版本，保证所有人环境一致）
• pdm：类似，国内很多公司在用

2. requirements.txt（传统方式）

fastapi==0.110.0
uvicorn==0.29.0
pydantic>=2.0,<3.0

缺点：没有自动锁版本，多人协作容易出现 “本地能跑，线上不行”。

⚠️ 禁止：pip install xxx 之后直接写 pip freeze > requirements.txt，会把全部环境依赖都导出。

三、代码规范 & 静态检查

1. 格式化：black 自动格式化代码
2. 代码风格检查：flake8 / ruff（ruff 速度更快，现在主流）
3. 类型提示：Python 3.5+ 类型注解 typing

from typing import Optional

def add(a: int, b: int) -> int:
    return a + b

配合 mypy 做静态类型检查，提前发现类型错误。

4. 导入规范：isort 自动排序 import

组合：ruff + black + mypy，写入 pre-commit，git 提交前自动校验。

四、分层设计（后端服务常用）

以 FastAPI 服务举例：

1. api 层（路由）：接收请求、参数校验、调用 service，不写业务逻辑
2. service 层（业务）：核心业务逻辑，事务、规则判断
3. dao 层：只负责数据库增删改查，不包含业务
4. models：Pydantic 入参出参模型 + ORM 数据库模型
5. common：全局异常、日志、工具类、常量

优点：解耦，方便单元测试；路由改了不影响数据库代码。

五、配置管理

不要硬编码密码、数据库地址！

• 开发：yaml /toml 配置文件
• 生产：环境变量（.env），容器 / 云平台注入密钥
• 工具：pydantic-settings 读取配置，自动类型校验

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    db_url: str
    redis_host: str

settings = Settings(_env_file=".env")

六、日志（不要 print！）

工程代码禁止大量 print，使用标准库 logging

• 分级：DEBUG / INFO / WARNING / ERROR / CRITICAL
• 输出文件 + 控制台；线上采集日志（ELK / Loki）
• 增加字段：request_id，链路追踪，方便排查问题

七、异常处理

全局统一异常捕获，不要到处写 try-except

• 自定义业务异常类
• 全局异常中间件，统一返回 JSON 格式错误信息
• 区分：业务异常（用户参数错误）、系统异常（数据库挂了）

八、单元测试 & 集成测试

工具：pytest

• 单元测试：测 service 函数，mock 数据库、redis
• 集成测试：启动服务，请求接口
• 覆盖率：pytest-cov，查看代码测试覆盖率

# tests/test_service.py
def test_calc():
    assert 1 + 2 == 3

九、打包与部署

1. 打包：poetry build 生成 wheel 包
2. 容器化：Docker 打包，统一运行环境，解决 “本地能跑线上不行”

FROM python:3.11-slim
WORKDIR /app
COPY pyproject.toml .
RUN pip install .
COPY src ./src
CMD ["python", "-m", "my_project.main"]

3. 进程管理：uvicorn/gunicorn 跑 web 服务；supervisor / systemd 守护进程

十、CI/CD（持续集成）

git 提交触发：

1. 代码格式检查、静态检查
2. 运行单元测试
3. 通过后自动构建镜像、部署到测试环境

工具：Github Actions、Gitlab CI、Jenkins

十一、工程化避坑点

1. ❌ 不要使用相对导入混乱，推荐包导入 from my_project.service import xxx
2. ❌ 不要硬编码配置、密钥
3. ❌ 不要用 print 代替日志
4. ❌ 单文件几千行，所有代码堆在一起
5. ❌ 依赖不锁版本，线上环境不可复现

十二、Python 工程化核心工具清单

• 包管理：poetry /pdm
• 代码质量：ruff、black、mypy、pre-commit
• web 框架：FastAPI（推荐新项目）、Flask
• ORM：SQLAlchemy 2.0
• 配置：pydantic-settings
• 测试：pytest + pytest-mock
• 容器：Docker

一句话总结

Python 工程化，就是把随手写的脚本变成结构清晰、依赖可控、可测试、可部署、多人可协作的项目，核心就是：分层、规范、自动化校验、环境隔离。

本作品采用《CC 协议》，转载必须注明作者和本文链接