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/ 下，区分环境：
立即学习“Python免费学习笔记（深入）”；
-
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__ 显式控制导出符号。
