游乐游手机版
首页/AI教程/文章详情

HarmonyOS网络请求与数据持久化实现指南

时间：2026-07-08 15:38
HarmonyOS原生支持网络请求（@ohos net http实现GET POST及封装工具类）与数据持久化（轻量Preferences、关系型数据库、分布式KV-Store），满足多场景开发需求。

在 HarmonyOS 应用开发中，网络请求与数据持久化是每个应用必不可少的基础功能。HarmonyOS 提供了完善的原生解决方案——从轻量级的 Preferences 键值存储到关系型数据库，再到分布式 KV-Store，能够满足绝大多数场景需求。本文将从实际代码出发，梳理常用操作，便于开发者在项目中直接参考使用。

HarmonyOS 网络请求与数据持久化完整指南

HTTP 网络请求

@ohos.net.http 基础请求

import http from '@ohos.net.http'

// 发起 GET 请求
async function fetchData(url: string): Promise {
  const httpRequest = http.createHttp()
  try {
    const response = await httpRequest.request(url, {
      method: http.RequestMethod.GET,
      header: {
        'Content-Type': 'application/json'
      },
      connectTimeout: 60000,
      readTimeout: 60000,
      extraData: {} // GET 请求通常不需要携带请求体
    })
    if (response.responseCode === 200) {
      const result = JSON.parse(response.result as string) as ResponseData
      return result
    } else {
      throw new Error(`HTTP 错误: ${response.responseCode}`)
    }
  } finally {
    httpRequest.destroy() // 必须销毁请求对象，释放资源
  }
}

// 发起 POST 请求
async function postData(url: string, body: Object): Promise {
  const httpRequest = http.createHttp()
  try {
    const response = await httpRequest.request(url, {
      method: http.RequestMethod.POST,
      header: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${getToken()}`
      },
      extraData: JSON.stringify(body)
    })
    return JSON.parse(response.result as string) as ResponseData
  } finally {
    httpRequest.destroy()
  }
}

// PUT 和 DELETE 请求用法类似，只需更改 method 参数

请求事件监听

const httpRequest = http.createHttp()

httpRequest.on('headerReceive', (err, header) => {
  console.info('已收到响应头')
})

httpRequest.on('dataReceive', (data) => {
  console.info('收到数据片段')
})

httpRequest.on('dataEnd', () => {
  console.info('数据接收完毕')
})

httpRequest.on('responseReceive', (response) => {
  console.info('收到完整响应')
})

// 流式接收，适用于大文件下载
httpRequest.requestInStream(url, options)

// 取消正在进行的请求
httpRequest.destroy()

封装网络请求工具类

import http from '@ohos.net.http'

const BASE_URL = 'https://api.example.com'

interface ApiResponse {
  code: number
  message: string
  data: T
}

class HttpClient {
  private static instance: HttpClient
  private token: string = ''

  static getInstance(): HttpClient {
    if (!HttpClient.instance) {
      HttpClient.instance = new HttpClient()
    }
    return HttpClient.instance
  }

  setToken(token: string) {
    this.token = token
  }

  private getHeaders(): Record {
    const headers: Record = {
      'Content-Type': 'application/json'
    }
    if (this.token) {
      headers['Authorization'] = `Bearer ${this.token}`
    }
    return headers
  }

  async get(path: string, params?: Record): Promise> {
    let url = `${BASE_URL}${path}`
    if (params) {
      const query = Object.entries(params)
        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
        .join('&')
      url += `?${query}`
    }
    return this.request(url, http.RequestMethod.GET)
  }

  async post(path: string, body?: Object): Promise> {
    const url = `${BASE_URL}${path}`
    return this.request(url, http.RequestMethod.POST, body)
  }

  async put(path: string, body?: Object): Promise> {
    const url = `${BASE_URL}${path}`
    return this.request(url, http.RequestMethod.PUT, body)
  }

  async delete(path: string): Promise> {
    const url = `${BASE_URL}${path}`
    return this.request(url, http.RequestMethod.DELETE)
  }

  private async request(
    url: string,
    method: http.RequestMethod,
    body?: Object
  ): Promise> {
    const httpRequest = http.createHttp()
    try {
      const response = await httpRequest.request(url, {
        method,
        header: this.getHeaders(),
        connectTimeout: 30000,
        readTimeout: 30000,
        extraData: body ? JSON.stringify(body) : undefined
      })
      if (response.responseCode === 200) {
        return JSON.parse(response.result as string) as ApiResponse
      }
      if (response.responseCode === 401) {
        // Token 过期，执行重新认证
        this.handleAuthError()
        throw new Error('认证已过期')
      }
      throw new Error(`请求失败: ${response.responseCode}`)
    } catch (error) {
      console.error(`HTTP 请求出错: ${error}`)
      throw error
    } finally {
      httpRequest.destroy()
    }
  }

  private handleAuthError() {
    this.token = ''
    // 可在此跳转登录页或自动刷新 Token
  }
}

export default HttpClient.getInstance()

数据持久化

Preferences 轻量存储（键值对）

import preferences from '@ohos.data.preferences'

const PREFERENCES_NAME = 'my_app_prefs'

async function getPreferences(context: Context): Promise {
  return preferences.getPreferences(context, PREFERENCES_NAME)
}

// 写入数据
async function sa veSetting(context: Context, key: string, value: preferences.ValueType) {
  const prefs = await getPreferences(context)
  await prefs.put(key, value)
  await prefs.flush() // 持久化到磁盘
}

// 读取数据
async function getSetting(context: Context, key: string): Promise {
  const prefs = await getPreferences(context)
  return prefs.get(key, '') // 设置默认值为空字符串
}

// 删除指定键
async function removeSetting(context: Context, key: string) {
  const prefs = await getPreferences(context)
  await prefs.delete(key)
  await prefs.flush()
}

// 清空所有存储
async function clearSettings(context: Context) {
  const prefs = await getPreferences(context)
  await prefs.clear()
  await prefs.flush()
}

// 常见使用场景示例
// sa veSetting(context, 'user_token', 'xxx')
// sa veSetting(context, 'is_first_launch', true)
// sa veSetting(context, 'last_login_time', 1700000000)

RelationalDB 关系型数据库（SQLite）

import relationalStore from '@ohos.data.relationalStore'

const STORE_CONFIG: relationalStore.StoreConfig = {
  name: 'app_database.db',
  securityLevel: relationalStore.SecurityLevel.S1
}

// 创建数据表
const CREATE_TABLE_SQL = `
  CREATE TABLE IF NOT EXISTS user (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    age INTEGER,
    created_at INTEGER
  )`

async function initDB(context: Context): Promise {
  const store = await relationalStore.getRdbStore(context, STORE_CONFIG)
  await store.executeSql(CREATE_TABLE_SQL)
  return store
}

// 插入用户数据
async function insertUser(store: relationalStore.RdbStore, user: User): Promise {
  const valueBucket: relationalStore.ValuesBucket = {
    'name': user.name,
    'age': user.age,
    'created_at': Date.now()
  }
  return store.insert('user', valueBucket)
}

// 查询用户列表，可按年龄筛选
async function queryUsers(store: relationalStore.RdbStore, ageFilter?: number): Promise {
  const predicates = new relationalStore.RdbPredicates('user')
  if (ageFilter) {
    predicates.equalTo('age', ageFilter)
  }
  predicates.orderByDesc('created_at')
  const resultSet = await store.query(predicates)
  const users: User[] = []
  while (resultSet.goToNextRow()) {
    users.push({
      id: resultSet.getLong(resultSet.getColumnIndex('id')),
      name: resultSet.getString(resultSet.getColumnIndex('name')),
      age: resultSet.getLong(resultSet.getColumnIndex('age')),
      created_at: resultSet.getLong(resultSet.getColumnIndex('created_at'))
    })
  }
  resultSet.close()
  return users
}

// 更新用户名称
async function updateUser(store: relationalStore.RdbStore, id: number, name: string): Promise {
  const valueBucket: relationalStore.ValuesBucket = { 'name': name }
  const predicates = new relationalStore.RdbPredicates('user')
  predicates.equalTo('id', id)
  return store.update(valueBucket, predicates)
}

// 删除指定用户
async function deleteUser(store: relationalStore.RdbStore, id: number): Promise {
  const predicates = new relationalStore.RdbPredicates('user')
  predicates.equalTo('id', id)
  return store.delete(predicates)
}

KV-Store 分布式键值数据库

import distributedKVStore from '@ohos.data.distributedKVStore'

// 创建 KV-Store 分布式数据库
const options: distributedKVStore.Options = {
  createIfMissing: true,
  encrypt: false,
  backup: false,
  autoSync: true, // 自动同步到其他设备
  kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION
}

async function createKVStore(context: Context): Promise {
  return distributedKVStore.createKVStore(context, 'distributed_store', options)
}

// 写入键值对
kvStore.put('sync_key', 'sync_value')

// 读取键值对
const value = await kvStore.get('sync_key')

// 手动同步数据到其他设备
kvStore.sync(['device_id_1', 'device_id_2'], distributedKVStore.SyncMode.PUSH_ONLY)

文件存储

应用文件目录

import fileIo from '@ohos.file.fs'

// 应用私有目录路径
const filesDir = context.filesDir      // /data/app/el2/100/.../files
const cacheDir = context.cacheDir      // /data/app/el2/100/.../cache
const tempDir = context.tempDir       // /data/app/el2/100/.../temp
const preferencesDir = context.preferencesDir

// 写入文件
const file = fileIo.openSync(`${filesDir}/data.json`, fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY)
fileIo.writeSync(file.fd, JSON.stringify(data))
fileIo.closeSync(file)

// 读取文件
const readFile = fileIo.openSync(`${filesDir}/data.json`, fileIo.OpenMode.READ_ONLY)
const content = fileIo.readSync(readFile.fd)
fileIo.closeSync(readFile)

// 判断文件是否存在
const exists = fileIo.accessSync(`${filesDir}/data.json`)
来源：https://cloud.tencent.com.cn/developer/article/2704590
HarmonyOS
上一篇ArkTS语言与状态管理核心机制及实战案例详解 下一篇Go 1.26全面解读：语言增强、工具升级以及Green Tea GC默认启用
本站内容用于信息整理与展示，如有侵权或内容问题请及时联系处理。

相关推荐

补充同频道和同主题内容，方便继续浏览更多相关内容。

Windows系统下鸿蒙开发工具安装与DevEco Studio 3.1及SDK配置详细步骤 HarmonyOS APP开发：AI工具链与自动化部署实践 鸿蒙OS开发 AI模型市场与模型管理 鸿蒙应用开发中的人工智能安全与对抗攻击防御 HarmonyOS 6.1十大重要升级盘点

同类最新

继续查看同栏目最近更新的文章。

更多
Claude Code官方教你Loop工程附6大省token技巧
AI教程 · 2026-07-08

Claude Code官方教你Loop工程附6大省token技巧

之前写过一篇《Loop Engineering 的保姆级教程》，从概念到多工具实战，比较全面地讲了循环工程的玩法。这两天 Claude Code 官方团队下场，发了一篇博客叫「Getting started with loops」，系统地整理了他们团队内部对「循环」的定义和分类。 这篇博客的含金量十

 阿里云2核4G服务器价格与选型：实例规格、收费标准及活动价
AI教程 · 2026-07-08

阿里云2核4G服务器价格与选型：实例规格、收费标准及活动价

阿里云2核4G这个配置，可以说是个人站长和中小企业用户最常关注的“爆款”了。不过它的价格可不是一个固定的数字，而是跟实例规格、带宽、云盘类型、地域等等因素紧密相关。比如目前轻量应用服务器2核4G给到峰值200M带宽、50G ESSD云盘，抢购价能做到9 9元1个月或者199元1年。通用算力型u1实例

 阿里巴巴研发效能实践日：敏捷精益项目管理报名
AI教程 · 2026-07-08

阿里巴巴研发效能实践日：敏捷精益项目管理报名

研发效能提升领域又有重磅消息了。阿里巴巴研发效能实践日——由阿里研发效能部主办的线下沙龙品牌，这次携手全球领先的项目管理协会PMI，共同聚焦“敏捷精益项目管理”这一核心主题。听起来就干货满满？别急，活动精心安排了4大主题演讲，旨在帮助参会者在思维层面实现突破，并且回去就能直接落地实践。更关键的是，参

 RFID资产管理系统：企业资产数字化高效管控方案
AI教程 · 2026-07-08

RFID资产管理系统：企业资产数字化高效管控方案

数字化转型走到今天，传统人工管资产那套老办法——效率低、差错多、资产一挪窝就成“失踪人口”——已经越来越扛不住了。从仓库、车间到办公室，但凡资产流转量大、品类多的企业，都急需一套能实时盯、自动盘的方案。结合多行业的落地经验来看，RFID资产管理系统之所以能成为主流选择，核心在于它用射频技术把资产全生

 智能体工作流知识沉淀：从一次修复到长期记忆
AI教程 · 2026-07-08

智能体工作流知识沉淀：从一次修复到长期记忆

好的，作为一位资深的技术专家和知识管理实践者，我将为你重新讲述这篇文章的核心内容，让这些观点和案例听起来更像是一次真诚的技术分享，而不是一份AI生成的报告。 在传统软件工程里，我们反复念叨“代码复用”，但到了AI Agent参与的工程时代，真正能产生复利的东西变了——从“代码复用”悄然转向了“知识复