7.8 KiB
7.8 KiB
title, description, date, img, navigation
| title | description | date | img | navigation | ||
|---|---|---|---|---|---|---|
| Python 代码规范 | 这是一份提供给AI大模型的Python代码规范与编程标准，可以有效提高Cursor等大模型对Python项目的编写能力。 | 2025-07-12 | https://lijue-me.oss-cn-chengdu.aliyuncs.com/20250624130616733.png |
|
概述
这是一份提供给AI大模型的Python代码规范与编程标准，可以有效提高Cursor等大模型对Python项目的编写能力。
description: Python开发综合指南，涵盖代码组织、性能、安全性、测试等内容。这些规则旨在促进可维护、高效且安全的Python代码库。 globs: *.py
Python最佳实践与编码规范
本文档概述了Python开发的综合最佳实践和编码标准，旨在促进编写干净、高效、可维护和安全的代码。
1. 代码组织与结构
1.1 目录结构最佳实践
-
扁平结构优于嵌套（但不绝对）。 从简单结构开始，按需重构
-
包与模块： 使用包（包含
__init__.py的目录）对模块进行逻辑分组 -
src布局： 考虑使用
src目录分离应用代码和项目级文件（setup.py、requirements.txt等），避免导入冲突并明确项目边界 -
典型项目结构：
project_name/ ├── src/ │ ├── package_name/ │ │ ├── init.py │ │ ├── module1.py │ │ ├── module2.py │ ├── main.py # 入口文件 ├── tests/ │ ├── init.py │ ├── test_module1.py │ ├── test_module2.py ├── docs/ │ ├── conf.py │ ├── index.rst ├── .gitignore ├── pyproject.toml 或 setup.py ├── README.md ├── requirements.txt 或 requirements-dev.txt
1.2 文件命名规范
- 模块： 小写字母，使用下划线增强可读性（如
my_module.py） - 包： 全小写（如
my_package），非必要不使用下划线 - 测试文件： 以
test_开头（如test_my_module.py）
1.3 模块组织最佳实践
- 单一职责原则： 每个模块应有明确定义的用途
- 导入规范：
- 顺序：标准库→第三方库→本地模块
- 优先使用绝对导入（如
from my_package.module1 import function1） - 在复杂包结构中需明确相对导入时使用显式相对导入（
from . import sibling_module）
- 常量： 使用全大写定义模块级常量（如
MAX_ITERATIONS = 100） - 双下划线名称：
__all__、__version__等应放在模块文档字符串之后、所有导入之前（from __future__除外）。使用__all__显式声明公共API
1.4 组件架构建议
- 分层架构： 适用于大型应用，将关注点分离为表现层、业务逻辑层和数据访问层
- 微服务： 超大型系统可拆分为小型独立服务
- 六边形/整洁架构： 强调业务逻辑与数据库/框架等外部依赖的解耦
- 依赖注入： 提高可测试性并降低耦合度
1.5 代码分割策略
- 按功能拆分： 基于不同功能划分模块（如用户管理、数据处理）
- 按层级拆分： 分离表现层、业务逻辑层和数据访问代码
- 懒加载： 使用
importlib.import_module()实现按需加载，优化启动时间 - 条件导入： 根据特定条件导入模块
2. 常见模式与反模式
2.1 设计模式
- 单例模式： 限制类只能实例化一个对象
- 工厂模式： 创建对象时无需指定具体类
- 观察者模式： 建立对象间一对多依赖关系
- 策略模式： 定义算法族并使其可互换
- 装饰器模式： 动态扩展对象功能
- 上下文管理器： 确保资源正确清理（如自动关闭文件）
2.2 常见任务的推荐方案
- 数据验证： 使用
pydantic或marshmallow等库 - 配置管理： 使用
python-decouple、dynaconf或标准库的configparser - 日志记录： 使用
logging模块实现结构化日志 - 命令行接口： 使用
argparse、click或typer - 异步编程： 使用
asyncio处理I/O密集型任务
2.3 反模式与代码异味
- 上帝类： 承担过多职责的类，应拆分为专注单一功能的小类
- 霰弹式变更： 需在多处做小修改，表明内聚性不足
- 面条代码： 结构混乱难以追踪，应重构为定义明确的函数/类
- 重复代码： 提取公共代码为可复用函数/类（遵循DRY原则）
- 魔法数值/字符串： 使用命名常量替代硬编码值
- 过早优化： 避免在没有性能瓶颈分析前提下的优化
2.4 状态管理最佳实践
- 无状态函数： 尽可能使用无状态函数
- 不可变数据： 使用不可变数据结构防止意外修改
- 显式状态： 使用类或数据结构明确管理状态，避免全局变量
- 上下文变量： Python 3.7+可使用
contextvars管理异步应用中的请求级状态
2.5 错误处理模式
- 捕获特定异常： 避免笼统捕获
Exception或BaseException - 资源清理： 使用
finally确保清理代码必执行 - 异常日志： 记录完整堆栈信息
- 异常消息： 抛出包含明确错误信息的异常
- 避免异常控制流： 异常应用于处理意外情况而非常规流程
3. 性能优化
3.1 优化技术
- 性能分析： 使用
cProfile定位瓶颈 - 高效数据结构： 根据场景选择（如
set用于成员测试、dict用于查找） - 列表推导式与生成器： 编写简洁高效的代码
- NumPy向量化： 对数值计算使用向量化操作
- 即时编译： 性能关键代码考虑使用Numba等JIT编译器
- 字符串拼接： 使用
''.join(iterable)高效拼接字符串
3.2 内存管理
- 内存分析： 使用
memory_profiler定位内存泄漏 __slots__： 减少类实例的内存占用- 生成器： 处理大数据集时避免全部加载到内存
4. 安全性最佳实践
4.1 常见漏洞防范
- SQL注入： 使用参数化查询或ORM
- XSS攻击： 对用户输入消毒并转义输出
- CSRF防护： 使用CSRF令牌
- 依赖漏洞： 定期审计和更新依赖项
- 硬编码密钥： 禁止在代码中硬编码密码/API密钥，使用环境变量管理
4.2 API安全通信
- 强制HTTPS： 所有API通信必须加密
- 速率限制： 防止接口滥用
- 输入验证： 处理前验证所有API请求
5. 测试策略
5.1 单元测试要点
- 测试粒度： 隔离测试单个函数/类/模块
- 边界条件： 特别测试边界情况和异常场景
- 测试覆盖率： 追求高覆盖率但避免教条化
5.2 集成测试建议
- 聚焦关键流程： 关注核心用户场景
- 模拟外部服务： 使用mock替代真实外部依赖
6. 常见陷阱
6.1 高频错误
- 可变默认参数： 函数定义中避免使用可变对象作为默认值
- 变量作用域： 注意嵌套函数中的变量作用域
- 忽略异常： 禁止直接忽略未处理的异常
- 虚拟环境： 必须使用虚拟环境管理项目依赖
7. 工具与环境
7.1 推荐工具链
- IDE： PyCharm、VS Code（搭配Python插件）
- 包管理：
pip、poetry - 格式化：
black、autopep8 - 静态检查：
mypy、pylint
7.2 CI/CD集成
- 自动化测试： 每次提交自动运行测试套件
- 代码质量门禁： 集成静态分析工具到流水线
遵循这些规范和最佳实践，开发者能够构建出更健壮、可维护且安全的Python应用。