Back to Details

flutter-isar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Isar Database

Isar 数据库

Use Isar as the primary local database for structured data persistence
Define collections using
```
@collection
```
annotation with
```
Id
```
field
Place collection definitions in the
```
data/local/
```
directory of the relevant feature

Run

dart run build_runner build --delete-conflicting-outputs

after modifying collections

使用 Isar 作为结构化数据持久化的首选本地数据库
使用带有
```
Id
```
字段的
```
@collection
```
注解定义集合
将集合定义放在对应功能模块的
```
data/local/
```
目录下

修改集合后执行

dart run build_runner build --delete-conflicting-outputs

Schema Design

Schema 设计

Keep collections focused — one collection per domain entity
Use
```
@Index
```
annotations for fields queried frequently
Use
```
@enumerated
```
for enum fields
Use
```
Links
```
and
```
Backlinks
```
for relationships between collections
NEVER store derived/computed values — compute them in the domain layer

保持集合职责单一——每个领域实体对应一个集合
对高频查询的字段使用
```
@Index
```
注解
枚举字段使用
```
@enumerated
```
注解
使用
```
Links
```
和
```
Backlinks
```
处理集合之间的关系
绝对不要存储派生/计算值——在领域层完成相关计算

Migrations

数据迁移

Isar handles additive schema changes automatically (new fields, new collections)
For breaking changes (renamed fields, removed fields), write migration logic in the repository
Version your database schema and check version on app startup

Isar会自动处理增量式Schema变更（新增字段、新增集合）
遇到破坏性变更（字段重命名、字段删除）时，需在仓储层编写迁移逻辑
给数据库Schema添加版本控制，在应用启动时校验版本

Repository Pattern for Local Data

本地数据的仓储模式

Local DataSource wraps all Isar
```
put
```
,
```
get
```
,
```
delete
```
,
```
watch
```
calls
Repositories orchestrate between remote and local DataSources
Repositories decide cache-first vs network-first strategy per use case

本地数据源（Local DataSource）封装所有Isar的
```
put
```
、
```
get
```
、
```
delete
```
、
```
watch
```
调用
仓储层负责协调远程和本地数据源
仓储层可根据不同使用场景决定采用缓存优先还是网络优先策略

Offline-First Patterns

离线优先模式

Cache-First: Read from Isar first, fetch from network in background, update Isar on success
Network-First: Fetch from network, fall back to Isar on failure
Write-Behind: Write to Isar immediately, sync to server asynchronously (queue pending changes)
Always show cached data immediately while refreshing in background

缓存优先：优先从Isar读取数据，后台发起网络请求，请求成功后更新Isar数据
网络优先：优先发起网络请求，请求失败时回退到Isar读取本地数据
写延后：立即写入Isar，异步同步到服务端（将待变更内容加入队列）
后台刷新数据时，始终优先立即展示已缓存的数据

Reactive Queries

响应式查询

Use Isar's
```
watchLazy()
```
or
```
watch()
```
to stream changes to the UI via BLoC
Wrap Isar watch streams in the repository and expose as
```
Stream<List<DomainModel>>
```
Dispose stream subscriptions properly in BLoC
```
close()
```
method

使用Isar的
```
watchLazy()
```
或
```
watch()
```
方法，通过BLoC向UI层发送变更流
在仓储层封装Isar监听流，对外暴露为
```
Stream<List<DomainModel>>
```
类型
在BLoC的
```
close()
```
方法中正确释放流订阅资源

Secure Storage

安全存储

Use
```
flutter_secure_storage
```
for sensitive key-value data (tokens, encryption keys)
Use
```
SharedPreferences
```
ONLY for non-sensitive user preferences (theme, locale, onboarding flags)
NEVER store passwords, tokens, or secrets in
```
SharedPreferences
```
or plain Isar

敏感键值对数据（令牌、加密密钥）使用
```
flutter_secure_storage
```
存储
仅非敏感用户偏好设置（主题、语言、新手引导标记）可以使用
```
SharedPreferences
```
存储
绝对不要在
```
SharedPreferences
```
或未加密的Isar中存储密码、令牌或密钥类信息