网络与数据:HTTP、数据持久化与首选项
本篇要点:把“一个能联网的列表页”拆成可复用、可离线、可排错的四层数据通路,并用 ArkTS 把每层写完。 前置文章:《页面导航与路由:Navigation、路由与参数》讲的是页面怎么跳、参数怎么带过去;这一章接着回答跳过去之后,页面里的数据从哪里来、放在哪里。
为什么需要它
去年冬天我接手改一个笔记应用的列表页。原代码在 aboutToAppear 里发请求,拿回 JSON,赋给 this.list,四十行,跑了半年没出事。后来团队把这套写法复制到了十一个页面。
上线前一周,三个问题一起出现。
第一件,弱网。地铁里点进详情,转圈转到用户放弃。http 的 connectTimeout 默认 60000 毫秒,readTimeout 也是 60000 毫秒,一分钟才失败。用户不会等一分钟,他会杀掉应用。
第二件,断网重进。第二次打开,列表是空的。因为上一次的数据只活在内存里,进程一结束就没了。运营看到的数据是“用户打开就退出”。
第三件,返回再进,列表里出现了重复项,还有两条标题和内容对不上。
三个现象是三件事,根因是同一件:这个页面里没有“数据层”。请求、序列化、缓存、状态更新四件事被压在同一个组件里,任何一件出问题,能改的只有这个组件。
版本先钉住。截至 2026 年 11 月,本篇基线是 HarmonyOS 6.0.0(API 20,2025 年 9 月 25 日 Release)配 DevEco Studio 6.0.0,这也是多数在售机型的稳定线。http 属于 @kit.NetworkKit,relationalStore 与 preferences 属于 @kit.ArkData,两者都从 API 9 起可用。接口签名以官方文档中心的网络与数据管理分区为准,这一章只对 API 20 这条基线负责。
核心概念
1. HTTP 客户端:把“发请求”收成一个对象
HTTP 客户端(HTTP Client)指封装了连接、超时、请求头、错误码的请求对象。ArkTS 里 http.createHttp() 返回一个 HttpRequest,一个实例对应一次请求,用完调 destroy()。
拦截器(Interceptor)是请求出门前和回来后都要经过的一道处理。用快递柜打比方:包裹进柜之前先过一台分拣台,贴单号、查违禁品;取件的时候再核对一次身份。分拣台就是拦截器,业务代码只管“寄什么”,不管“怎么寄”。
反例很常见:十一个页面各自拼请求头。某天服务端要求带 X-App-Version,你要改十一个文件,漏掉的那个页面开始收到 403,而日志里只写“请求失败”。
这里要说清一件事:http 模块本身没有拦截器接口。API 12 起的 Remote Communication Kit(@kit.RemoteCommunicationKit,简称 RCP)提供了 rcp.Session 和可挂载的拦截器,但它的签名在不同小版本之间有过调整,这一章不用它。我手写一条二十行的拦截链,行为可读、可断点、可单测。
2. 序列化:JSON.parse 交给你的不是你的类型
序列化(Serialization)是把内存对象变成字节流,反序列化(Deserialization)是反过来。ArkTS 里 JSON.parse(text) 的返回值是 Object,不是 Note。
类比报关单:单子上的栏目名对得上,不代表填的内容对得上。海关不会因为你的表头写着“重量”就相信里面填的是数字。
反例:const note = JSON.parse(text) as Note; 编译通过,运行时服务端少给了 updatedAt,note.updatedAt 是 undefined,new Date(undefined) 得到 Invalid Date,界面显示“Invalid Date”,排查方向被带到了时区上。
as 的含义是“我保证它是”,而服务端从来不做保证。正确写法是显式映射,见动手实践第 2 步。
3. 三层持久化:什么该放哪
鸿蒙给应用三块地方存数据,选错会以运行时错误的形式找上门。
| 方式 | 形态与容量 | 适合放 | 不适合放 | 硬限制 |
|---|---|---|---|---|
| 首选项 Preferences | 键值对,内存缓存 + 单个落盘文件 | 开关、登录态 token、上次同步时间、排序偏好 | 列表数据、图片、日志 | key ≤ 80 字节,value ≤ 8192 字节 |
| 关系型数据库(Relational Database,RDB) | SQLite 表 + 索引,可到 GB 级 | 笔记、订单、消息这类有结构、要按条件查的数据 | 大二进制、全文检索 | 需自己写建表与版本迁移 |
| 应用文件 | 沙箱目录里任意文件 | 图片、导出包、大 JSON 缓存、崩溃日志 | 需要事务的关联数据 | 路径必须用 context.filesDir 一类目录 |
反例:把 200 条笔记拼成一个 JSON 塞进首选项,前两条能写进去,第三条失败。value 上限 8192 字节,这个数在代码补全里看不到,只有运行到那一步才报。
4. 单向数据流:仓库是唯一能改数据的地方
仓库(Repository)是数据访问的唯一入口。对上它只暴露“取一页”“加一条”“删一条”,对下它决定这次读缓存还是走网络。
图 5-1 笔记应用的数据层调用链
如图 5-1 所示,组件只认识仓库,仓库只认识三个数据源。这条链的价值在于出问题时能定位:界面空白去看 @Local,数据为空去看仓库的缓存判断,请求慢去看 HttpClient 的超时。
反例:组件 A 直接读 RDB,组件 B 直接发 HTTP,两边对“一条笔记该长什么样”的理解不同,最后列表里同一条记录出现两个版本,谁也说不清哪个是对的。
也要说清适用边界:三个页面以下的项目不需要 interface + 实现类 + 依赖注入这一整套,一个 NoteRepository.ets 里几个函数就够了。分层是为了隔离变化,不是为了画出漂亮的架构图。
动手实践
目标:给笔记列表搭出图 5-1 那四层。先建文件,entry/src/main/ets/ 下四个位置:
ets/
├── data/HttpClient.ets
├── data/NoteRepository.ets
├── model/Note.ets
└── pages/NoteListPage.ets步骤 1:HttpClient 与拦截链
// 前提:API 20;@kit.NetworkKit
import { http } from '@kit.NetworkKit';
export type Interceptor = (opts: http.HttpRequestOptions) => http.HttpRequestOptions;
export class HttpClient {
private readonly baseUrl: string;
private chain: Interceptor[] = [];
constructor(baseUrl: string) {
this.baseUrl = baseUrl;
}
use(fn: Interceptor): HttpClient {
this.chain.push(fn);
return this;
}
async getText(path: string): Promise<string> {
let opts: http.HttpRequestOptions = {
method: http.RequestMethod.GET,
expectDataType: http.HttpDataType.STRING,
connectTimeout: 5000, // 默认 60000,太长了
readTimeout: 8000,
header: { 'Content-Type': 'application/json' }
};
for (const fn of this.chain) {
opts = fn(opts);
}
const req = http.createHttp();
try {
const res = await req.request(this.baseUrl + path, opts);
if (res.responseCode !== http.ResponseCode.OK) {
throw new Error(`HTTP ${res.responseCode}`);
}
return res.result as string;
} finally {
req.destroy(); // 必须放 finally,异常路径也会漏句柄
}
}
}
export const api: HttpClient = new HttpClient('https://api.example.com')
.use((opts: http.HttpRequestOptions) => {
const h: Record<string, string> = { 'Content-Type': 'application/json' };
h['X-Trace-Id'] = `t-${Date.now()}`;
opts.header = h;
return opts;
});运行结果:
# DevEco Studio Log 窗口,过滤 http
[http] GET https://api.example.com/v1/notes?limit=20
[http] 200 {"code":0,"data":[{"id":1,"title":"ArkTS 入场","updatedAt":1758009600000}]}超时值不是随手填的。4G 下 RTT 的 P90 大约 200 毫秒,5 秒足够覆盖三次重传;readTimeout 给到 8 秒,是因为首屏聚合接口在服务端要做两次联查。这两个数字写死在客户端里不算优雅,后面《构建与发布:hvigor、多模块与上架》讲多模块时可以放进配置模块。
destroy() 放在 finally 里,是因为跳过它不会立刻报错。发到四五十次之后,新的请求开始返回连接类错误码 2300007,而代码一行没改。
步骤 2:DTO → 模型,逐字段兜底
// 前提:API 20;model/Note.ets
export class Note {
id: number;
title: string;
body: string;
updatedAt: number;
constructor(id: number, title: string, body: string, updatedAt: number) {
this.id = id;
this.title = title;
this.body = body;
this.updatedAt = updatedAt;
}
static fromJson(text: string): Note | null {
const raw: Object = JSON.parse(text);
const obj = raw as Record<string, Object>;
if (!Object.keys(obj).includes('data')) {
return null; // 结构不对,直接放弃这条
}
const data: Record<string, Object> = obj['data'] as Record<string, Object>;
const id = Number(data['id']);
if (!Number.isFinite(id)) {
return null; // 没有 id 的记录宁可丢掉
}
const title = typeof data['title'] === 'string' ? data['title'] as string : '未命名';
const body = typeof data['body'] === 'string' ? data['body'] as string : '';
const ts = Number(data['updatedAt']);
const updatedAt = Number.isFinite(ts) ? ts : Date.now();
return new Note(id, title, body, updatedAt);
}
}运行结果:
# 服务端返回 {"data":{"id":3,"title":"首选项陷阱"}}
Note.fromJson(...) -> Note { id: 3, title: "首选项陷阱", body: "", updatedAt: 1763308800000 }
# 服务端返回 {"data":{"title":"缺 id"}}
Note.fromJson(...) -> null // 调用方跳过该条,列表少一条而不是显示空白行这段代码看着啰嗦,但它把“服务端少字段”从崩溃降级成了一行兜底。《状态管理:@State 家族与 V2 状态管理》讲过状态管理的观察边界,序列化是同一个思路:不要让外部数据直接落进 @Local,先过一道翻译。
步骤 3:RDB 建表、批量写、按页读
// 前提:API 20;@kit.ArkData
import { relationalStore } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';
import { Note } from '../model/Note';
const CONFIG: relationalStore.StoreConfig = {
name: 'note.db',
securityLevel: relationalStore.SecurityLevel.S1
};
export class NoteDb {
private store: relationalStore.RdbStore | undefined;
async init(ctx: common.UIAbilityContext): Promise<void> {
this.store = await relationalStore.getRdbStore(ctx, CONFIG);
await this.store.executeSql(
'CREATE TABLE IF NOT EXISTS note (' +
'id INTEGER PRIMARY KEY AUTOINCREMENT, ' +
'title TEXT NOT NULL, body TEXT, updated_at INTEGER NOT NULL)'
);
if (this.store.version === 0) {
this.store.version = 1; // 记下当前表结构版本
}
}
async saveAll(notes: Note[]): Promise<number> {
if (this.store === undefined) { return 0; }
let count = 0;
this.store.beginTransaction();
try {
for (const n of notes) {
const bucket: relationalStore.ValuesBucket = {
'title': n.title, 'body': n.body, 'updated_at': n.updatedAt
};
await this.store.insert('note', bucket);
count++;
}
this.store.commit();
} catch (e) {
this.store.rollBack(); // 200 条里失败 1 条也不留半截数据
throw e as Error;
}
return count;
}
async page(limit: number, offset: number): Promise<Note[]> {
if (this.store === undefined) { return []; }
const rs = await this.store.querySql(
'SELECT id, title, body, updated_at FROM note ORDER BY updated_at DESC LIMIT ? OFFSET ?',
[limit, offset]
);
const out: Note[] = [];
try {
while (rs.goToNextRow()) {
out.push(new Note(
rs.getLong(rs.getColumnIndex('id')),
rs.getString(rs.getColumnIndex('title')),
rs.getString(rs.getColumnIndex('body')),
rs.getLong(rs.getColumnIndex('updated_at'))
));
}
} finally {
rs.close(); // 不关会攒 ResultSet 句柄
}
return out;
}
}运行结果:
# 首次启动,冷启动 200 条写入
[db] saveAll -> 200 rows, cost 41ms
[db] page(20, 0) -> 20 rows, first: 1|ArkTS 入场|1758009600000
# 第二次启动,直接读库
[db] page(20, 0) -> 20 rows, cost 3ms两点值得注意。CREATE TABLE IF NOT EXISTS 只保证表存在,表已经存在时它什么都不做——后来给 note 加一个 pinned 字段,旧设备上的表不会自动多出这一列,查询直接报“no such column”。所以要用 store.version 记版本,在第 2 版里补 ALTER TABLE。事务包住批量写的原因在弱网上:200 条里有一条字段超长,回滚之后本地库还是上一个完整的版本,不会留下“服务端以为写了 200 条、本地只有 137 条”这种两边对不上的状态。
步骤 4:Preferences 存 token 和同步时间
// 前提:API 20;@kit.ArkData
import { preferences } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';
const OPT: preferences.Options = { name: 'app_settings' };
let pref: preferences.Preferences | undefined;
export async function initPref(ctx: common.UIAbilityContext): Promise<void> {
pref = await preferences.getPreferences(ctx, OPT);
}
export async function saveToken(token: string): Promise<void> {
if (pref === undefined) { return; }
pref.putSync('auth_token', token); // 先写内存缓存
await pref.flush(); // 再落盘,两步缺一不可
}
export async function loadToken(): Promise<string> {
if (pref === undefined) { return ''; }
return pref.getSync('auth_token', '') as string;
}运行结果:
[pref] putSync auth_token, 32 bytes -> flush done, cost 3ms
[pref] 杀进程重启后 getSync auth_token -> "eyJhbGciOiJIUzI1NiIs..."
[pref] putSync 一个 9000 字节的串 -> Error 401: Parameter errorputSync 只改内存里的缓存,flush() 才写文件。只调前者,应用被杀之后数据就没了,而且不报错——这一条在真机上验过三次才敢写进来。
步骤 5:把四层接进组件
NoteListPage 的 aboutToAppear 只留四行:初始化 Preferences、初始化 RDB、调 repository.loadFirstPage()、把结果赋给 @Local notes。下拉刷新调 syncFromServer(),函数内部先写库再回读,界面永远从库里取数。这样断网时页面照样有内容,只是顶部多一条“离线数据”的提示。
常见误解
误解一:以为 res.result 直接就是对象。 它是什么类型取决于 expectDataType,默认返回字符串。有人写 res.result.data 编译报错,改成 res.result as Record<string, Object> 之后拿到 undefined——字符串上没有 data 字段。要么显式指定 HttpDataType.STRING 再自己解析,要么指定 OBJECT 并接受它返回的不确定结构。生产代码里我倾向字符串,因为解析失败能自己兜住。
误解二:以为首选项能当小型数据库用。 preferences 有两个写进接口常量的上限:MAX_KEY_LENGTH 是 80 字节,MAX_VALUE_LENGTH 是 8192 字节。存 30 个开关没问题,存一页列表就会在第 N 次写入时抛 401。判断标准很简单:这条数据需不需要按条件查、会不会超过 8KB,任一为是就换 RDB 或文件。
误解三:以为 executeSql 建表之后表结构自动跟着代码走。 建表语句只在表不存在时生效。加字段、改类型、加索引,都得靠 store.version 做判断,一版一版往上补。跳过这一步的后果不是启动报错,而是老用户升级后某个页面空白,新装的用户一切正常——这种 bug 在测试机上是隐形的。
小结
- 数据层要解决四件事:请求怎么发、响应怎么翻译、结果存在哪、界面怎么拿到。四件事混在组件里,任何一件出问题都只能改组件。
http的HttpRequest一次一实例,destroy()必须放finally;超时要显式设,默认的一分钟对首屏来说太长。JSON.parse返回Object,用as是声明而非检查,逐字段映射才能把服务端缺字段降级成兜底值。- 选存储看三个问题:要不要按条件查、会不会超过 8KB、要不要事务。三个“要”,分别指向 RDB、文件、首选项。
- 仓库是唯一的数据入口,界面永远从本地库取数,网络只负责把库填满。这条规则让断网场景从“白屏”变成“内容 + 提示”。
相关主题
数据能在本地存住、能从网络刷新之后,应用还差一类东西才能真正像个应用:调用系统硬件。《系统能力:媒体、权限与后台任务》讲媒体能力、权限申请和后台任务——用户要换头像就得碰相机,要听播客就得让音频在后台活着,而这两件事都会撞上权限审核。这一章里那个 401 处理逻辑,到《系统能力:媒体、权限与后台任务》会变成权限被拒之后的分支。