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


一、文件与函数设计

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


二、命名规范与常量管理

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


三、日志与错误处理

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


四、注释与代码格式

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


五、配置与资源管理

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


六、依赖与敏感信息管理

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


七、测试与代码审查

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


八、Git 提交与版本管理

统一的 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)

改进亮点:


总结

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

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

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

-


↙↙↙阅读原文可查看相关链接,并与作者交流