Python最佳实践

Python 项目扩张时，常见痛点会逐渐暴露：函数签名缺少类型注解导致协作时反复猜参数，async 代码里混入阻塞 I/O 引发性能瓶颈，项目结构混乱导致意外从根目录导入，环境依赖未隔离引发版本冲突，测试重复代码多且难以维护。这些散落的问题会持续消耗维护成本，该技能以明确的规则覆盖这些高频场景。

核心能力覆盖

• 类型注解规范：要求始终标注函数签名，使用 3.12+ 语法，CI 中集成 mypy --strict 或 pyright，type: ignore 需附具体理由
• Dataclass 与 Pydantic 的边界：内部领域模型、无需校验的数据用 dataclass（frozen=True 实现不可变值对象，slots=True 优化内存）；API 边界、配置文件、外部输入解析用 Pydantic 做校验
• Async 模式约束：异步 HTTP 用 httpx 替代 requests，并发任务用 asyncio.gather，限流用 asyncio.Semaphore，遗留阻塞 I/O 用 asyncio.to_thread 包装，连接/会话等资源用 async with 管理
• 项目结构：采用 src 布局，避免意外从项目根目录导入
• 虚拟环境与依赖：强制使用虚拟环境，禁止全局安装包，通过 uv.lock 或 pip freeze 生成的 requirements.txt 锁定精确版本
• 测试规范：pytest 用 conftest.py 存放共享 fixture，pytest.mark.parametrize 覆盖测试变体，tmp_path 处理文件系统相关测试
• 错误处理约定：禁用裸 except:，捕获最具体的异常类型，用 logger.exception() 记录 traceback，为应用定义自定义异常层级

适用边界

适合需要团队协作的中大型 Python 项目，依赖 Python 3.12+ 的类型语法支持；极小脚本可按需裁剪规则，无需强制全量遵循。