一、引言

在 Harmony OS NEXT / 5.0 / API 12+ 版本的应用开发中，对音频数据进行高效管理是许多应用场景的需求。本文将深入介绍如何借助 HarmonyOS ArkUI 框架、@kit.ArkData/relationalStore（SQLite 封装）数据库以及 ArkTS 语言，通过自定义 InterviewAudioItem 数据模型，实现对音频数据的全面管理。

二、适用版本说明

本文所阐述的音频数据管理方案专为 Harmony OS NEXT / 5.0 / API 12+ 版本设计。这些版本为开发者提供了稳定且丰富的 API 支持，确保数据库操作、界面开发以及数据模型构建等功能能够顺利实现与优化。

三、技术栈剖析

1. HarmonyOS ArkUI：它就像是应用的 “舞台搭建师”，负责构建用户界面，为用户与音频数据管理功能的交互提供直观的展示平台。通过 ArkUI，开发者可以轻松创建美观、易用的界面元素，提升用户体验。
2. @kit.ArkData/relationalStore（SQLite 封装）：这是管理音频数据的 “数据保险箱”，基于 SQLite 进行封装，为开发者提供了便捷的关系型数据库操作接口。就像有了一个功能强大的仓库管理员，能高效地对音频数据进行存储、读取、修改和删除等操作。
3. ArkTS：作为编程语言，是整个项目的 “建筑师”，它将各个部分有机地结合在一起。通过 ArkTS，开发者能够编写逻辑清晰、结构严谨的代码，实现音频数据管理的各种功能。
4. 自定义 InterviewAudioItem 数据模型：这是音频数据的 “蓝图”，定义了音频数据的结构，包括 id、user_id、name、path、duration 和 size 等属性，确保音频数据以统一、规范的格式进行存储和处理。

四、封装工具源码解读

// 导入关系型数据库模块
import { relationalStore } from "@kit.ArkData";
// 导入音频数据模型
import { InterviewAudioItem } from "../../models";

// 定义 AudioDB 类，用于管理音频数据的数据库操作
class AudioDB {
    // 数据库存储实例
    store?: relationalStore.RdbStore;
    // 数据库表名
    tableName: string = 'interview_audio';

    // 初始化数据库存储实例
    async initStore() {
        // 获取应用上下文
        const ctx = AppStorage.get<Context>('context');
        if (ctx) {
            // 创建或获取数据库存储实例
            const store = await relationalStore.getRdbStore(getContext(this), {
                name: 'audio.db',
                securityLevel: relationalStore.SecurityLevel.S1
            });
            // 执行 SQL 语句，创建音频数据表
            await store.executeSql(
                `CREATE TABLE IF NOT EXISTS ${this.tableName} (
                    id INTEGER PRIMARY KEY AUTOINCREMENT,
                    user_id TEXT NOT NULL,
                    name TEXT NOT NULL,
                    path TEXT NOT NULL,
                    duration INTEGER NOT NULL,
                    size INTEGER NOT NULL)`
            );
            // 将数据库存储实例赋值给类的属性
            this.store = store;
        }
    }

    // 插入音频数据
    async insertStore(audio: InterviewAudioItem) {
        if (this.store) {
            // 插入音频数据
            const res = await this.store.insert(this.tableName, audio);
            if (res === -1 || res === undefined) {
                // 插入失败，返回拒绝的 Promise
                return Promise.reject('插入失败');
            } else {
                // 插入成功，返回解决的 Promise
                return Promise.resolve('插入成功');
            }
        }
        // 数据库未初始化，返回拒绝的 Promise
        return Promise.reject('插入失败');
    }

    // 删除音频数据
    async deleteStore(audioId: number) {
        if (this.store) {
            // 创建删除条件
            const perdicates = new relationalStore.RdbPredicates(this.tableName);
            perdicates.equalTo('id', audioId);
            // 执行删除操作
            const rowId = await this.store.delete(perdicates);
            if (rowId === -1 || rowId === undefined) {
                // 删除失败，返回拒绝的 Promise
                return Promise.reject('删除失败');
            } else {
                // 删除成功，返回解决的 Promise
                return Promise.resolve('删除成功');
            }
        }
        // 数据库未初始化，返回拒绝的 Promise
        return Promise.reject('删除失败');
    }

    // 更新音频数据
    async updateStore(audio: InterviewAudioItem) {
        if (this.store) {
            // 创建更新条件
            const perdicates = new relationalStore.RdbPredicates(this.tableName);
            perdicates.equalTo('id', audio.id);
            // 执行更新操作
            const rowId = await this.store.update(audio, perdicates);
            if (rowId === -1 || rowId === undefined) {
                // 更新失败，返回拒绝的 Promise
                return Promise.reject('修改失败');
            } else {
                // 更新成功，返回解决的 Promise
                return Promise.resolve('修改成功');
            }
        }
        // 数据库未初始化，返回拒绝的 Promise
        return Promise.reject('修改失败');
    }

    // 查询音频数据
    async queryStore() {
        if (this.store) {
            // 创建查询条件
            const perdicates = new relationalStore.RdbPredicates(this.tableName);
            // 执行查询操作
            const resultSet = await this.store.query(perdicates);
            if (!resultSet) {
                // 查询失败，返回拒绝的 Promise
                return Promise.reject('查询失败');
            }
            // 遍历查询结果，将数据存入列表
            const list: InterviewAudioItem[] = [];
            while (resultSet?.goToNextRow()) {
                list.push(resultSet.getRow() as InterviewAudioItem);
            }
            // 关闭结果集
            resultSet.close();
            // 返回查询结果
            return Promise.resolve(list);
        }
        // 数据库未初始化，返回拒绝的 Promise
        return Promise.reject('查询失败');
    }
}

// 导出 AudioDB 实例
export const audioDB = new AudioDB();

1. 类 AudioDB：这是音频数据管理的 “核心控制中心”，封装了所有与音频数据相关的数据库操作方法，方便在应用的不同地方复用。
   • store 属性：用于存储数据库实例，就像一个 “数据仓库指针”，指向实际的数据库存储位置。
   • tableName 属性：定义了数据库表名，如同给 “数据仓库” 中的一个特定区域命名，方便对音频数据进行集中管理。
2. initStore 方法：数据库初始化的 “启动器”。
   • 首先获取应用上下文 ctx，这就像是找到应用的 “大本营”，为后续操作提供环境支持。
   • 通过 relationalStore.getRdbStore 创建或获取数据库存储实例，设置数据库名称为 audio.db 以及安全级别为 SecurityLevel.S1。
   • 执行 SQL 语句创建音频数据表，规定了数据的存储结构。如果这一步 SQL 语句写错，就好比建房子的图纸画错，会导致建表失败。
   • 最后将数据库存储实例赋值给 store 属性，完成初始化。
3. insertStore 方法：数据插入的 “搬运工”。
   • 检查数据库实例是否存在，若存在则执行插入操作。
   • 根据返回结果判断插入是否成功，若返回 -1 或 undefined，说明插入失败，返回拒绝的 Promise；否则返回解决的 Promise。如果数据库未初始化，也返回插入失败的结果。
4. deleteStore 方法：数据删除的 “清洁工”。
   • 同样先检查数据库实例。
   • 创建 RdbPredicates 对象作为删除条件，这里通过 equalTo 方法指定要删除的音频数据的 id。
   • 根据删除操作的返回结果判断是否成功，处理方式与插入操作类似。
5. updateStore 方法：数据更新的 “修改器”。
   • 检查数据库实例后，创建 RdbPredicates 对象设置更新条件，根据音频数据的 id 进行更新。
   • 根据更新操作的返回结果判断是否成功，返回相应的 Promise。
6. queryStore 方法：数据查询的 “搜索器”。
   • 检查数据库实例后，创建查询条件。
   • 执行查询操作获取结果集，如果结果集不存在则返回查询失败的 Promise。
   • 遍历结果集，将查询到的数据存入列表，最后关闭结果集并返回查询结果。如果忘记关闭结果集，就像打开了仓库的门却没关上，可能会导致资源浪费或其他问题。

五、核心技术实现细节

1. 数据库的初始化：initStore 方法是数据库初始化的关键。通过获取应用上下文，创建或获取数据库实例，并执行 SQL 语句创建音频数据表。这一系列操作就像为音频数据搭建了一个专属的 “数据仓库”，为后续的数据操作提供了基础架构。
2. 数据插入操作：insertStore 方法负责将音频数据插入到数据库表中。它直接使用数据库实例的 insert 方法，不需要谓词对象（这是与其他操作的不同点），并根据返回结果判断插入是否成功，确保数据准确无误地进入 “数据仓库”。
3. 数据删除操作：deleteStore 方法通过创建谓词对象，设置删除条件（这里是根据音频数据的 id），然后执行删除操作。谓词对象就像一个 “筛选器”，准确地找到要删除的数据，保证只删除指定的数据。
4. 数据更新操作：updateStore 方法同样利用谓词对象设置更新条件（基于音频数据的 id），对数据库中的音频数据进行更新。它确保只有符合条件的数据被修改，维护了数据的准确性和一致性。
5. 数据查询操作：queryStore 方法创建谓词对象作为查询条件，执行查询操作获取结果集。然后遍历结果集，将数据整理成列表返回。在这个过程中，关闭结果集是很重要的一步，避免资源占用。

六、核心易错点及解决方案

1. 初始化时上下文获取与 SQL 语句：初始化时必须先正确获取应用上下文，否则无法创建数据库实例。同时，SQL 语句要确保准确无误，任何语法错误都可能导致建表失败。在编写 SQL 语句时，建议仔细检查每个字段的定义和约束条件。
2. 操作结果处理：所有数据库操作返回 -1 或 undefined 都意味着操作失败，需要在代码中妥善处理这些情况，给用户提供明确的反馈，比如显示错误提示信息。
3. 结果集关闭：查询操作完成后，务必关闭结果集，避免资源浪费和潜在的内存泄漏问题。可以在查询方法的最后添加关闭结果集的代码，形成良好的编程习惯。
4. 谓词对象使用：除了插入操作，其他数据库操作（删除、更新、查询）都需要使用谓词对象来指定条件。在使用谓词对象时，要确保条件设置准确，否则可能导致误操作，比如删除或更新了错误的数据。

七、优化方向探讨

1. 缺乏事务支持：当前方案缺乏事务支持，在进行批量操作时可能会出现原子性缺失的问题，就好比搬一堆东西，可能只搬了一部分就中断了，导致数据不一致。解决方案是集成 beginTransaction/commit 事务 API，确保一组数据库操作要么全部成功，要么全部失败，就像把这堆东西一次性完整地搬走。
2. 无数据加密：存在敏感信息泄露风险，尤其是在处理一些包含用户隐私的音频数据时。启用 SecurityLevel.S2（硬件级加密）可以为数据加上一层坚固的 “保护锁”，防止数据被非法获取和篡改。
3. 索引未优化：在大数据量查询时，性能可能会受到影响。为 user_id 和 path 字段创建复合索引，就像给数据仓库建立了一个高效的 “索引目录”，可以大大提高查询速度，快速定位到所需的数据。

八、总结

本文通过 AudioDB 类实现了对音频数据的全面管理，涵盖数据库初始化、插入、删除、更新和查询等核心功能。底层借助 @kit.ArkData 的 relationalStore 模块，结合 TypeScript 语言，为音频数据持久化存储提供了有效的解决方案。

在实际应用中，如语音面试记录管理、音频文件资源库等场景，该方案能够满足对音频数据的基本管理需求。然而，为了使应用更加健壮和安全，需要注意上述提到的易错点，并根据实际情况进行优化。

关于 HarmonyOS 音频数据管理的更多技巧和优化实践，我会在后续博客中持续分享，感兴趣的话欢迎关注。对于本文介绍的音频数据管理方案，你有什么疑问或者想法吗？欢迎随时交流。