Flutter Map 网络瓦片提供者客户端管理问题分析

问题概述

在 Flutter Map 项目中，NetworkTileProvider 和 CancellableNetworkTileProvider 这两个瓦片提供者类存在一个重要的资源管理问题：它们会无条件地关闭传入的 HTTP 客户端实例，即使这些客户端是由外部创建并可能在其他地方继续使用的。

问题详情

当前实现的问题

在现有实现中，无论 HTTP 客户端是由瓦片提供者内部创建还是外部传入，当瓦片提供者被销毁时，都会调用客户端的 close() 方法。这种行为会导致以下问题：

1. 当共享同一个客户端实例时，其他部分的网络请求会因客户端被意外关闭而失败
2. 开发者需要为每个瓦片提供者创建独立的客户端实例，增加了资源消耗
3. 不符合资源管理的常规做法，通常由创建者负责销毁

问题代码示例

@override
Future<void> dispose() async {
  if (_tilesInProgress.isNotEmpty) {
    await Future.wait(_tilesInProgress.values.map((c) => c.future));
  }
  // 无条件关闭客户端
  _httpClient.close();
  super.dispose();
}

解决方案

改进思路

正确的做法应该是：

1. 只关闭由瓦片提供者自身创建的客户端
2. 保留外部传入的客户端，由创建者管理其生命周期

具体实现

可以通过添加一个标志位来记录客户端来源：

class NetworkTileProvider extends TileProvider {
  NetworkTileProvider({
    super.headers,
    BaseClient? httpClient,
    this.silenceExceptions = false,
  })  : _closeClientOnDispose = (httpClient == null), // 记录客户端来源
        _httpClient = httpClient ?? RetryClient(Client());

  final bool silenceExceptions;
  final BaseClient _httpClient;
  final bool _closeClientOnDispose; // 新增标志位

  @override
  Future<void> dispose() async {
    if (_tilesInProgress.isNotEmpty) {
      await Future.wait(_tilesInProgress.values.map((c) => c.future));
    }

    if (_closeClientOnDispose) { // 仅关闭内部创建的客户端
      _httpClient.close();
    }

    super.dispose();
  }
}

影响范围

这个问题影响以下两个类：

1. NetworkTileProvider - 基础网络瓦片提供者
2. CancellableNetworkTileProvider - 可取消的网络瓦片提供者

最佳实践建议

1. 当需要共享 HTTP 客户端时，应该从外部创建并传入
2. 对于独立使用的瓦片提供者，可以不传入客户端，由提供者自行管理
3. 更新到修复后的版本后，可以安全地共享客户端实例

总结

这个问题的修复使得 Flutter Map 的资源管理更加合理，允许开发者更灵活地共享 HTTP 客户端资源，同时保持了自动资源回收的便利性。对于性能敏感的应用，共享客户端可以减少网络连接建立的开销，提升整体性能。