企业级开发项目中的光标规则解析 – 今日头条

沉默有时也是一种力量，终会闪耀光芒

大家好，我是沉默

Cursor rules（也就是 .cursorrules 文件），其实是给 AI 助手设定了一些“工作习惯”，这样它在帮你写代码或者修改代码的时候，能更符合团队的规范，减少低级错误的发生。

如果团队里新成员比较多，或者项目需要快速推进，统一的工程规范就能大幅降低沟通成本，同时提升交付的一致性。

今天我将复杂的规则整理成“一页速览 + 一些可直接复制的样板代码”，这样新人能很快上手，资深工程师也能迅速审核。

-01-

核心规范

Java（后端）

• 语言：使用 Java 8/17，优先考虑 Stream / Lambda。
• 风格：遵循阿里巴巴的 Java 开发手册。
• 注解：使用 @RestController、@Service、@Mapper 等。
• 异常处理：@ControllerAdvice + @ExceptionHandler 统一返回格式。

{ "code": 200, "message": "success", "data": {}, "timestamp": "2024-01-01T00:00:00Z" }

• Lombok：实体/DTO/VO 使用 @Data，构建器用 @Builder，日志用 @Slf4j，构造推荐 @RequiredArgsConstructor。
• 校验：结合 @Valid 与 Bean Validation（Hibernate Validator）。

Python（脚本 / 工具）

• 遵循 PEP8，并使用类型提示。
• 文件操作建议使用 pathlib，日志用 logging。
• 尽量避免裸 except:；要捕获具体的异常。
• 使用 venv / pipenv / poetry 来管理依赖。

前端（Vue）

• 使用 Vue3 和 TypeScript，优先选择 与 Composition API。
• 组件名称采用 PascalCase，CSS 类名使用 kebab-case。
• 使用 Element Plus，状态管理选 Pinia 或 Vuex。
• 性能方面：要注意懒加载、虚拟列表以及防抖/节流。

数据库 & 缓存

• MySQL 的表和字段命名：小写并用下划线（例如 user_profile、create_time）。
• 主键设置：id bigint auto_increment（或 MyBatis-Plus 的雪花算法）。
• Redis 键的格式：project:module:biz:identifier，TTL 一定要设定。
• 分布式锁推荐使用 Redisson，避免手动编写复杂的逻辑。

AI/ML 特殊点

• 使用异步请求 + 重试 + 降级策略。
• 日志记录：包括模型的输入/输出（需脱敏）、耗时和 token 使用量。
• TTS/音频处理：流式传输、缓存以及格式转换。
• Agent/MCP：需要实现责任链、状态持久化和插件化。

-02-

示例代码

项目结构（Spring Boot）

src/main/java/
├── controller/     # 处理请求的层
├── service/        # 业务逻辑处理
├── mapper/         # MyBatis 数据映射接口
├── entity/         # 实体类定义
├── dto/            # 数据传输对象
├── vo/             # 返回给用户的视图对象
├── config/         # 配置相关的类
├── exception/      # 处理异常的类
└── util/           # 工具类集合

Java 实体类示例

注：代码中的注释使用中文，以符合团队的编码规范。

package com.example.entity;
import com.baomidou.mybatisplus.annotation.*;
import com.fasterxml.jackson.annotation.JsonFormat;
import com.fasterxml.jackson.annotation.JsonIgnore;
import lombok.Data;
import java.time.LocalDateTime;
/**
 * 用户实体类，映射到数据库的 user 表
 */
@Data
@TableName("user")
public class User {
    /**
     * 主键ID，采用 MyBatis-Plus 的雪花算法生成
     */
    @TableId(type = IdType.ASSIGN_ID)
    private Long id;
    /**
     * 用户名，必须是唯一的
     */
    private String username;
    /**
     * 密码，返回时会被忽略
     */
    @JsonIgnore
    private String password;
    /**
     * 用户邮箱
     */
    private String email;
    /**
     * 创建时间，插入时自动填充
     */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
    /**
     * 更新时间，插入或更新时会自动填充
     */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;
    /**
     * 逻辑删除标识：0 表示未删除，1 表示已删除
     */
    @TableLogic
    private Integer deleted;
}

Python 小工具示例（日志 + 路径处理）

"示例：安全读取文件的工具函数"
from pathlib import Path
import logging
from typing import Optional
logger = logging.getLogger(__name__)
def read_text_safe(path: str) -> Optional[str]:
    """
    安全地读取文本文件（防止异常信息泄露）
    :param path: 文件的路径
    :return: 文件内容或 None（读取失败）
    """
    p = Path(path)
    if not p.exists() or not p.is_file():
        logger.warning("文件不存在：%s", path)
        return None
    try:
        return p.read_text(encoding="utf-8")
    except Exception as e:
        logger.exception("读取文件时出错：%s", e)
        return None

代码质量与交付标准

• 单元测试：确保覆盖率超过 80%，关键逻辑要通过集成测试（Testcontainers）来验证。
• 静态代码检查：使用 SonarQube 和 CI（PR 必须通过）。
• PR 模板：每个 PR 必须填写“改动原因 / 影响范围 / 回归风险 / 测试说明”。
• 运行时监控：整合 Prometheus 和 Grafana，关键业务（QPS/延迟/错误率）必须设置告警。

-03-

.cursorrules 文件示例

通用信息

打造高效代码，提升开发体验

rules:
  - name: 基本编码规范
    description: 确保代码风格的一致性和基本习惯
    patterns: ["*.java", "*.js", "*.ts", "*.py"]
    commands:
      - "避免无意义的 import，要按需来"
      - "变量命名用驼峰法，类名用大写驼峰"
      - "方法最好控制在 50 行以内，超长的要拆开"
      - "尽量不要硬编码，提取成常量或者配置文件"
  - name: Java 编码规则
    description: Java 开发的具体要求
    patterns: ["*.java"]
    commands:
      - "尽量用 Optional 替代 null"
      - "如果项目中启用了 Lombok，可以简化 getter/setter"
      - "Service 层不允许写业务逻辑，保持职责单一"
      - "Controller 层不要直接返回实体，统一封装成响应对象"
  - name: 前端 TypeScript/Vue 规范
    description: 前端代码风格统一
    patterns: ["*.ts", "*.tsx"]
    commands:
      - "优先用函数组件代替 class 组件"
      - "统一采用 Vue Hooks"
      - "props 和 state 必须明确类型，避免使用 any"
      - "UI 元素要有语义，别随便用 div"
  - name: 测试驱动开发
    description: 确保生成的代码可以测试
    patterns: ["*.java", "*.py", "*.ts"]
    commands:
      - "新增功能时，必须同时编写单元测试示例"
      - "测试要覆盖边界条件（如异常输入、空数据和大数据量）"
      - "测试方法命名使用 should_xxx_when_xxx 的格式"
  - name: 注释与文档
    description: 生成可读性强的注释
    patterns: ["*.java", "*.py", "*.ts"]
    commands:
      - "所有公共方法必须写 Javadoc/Docstring，解释输入和输出"
      - "复杂逻辑要用行内注释解释原因，而非解释代码本身"
      - "类文件开头要说明用途，避免以后看不懂"
  - name: 提升效率的小窍门
    description: 优化 AI 编码助手的表现
    commands:
      - "生成的代码要能直接编译和运行，别省略依赖"
      - "避免写伪代码，要给出完整实现"
      - "生成配置文件时必须附带示例值"
      - "不确定库使用方式时，给出两种方案并说明优缺点"

（Java 高并发/微服务项目）

rules:
  - name: 基础编码规范
    description: Java 微服务项目的通用规范
    patterns: ["*.java"]
    commands:
      - "每个类都要有明确的包分层：controller, service, repository, domain, config"
      - "Controller 层禁止写业务逻辑，只负责校验请求和转发"
      - "Service 层的方法要尽量简短，超过 100 行的要拆开"
      - "Repository 层禁止拼接 SQL，统一使用 JPA/MyBatis"
  - name: 并发与线程安全
    description: 高并发场景下的编码规范
    patterns: ["*.java"]
    commands:
      - "在多线程环境下不要使用非线程安全的集合（如 HashMap），优先用 ConcurrentHashMap"
      - "多线程共享变量要加 volatile 或使用原子类（AtomicInteger/Long）"
      - "锁的粒度要尽量小，避免在大方法上使用 synchronized"
      - "优先使用线程池 ExecutorService，禁止手动创建线程"
      - "线程池要自定义 ThreadFactory，并设置有意义的线程名称"
      - "定时任务要使用 ScheduledExecutorService 或 Spring Task，禁止用 Timer"
  - name: 微服务与分布式
    description: 微服务架构的开发规范
    patterns: ["*.java", "*.yml"]
    commands:
      - "接口必须保持幂等性，POST/PUT 请求要有唯一请求 ID 以防重处理"
      - "跨服务调用要通过统一的 HTTP/gRPC 客户端，禁止硬编码 URL"
      - "必须实现请求超时、重试和熔断机制（如 Resilience4j/Sentinel）"
      - "分布式事务要有明确的方案（如 Seata/TCC/Saga），不能用本地事务假装全局成功"
      - "消息队列消费者要支持幂等消费，避免重复消息造成数据混乱"
      - "批量处理任务要进行分片或分页，避免一次拉取过多数据"
  - name: 性能与缓存
    description: 高性能服务的关键规范
    patterns: ["*.java"]
    commands:
      - "高频接口要加入缓存（如 Redis/本地 Caffeine），避免数据库压力过大"
      - "缓存更新要选择合适的策略（旁路、双写、异步刷新），代码注释中要说明"
      - "不要在 for 循环中频繁访问远程服务或数据库，应该批量查询"
      - "分页查询要限制 pageSize，默认不超过 1000"
      - "禁止出现 N+1 查询，复杂查询要用 join 或 batch fetch"
  - name: 日志与监控
    description: 服务可观测性的要求
    patterns: ["*.java"]
    commands:
      - "统一使用 Slf4j + Logback，禁止用 System.out.println"
      - "敏感信息（如密码、Token、身份证号）不能打印到日志"
      - "接口必须记录日志，包含 traceId/requestId 以便于链路追踪"
      - "异常日志必须包含堆栈 trace，禁止只打印 e.getMessage()"
      - "必须埋点 metrics（如 QPS、耗时、错误率），支持 Prometheus/Zipkin/Jaeger"
  - name: 安全与合规
    description: 微服务的安全规范
    patterns: ["*.java"]
    commands:
      - "所有外部接口必须进行鉴权，不能默认开放"
      - "入参必须经过校验（@Valid / 手动校验），以防止注入攻击"
      - "数据库操作要使用预编译 SQL，禁止字符串拼接"
      - "配置文件中的密钥必须通过 KMS/环境变量处理，不能明文写入"
  - name: 测试与发布
    description: 高并发微服务项目的测试规范
    patterns: ["*.java", "*.yml"]
    commands:
      - "单元测试覆盖率必须大于等于 70%，关键模块要有集成测试"
      - "高并发场景下必须进行性能测试（JMH/压测脚本）"
      - "CI/CD 流水线必须包含静态代码检查（SpotBugs/SonarQube）"
      - "发布要采用灰度策略，禁止全量一次性上线"

总结

如何有效运用 Cursor Rules？

1. 全局规范应放在项目根目录下的 .cursorrules 文件里。
2. 项目定制：比如你的项目是用 Spring Boot，那你可以这样添加：
3. -name:SpringBoot专属规则
   patterns: [“*.java”]
   commands:
   -“Controller 只负责路由和参数校验”
   -“所有业务逻辑都应该在 Service 层处理，事务控制也要放在 Service 层”
   -“DAO 层必须使用 JPA/MyBatis，尽量避免 SQL 拼接”
4. 个性化偏好：比如规定 tab=4 个空格，或使用 Slf4j 进行日志记录，这些都可以写进去。
5. 每当你换项目时，可以保留一份 全局规则，然后在新项目里再添加一份 项目规则。

-05-

粉丝福利

我在这里创建了一个程序员成长与副业交流群，
希望和一群志同道合的小伙伴们一起探讨自我提升，
可以聊聊：
技术成长、职业规划，分享学习路线、面试经验，以及各种效率工具，
还可以探讨多元化的副业变现途径，从写作课程到接私活，
我们会组织主题活动、打卡挑战和项目合作，让大家互相帮助，共同进步。
如果你对这个特别的群感兴趣，
可以加我微信，通过后我会邀请你进群，
不过请注意，群里不允许任何广告，违者将被踢出。