Http

支持 GET/POST、自定义编解码、任意返回类型解析的网络请求框架

介绍#

mk.network.http 是支持 Web 和原生环境的 Http 封装对象，扩展了编解码，自动解析返回数据， 且以 Promise 方式实现

方法#

get / post#

基础用法#

// GET 请求
const response = await mk.network.http.get('https://api.example.com/data', {
    returnType: 'json',
    timeoutNum: 10000,
});

// POST 请求
const response = await mk.network.http.post('https://api.example.com/login', {
    body: JSON.stringify({ username: 'user', password: 'pass' }),
    header: { 'Content-Type': 'application/json' },
    returnType: 'json',
});

返回值#

  • 成功时返回 Promise<any>（解析后的响应数据）
  • 失败时返回 Promise<null>（超时、网络错误、状态码异常）

Http_.Config 配置类#

属性类型默认值描述
timeoutNumnumber5000超时时间（毫秒）
returnTypeXMLHttpRequestResponseType-返回数据类型（如 'json'、'arraybuffer'）
codecmk.CodecBase-编解码器（可选）
bodyDocument | Blob | BufferSource | FormData | URLSearchParams | string-请求体
headerRecord<string, string>-请求头
openCallbackFunc(http: XMLHttpRequest) => void-请求初始化回调

配置示例#

const config = new mk.network.Http_.Config({
    timeoutNum: 10000,
    returnType: 'arraybuffer', // 接收二进制数据
    header: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer token123',
    },
    codec: new MyCodec(), // 自定义编解码器
});

返回类型处理逻辑#

returnType响应处理适用场景
text / ""直接返回 xmlHttp.response文本、HTML
arraybuffer转换为 data:image/png;base64,...图片、二进制数据
blob通过 FileReader 转换为 Data URL文件、图片
document返回 Document 或 XMLDocumentXML、HTML 文档
json自动解析为 JavaScript 对象JSON API

请求头（header）#

支持自定义请求头，例如：

header: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123',
    'X-Custom-Header': 'value',
}

注意：在原生环境（sys.isNative）下，框架自动添加 Accept-Encoding: gzip,deflate。

请求初始化回调（openCallbackFunc）#

在 XMLHttpRequest.open 后触发，可用于注册事件或设置额外属性。

示例#

openCallbackFunc: (http) => {
    http.onprogress = (e) => console.log('下载进度：', e.loaded / e.total);
    http.ontimeout = () => console.log('请求超时');
};

高级功能#

超时处理#

  • 默认超时 5000ms
  • 通过 timeoutNum 自定义超时
  • 在 openCallbackFunc 中注册 ontimeout 处理超时事件

二进制数据支持#

通过 returnType: 'arraybuffer' 接收二进制数据，框架自动转换为 Base64 Data URL。

适用场景：

  • 图片加载
  • 音频/视频文件
  • 自定义二进制协议

跨域支持#

  • 浏览器：遵循同源策略，需服务器支持 CORS
  • 原生环境：无跨域限制

错误处理策略#

错误类型处理方式
网络错误返回 null
状态码错误仅处理 200-399 的状态码，其他状态码返回 null
超时返回 null，并在 openCallbackFunc 中触发 ontimeout

最佳实践#

配置复用#

创建全局配置，避免重复代码：

const defaultConfig = new mk.network.Http_.Config({
    timeoutNum: 10000,
    header: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer token123',
    },
});

// 使用
const response = await mk.network.http.get('https://api.example.com/data', defaultConfig);

错误重试机制#

通过 Promise.race 实现超时重试：

async function requestWithRetry(url: string, config: Http_.Config, retries = 3) {
    for (let i = 0; i < retries; i++) {
        const response = await mk.network.http.get(url, config);
        if (response) return response;
    }
    return null;
}

资源释放#

  • 二进制数据：通过 arraybuffer 或 blob 接收后，及时释放内存
  • 请求中断：通过 XMLHttpRequest.abort() 中断请求

常见问题（FAQ）#

Q: 如何发送 FormData 请求？

通过 body 传递 FormData 对象：

const formData = new FormData();
formData.append('file', file);
const response = await mk.network.http.post('https://api.example.com/upload', {
    body: formData,
});