提案

apidiff，OpenJDK CodeTools 项目中的一个新工具。

摘要

一个用于比较两个或更多 API 版本的实用工具，它结合了类文件、源文件和/或 API 文档文件中的信息（参见 原始帖子）。

基本原理

在不断发展的 API 中，一项重要任务是能够比较 API 的不同版本，例如在提出更改之前和之后。但是，比较 API 的版本并非易事

• 仅比较源文件很困难，因为有与 API 实现相关的其他内容。

• 仅比较类文件很困难，因为类文件不包含文档注释中的任何叙述规范。

• 仅比较 API 文档文件很困难，因为 API 的底层模型可能难以辨别，并且受 javadoc 工具的呈现方式影响。但是，这是开发人员想要阅读 API 规范时最常用的形式。

此外，Java 语言正在 不断发展，具有 记录和 密封类等新功能，并且希望比较工具能够在 API 中出现此类功能时处理此类功能。

能够根据更改是否兼容来对更改进行分类也很不错，如果是，则兼容的 “类型”是什么。但是，这通常需要对要比较的 API 进行详细且准确的建模：比从 API 文档文件中合理获得的更多。

描述

apidiff 是一个利用 javac 前端和 JDK java.compiler 和 jdk.compiler 模块中的其他代码的工具，用于读取源和/或类文件，并找到要比较的声明。当提供源文件时，该工具还可以比较这些声明的“原始”文档注释，如果提供了相应的 API 文档，该工具还可以提取并比较这些声明的文档部分。第三方库 (java-diff-utils、daisydiff) 用于比较文档注释的纯文本和生成 API 文档的相关部分。

该工具可以比较两个或三个版本的 API。它可以比较类路径或模块中的类。它还可以比较序列化类形式中经常被忽略的规范。它可以比较不同版本的 JDK 中的类，尽管如果涉及预览功能，目前存在限制。该工具需要 JDK 11 或更高版本才能运行：因为它在内部使用 JDK 模块，因此必须使用至少与所比较的最新 API 一样新的 JDK 版本运行该工具。

在比较多个版本的 API 时，每个声明的“结构”部分将被比较并作为一组报告；每个声明的规范的“叙述”部分将与最新版本成对比较。

在内部，该工具包含一个前端，它可以设置和访问 javac 前端的不同并发实例，并通过一个接口向后端报告差异，该后端可以生成一个 HTML 报告。一个内部组件提供了提取 API 文档文件中包含该文件中声明的规范的部分的能力，忽略页眉、页脚和摘要表的“装饰”；此组件可以处理 javadoc 工具的最新版本生成的结果。