---
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`，应使用日志框架替代。 |