从0到1配置cursor规则Java篇：全局（Always Apply）

Ne0inhk

— 15 min read
从0到1配置cursor规则Java篇：全局（Always Apply）

alwaysApply: true

Java 项目全局规则 (Always Apply)

编码规范

命名规范

  • 类名: 使用 PascalCase（大驼峰），如 UserService, OrderController
  • 方法名: 使用 camelCase（小驼峰），如 getUserById, processOrder
  • 变量名: 使用 camelCase，如 userName, orderList
  • 常量名: 使用 UPPER_SNAKE_CASE，如 MAX_SIZE, DEFAULT_TIMEOUT
  • 包名: 全小写，使用点分隔，如 com.example.project.service
  • 接口名: 不使用 I 前缀，直接使用有意义的名称，如 UserService 而非 IUserService
  • 实现类: 可使用 Impl 后缀，如 UserServiceImpl

代码风格

  • 使用 4 个空格缩进，不使用 Tab
  • 左大括号不换行，右大括号独占一行
  • 方法之间空一行
  • 逻辑块之间适当空行以提高可读性
  • 每行代码不超过 120 字符
  • import 语句按字母顺序排列，不使用通配符 *

注释规范

  • 类注释: 使用 JavaDoc，说明类的用途、作者、日期
/** * 用户服务类 * * @author 作者名 * @date 2025-12-09 */
  • 方法注释: 使用 JavaDoc，说明方法用途、参数、返回值、异常
/** * 根据用户ID获取用户信息 * * @param userId 用户ID * @return 用户信息 * @throws UserNotFoundException 用户不存在时抛出 */
  • 复杂逻辑: 使用单行或多行注释说明业务逻辑
  • 避免无意义的注释，代码应自解释

Spring Boot 项目规范

项目结构

src/main/java/com/example/project/ ├── controller/ # 控制器层 ├── service/ # 服务层 │ └── impl/ # 服务实现 ├── mapper/ # 数据访问层（MyBatis） ├── entity/ # 实体类 ├── dto/ # 数据传输对象 ├── vo/ # 视图对象 ├── config/ # 配置类 ├── exception/ # 异常类 ├── util/ # 工具类 └── constant/ # 常量类

分层架构

  • Controller 层: 只负责接收请求、参数校验、调用 Service、返回响应
  • Service 层: 处理业务逻辑，不直接操作数据库
  • Mapper 层: 只负责数据库操作，不包含业务逻辑
  • 避免跨层调用，Controller 不直接调用 Mapper

依赖注入

  • 优先使用构造器注入，避免使用 @Autowired 字段注入
// 推荐privatefinalUserService userService;publicUserController(UserService userService){this.userService = userService;}// 不推荐@AutowiredprivateUserService userService;

RESTful API 规范

  • 使用标准 HTTP 方法：GET（查询）、POST（创建）、PUT（更新）、DELETE（删除）
  • URL 使用小写，多个单词用连字符分隔：/api/user-orders
  • 使用复数形式：/api/users 而非 /api/user
  • 版本控制：/api/v1/users
  • 统一返回格式：
{"code":200,"message":"success","data":{...}}

异常处理

异常分类

  • 使用自定义业务异常继承 RuntimeException
  • 创建全局异常处理器 @ControllerAdvice
  • 不要捕获后不处理或只打印日志

异常处理示例

@ControllerAdvicepublicclassGlobalExceptionHandler{@ExceptionHandler(BusinessException.class)publicResponseEntity<Result>handleBusinessException(BusinessException e){returnResponseEntity.ok(Result.error(e.getMessage()));}@ExceptionHandler(Exception.class)publicResponseEntity<Result>handleException(Exception e){ log.error("系统异常", e);returnResponseEntity.ok(Result.error("系统异常"));}}

日志规范

日志级别

  • ERROR: 系统错误，需要立即处理
  • WARN: 警告信息，可能存在问题
  • INFO: 关键业务流程信息
  • DEBUG: 调试信息，生产环境关闭

日志使用

  • 使用 SLF4J + Logback
  • 使用占位符而非字符串拼接：log.info("用户ID: {}", userId)
  • 异常日志必须包含堆栈信息：log.error("处理失败", e)
  • 避免在循环中打印日志
  • 日志中不包含敏感信息（密码、身份证、银行卡等）
  • 生产环境日志级别设置为 INFO，开发环境可以使用 DEBUG

日志最佳实践

// 推荐：使用占位符 log.info("用户 {} 执行了 {} 操作", username, operation);// 不推荐：字符串拼接 log.info("用户 "+ username +" 执行了 "+ operation +" 操作");// 推荐：条件日志if(log.isDebugEnabled()){ log.debug("详细信息: {}",expensiveOperation());}// 推荐：异常日志包含堆栈 log.error("处理订单失败，订单ID: {}", orderId, e);// 不推荐：只记录异常消息 log.error("处理订单失败: "+ e.getMessage());

数据库规范

MyBatis 使用

  • 优先使用注解方式，复杂 SQL 使用 XML
  • 避免使用 SELECT *，明确指定字段
  • 使用 #{} 防止 SQL 注入，避免使用 ${}
  • 分页查询使用 PageHelper

事务管理

  • Service 层方法添加 @Transactional 注解
  • 只读操作使用 @Transactional(readOnly = true)
  • 注意事务传播行为和隔离级别

性能优化

通用原则

  • 避免 N+1 查询问题
  • 合理使用缓存（Redis）
  • 大数据量操作使用分页
  • 异步处理耗时操作
  • 使用连接池管理数据库连接

代码优化

  • 使用 Stream API 处理集合，但注意性能（小数据量时 for 循环可能更快）
  • 避免在循环中进行数据库操作（使用批量查询）
  • 合理使用线程池，不要频繁创建线程
  • 及时关闭资源，使用 try-with-resources
// 推荐：try-with-resources 自动关闭资源try(InputStream is =newFileInputStream("file.txt");BufferedReader reader =newBufferedReader(newInputStreamReader(is))){String line = reader.readLine();}// 不推荐：手动关闭资源InputStream is =null;try{ is =newFileInputStream("file.txt");}finally{if(is !=null){ is.close();}}

集合使用最佳实践

  • 指定初始容量: 避免频繁扩容
// 推荐：已知大小时指定初始容量List<String> list =newArrayList<>(100);Map<String,Object> map =newHashMap<>(16);// 不推荐：使用默认容量List<String> list =newArrayList<>();
  • 选择合适的集合类型
    • 需要快速随机访问：ArrayList
    • 频繁插入删除：LinkedList
    • 不允许重复：HashSet
    • 需要排序：TreeSet 或 TreeMap
    • 线程安全：ConcurrentHashMap

空值处理

  • 使用 Optional 处理可能为空的值
// 推荐publicOptional<User>findUserById(Long id){User user = userMapper.selectById(id);returnOptional.ofNullable(user);}// 使用 userService.findUserById(1L).map(User::getUsername).orElse("匿名用户");
  • 避免返回 null，返回空集合
// 推荐publicList<User>listUsers(){List<User> users = userMapper.selectAll();return users !=null? users :Collections.emptyList();}// 不推荐publicList<User>listUsers(){return userMapper.selectAll();// 可能返回 null}

安全规范

OWASP Top 10 防护

  • SQL 注入防护: 使用参数化查询（#{}），避免字符串拼接 SQL
  • XSS 防护: 对用户输入进行 HTML 转义，使用 @JsonIgnore 防止敏感信息泄露
  • CSRF 防护: 使用 Spring Security 的 CSRF Token
  • 认证和授权: 使用 Spring Security 或 Shiro 进行权限控制
  • 敏感数据加密: 密码使用 BCrypt，身份证等使用 AES 加密

输入验证

  • 所有用户输入必须校验: 前端校验 + 后端校验（双重保障）
  • 白名单验证: 优先使用白名单而非黑名单
// 推荐：白名单验证privatestaticfinalSet<String> ALLOWED_TYPES =Set.of("image/jpeg","image/png","image/gif");if(!ALLOWED_TYPES.contains(file.getContentType())){thrownewBusinessException("不支持的文件类型");}

数据校验

  • 使用 @Valid 和 @Validated 进行参数校验
  • 在 DTO 中使用 JSR-303 注解：@NotNull, @NotBlank, @Size 等
@DatapublicclassUserDTO{@NotBlank(message ="用户名不能为空")@Pattern(regexp ="^[a-zA-Z0-9_]{4,20}$", message ="用户名只能包含字母、数字和下划线，长度4-20")privateString username;@NotBlank(message ="密码不能为空")@Size(min =8, max =20, message ="密码长度必须在8-20之间")privateString password;}

敏感信息处理

  • 密码: 使用 BCrypt 加密，永不明文存储
@ServicepublicclassPasswordService{privatefinalBCryptPasswordEncoder encoder =newBCryptPasswordEncoder();publicStringencodePassword(String rawPassword){return encoder.encode(rawPassword);}publicbooleanmatches(String rawPassword,String encodedPassword){return encoder.matches(rawPassword, encodedPassword);}}
  • 日志脱敏: 日志中不记录密码、身份证、银行卡等敏感信息
log.info("用户登录: username={}", username);// 正确 log.info("用户登录: password={}", password);// 错误！不要记录密码
  • 响应脱敏: 返回给前端的数据不包含敏感信息
@DatapublicclassUserVO{privateLong id;privateString username;// 不包含 password 字段}

API 安全

  • 使用 HTTPS: 生产环境必须使用 HTTPS
  • 限流防刷: 使用 Redis + AOP 实现接口限流
@Target(ElementType.METHOD)@Retention(RetentionPolicy.RUNTIME)public@interfaceRateLimit{intlimit()default10;// 每分钟最多请求次数}
  • Token 管理: JWT Token 设置合理的过期时间（如 2 小时）
  • 重要操作记录: 登录、修改密码、删除数据等操作记录操作日志

文件上传安全

  • 限制文件类型: 白名单验证文件类型
  • 限制文件大小: 防止大文件攻击
  • 文件名处理: 使用 UUID 重命名，防止路径遍历攻击
publicStringuploadFile(MultipartFile file){// 1. 验证文件类型String contentType = file.getContentType();if(!ALLOWED_TYPES.contains(contentType)){thrownewBusinessException("不支持的文件类型");}// 2. 验证文件大小（5MB）if(file.getSize()>5*1024*1024){thrownewBusinessException("文件大小不能超过5MB");}// 3. 使用 UUID 重命名String originalFilename = file.getOriginalFilename();String extension = originalFilename.substring(originalFilename.lastIndexOf("."));String newFilename = UUID.randomUUID().toString()+ extension;// 4. 保存文件returnsaveFile(file, newFilename);}

代码质量

SOLID 设计原则

  • 单一职责原则 (SRP): 一个类只负责一项职责，避免类的功能过于复杂
// 不推荐：一个类承担多个职责publicclassUserService{publicvoidsaveUser(User user){}publicvoidsendEmail(String email){}// 应该独立为 EmailServicepublicvoidgenerateReport(){}// 应该独立为 ReportService}// 推荐：职责分离publicclassUserService{publicvoidsaveUser(User user){}}publicclassEmailService{publicvoidsendEmail(String email){}}
  • 开闭原则 (OCP): 对扩展开放，对修改关闭
// 使用接口和多态实现扩展publicinterfacePaymentStrategy{voidpay(BigDecimal amount);}publicclassAlipayPaymentimplementsPaymentStrategy{publicvoidpay(BigDecimal amount){}}publicclassWechatPaymentimplementsPaymentStrategy{publicvoidpay(BigDecimal amount){}}
  • 里氏替换原则 (LSP): 子类可以替换父类且不影响程序正确性
  • 接口隔离原则 (ISP): 客户端不应依赖它不需要的接口
  • 依赖倒置原则 (DIP): 依赖于抽象而不是具体实现

代码质量工具

  • Checkstyle: 检查代码风格和编码规范
  • PMD: 检测代码中的潜在问题（未使用的变量、空的 catch 块等）
  • SpotBugs: 静态分析工具，查找代码中的 bug
  • SonarQube: 代码质量管理平台，提供全面的代码分析

基本要求

  • 方法长度不超过 50 行（理想情况 20-30 行）
  • 方法参数不超过 5 个（超过时考虑使用对象封装）
  • 圈复杂度不超过 10
  • 避免重复代码（DRY 原则），提取公共方法
  • 使用设计模式解决常见问题
  • 避免深层嵌套（不超过 3 层）
  • 类的大小不超过 500 行

命名最佳实践

  • 使用有意义且可搜索的名称
// 不推荐int d;// 经过的天数// 推荐int daysSinceCreation;int daysSinceModification;
  • 避免使用魔法数字
// 不推荐if(status ==1){}// 推荐privatestaticfinalint STATUS_ACTIVE =1;if(status == STATUS_ACTIVE){}
  • 方法名应该说明做什么
// 不推荐publicvoidprocess(){}// 推荐publicvoidsendEmailToUser(){}publicvoidcalculateTotalPrice(){}

代码审查

  • 提交前自我审查代码
  • 确保代码可读性和可维护性
  • 添加必要的单元测试（测试覆盖率 > 80%）
  • 确保没有警告和错误
  • 使用代码审查工具（如 SonarQube）
  • 团队 Code Review，至少一人审核

版本控制

Git 规范

  • Commit 信息规范 (Conventional Commits)：
    • feat: 新功能 - feat: 添加用户登录功能
    • fix: 修复 Bug - fix: 修复用户无法登出的问题
    • docs: 文档更新 - docs: 更新 API 文档
    • style: 代码格式调整（不影响功能）- style: 格式化代码
    • refactor: 重构（不增加功能也不修复 Bug）- refactor: 重构用户服务层
    • perf: 性能优化 - perf: 优化查询性能
    • test: 测试相关 - test: 添加用户服务单元测试
    • chore: 构建过程或辅助工具的变动 - chore: 更新依赖版本

Git 分支管理

  • 主分支 (main/master): 生产环境代码，只接受合并请求
  • 开发分支 (develop): 开发环境代码
  • 功能分支 (feature/xxx): 新功能开发
  • 修复分支 (hotfix/xxx): 紧急修复
  • 发布分支 (release/xxx): 发布准备

Git 最佳实践

  • 避免提交敏感信息（密码、密钥、Token 等）
  • 使用 .gitignore 忽略不必要的文件
  • 提交前进行代码审查和测试
  • 定期同步主分支代码，避免冲突
  • 小步提交，每次提交只做一件事
  • 使用有意义的分支名称：feature/user-login、fix/order-bug

代码审查清单

  • 代码是否符合编码规范
  • 是否有明显的 Bug 或逻辑错误
  • 是否有安全隐患
  • 是否有性能问题
  • 是否有充分的单元测试
  • 是否有必要的注释和文档
  • 是否有代码重复
  • 是否考虑了边界情况和异常处理

项目文档规范

核心文档要求

项目必须维护一份核心架构文档，用于描述项目的整体框架和功能模块，确保团队成员和 AI 辅助工具能够快速理解项目结构。

文档创建

  • 文档位置: 项目根目录
  • 文档名称: 项目框架和功能.md 或 项目功能模块分析.md
  • 强制性: 该文档为项目必备文件，与 README.md 同等重要

文档内容规范

文档应包含但不限于以下内容：

  1. 项目概述
    • 项目名称、简介、主要功能
    • 技术栈（Spring Boot、MyBatis、Redis 等）
    • 项目定位与业务领域
  2. 项目架构
    • 整体架构设计（分层架构、微服务等）
    • 模块划分与职责说明
    • 核心目录结构说明
示例： biz/ # 业务逻辑模块 └── module/ # 各业务子模块 common/ # 公共组件模块 runner/ # 应用启动模块
  1. 核心功能模块
    • 列出所有主要功能模块
    • 每个模块的职责描述
    • 模块间的依赖关系
    • 关键业务流程说明
  2. 数据库设计
    • 核心数据表说明
    • 重要表之间的关联关系
  3. 技术要点
    • 使用的关键技术或框架
    • 特殊的技术实现方案
    • 性能优化措施
  4. API 接口概览
    • 主要对外接口分类
    • 核心接口说明

文档初始化

如果项目中不存在该文档，必须立即创建：

  1. 分析代码库: 深入分析现有代码结构、包结构、类命名规范
  2. 识别模块: 识别所有功能模块（通过 controller、service、entity 等）
  3. 梳理架构: 理解项目的分层架构和技术栈
  4. 生成文档: 基于分析结果生成初始版本文档
  5. 审核完善: 与团队一起审核并完善文档内容

文档使用规范

开发前必读
  • 新成员入职: 第一时间阅读该文档，了解项目全貌
  • 开始新功能: 开发任何新功能前，先查阅文档了解相关模块
  • Bug 修复: 修复 Bug 前，通过文档定位相关模块和依赖
  • AI 辅助开发: AI 工具在接手任务前，应首先读取该文档理解项目架构
文档优先原则
工作流程： 1. 阅读项目文档 → 了解整体架构 2. 定位相关模块 → 查看具体代码 3. 理解业务逻辑 → 开始开发 4. 完成开发 → 更新文档（如有变更）

文档维护规范

必须同步更新的场景

以下情况发生时，必须立即更新文档：

  1. 架构变更
    • 新增、删除或重命名模块
    • 调整目录结构
    • 修改分层架构设计
    • 引入新的技术栈或框架
  2. 功能变更
    • 新增核心功能模块
    • 删除已有功能模块
    • 重大功能重构
  3. 数据库变更
    • 新增核心数据表
    • 删除重要数据表
    • 修改关键表结构
  4. API 变更
    • 新增主要对外接口
    • 废弃重要接口
    • 接口职责调整
更新流程
代码变更 → 同步更新文档 → Code Review 时检查文档 → 提交代码和文档

禁止行为：

  • ❌ 只修改代码，不更新文档
  • ❌ 等到项目结束再统一更新文档
  • ❌ 文档与代码不一致

正确做法：

  • ✅ 代码和文档在同一个 Commit 中提交
  • ✅ 使用 Git Commit 信息说明文档变更：feat: 添加用户模块 + 更新项目文档
  • ✅ Code Review 时同时审查代码和文档的一致性

文档地位与重要性

基础性文件
  • 该文档是理解项目的第一入口
  • 与 README.md 和 pom.xml 同等重要
  • 文档缺失或过期将严重影响开发效率
质量要求
  • 准确性: 文档内容必须与代码实现保持一致
  • 时效性: 文档必须实时反映当前项目状态
  • 完整性: 涵盖所有核心模块和功能
  • 可读性: 结构清晰，易于理解
文档审查

在 Code Review 清单中增加文档审查项：

  • 是否需要更新项目文档
  • 文档更新是否与代码变更一致
  • 文档描述是否清晰准确

文档示例结构

# 项目框架和功能 ## 项目概述 项目名称：XXX系统 技术栈：Spring Boot 2.x + MyBatis + MySQL + Redis 项目简介：... ## 项目架构 ### 整体架构 三层架构：Controller → Service → Mapper ### 模块划分 - biz: 核心业务模块 - common: 公共组件 - runner: 应用启动 ## 核心功能模块 ### 1. 用户管理模块 - 位置：biz/module/user - 功能：用户注册、登录、权限管理 - 核心类：UserController, UserService ### 2. 订单管理模块 ... ## 数据库设计 ### 核心表 - user: 用户表 - order: 订单表 ... ## 技术要点 - 使用 Redis 实现分布式缓存 - 使用 JWT 进行身份认证 ...

最佳实践

  1. 保持简洁: 文档应聚焦架构和模块，避免过度详细的代码级说明
  2. 定期审查: 每个迭代结束后，审查文档是否需要更新
  3. 版本管理: 文档纳入 Git 版本控制，保留变更历史
  4. 团队共识: 团队达成共识，将文档维护作为开发流程的一部分
  5. 工具辅助: 可以使用 AI 工具辅助生成和更新文档，但需人工审核

Read more

C++ 异常处理机制：异常捕获、自定义异常与实战应用

C++ 异常处理机制：异常捕获、自定义异常与实战应用

第34篇：C++ 异常处理机制：异常捕获、自定义异常与实战应用 一、学习目标与重点 * 掌握异常处理的核心概念（异常、抛出、捕获、处理）及基本语法 * 理解 try-catch-throw 语句的执行流程，能够正确捕获和处理标准异常 * 学会自定义异常类，满足实际开发中的个性化异常场景需求 * 掌握异常处理的最佳实践，规避常见错误（内存泄漏、异常安全问题） * 理解异常规格说明（C++11前）与 noexcept 关键字的使用场景 * 结合实战案例，提升代码的健壮性和容错能力 💡 核心重点：try-catch 捕获规则、自定义异常的继承设计、异常安全保障、实战场景中的异常处理策略 二、异常处理概述 2.1 什么是异常处理 异常处理是C++中处理程序运行时错误的机制，核心是“将错误检测与错误处理分离”——在程序出错的地方（如除以零、内存分配失败）“抛出”

By Ne0inhk
【 C++ 入门】Cyber骇客的 流式文本序列处理器 —— 【 string 类】万字大文带你从0学好C++的string类！

【 C++ 入门】Cyber骇客的 流式文本序列处理器 —— 【 string 类】万字大文带你从0学好C++的string类！

⚡ CYBER_PROFILE ⚡ /// SYSTEM READY /// [WARNING]: DETECTING HIGH ENERGY 🌊 🌉 🌊 心手合一 · 水到渠成 >>> ACCESS TERMINAL <<<[ 🦾 作者主页 ][ 🔥 C语言核心 ][ 💾 编程百度 ][ 📡 代码仓库 ] --------------------------------------- Running Process: 100% | Latency: 0ms 索引与导读 * 一、为什么学习 string类 ？ * 二、C++ 标准库中的 string 类 * 2.1）auto和范围for * 2.2）string类的常用接口 * 🚩1）string类的常用构造 * 🚩2）string类对象的容量操作 * ❗注意事项 * 1）size(

By Ne0inhk
【C++】平衡树优化实战：如何手搓一棵查找更快的 AVL 树？

【C++】平衡树优化实战：如何手搓一棵查找更快的 AVL 树？

🎬 个人主页：MSTcheng · ZEEKLOG 🌱 代码仓库 ：MSTcheng · Gitee 🔥 精选专栏: 《C语言》 《数据结构》 《C++由浅入深》 💬座右铭：路虽远行则将至，事虽难做则必成！ 前言：前两篇文章我们已经向大家介绍了map和set这两个容器，他们的底层都是平衡二叉搜索树，而今天我们就来介绍一种平衡二叉搜索树——AVL树。 文章目录 * 一、AVL树的认识 * 1.1AVL树的概念 * 二、AVL树的实现 * 2.1AVL树的基本框架 * 2.2AVL树的插入 * 2.3AVL树的中序遍历 * 2.4AVL树其他功能实现 * 三、总结 一、AVL树的认识 1.1AVL树的概念 AVL树是由G. M. Adelson-Velsky和E. M. Landis两个前苏联的科学家所发明的，它的具体定义如下： * AVL树是最先发明的自平衡⼆叉查找树，AVL是⼀颗空树，

By Ne0inhk
【Linux/C++多进程篇(二) 】万字解析从“传纸条”到“建仓库”：一文读懂linux系统编程之进程间通信 (IPC)

【Linux/C++多进程篇(二) 】万字解析从“传纸条”到“建仓库”：一文读懂linux系统编程之进程间通信 (IPC)

⭐️在这个怀疑的年代，我们依然需要信仰。 个人主页：YYYing. ⭐️Linux/C++进阶系列专栏：【从零开始的linux/c++进阶编程】 系列上期内容：【Linux/C++多进程篇(一) 】C/C++ 程序中神奇的“分身术” 系列下期内容：【Linux/C++多线程篇(一) 】多线程编程入门 目录 前言： 进程间通信（IPC） 一、进程间通信的基础概念 二、内核提供的通信方式 2.1、无名管道  📖 无名管道的API  📖 代码案例 2.2、有名管道  📖 有名管道的API  📖 代码案例 2.3、管道特点 2.4、信号  📖 信号相关概念

By Ne0inhk