Python 项目结构如何设计更清晰？

Python项目结构清晰的关键是按业务功能而非技术类型划分模块，如src/payments/、src/reports/；设唯一入口（如src/main.py），配置统一放config/并按环境分离；测试目录tests/镜像src/结构；初期避免过度分层，用目录约束和导入规则保障可维护性。

Python 项目结构清晰的关键是让代码职责分明、易于定位、方便测试和部署，而不是堆文件或盲目套模板。

按功能或领域划分模块，而非技术类型

避免把所有 .py 文件按“models/”“views/”“utils/”这种通用名粗暴分类——尤其在中小型项目中，容易导致逻辑分散、跨目录跳转频繁。更推荐以业务主线或核心能力为单位组织，比如：

• src/payments/：支付相关逻辑（含接口、校验、回调处理）
• src/reports/：报表生成与导出逻辑
• src/shared/：跨模块复用的工具函数、基础配置、自定义异常

这样改动一个功能时，90% 的代码都在同一目录下，不需满项目找依赖。

明确入口与配置边界

项目应有唯一、显眼的启动点（如 src/main.py 或 app.py），不建议把启动逻辑藏在子包里。配置统一放在 config/ 下，区分环境：

• config/base.py：通用配置
• config/dev.py、config/prod.py：覆盖式环境配置
• config/__init__.py 中根据 ENV 环境变量自动加载对应配置

避免硬编码路径、密钥或数据库地址，也别让配置散落在各个模块的 __init__.py 中。

测试与源码分离，但保持就近映射

测试目录（tests/）结构应镜像 src/，便于快速定位对应测试：

• src/payments/gateway.py → tests/payments/test_gateway.py
• src/shared/validation.py → tests/shared/test_validation.py

不用为每个模块建单独的 test_ 子目录，扁平化更易维护。确保 pytest 能直接运行 tests/ 并自动发现用例。

预留扩展层，不提前过度设计

初期不必强加 domain/

、application/、infrastructure/ 分层。等出现明显耦合或替换需求（如换数据库、换消息队列）时，再把数据访问、外部服务调用等抽成独立子包。过早分层反而增加理解成本和 import 链路。

可以先用简单约定：模块内函数优先调用同目录内容；跨目录调用只允许向上（如 payments/ 可用 shared/），禁止循环引用；用 pyproject.toml 中的 [tool.ruff.per-file-ignores] 或 __all__ 显式控制导出符号。