如何配置Checkstyle规则：仅允许带附近注释的SuppressWarnings注解

好问题！要实现这个需求，你可以通过组合Checkstyle的现有规则来达成——核心思路是用正则检查@SuppressWarnings注解的上下文，确保它的同一行或者上一行存在注释说明抑制原因。下面是具体的实现方案：

1. 保留原有抑制类型限制规则 #

首先继续使用你现有的SuppressWarnings模块，它的作用是限制代码中只能使用指定类型的抑制（比如unchecked、unused），避免滥用：

<module name="SuppressWarnings">
  <property name="format" value="^unchecked$|^unused$"/>
  <property name="tokens" value="CLASS_DEF,INTERFACE_DEF,ENUM_DEF,ANNOTATION_DEF,ANNOTATION_FIELD_DEF,ENUM_CONSTANT_DEF,METHOD_DEF,CTOR_DEF"/>
</module>

2. 添加上下文检查规则 #

新增RegexpSinglelineJava模块，专门检查@SuppressWarnings注解是否伴随注释。这个规则会匹配没有在同一行或上一行添加注释的注解，并抛出错误：

<module name="RegexpSinglelineJava">
  <property name="format" value="^(?!.*//.*@SuppressWarnings|@SuppressWarnings.*//|//.*\n.*@SuppressWarnings).*@SuppressWarnings"/>
  <property name="message" value="@SuppressWarnings注解必须在同一行或上一行添加注释说明抑制原因"/>
  <property name="severity" value="ERROR"/>
  <property name="tokens" value="ANNOTATION"/>
</module>

正则规则说明 #

这个正则的逻辑是反向匹配：排除掉以下三种合法场景，剩下的无注释注解都会被标记为错误：

• 注释与注解在同一行，注释在前：// 因作为Lib暴露API，抑制访问权限警告 @SuppressWarnings("WeakerAccess")
• 注释与注解在同一行，注释在后：@SuppressWarnings("WeakerAccess") // 因作为Lib暴露API，抑制访问权限警告
• 注释在上一行，注解在下一行：

  // 第三方Lib隐藏受检异常抛出事实，抑制instanceof判断的假警告
  @SuppressWarnings("ConstantConditions")
  

3. 扩展支持多行注释（可选） #

如果你的团队习惯用多行注释/* ... */，可以把正则调整为支持多行注释的版本，同时改用RegexpMultiline模块：

<module name="RegexpMultiline">
  <property name="format" value="^(?!.*(/\*.*?\*/|//).*@SuppressWarnings|@SuppressWarnings.*(/\*.*?\*/|//)|(/\*.*?\*/|//).*\n.*@SuppressWarnings).*@SuppressWarnings"/>
  <property name="message" value="@SuppressWarnings注解必须在同一行或上一行添加注释说明抑制原因"/>
  <property name="severity" value="ERROR"/>
  <property name="tokens" value="ANNOTATION"/>
</module>

4. 覆盖单行Checkstyle关闭的场景 #

对于你提到的// CHECKSTYLE:OFF这类单行关闭检查的操作，也可以用类似的规则强制添加注释：

<module name="RegexpSinglelineJava">
  <property name="format" value="^(?!.*//.*CHECKSTYLE:OFF).*CHECKSTYLE:OFF"/>
  <property name="message" value="使用CHECKSTYLE:OFF关闭检查时，必须添加注释说明原因"/>
  <property name="severity" value="ERROR"/>
  <property name="tokens" value="COMMENT"/>
</module>

这个方案不需要自定义Checkstyle插件，完全基于现有规则组合实现，能有效督促开发者为抑制操作添加必要的说明，避免无理由的警告屏蔽。

内容的提问来源于stack exchange，提问作者Alissa