refactorfirst/RefactorFirst

# RefactorFirst 这款针对 Java 代码库的工具将帮助你确定首先应该重构的内容： - 类和包的循环（包含循环图像！） - 在 [Object Oriented Metrics in Practice](https://link.springer.com/book/10.1007/3-540-39538-5) 中识别出的面向对象不和谐问题（即反模式） 它会扫描你的 Git 仓库，并通过运行以下分析来生成一个单页应用： - 使用 [OpenRewrite](https://github.com/openrewrite/rewrite) Java 解析器和 [JGraphT](https://jgrapht.org/) 对你的源代码进行循环分析 - 进行假设分析，以确定在类循环中移除最合适的关联关系 代码地图查看器由 [3D Force Graph](https://vasturiano.github.io/3d-force-graph)、[sigma.js](https://www.sigmajs.org/) 和 [GraphViz DOT](https://graphviz.org/docs/layouts/dot/) 提供支持，并使用 [Vizdom](https://github.com/vizdom-dev/vizdom) 来渲染 DOT 图。
如果类和关系数量超过 4000 个，将提供一个简化的 3D 查看器，以避免页面加载变慢。未来的版本中将支持在 3D 界面中切换功能。 ## 如何快速使用 RefactorFirst 在你的 Java 项目的根目录下运行以下命令。你需要安装 Git、Java 11（或更高版本）和 Maven 3。此命令将同时分析 Maven 和非 Maven 项目： ``` mvn org.hjug.refactorfirst.plugin:refactor-first-maven-plugin:0.9.0:htmlReport ``` 在你的项目中查看位于 ```target/site/refactor-first-report.html``` 的报告。 各种使用场景的完整说明请见下文。 我们已经尽了最大努力，使分析和页面渲染的时间尽可能快。 ## 分解和移除循环 循环分析是使用前沿的 [Directed Feedback Vertex Set](https://dl.acm.org/doi/10.1145/3711669) 和 [Directed Feedback Arc Set](https://arxiv.org/abs/2208.09234) 算法进行的，旨在确定最适合移除的类以及类之间的关联关系，从而消除代码库中的循环。 这些算法非常强大，在处理大型代码库时会把你的 CPU 推到极限，不过它们表现得很有礼貌，不会让你的电脑卡顿。 这些图算法也可以在 RefactorFirst 之外使用。 有关顶点内核化算法的流程，请参见 [DIAGRAM.md](./graph-algorithms/src/main/java/org/hjug/feedback/vertex/kernelized/DIAGRAM.md)。 有关边内核化算法的更多细节，请参见 [DIAGRAM.md](./graph-algorithms/src/main/java/org/hjug/feedback/arc/pageRank/DIAGRAM.md)。 ### 如何理解“关系移除优先级”表格 “关系移除优先级”表格显示了从代码库中移除以消除所有循环的最合适的关系。 该表首先按照关系所存在的循环数量进行排序，其次是关系中类的变更倾向性（change proneness）。 - 应该被拆分或从代码库中移除的类会带有一个 * 号。 - 如果只有一个类是粗体，那么共享的功能应该被移至非粗体的类中。 - 如果两个类都不是粗体或都是粗体：请仔细检查这两个类，重新评估类的职责，然后进行重构以移除该关系。如果其中一个或两个类被识别为不和谐问题，请遵循针对该不和谐问题提供的指导建议。 看一看 [Spring Petclinic REST 项目示例报告](https://rawcdn.githack.com/refactorfirst/RefactorFirst/c46d26211a91ffbe08d4089e04a85ff31eb093c0/spring-petclinic-rest-report.html)吧！ 报告中生成的图表看起来会类似这样：  ## 请注意：运行 RefactorFirst 需要 Java 11（或更高版本） **支持 Java 25 代码库分析！** 请使用你所使用的 Java 版本中较新的 JDK 发行版。 如果你使用的是所选 Java 版本的旧版 JDK 发行版，你可能会在分析过程中遇到问题。 ## 如何使用 RefactorFirst： ### 通过命令行生成为 HTML 报告 在项目的根目录下运行以下命令（不需要构建源代码）： ``` mvn org.hjug.refactorfirst.plugin:refactor-first-maven-plugin:0.9.0:htmlReport ``` 在 `target/site/refactor-first-report.html` 查看报告 ### [作为 GitHub Actions 输出的一部分](https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries/) 这将在 GitHub Action 步骤的输出中生成一个简化的 HTML 报告（不含图表或图像） ``` mvn -B clean test \ org.hjug.refactorfirst.plugin:refactor-first-maven-plugin:0.9.0:simpleHtmlReport \ && echo "$(cat target/site/refactor-first-report.html)" >> $GITHUB_STEP_SUMMARY ``` ### 作为构建的一部分 将以下内容添加到你项目的构建（build）部分。**showDetails** 将在生成的表格中显示 God Class 的指标和排名。 ``` ... org.hjug.refactorfirst.plugin refactor-first-maven-plugin 0.9.0 false ... ``` ### 作为 Maven 报告 将以下内容添加到你项目的报告（reports）部分。 当你运行 ```mvn site``` 时，RefactorFirst 报告将出现在站点报告中。 ``` ... org.hjug.refactorfirst.plugin refactor-first-maven-plugin 0.9.0 ... ``` ## 配置选项 我们已经使用了合理的默认配置，但如果你想覆盖这些默认值，可以指定以下参数。 如果在命令行中运行，请使用 -D 指定。例如：```-DbackEdgeAnalysisCount=0 `DanalyzeCycles=false```；如果包含在 Maven 构建中，请在配置部分指定（如上例所示）。 |选项|作用| 默认值 | |------|------|-----------------------------------------------------------| |showDetails|显示 God Class 指标| false | |backEdgeAnalysisCount|要分析的循环中后向边的数量。
如果后向边的总数大于指定的值，它将分析指定数量的最小权重边。
**如果指定为 0，则将分析所有后向边**| 50 | |analyzeCycles|分析 10 个最大的循环（未来将支持自定义配置）| true | |minifyHtml|压缩生成的 HTML 报告。 仅在 ```htmlReport``` 和 ```simpleHtmlReport``` 目标上可用。 对于大型报告可能会导致问题。| false | |excludeTests|从分析中排除测试类| true | |testSrcDirectory|从分析中排除包含此模式的类| ```src/test``` | |projectName|要在报告中显示的你的项目名称| 你的 Maven 项目名称 | |projectVersion|要在报告中显示的你的项目版本| 你的 Maven 项目版本 | |outputDirectory|项目报告写入的位置| ```${projectDir}/target/site/refactor-first-report.html``` ## 但我用的是 Gradle / 我的项目布局不是常规的！ 我计划在未来创建一个 Gradle 插件，并（可能）支持非常规的项目结构，但与此同时，你可以在与你的 .git 目录相同的目录下创建一个虚拟的 POM 文件，以便在报告中显示你项目的名称： ``` 4.0.0 com.mycompany.app my-app 1.0-SNAPSHOT ``` 然后（假设已安装 Maven）运行 ``` mvn org.hjug.refactorfirst.plugin:refactor-first-maven-plugin:0.9.0:htmlReport ``` ### 遇到错误？ 如果你看到类似下面的错误 ``` Execution default-site of goal org.apache.maven.plugins:maven-site-plugin:3.3:site failed: A required class was missing while executing org.apache.maven.plugins:maven-site-plugin:3.3:site: org/apache/maven/doxia/siterenderer/DocumentContent ``` 你需要在你的 pom.xml 中添加以下内容： ``` org.apache.maven.plugins maven-site-plugin 3.12.1 org.apache.maven.plugins maven-project-info-reports-plugin 3.4.5 ``` ## 查看报告 在 ```target/site/refactor-first-report.html``` 查看报告 一旦插件执行完毕（对于大型/老旧的代码库可能需要一段时间），在项目根目录下打开文件 **target/site/refactor-first-report.html**。它将包含一个类似于上面的图表，以及一个按照推荐的重构顺序列出 God 类的表格。图表左上角的类最容易重构，同时对团队生产力的积极影响也最大。 如果检测到高耦合的类，将会生成一个列出高耦合类的图表和表格。 ## 我已经拿到报告了。接下来该怎么办？？？ 与你的产品负责人合作，确定已识别的技术债务的优先级。将其解释为拖累团队生产力的隐性负面价值可能会有所帮助。 如果你使用的是 IntelliJ Ultimate，你可以安装 [Method Reference Diagram](https://plugins.jetbrains.com/plugin/7996-java-method-reference-diagram) 插件，以帮助你确定如何重构识别出的 God 类和高耦合类。 ## 更多细节 此插件适用于具有典型 Maven 项目布局的单模块和多模块 Maven 项目。 此工具基于 Nico Zazworka、Carolyn Seaman 和 Forrest Shull 的论文 **[Prioritizing Design Debt Investment Opportunities](https://dl.acm.org/doi/10.1145/1985362.1985372)**。基于该论文的演示文稿可在 https://resources.sei.cmu.edu/asset_files/Presentation/2011_017_001_516911.pdf 获取。 ## 局限性 * 我的时间。这是一个充满热情的项目，利用我的业余时间开发。 ## 未来计划 * 添加 Gradle 插件。 * 引入单元测试覆盖率指标，以快速识别重构类的安全性。 * 引入更多有意义的指标。 ## 注意： 如果你使用的是 0.8.0 或更早的版本，你可能会注意到从 0.9.0 版本开始，插件找到的 God 类列表发生了变化。这是因为从 0.9.0 版本开始，使用的 God class 指标忠实于《Object Oriented Metrics in Practice》中定义的指标参数。 # 谢谢！祝使用愉快！

标签：JS文件枚举, Maven插件, 代码重构, 域名枚举, 技术债务, 错误基检测, 静态代码分析