标准Python项目结构指南：模块划分与依赖管理

一、标准项目物理骨架：为什么首选 src 布局？

在 Python 社区的演进历程中，工程目录经历过从早期直接平铺在根目录的“扁平布局”（Flat Layout）到现代标准化“源码布局”（Src Layout）的转变。一个符合当前行业最佳实践的标准项目文件树如下：

my_project/
├── .gitignore               # 版本控制忽略配置
├── pyproject.toml           # 项目统一配置元数据（PEP 621）
├── README.md                # 项目文档与使用说明
├── LICENSE                  # 开源协议文件
├── src/                     # 源码物理隔离目录
│   └── my_pkg/              # 业务核心顶级包
│       ├── __init__.py      # 包初始化与公开 API 声明
│       ├── py.typed         # PEP 561 类型提示标记
│       ├── core/            # 核心领域模型与算法
│       │   ├── __init__.py
│       │   ├── models.py
│       │   └── engine.py
│       ├── services/        # 业务编排与用例服务
│       │   ├── __init__.py
│       │   └── processor.py
│       ├── adapters/        # 外部交互与 I/O 适配器
│       │   ├── __init__.py
│       │   └── client.py
│       └── cli.py           # 命令行工具与可执行入口
├── tests/                   # 独立测试用例目录
│   ├── conftest.py          # 测试固件与通用桩代码
│   ├── test_models.py
│   └── test_processor.py
└── docs/                    # 项目技术说明与架构文档

扁平布局与源码布局的核心机制差异

许多初学者倾向于直接在项目根目录下放置 my_pkg/（扁平布局），认为这比额外嵌套一层 src/ 更为精简。然而，两者在执行测试和打包验证时存在根本性的机制差异。

在一致的验证条件下（即在项目根目录下通过终端执行 pytest 或 python -m unittest）：

• 扁平布局机制与隐患：Python 解释器在启动时，默认会将当前工作目录（CWD，即 my_project/）自动压入 sys.path[0]。这意味着测试用例能够直接从当前源码目录中 import my_pkg，即便你从未配置打包文件，或者在打包元数据中遗漏了关键的子模块或数据文件。本地测试全部通过，但生成 Wheel 包发布到生产服务器或者他人机器上运行时，却会突发 ModuleNotFoundError。这种“本地能跑、部署崩溃”的假阳性现象，根源就在于当前目录对导入路径的隐式污染。
• 源码布局机制与优势：采用 src/ 目录后，由于项目根目录下不存在名为 my_pkg 的物理文件夹，测试框架在当前工作目录找不到该模块。开发者必须运行 pip install -e .（可编辑安装），在虚拟环境的 site-packages 中显式生成指向 src/my_pkg 的映射链接。这一步骤强制触发了构建系统的元数据解析，使得本地测试执行的代码与打包发布的成品完全对齐，从源头上杜绝了打包缺失。

二、包内部模块划分：职责分层与引用拓扑

合理的物理布局搭建完毕后，包内部（src/my_pkg/）的代码如何组织是维持项目可维护性的关键。Python 模块划分应遵循关注点分离（SoC）与单向依赖原则。

推荐的分层职责体系

无论工程是数据处理流水线、后台 Web 服务还是终端 CLI 工具，都可以划分为以下四层清晰的职责单元：

1. 领域核心层（core/）：存放业务领域实体、纯计算逻辑、不可变数据结构与自定义异常（如 models.py, exceptions.py）。该层应该保持高度纯粹，不导入任何与网络、数据库或本地文件系统相关的第三方库，只依赖 Python 标准库和基础类型库。
2. 应用服务层（services/）：实现具体的用例编排与业务状态机流转。服务层负责调用核心算法，并将外部数据适配器串联成完整的处理管线，但不直接实现底层协议细节。
3. 基础设施与适配层（adapters/）：封装所有与外界 I/O 交互的具体实现，包括数据库客户端、第三方 HTTP API 包装类、消息队列驱动或本地磁盘读写。适配层负责把外界异构数据转换成核心层的标准实体。
4. 入口装配层（cli.py / main.py）：负责接收用户输入、解析命令行参数（如通过 argparse 或 click）、读取环境变量与配置文件，并将具体的适配器实例注入到服务层中启动执行。

消除循环依赖的三大工程准则

初学者在多模块项目中常遇到 ImportError: cannot import name ... from partially initialized module 报错，其本质原因在于模块间形成了网状的循环交叉导入。要彻底解决此问题，需严格执行以下准则：

• 坚持显式绝对导入：在包内跨子目录引用时，统一使用完整包名作为前缀，例如 from my_pkg.core.models import TaskItem。禁止在深层目录使用 from ...core import models 这类层级不明确的模糊相对导入。显式绝对导入在文件重构移动时具有极佳的静态检查提示能力。
• 单向依赖与依赖倒置：依赖关系只能“由外向内”流动——cli 依赖 services，services 依赖 core 与 adapters，而 core 绝对不能反向依赖 services。若底层核心逻辑需要触发某种外部行为，应在 core 中定义抽象基类（typing.Protocol 或 abc.ABC），由外部适配层去实现，最后在顶层入口处进行组装注入。
• 严禁在模块顶级作用域执行副作用：Python 模块在首次被 import 时会自上而下执行模块内的所有顶级语句。禁止在模块顶级作用域编写数据库连接、文件写入或远程网络请求代码。顶级作用域只应进行类定义、函数定义与类型声明，将一切执行逻辑封装在可调用函数或初始化方法中，确保模块导入在毫秒级内无副作用完成。
• 通过 __all__ 显式收拢公共 API：在 src/my_pkg/__init__.py 中，通过 __all__ = ["Engine", "TaskItem"] 明确规定包对外公开的类和函数。未声明的内部辅助模块对外隐藏，既防范了调用方误用内部私有逻辑，也给后续内部模块重构留出了充裕自由。

三、从零构建规范项目：四步操作与验证流程

明确了布局与分层原则后，本节以一个具体的范例项目 demo_pipeline 为例，完整展示从空文件夹到具备可编辑安装能力的四步初始化流程。

第一步：创建标准物理骨架

在终端中选定工作目录，执行以下命令创建顶层结构与初始文件：

# 1. 建立目录骨架
mkdir -p demo_pipeline/src/demo_pipeline/core
mkdir -p demo_pipeline/src/demo_pipeline/services
mkdir -p demo_pipeline/src/demo_pipeline/adapters
mkdir -p demo_pipeline/tests demo_pipeline/docs
cd demo_pipeline

# 2. 创建包标识文件与初始模块
touch src/demo_pipeline/__init__.py
touch src/demo_pipeline/py.typed
touch src/demo_pipeline/core/__init__.py src/demo_pipeline/core/models.py
touch src/demo_pipeline/services/__init__.py src/demo_pipeline/services/processor.py
touch src/demo_pipeline/adapters/__init__.py src/demo_pipeline/adapters/client.py
touch src/demo_pipeline/cli.py
touch tests/__init__.py tests/conftest.py tests/test_processor.py
touch README.md .gitignore

在 .gitignore 文件中填入 Python 开发的标准忽略规则，避免环境垃圾文件污染代码仓库：

# 虚拟环境
.venv/
venv/
env/

# Python 字节码与缓存
__pycache__/
*.py[cod]
*$py.class

# 打包构建产物
build/
dist/
*.egg-info/
.eggs/

# 测试与类型检查缓存
.pytest_cache/
.mypy_cache/
.ruff_cache/
.coverage
htmlcov/

第二步：编写统一项目配置 pyproject.toml

根据 PEP 517、PEP 518 和 PEP 621 标准，pyproject.toml 现已成为 Python 工程声明构建系统和元数据的统一中枢，彻底取代过时的 setup.py 与 setup.cfg。

在项目根目录下创建 pyproject.toml，这里推荐采用轻量高效且符合标准的现代构建后端 hatchling（亦可选用 flit-core 或 setuptools>=61.0）：

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "demo-pipeline"
version = "0.1.0"
description = "标准Python结构示例数据处理管线"
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
authors = [
  { name = "Dev Team", email = "dev@example.com" }
]
# 运行时直接抽象依赖（宽松语义范围）
dependencies = [
  "httpx>=0.25.0,<1.0.0",
  "pydantic>=2.5.0,<3.0.0",
]

[project.optional-dependencies]
# 开发、测试与代码质量工具依赖
dev = [
  "pytest>=8.0.0",
  "pytest-cov>=5.0.0",
  "ruff>=0.4.0",
  "mypy>=1.10.0",
]

[project.scripts]
# 注册全局命令行可执行命令
demo-cli = "demo_pipeline.cli:main"

[tool.hatch.build.targets.wheel]
packages = ["src/demo_pipeline"]

[tool.ruff]
line-length = 88
src = ["src", "tests"]

[tool.mypy]
python_version = "3.10"
strict = true

第三步：创建并激活独立虚拟环境

在项目根目录下通过 Python 内置的 venv 模块创建完全隔离的开发环境：

# 创建本地虚拟环境目录 .venv
python3 -m venv .venv

# 激活虚拟环境 (macOS/Linux)
source .venv/bin/activate

# 若在 Windows 系统下执行：
# .venv\Scriptsctivate

此时终端提示符前端会出现 (.venv) 标识，代表所有包操作均已锁定在本地目录中，不再与全局系统 Python 混杂。

第四步：以可编辑模式安装并验证导入

在激活的虚拟环境中，执行带 -e 参数的 pip 安装命令。该命令会解析 pyproject.toml，自动下载运行时依赖，并在 .venv 的 site-packages 中植入直接链接到 src/demo_pipeline 的映射：

# 以可编辑模式安装当前项目以及开发依赖项
pip install -e ".[dev]"

# 在根目录下通过命令行直接测试导入包路径
python -c "import demo_pipeline; print('模块物理定位:', demo_pipeline.__file__)"

验证成效： 通过 python -c 打印出的模块路径明确指向 src/demo_pipeline/__init__.py，这证明 Python 成功通过虚拟环境的包寻址机制找到了源码。此时你修改 src/ 下的任何代码均会实时生效，无须重复安装。

四、现代依赖管理：抽象声明与具体锁定的双轨协同

在长期项目维护中，“在我机器上能运行，在别人机器上版本冲突”往往是由于对依赖概念的混淆造成的。现代 Python 工程规范将依赖划分为抽象依赖（Abstract Dependencies）与具体锁定（Concrete Dependencies）两个正交的维度。

传统 requirements.txt 的缺陷对比

传统工作流往往通过 pip freeze > requirements.txt 记录环境。这种做法存在显著弊端：

工程落地实践：使用现代工具实现确定性锁定

目前行业主流推崇使用 uv（高性能 Rust 构建的包管理工具）或 pip-tools 来配合 pyproject.toml 生成确定性锁。

以 uv 为例，在项目根目录下声明完 pyproject.toml 后，仅需一行命令即可完成整树依赖解析与锁文件生成：

# 1. 根据 pyproject.toml 求解依赖树，生成精确跨平台锁定文件 uv.lock
uv lock

# 2. 根据锁文件将本地虚拟环境精确同步至目标状态（自动清理无关包）
uv sync --extra dev

五、常见陷阱排查与落地核对清单

在按照规范组织项目结构的过程中，开发者可能会遇到一些特定的边界情况与报错，以下是典型排查指引：

1. 误将 src 本身当作模块导入

典型现象：出现 ModuleNotFoundError: No module named 'src' 或写出了 from src.demo_pipeline import ...。

排查与修复：src 只是存放源码的物理隔离容器目录，它不是一个 Python 包，内部绝不应该放置 __init__.py。所有模块导入的前缀必须是 demo_pipeline 本身。检查代码中的所有导入语句，将 src.demo_pipeline 统一修正为 demo_pipeline，并确认已在虚拟环境中运行 pip install -e .。

2. 顶层导入导致测试执行过慢或夹带网络副作用

典型现象：运行 pytest --collect-only 仅扫描测试用例时就耗费数秒，甚至尝试连接远程外部服务。

排查与修复：检查各个模块的全局顶级区域，排查是否有 client = DatabaseClient() 或 response = httpx.get(...)。此类语句会在测试框架导入测试文件时强行触发执行。必须将网络连接和实例构造转移至类的 __init__、工厂函数或依赖注入容器中，确保模块被静态加载时只注册符号，不执行任何外部 I/O。

交付自查清单

• 目录结构：已采用 src/ 布局，测试代码置于根目录 tests/，无遗留平铺混杂文件。
• 元数据统一：根目录配置 pyproject.toml，指定构建后端（PEP 517/621），废弃无头 setup.py。
• 模块引用：全局使用显式绝对导入，上层调用下层，底层领域核心零外部网络/数据库依赖。
• 依赖双轨：在 pyproject.toml 中声明直接依赖的语义范围，通过锁文件锁定生产确定性环境。
• 本地验证：在激活的 .venv 中执行 pip install -e .，并通过 pytest 验证所有测试。