Python 最佳实践

解决什么问题

Python 项目在快速迭代中容易积累技术债务：类型标注时有时无，数据模型选型混乱（内部结构与外部输入共用同一套模型），异步代码混入阻塞调用导致性能瓶颈，项目结构不规范引发导入错误，虚拟环境缺失或依赖未锁定导致环境不一致，测试用例缺乏共享夹具和参数化能力，错误处理使用裸 except: 导致问题定位困难。

核心能力与关键步骤

• 类型标注规范化：要求所有函数签名必须添加类型标注，推荐在 CI 中集成 mypy --strict 或 pyright，type: ignore 注释需附带具体理由。
• 数据模型分层：内部数据结构使用 @dataclass(frozen=True, slots=True) 实现不可变值对象和内存优化；API 边界、配置文件解析等外部输入场景强制使用 Pydantic 进行验证。
• 异步模式统一：HTTP 请求替换为 httpx，并发任务通过 asyncio.gather 实现，限流使用 asyncio.Semaphore，遗留阻塞代码通过 asyncio.to_thread 转换，资源管理采用 async with 语法。
• 项目结构标准化：采用 src 布局避免根目录导入污染，所有工具配置集中到 pyproject.toml，用 Ruff 替代 flake8/isort/black 三件套。
• 环境隔离与依赖锁定：强制使用虚拟环境，依赖版本通过 uv.lock 或 pip freeze 生成的锁定文件精确控制。
• 测试工程化：共享夹具通过 conftest.py 管理，测试参数化使用 pytest.mark.parametrize，文件系统测试使用 tmp_path 临时目录。

适用边界与注意点

本技能适用于需要长期维护的中大型 Python 项目，尤其是涉及异步IO、多团队协作或需要严格类型检查的场景。不适合教学示例代码或一次性脚本。部分规范（如强制使用 Ruff）需要团队达成共识后推行，避免因工具链变更影响现有流程。