Python项目规范：结构化工程目录与代码风格
你永远不知道一个没有项目规范的Python仓库能烂到什么程度。一个utils.py塞满5000行函数，全局变量从A到Z排列，import语句像蜘蛛网一样交叉引用，main.py里混着单元测试和数据库连接——这不是段子，是每天都在发生的代码灾难。结构混乱的项目，三个月后连原作者都看不懂自己写的逻辑。不遵循工程规范的Python代码，本质上是在给未来的自己埋定时炸弹。
目录结构：用文件系统讲述项目故事
一个规范的项目目录应该让人一眼就明白业务边界。不要用src套lib套core这种抽象层，除非你打算把项目变成俄罗斯套娃。最可靠的入门模板是Cookiecutter-PyPackage或PyPa推荐的扁平化布局：项目根目录放README.md、pyproject.toml、setup.cfg这类元信息；项目包目录直接以项目名命名，例如mypackage/。包内按功能模块划分子包，比如mypackage/api/、mypackage/models/、mypackage/services/。测试目录tests/与包目录平级，每个测试文件命名要对应被测模块，test_services.py测试services模块。
有些团队喜欢把所有业务逻辑塞进一个app.py，然后衍生出app_v2.py、app_final.py——请立刻停止这种行为。版本控制不是靠文件名后缀实现的，那是Git的职责。规范的目录结构强制开发者思考依赖关系：如果models和services互相导入，说明抽象层次错了。建议在包目录下加一个__init__.py（即使是命名空间包也建议显式写），用来做公共导出。同时，根目录下必须保留docs/、scripts/、requirements/等基础设施目录，但避免出现tmp/、archive/这类容易膨胀的文件夹。
文件命名：从蛇形到一致性的强迫症
Python社区约定俗成用snake_case命名模块和包文件，但总有人坚持用camelCase或middle-case-with-dash。这种不一致导致import语句看起来像在玩拼图游戏——from My-Code_Lib import helperUtil。违反PEP 8命名约定的代码，在代码审查时的第一印象就已经输了。模块名应简短、小写、不含下划线（除非必须区分，如http_client.pyvshttp_server.py）。测试文件命名必须包含test_前缀或_test后缀，让pytest能自动发现。数据文件、配置文件的命名也要遵循项目统一约定，比如config.yamlvsconfig.prod.yaml。
别小看命名对代码可维护性的影响。我曾经见过一个项目里有utils.py、helper.py、common.py、tools.py四个文件，里面内容高度重叠——这种命名等于告诉维护者“别区分了，都扔进来”。每个文件只做一件事，文件名就是它的说明文档。按功能领域拆分：data_loader.py、feature_engineering.py、trainer.py明显比helper_part1.py清晰一百倍。
代码风格：PEP 8是底线，但工具才是护城河
人工对齐缩进、手动删除末尾空格、逐个检查行长是否超过79字符——这些工作在2025年还靠人肉做，属于自虐行为。PEP 8不是可选项，而是Python社区的通用语。但更关键的是，依赖工具强制执行风格检查。用black做自动格式化，它不会问你是否喜欢单引号还是双引号——直接给你定死，消除一切无意义的争论。配合isort自动排序import语句，标准库、第三方库、本地模块用空行隔开，按字母顺序排列。flake8或ruff做静态检查，捕捉未使用的变量、语法错误、复杂度过高的函数。
我见过最糟糕的反例：一个团队花两小时在代码审查里争论if x is not None还是if not x is None。代码审查的时间应该花在逻辑正确性和架构抽象上，而不是格式细节。在pyproject.toml或setup.cfg中配置好[tool.black]、[tool.isort]、[tool.ruff]，然后集成到CI流水线里。但凡PR触发了格式违规，直接阻断合并。这样团队就自动形成肌肉记忆：写代码、保存、black .格式化、提交。风格统一后，阅读代码的认知负荷至少下降30%。
导入与依赖管理：别让你的requirements.txt变成黑洞
人们常常忽略import语句本身也是项目的“架构图”。PEP 8要求顺序：标准库、第三方库、本地模块，每组之间空一行。但更重要的是避免通配导入from module import，这会把命名空间污染成公共厕所——你不知道哪些符号被引入了，也不知道是否覆盖了已有的变量。同样，避免循环导入：模块A导入B，B又导入A，Python在运行时可能会抛出ImportError。解决方法通常是重构公共逻辑到第三个模块，或者使用延迟导入（在函数内部导入）。
依赖管理方面，requirements.txt可以工作，但不够规范。推荐使用pipenv、poetry或PDM，它们能生成锁定文件（Pipfile.lock或poetry.lock），确保开发、测试、生产环境的依赖版本完全一致。没有锁定文件的Python项目，随时可能因依赖升级而崩溃。将依赖分组：requirements/dev.txt包含pytest、black等开发工具；requirements/prod.txt只包含运行时的必要包。或者用pyproject.toml的[project.optional-dependencies]来区分。永远不要在生产环境安装pytest或ipython，这既是安全风险也是性能浪费。
代码组织：函数、类、模块的清晰边界
一个函数超过50行就该考虑拆分了。一个类超过200行说明它可能违反了单一职责原则。一个模块超过800行基本上可以判定为设计失败。这些不是严格限制，但反映了代码组织的健康度。规范的做法是：每个函数只做一件事，并且函数名是动词短语（compute_average,validate_email）。类名用驼峰（UserService,DatabaseConnector），方法名用蛇形。模块内部按“公开API在前，私有辅助在后”的顺序排列，__all__变量明确导出接口。
我还观察到一种坏习惯：把所有业务逻辑写在if __name__ == "__main__"下。这个块应该只用于短脚本或命令行入口，真正的逻辑应该放在函数或类里，方便单元测试。if __name__ == "__main__"不是主函数的替代品，而是模块的“自测开关”。如果要创建命令行工具，使用click或typer库，把入口逻辑单独放在cli.py或main.py中，然后通过setup.py的entry_points注册。
注释与文档：别让未来的人咒骂现在的你
“Write code that documents itself”这句话被误解了。代码本身能表达逻辑，但表达不了“为什么”——为什么选择这种算法？为什么这个边界条件被忽略？为什么这个函数参数顺序如此奇怪？注释应该解释“为什么”，而不是“是什么”。例如，x += 1 # 增加x这种注释毫无价值。好的注释是# 根据业务规则A-007，此处需要忽略0值，避免除零错误。
文档规范上，每个公共模块、类、方法必须包含docstring。推荐使用Google风格或NumPy风格，配合Sphinx或mkdocs自动生成API文档。我曾经接手一个项目，所有函数的参数名都是a,b,c，文档里写“这个函数处理数据”——处理什么数据？怎么处理？全靠猜。没有文档的Python库，本质上是个黑箱。在pyproject.toml中配置[tool.pydocstyle]，强制要求docstring的存在。同时，README.md应该包含项目简介、安装步骤、快速开始示例和贡献指南。docs/目录下放更全面的设计文档、变更日志和架构说明。
测试结构：让测试成为项目的第二层文档
测试代码在项目里常常被当作二等公民，扔在一个扁平的tests/文件夹里，文件名叫test1.py,test2.py。这等于放弃了测试的组织价值。测试目录的结构应该镜像源文件的结构：tests/test_services/test_user_service.py对应mypackage/services/user_service.py。每个测试函数以test_开头，命名清晰表达测试场景，例如test_create_user_returns_id。使用pytest的fixture机制代替setUp/tearDown，利用conftest.py共享跨模块的fixture。
覆盖率不是目标，而是基线。如果一个项目没有测试，任何重构都是在走钢丝。在CI中配置pytest --cov=mypackage --cov-fail-under=80，强制要求测试覆盖率不低于某个阈值。但更重要的是测试的质量：不是每个函数都必须有单元测试，但关键业务逻辑、边界条件、异常处理路径必须覆盖。测试本身也要遵守代码风格规范，不然未来的维护者会忽视测试的存在。
配置与环境：12-Factor App原则在Python中的落地
硬编码数据库连接字符串、API密钥、文件路径是Python项目最常见的反模式。配置应该从环境变量中读取，而不是写在源码里。使用python-dotenv库在本地开发时加载.env文件，但永远不要将.env提交到版本控制。将环境变量分组到settings.py或config.py中，通过os.environ.get读取并赋予默认值。如果配置项较多，考虑用pydantic-settings定义带类型校验的配置模型，还能自动从环境变量映射。
另一个常见问题是在不同环境使用不同的配置：开发用SQLite，生产用PostgreSQL。最好使用统一的配置接口，通过DJANGO_SETTINGS_MODULE或自定义的ENV变量来切换配置模块。项目的可配置性决定了它的可移植性。如果换一台机器就要修改十几个文件，说明你还没有掌握12-Factor App的配置管理精髓。
工具链集成：用自动化消灭人为偏差
手动运行black、isort、pylint、mypy、pytest——如果每个开发者都自己敲命令，总会有人漏掉某个步骤。解决方案是统一的Makefile或Taskfile.yml，定义make format,make lint,make test,make typecheck等目标。在CI里也要执行同样的命令。让工具去约束人，而不是让人去记住工具。例如pre-commit钩子，在每次git commit前自动运行钩子脚本，如果格式检查或类型检查失败则禁止提交。这样能在代码进入仓库前就把大部分低级问题过滤掉。
类型检查是一个被严重低估的规范。Python是动态类型语言，但mypy的静态类型检查可以在开发阶段捕获大量空指针、类型错误、参数不匹配问题。在pyproject.toml中启用--strict模式，强制要求函数签名带类型注解。虽然初期要花时间加注解，但一个带完整类型注解的Python项目，其可维护性不亚于TypeScript项目。
版本控制与开发流程：规范不是写在文档里，而是写在分支里
代码规范最终要通过版本控制来落地。Git的分支策略、PR模板、代码审查清单都影响着项目规范的执行力。例如，在PR模板中包含“是否符合PEP8？”、“是否有类型注解？”、“是否有测试？”、“配置文件是否涉及敏感信息？”这类问题。将规范检查集成到PR的门禁中，比任何培训都有效。使用gitignore排除__pycache__/,.env,.pyc,.mypy_cache/,.egg-info/等自动生成的文件，避免污染仓库。
最后，请记住：规范不是束缚，而是自由。因为有了统一的目录结构，新成员可以立刻知道去哪里找配置；因为有了代码风格工具，没有人再为缩进争吵；因为有了测试结构和类型注解，重构时心里有底。一个规范的Python项目，看起来就像一套搭建好的脚手架——每一根螺栓都在正确的位置，每一个模块都自成体系，整个项目像一台精密的机器一样运转。这，才是专业开发者的尊严。