沉默是金，总会发光
大家好，我是沉默
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 小工具样板（日志 + path）
"示例：安全的文件读取工具函数"from pathlib import Pathimport loggingfrom typing import Optionallogger = 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。
**-**05-
粉丝福利
我这里创建一个程序员成长&副业交流群，
和一群志同道合的小伙伴，一起聚焦自身发展，
可以聊：
技术成长与职业规划，分享路线图、面试经验和效率工具，
探讨多种副业变现路径，从写作课程到私活接单，
主题活动、打卡挑战和项目组队，让志同道合的伙伴互帮互助、共同进步。
如果你对这个特别的群，感兴趣的，
****可以加一下，微信通过后会拉你入群，
但是任何人在群里打任何广告，都会被我T掉。
