跨平台开发 / 系统课时
保证参数具备稳定相等性
保证参数具备稳定相等性
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 实例,构建函数只执行一次。
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'),
),
),
);
}
}预期结果
页面显示:第一次: 1 / 第二次: 1这说明两个不同实例因为值相等而共享了同一个 family 缓存项。若删除 == 与 hashCode 的重写,冷启动时通常会看到两次构建,对应两个独立参数身份。
相等性必须同时稳定且一致
== 与 hashCode 必须描述同一组字段:只要两个对象满足 a == b,它们的 hashCode 就必须相同。参数对象还应保持不可变,否则对象放入缓存后再修改参与相等性判断的字段,会让查找结果变得不可预测。
原生 List 和 Map 默认并不是“内容相同就相等”。如果业务参数是筛选条件集合,不要直接反复创建新的列表或映射作为 family 参数;可以改用 record、不可变值对象,或先把条件归一化成稳定字符串。
选择合适的参数形态
例如两个字段的查询条件可以直接使用 record:(userId: 'u-100', locale: 'zh-CN')。Record 自带结构化值相等性,避免手写 == 与 hashCode。当参数还包含验证逻辑、方法或更多业务语义时,再使用不可变类会更清晰。
稳定相等性的核心不是“让所有对象都相等”,而是让业务上代表同一个查询的参数得到同一个身份。这样 family 的缓存、复用与销毁行为才会与业务预期一致。