企业官网建设流程全解析

提到“Flutter for OpenHarmony二手物品置换App”这个组合，很多人第一反应是：跨端框架配国产系统，这条路到底走不走得通？我最近刚好把一个二手物品置换App跑在了OpenHarmony设备上，技术栈用Flutter，需求排期又急又密，整个项目从框架选型到落地过审用了将近一个季度。这中间给我教训最多的，不是UI适配，不是列表性能，反而是本地存储——一个看起来最简单、最不起眼的模块，在OpenHarmony上让我栽了不少跟头。

这篇文章把我在这个项目里关于本地存储的全部实践整理出来，包括存储方案怎么选、表结构怎么设计、加密怎么做、插件在OpenHarmony上怎么适配、踩过哪些坑。如果你也在做Flutter跨端、又需要对接OpenHarmony，尤其是二手置换、电商、社区类App的本地存储模块，这篇应该能帮你少走很多弯路。

1. 项目背景与存储需求拆解

1.1 二手置换App到底要存什么

先别急着谈技术选型，把需求盘清楚再说。二手物品置换App跟普通电商App的最大区别在于：用户画像复杂、商品生命周期长、发布流程重。这些特征直接决定了本地存储要承担的任务量。

我按功能模块梳理了一遍，需要落盘的本地数据大致有这几类：

• 用户会话信息：登录token、用户ID、昵称、偏好设置，这些是每次启动都要读的。
• 发布草稿：用户在发布页填了一半的商品标题、描述、图片路径、期望置换物品、联系方式。这是最容易弄丢、也最需要抢救的数据。
• 收藏列表：用户点了“想换”的商品ID集合，以及收藏时间。
• 浏览历史：用户最近看过的商品ID和浏览时间，用于足迹回看和推荐。
• 搜索记录：搜索关键词的历史，用于热搜词联想。
• 离线缓存：商品详情页的轻量缓存，弱网时先渲染缓存内容，再异步刷新。
• 消息回执：站内消息的本地标记，避免重复推送。

这些数据看起来零散，但它们有一个共同点：必须在用户关掉网络之后依然可读。这正是本地存储存在的意义。

1.2 数据的生命周期与分级

盘完之后你会发现，这些数据不是同等重要，更新频率也不一样。我习惯把它们分成三层，这个分层直接影响后面的技术选型。

• 高频轻量数据：设置项、搜索记录、收藏标记。特点是单条体积小、读写频繁，用Key-Value就够了。
• 结构化业务数据：发布草稿、浏览历史、离线商品缓存。特点是记录数多、有字段结构，需要关系模型，至少得支持复杂查询。
• 私密敏感数据：token、联系方式、聊天记录。特点是价值密度高、泄露影响大，必须加密存储。

如果一开始不分层，直接拿一个方案套所有需求，大概率会出问题：要么用KV存结构化数据导致查询很难写，要么用SQLite存配置项导致杀鸡用牛刀。我在项目初期就吃过这个亏，后面是在第一轮评审时被同事提醒，才赶紧重新分了层。

1.3 为什么本地存储是刚需而不是锦上添花

说句实在话，二手置换场景的用户，很多在通勤、地铁、电梯这种弱网环境里活动，指望每次打开App都走网络是不现实的。本地存储在这个业务里至少承担三件事：

第一是秒开体验。收藏夹、草稿箱这种页面，如果每次打开都要等接口，用户早就卸载了。第二是断网兜底。弱网时进商品详情，可以先把缓存内容渲染出来，再提示用户刷新。第三是数据保全。发布页写了半天的商品描述，因为来电、切后台就丢了，这是二手App里用户最不能忍的事。

所以本地存储不是“锦上添花”，而是这个业务形态的地基。尤其换到OpenHarmony这个新生态，插件不像Android那么现成，更要把这套地基设计得尽量独立、可替换。

2. 存储方案选型：在OpenHarmony上找平衡

2.1 Flutter生态里那几张牌

Flutter本地存储的主流方案，翻来覆去就是那几种，我来回权衡了好几轮：

• shared_preferences：官方维护的轻量KV，适合存设置项和标记位。缺点是value类型受限，只能存int、double、bool、String和StringList。
• sqflite：老牌关系数据库插件，基于SQLite，适合结构化数据。Android上很成熟，但OpenHarmony上需要找适配版本。
• hive：纯Dart实现的KV数据库，性能不错，无需原生依赖。缺点是有自己的一套二进制格式，数据调试不如SQL直观。
• drift / floor：基于sqflite的ORM框架，写起来确实舒服，但依赖链更长，在OpenHarmony上的兼容风险更大。
• isar：性能极佳，但维护状态不稳定，而且依赖native，不适合要过生态认证的场景。
• 文件存储：通过path_provider拿目录，直接写JSON、图片等文件，适合体积大、结构简单的数据。

这些方案各有各的优势，纸上谈兵很难分胜负，关键还得看OpenHarmony这边的现实约束。

2.2 OpenHarmony带来的四个现实约束

选择方案不能只看纸面能力，OpenHarmony这边有几个问题必须正视：

第一，插件生态不完善。很多常用Flutter插件在OpenHarmony上没有官方适配，社区适配版质量参差不齐，更新也慢。第二，XTS认证要求。App要上架官方市场，得过OpenHarmony的XTS兼容性认证，这会对插件使用、系统API调用做严格检查，不能随便调私有接口。第三，原生语言差异。OpenHarmony的原生开发是ArkTS，不是Kotlin，Android插件不能直接搬过来用，原生部分需要移植成ArkTS。第四，版本分裂。API版本、设备类型差异大，手机上跑得好好的代码，换个开发板可能就崩了。

这些约束叠加在一起，直接劝退了一堆“看起来很美好”的方案。

2.3 我的最终选型结论

纠结了很久，最后定下的组合是：

• shared_preferences的ohos适配版：存设置项、搜索记录、收藏标记这类轻量KV。
• sqflite的ohos适配版：存商品草稿、浏览历史、离线商品缓存，这些数据量大、需要查询。
• path_provider的ohos适配版：拿文件目录，存图片、大JSON。
• 自己封装一个StorageService：对上层业务屏蔽具体实现，将来就算换存储方案，业务代码不用动。

为什么不用hive？因为我们调试时会直接查数据库内容，KV格式不直观，而且hive的二进制格式出了问题很难修。为什么不用drift？依赖太重，OpenHarmony适配版没跟上，风险太大。宁愿自己写SQL和DAO，也就那几十行的事。

2.4 接口设计先于实现

这里有一个我认为很重要的心得：不管底层用什么，对业务层暴露的接口一定要先设计好。我当时定了这么几个方法组：

• KV组：setString、getString、remove、clear。
• DAO组：saveDraft、getDraftById、getAllDrafts、updateDraft、deleteDraft。
• 文件组：saveFile、readFile、deleteFile。
• 加密组：encrypt、decrypt。

业务层只依赖这组接口，完全不感知底层是SQLite还是Hive。后来有一次sqflite的ohos适配版踩到一个严重bug，我们一度想换成Hive，结果因为接口隔离做得好，只改了一个StorageServiceImpl文件，业务层零改动。这个钱花得值。

3. 数据模型设计与建表细节

3.1 商品草稿表

发布草稿是本地存储里最核心的数据。用户可能花了20分钟填一个商品，各种字段都填好了，还选了好几张图，结果一个来电切了后台。草稿表必须能完整保存发布页的所有状态。

我设计的表结构是：

CREATE TABLE draft ( id TEXT PRIMARY KEY, title TEXT, description TEXT, category_id TEXT, category_name TEXT, expect_item TEXT, price REAL, original_price REAL, trade_location TEXT, contact_phone TEXT, contact_wechat TEXT, image_paths TEXT, -- JSON数组：存放图片的本地路径和上传状态 status INTEGER DEFAULT 0, -- 0草稿 1已发布 created_at INTEGER, updated_at INTEGER );

几个关键点想提一下。image_paths用JSON数组存储，因为图片是文件，把本地路径存成字符串数组，渲染时直接用，上传进度也可以标注在JSON里。contact_phone和contact_wechat属于敏感字段，落地前要走加密列。price和original_price用REAL，避免整数定价丢失小数。status字段给“从草稿继续发布”留了一个状态位，这样就算用户发了两次商品，也能追溯哪些草稿已经转成正式商品了。

3.2 收藏与浏览历史表

收藏表和浏览历史表是典型的“以商品ID为中心”的轻量表，但量一大起来，索引和去重要想清楚。

CREATE TABLE favorite ( id INTEGER PRIMARY KEY AUTOINCREMENT, goods_id TEXT NOT NULL, goods_title TEXT, goods_cover TEXT, created_at INTEGER ); CREATE UNIQUE INDEX idx_favorite_goods ON favorite(goods_id); CREATE TABLE browse_history ( id INTEGER PRIMARY KEY AUTOINCREMENT, goods_id TEXT NOT NULL, goods_title TEXT, goods_cover TEXT, browse_time INTEGER ); CREATE INDEX idx_browse_time ON browse_history(browse_time DESC);

设计说明：favorite表的goods_id加唯一索引，防止用户手滑连点收藏写进两条重复数据。业务上即使先查后插，也存在并发窗口，直接在数据库层约束最稳。browse_history不做唯一约束，因为用户会重复浏览同一个商品，我们要记录“最近一次浏览时间”。查询时按browse_time倒序即可。数据量大了之后，可以加个策略：每个商品只保留最近一条浏览记录。

goods_title和goods_cover冗余进表，是典型的空间换时间做法。查列表时直接读本地缓存字段，不用再回源接口。

3.3 用户信息与会话缓存

用户表其实没什么可炫技的，关键就是别把token和用户资料存到同一个明文表里。我的做法是用户资料放SQLite，token单独走加密存储。

CREATE TABLE user_profile ( user_id TEXT PRIMARY KEY, nickname TEXT, avatar_path TEXT, updated_at INTEGER );

token不走SQLite，而是单独放在加密后的存储区域。这样万一数据库文件被拖走，token不会跟着一起漏。很多新手容易忽略这点，觉得都是“本地数据”就一起存了，其实敏感等级完全不同。

3.4 所有表都预留同步字段

本地库既然要承担离线能力，就一定要考虑将来和云端同步。我给所有业务表都预留了三个字段：sync_status（0未同步、1已同步、2冲突）、server_id（云端ID）、updated_at（本地最后修改时间）。

这一步当时看起来像超前设计，但在二手置换这种“可能换设备、可能删App重装”的场景里，以后做云同步时会省很多事。数据双写、冲突合并、增量拉取都是绕不开的话题，表里预留好位置，能少改一轮数据库迁移。

4. 核心实现：从初始化到增删改查

4.1 依赖配置

在pubspec.yaml里把依赖写上。注意一定要用ohos适配的包名，我们当时用的是社区维护的适配版，写法大致是这样：

dependencies: flutter: sdk: flutter shared_preferences_ohos: ^x.y.z sqflite_ohos: ^x.y.z path_provider_ohos: ^x.y.z path: ^x.y.z encrypt: ^x.y.z pointycastle: ^x.y.z

实际包名和版本号以你拉到的为准，这里不写死。提醒一句：别图省事直接依赖Android版的sqflite，在OpenHarmony上跑起来报MissingPluginException的概率几乎是100%。

4.2 初始化流程

我封装了一个LocalStorageManager，在App启动时统一初始化。初始化要做的几件事：创建数据库、建表、加载加密密钥、预热KV缓存。

class LocalStorageManager { static Database? _db; static SharedPreferences? _prefs; static Future<void> init() async { WidgetsFlutterBinding.ensureInitialized(); _prefs = await SharedPreferences.getInstance(); final dbPath = await getDatabasesPath(); _db = await openDatabase( p.join(dbPath, 'second_hand.db'), version: 1, onCreate: (db, version) async { await db.execute(CREATE_TABLE_DRAFT); await db.execute(CREATE_TABLE_FAVORITE); await db.execute(CREATE_TABLE_BROWSE_HISTORY); await db.execute(CREATE_TABLE_USER_PROFILE); }, ); } static Database get db => _db!; static SharedPreferences get prefs => _prefs!; }

有个细节必须强调：openDatabase的onCreate只在数据库不存在时执行。如果后期要改表结构，要通过onUpgrade里写ALTER TABLE，并把version加1。千万别图省事删库重建，用户本地数据会全没。

4.3 商品草稿的保存与恢复

草稿DAO我单独写了DraftDao，不看业务代码，只做数据库操作。保存草稿要支持“存在就更新、不存在就插入”，避免发布页每次自动保存产生一堆重复草稿。

class DraftDao { static Future<void> upsertDraft(Draft draft) async { final db = LocalStorageManager.db; final now = DateTime.now().millisecondsSinceEpoch; await db.insert('draft', draft.toMap() ..['updated_at'] = now ..['created_at'] = now, conflictAlgorithm: ConflictAlgorithm.replace); } static Future<Draft?> getDraftById(String id) async { final db = LocalStorageManager.db; final rows = await db.query('draft', where: 'id = ?', whereArgs: [id], limit: 1); if (rows.isEmpty) return null; return Draft.fromMap(rows.first); } static Future<List<Draft>> getAllDrafts() async { final db = LocalStorageManager.db; final rows = await db.query('draft', orderBy: 'updated_at DESC'); return rows.map(Draft.fromMap).toList(); } }

使用ConflictAlgorithm.replace这个点要当心：它本质上是delete加insert，如果表里有外键关联，关联数据可能被连带删掉。我的draft表没有外键，所以没问题。如果你的草稿表关联了图片表，建议先update，捕获到受影响行数为0再insert，这样更稳。

恢复草稿的页面逻辑很简单：进入发布页时先查draft表，有草稿就弹提示，引导用户“继续上次未完成的发布”。因为草稿保存得全，用户点继续时，所有字段和图片路径都可以原样回填，体感就是“App没让我重新填过”。

4.4 浏览历史的增量写入

浏览历史是高频写操作，不能每次浏览都全量查库。我的做法是：进入详情页时插入一条历史记录。为了让表不会无限膨胀，我加了一个裁剪逻辑：超过500条时，删除最旧的那批。

static Future<void> addBrowseRecord(BrowseRecord record) async { final db = LocalStorageManager.db; await db.insert('browse_history', record.toMap()); await trimIfNeeded(db, maxRows: 500); } static Future<void> trimIfNeeded(Database db, {int maxRows = 500}) async { final count = Sqflite.firstIntValue( await db.rawQuery('SELECT COUNT(*) FROM browse_history'))!; if (count > maxRows) { await db.rawDelete( 'DELETE FROM browse_history WHERE id IN (SELECT id FROM browse_history ORDER BY browse_time ASC LIMIT ?)', [count - maxRows], ); } }

这个裁剪逻辑不复杂，但能在“保留足够历史”和“不让数据库膨胀”之间取一个平衡。500条对普通用户来说，大概能覆盖一个月的浏览足迹，足够了。

4.5 通过EventChannel和OpenHarmony原生层打交道

虽然绝大多数存储需求用插件就能解决，但有几个场景绕不开原生：获取系统级的存储路径、监听存储空间不足、获取设备唯一ID参与密钥生成。

这里用到了EventChannel。Flutter侧代码：

class NativeStorageBridge { static const EventChannel _storageEventChannel = EventChannel('app.second_hand/storage_events'); static const MethodChannel _methodChannel = MethodChannel('app.second_hand/storage_methods'); static void listenStorageEvents() { _storageEventChannel.receiveBroadcastStream().listen((event) { if (event == 'storage_low') { // 触发缓存清理 LocalStorageManager.cleanCache(); } }); } static Future<String?> getDeviceStoragePath() async { return await _methodChannel.invokeMethod<String>('getDefaultStoragePath'); } }

OpenHarmony原生侧（ArkTS）的职责是创建对应的EventChannel，监听系统存储变化事件，再通过channel把事件推给Flutter侧。这块桥的价值在于：把Flutter层的存储服务和系统底层的存储状况打通。比如OpenHarmony某些设备存储空间比较紧张，系统发出低存储广播后，App能及时清理本地缓存，避免被系统杀掉。

4.6 AES256敏感数据加密

token、联系方式这类字段，落库必须加密。我用的是encrypt这个纯Dart库封装的AES256 GCM模式。考虑到性能，只对敏感字段单独加密，不整表加密。

final key = Key.fromBase64(base64Key); // 在原生层生成并返回 final iv = IV.fromLength(16); final encrypter = Encrypter(AES(key, mode: AESMode.gcm)); String encryptText(String plainText) { return encrypter.encrypt(plainText, iv: iv).base64; } String decryptText(String cipherText) { return encrypter.decrypt64(cipherText, iv: iv); }

GCM模式自带认证标签，防篡改，比单纯的CBC更合适。有一点必须强调：不要把密钥硬编码写在Dart代码里，否则反编译就全暴露了。我在OpenHarmony上是通过MethodChannel调ArkTS层的通用密钥库能力生成密钥，存到系统安全区域，Flutter侧只拿密钥引用。如果你实在没有系统密钥库，至少也要把Key用类似Keystore的机制存起来，别放在assets里。

5. OpenHarmony专项适配与排坑实录

5.1 MissingPluginException这个老冤家

在OpenHarmony上跑Flutter项目，遇到的第一堵墙大概率是MissingPluginException。这个错误从表面看是插件没注册，根因是OpenHarmony的插件机制和Android不完全一样。

我排查一般按这个顺序走：

1. 看pubspec.yaml里依赖的是不是ohos适配版包名，很多插件是Android原版，在OpenHarmony上根本没有实现。
2. 检查插件工程里是否声明了OpenHarmony侧的映射关系。
3. 看运行日志里GeneratedPluginRegistrant有没有把插件注册进去，没注册就手动注册。
4. 查看插件的release版本是否滞后，有些社区适配版只支持旧版Flutter。

我因为一个内部工具插件一直报MissingPluginException，排查了半天，最后发现是插件在OpenHarmony侧只有MethodChannel，没实现EventChannel，而我在Flutter侧同时订阅了EventChannel，导致启动流程异常。这个教训就是：使用不熟悉的插件前，先读一遍README里的“支持范围”。

5.2 path_provider返回的路径跟预期不一样

在Android上，getApplicationDocumentsDirectory拿到的路径很直观。OpenHarmony上，path_provider的ohos适配版返回的路径会多一层应用沙箱目录。如果你习惯性拼一个相对路径直接写文件，很可能因为目录不存在直接抛异常。

后来我养成了一个习惯：拿路径后先自己mkdir创建目录，再做文件操作。不要默认目录已经存在。

final dir = await getApplicationDocumentsDirectory(); final targetDir = Directory(p.join(dir.path, 'app_images')); if (!targetDir.exists()) { targetDir.create(recursive: true); }

这个小习惯帮我避了好几次雷，不只是OpenHarmony，很多新设备的上层目录权限策略都在变，先建目录永远不亏。

5.3 中文乱码与编码问题

这个坑非常隐蔽。有一次我们从SQLite里读出的商品描述，英文正常，中文全是乱码。查了半天发现问题不在数据库，而在JSON序列化时没有指定UTF-8，导致中文文件名路径丢失。

统一规范是：所有文件读写、JSON编码，都显式指定utf8：

final jsonStr = jsonEncode(data); await file.writeAsString(jsonStr, encoding: utf8);

还有一个细节：draft的image_paths字段如果包含中文文件名，要注意不同设备对中文字符串的大小写归一化规则不同，别用中文路径做唯一索引。

5.4 database is locked

本地存储最常见的并发错误就是database is locked。在Flutter里，sqflite默认是单实例管理连接，但如果你有多个isolate同时访问数据库，很容易踩这个坑。

我遇到的具体场景是：后台isolate在同步云端数据，同时主isolate在自动保存草稿，两边同时写库，锁冲突就爆了。解决办法：

• 所有数据库操作都走同一个Database实例，不要在不同isolate里各自openDatabase。
• 如果必须跨isolate，用sqflite_common_ffi的DatabaseFactory，或者自己维护一个全局并发队列。
• 高频写操作合并成事务，减少锁竞争。

await db.transaction((txn) async { await txn.insert('draft', draftMap); await txn.insert('favorite', favMap); });

事务的好处不只是原子性，还能减少SQLite的锁切换次数。能合并的写操作尽量合并。

6. 性能优化与日常维护经验

6.1 别在UI线程里跑数据库操作

sqflite的异步接口虽然是异步的，但底层IO和线程调度在某些实现上会占用平台主线程。在OpenHarmony上这个问题更明显。我处理的原则是：所有DB操作包一层Isolate.run或compute，确认耗时操作不会卡掉页面帧率。

final drafts = await compute(fetchAllDrafts, null);

不过这里有一个反直觉的点：对于单条查询，compute的调度开销可能比直接查还慢。我的经验是，单条数据只查主键、调用不频繁时，直接调就行；批量查询、复杂查询、JOIN查询，才值得丢到后台isolate。

6.2 数据库版本的平滑升级

本地存储最大的噩梦是发版之后，用户手机上的旧数据库结构和新代码对不上。OpenHarmony上又不能像某些生态那样强制用户升级，所以升级逻辑一定要稳。

我的onUpgrade写法：

static Future<void> _onUpgrade(Database db, int oldVersion, int newVersion) async { if (oldVersion < 2) { await db.execute('ALTER TABLE draft ADD COLUMN exchange_method TEXT'); } if (oldVersion < 3) { await db.execute('CREATE TABLE search_history (...)'); } }

核心原则是：升级脚本按照oldVersion逐级递增，永远不要只写if (oldVersion < newVersion)。否则用户从1.0直接跳到1.2时，中间1.1的改动会被跳过，轻则缺列，重则整个App启动崩溃。

6.3 常见错误排查速查表

我把OpenHarmony本地存储开发中遇到的典型问题整理成了表格，方便直接对照排查。

6.4 缓存清理策略

二手置换App的离线缓存如果不管，很容易把用户存储空间吃光。我给缓存目录设置了一个总大小上限，比如200MB，超过就按最后访问时间从旧到新删除。这样即使离线缓存了很多商品图片，也不至于造成灾难。

Future<void> cleanCacheIfNeeded() async { final cacheDir = await getTemporaryDirectory(); final totalSize = await _getDirSize(cacheDir); if (totalSize > 200 * 1024 * 1024) { await _deleteOldestFiles(cacheDir); } }

这里用的是临时目录而不是文档目录，语义上更合适——缓存本来就是“可随时清空”的数据，临时目录在系统空间紧张时还可能被系统自动清理，正好符合缓存的性质。

最后再分享一点个人体会。做一个OpenHarmony上的Flutter应用，跟Android最大的不同，就是很多问题没有现成答案，只能自己去读插件源码、看原生侧实现。但恰恰是这个过程，逼着我把以前在Android上“能用就行”的模糊认知重新过了一遍。SQLite的事务、索引、字段类型这些，在OpenHarmony上都是一样的通用知识，只是换了一套机制和约束。

如果让我给后来者一句话建议：本地存储层一定要做好接口隔离，因为你根本不知道明天哪个插件版本会翻车。存储方案、数据库版本、加密策略都要留出替换空间。这个二手置换App的本地存储模块，前前后后改了四轮，最终稳定下来的，正是刚开始打地基时留下的那点余地。