异步编程：Future、async 和 await

本教程教你如何使用 Future 以及 `async` 和 `await` 关键字编写异步代码。使用嵌入式 DartPad 编辑器，你可以通过运行示例代码和完成练习来测试你的知识。

要充分利用本教程，你应该具备以下条件

• 了解 基本的 Dart 语法。
• 有一些使用其他语言编写异步代码的经验。
• 已启用 `discarded_futures` 和 `unawaited_futures` 代码风格检查规则。

本教程涵盖以下内容

• 如何以及何时使用 `async` 和 `await` 关键字。
• 使用 `async` 和 `await` 如何影响执行顺序。
• 如何在 `async` 函数中使用 `try-catch` 表达式处理异步调用的错误。

完成本教程的预计时间：40-60 分钟。

本教程中的练习包含部分完成的代码片段。你可以使用 DartPad 通过完成代码并点击“运行”按钮来测试你的知识。**不要编辑 `main` 函数或以下的测试代码**。

如果需要帮助，请在每个练习后展开“提示”或“解答”下拉菜单。

异步操作允许你的程序在等待另一个操作完成时完成工作。以下是一些常见的异步操作

• 通过网络获取数据。
• 写入数据库。
• 从文件读取数据。

此类异步计算通常将其结果作为 `Future` 提供，或者如果结果有多个部分，则作为 `Stream` 提供。这些计算将异步性引入程序。为了适应这种初始的异步性，其他普通 Dart 函数也需要变成异步的。

为了与这些异步结果交互，你可以使用 `async` 和 `await` 关键字。大多数异步函数只是异步 Dart 函数，这些函数可能在更深层次上依赖于固有的异步计算。

以下示例显示了错误地使用异步函数（`fetchUserOrder()`）的方式。稍后你将使用 `async` 和 `await` 修复此示例。在运行此示例之前，尝试找出问题所在——你认为输出会是什么？

// This example shows how *not* to write asynchronous Dart code.

String createOrderMessage() {
  var order = fetchUserOrder();
  return 'Your order is: $order';
}

Future<String> fetchUserOrder() =>
    // Imagine that this function is more complex and slow.
    Future.delayed(
      const Duration(seconds: 2),
      () => 'Large Latte',
    );

void main() {
  print(createOrderMessage());
}

以下是此示例无法打印 `fetchUserOrder()` 最终产生的值的理由

• `fetchUserOrder()` 是一个异步函数，它会在延迟一段时间后提供一个描述用户订单的字符串：“Large Latte”。
• 要获取用户的订单，`createOrderMessage()` 应该调用 `fetchUserOrder()` 并等待它完成。因为 `createOrderMessage()` 不会等待 `fetchUserOrder()` 完成，所以 `createOrderMessage()` 无法获取 `fetchUserOrder()` 最终提供的字符串值。
• 相反，`createOrderMessage()` 获取了要执行的挂起工作的表示形式：一个未完成的 Future。你将在下一节中了解有关 Future 的更多信息。
• 由于 `createOrderMessage()` 无法获取描述用户订单的值，因此此示例无法将“Large Latte”打印到控制台，而是打印“Your order is: Instance of '_Future<String>'"。

在接下来的部分中，你将了解有关 Future 以及如何使用 Future（使用 `async` 和 `await`）的信息，以便能够编写必要的代码来使 `fetchUserOrder()` 将所需的值（“Large Latte”）打印到控制台。

Future（小写“f”）是 Future（大写“F”）类的实例。Future 表示异步操作的结果，并且可以具有两种状态：未完成或已完成。

当你调用异步函数时，它会返回一个未完成的 Future。该 Future 正在等待函数的异步操作完成或抛出错误。

如果异步操作成功，则 Future 会使用值完成。否则，它会使用错误完成。

类型为 `Future<T>` 的 Future 使用类型为 `T` 的值完成。例如，类型为 `Future<String>` 的 Future 会生成字符串值。如果 Future 没有生成可用的值，则 Future 的类型为 `Future<void>`。

如果函数执行的异步操作由于任何原因失败，则 Future 会使用错误完成。

在以下示例中，`fetchUserOrder()` 返回一个在打印到控制台后完成的 Future。因为它不返回值，所以 `fetchUserOrder()` 的类型为 `Future<void>`。在运行示例之前，尝试预测哪个会先打印：“Large Latte”还是“Fetching user order…”。

Future<void> fetchUserOrder() {
  // Imagine that this function is fetching user info from another service or database.
  return Future.delayed(const Duration(seconds: 2), () => print('Large Latte'));
}

void main() {
  fetchUserOrder();
  print('Fetching user order...');
}

在前面的示例中，即使 `fetchUserOrder()` 在第 8 行的 `print()` 调用之前执行，控制台也显示第 8 行（“Fetching user order…”）的输出，然后再显示 `fetchUserOrder()`（“Large Latte”）的输出。这是因为 `fetchUserOrder()` 在打印“Large Latte”之前会延迟。

运行以下示例以了解 Future 如何使用错误完成。稍后你将学习如何处理错误。

Future<void> fetchUserOrder() {
  // Imagine that this function is fetching user info but encounters a bug.
  return Future.delayed(
    const Duration(seconds: 2),
    () => throw Exception('Logout failed: user ID is invalid'),
  );
}

void main() {
  fetchUserOrder();
  print('Fetching user order...');
}

在此示例中，`fetchUserOrder()` 使用指示用户 ID 无效的错误完成。

您已经学习了期货及其完成方式，但如何使用异步函数的结果呢？在下一节中，您将学习如何使用async和await关键字获取结果。

async和await关键字提供了一种声明式的方式来定义异步函数并使用其结果。在使用async和await时，请记住以下两个基本准则

• 要定义一个异步函数，请在函数体之前添加async
• await关键字仅在async函数中有效。

以下是一个将main()从同步函数转换为异步函数的示例。

首先，在函数体之前添加async关键字

void main() async { ··· }

如果函数具有声明的返回类型，则将其更新为Future<T>，其中T是函数返回的值的类型。如果函数没有显式返回值，则返回类型为Future<void>

Future<void> main() async { ··· }

现在您已经有了一个async函数，您可以使用await关键字等待期货完成

print(await createOrderMessage());

如下面的两个示例所示，async和await关键字导致异步代码看起来非常像同步代码。唯一的区别在异步示例中突出显示，如果您的窗口足够宽，它将位于同步示例的右侧。

String createOrderMessage() {
  var order = fetchUserOrder();
  return 'Your order is: $order';
}

Future<String> fetchUserOrder() =>
    // Imagine that this function is
    // more complex and slow.
    Future.delayed(
      const Duration(seconds: 2),
      () => 'Large Latte',
    );

void main() {
  print('Fetching user order...');
  print(createOrderMessage());
}

Fetching user order...
Your order is: Instance of 'Future<String>'

如下面的两个示例所示，它像同步代码一样工作。

Future<String> createOrderMessage() async {
  var order = await fetchUserOrder();
  return 'Your order is: $order';
}

Future<String> fetchUserOrder() =>
    // Imagine that this function is
    // more complex and slow.
    Future.delayed(
      const Duration(seconds: 2),
      () => 'Large Latte',
    );

Future<void> main() async {
  print('Fetching user order...');
  print(await createOrderMessage());
}

Fetching user order...
Your order is: Large Latte

异步示例在三个方面有所不同

• createOrderMessage()的返回类型从String更改为Future<String>。
• async关键字出现在createOrderMessage()和main()的函数体之前。
• await关键字出现在调用异步函数fetchUserOrder()和createOrderMessage()之前。

一个async函数同步运行，直到第一个await关键字。这意味着在async函数体中，第一个await关键字之前的所有同步代码都会立即执行。

运行以下示例以查看async函数体内的执行过程。您认为输出是什么？

Future<void> printOrderMessage() async {
  print('Awaiting user order...');
  var order = await fetchUserOrder();
  print('Your order is: $order');
}

Future<String> fetchUserOrder() {
  // Imagine that this function is more complex and slow.
  return Future.delayed(const Duration(seconds: 4), () => 'Large Latte');
}

void main() async {
  countSeconds(4);
  await printOrderMessage();
}

// You can ignore this function - it's here to visualize delay time in this example.
void countSeconds(int s) {
  for (var i = 1; i <= s; i++) {
    Future.delayed(Duration(seconds: i), () => print(i));
  }
}

在运行前面示例中的代码后，尝试反转第 2 行和第 3 行

var order = await fetchUserOrder();
print('Awaiting user order...');

请注意，输出的时机发生了变化，现在print('Awaiting user order')出现在printOrderMessage()中第一个await关键字之后。

以下练习是一个失败的单元测试，其中包含部分完成的代码片段。您的任务是通过编写代码使测试通过来完成练习。您不需要实现main()。

要模拟异步操作，请调用以下为您提供的函数

在reportUserRole()函数中添加代码，使其执行以下操作

• 返回一个使用以下字符串完成的期货："User role: <user role>"
  • 注意：您必须使用fetchRole()返回的实际值；复制粘贴示例返回值将无法使测试通过。
  • 示例返回值："User role: tester"
• 通过调用提供的函数fetchRole()获取用户角色。

实现一个异步函数reportLogins()，使其执行以下操作

• 返回字符串"Total number of logins: <# of logins>"。
  • 注意：您必须使用fetchLoginAmount()返回的实际值；复制粘贴示例返回值将无法使测试通过。
  • reportLogins()的示例返回值："Total number of logins: 57"
• 通过调用提供的函数fetchLoginAmount()获取登录次数。

// Part 1
// Call the provided async function fetchRole()
// to return the user role.
Future<String> reportUserRole() async {
  // TODO: Implement the reportUserRole function here.
}

// Part 2
// TODO: Implement the reportLogins function here.
// Call the provided async function fetchLoginAmount()
// to return the number of times that the user has logged in.
reportLogins() {}

// The following functions those provided to you to simulate
// asynchronous operations that could take a while.

Future<String> fetchRole() => Future.delayed(_halfSecond, () => _role);
Future<int> fetchLoginAmount() => Future.delayed(_halfSecond, () => _logins);

// The following code is used to test and provide feedback on your solution.
// There is no need to read or modify it.

void main() async {
  print('Testing...');
  List<String> messages = [];
  const passed = 'PASSED';
  const testFailedMessage = 'Test failed for the function:';
  const typoMessage = 'Test failed! Check for typos in your return value';
  try {
    messages
      ..add(_makeReadable(
          testLabel: 'Part 1',
          testResult: await _asyncEquals(
            expected: 'User role: administrator',
            actual: await reportUserRole(),
            typoKeyword: _role,
          ),
          readableErrors: {
            typoMessage: typoMessage,
            'null':
                'Test failed! Did you forget to implement or return from reportUserRole?',
            'User role: Instance of \'Future<String>\'':
                '$testFailedMessage reportUserRole. Did you use the await keyword?',
            'User role: Instance of \'_Future<String>\'':
                '$testFailedMessage reportUserRole. Did you use the await keyword?',
            'User role:':
                '$testFailedMessage reportUserRole. Did you return a user role?',
            'User role: ':
                '$testFailedMessage reportUserRole. Did you return a user role?',
            'User role: tester':
                '$testFailedMessage reportUserRole. Did you invoke fetchRole to fetch the user\'s role?',
          }))
      ..add(_makeReadable(
          testLabel: 'Part 2',
          testResult: await _asyncEquals(
            expected: 'Total number of logins: 42',
            actual: await reportLogins(),
            typoKeyword: _logins.toString(),
          ),
          readableErrors: {
            typoMessage: typoMessage,
            'null':
                'Test failed! Did you forget to implement or return from reportLogins?',
            'Total number of logins: Instance of \'Future<int>\'':
                '$testFailedMessage reportLogins. Did you use the await keyword?',
            'Total number of logins: Instance of \'_Future<int>\'':
                '$testFailedMessage reportLogins. Did you use the await keyword?',
            'Total number of logins: ':
                '$testFailedMessage reportLogins. Did you return the number of logins?',
            'Total number of logins:':
                '$testFailedMessage reportLogins. Did you return the number of logins?',
            'Total number of logins: 57':
                '$testFailedMessage reportLogins. Did you invoke fetchLoginAmount to fetch the number of user logins?',
          }))
      ..removeWhere((m) => m.contains(passed))
      ..toList();

    if (messages.isEmpty) {
      print('Success. All tests passed!');
    } else {
      messages.forEach(print);
    }
  } on UnimplementedError {
    print(
        'Test failed! Did you forget to implement or return from reportUserRole?');
  } catch (e) {
    print('Tried to run solution, but received an exception: $e');
  }
}

const _role = 'administrator';
const _logins = 42;
const _halfSecond = Duration(milliseconds: 500);

// Test helpers.
String _makeReadable({
  required String testResult,
  required Map<String, String> readableErrors,
  required String testLabel,
}) {
  if (readableErrors.containsKey(testResult)) {
    var readable = readableErrors[testResult];
    return '$testLabel $readable';
  } else {
    return '$testLabel $testResult';
  }
}

// Assertions used in tests.
Future<String> _asyncEquals({
  required String expected,
  required dynamic actual,
  required String typoKeyword,
}) async {
  var strActual = actual is String ? actual : actual.toString();
  try {
    if (expected == actual) {
      return 'PASSED';
    } else if (strActual.contains(typoKeyword)) {
      return 'Test failed! Check for typos in your return value';
    } else {
      return strActual;
    }
  } catch (e) {
    return e.toString();
  }
}

Future<String> reportUserRole() async {
  final username = await fetchRole();
  return 'User role: $username';
}

Future<String> reportLogins() async {
  final logins = await fetchLoginAmount();
  return 'Total number of logins: $logins';
}

要在async函数中处理错误，请使用try-catch

try {
  print('Awaiting user order...');
  var order = await fetchUserOrder();
} catch (err) {
  print('Caught error: $err');
}

在async函数内，您可以像在同步代码中一样编写try-catch语句。

运行以下示例以查看如何处理异步函数的错误。您认为输出是什么？

Future<void> printOrderMessage() async {
  try {
    print('Awaiting user order...');
    var order = await fetchUserOrder();
    print(order);
  } catch (err) {
    print('Caught error: $err');
  }
}

Future<String> fetchUserOrder() {
  // Imagine that this function is more complex.
  var str = Future.delayed(
      const Duration(seconds: 4),
      () => throw 'Cannot locate user order');
  return str;
}

void main() async {
  await printOrderMessage();
}

以下练习提供了使用上一节中描述的方法处理异步代码错误的实践。要模拟异步操作，您的代码将调用以下为您提供的函数

使用async和await实现一个异步changeUsername()函数，使其执行以下操作

• 调用提供的异步函数fetchNewUsername()并返回其结果。
  • changeUsername()的示例返回值："jane_smith_92"
• 捕获发生的任何错误并返回错误的字符串值。
  • 您可以使用toString()方法将异常和错误都转换为字符串。

// TODO: Implement changeUsername here.
changeUsername() {}

// The following function is provided to you to simulate
// an asynchronous operation that could take a while and
// potentially throw an exception.

Future<String> fetchNewUsername() =>
    Future.delayed(const Duration(milliseconds: 500), () => throw UserError());

class UserError implements Exception {
  @override
  String toString() => 'New username is invalid';
}

// The following code is used to test and provide feedback on your solution.
// There is no need to read or modify it.

void main() async {
  final List<String> messages = [];
  const typoMessage = 'Test failed! Check for typos in your return value';

  print('Testing...');
  try {
    messages
      ..add(_makeReadable(
          testLabel: '',
          testResult: await _asyncDidCatchException(changeUsername),
          readableErrors: {
            typoMessage: typoMessage,
            _noCatch:
                'Did you remember to call fetchNewUsername within a try/catch block?',
          }))
      ..add(_makeReadable(
          testLabel: '',
          testResult: await _asyncErrorEquals(changeUsername),
          readableErrors: {
            typoMessage: typoMessage,
            _noCatch:
                'Did you remember to call fetchNewUsername within a try/catch block?',
          }))
      ..removeWhere((m) => m.contains(_passed))
      ..toList();

    if (messages.isEmpty) {
      print('Success. All tests passed!');
    } else {
      messages.forEach(print);
    }
  } catch (e) {
    print('Tried to run solution, but received an exception: $e');
  }
}

// Test helpers.
String _makeReadable({
  required String testResult,
  required Map<String, String> readableErrors,
  required String testLabel,
}) {
  if (readableErrors.containsKey(testResult)) {
    final readable = readableErrors[testResult];
    return '$testLabel $readable';
  } else {
    return '$testLabel $testResult';
  }
}

Future<String> _asyncErrorEquals(Function fn) async {
  final result = await fn();
  if (result == UserError().toString()) {
    return _passed;
  } else {
    return 'Test failed! Did you stringify and return the caught error?';
  }
}

Future<String> _asyncDidCatchException(Function fn) async {
  var caught = true;
  try {
    await fn();
  } on UserError catch (_) {
    caught = false;
  }

  if (caught == false) {
    return _noCatch;
  } else {
    return _passed;
  }
}

const _passed = 'PASSED';
const _noCatch = 'NO_CATCH';

Future<String> changeUsername() async {
  try {
    return await fetchNewUsername();
  } catch (err) {
    return err.toString();
  }
}

现在是时候在一个最后的练习中实践您所学到的知识了。为了模拟异步操作，本练习提供了异步函数fetchUsername()和logoutUser()

编写以下内容

• 编写一个函数addHello()，它接受一个String参数。
• addHello()返回其String参数，并在其前面加上'Hello '。
  示例：addHello('Jon')返回'Hello Jon'。

• 编写一个函数greetUser()，它不接受任何参数。
• 要获取用户名，greetUser()会调用提供的异步函数fetchUsername()。
• greetUser()通过调用addHello()并传递用户名来为用户创建问候语，并返回结果。
  示例：如果fetchUsername()返回'Jenny'，则greetUser()返回'Hello Jenny'。

• 编写一个函数sayGoodbye()，它执行以下操作
  • 不接受任何参数。
  • 捕获任何错误。
  • 调用提供的异步函数logoutUser()。
• 如果logoutUser()失败，sayGoodbye()返回任何您喜欢的字符串。
• 如果logoutUser()成功，sayGoodbye()返回字符串'<result> Thanks, see you next time'，其中<result>是调用logoutUser()返回的字符串值。

// Part 1
addHello(String user) {}

// Part 2
// Call the provided async function fetchUsername()
// to return the username.
greetUser() {}

// Part 3
// Call the provided async function logoutUser()
// to log out the user.
sayGoodbye() {}

// The following functions are provided to you to use in your solutions.

Future<String> fetchUsername() => Future.delayed(_halfSecond, () => 'Jean');

Future<String> logoutUser() => Future.delayed(_halfSecond, _failOnce);

// The following code is used to test and provide feedback on your solution.
// There is no need to read or modify it.

void main() async {
  const didNotImplement =
      'Test failed! Did you forget to implement or return from';

  final List<String> messages = [];

  print('Testing...');
  try {
    messages
      ..add(_makeReadable(
          testLabel: 'Part 1',
          testResult: await _asyncEquals(
              expected: 'Hello Jerry',
              actual: addHello('Jerry'),
              typoKeyword: 'Jerry'),
          readableErrors: {
            _typoMessage: _typoMessage,
            'null': '$didNotImplement addHello?',
            'Hello Instance of \'Future<String>\'':
                'Looks like you forgot to use the \'await\' keyword!',
            'Hello Instance of \'_Future<String>\'':
                'Looks like you forgot to use the \'await\' keyword!',
          }))
      ..add(_makeReadable(
          testLabel: 'Part 2',
          testResult: await _asyncEquals(
              expected: 'Hello Jean',
              actual: await greetUser(),
              typoKeyword: 'Jean'),
          readableErrors: {
            _typoMessage: _typoMessage,
            'null': '$didNotImplement greetUser?',
            'HelloJean':
                'Looks like you forgot the space between \'Hello\' and \'Jean\'',
            'Hello Instance of \'Future<String>\'':
                'Looks like you forgot to use the \'await\' keyword!',
            'Hello Instance of \'_Future<String>\'':
                'Looks like you forgot to use the \'await\' keyword!',
            '{Closure: (String) => dynamic from Function \'addHello\': static.(await fetchUsername())}':
                'Did you place the \'\$\' character correctly?',
            '{Closure \'addHello\'(await fetchUsername())}':
                'Did you place the \'\$\' character correctly?',
          }))
      ..add(_makeReadable(
          testLabel: 'Part 3',
          testResult: await _asyncDidCatchException(sayGoodbye),
          readableErrors: {
            _typoMessage:
                '$_typoMessage. Did you add the text \'Thanks, see you next time\'?',
            'null': '$didNotImplement sayGoodbye?',
            _noCatch:
                'Did you remember to call logoutUser within a try/catch block?',
            'Instance of \'Future<String>\' Thanks, see you next time':
                'Did you remember to use the \'await\' keyword in the sayGoodbye function?',
            'Instance of \'_Future<String>\' Thanks, see you next time':
                'Did you remember to use the \'await\' keyword in the sayGoodbye function?',
          }))
      ..add(_makeReadable(
          testLabel: 'Part 3',
          testResult: await _asyncEquals(
              expected: 'Success! Thanks, see you next time',
              actual: await sayGoodbye(),
              typoKeyword: 'Success'),
          readableErrors: {
            _typoMessage:
                '$_typoMessage. Did you add the text \'Thanks, see you next time\'?',
            'null': '$didNotImplement sayGoodbye?',
            _noCatch:
                'Did you remember to call logoutUser within a try/catch block?',
            'Instance of \'Future<String>\' Thanks, see you next time':
                'Did you remember to use the \'await\' keyword in the sayGoodbye function?',
            'Instance of \'_Future<String>\' Thanks, see you next time':
                'Did you remember to use the \'await\' keyword in the sayGoodbye function?',
            'Instance of \'_Exception\'':
                'CAUGHT Did you remember to return a string?',
          }))
      ..removeWhere((m) => m.contains(_passed))
      ..toList();

    if (messages.isEmpty) {
      print('Success. All tests passed!');
    } else {
      messages.forEach(print);
    }
  } catch (e) {
    print('Tried to run solution, but received an exception: $e');
  }
}

// Test helpers.
String _makeReadable({
  required String testResult,
  required Map<String, String> readableErrors,
  required String testLabel,
}) {
  String? readable;
  if (readableErrors.containsKey(testResult)) {
    readable = readableErrors[testResult];
    return '$testLabel $readable';
  } else if ((testResult != _passed) && (testResult.length < 18)) {
    readable = _typoMessage;
    return '$testLabel $readable';
  } else {
    return '$testLabel $testResult';
  }
}

Future<String> _asyncEquals({
  required String expected,
  required dynamic actual,
  required String typoKeyword,
}) async {
  final strActual = actual is String ? actual : actual.toString();
  try {
    if (expected == actual) {
      return _passed;
    } else if (strActual.contains(typoKeyword)) {
      return _typoMessage;
    } else {
      return strActual;
    }
  } catch (e) {
    return e.toString();
  }
}

Future<String> _asyncDidCatchException(Function fn) async {
  var caught = true;
  try {
    await fn();
  } on Exception catch (_) {
    caught = false;
  }

  if (caught == true) {
    return _passed;
  } else {
    return _noCatch;
  }
}

const _typoMessage = 'Test failed! Check for typos in your return value';
const _passed = 'PASSED';
const _noCatch = 'NO_CATCH';
const _halfSecond = Duration(milliseconds: 500);

String _failOnce() {
  if (_logoutSucceeds) {
    return 'Success!';
  } else {
    _logoutSucceeds = true;
    throw Exception('Logout failed');
  }
}

bool _logoutSucceeds = false;

String addHello(String user) => 'Hello $user';

Future<String> greetUser() async {
  final username = await fetchUsername();
  return addHello(username);
}

Future<String> sayGoodbye() async {
  try {
    final result = await logoutUser();
    return '$result Thanks, see you next time';
  } catch (e) {
    return 'Failed to logout user: $e';
  }
}

为了捕获在使用异步和期货时出现的常见错误，请启用以下 lint

• discarded_futures
• unawaited_futures

恭喜您完成了本教程！如果您想了解更多信息，以下是一些下一步去哪里建议

• 使用DartPad。
• 尝试另一个教程。
• 了解有关 Dart 中的期货和异步代码的更多信息
  • 流教程：了解如何处理一系列异步事件。
  • Dart 中的并发：了解并学习如何在 Dart 中实现并发。
  • 异步支持：深入了解 Dart 语言和库对异步编码的支持。
  • 来自 Google 的 Dart 视频：观看一个或多个关于异步编码的视频。
• 获取Dart SDK！

除非另有说明，否则本网站上的文档反映了 Dart 3.5.3。页面上次更新于 2024-08-04。 查看源代码 或 报告问题.