---
title: Coolify
description: Coolify是什么？
date: 2025-07-14
img: https://lijue-me.oss-cn-chengdu.aliyuncs.com/20250628122847084.png
navigation:
  icon: simple-icons:chai
---
# 概述
    这是一份提供给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应用。