flutter-concurrency

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Flutter Concurrency and Data Management

Flutter 并发与数据管理

Goal

目标

Implements advanced Flutter data handling, including background JSON serialization using Isolates, asynchronous state management, and platform-aware concurrency to ensure jank-free 60fps+ UI rendering. Assumes a standard Flutter environment (Dart 2.19+) with access to
dart:convert
,
dart:isolate
, and standard state management paradigms.
实现高级Flutter数据处理能力,包括使用Isolate进行后台JSON序列化、异步状态管理,以及适配平台的并发机制,确保无卡顿的60fps+ UI渲染。本文假设你使用标准Flutter环境(Dart 2.19及以上版本),可使用
dart:convert
dart:isolate
以及标准状态管理范式。

Decision Logic

决策逻辑

Use the following decision tree to determine the correct serialization and concurrency approach before writing code:
  1. Serialization Strategy:
    • Condition: Is the JSON model simple, flat, and rarely changed?
      • Action: Use Manual Serialization (
        dart:convert
        ).
    • Condition: Is the JSON model complex, nested, or part of a large-scale application?
      • Action: Use Code Generation (
        json_serializable
        and
        build_runner
        ).
  2. Concurrency Strategy:
    • Condition: Is the data payload small and parsing takes < 16ms?
      • Action: Run on the Main UI Isolate using standard
        async
        /
        await
        .
    • Condition: Is the data payload large (e.g., > 1MB JSON) or computationally expensive?
      • Action: Offload to a Background Isolate using
        Isolate.run()
        .
    • Condition: Does the background task require continuous, two-way communication over time?
      • Action: Implement a Long-lived Isolate using
        ReceivePort
        and
        SendPort
        .
    • Condition: Is the target platform Web?
      • Action: Use
        compute()
        as a fallback, as standard
        dart:isolate
        threading is not supported on Flutter Web.
编写代码前,可参考以下决策树选择合适的序列化与并发方案:
  1. 序列化策略:
    • 条件: JSON模型是否简单扁平化、且很少变更?
      • 操作: 使用手动序列化
        dart:convert
        )。
    • 条件: JSON模型是否复杂、嵌套层级多,或是属于大型应用的一部分?
      • 操作: 使用代码生成
        json_serializable
        build_runner
        )。
  2. 并发策略:
    • 条件: 数据载荷是否很小,解析耗时小于16ms?
      • 操作: 使用标准
        async
        /
        await
        主UI Isolate中运行。
    • 条件: 数据载荷较大(比如大于1MB的JSON)或计算开销高?
      • 操作: 使用
        Isolate.run()
        将任务转移到后台Isolate执行。
    • 条件: 后台任务是否需要持续的双向通信?
      • 操作: 使用
        ReceivePort
        SendPort
        实现长生命周期Isolate
    • 条件: 目标平台是否为Web?
      • 操作: 使用
        compute()
        作为兜底方案,因为Flutter Web不支持标准
        dart:isolate
        线程能力。

Instructions

使用说明

1. Determine Environment and Payload Context

1. 确定环境与载荷上下文

STOP AND ASK THE USER:
  • "Are you targeting Flutter Web, Mobile, or Desktop?"
  • "What is the expected size and complexity of the JSON payload?"
  • "Do you prefer manual JSON serialization or code generation (
    json_serializable
    )?"
先询问用户以下信息:
  • "你的目标平台是Flutter Web、移动端还是桌面端?"
  • "JSON载荷的预期大小和复杂度是怎样的?"
  • "你倾向于使用手动JSON序列化还是代码生成(
    json_serializable
    )?"

2. Implement JSON Serialization Models

2. 实现JSON序列化模型

Based on the user's preference, implement the data models.
Option A: Manual Serialization
dart
import 'dart:convert';

class User {
  final String name;
  final String email;

  User(this.name, this.email);

  User.fromJson(Map<String, dynamic> json)
      : name = json['name'] as String,
        email = json['email'] as String;

  Map<String, dynamic> toJson() => {'name': name, 'email': email};
}
Option B: Code Generation (
json_serializable
)
Ensure
json_annotation
is in
dependencies
, and
build_runner
/
json_serializable
are in
dev_dependencies
.
dart
import 'package:json_annotation/json_annotation.dart';

part 'user.g.dart';

(explicitToJson: true)
class User {
  final String name;
  
  (name: 'email_address', defaultValue: 'unknown@example.com')
  final String email;

  User(this.name, this.email);

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}
Validate-and-Fix: Instruct the user to run
dart run build_runner build --delete-conflicting-outputs
to generate the
*.g.dart
file.
根据用户的选择实现数据模型。
选项A:手动序列化
dart
import 'dart:convert';

class User {
  final String name;
  final String email;

  User(this.name, this.email);

  User.fromJson(Map<String, dynamic> json)
      : name = json['name'] as String,
        email = json['email'] as String;

  Map<String, dynamic> toJson() => {'name': name, 'email': email};
}
选项B:代码生成(
json_serializable
确保
json_annotation
dependencies
中,
build_runner
/
json_serializable
dev_dependencies
中。
dart
import 'package:json_annotation/json_annotation.dart';

part 'user.g.dart';

(explicitToJson: true)
class User {
  final String name;
  
  (name: 'email_address', defaultValue: 'unknown@example.com')
  final String email;

  User(this.name, this.email);

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}
验证与修复: 指导用户执行
dart run build_runner build --delete-conflicting-outputs
生成
*.g.dart
文件。

3. Implement Background Parsing (Isolates)

3. 实现后台解析(Isolate)

To prevent UI jank, offload heavy JSON parsing to a background isolate.
Option A: Short-lived Isolate (Dart 2.19+) Use
Isolate.run()
for one-off heavy computations.
dart
import 'dart:convert';
import 'dart:isolate';
import 'package:flutter/services.dart';

Future<List<User>> fetchAndParseUsers() async {
  // 1. Load data on the main isolate
  final String jsonString = await rootBundle.loadString('assets/large_users.json');
  
  // 2. Spawn an isolate, pass the computation, and await the result
  final List<User> users = await Isolate.run<List<User>>(() {
    // This runs on the background isolate
    final List<dynamic> decoded = jsonDecode(jsonString) as List<dynamic>;
    return decoded.cast<Map<String, dynamic>>().map(User.fromJson).toList();
  });
  
  return users;
}
Option B: Long-lived Isolate (Continuous Data Stream) Use
ReceivePort
and
SendPort
for continuous communication.
dart
import 'dart:isolate';

Future<void> setupLongLivedIsolate() async {
  final ReceivePort mainReceivePort = ReceivePort();
  
  await Isolate.spawn(_backgroundWorker, mainReceivePort.sendPort);
  
  final SendPort backgroundSendPort = await mainReceivePort.first as SendPort;
  
  // Send data to the background isolate
  final ReceivePort responsePort = ReceivePort();
  backgroundSendPort.send(['https://api.example.com/data', responsePort.sendPort]);
  
  final result = await responsePort.first;
  print('Received from background: $result');
}

static void _backgroundWorker(SendPort mainSendPort) async {
  final ReceivePort workerReceivePort = ReceivePort();
  mainSendPort.send(workerReceivePort.sendPort);
  
  await for (final message in workerReceivePort) {
    final String url = message[0] as String;
    final SendPort replyPort = message[1] as SendPort;
    
    // Perform heavy work here
    final parsedData = await _heavyNetworkAndParse(url);
    replyPort.send(parsedData);
  }
}
为避免UI卡顿,将重度JSON解析转移到后台Isolate执行。
选项A:短生命周期Isolate(Dart 2.19及以上) 使用
Isolate.run()
执行一次性的重度计算任务。
dart
import 'dart:convert';
import 'dart:isolate';
import 'package:flutter/services.dart';

Future<List<User>> fetchAndParseUsers() async {
  // 1. 在主Isolate加载数据
  final String jsonString = await rootBundle.loadString('assets/large_users.json');
  
  // 2. 生成Isolate,传入计算逻辑并等待结果
  final List<User> users = await Isolate.run<List<User>>(() {
    // 以下代码在后台Isolate运行
    final List<dynamic> decoded = jsonDecode(jsonString) as List<dynamic>;
    return decoded.cast<Map<String, dynamic>>().map(User.fromJson).toList();
  });
  
  return users;
}
选项B:长生命周期Isolate(持续数据流场景) 使用
ReceivePort
SendPort
实现持续通信。
dart
import 'dart:isolate';

Future<void> setupLongLivedIsolate() async {
  final ReceivePort mainReceivePort = ReceivePort();
  
  await Isolate.spawn(_backgroundWorker, mainReceivePort.sendPort);
  
  final SendPort backgroundSendPort = await mainReceivePort.first as SendPort;
  
  // 向后台Isolate发送数据
  final ReceivePort responsePort = ReceivePort();
  backgroundSendPort.send(['https://api.example.com/data', responsePort.sendPort]);
  
  final result = await responsePort.first;
  print('从后台接收到数据: $result');
}

static void _backgroundWorker(SendPort mainSendPort) async {
  final ReceivePort workerReceivePort = ReceivePort();
  mainSendPort.send(workerReceivePort.sendPort);
  
  await for (final message in workerReceivePort) {
    final String url = message[0] as String;
    final SendPort replyPort = message[1] as SendPort;
    
    // 在此执行重度任务
    final parsedData = await _heavyNetworkAndParse(url);
    replyPort.send(parsedData);
  }
}

4. Integrate with UI State Management

4. 与UI状态管理集成

Bind the asynchronous isolate computation to the UI using
FutureBuilder
to ensure the main thread remains responsive.
dart
import 'package:flutter/material.dart';

class UserListScreen extends StatefulWidget {
  const UserListScreen({super.key});

  
  State<UserListScreen> createState() => _UserListScreenState();
}

class _UserListScreenState extends State<UserListScreen> {
  late Future<List<User>> _usersFuture;

  
  void initState() {
    super.initState();
    _usersFuture = fetchAndParseUsers(); // Calls the Isolate.run method
  }

  
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Users')),
      body: FutureBuilder<List<User>>(
        future: _usersFuture,
        builder: (context, snapshot) {
          if (snapshot.connectionState == ConnectionState.waiting) {
            return const Center(child: CircularProgressIndicator());
          } else if (snapshot.hasError) {
            return Center(child: Text('Error: ${snapshot.error}'));
          } else if (!snapshot.hasData || snapshot.data!.isEmpty) {
            return const Center(child: Text('No users found.'));
          }

          final users = snapshot.data!;
          return ListView.builder(
            itemCount: users.length,
            itemBuilder: (context, index) {
              return ListTile(
                title: Text(users[index].name),
                subtitle: Text(users[index].email),
              );
            },
          );
        },
      ),
    );
  }
}
使用
FutureBuilder
将异步Isolate计算结果绑定到UI,确保主线程保持响应。
dart
import 'package:flutter/material.dart';

class UserListScreen extends StatefulWidget {
  const UserListScreen({super.key});

  
  State<UserListScreen> createState() => _UserListScreenState();
}

class _UserListScreenState extends State<UserListScreen> {
  late Future<List<User>> _usersFuture;

  
  void initState() {
    super.initState();
    _usersFuture = fetchAndParseUsers(); // 调用Isolate.run方法
  }

  
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('用户列表')),
      body: FutureBuilder<List<User>>(
        future: _usersFuture,
        builder: (context, snapshot) {
          if (snapshot.connectionState == ConnectionState.waiting) {
            return const Center(child: CircularProgressIndicator());
          } else if (snapshot.hasError) {
            return Center(child: Text('错误: ${snapshot.error}'));
          } else if (!snapshot.hasData || snapshot.data!.isEmpty) {
            return const Center(child: Text('未找到用户数据。'));
          }

          final users = snapshot.data!;
          return ListView.builder(
            itemCount: users.length,
            itemBuilder: (context, index) {
              return ListTile(
                title: Text(users[index].name),
                subtitle: Text(users[index].email),
              );
            },
          );
        },
      ),
    );
  }
}

Constraints

约束条件

  • No UI in Isolates: Never attempt to access
    dart:ui
    ,
    rootBundle
    , or manipulate Flutter Widgets inside a spawned isolate. Isolates do not share memory with the main thread.
  • Web Platform Limitations:
    dart:isolate
    is not supported on Flutter Web. If targeting Web, you MUST use the
    compute()
    function from
    package:flutter/foundation.dart
    instead of
    Isolate.run()
    , as
    compute()
    safely falls back to the main thread on web platforms.
  • Immutable Messages: When passing data between isolates via
    SendPort
    , prefer passing immutable objects (like Strings or unmodifiable byte data) to avoid deep-copy performance overhead.
  • State Immutability: Always treat
    Widget
    properties as immutable. Use
    StatefulWidget
    and
    setState
    (or a state management package) to trigger rebuilds when asynchronous data resolves.
  • Reflection: Do not use
    dart:mirrors
    for JSON serialization. Flutter disables runtime reflection to enable aggressive tree-shaking and AOT compilation. Always use manual parsing or code generation.
  • Isolate中不能操作UI: 绝对不要在生成的Isolate中访问
    dart:ui
    rootBundle
    或者操作Flutter Widget,Isolate和主线程不共享内存。
  • Web平台限制: Flutter Web不支持
    dart:isolate
    ,如果目标平台是Web,必须使用
    package:flutter/foundation.dart
    中的
    compute()
    函数替代
    Isolate.run()
    compute()
    会在Web平台安全地回退到主线程执行。
  • 不可变消息: 通过
    SendPort
    在Isolate之间传递数据时,优先传递不可变对象(比如字符串或者不可修改的字节数据),避免深拷贝带来的性能开销。
  • 状态不可变性: 始终将
    Widget
    属性视为不可变,异步数据返回后,使用
    StatefulWidget
    setState
    (或者状态管理包)触发UI重绘。
  • *反射: 不要使用
    dart:mirrors
    做JSON序列化,Flutter禁用了运行时反射以支持高效的树抖动和AOT编译,始终使用手动解析或者代码生成方案。