深入理解 Gradle Tooling API

1. 简介
构建系统是用来从源代码生成目标产物的自动化工具，目标产物包括库、可执行文件、生成的脚本等，构建系统一般会提供平台相关的可执行程序，外部通过执行命令的形式触发构建，如 GUN Make、Ant、CMake、等等。是一个灵活而强大的开源构建系统，它提供了跨平台的可执行程序，供外部在命令行窗口通过命令执行构建，如 ./命令触发构建任务。
现代成熟的 IDE 中会把需要的构建系统集成进来，结合多种命令行工具，封装为一套自动化的构建工具，并提供构建视图工具，提高开发人员的生产力。在IDEA 中，可以通过视图工具触发执行任务，但它并不是通过封装命令行工具来实现的，而是集成了专门提供的编程 SDK -API，通过此 API 可以将构建能力嵌入到 IDE 或其他工具软件中：
为什么要专门提供一个API 供外部集成调用，而不是像其他构建系统一样，只提供基于可执行程序的命令方式呢？ API 是对的一个重大扩展，它提供了比命令方式更可控、更深入的构建控制能力，可以让 IDE 和其他工具更方便、紧密地和能力结合。API 接口可以直接返回构建结果，无需像命令方式一样再手动解析命令行程序的日志输出，并且可以独立于版本运行，这意味着相同版本的API 可以处理不同版本的构建，同时向前和向后兼容。
2. 接口功能及调用示例 2.1 接口功能
API 提供了执行和监控构建、查询构建信息等功能：
关键 API 如下：
2.2 调用示例查询项目结构和任务
try (ProjectConnection connection = GradleConnector.newConnector().forProjectDirectory(new File("someFolder")).connect()) {GradleProject rootProject = connection.getModel(GradleProject.class);Set subProject = rootProject.getChildren();Set tasks = rootProject.getTasks();}
如上文 API 介绍，首先通过API 的入口类创建一个到参与构建工程的连接，然后通过 (Class ) 获取此工程的结构信息模型，该模型包含我们要查询的项目结构、项目任务等信息。
执行构建任务
String[] gradleTasks = new String[]{"clean", "app:assembleDebug"};try (ProjectConnection connection = GradleConnector.newConnector().forProjectDirectory(new File("someFolder")).connect()) {BuildLauncher build = connection.newBuild();build.forTasks(gradleTasks).addProgressListener(progressListener).setColorOutput(true).setJvmArguments(jvmArguments);build.run();}
此例中通过的 () 方法创建了一个用于执行构建任务的，然后通过 (... tasks) 配置要执行的任务以及配置执行进度监听等等，最后通过 run() 触发执行任务。
3. 原理分析 3.1 如何与构建进程通信？
API 并不具备真正的构建能力，而是提供了调用本机程序的入口，方便以编码形式与通信，在我们自己的工具程序中通过 API 触发调用构建能力后，还需要和真正的构建程序进行跨进程通信。不论是通过API 与交互的 IDE 或工具程序，还是以形式与交互的命令行窗口程序，这种跨进程调用构建程序的客户端程序，都是一个，真正执行任务的构建程序才是build .
是长期存在的build ，通过规避构建JVM 环境和内存缓存提高构建速度，对于集成API 的，会始终启用。也就是说，集成了API 的工具程序，会始终与跨进程通信，调用构建能力。是动态创建的，若要连接到动态创建的，就需要通过服务注册和服务发现机制，将注册记录下来并开放查询，就提供了这样的机制。
客户端 -
下面以获取工程结构信息为切入点，从源码角度分析API 的跨进程通信机制：
try (ProjectConnection connection = GradleConnector.newConnector().forProjectDirectory(new File("someFolder")).connect()) {GradleProject rootProject = connection.getModel(GradleProject.class);}
从代码上看，虽然像是建立了一个到的链接，但并没有，而是在 (Class ) 方法中才会真正去建立与的链接，此方法内部，会从API 侧调用到源码中，最后在 or.java 中查找可用的：

文章插图

public DaemonClientConnection connect(ExplainingSpec constraint) {final Pair, Collection> idleBusy = partitionByState(daemonRegistry.getAll(), Idle);final Collection idleDaemons = idleBusy.getLeft();final Collection busyDaemons = idleBusy.getRight();// Check to see if there are any compatible idle daemonsDaemonClientConnection connection = connectToIdleDaemon(idleDaemons, constraint);if (connection != null) {return connection;}// Check to see if there are any compatible canceled daemons and wait to see if one becomes idleconnection = connectToCanceledDaemon(busyDaemons, constraint);if (connection != null) {return connection;}// No compatible daemons available - start a new daemonhandleStopEvents(idleDaemons, busyDaemons);return startDaemon(constraint);}

通过以上查找逻辑及相关代码，可以得出：
包括 Idle、Busy、、、、六种状态；
通过模式执行构建时，会依次尝试查找 Idle、状态且环境兼容的，如果没有找到，就新建一个与环境兼容的；
所有的记录在 .java 注册表中，供获取；
的环境兼容判断包括版本、文件编码、JVM heap size 等属性；
获取到一个兼容的后，会通过链接到监听的端口，然后通过与通信；
服务端 -
当一个调用构建能力时，会触发的创建，进程入口函数在 .java 中，然后会转到 .java 中初始化，最后在 .java 中开启并绑定监听一个指定的端口：

public ConnectionAcceptor accept(Action action, boolean allowRemote) {final ServerSocketChannel serverSocket;int localPort;try {serverSocket = ServerSocketChannel.open();serverSocket.socket().bind(new InetSocketAddress(addressFactory.getLocalBindingAddress(), 0));localPort = serverSocket.socket().getLocalPort();} catch (Exception e) {throw UncheckedException.throwAsUncheckedException(e);}...}

随后会在 r.java 中将记录到注册表中：

public void onStart(Address connectorAddress) {LOGGER.info("{}{}", DaemonMessages.ADVERTISING_DAEMON, connectorAddress);LOGGER.debug("Advertised daemon context: {}", daemonContext);this.connectorAddress = connectorAddress;daemonRegistry.store(new DaemonInfo(connectorAddress, daemonContext, token, Busy));}

这样就可以在注册表中获取到兼容的及其端口，从而与建立连接实现通信，具体流程如下图：
总结梳理一下API 与的连接建立流程：
API 本身代码量并不是太多，调用获取项目信息接口经过抽象封装后，会进入到源码中，但还属于进程中；
在 or 中会尝试从获取可用的、兼容的，如果没有，就新建一个；
启动后会通过绑定监听到固定端口，然后将监听端口等自身信息记录到中，供查询、获取以及建立连接；
3.2 如何实现向前和向后兼容？
API 支持2.6 及更高版本，即某一版本的API 与其他版本向前和向后兼容，支持调用旧版或新版进行构建，但API 所包含的接口功能并非适用于所有版本； 5.0 及更高版本对API 版本也有要求，需要API 3.0 及更高版本。和API 不同版本之间是如何实现兼容的呢？
思考一个问题，如果我们有两个软件：主软件 A 和专门用于调用 A 的工具软件 B，如何才能实现 A、B 之间最大程度且优雅的版本兼容？下面深入分析API 和源码，看看在版本兼容方面采取了哪些值得关注的技术方案。

文章插图
版本适配
在API 源码仓库中，有一张介绍获取项目信息调用链的流程图：
我们只关注图中的 - 从API 调用到模块的关键类：
has entrytocalls from
API 侧最终在 .java 中通过自定义加载，自定义类加载路径指定了对应版本 lib 下的 jar 包，从而可以实现加载不同版本的：

private ClassLoader createImplementationClassLoader(Distribution distribution, ProgressLoggerFactory progressLoggerFactory, InternalBuildProgressListener progressListener, ConnectionParameters connectionParameters, BuildCancellationToken cancellationToken) {ClassPath implementationClasspath = distribution.getToolingImplementationClasspath(progressLoggerFactory, progressListener, connectionParameters, cancellationToken);LOGGER.debug("Using tooling provider classpath: {}", implementationClasspath);FilteringClassLoader.Spec filterSpec = new FilteringClassLoader.Spec();filterSpec.allowPackage("org.gradle.tooling.internal.protocol");filterSpec.allowClass(JavaVersion.class);FilteringClassLoader filteringClassLoader = new FilteringClassLoader(classLoader, filterSpec);return new VisitableURLClassLoader("tooling-implementation-loader", filteringClassLoader, implementationClasspath);}

API 通过自定义 Java 类加载器调用到本机指定版本的源码，需要注意的是，虽然已经是侧的源码，但还属于端进程，即 IDE 等工具软件程序中。
模型类适配
通过 (Class ) 方法可以从中获取工程结构信息模型，而不同版本可能有不同的定义，如何在同一版本API 中兼容多个版本的信息模型结构呢？
API 在请求获取信息模型前，会在 .java 中根据版本判断是否支持获取该模型，若支持，才会向发出获取请求。将对应版本的信息模型返回后，在API 的 er.java 中会对其封装一层动态代理，最终以 Proxy 形式返回：

private static  T createView(Class targetType, Object sourceObject, ViewDecoration decoration, ViewGraphDetails graphDetails) {......// Create a proxyInvocationHandlerImpl handler = new InvocationHandlerImpl(targetType, sourceObject, decorationsForThisType, graphDetails);Object proxy = Proxy.newProxyInstance(viewType.getClassLoader(), new Class[]{viewType}, handler);handler.attachProxy(proxy);return viewType.cast(proxy);}

最终API 返回的仅仅是一个动态代理接口，如下：

public interface GradleProject extends HierarchicalElement, BuildableElement, ProjectModel {......File getBuildDirectory() throws UnsupportedMethodException;}

可以看到，即使是支持的信息模型，其中的某些内容也可能由于版本不匹配而不支持获取，调用会抛出异常。
通过动态代理接口方式，实现了适配不同版本的模型类，但这种方式也带来一个缺点，在API 侧由于只能拿到模型信息的接口，并不是真正的模型实体类，那后续对整个模型信息类做序列化或传递时，就需要再做一层转换，构造出一个真正包含内容的实体类，库中就针对模型，构造了的真正包含内容的实体类 l 。
4. 总结
本文首先从现代 IDE 与构建系统的结合方式出发，引出API，介绍了它对于构建系统的特殊意义，然后通过API 具体的 API 及调用示例介绍了它的主要功能，最后在原理分析方面，结合源码着重分析了跨进程通信与版本兼容原理，这也是API 中非常重要的两个机制。
通过对API 的分析学习，可以对API 整体的架构原理深度掌握，从而更好地基于它开发具有能力的工具软件，另外还可以学习到一些类似技术架构场景下的方法论：在需要与程序运行时动态创建的服务通讯时，一般可以引入服务注册和服务发现机制去实现对动态服务的查询、连接；作为一个供外部接入的工具程序，在同类程序都仅提供命令行方式时，我们要敢于打破常规、提供一种全新的方式，从而可以更大程度给其他软件赋能，实现双方共赢。
5. 参考文章
6. 加入我们
我们是字节跳动终端技术团队（）下的Tools 团队，负责打造公司范围内，面向不同业务场景的研发工具，提升移动应用研发效率。目前急需寻找移动研发工程师 / iOS 移动研发工程师 / 服务端研发工程师。
【深入理解 Gradle Tooling API】了解更多信息请联系：，邮件主题简历-姓名-求职意向-期望城市-电话。