跨平台开发 / 系统课时

保证参数具备稳定相等性

保证参数具备稳定相等性

family 会把参数当作 Provider 实例的身份组成部分。同一个业务参数如果每次都被判定为“不同对象”,Riverpod 就会创建不同缓存项;反过来,只要 == 与 hashCode 稳定一致,等价参数就能命中同一份状态。

学习目标

  • 解释 == 与 hashCode 如何影响 family 的缓存身份
  • 为自定义参数类型实现稳定的值相等性
  • 识别可变对象、List、Map 等容易导致缓存失配的参数

family 为什么关心参数相等性

调用 userProvider(param) 时,Riverpod 不只看 userProvider 本身,还会把 param 纳入 Provider 的身份判断。两次调用若参数相等,就会指向同一个逻辑 Provider;参数不等,则会得到不同的状态与缓存。

因此,family 参数最好天然具有值语义,例如 String、int、枚举、Dart record,或正确实现了 == 与 hashCode 的不可变类。默认的普通类实例通常按对象身份比较,即使字段完全相同,也会被认为不同。

用值相等性保证缓存命中

下面的完整 Flutter 示例创建两个字段相同、但实例不同的 UserQuery。因为类实现了值相等性,两次读取会命中同一个 Provider.family 实例,构建函数只执行一次。

dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

int buildCount = 0;

class UserQuery {
  const UserQuery({required this.userId, required this.locale});

  final String userId;
  final String locale;

  @override
  bool operator ==(Object other) {
    return other is UserQuery &&
        other.userId == userId &&
        other.locale == locale;
  }

  @override
  int get hashCode => Object.hash(userId, locale);
}

final queryBuildProvider = Provider.family<int, UserQuery>((ref, query) {
  buildCount += 1;
  return buildCount;
});

void main() {
  runApp(const ProviderScope(child: DemoApp()));
}

class DemoApp extends ConsumerWidget {
  const DemoApp({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    const first = UserQuery(userId: 'u-100', locale: 'zh-CN');
    const second = UserQuery(userId: 'u-100', locale: 'zh-CN');

    final firstBuild = ref.watch(queryBuildProvider(first));
    final secondBuild = ref.watch(queryBuildProvider(second));

    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: Text('第一次: $firstBuild / 第二次: $secondBuild'),
        ),
      ),
    );
  }
}

预期结果

text
页面显示:第一次: 1 / 第二次: 1

这说明两个不同实例因为值相等而共享了同一个 family 缓存项。若删除 == 与 hashCode 的重写,冷启动时通常会看到两次构建,对应两个独立参数身份。

相等性必须同时稳定且一致

== 与 hashCode 必须描述同一组字段:只要两个对象满足 a == b,它们的 hashCode 就必须相同。参数对象还应保持不可变,否则对象放入缓存后再修改参与相等性判断的字段,会让查找结果变得不可预测。

原生 List 和 Map 默认并不是“内容相同就相等”。如果业务参数是筛选条件集合,不要直接反复创建新的列表或映射作为 family 参数;可以改用 record、不可变值对象,或先把条件归一化成稳定字符串。

选择合适的参数形态

例如两个字段的查询条件可以直接使用 record:(userId: 'u-100', locale: 'zh-CN')。Record 自带结构化值相等性,避免手写 == 与 hashCode。当参数还包含验证逻辑、方法或更多业务语义时,再使用不可变类会更清晰。

稳定相等性的核心不是“让所有对象都相等”,而是让业务上代表同一个查询的参数得到同一个身份。这样 family 的缓存、复用与销毁行为才会与业务预期一致。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

保证参数具备稳定相等性

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通