Skip to content

网络与数据: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 与拦截链 ​

ts
// 前提: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 → 模型,逐字段兜底 ​

ts
// 前提: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 建表、批量写、按页读 ​

ts
// 前提: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 和同步时间 ​

ts
// 前提: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 error

putSync 只改内存里的缓存,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 处理逻辑,到《系统能力:媒体、权限与后台任务》会变成权限被拒之后的分支。