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;
}
- 主键ID，使用 MyBatis-Plus 雪花算法分配
Python 小工具样板（日志 + path）
"示例：安全的文件读取工具函数"
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，禁止手动 new Thread()"
- "线程池必须自定义 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）"
- "发布必须灰度，禁止全量一次性上线"
-04-
总结
怎么用好 Cursor Rules？
全局规范放在项目根目录的 .cursorrules 文件。
项目定制：比如你项目是 Spring Boot，就加：
-name:SpringBoot特定规则
patterns: ["*.java"]
commands:
-"Controller 层只写路由和参数校验"
-"业务逻辑必须在 Service 层，事务控制也在 Service 层"
-"DAO 层必须使用 JPA/MyBatis，不写 SQL 拼接"
个性化偏好：比如强制 tab=4 空格，或者日志用 Slf4j，也可以写进去。
每次换项目，可以有一份 全局 rules，然后在项目里再补充一份 项目 rules。
