obsidian-sync/work常用/cursor/rules/coding.md

alwaysApply
true

Checkstyle 代码规范

本文档根据 checkstyle.xml 配置文件生成，描述了项目所遵循的 Java 代码规范。

一、全局检查 (Checker)

这些规则应用于项目中的每个文件。

• 文件编码: 所有文件必须使用 UTF-8 编码。
• 规则严重性: 违反规则将报告为 error 级别。
• 检查范围: 检查适用于 .java, .properties, .xml 文件。

1.1 文件格式

规则 (Module)	描述
Translation	检查 .properties 文件中是否存在重复的键 (key)。
FileTabCharacter	禁止在代码中使用 Tab 字符进行缩进，应使用空格。
RegexpSingleline	禁止行尾出现多余的空格。
NewlineAtEndOfFile	文件必须以一个空行结束。
FileLength	单个文件长度不能超过 2500 行。
LineLength	单行代码长度不能超过 300 个字符。 (package 和 import 语句、URL等除外)
SuppressWarningsFilter	允许使用 @SuppressWarnings 注解来抑制特定的规则警告。

二、Java 语法树检查 (TreeWalker)

这些规则基于 Java 的语法树，对代码结构和风格进行详细检查。

2.1 Javadoc 注释

规则 (Module)	描述
JavadocType	类和接口必须包含 Javadoc 注释。
JavadocMethod	public 和 protected 方法必须有 Javadoc 注释。被 @Override 或 @Test 注解的方法除外。允许缺少 @return 标签。
JavadocVariable	(已忽略) 此配置中，对变量 Javadoc 的检查级别为 ignore，即不强制要求。
JavadocStyle	检查 Javadoc 的基本格式。
TodoComment	代码中不应包含 TODO 注释，表示代码中不应有未完成的功能点。

2.2 命名规范

规则 (Module)	描述	格式
PackageName	包名必须全部小写。	^[a-z]+(\.[a-z][a-z0-9]*)*$
TypeName	类和接口名必须使用大驼峰命名法 (UpperCamelCase)。	^[A-Z][a-zA-Z0-9]*$
MethodName	方法名必须使用小驼峰命名法 (lowerCamelCase)。	^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$
ParameterName	方法参数名必须使用小驼峰命名法 (lowerCamelCase)。	^[a-z][a-zA-Z0-9]*$
ConstantName	常量 (static final) 命名必须使用全大写字母和下划线。	^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$
StaticVariableName	静态变量名 (static 但非 final) 必须使用小驼峰命名法。	^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$
MemberName	成员变量（非静态）名必须使用小驼峰命名法。	^[a-z][a-zA-Z0-9_]*$
LocalVariableName	局部变量名必须使用小驼峰命名法。	^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$
LocalFinalVariableName	局部 final 变量名必须使用小驼峰命名法。	^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$
MethodTypeParameterName	方法的泛型参数名必须是单个大写字母。	^[A-Z]$

2.3 定义与导入

规则 (Module)	描述
ArrayTypeStyle	数组的定义必须使用 Java 风格，例如 String[] args 而不是 String args[]。
UpperEll	long 类型的字面量必须使用大写 L (例如 123L)，避免与数字 1 混淆。
AvoidStarImport	禁止使用星号 * 进行导包，例如 import java.util.*;。
IllegalImport	禁止导入 autovalue.shaded 和 avro.shaded 包，以及 sun.* 等不推荐的包。
RedundantImport	移除多余的导入，例如导入了 java.lang 下的类、当前包的类或重复导入。
UnusedImports	移除未被使用的 import 语句。

2.4 代码尺寸

规则 (Module)	描述
MethodLength	单个方法的代码行数不能超过 200 行。
ParameterNumber	方法的参数数量不能超过 5 个 (构造方法和重写的方法除外)。
CyclomaticComplexity	方法的圈复杂度不能超过 25，以控制方法的逻辑复杂度。

2.5 空白与格式

规则 (Module)	描述
MethodParamPad	方法名和左括号 ( 之间不能有空格。
TypecastParenPad	类型转换时，括号内部不应有空格，例如 (String) obj。
ParenPad	其他圆括号（如 if for while 语句）内部不应有空格。
WhitespaceAfter	逗号 ,、分号 ; 和类型转换的右括号 ) 之后必须有空格。
WhitespaceAround	运算符（如 = + > 等）两边必须有空格。空构造器、方法等允许写成 {}。
GenericWhitespace	泛型尖括号 < > 两边不应有空格，例如 List<String>。
OperatorWrap	操作符换行时，操作符应位于行尾。
SingleSpaceSeparator	代码元素（如 if 和 (）之间应用单个空格分隔。
EmptyLineSeparator	不允许在类成员之间或方法内部存在连续多个空行。
NoWhitespaceAfter	一元运算符（如 ++ -- !）之后不应有空格。
NoWhitespaceBefore	逗号 , 和分号 ; 之前不应有空格。

2.6 修饰符

规则 (Module)	描述
ModifierOrder	类、方法、变量的修饰符必须遵循 Java 语言规范的顺序 (public, protected, private, abstract, static, final...)。
RedundantModifier	移除接口和注解中多余的修饰符（如接口方法默认为 public，无需显式声明）。

2.7 代码块

规则 (Module)	描述
NeedBraces	if、else、for、while、do-while 语句必须使用花括号 {} 包围代码块，即使只有一行。
LeftCurly	左花括号 { 必须位于代码块开始行的末尾。
RightCurly	右花括号 } 的位置遵循约定：if/else/try/catch/finally 等语句的 } 如果后面紧跟 else 或 catch，则不换行；其他情况（如类、方法结束）则应单独占一行。
AvoidNestedBlocks	避免不必要的嵌套代码块。
EmptyBlock	禁止空的 try, if, else, switch 代码块，除非在块内有注释说明。
EmptyCatchBlock	禁止空的 catch 块，除非异常变量命名为 expected 或 ignored。

2.8 编码实践

规则 (Module)	描述
EqualsHashCode	如果重写了 equals() 方法，必须同时重写 hashCode() 方法。
EqualsAvoidNull	比较字符串时，应使用字面量调用 equals 方法，如 "literal".equals(var)，以避免空指针异常。
EmptyStatement	禁止出现空语句 (单独一个分号 ;)。
SimplifyBooleanExpression	简化不必要的布尔表达式，例如 if (b == true) 应简化为 if (b)。
SimplifyBooleanReturn	简化布尔返回语句，例如 if (x) { return true; } else { return false; } 应简化为 return x;。
DefaultComesLast	在 switch 语句中，default 分支必须位于所有 case 分支之后。
MissingSwitchDefault	switch 语句必须包含 default 分支。
HiddenField	局部变量或方法参数不能与类的成员变量同名（隐藏成员变量），除非在构造器或 setter 方法中。
InnerAssignment	禁止在表达式内部进行赋值操作，例如 String s = Integer.toString(i = 2);。
IllegalInstantiation	禁止直接实例化某些应通过工厂方法创建的类。

2.9 类设计

规则 (Module)	描述
FinalClass	如果一个类只有 private 构造方法，它应该被声明为 final。
HideUtilityClassConstructor	工具类（只包含 static 方法和字段的类）必须隐藏其默认的 public 构造方法，通常是提供一个 private 的构造方法。
VisibilityModifier	检查类成员的可见性。

2.10 其他

规则 (Module)	描述
Indentation	代码必须使用 4 个空格进行缩进，相关换行策略也有规定。
CommentsIndentation	注释必须与它所描述的代码保持相同的缩进级别。
RegexpSinglelineJava	禁止在代码中使用 System.out.print，应使用日志框架替代。