flutter_observation #

flutter_observation 是一个参考 Swift Observation 设计的 Flutter 属性观察库。

核心能力包括：

• 属性级依赖跟踪：只读取 user.name 的 Widget 不会被 user.age 的变化刷新。
• Model 和 Widget source generation，减少手写 getter、setter 和 State 生命周期代码。
• 显式区分 @ObservableState() 与 @PlainState()，避免把普通资源误认为可观察状态。
• Observable<T>、ObservableList、ObservableMap、ObservableSet。
• 嵌套 Observable、多个 Widget state、自动释放和 Widget 配置同步。
• Observer、手写 Observation Widget、现有 StatefulWidget mixin。
• 基于 Flutter InheritedWidget 的 ObservationScope，用于跨子树共享全局或局部状态。
• 一次性观察、连续订阅、Stream、事务、调度器、错误处理和调试事件。
• ValueListenable 适配器，可接入 Flutter 自带的 Listenable 生态。

它提供两套统一的代码生成入口：

@ObservableModel()   // 声明可观察 Model
@ObservationWidget() // 声明自动观察的 Widget

Widget 中存在 @PlainState() 或 @ObservableState() factory 时，生成器会自动 管理状态的创建、注入、更新和释放。@PlainState() 明确声明普通资源， @ObservableState() 明确要求状态实现 ObservableObject；没有 state factory 时，生成器只负责跟踪 build() 中读取的 Observable。

所有 annotation 统一使用大写构造形式：

需要传递选项时仍使用相同构造函数，例如 @PlainState(name: 'resource', autoDispose: false) 或 @ObservableState(name: 'user', autoDispose: false)。

安装 #

准备发布的 prerelease：

dependencies:
  flutter:
    sdk: flutter
  flutter_observation: ^0.2.1

dev_dependencies:
  build_runner: ^2.16.0
  flutter_observation_generator: ^0.2.1

flutter pub get

Observable Model #

import 'package:flutter_observation/flutter_observation.dart';

part 'user.g.dart';

@ObservableModel()
class User extends _$User {
  User({String super.name = '', int super.age = 18});

  void celebrateBirthday() => age++;

  String get label => '$name ($age)';
}

构造参数定义生成属性的名称、类型和初始值。这里使用 Dart 的 typed super parameters，把参数直接转发给生成基类，因此不需要重复编写 : super(name, age)。普通计算 getter 会继续跟踪它读取的底层属性，因此 label 会自动依赖 name 和 age。

原有写法继续支持，生成器会自动为它保留 positional 基类构造函数：

@ObservableModel()
class User extends _$User {
  User({String name = '', int age = 18}) : super(name, age);
}

生成代码：

dart run build_runner build

开发期间可以持续监听：

dart run build_runner watch

Model generator 的输入规则：

• 类必须是 concrete class，并继承生成的 _$ClassName。
• 必须声明 unnamed generative constructor，且至少有一个 named parameter。
• constructor parameter 就是生成属性，不要在类体中再次声明同名字段。
• Model constructor 可以使用 typed super parameters，也可以继续使用普通参数和 positional super(...) initializer；生成器会按类自动选择对应构造函数。
• 使用 super parameters 时必须保留显式类型，让首次生成在尚无 .g.dart 时仍能 确定属性类型。若项目启用了 type_init_formals lint，请为 Model 文件关闭这条 纯样式规则。
• 泛型和泛型 bound 会保留到生成基类。
• 默认 setter 使用 == 去重；赋相等值不会通知。

part 文件名可以自行决定，只要与当前 Dart 文件中的 part '...g.dart' 一致。 生成文件不要手动修改。

无内部状态的响应式 Widget #

外部传入 Model 时，只使用 @ObservationWidget()：

part 'user_card.g.dart';

@ObservationWidget()
class UserCard extends _$UserCard {
  const UserCard({
    required this.user,
    super.key,
  });

  final User user;

  @override
  Widget build(BuildContext context) {
    return Text(user.name);
  }
}

build() 中读取的属性会自动建立依赖。user.name 变化时组件重建，其他没有被 读取的属性不会触发它。

{super.key} 是 Dart 的 super parameter 语法：它声明一个可选命名参数 key， 并直接传给生成基类的构造函数。它等价于手写 UserCard({Key? key}) : super(key: key)，与 Observation state 无关。

拥有内部状态的响应式 Widget #

使用 @ObservableState() 标记返回非空 ObservableObject 的零参数 factory。 返回值可以是 @ObservableModel() Model、Observable<T>、Observable 集合，或 手动混入 ObservableModelMixin 的类型：

part 'user_page.g.dart';

@ObservationWidget()
class UserPage extends _$UserPage {
  const UserPage({super.key});

  @ObservableState()
  User createUser() => User(name: 'Alice');

  @override
  Widget build(
    BuildContext context, {
    required User user,
  }) {
    return Scaffold(
      body: Text(user.name),
      floatingActionButton: FloatingActionButton(
        onPressed: () => user.name = 'Tom',
      ),
    );
  }
}

状态 factory 由注解识别，不是生成父类中的抽象方法，因此不需要 @override。 build() 仍然是 Widget 的构建契约，继续使用 @override。

生成器会：

• 在 initState() 中调用 createUser() 一次。
• 把方法名 createUser 转成状态名 user。
• 通过命名参数把 user 注入 build()。
• 跟踪 build() 中的 Observable 读取。
• Widget 移除时自动调用状态类型公开的零参数 dispose()。

普通资源使用 @PlainState()。它要求返回类型不能实现 ObservableObject，只表达 Widget 对对象的所有权和生命周期：

@PlainState()
PageResource createResource() => PageResource();

两者都要求 factory 是实例零参数方法，并使用相同的创建、注入、更新和释放流程。

Widget generator 会在编译期检查完整契约：

• Widget 必须是 concrete class，并声明 unnamed generative constructor。
• build() 的第一个参数必须是唯一的 required positional BuildContext。
• 每个 state factory 必须是实例、零参数方法，并声明具体的非 void、非 dynamic 返回类型。
• 每个 state 都必须在 build() 中存在名称和类型完全匹配的 required named parameter；不能添加没有对应 factory 的 named build parameter。
• @ObservableState() 必须返回非空 ObservableObject；可空值请包装成 Observable<T?>。
• @PlainState() 的返回类型不能实现 ObservableObject。这要求调用者明确表达 “该资源本身不可观察”的意图；资源内部仍然可以持有 Observable。

多个状态 #

@ObservationWidget()
class UserPage extends _$UserPage {
  const UserPage({super.key});

  @ObservableState()
  User createUser() => User(name: 'Alice');

  @ObservableState()
  Settings createSettings() => Settings();

  @override
  Widget build(
    BuildContext context, {
    required User user,
    required Settings settings,
  }) {
    return Text('${user.name} / ${settings.themeName}');
  }
}

每个 factory 只执行一次，并按照声明顺序创建、逆序释放。

创建中途失败时，已经创建成功的状态也会按逆序清理，然后重新抛出最初的创建 错误。释放过程中即使某个 dispose() 抛错，其余状态仍会继续释放，最后重新抛出 第一个错误。

注意：一个 state factory 不应调用另一个 state factory，因为那会创建第二个实例。 有关联的状态应组合成页面 Model，或者在普通 Widget 配置中共享依赖。

自定义状态名称和释放行为 #

默认规则是去掉 create 前缀并把首字母改成小写：

createUser     → user
createSettings → settings
counter        → counter

可以显式指定名称：

@ObservableState(name: 'currentUser')
User makeUser() => User(name: 'Alice');

显式名称必须是合法 Dart identifier，不能是 keyword、context 或 oldWidget，也 不能与另一个 state 重名。

生成器会在编译期检查状态的静态类型。如果它声明或继承了零参数 dispose()，生成代码会直接调用该方法，不需要实现公共接口。禁用自动释放：

@PlainState(autoDispose: false)
ExternalResource createSharedResource() => sharedResource;

Observable<T> 和普通 @ObservableModel() Model 是纯 Observation 对象，本身 不需要 dispose。持有 Controller、Timer 或 Subscription 的 Observable Model 可以公开零参数 dispose()，由生成器自动识别并释放。

自动识别的 dispose() 必须是同步的零参数 void dispose()。异步清理应关闭自动 释放并在生命周期钩子中启动或协调：

// 需要 import 'dart:async';
@PlainState(autoDispose: false)
AsyncResource createResource() => AsyncResource();

@override
void disposeStates({required AsyncResource resource}) {
  unawaited(resource.close());
}

库不要求资源实现 Disposable 接口；是否可自动释放完全由 factory 的静态返回 类型决定。

Widget 配置变化 #

默认会保留已创建状态。需要根据 Widget 参数重新创建全部状态时：

@override
bool shouldRecreateStates(covariant UserPage oldWidget) {
  return oldWidget.userId != userId;
}

保留状态但需要同步新配置时：

@override
void didUpdateStates(
  covariant UserPage oldWidget, {
  required User user,
}) {
  if (oldWidget.userId != userId) {
    user.load(userId);
  }
}

没有标准 dispose()，或者需要额外清理逻辑时，可以使用自定义钩子：

@override
void disposeStates({required User user}) {
  // 在这里释放 User 持有的其他外部资源。
}

不要在 disposeStates() 中再次调用生成器已经自动处理的 dispose()。

生命周期顺序如下：

1. initState 按声明顺序创建全部 state。
2. Widget 配置变化时，shouldRecreateStates 决定是保留还是替换全部 state。
3. 保留时调用 didUpdateStates；替换时先清理旧 state，再创建新 state。
4. 清理时先调用 disposeStates，然后按声明逆序执行自动 dispose()。
5. Widget 移除时取消属性依赖并执行同一套清理流程。

不使用 Widget generator #

只消费外部 Model：

class UserCard extends ObservationStatelessWidget {
  const UserCard({required this.user, super.key});

  final User user;

  @override
  Widget build(BuildContext context) => Text(user.name);
}

直接拥有一个 Model：

class UserPage extends ObservationStatefulWidget<User> {
  const UserPage({super.key});

  @override
  User createModel() => User(name: 'Alice');

  @override
  Widget build(BuildContext context, User user) => Text(user.name);

  @override
  bool shouldRecreateModel(covariant UserPage oldWidget) {
    return false;
  }

  @override
  void didUpdateModel(covariant UserPage oldWidget, User user) {
    // 保留 model 时同步新的 Widget 配置。
  }

  @override
  void disposeModel(User user) {
    // 手写 Widget 需要在这里显式清理；generator 才会静态检测 dispose()。
  }
}

ObservationStatelessWidget 名称对应“不拥有业务状态”，但它内部仍借助一个 Flutter State 保存依赖关系；这些框架内部状态会自动管理。ObservationStatefulWidget 每个 实例只能注入一个 Model，多个状态和自动静态 dispose() 检测请使用 @ObservationWidget() generator。

嵌入现有 Widget #

局部观察：

Observer(
  builder: (context) => Text(user.name),
)

已有 StatefulWidget：

class _PageState extends State<Page> with ObservationStateMixin<Page> {
  @override
  Widget build(BuildContext context) {
    return buildObserved((context) => Text(widget.user.name));
  }
}

buildObserved() 每次执行前会取消上一轮依赖并重新收集；mixin 的 dispose() 会 自动执行 stopObservation()。如果一个 build() 中只有局部区域需要刷新，优先 把该区域包装为 Observer，可以缩小重建范围。

全局和跨子树状态：ObservationScope #

ObservationScope<T> 用来把一个已有实例传给后代。它不是必须的；状态也可以通过 constructor 传递、放在自定义 InheritedWidget 中，或者交给 Provider、Riverpod 等容器管理。

一个由根 Widget 创建、由页面读取的完整例子：

@ObservableModel()
class AppState extends _$AppState {
  AppState({String super.currentUserName = ''});
}

@ObservationWidget()
class App extends _$App {
  const App({super.key});

  @ObservableState()
  AppState createAppState() => AppState();

  @override
  Widget build(BuildContext context, {required AppState appState}) {
    return ObservationScope<AppState>(
      value: appState,
      child: const MaterialApp(home: HomePage()),
    );
  }
}

@ObservationWidget()
class HomePage extends _$HomePage {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    final appState = ObservationScope.of<AppState>(context);
    return Text(appState.currentUserName);
  }
}

这里的所有权与观察是分开的：

• 根 App 的 @ObservableState() 负责创建和必要时释放 AppState。
• ObservationScope 只负责传递引用，不创建、不拥有、也不释放 value。
• ObservationScope.of<T>(context) 依赖实例替换；value identity 改变时后代重建。
• appState.currentUserName 的属性级变化由 HomePage 的 Observation build 跟踪， 不是由 Scope 跟踪。
• ObservationScope.maybeOf<T>(context) 在找不到时返回 null；of<T> 会抛出 FlutterError。

ObservationScope 本身就是对 Flutter InheritedWidget 的轻量封装。它没有用 InheritedNotifier，因为 ObservableObject 不是 Listenable；属性依赖已经由 Observation registrar 更细粒度地维护。若 Flutter API 必须接收 Listenable，请 使用后面的 toValueListenable()。

多个全局状态可以按类型嵌套：

ObservationScope<AuthState>(
  value: auth,
  child: ObservationScope<SettingsState>(
    value: settings,
    child: const AppRouter(),
  ),
);

同一类型嵌套时，of<T> 返回距离当前 context 最近的 Scope。读取 Scope 中的属性 仍必须发生在 Observer、Observation Widget 或其他同步跟踪作用域内，普通 StatelessWidget.build() 不会因为属性变化自动刷新。

单值 Observable #

Observable<T> 与 @ObservableModel() Model 使用相同的 Registrar，不依赖 ChangeNotifier，因此不需要 dispose：

final count = Observable(0);

Observer(
  builder: (context) => Text('${count.value}'),
);

count.value++;

value setter 默认也使用 == 去重。Observable<T?> 可以表达一个可空但仍然可 观察的状态，尤其适合 @ObservableState() factory：

@ObservableState()
Observable<User?> createCurrentUser() => Observable(null);

需要接入 ValueListenableBuilder、AnimatedBuilder 等 Flutter API 时：

final name = toValueListenable(() => user.name);

ValueListenableBuilder(
  valueListenable: name,
  builder: (context, value, child) => Text(value),
);

// 放在 State.dispose() 或其他 owner 的清理逻辑中：
name.dispose();

适配器应由 State.initState()、dependency injection container 或其他长期 owner 创建一次，不要在每次 build() 时重新创建。

ObservationValueListenable 拥有连续观察 subscription，单独创建时需要 dispose。 它还支持 notifyOnEqual、scheduler 和 onError：

final label = toValueListenable(
  () => '${user.name} (${user.age})',
  notifyOnEqual: false,
  scheduler: ObservationSchedulers.frame,
  onError: reportError,
);

notifyOnEqual: false 表示依赖已经失效、但派生值仍然 == 时不通知 Flutter listener。适配器只是互操作桥梁；Observation Widget 自身不需要先转成 ValueListenable。

可观察集合 #

Dart 普通集合的原地变更不经过属性 setter。需要观察内容时使用：

final tags = ObservableList<String>(['Flutter']);
final scores = ObservableMap<String, int>({'Alice': 10});
final selected = ObservableSet<String>();

tags.add('Dart');
scores['Alice'] = 11;
selected.add('Alice');

集合本身不注册到外部 source，因此不需要 dispose。直接索引、键和成员查询是 细粒度依赖：修改 scores['Bob'] 不会让只读取 scores['Alice'] 的观察者失效； 迭代、join()、keys 等整体读取仍会观察完整内容。List 的插入和删除会使受影响 位置之后的索引依赖失效。

细粒度规则：

三个集合都实现对应的 Dart collection interface，可以使用常规 List、Map、Set API。 批量业务操作可以使用集合自带的 transaction()，让同一观察者最多失效一次：

tags.transaction((tags) {
  tags.add('Dart');
  tags.add('Observation');
});

嵌套 Observable #

@ObservableModel()
class Address extends _$Address {
  Address({String super.city = 'Shanghai'});
}

@ObservableModel()
class User extends _$User {
  User({required Address super.address});
}

读取 user.address.city 会同时订阅外层引用和内层属性。修改 city 或替换整个 address 都会刷新；重建后会取消旧对象依赖。

一次性、连续和异步观察 #

一次性观察，在第一次变化后自动解除：

final initialName = withObservationTracking(
  () => user.name,
  onChange: scheduleRender,
);

它立即返回闭包的值。onChange 在任意已读取属性第一次变化时同步执行一次，执行前 依赖已经解除；需要继续观察时，由调用者重新运行 tracking。这是 Widget renderer 使用的底层模式。

需要在首次变化前主动取消时：

final tracking = withCancellableObservationTracking(
  () => user.name,
  onChange: scheduleRender,
);

tracking.cancel();

handle 同时提供首次读取的 value 与 isActive。如果闭包没有读取任何 Observable， 就不会建立依赖，isActive 为 false。

连续观察：

final subscription = observe(
  () => user.name,
  onChange: print,
  onError: (error, stackTrace) => report(error, stackTrace),
  fireImmediately: true,
);

subscription.dispose();

ObservationSubscription<T> 提供：

• value：最近一次跟踪得到的值。
• refresh()：立即重新读取、重新收集依赖并返回新值，不等待 scheduler。
• isDisposed：订阅是否已经停止。
• dispose()：幂等地取消订阅并释放 registrar 引用。

每次 refresh 都会重新收集依赖，因此条件读取可以动态切换：

final subscription = observe(
  () => useNickname.value ? user.nickname : user.name,
  onChange: print,
);

切换到 nickname 后，旧的 name 依赖会被解除。

默认使用 microtask 合并同步变化，也可以按下一帧刷新：

observe(
  () => user.name,
  onChange: print,
  scheduler: ObservationSchedulers.frame,
);

可用 scheduler：

• ObservationSchedulers.immediate：失效时同步 refresh。
• ObservationSchedulers.microtask：默认值；同一 microtask 前的同步变化自然合并。
• ObservationSchedulers.frame：下一 Flutter frame 开始时 refresh。
• 自定义 ObservationScheduler：接收 callback 并自行安排执行。

初始 read 或启用 fireImmediately 时的 onChange 抛错，会停止订阅并把错误重新 抛出。后续 scheduler、read 或 onChange 抛错时也会先停止订阅；传入 onError 时错误交给它，否则保留原 stack trace 重新抛出。

异步 Stream：

await for (final name in observeStream(() => user.name)) {
  print(name);
}

observeStream(read, emitInitial: true) 返回 single-subscription Stream。默认先发送 初始值；取消 StreamSubscription 会取消底层 observation。refresh 出错会把错误 发送到 Stream 并关闭它。

事务 #

observationTransaction(() {
  user.name = 'Alice';
  user.age = 20;
});

同一观察者在一个事务中只失效一次。 事务可以嵌套，只有最外层结束时才 flush。observationMutation() 和 Observable 集合的批量通知内部也使用同一事务机制。

通知采用容错 fan-out：即使一个观察者回调抛错，其他观察者仍会收到通知，完成后 重新抛出第一个错误。公开的 runObservationCallbacks() 可用于需要相同行为的自定义 清理或通知代码。

Flutter DevTools Extension #

flutter_observation 从 0.2.0-dev.2 开始内置只读 DevTools Extension。应用以 debug 或 profile 模式运行并连接 DevTools 后，会出现 flutter_observation 标签页； 第一次打开需要在 DevTools 的 Extensions 对话框中启用。

无需在 main() 中初始化。创建第一个 ObservationRegistrar 时会自动注册当前 isolate 的 VM Service protocol；当前面板读取 main isolate。release 构建不会注册、 记录或保留调试数据。

Extension 提供：

• Overview：Observable source、被观察属性、observer、通知、失效和重建数量。
• State：按 source 查看生成 Model、Observable<T> 和可观察集合的当前状态； Observable 引用可点击跳到目标 source。
• Dependencies：当前 Observable.property → Widget/Subscription 依赖关系；显示 实际 Widget 和对应 State，点击可在 Flutter Inspector 中选中该 Element。
• Events：依赖增删、通知、失效、重建、连续观察和事务时间线；source、property 和 Widget 引用可跳到对应 State、Dependencies 或 Flutter Inspector。
• Hot properties：事件窗口内通知次数最多的属性。

跳转到 Flutter Inspector 后，原生 state 属性只显示真实的 Flutter State 类型。 Observation 业务状态会作为独立的 Widget property 行显示：生成器创建的 @ObservableState() / @PlainState() 使用 owned state · 名称，当前 Widget 在 最近一次 build 中读取的 Observable source 使用 observed state。例如：

state                _$ObservationExampleState#...
owned state · user   User #16

state                _ObservationStatelessWidgetState#...
observed state       User #16
observed state       ObservableList<String> #10

这里的稳定 ID 与 Extension 的 State、Dependencies 页一致；业务属性的完整值仍在 Extension 的 State 页查看。Flutter Inspector 当前不向第三方 diagnostics 开放属性行 点击回调，因此跨页跳转仍从 Extension 的 Dependencies 或 Events 中发起。

将鼠标停在 owned state 或 observed state 的值上，悬浮面板会显示已注册的 backing-field 值。生成 Model 自动包含所有可观察字段；内置类型包括：

• Observable<T>：Observable.value
• ObservableList<T>：contents、length，以及本次实际读取的索引
• ObservableMap<K, V>：contents，以及本次实际读取的 key
• ObservableSet<T>：contents，以及本次实际读取的成员关系

也可以在 Flutter Inspector 的 Console 中读取当前选中 Widget 的真实业务对象：

// 查看当前 Widget 的全部 owned / observed state
ObservationInspector.selectedStates

// 按类型取得第一个匹配的 state
ObservationInspector.selectedStateOf<User>()

// 查看集合内容
ObservationInspector
    .selectedStateOf<ObservableList<String>>()
    ?.toList()

ObservationInspector
    .selectedStateOf<ObservableSet<String>>()
    ?.toSet()

ObservationInspector
    .selectedStateOf<ObservableMap<String, int>>()
    ?.entries
    .toList()

// 也可以直接使用 Inspector / Extension 显示的 #id
ObservationInspector.stateById(5)
ObservationInspector.stateById<ObservableList<String>>(5)?.toList()

ObservationInspector 仅用于 debug/profile 诊断；release 模式返回空结果，Console 表达式求值需要 debug 模式。取得的是实际业务对象而不是副本，因此应避免在检查时 意外修改它。

#id 由 ObservationDebug.idFor() 按对象身份分配，同一个对象在当前 Dart isolate 生命周期内保持稳定且不会复用。它不是跨 isolate 的全局 ID；hot restart、应用重启、 切换设备或连接另一个 isolate 后都可能重新从相同数字开始。反查采用弱引用，对象被 回收后 stateById() 会返回 null。

State 页始终显示当前值；打开 Extension 时自动启用读取，关闭面板后停止。状态可能 包含 token、用户资料等敏感数据。生成代码注册的是 backing-field reader，读取不会 调用 Observable getter、不会产生新依赖，也不会调用任意业务对象的 toString()。 字符串和集合预览有长度上限，Observable 引用只显示类型和稳定 ID；快照不会保留 业务对象的原始引用。release 构建会移除 reader 和 Inspector target 注册。

面板默认不记录每次属性读取，因为 access 频率通常很高；需要时可打开 Property reads。记录使用有界 ring buffer，默认最多 2000 条。

底层 VM Service 方法如下，主要供其他工具集成：

ext.flutter_observation.getSnapshot
ext.flutter_observation.getEvents
ext.flutter_observation.setRecording
ext.flutter_observation.setValueInspection
ext.flutter_observation.selectInspectorTarget
ext.flutter_observation.clearEvents

开发 Extension 源码：

cd tool/flutter_observation_devtools_extension
flutter test
dart run devtools_extensions build_and_copy \
  --source=. \
  --dest=../../extension/devtools
dart run devtools_extensions validate --package=../..

调试 API 和性能基线 #

开发工具可以订阅属性访问和通知事件；未设置回调时不会分配事件对象：

ObservationDebug.onEvent = (event) {
  print(
    '${event.kind}: ${event.property}, observers=${event.observerCount}',
  );
};

// 调试结束后恢复
ObservationDebug.onEvent = null;

多个工具需要同时监听时，使用不会互相覆盖的 listener：

final handle = ObservationDebug.addListener((event) {
  print(event.toJson());
});

handle.dispose();

也可以直接控制有界记录器和 opt-in 状态快照：

ObservationDebug.setRecording(true, capacity: 1000);
ObservationDebug.setValueInspection(true);
final snapshot = ObservationDebug.snapshot();
final events = ObservationDebug.eventsAfter(0);
ObservationDebug.setValueInspection(false);
ObservationDebug.setRecording(false);

事件 kind 包括 access、依赖增删、notify、invalidate、重建、连续观察和事务；同时 包含 sequence、timestamp、稳定 ID、类型、属性与 observer label。registrar、 property、observer 原始引用只会传给进程内 listener，不进入序列化缓存。 未设置 listener 且记录器关闭时不会创建事件对象。

运行仓库内的性能基线：

flutter test benchmark/observation_benchmark.dart --reporter expanded

Model generator 选项 #

@ObservableModel()
class Box<T extends Object?> extends _$Box<T> {
  Box({
    required T super.value,
    @ObservationReadOnly() required String super.id,
    @ObservationIgnored() int super.cacheHits = 0,
    @ObservationAlwaysNotify() int super.revision = 0,
  });
}

• @ObservationReadOnly()：只生成 getter。
• @ObservationIgnored()：保留 getter/setter，但读取不跟踪、写入不通知。
• @ObservationAlwaysNotify()：跳过 == 去重，每次赋值都通知。

@ObservationAlwaysNotify() 不能与 @ObservationIgnored() 或 @ObservationReadOnly() 组合。@ObservationReadOnly() 只限制公开 setter；如果 属性引用的是可变 Observable 对象，仍可修改那个对象自身的属性。

手写 Observable Model #

当 generator 不能占用 superclass slot，或属性来自外部存储时，可以混入 ObservableModelMixin：

class ManualCounter with ObservableModelMixin {
  ManualCounter() {
    if (!ObservationDebug.isReleaseMode) {
      observationRegisterDebugProperty(_countKey, () => _count);
    }
  }

  static final ObservationKey<int> _countKey =
      ObservationKey<int>('ManualCounter.count');

  int _count = 0;

  int get count {
    observationAccess(_countKey);
    return _count;
  }

  set count(int value) {
    if (_count == value) return;
    observationMutation(_countKey, () => _count = value);
  }

  void syncFromExternalStorage(int value) {
    _count = value;
    observationNotify(_countKey);
  }
}

每个属性应持有一个生命周期稳定的 ObservationKey<T>；key 按 identity 区分，通常 声明为 static final。mixin 自动提供 ObservationRegistrar 以及 observationAccess、observationMutation、observationNotify。 如果希望手写属性出现在 DevTools State 页，再通过 observationRegisterDebugProperty() 注册直接读取 backing field 的闭包；release 分支会被常量消除。

更底层的适配器可以直接实现 ObservableObject 并暴露 Registrar：

class ExternalValue implements ObservableObject {
  ExternalValue() {
    observationRegistrar.attachDebugSource(this);
    if (!ObservationDebug.isReleaseMode) {
      observationRegistrar.registerDebugProperty(_valueKey, () => _value);
    }
  }

  @override
  final observationRegistrar = ObservationRegistrar();

  final _valueKey = ObservationKey<int>('ExternalValue.value');
  int _value = 0;

  int get value {
    observationRegistrar.access(_valueKey);
    return _value;
  }

  void setValue(int value) {
    observationRegistrar.withMutation(_valueKey, () => _value = value);
  }
}

Registrar 还提供成对的 willSet() / didSet()、显式 notify()、 removeObserver() 和 hasObserversFor()。这些属于框架集成层；普通业务 Model 优先 使用 generator 或 mixin helper。

跟踪规则 #

• 只有同步跟踪作用域内的读取会建立依赖；await 之后的读取不属于原作用域。
• 每次重新构建会重新收集依赖，条件分支不再读取的属性会取消订阅。
• 计算 getter 不需要额外 annotation；它读取的底层 Observable 会成为实际依赖。
• 普通对象不会被递归变为 Observable。
• 普通集合原地变更无法拦截，使用 Observable 集合或重新赋值。
• 生成 setter 和 Observable<T> 默认使用 == 去重；需要每次赋值都通知时使用 @ObservationAlwaysNotify()。
• @PlainState() 必须标记实例零参数方法，并返回非 ObservableObject。
• @ObservableState() 具有相同生命周期语义，但必须返回非空 ObservableObject；可空数据请包装在 Observable<T?> 中。
• Widget constructor 参数属于外部配置，不会被自动释放。

什么时候需要 dispose #

Observation 的属性注册关系由 Widget 或 subscription owner 解除；纯 Model 并不持有 后台任务，所以并不是所有对象都需要 dispose()。

如果 Observable Model 自己持有 Timer、StreamSubscription、Controller、isolate 或平台资源，它仍然需要为这些业务资源定义清理方法。generator 可以自动调用同步 零参数 void dispose()，但不会猜测其他方法或异步协议。

公开 API 总览 #

下表覆盖 package:flutter_observation/flutter_observation.dart 当前导出的公开功能。

普通应用通常只需要 annotations、Observable source 和 Widget integration。Registrar、 Observer protocol 与 ObservationTracking.track() 主要用于编写新的 framework adapter；直接使用时，owner 必须在结束时通过 registrar 移除 observer。

运行 Example #

cd example
flutter pub get
dart run build_runner build
flutter run -d macos

# runtime
flutter test

# Example
cd example && flutter test

# generator golden
cd packages/flutter_observation_generator && dart test

更多说明参见 example/README.md。