基于web搜索的 java API 使用推荐系统APIExample

程序员经常通过学习 API 的使用示例来学习如何使用它。因特网上的网页上散布着许多使用实例。然而，通过网络搜索从大量的 web 页面中找出所需的示例通常需要程序员付出很大的努力。本文提出了一个名为 APIExample 的工具，它可以从因特网上的 web 页面中提取 java API 的使用示例并推荐给程序员。给定一个 java API，该工具从网络上收集相关的 web 页面，提取嵌入页面中的 java 代码片段及其周围的描述性文本，然后将它们组合成程序员的使用示例。此外，为了帮助程序员通过浏览更少的示例来获取更多类型的目标 API 用法，我们的工具将根据目标 API 的用法对列出的示例进行聚类和排序。此外，作为一个实用的工具，APIExample 在一个简洁的用户界面中提供了有关使用目标 API 的多个方面的常用信息，并提供了友好的用户体验。两种用户交互风格，web 搜索门户和 Eclipse 插件，现在都是公开可用的。

3 APIEXAMPLE 概述

在本节中，我们以 APIExample 的 Web 搜索门户用户界面为例简要介绍 APIExample 的功能，有关该工具演示的详细信息，请访问网站。

提交“java.io.BufferedReader”查询后，将返回 API 的用法示例和其他与用法有关的信息，如图 1 所示。所提供的用法示例都是从互联网上的网页中自动提取的。

图 1 java.io.BufferedReader 的用法示例搜索结果

4 方法

如图 2 所示，APIExample 背后的方法包括四个主要阶段：（1）网页收集，（2）使用示例提取，（3）示例聚类和排名以及（4）统计分析。

图 2 APIExample 背后方法的过程

4.1 网页收集

给定一个 API，APIExample 通过利用 “APIFQN” example java 的格式构造查询，利用 Google 从互联网上收集相关的 web 页面，其中 APIFQN 是给定 API 的全限定名，术语“example”和“java”用于限制搜索范围。结果列表中的前 N 个（当前为 300 个）网页被下载为目标 API 的相关网页。

4.2 使用示例例提取

这个阶段包括三个步骤：1）网页分割；2）代码片段识别；3）描述性文本提取。

1）网页分割

此步骤根据 HTML 文档结构将网页的文本内容拆分为页段。我们将几个特定的标记看作段符号，包括 P、DIV、TABLE、TR、PRE、CODE、OL、UL、LI 和 Heading 标记（H1~H6），因为它们通常用作内容段的容器。嵌入在这些标记中的文本内容被视为一个段。当其他标记的文本内容保留给其父标记时，这些标记将被删除。

2）代码片段识别

对于每个页面段，我们通过两个步骤判断它是否是代码段：a）使用启发式方法初步确定该段是否“看起来”是代码段；b）使用可适应的解析器解析可能的代码段以做出最终决定，同时提取代码段的细粒度结构信息。

在这一步中，在解析阶段生成的细粒度编程结构信息（例如使用了哪些 APIs，在哪一行调用了哪些方法，声明了哪些方法）将被记录到以下阶段。

3）描述性文本提取

遍历每个网页的段列表，当遇到一个代码段时，我们使用以下策略提取其前面的描述性文本：迭代合并代码段前面的段，直到满足以下条件之一：1）遇到另一个代码段。2） 合并的描述性文本的长度达到给定的阈值（当前为 250 个术语）3）遇到内容中断的符号。以下标签被视为中断符号：DIV、TABLE、HR、UL、OL、H1~H6。

对于代码后面的描述性文本，根据观察结果，如果紧跟在代码片段后面的文本段提到代码块声明的编程元素，我们将尝试提取它们。然后，我们使用与前面的文本提取相似的策略来提取代码片段后面的描述性文本。

4.3 示例聚类和排名

由于 web 搜索返回的结果非常庞大，因此使用示例的数量通常非常大。实际上，它们中的许多演示了目标 API 的类似用法。要了解如何使用 API，程序员通常需要掌握 API 的多种用法。为了减少程序员在探索许多重复结果时所需的工作量，我们对收集到的使用示例进行聚类和排序。这一点很重要，因为在 web 搜索过程中，程序员在理解大量搜索结果时的认知负担一直是一个很大的问题，使他们难以处理信息。

应用 API 来完成不同任务的人通常会调用 API 的不同方法集。因此，我们将对每个示例的代码片段公开的目标 API 方法的调用作为使用特性。然后我们利用这个特性计算任意两个使用示例之间的相似性。调用目标 API 的相同方法集的两个示例将集群到一个类别中。

排名包括两部分：1）簇间排名，即对使用簇进行排名；2）簇内排名，即对使用簇中的使用实例进行排名。

4.4 统计分析

基于上述阶段产生的数据，我们对 API 的使用相关信息进行统计分析，包括 API 的不同用法分布、API 的每个方法的调用频率以及常用的 APIs。分析结果存储在数据库中，以及用于检索的使用示例。

5 本文主要贡献

本文提出了一个实用工具 APIExample，它提供了一个基于 web 搜索的 java API 使用实例的完整视图。为了帮助程序员从大量的网页中轻松地找出 API 的使用示例，该工具自动识别并从相关网页中提取其使用示例，同时消除不相关的噪音。该工具不仅可以提取代码片段，还可以正确提取可读的描述性文本。这使得使用示例更容易理解，程序员可以在不干扰无关信息的情况下查看它们。为了减少程序员查看许多重复结果的负担，APIExample 对收集到的使用示例进行基于使用的集群和排名。有了这种支持，程序员可以通过浏览更少的结果来研究目标 API 的更多种用法。此外，通过对收集到的实例的分析，APIExample 可以直接告诉程序员哪些 API 的用法经常出现在互联网上，哪些 API 的方法经常使用，哪些 API 经常与 API 一起使用。这些信息有助于指导程序员更好地了解 API。所有这些与使用相关的信息都以简洁的用户界面和友好的用户体验呈现给程序员。该工具现在可在http://www.apiexample.com上获得。