在团队协作开发中，统一的代码规范能够大幅提升代码质量、可维护性和可读性。本文整理了一套 Cursor 项目的开发规则，覆盖了文件结构、函数设计、日志规范、测试要求、Git 提交等方面，确保我们的代码始终保持高质量、可扩展和可维护。

---

一、文件与函数设计

• 文件大小控制：单个文件不得超过 2000 行，超过需按照功能模块进行拆分。
• 函数行数限制：单个函数不超过 80 行，保证逻辑清晰、职责单一。
• 函数职责单一：一个函数只做一件事，避免混合过多逻辑。

这样做的好处是：代码更简洁，逻辑更清晰，后期维护成本更低。

---

二、命名规范与常量管理

• 变量命名：必须采用有意义的英文单词，禁止使用例如 cursor 等无效的单词作为变量名，避免歧义。
• 常量管理：所有可配置项禁止硬编码，必须统一放在 配置文件 或 数据管理层。

这能避免 “魔法数字” 和 “硬编码陷阱”，同时让配置更灵活。

---

三、日志与错误处理

• 日志规范：日志只输出 关键结果 或 错误信息，禁止堆砌无用的调试日志。
• 错误处理：遇到无法处理的异常，必须 抛出 或 返回明确的错误信息，不可悄悄忽略。

好的日志和错误处理能帮助快速定位问题，避免线上故障被掩盖。

---

四、注释与代码格式

• 注释要求：复杂逻辑必须写注释，并保证与代码保持同步。
• 格式化工具：统一使用 Black（Python）或 Prettier（JS/TS）进行代码格式化。

这可以减少无谓的代码风格争论，让团队更专注于业务逻辑。

---

五、配置与资源管理

• 配置文件：所有配置项必须支持 热更新，严禁写死在代码中。
• 资源释放：文件、网络、数据库连接等资源必须显式关闭，或交由上下文管理器管理。

这样可以最大限度地减少资源泄漏问题。

---

六、依赖与敏感信息管理

• 依赖管理：所有外部依赖必须在 requirements.txt（Python）或 package.json（Node.js）中声明。
• 敏感信息：严禁提交密码、Token、密钥等敏感信息，统一使用 .env 文件 管理。

这是保障系统安全的基本要求。

---

七、测试与代码审查

• 单元测试覆盖率：关键模块必须有单元测试，核心逻辑测试覆盖率 ≥ 80%。
• 代码审查：所有新功能必须经过 Code Review 审查后才能合并。

测试与审查是质量保证的最后一道防线。

---

八、Git 提交与版本管理

• 忽略规则：临时文件、日志文件、虚拟环境目录必须写入 .gitignore。

• 提交信息：遵循 Conventional Commits 规范，例如：

  • feat: 新功能
  • fix: Bug 修复
  • docs: 文档修改
  • refactor: 代码重构

• 提交检查：所有提交必须通过 pre-commit 检查（lint + test）。

统一的 Git 提交流程能让版本历史更清晰，利于回溯与持续集成。

---

九、拒绝与改进原则

• 拒绝原则：无法确定或无法解决的问题，必须明确拒绝，并提出合理的改进建议。

这能避免 “糊弄式提交”，让问题在第一时间暴露并获得解决。

---

好的 ✅ 我来给博客补充一个 实际案例，展示 “不符合规则的代码” 和 “符合规则的代码” 的对比，让规范更直观。

---

十、实际案例：从不规范到规范的代码改造

我们以一个 车辆数据处理函数 为例，展示如何将一段不规范的代码改造为符合上述规则的版本。

❌ 不规范的写法

# vehicle.py
import json, time, os

def process(data, cursor):  # 命名不清晰，变量名 cursor 禁止使用
    f = open("vehicle.log", "a")  # 文件路径硬编码，且未显式关闭
    try:
        js = json.loads(data)  # 没有异常处理
        if js["speed"] > 100:  # 魔法数字
            print("Too fast!")  # 使用 print 打日志
        else:
            print("ok")
        f.write(data + "\n")
    except:
        pass  # 异常被直接忽略
    f.close()

问题总结：

1. 文件行数少，但函数混合了 解析、校验、日志 等多种逻辑。
2. 使用了 硬编码路径 "vehicle.log"。
3. 变量名用了 cursor（禁止）。
4. 错误处理被 忽略。
5. 使用 print 打日志，不可控。
6. 文件操作没有用上下文管理器，可能导致资源泄漏。

---

✅ 符合规则的写法

# config.py
LOG_FILE_PATH = "logs/vehicle.log"
MAX_SPEED = 100

# logger_helper.py
import logging

logging.basicConfig(
    filename="logs/system.log",
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s"
)

def log_info(message: str):
    logging.info(message)

def log_error(message: str):
    logging.error(message)

# vehicle_processor.py
import json
from config import LOG_FILE_PATH, MAX_SPEED
from logger_helper import log_info, log_error

def parse_vehicle_data(data: str) -> dict:
    """解析车辆数据"""
    try:
        return json.loads(data)
    except json.JSONDecodeError as e:
        log_error(f"JSON decode error: {e}")
        raise ValueError("Invalid vehicle data format")

def validate_speed(speed: float) -> bool:
    """校验车辆速度是否合理"""
    return speed <= MAX_SPEED

def save_data_to_file(data: str, filepath: str = LOG_FILE_PATH):
    """保存车辆数据到文件"""
    with open(filepath, "a", encoding="utf-8") as f:
        f.write(data + "\n")

def process_vehicle_data(data: str):
    """处理车辆数据：解析 -> 校验 -> 存储"""
    vehicle = parse_vehicle_data(data)

    if not validate_speed(vehicle.get("speed", 0)):
        log_error(f"Vehicle {vehicle.get('id')} speed too high: {vehicle['speed']}")
    else:
        log_info(f"Vehicle {vehicle.get('id')} data valid.")

    save_data_to_file(data)

改进亮点：

• 拆分函数：解析、校验、保存逻辑独立。
• 常量管理：MAX_SPEED 和日志路径都放在 config.py。
• 日志规范：统一使用 logging，输出到文件，方便排查问题。
• 错误处理：JSONDecodeError 被捕获并抛出合理异常。
• 资源释放：使用 with open(...) 确保文件写入后自动关闭。

---

总结

通过这个案例，可以清楚看到从 “杂乱无章” 的代码到 “规范清晰” 的代码的变化：

• 函数更短小精悍
• 配置项更灵活
• 日志与错误处理更可靠
• 代码结构更易读、更易扩展

这套规则不是为了束缚开发，而是为了让团队在 高速迭代 的同时，依然能保持 代码的可读性、可维护性和安全性。

高质量的代码不是单兵作战的结果，而是团队共同遵守规则的产物。

-