這說明問題出在客戶端接收側(cè)，而非服務(wù)端。

2.3 添加錯(cuò)誤日志定位根因

在 HTTP 回調(diào)的 onError 中添加結(jié)構(gòu)化日志，捕獲到關(guān)鍵信息：

[Error] url=https://xxx.com/api/large-list, code=2300023, 
  message=Failed writing received data to disk/application

部分場景下還伴隨降級請求的超時(shí)錯(cuò)誤：

[Error] url=https://xxx.com/api/fallback-list, code=2300028, 
  message=Timeout was reached

兩個(gè)錯(cuò)誤的含義：

至此，根因確認(rèn)：鴻蒙 @ohos.net.http 模塊的 request() 方法默認(rèn)最大只能接收約 5MB 的響應(yīng)數(shù)據(jù)。

三、根因分析

3.1 鴻蒙 HTTP 模塊的響應(yīng)體大小限制

根據(jù)華為官方 FAQ：

http 請求默認(rèn)規(guī)格最大可傳輸 5M 數(shù)據(jù)文件（自 API Version 23 開始，該默認(rèn)規(guī)格擴(kuò)充至 50MB），當(dāng) http 請求數(shù)據(jù)超過 5M 時(shí)，可在 HttpRequestOptions 中增大 maxLimit 屬性，或使用流式接口 requestInStream。

— 華為開發(fā)者文檔：http請求傳輸大于5M文件報(bào)錯(cuò)2300023

3.2 為什么 Android / iOS 沒有這個(gè)問題？

• Android（OkHttp）：底層基于 okio，天然采用流式讀取，不會(huì)一次性將響應(yīng)體加載到內(nèi)存緩沖區(qū)。
• iOS（NSURLSession）：同樣基于流式回調(diào)機(jī)制（didReceiveData），沒有固定的響應(yīng)體大小限制。
• HarmonyOS（@ohos.net.http）：request() 方法會(huì)將完整響應(yīng)體緩存后一次性返回，受到底層 libcurl 寫入回調(diào)的大小校驗(yàn)限制。

四、解決方案：requestInStream() 流式接收

4.1 方案選擇

由于組織架構(gòu)數(shù)據(jù)量隨業(yè)務(wù)增長會(huì)持續(xù)變化，選擇 requestInStream() 方案更穩(wěn)健。

4.2 核心實(shí)現(xiàn)

import http from '@ohos.net.http';
import util from '@ohos.util';

function requestInStream(
  url: string,
  options: http.HttpRequestOptions,
  onSuccess: (data: string, code: number) => void,
  onError: (err: Error) => void
) {
  let httpRequest = http.createHttp();
  let responseChunks: ArrayBuffer[] = [];
  let responseCode: number = 200;

  // 1. 監(jiān)聽數(shù)據(jù)分塊到達(dá)
  httpRequest.on('dataReceive', (data: ArrayBuffer) => {
    responseChunks.push(data);
  });

  // 2. 監(jiān)聽數(shù)據(jù)接收完成
  httpRequest.on('dataEnd', () => {
    httpRequest.destroy();

    // 3. 合并所有 ArrayBuffer
    let totalLength = 0;
    for (let chunk of responseChunks) {
      totalLength += chunk.byteLength;
    }
    let merged = new Uint8Array(totalLength);
    let offset = 0;
    for (let chunk of responseChunks) {
      merged.set(new Uint8Array(chunk), offset);
      offset += chunk.byteLength;
    }

    // 4. 使用 TextDecoder 解碼 UTF-8（關(guān)鍵！）
    let decoder = util.TextDecoder.create('utf-8');
    let fullData = decoder.decodeToString(merged);

    onSuccess(fullData, responseCode);
  });

  // 5. 發(fā)起流式請求
  httpRequest.requestInStream(url, options, (err, code) => {
    if (err) {
      httpRequest.destroy();
      onError(err);
      return;
    }
    responseCode = code;
  });
}

4.3 調(diào)用示例

let httpRequest = http.createHttp();

// 設(shè)置較長的超時(shí)時(shí)間（大數(shù)據(jù)量傳輸需要更多時(shí)間）
let options: http.HttpRequestOptions = {
  method: http.RequestMethod.POST,
  header: { 'Content-Type': 'application/x-www-form-urlencoded' },
  extraData: 'param1=value1&param2=value2',
  readTimeout: 60000,    // 60秒
  connectTimeout: 60000,
};

requestInStream(
  'https://your-api.com/large-data-endpoint',
  options,
  (data, code) => {
    console.info(`接收完成，數(shù)據(jù)長度: ${data.length}, HTTP狀態(tài)碼: ${code}`);
    let parsed = JSON.parse(data);
    // 處理業(yè)務(wù)數(shù)據(jù)...
  },
  (err) => {
    console.error(`請求失敗: code=${err.code}, message=${err.message}`);
  }
);

五、踩坑：流式接收中文亂碼

5.1 錯(cuò)誤寫法

拿到 ArrayBuffer 后直接逐字節(jié)轉(zhuǎn)字符串：

// ? 錯(cuò)誤！會(huì)導(dǎo)致中文亂碼
httpRequest.on('dataReceive', (data: ArrayBuffer) => {
  fullData += String.fromCharCode(...new Uint8Array(data));
});

原因：String.fromCharCode() 按單字節(jié)處理，而 UTF-8 中文占 3 個(gè)字節(jié)。逐字節(jié)轉(zhuǎn)換會(huì)把一個(gè)中文字符拆成 3 個(gè)亂碼字符。更嚴(yán)重的是，dataReceive 的分塊邊界可能恰好切斷一個(gè) UTF-8 多字節(jié)序列，導(dǎo)致即使單塊內(nèi)解碼也會(huì)出錯(cuò)。

5.2 正確寫法

先收集所有 ArrayBuffer 塊，最后統(tǒng)一用 TextDecoder 解碼：

import util from '@ohos.util';

// ? 正確：收集所有 chunk
let responseChunks: ArrayBuffer[] = [];

httpRequest.on('dataReceive', (data: ArrayBuffer) => {
  responseChunks.push(data);
});

httpRequest.on('dataEnd', () => {
  // 合并
  let totalLength = 0;
  for (let chunk of responseChunks) {
    totalLength += chunk.byteLength;
  }
  let merged = new Uint8Array(totalLength);
  let offset = 0;
  for (let chunk of responseChunks) {
    merged.set(new Uint8Array(chunk), offset);
    offset += chunk.byteLength;
  }

  // 統(tǒng)一解碼
  let decoder = util.TextDecoder.create('utf-8');
  let fullData = decoder.decodeToString(merged);
});

注意：TextDecoder 的 decode() 方法自 API version 9 起已廢棄，請使用 decodeToString() 替代。
參考：@ohos.util (util工具函數(shù)) — TextDecoder

六、完整修復(fù)要點(diǎn)總結(jié)

七、適用范圍與注意事項(xiàng)

1. 影響面評估：requestInStream() 僅替換了可能返回大數(shù)據(jù)量的特定接口，其他接口仍使用 request()，不影響全局。

2. API 版本兼容：

   • requestInStream() 自 API version 10 起支持。
   • 自 API version 23 起，request() 的默認(rèn)上限已擴(kuò)充至 50MB，如果你的 minSdkVersion >= 23，也可以通過設(shè)置 maxLimit 參數(shù)解決。

3. 內(nèi)存考量：流式接收方案在 dataEnd 時(shí)需要合并全部 chunk，峰值內(nèi)存占用約為響應(yīng)體大小的 2 倍（原始 chunk + 合并后的 Uint8Array）。對于 10MB 級別的響應(yīng)體完全可接受；如果響應(yīng)體達(dá)到百 MB 級別，建議改用分頁接口或文件下載方案。

4. 服務(wù)端優(yōu)化建議：如果接口返回?cái)?shù)據(jù)量可能持續(xù)增長（如組織架構(gòu)隨業(yè)務(wù)擴(kuò)張），建議推動(dòng)服務(wù)端支持分頁或增量查詢，從根本上減少單次傳輸?shù)臄?shù)據(jù)量。

八、參考文檔

• 華為官方 FAQ：http請求傳輸大于5M文件報(bào)錯(cuò)2300023
• 華為官方 API 文檔：@ohos.net.http (數(shù)據(jù)請求)
• 華為官方 API 文檔：@ohos.util — TextDecoder
• 華為開發(fā)者論壇：requestInStream API 使用
• libcurl 錯(cuò)誤碼對照表：CURLE_WRITE_ERROR (23)

本文基于 HarmonyOS NEXT（API 12）實(shí)際開發(fā)經(jīng)驗(yàn)總結(jié)，如有錯(cuò)誤歡迎指正。