第19篇云数据库——端云数据同步HarmonyOS 的云数据库Cloud DB提供了端云一致的数据存储方案支持数据在本地和云端之间自动同步实现跨设备数据共享。本篇以柚兔学伴项目为例讲解如何使用kit.CloudFoundationKit中的cloudDatabase模块完成云端数据的查询、插入与更新操作。1. 云数据库基础概念1.1 云数据库 vs 本地 RDB特性云数据库 (Cloud DB)本地 RDB数据存储位置云端 本地缓存仅本地跨设备同步支持不支持网络依赖首次查询需联网无适用场景用户共享数据、跨设备同步离线数据、本地缓存数据类型DatabaseObject 子类ValuesBucket在柚兔学伴中AI 工具卡片Tool、用户单词本Word、长难句Sentence都存储在云数据库中实现不同设备间的学习数据同步。1.2 核心对象关系cloudDatabase.zone(name) → DatabaseZone (数据区域) DatabaseQueryT(Class) → DatabaseQuery (查询条件) DatabaseZone.query(condition) → T[] (查询结果) DatabaseZone.upsert(data) → number (插入/更新)2. 获取 DatabaseZone 实例所有云数据库操作都从获取DatabaseZone开始需要指定区域名称import{cloudDatabase}fromkit.CloudFoundationKit;import{UrlConstants}fromnetwork;agcDataBase:cloudDatabase.DatabaseZonecloudDatabase.zone(UrlConstants.ZONE_NAME);其中ZONE_NAME在UrlConstants中定义为常量exportclassUrlConstants{staticreadonlyZONE_NAME:stringPartner}注意区域名称需与 AGC 控制台中配置的云数据库区域名称一致。3. 定义云对象类型云数据库中的每张表对应一个继承自cloudDatabase.DatabaseObject的类通过naturalbase_ClassName()方法指定表名3.1 ToolAI 工具卡片import{cloudDatabase}fromkit.CloudFoundationKit;classToolextendscloudDatabase.DatabaseObject{id:number|undefined;name:string;cover:string;num:string|undefined;type:string|undefined;naturalbase_ClassName():string{returnTool;}}export{Tool};3.2 Word单词卡片classWordextendscloudDatabase.DatabaseObject{id:number|undefined;name:string|undefined;ttsUrl:string|undefined;pronunciation:string|undefined;means:string|undefined;userId:string|undefined;publicnaturalbase_ClassName():string{returnWord;}}export{Word};3.3 Sentence长难句classSentenceextendscloudDatabase.DatabaseObject{id:number|undefined;src:string|undefined;dst:string|undefined;ttsUrl:string|undefined;userId:string|undefined;publicnaturalbase_ClassName():string{returnSentence;}}export{Sentence};设计要点naturalbase_ClassName()返回的名称必须与 AGC 控制台中定义的表名完全一致字段名与云数据库表中的列名对应userId字段用于实现用户维度的数据隔离4. 查询数据4.1 ChatView查询 Tool 列表在聊天首页加载所有 AI 工具卡片不需要按用户过滤Componentexportstruct ChatView{agcDataBase:cloudDatabase.DatabaseZone|undefinedundefined;condition:cloudDatabase.DatabaseQuerycloudDatabase.DatabaseObject|undefinedundefined;StatecardList:Tool[][]asyncaboutToAppear():Promisevoid{this.agcDataBasecloudDatabase.zone(UrlConstants.ZONE_NAME);this.getCardList()}asyncgetCardList(){letconditionnewcloudDatabase.DatabaseQuery(Tool);try{this.cardListawaitthis.agcDataBase!!.query(condition)hilog.info(0x0000,testTag,Succeeded in querying data, result:${JSON.stringify(this.cardList)});}catch(err){hilog.error(0x0000,testTag,Failed to query data, code:${err.code}, message:${err.message});}}}查询流程new cloudDatabase.DatabaseQuery(Tool)创建以 Tool 类为模板的查询条件不添加任何条件表示查询所有记录agcDataBase.query(condition)执行查询返回Tool[]数组4.2 WordCardPage按用户查询单词单词本需要只显示当前用户的单词通过condition.equalTo(userId, uuid)实现数据隔离Componentstruct WordCardPage{agcDataBase:cloudDatabase.DatabaseZonecloudDatabase.zone(UrlConstants.ZONE_NAME);condition:cloudDatabase.DatabaseQuerycloudDatabase.DatabaseObject|undefinedundefined;StatewordList:Word[][]aboutToAppear():void{this.getWordList().then((wordList:Word[]){this.wordListwordList})}asyncgetWordList():PromiseWord[]{try{this.conditionnewcloudDatabase.DatabaseQuery(Word);letuuidawaitUserInfoManager.getUserInfo()?.unionIDthis.condition.equalTo(userId,uuid)returnawaitthis.agcDataBase?.query(this.condition)asWord[]}catch(err){return[]}}}用户数据隔离的关键步骤通过UserInfoManager.getUserInfo()?.unionID获取用户唯一标识condition.equalTo(userId, uuid)添加等值查询条件查询结果只包含当前用户的单词数据4.3 SentenceCardPage按用户查询长难句查询模式与 WordCardPage 完全一致仅将类型替换为SentenceComponentstruct SentenceCardPage{agcDataBase:cloudDatabase.DatabaseZonecloudDatabase.zone(UrlConstants.ZONE_NAME);condition:cloudDatabase.DatabaseQuerycloudDatabase.DatabaseObject|undefinedundefined;StatesentenceList:Sentence[][]asyncgetWordList():PromiseSentence[]{try{this.conditionnewcloudDatabase.DatabaseQuery(Sentence);letuuidawaitUserInfoManager.getUserInfo()?.unionIDthis.condition.equalTo(userId,uuid)returnawaitthis.agcDataBase?.query(this.condition)asSentence[]}catch(err){return[]}}}5. 插入与更新数据5.1 upsert 操作upsert是云数据库提供的插入或更新操作——如果记录已存在则更新不存在则插入。在ChatView中可以看到注释中的 upsert 用法// 更新卡片点击次数data.num(parseInt(data.num!!)1).toString()this.agcDataBase!!.upsert(data).then((num:number){this.getCardList()}).catch((err:BusinessError){err})5.2 创建新的云对象添加长难句时创建Sentence实例并设置字段值letsentencenewSentence();sentence.srcthis.model.resultData.result!!.trans_result!![0].src sentence.dstthis.model.resultData.result!!.trans_result!![0].dst sentence.ttsUrlthis.model.resultData.result!!.trans_result!![0].dst_tts sentence.userIdUserInfoManager.getUserInfo()?.unionID// this.agcDataBase.upsert(sentence) // 插入到云端步骤new Sentence()创建空的云对象实例设置各字段值特别是userId确保数据归属agcDataBase.upsert(sentence)将数据写入云数据库6. 错误处理云数据库操作涉及网络请求必须做好错误处理。项目中采用try/catch包裹查询操作asyncgetCardList(){letconditionnewcloudDatabase.DatabaseQuery(Tool);try{this.cardListawaitthis.agcDataBase!!.query(condition)hilog.info(0x0000,testTag,Succeeded in querying data, result:${JSON.stringify(this.cardList)});}catch(err){hilog.error(0x0000,testTag,Failed to query data, code:${err.code}, message:${err.message});}}对于非关键数据如单词列表查询失败时返回空数组asyncgetWordList():PromiseWord[]{try{this.conditionnewcloudDatabase.DatabaseQuery(Word);letuuidawaitUserInfoManager.getUserInfo()?.unionIDthis.condition.equalTo(userId,uuid)returnawaitthis.agcDataBase?.query(this.condition)asWord[]}catch(err){return[]}}错误处理建议场景处理方式关键数据查询失败使用hilog.error记录UI 显示错误提示非关键数据查询失败返回空数组UI 显示暂无数据写入操作失败catch中提示用户重试网络不可用结合本地缓存提供离线体验7. UI 数据绑定查询结果直接绑定到State变量实现数据驱动 UI 更新StatecardList:Tool[][]BuilderCardLayout(){Grid(this.scroller){ForEach(this.cardList,(data:Tool,index:number){GridItem(){Column(){Column({space:5}){Row(){Text(data.name).fontWeight(FontWeight.Bold).fontColor(Color.White);Text(复习记忆).fontSize(10).fontColor(Color.White)}.width(100%).justifyContent(FlexAlign.SpaceBetween);}.width(100%).padding(10)}.backgroundImage(data.cover).width(100%).aspectRatio(1);}.onClick((){if(index1){this.pageContext.openPage({routerName:WordCardPage},true);}elseif(index0){this.pageContext.openPage({routerName:SentenceCardPage},true);}});});}.columnsTemplate(1fr 1fr).columnsGap(10).rowsGap(10)}单词列表页面无数据时显示空状态if(this.wordList.length0){Column({space:15}){Image($r(app.media.ic_no_data)).width(50)Text(点击对话记录中的单词可添加到单词卡片).fontSize(12)Text(暂无单词卡片).fontColor($r(app.color.color_divider)).fontSize(12)}.layoutWeight(1).justifyContent(FlexAlign.Center)}else{List({space:10}){ForEach(this.wordList,(word:Word,index:number){ListItem(){Column({space:10}){Row({space:5}){Text(word.name).fontWeight(FontWeight.Bold).fontSize(18)Image($r(app.media.ic_listening)).width(24).onClick((){this.model.download(word.ttsUrl!!).then((name:string){AudioUtils.getInstance().startPlay(getContext(this).cacheDirname)})})Blank()}.width(100%)Text(word.pronunciation).fontSize(12).width(100%)Text(word.means).fontSize(14).fontStyle(FontStyle.Italic)}.padding(12).alignItems(HorizontalAlign.Start)}.backgroundColor($r(app.color.color_card)).borderRadius(12)})}.layoutWeight(1)}8. DatabaseQuery 条件构建DatabaseQuery支持多种条件构建方式方法说明示例equalTo(field, value)等值查询condition.equalTo(userId, uuid)lessThan(field, value)小于condition.lessThan(age, 18)greaterThan(field, value)大于condition.greaterThan(score, 60)orderByDesc(field)降序排列condition.orderByDesc(date)orderByAsc(field)升序排列condition.orderByAsc(name)limit(count)限制返回数量condition.limit(10)多条件组合可以链式调用多个条件方法letconditionnewcloudDatabase.DatabaseQuery(Word);condition.equalTo(userId,uuid).orderByDesc(name).limit(20);小结本篇围绕 HarmonyOS 云数据库的核心操作展开讲解连接云数据库cloudDatabase.zone(name)获取DatabaseZone实例定义云对象继承DatabaseObject实现naturalbase_ClassName()指定表名查询数据DatabaseQueryT构建条件 →zone.query(condition)执行查询数据隔离condition.equalTo(userId, uuid)实现用户维度过滤写入数据zone.upsert(data)实现插入或更新错误处理try/catch包裹异步操作查询失败返回空数组UI 绑定查询结果直接赋值State变量驱动界面自动刷新云数据库为柚兔学伴实现了单词本、长难句等学习数据的端云同步用户在不同设备上都能获取一致的学习进度。