区域

目录 keyboard_arrow_down keyboard_arrow_up

异步动态范围
区域基础
处理未捕获的错误
- 示例：错误不能跨越进入错误区域
- 示例：错误不能离开错误区域
在 Stream 中使用区域
- 示例：在 runZonedGuarded() 中使用 Stream
存储区域本地值
- 示例：使用区域本地值进行调试日志记录
覆盖功能
总结
- 更多资源
- 更多示例

more_horiz

本文讨论了 dart:async 库中与区域相关的 API，重点介绍了顶级的 runZoned() 和 runZonedGuarded() 函数。在阅读本文之前，请回顾 Future 和错误处理中介绍的技术。

区域使得以下任务成为可能

保护您的应用免受未捕获异常导致退出的影响。例如，一个简单的 HTTP 服务器可能使用以下异步代码
dart
```
runZonedGuarded(() {
  HttpServer.bind('0.0.0.0', port).then((server) {
    server.listen(staticFiles.serveRequest);
  });
},
(error, stackTrace) => print('Oh noes! $error $stackTrace'));
```
在区域中运行 HTTP 服务器，可以使应用在服务器的异步代码中出现未捕获的（但非致命的）错误时继续运行。
将数据（称为区域本地值）与各个区域关联起来。
在部分或全部代码中，覆盖一组有限的方法，例如 print() 和 scheduleMicrotask()。
每次代码进入或离开区域时执行一个操作。此类操作可能包括启动或停止计时器，或保存堆栈跟踪。

您可能在其他语言中遇到过类似于区域的概念。Node.js 中的 Domains 是 Dart 区域的灵感来源。Java 的线程本地存储（thread-local storage）也有一些相似之处。最接近的是 Brian Ford 的 Dart 区域的 JavaScript 移植版本 zone.js，他在这个视频中对此进行了描述。

区域代表调用的异步动态范围。它是作为调用一部分执行的计算，并且是该代码间接注册的异步回调。

例如，在 HTTP 服务器示例中，bind()、then() 以及 then() 的回调都在同一个区域中执行——这个区域是使用 runZoned() 创建的。

在下一个示例中，代码在 3 个不同的区域中执行：区域 #1（根区域）、区域 #2 和区域 #3。

import 'dart:async';

main() {
  foo();
  var future;
  runZoned(() {          // Starts a new child zone (zone #2).
    future = new Future(bar).then(baz);
  });
  future.then(qux);
}

foo() => ...foo-body...  // Executed twice (once each in two zones).
bar() => ...bar-body...
baz(x) => runZoned(() => foo()); // New child zone (zone #3).
qux(x) => ...qux-body...

下图显示了代码的执行顺序，以及代码在哪个区域中执行。

illustration of program execution

每次调用 runZoned() 都会创建一个新区域并在该区域中执行代码。当这段代码调度一个任务（例如调用 baz()）时，该任务将在它被调度的区域中执行。例如，对 qux() 的调用（main() 的最后一行）在区域 #1（根区域）中运行，尽管它附加到一个本身在区域 #2 中运行的 Future 上。

子区域不会完全取代其父区域。相反，新区域嵌套在其周围的区域内部。例如，区域 #2 包含区域 #3，而区域 #1（根区域）同时包含区域 #2 和区域 #3。

所有 Dart 代码都在根区域中执行。代码也可能在其他嵌套的子区域中执行，但至少它始终在根区域中运行。

区域能够捕获和处理未捕获的错误。

未捕获的错误通常是因为代码使用 throw 抛出异常而没有相应的 catch 语句来处理。未捕获的错误也可能在 async 函数中出现，当 Future 以错误结果完成，但缺少相应的 await 来处理该错误时。

未捕获的错误会报告给当前未能捕获它的区域。默认情况下，区域在响应未捕获错误时会使程序崩溃。您可以为新区域安装自定义的未捕获错误处理程序，以按照您喜欢的方式拦截和处理未捕获的错误。

要引入一个带有未捕获错误处理程序的新区域，请使用 runZoneGuarded 方法。它的 onError 回调将成为新区域的未捕获错误处理程序。此回调处理调用抛出的任何同步错误。

dartrunZonedGuarded(() {
  Timer.run(() { throw 'Would normally kill the program'; });
}, (error, stackTrace) {
  print('Uncaught error: $error');
});

其他用于未捕获错误处理的区域 API 包括 Zone.fork、Zone.runGuarded 和 ZoneSpecification.uncaughtErrorHandler。

前面的代码有一个异步回调（通过 Timer.run()）抛出异常。通常，这个异常将是一个未处理的错误并到达顶层（在独立的 Dart 可执行文件中，这将终止正在运行的进程）。然而，使用区域错误处理程序，错误被传递给错误处理程序，而不会关闭程序。

try-catch 和区域错误处理程序之间的一个显著区别是，区域在发生未捕获错误后会继续执行。如果区域内安排了其他异步回调，它们仍然会执行。因此，区域错误处理程序可能会被多次调用。

任何带有未捕获错误处理程序的区域都被称为错误区域。错误区域可以处理源自该区域后代中的错误。一个简单的规则决定了在 Future 转换序列（使用 then() 或 catchError()）中错误在哪里处理：Future 链上的错误永远不会跨越错误区域的边界。

如果错误到达错误区域边界，则在该点被视为未处理的错误。

在以下示例中，第一行抛出的错误不能跨越进入错误区域。

dartvar f = new Future.error(499);
f = f.whenComplete(() { print('Outside of zones'); });
runZoned(() {
  f = f.whenComplete(() { print('Inside non-error zone'); });
});
runZonedGuarded(() {
  f = f.whenComplete(() { print('Inside error zone (not called)'); });
}, (error) { print(error); });

如果您运行该示例，将看到以下输出

Outside of zones
Inside non-error zone
Uncaught Error: 499
Unhandled exception:
499
...stack trace...

如果您移除对 runZoned() 或对 runZonedGuarded() 的调用，您将看到以下输出

Outside of zones
Inside non-error zone
Inside error zone (not called)
Uncaught Error: 499
Unhandled exception:
499
...stack trace...

请注意，移除区域或错误区域会使错误进一步传播。

出现堆栈跟踪是因为错误发生在错误区域之外。如果您在整个代码片段周围添加一个错误区域，则可以避免出现堆栈跟踪。

如前述代码所示，错误不能跨越进入错误区域。同样，错误也不能跨越离开错误区域。考虑以下示例

dartvar completer = new Completer();
var future = completer.future.then((x) => x + 1);
var zoneFuture;
runZonedGuarded(() {
  zoneFuture = future.then((y) => throw 'Inside zone');
}, (error) { print('Caught: $error'); });

zoneFuture.catchError((e) { print('Never reached'); });
completer.complete(499);

尽管 Future 链以 catchError() 结尾，但异步错误不能离开错误区域。runZonedGuarded() 中的区域错误处理程序处理了该错误。因此，zoneFuture 永远不会完成——既不会带有值，也不会带有错误。

区域和 Stream 的规则比 Future 更简单

此规则遵循 Stream 在被监听之前不应产生副作用的指导原则。同步代码中的类似情况是 Iterable 的行为，它们在您请求值之前不会被评估。

以下示例设置了一个带有回调的 Stream，然后在新的区域中使用 runZonedGuarded() 执行该 Stream

dartvar stream = new File('stream.dart').openRead()
    .map((x) => throw 'Callback throws');

runZonedGuarded(() { stream.listen(print); },
         (e) { print('Caught error: $e'); });

runZonedGuarded() 中的错误处理程序捕获回调抛出的错误。以下是输出结果

Caught error: Callback throws

如输出所示，回调与监听区域关联，而不是与调用 map() 的区域关联。

如果您曾经想使用静态变量，但由于多个并发运行的计算相互干扰而无法实现，请考虑使用区域本地值。您可以添加区域本地值来帮助调试。另一个用例是处理 HTTP 请求：您可以在区域本地值中存储用户 ID 及其授权令牌。

使用 runZoned() 的 zoneValues 参数在新创建的区域中存储值

dartrunZoned(() {
  print(Zone.current[#key]);
}, zoneValues: { #key: 499 });

要读取区域本地值，请使用区域的索引运算符和值的键：[key]。任何对象都可以用作键，只要它具有兼容的 operator == 和 hashCode 实现。通常，键是一个符号字面量：#identifier。

您不能更改键映射到的对象，但可以操作该对象。例如，以下代码将一个项添加到区域本地列表中

dartrunZoned(() {
  Zone.current[#key].add(499);
  print(Zone.current[#key]); // [499]
}, zoneValues: { #key: [] });

区域从其父区域继承区域本地值，因此添加嵌套区域不会意外丢失现有值。然而，嵌套区域可以屏蔽父区域的值。

假设您有两个文件 foo.txt 和 bar.txt，并且想打印它们的所有行。程序可能看起来像这样

dartimport 'dart:async';
import 'dart:convert';
import 'dart:io';

Future splitLinesStream(stream) {
  return stream
      .transform(ASCII.decoder)
      .transform(const LineSplitter())
      .toList();
}

Future splitLines(filename) {
  return splitLinesStream(new File(filename).openRead());
}
main() {
  Future.forEach(['foo.txt', 'bar.txt'],
                 (file) => splitLines(file)
                     .then((lines) { lines.forEach(print); }));
}

这个程序可以工作，但是现在假设您想知道每一行来自哪个文件，并且不能简单地向 splitLinesStream() 添加一个文件名参数。通过区域本地值，您可以将文件名添加到返回的字符串中（新行已突出显示）

dartimport 'dart:async';
import 'dart:convert';
import 'dart:io';

Future splitLinesStream(stream) {
  return stream
      .transform(ASCII.decoder)
      .transform(const LineSplitter())
      .map((line) => '${Zone.current[#filename]}: $line')
      .toList();
}

Future splitLines(filename) {
  return runZoned(() {
    return splitLinesStream(new File(filename).openRead());
  }, zoneValues: { #filename: filename });
}

main() {
  Future.forEach(['foo.txt', 'bar.txt'],
                 (file) => splitLines(file)
                     .then((lines) { lines.forEach(print); }));
}

请注意，新代码没有修改函数签名，也没有将文件名从 splitLines() 传递到 splitLinesStream()。相反，它使用区域本地值来实现一个类似于静态变量的功能，该功能在异步上下文中也能工作。

使用 runZoned() 的 zoneSpecification 参数来覆盖由区域管理的功能。该参数的值是一个 ZoneSpecification 对象，通过它可以覆盖以下任何功能

分叉子区域
在区域中注册和运行回调
调度微任务和计时器
处理未捕获的异步错误（runZonedGuarded() 是此功能的快捷方式）
打印

作为一个覆盖功能的简单示例，这里有一个方法可以静默区域内的所有打印输出

dartimport 'dart:async';

main() {
  runZoned(() {
    print('Will be ignored');
  }, zoneSpecification: new ZoneSpecification(
    print: (self, parent, zone, message) {
      // Ignore message.
    }));
}

在分叉区域内，print() 函数被指定的打印拦截器覆盖，该拦截器只是简单地丢弃消息。覆盖 print 是可能的，因为 print()（就像 scheduleMicrotask() 和 Timer 构造函数一样）使用当前区域（Zone.current）来执行其工作。

正如打印示例所示，拦截器会在 Zone 类对应方法定义的参数基础上增加三个参数。例如，Zone 的 print() 方法有一个参数：print(String line)。由 ZoneSpecification 定义的 print() 拦截器版本有四个参数：print(Zone self, ZoneDelegate parent, Zone zone, String line)。

这三个拦截器参数总是以相同的顺序出现，在其他任何参数之前。

self: 正在处理回调的区域。
parent: 表示父区域的 ZoneDelegate。使用它将操作转发给父级。
zone: 操作源自的区域。有些操作需要知道该操作是在哪个区域上调用的。例如，zone.fork(specification) 必须创建新区域作为 zone 的子区域。再举一个例子，即使您将 scheduleMicrotask() 委托给另一个区域，执行微任务的必须是原始的 zone。

当拦截器将方法委托给父级时，父级 (ZoneDelegate) 版本的方法只多一个参数：zone，即原始调用源自的区域。例如，ZoneDelegate 上 print() 方法的签名是 print(Zone zone, String line)。

以下是另一个可拦截方法 scheduleMicrotask() 的参数示例

以下是一个示例，展示如何委托给父区域

dartimport 'dart:async';

main() {
  runZoned(() {
    var currentZone = Zone.current;
    scheduleMicrotask(() {
      print(identical(currentZone, Zone.current));  // prints true.
    });
  }, zoneSpecification: new ZoneSpecification(
    scheduleMicrotask: (self, parent, zone, task) {
      print('scheduleMicrotask has been called inside the zone');
      // The origin `zone` needs to be passed to the parent so that
      // the task can be executed in it.
      parent.scheduleMicrotask(zone, task);
    }));
}

假设您想知道某些异步代码花费了多少执行时间。您可以通过将代码放入一个区域来实现：每次进入该区域时启动一个计时器，并在离开该区域时停止计时器。

为 ZoneSpecification 提供 run* 参数可以让您指定区域执行的代码。

run* 参数——run、runUnary 和 runBinary——指定了每次区域被要求执行代码时运行的代码。这些参数分别适用于零参数、一个参数和两个参数的回调。run 参数也适用于调用 runZoned() 后立即执行的初始同步代码。

以下是使用 run* 进行代码性能分析的示例

dartfinal total = new Stopwatch();
final user = new Stopwatch();

final specification = new ZoneSpecification(
  run: (self, parent, zone, f) {
    user.start();
    try { return parent.run(zone, f); } finally { user.stop(); }
  },
  runUnary: (self, parent, zone, f, arg) {
    user.start();
    try { return parent.runUnary(zone, f, arg); } finally { user.stop(); }
  },
  runBinary: (self, parent, zone, f, arg1, arg2) {
    user.start();
    try {
      return parent.runBinary(zone, f, arg1, arg2);
    } finally {
      user.stop();
    }
  });

runZoned(() {
  total.start();
  // ... Code that runs synchronously...
  // ... Then code that runs asynchronously ...
    .then((...) {
      print(total.elapsedMilliseconds);
      print(user.elapsedMilliseconds);
    });
}, zoneSpecification: specification);

在这段代码中，每个 run* 的覆盖实现只是启动用户计时器，执行指定函数，然后停止用户计时器。

为 ZoneSpecification 提供 register*Callback 参数来包装或修改回调代码——即在区域中异步执行的代码。与 run* 参数类似，register*Callback 参数也有三种形式：registerCallback（用于无参数回调）、registerUnaryCallback（用于一个参数回调）和 registerBinaryCallback（用于两个参数回调）。

以下是一个示例，它使得区域在代码进入异步上下文之前保存堆栈跟踪。

dartimport 'dart:async';

get currentStackTrace {
  try {
    throw 0;
  } catch(_, st) {
    return st;
  }
}

var lastStackTrace = null;

bar() => throw "in bar";
foo() => new Future(bar);

main() {
  final specification = new ZoneSpecification(
    registerCallback: (self, parent, zone, f) {
      var stackTrace = currentStackTrace;
      return parent.registerCallback(zone, () {
        lastStackTrace = stackTrace;
        return f();
      });
    },
    registerUnaryCallback: (self, parent, zone, f) {
      var stackTrace = currentStackTrace;
      return parent.registerUnaryCallback(zone, (arg) {
        lastStackTrace = stackTrace;
        return f(arg);
      });
    },
    registerBinaryCallback: (self, parent, zone, f) {
      var stackTrace = currentStackTrace;
      return parent.registerBinaryCallback(zone, (arg1, arg2) {
        lastStackTrace = stackTrace;
        return f(arg1, arg2);
      });
    },
    handleUncaughtError: (self, parent, zone, error, stackTrace) {
      if (lastStackTrace != null) print("last stack: $lastStackTrace");
      return parent.handleUncaughtError(zone, error, stackTrace);
    });

  runZoned(() {
    foo();
  }, zoneSpecification: specification);
}

继续运行该示例。您将看到一个“上次堆栈”跟踪（lastStackTrace），其中包含 foo()，因为 foo() 是同步调用的。下一个堆栈跟踪（stackTrace）来自异步上下文，它知道 bar() 但不知道 foo()。

即使您正在实现一个异步 API，您也可能完全不需要处理区域。例如，尽管您可能期望 dart:io 库会跟踪当前区域，但它依赖于 dart:async 类（如 Future 和 Stream）的区域处理。

如果您确实需要显式处理区域，那么您需要注册所有异步回调，并确保每个回调都在其注册的区域中被调用。Zone 的 bind*Callback 辅助方法使这项任务变得更容易。它们是 register*Callback 和 run* 的快捷方式，确保每个回调在该区域中注册并运行。

如果您需要比 bind*Callback 提供更多的控制，那么您需要使用 register*Callback 和 run*。您可能还想使用 Zone 的 run*Guarded 方法，这些方法将调用包装在一个 try-catch 中，并在发生错误时调用 uncaughtErrorHandler。

区域对于保护您的代码免受异步代码中未捕获异常的影响很有用，但它们可以做更多的事情。您可以将数据与区域关联，并且可以覆盖核心功能，例如打印和任务调度。区域能够更好地进行调试，并提供可以用于性能分析等功能的钩子。

区域相关的 API 文档: 阅读 runZoned()、runZonedGuarded()、Zone、ZoneDelegate 和 ZoneSpecification 的文档。
stack_trace: 使用 stack_trace 库的 Chain 类，您可以为异步执行的代码获取更好的堆栈跟踪。有关更多信息，请访问 pub.dev 网站上的stack_trace 包。

这里有一些更复杂的区域使用示例。

task_interceptor 示例: task_interceptor.dart 中的模拟区域拦截 scheduleMicrotask、createTimer 和 createPeriodicTimer，以模拟 Dart 原语的行为，而不让出给事件循环。
stack_trace 包的源代码: stack_trace 包使用区域来形成异步代码调试的堆栈跟踪链。使用的区域特性包括错误处理、区域本地值和回调。您可以在stack_trace GitHub 项目中找到 stack_trace 的源代码。
dart:async 的源代码: 这两个 SDK 库实现了包含异步回调的 API，因此它们处理区域。您可以在Dart GitHub 项目的 sdk/lib 目录下浏览或下载它们的源代码。

感谢 Anders Johnsen 和 Lasse Reichstein Nielsen 对本文的审阅。

此页面内容对您有帮助吗？

感谢您的反馈！

提供详细信息

感谢您的反馈！请告诉我们如何改进。

提供详细信息

除非另有说明，本网站的文档反映 Dart 3.8.1 版本。页面上次更新时间为 2014-03-03。查看源代码或报告问题。

此页面上的部分内容可能已过时。

区域

异步动态范围

区域基础

处理未捕获的错误

示例：错误不能跨越进入错误区域

示例：错误不能离开错误区域

在 Stream 中使用区域

示例：在 `runZonedGuarded()` 中使用 Stream

存储区域本地值

示例：使用区域本地值进行调试日志记录

覆盖功能

示例：覆盖 print

拦截器和委托的参数

示例：委托给父区域

示例：在进入和离开区域时执行代码

示例：处理回调

实现异步回调

总结

更多资源

更多示例