如何让自定义Checkstyle检查在Eclipse插件生效并排查部署问题

问题背景 #

需实现自定义Checkstyle规则：检查指定X类的方法标识符长度不超过18字符，在Eclipse中以警告/错误形式展示违规情况。

现象 #

• 最初基于net.sf.eclipsecs.sample项目（使用net.sf.eclipsecs.core.checkstyleAddonProvider扩展点）导出插件放入dropins目录，可在Checkstyle偏好设置UI中看到MethodLimitCheck。
• 添加自定义AbstractCheck子类并修改配置后无效果；删除插件重新导出（甚至恢复原项目），再也无法在UI中看到自定义检查。
• OSGi控制台显示插件状态为ACTIVE，但UI未加载自定义检查项。
• 已添加-clean -debug启动参数并配置.options文件，Error Log和/.metadata/.log无报错；p2日志显示存在单元未安装情况。

环境 #

• Eclipse 2024-03(4.31.0)
• Eclipse Checkstyle Project 10.14.1.202403151842（Marketplace安装）
• Mac OS 14.4

排查步骤 #

1. 彻底清理缓存与插件残留 #

• 关闭Eclipse，删除eclipse/configuration/org.eclipse.osgi目录（OSGi缓存目录，强制重新解析所有插件）。
• 删除dropins目录下的自定义插件，同时检查eclipse/plugins和eclipse/features目录是否有残留的自定义插件文件。
• 重新启动Eclipse，确保-clean参数生效（启动时会显示缓存清理日志）。

2. 验证插件导出完整性 #

• 打开导出的插件JAR包，检查以下内容：
  • META-INF/MANIFEST.MF是否正确声明了对net.sf.eclipsecs.core和com.puppycrawl.tools.checkstyle的依赖，且版本范围与当前Checkstyle版本匹配（比如[10.14.1,)）。
  • plugin.xml中net.sf.eclipsecs.core.checkstyleAddonProvider扩展点的配置是否正确，class属性指向的实现类是否存在于JAR中，类路径无误。
  • 自定义的AbstractCheck子类是否已编译并包含在JAR的对应路径下。

3. 分析p2未安装单元日志 #

• 找到p2日志文件（通常在/.metadata/.plugins/org.eclipse.p2.core/.log），搜索“未安装的单元”相关条目：
  • 若为自定义插件依赖缺失，需在MANIFEST.MF中补充依赖，或确保依赖插件已在Eclipse中安装。
  • 若为Checkstyle相关单元，尝试卸载当前Checkstyle插件，重新从Marketplace安装兼容版本后再导出自定义插件。

4. 验证OSGi插件加载状态 #

• 启动Eclipse后打开OSGi控制台（可通过Help > About Eclipse > Installation Details > Configuration > View Console，或启动时加-console参数），执行以下命令：
  • ss 你的插件ID：确认插件状态为ACTIVE，同时查看是否有RESOLVED但未启动的依赖插件。
  • bundle 你的插件ID：查看导入/导出包状态，确认无UNRESOLVED状态的导入包。
  • services net.sf.eclipsecs.core.checkstyleAddonProvider：检查自定义插件的服务是否已注册，未注册则说明扩展点配置有误。

5. 开启调试日志定位问题 #

• 在.options文件中添加以下配置，启动Eclipse后查看控制台输出：

  net.sf.eclipsecs.core/debug=true
  net.sf.eclipsecs.core/debug/addons=true
  

• 搜索控制台中与checkstyleAddonProvider相关的日志，确认自定义插件的扩展是否被识别，是否存在加载异常（部分细节可能仅在控制台输出）。

6. 最小化项目测试 #

• 恢复到最初可正常工作的net.sf.eclipsecs.sample项目，不做任何修改直接导出插件，放入dropins启动Eclipse：
  • 若仍无法加载，说明当前Eclipse或Checkstyle版本存在兼容性问题，尝试降级Checkstyle插件到与sample项目兼容的版本。
  • 若能正常加载，再逐步添加自定义AbstractCheck子类，每添加一次就导出测试，定位导致问题的修改点。

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