Python01-生产级项目搭建指南

一、目标与范围建立一致的工程结构降低协作成本。分离开发、测试、生产环境保证可重现构建。集成静态检查、自动化测试、日志、配置管理等生产必备能力。提供清晰的启动方式与部署路径。二、 环境准备工具版本/说明Python3.14推荐使用pyenv管理版本VS Code最新稳定版扩展Pythonms-python.python、Pylance、Black Formatter、Ruff、isort、Even Better TOML系统Linux / macOS / WindowsWSL2 建议安装 Python 3.14 后确保python3.14 -m pip可用。如使用pyenvpyenvinstall3.14.0 pyenvlocal3.14.0三、标准工程目录结构my_project/ ├── .vscode/ # VS Code 工作区配置 │ ├── settings.json # 编辑器格式化、静态检查设置 │ └── launch.json # 调试启动配置 ├── src/ # 主源码包推荐使用 src 布局 │ └── my_project/ # 实际包名下划线命名 │ ├── __init__.py │ ├── __main__.py # 允许通过 python -m my_project 运行 │ ├── core/ # 核心业务逻辑 │ │ ├── __init__.py │ │ └── engine.py │ ├── utils/ # 工具函数 │ │ ├── __init__.py │ │ └── helpers.py │ └── config/ # 配置加载 │ ├── __init__.py │ └── settings.py ├── tests/ # 测试代码 │ ├── __init__.py │ ├── conftest.py # pytest 共享夹具 │ ├── test_core.py │ └── test_utils.py ├── scripts/ # 辅助脚本数据迁移、种子数据等 │ └── seed_db.py ├── docs/ # 文档可选 │ └── usage.md ├── .env # 本地环境变量不提交 ├── .env.example # 环境变量模板提交 ├── .gitignore ├── pyproject.toml # 项目元数据、依赖、工具配置 ├── README.md ├── Makefile # 常用任务快捷命令可选但推荐 └── Dockerfile # 容器化部署可选为什么使用src布局避免直接导入未安装的包强制在开发时通过pip install -e .安装更贴近生产环境行为减少导入路径错误。四、 必要文件及其用途详解pyproject.toml核心现代 Python 项目的统一配置文件定义项目元数据、依赖、构建系统和各类工具配置。[build-system] requires [setuptools68.0, wheel] build-backend setuptools.build_meta [project] name my_project version 0.1.0 description A production-grade Python project template requires-python 3.14 dependencies [ pydantic2.0, # 配置模型与数据校验 python-dotenv1.0, # 加载 .env 文件 loguru0.7, # 优秀日志库替代标准 logging ] optional-dependencies { dev: [ pytest8.0, pytest-cov, ruff, black, mypy, pre-commit, ], prod: [] # 生产额外依赖如 gunicorn } [project.scripts] my-cli my_project.cli:main # 安装后可生成命令行入口 [tool.setuptools.packages.find] where [src] [tool.black] line-length 100 target-version [py314] [tool.ruff] line-length 100 target-version py314 [tool.ruff.lint] select [E, F, I, N, W, UP] [tool.mypy] python_version 3.14 strict true.gitignore__pycache__/ *.py[cod] .venv/ .env *.egg-info/ dist/ build/ .coverage .pytest_cache/ .mypy_cache/.env.exampleAPP_ENVdevelopment LOG_LEVELDEBUG DATABASE_URLsqlite:///./app.dbMakefile常用命令速查.PHONY: install install-dev test lint format clean install: pip install -e . install-dev: pip install -e .[dev] pre-commit install test: pytest -v --covsrc/my_project --cov-reportterm-missing lint: ruff check src tests mypy src format: black src tests ruff check --fix src tests clean: find . -type d -name __pycache__ -exec rm -rf {} rm -rf .pytest_cache .mypy_cache .coveragesrc/my_project/__main__.py允许使用python -m my_project运行适合开发阶段快速验证frommy_project.core.engineimportmainif__name____main__:main()tests/conftest.py共享测试配置和夹具如加载环境变量、提供临时数据库等。五、模块构建方式所有业务代码放在src/my_project/下按功能拆分子包core、services、utils、models、config等。每个子包应有清晰的__init__.py并可用__all__控制暴露接口。使用绝对导入from my_project.utils.helpers import parse_args避免相对导入在测试和脚本中的困扰。配置模块config/settings.py使用 Pydantic BaseSettings 管理从环境变量 /.env加载frompydantic_settingsimportBaseSettingsclassSettings(BaseSettings):app_env:strdevelopmentlog_level:strDEBUGdatabase_url:strsqlite:///./app.dbclassConfig:env_file.envsettingsSettings()日志统一使用 Loguru在入口处配置拦截标准loggingimportsysfromloguruimportlogger logger.remove()logger.add(sys.stderr,levelsettings.log_level)六、 开发模式最佳指南6.1 虚拟环境与依赖管理python3.14-mvenv .venvsource.venv/bin/activate# Linux/macOS# .venv\Scripts\activate # Windowspipinstall-e.[dev]6.2 静态检查与格式化Ruff快速检查与修复替代 flake8、isort、部分 pylint。Black无可商量的代码格式化。Mypy严格类型检查配置strict true。使用pre-commit在提交前自动执行# .pre-commit-config.yamlrepos:-repo:https://github.com/psf/blackrev:24.3.0hooks:-id:black-repo:https://github.com/astral-sh/ruff-pre-commitrev:v0.4.1hooks:-id:ruffargs:[--fix]-repo:https://github.com/pre-commit/mirrors-mypyrev:v1.9.0hooks:-id:mypyadditional_dependencies:[pydantic]6.3 测试驱动框架pytest异步测试可搭配pytest-asyncio。覆盖率pytest-cov门槛建议 ≥80%。测试分类单元测试tests/unit、集成测试tests/integration。Mock 外部依赖数据库、网络调用使用unittest.mock或pytest-mock。6.4 类型注解所有公共函数、方法必须添加完整类型注解。使用typing模块新特性如 Python 3.14 可用的类型别名语法简化提升代码可读性和 IDE 智能提示。6.5 错误处理与日志自定义异常类继承自项目基类异常便于上层捕获。关键路径记录结构化日志Loguru 支持logger.bind(user_id...)。避免在生产输出print全部经日志管道。6.6 配置分离本地开发用.env不入库。生产环境通过环境变量注入配置Docker、systemd 等。配置模型使用 Pydantic可在启动时自动校验。七、启动方式7.1 开发环境直接在终端运行python-mmy_project或通过 VS Codelaunch.json调试{version:0.2.0,configurations:[{name:Python: Module,type:debugpy,request:launch,module:my_project,console:integratedTerminal,env:{APP_ENV:development}}]}7.2 生产环境若为 Web 服务FastAPI/Flask使用gunicornuvicornworkergunicorn-w4-kuvicorn.workers.UvicornWorker my_project.web:app若为命令行工具打包后直接调用my-cli命令。推荐使用进程管理器如supervisord或systemd守护。八、部署最佳指南8.1 打包为 Docker 镜像FROM python:3.14-slim AS builder WORKDIR /app COPY pyproject.toml ./ RUN pip install --no-cache-dir -e . FROM python:3.14-slim WORKDIR /app COPY --frombuilder /usr/local/lib/python3.14/site-packages /usr/local/lib/python3.14/site-packages COPY src/ src/ ENV APP_ENVproduction EXPOSE 8000 CMD [python, -m, my_project]8.2 依赖锁定生产构建应使用pip freeze或pip-compile生成requirements.txt或直接使用 Poetry/PDM 的锁文件。示例pip-compile pyproject.toml-orequirements/prod.txt8.3 持续集成 (CI) 示例 (GitHub Actions)steps:-uses:actions/checkoutv4-uses:actions/setup-pythonv5with:python-version:3.14-run:pip install-e .[dev]-run:ruff check .-run:mypy src-run:pytest--cov8.4 进程守护systemd服务示例/etc/systemd/system/my_project.service[Unit] DescriptionMy Production Python Project Afternetwork.target [Service] Userapp WorkingDirectory/opt/my_project ExecStart/opt/my_project/.venv/bin/python -m my_project Restartalways EnvironmentFile/etc/my_project.env [Install] WantedBymulti-user.target