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，使用 type hints。
- 文件操作用 pathlib，日志用 logging。
- 避免裸
except:，要捕获具体异常。 - 用 venv / pipenv / poetry 管理依赖。
前端（Vue）
- Vue3 + TypeScript，优先
<script setup>与 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/ # REST 层
├── 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 模板：改动目的 / 影响范围 / 回归风险 / 测试说明。
- 运行时监控：Prometheus + Grafana，关键业务必设告警。
-03- 示例 .cursorrules 文件
通用规则
rules:
- name: 基础代码规范
description: 统一代码风格和基本习惯
patterns: ["*.java", "*.js", "*.ts", "*.py"]
commands:
- "不要生成冗余的 import，按需导入"
- "变量名使用驼峰命名，类名使用大驼峰命名"
- "方法长度尽量 < 50 行，超长拆分"
- "避免硬编码，提取为常量或配置"Java 高并发/微服务项目示例
rules:
- name: 并发与线程安全
description: 高并发场景下的编程规范
patterns: ["*.java"]
commands:
- "禁止在多线程环境下使用非线程安全集合，优先用 ConcurrentHashMap"
- "多线程共享变量必须加 volatile 或使用原子类（AtomicInteger/Long）"
- "锁粒度尽量小，避免 synchronized 在大方法上"
- "优先使用线程池 ExecutorService，禁止手动 new Thread()"（省略部分，可按项目复制扩展）
-04- 总结：怎么用好 Cursor Rules？
- 全局规范：放在项目根目录的
.cursorrules文件。 - 项目定制：比如 Spring Boot 项目，增加特定规则：
- name: SpringBoot特定规则
patterns: ["*.java"]
commands:
- "Controller 层只写路由和参数校验"
- "业务逻辑必须在 Service 层，事务控制也在 Service 层"
- "DAO 层必须使用 JPA/MyBatis，不写 SQL 拼接"- 个性化偏好：如 tab=4 空格，日志使用 Slf4j 等。
- 多项目管理：每个项目可保留一份全局 rules，再补充一份项目规则。
