Cronet 基础知识

1. 简介

上次更新日期：2022 年 5 月 6 日

Cronet 是以库的形式提供给 Android 应用使用的 Chromium 网络堆栈。Cronet 利用多种技术来减少延迟和提高网络请求吞吐量，以满足您的应用的运行需要。

很多每日用户量达到数百万的应用（如 YouTube、Google 应用、Google 相册以及 Google 地图 - 导航和公交）都由 Cronet 库来处理请求。Cronet 支持 HTTP3，是使用极广的 Android 网络库。

如需了解详情，请参阅 Cronet 功能页面。

您将构建的内容

在此 Codelab 中，您将为一款图片显示应用添加 Cronet 支持。您的应用将：

从 Google Play 服务加载 Cronet；如果 Cronet 不可用，则安全地回退。
使用 Cronet 发送请求以及接收和处理响应。
在简单的界面中显示结果。

学习内容

如何将 Cronet 作为依赖项添加到应用中
如何配置 Cronet 引擎
如何使用 Cronet 发送请求
如何编写 Cronet 回调来处理响应

此 Codelab 将重点介绍如何使用 Cronet。这款应用的大部分内容已预先实现，因此，即使您之前没有多少 Android 开发经验，您也能完成此 Codelab。不过，为使您在此 Codelab 中获得更好的学习效果，您应了解 Android 开发和 Jetpack Compose 库的基础知识。

所需条件

Android Studio 2021.1 (Bumblebee) 或更高版本
搭载 Android 10 或更高版本且装有 Google Play 服务的设备，或者搭载 Android 10 或更高版本且装有 Play 商店的模拟器
Kotlin 基础知识

2. 获取代码

我们已将您完成此项目所需的一切都放入一个 Git 代码库中。首先，请克隆此代码库并在 Android Studio 中打开其中的代码。

git clone https://github.com/android/codelab-cronet-basics

3.建立基准

我们从何处入手？

此项目的初始状态是已经构建好了一款专门为此 Codelab 设计的基本图片显示应用。如果您点击 Add an image（添加图片）按钮，就会看到向列表中添加了一张新图片，以及从互联网提取这张图片所花的时间的详细信息。该应用使用 Kotlin 提供的内置 HTTP 库，这个库不支持任何高级功能。

随着此 Codelab 的展开，我们将扩展该应用，以使用 Cronet 及其部分功能。

4. 向 Gradle 脚本中添加依赖项

您可以将 Cronet 作为搭载到该应用中的独立库来集成，也可以按平台提供的方式原样使用 Cronet。Cronet 团队建议您使用 Google Play 服务提供程序。如果使用 Google Play 服务提供程序，该应用就无需承担因搭载 Cronet（大约 5 MB）而产生的二进制文件存储空间开销，此平台也可确保提供最新的更新和安全修复程序。

无论您决定如何导入具体的实现代码，都需要添加 cronet-api 依赖项才能包含 Cronet API。

打开 build.gradle 文件，并将以下两行代码添加到 dependencies 部分。

implementation 'com.google.android.gms:play-services-cronet:18.0.1'
implementation 'org.chromium.net:cronet-api:101.4951.41'

5. 安装 Google Play 服务的 Cronet 提供程序

如上一部分所述，Cronet 可通过多种方式添加到该应用中。其中每种方式都通过一个 Provider 进行抽象化，从而确保此库与该应用之间建立必要的关联。每次您创建新的 Cronet 引擎时，Cronet 都会查看所有活跃的提供程序，并选择使用最合适的提供程序，对引擎进行实例化。

Google Play 服务提供程序通常都不是可直接使用的，因此您需要先安装该提供程序。为此，请在 MainActivity 中找到 TODO，然后粘贴以下代码段：

val ctx = LocalContext.current
CronetProviderInstaller.installProvider(ctx)

这样会启动一项以异步方式安装该提供程序的 Play 服务 Task。

6. 处理提供程序安装结果

您已经成功安装了该提供程序… 等一下，确定吗？这项 Task 是异步执行的，您还没有以任何方式处理其结果。让我们解决这个问题。将 installProvider 调用替换为以下代码段：

CronetProviderInstaller.installProvider(ctx).addOnCompleteListener {
   if (it.isSuccessful) {
       Log.i(LOGGER_TAG, "Successfully installed Play Services provider: $it")
       // TODO(you): Initialize Cronet engine
   } else {
       Log.w(LOGGER_TAG, "Unable to load Cronet from Play Services", it.exception)
   }
}

在此 Codelab 中，如果 Cronet 加载失败，我们将继续使用原生图片下载器。如果网络性能对您的应用至关重要，您可能需要安装或更新 Play 服务。如需了解详情，请参阅 CronetProviderInstaller 文档。

现在运行这款应用；如果一切正常，您应该会看到一条日志语句表明该提供程序已成功安装。

7. 创建 Cronet 引擎

Cronet 引擎是通过 Cronet 发送请求时需要用到的核心对象。该引擎使用构建器模式构建，因此您可以配置各种 Cronet 选项。我们暂且继续使用默认选项。通过将 TODO 替换为以下代码段，对新的 Cronet 引擎进行实例化：

val cronetEngine = CronetEngine.Builder(ctx).build()
// TODO(you): Initialize the Cronet image downloader

8. 实现 Cronet 回调

Cronet 的异步特性意味着要使用回调（即 UrlRequest.Callback 的实例）来控制响应处理。在本部分中，您将实现一个辅助回调，用于将整个响应读取到内存中。

创建一个名为 ReadToMemoryCronetCallback 的新抽象类，使其扩展 UrlRequest.Callback，并让 Android Studio 自动生成方法桩。您创建的新类应该类似于以下代码段：

abstract class ReadToMemoryCronetCallback : UrlRequest.Callback() {
   override fun onRedirectReceived(
       request: UrlRequest,
       info: UrlResponseInfo,
       newLocationUrl: String?
   ) {
       TODO("Not yet implemented")
   }

   override fun onSucceeded(request: UrlRequest, info: UrlResponseInfo) {
       TODO("Not yet implemented")
   }

   override fun onFailed(request: UrlRequest, info: UrlResponseInfo?, error: CronetException) {
       TODO("Not yet implemented")
   }

   override fun onResponseStarted(request: UrlRequest, info: UrlResponseInfo) {
       TODO("Not yet implemented")
   }

   override fun onReadCompleted(
       request: UrlRequest,
       info: UrlResponseInfo,
       byteBuffer: ByteBuffer
   ) {
       TODO("Not yet implemented")
   }
}

onRedirectReceived、onSucceeded 和 onFailed 方法均一目了然，因此我们暂不详细介绍，而要重点介绍 onResponseStarted 和 onReadCompleted。

在 Cronet 发送请求并收到所有响应标头之后，但未开始读取正文之时，系统会调用 onResponseStarted。与其他一些库（如 Volley）不同，Cronet 并不会自动读取整个正文。因此，请使用 UrlRequest.read() 将正文的下一个区块读取到您提供的缓冲区中。当 Cronet 完成响应正文区块的读取后，会调用 onReadCompleted 方法。此过程会重复执行，直到读取完所有数据。

让我们开始实现读取周期。首先，实例化一个新的字节数组输出流以及使用该输出流的通道。我们将用该通道作为响应正文的接收器。

private val bytesReceived = ByteArrayOutputStream()
private val receiveChannel = Channels.newChannel(bytesReceived)

接下来，实现 onReadCompleted 方法，将字节缓冲区内的数据复制到接收器中，然后调用下一次读取操作。

// The byte buffer we're getting in the callback hasn't been flipped for reading,
// so flip it so we can read the content.
byteBuffer.flip()
receiveChannel.write(byteBuffer)

// Reset the buffer to prepare it for the next read
byteBuffer.clear()

// Continue reading the request
request.read(byteBuffer)

如要完成正文读取循环，请通过 onResponseStarted 回调方法调用初始读取操作。请注意，您需要为 Cronet 使用直接字节缓冲区。在此 Codelab 的场景中，对缓冲区容量没有多大要求，不过对于大多数生产用例来说，默认的适宜容量为 16 KiB。

request.read(ByteBuffer.allocateDirect(BYTE_BUFFER_CAPACITY_BYTES))

现在，让我们完成本课程的其余部分。重定向与本课程的学习内容关系不大，所以就像处理网络浏览器的重定向一样，按常规方法实现即可。

override fun onRedirectReceived(
   request: UrlRequest, info: UrlResponseInfo?, newLocationUrl: String?
) {
   request.followRedirect()
}

最后，我们需要处理 onSucceeded 和 onFailed 方法。onFailed 与您想为辅助回调的使用方提供的签名一致，因此您可以删除定义并让扩展类覆盖该方法。onSucceeded 应将正文作为字节数组传递给下游。添加一种新的抽象方法，将正文放在签名中。

abstract fun onSucceeded(
   request: UrlRequest, info: UrlResponseInfo, bodyBytes: ByteArray)

然后，确保在请求成功完成时正确调用新的 onSucceeded 方法。

final override fun onSucceeded(request: UrlRequest, info: UrlResponseInfo) {
   val bodyBytes = bytesReceived.toByteArray()
   onSucceeded(request, info, bodyBytes)
}

太棒了，您已经学会如何实现 Cronet 回调！

9. 实现图片下载器

我们使用上一部分中创建的回调来实现基于 Cronet 的图片下载器。

创建一个名为 CronetImageDownloader 的新类，实现 ImageDownloader 接口并接受 CronetEngine 作为其构造函数参数。

class CronetImageDownloader(val engine: CronetEngine) : ImageDownloader {
   override suspend fun downloadImage(url: String): ImageDownloaderResult {
       TODO("Not yet implemented")
   }
}

如要实现 downloadImage 方法，您需要了解如何创建 Cronet 请求。很简单，只需调用 CronetEngine 的 newUrlRequestBuilder() 方法即可。此方法接受网址、回调类的实例以及运行回调方法的执行器。

val request = engine.newUrlRequestBuilder(url, callback, executor)

我们可通过 downloadImage 参数知悉该网址。对于执行器，我们将创建一个实例级字段。

private val executor = Executors.newSingleThreadExecutor()

最后，我们通过上一部分中完成的辅助回调实现来实现 callback。我们在此不详细介绍其实现细节了，因为它在更大程度上属于 Kotlin 协程主题。您可以将 cont.resume 视为 downloadImage 方法中的 return。

综上，downloadImage 实现应与以下代码段类似。

override suspend fun downloadImage(url: String): ImageDownloaderResult {
   val startNanoTime = System.nanoTime()
   return suspendCoroutine {
       cont ->
       val request = engine.newUrlRequestBuilder(url, object: ReadToMemoryCronetCallback() {
       override fun onSucceeded(
           request: UrlRequest,
           info: UrlResponseInfo,
           bodyBytes: ByteArray) {
           cont.resume(ImageDownloaderResult(
               successful = true,
               blob = bodyBytes,
               latency = Duration.ofNanos(System.nanoTime() - startNanoTime),
               wasCached = info.wasCached(),
               downloaderRef = this@CronetImageDownloader))
       }

       override fun onFailed(
           request: UrlRequest,
           info: UrlResponseInfo,
           error: CronetException
       ) {
           Log.w(LOGGER_TAG, "Cronet download failed!", error)
           cont.resume(ImageDownloaderResult(
               successful = false,
               blob = ByteArray(0),
               latency = Duration.ZERO,
               wasCached = info.wasCached(),
               downloaderRef = this@CronetImageDownloader))
       }
   }, executor)
       request.build().start()
   }
}

10. 最终连接

我们返回到 MainDisplay 可组合项，并使用我们刚刚创建的图片下载器处理最后一个 TODO。

imageDownloader = CronetImageDownloader(cronetEngine)

大功告成！试试运行该应用吧。您应该会看到您的请求通过 Cronet 图片下载器来路由。

11. 自定义

您可以在请求级别和引擎级别自定义请求行为。我们以缓存为例演示相应操作，但还有许多其他选择。如需了解详情，请参阅 UrlRequest.Builder 和 CronetEngine.Builder 文档。

如要在引擎级别启用缓存，请使用构建器的 enableHttpCache 方法。在下面的示例中，我们使用内存中的缓存。如需了解其他可用选项，请参阅文档。然后，创建 Cronet 引擎将变为：

val cronetEngine = CronetEngine.Builder(ctx)
   .enableHttpCache(CronetEngine.Builder.HTTP_CACHE_IN_MEMORY, 10 * 1024 * 1024)
   .build()

运行应用并添加一些图片。对于重复添加的图片，延迟时间明显较短，界面提示系统已缓存这些图片。

此功能可按请求进行替换。我们在 Cronet 下载器中稍作自定义，为“Sun”（太阳）图片（网址列表中的第一个）停用缓存。

if (url == CronetCodelabConstants.URLS[0]) {
   request.disableCache()
}

request.build().start()

现在，再次运行该应用。您会发现太阳图片没有缓存。

12. 总结

恭喜，您已完成了本 Codelab 的学习！在此过程中，您学习了关于如何使用 Cronet 的基础知识。

如需详细了解 Cronet，请查看开发者指南和源代码。此外，您可以订阅 Android 开发者博客，抢先了解 Cronet 以及 Android 的一般资讯。