# axios

**Repository Path**: LLLLLLin/axios

## Basic Information

- **Project Name**: axios
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 101
- **Created**: 2022-08-29
- **Last Updated**: 2022-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# axios

## 简介

[Axios](https://github.com/axios/axios) ，是一个基于 promise 的网络请求库，可以运行 node.js 和浏览器中。本库基于[Axios](https://github.com/axios/axios) 原库进行适配，使其可以运行在 OpenHarmony，并沿用其现有用法和特性。

- http 请求
- Promise API
- request 和 response 拦截器
- 转换 request 和 response 的 data 数据
- 自动转换 JSON data 数据

## 下载安装

```javascript
npm install @ohos/axios --save
```

OpenHarmony npm 环境配置等更多内容，请参考[如何安装 OpenHarmony npm 包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_npm_usage.md)

## 使用说明
```javascript
import { axios } from '@ohos/axios'
```

## 需要权限
```
ohos.permission.INTERNET
```

### axios API

#### 通过向 axios 传递相关配置来创建请求

##### axios(config)
```javascript
axios({
  method: "get",
  url: 'http://www.xxx.com/info'
}).then(res => {
   console.info('result:' + JSON.stringify(res.data));
}).catch(error => {
   console.error(error);
})
```

##### axios(url[, config])
```javascript
axios('http://www.xxx.com/info').then(res => {
   console.info('result:' + JSON.stringify(res.data));
}).catch(error => {
   console.error(error);
})
```

#### 请求方法的 别名方式 来创建请求
为方便起见，为所有支持的请求方法提供了别名

- axios.request(config)
- axios.get(url[, config])
- axios.delete(url[, config])
- axios.post(url[, data[, config]])
- axios.put(url[, data[, config]])

代码示例：
```javascript
axios.get("http://www.xxx.com/info", { params: { key: "value" } })
  .then(function (response) {
    console.info("result:" + JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.error(error);
  });
```
#### 请求配置
这些是创建请求时可以用的配置选项。只有 url 是必需的。如果没有指定 method，请求将默认使用 get 方法。
```javascript
// `url` 是用于请求的服务器 URL
url: '/user',

// `method` 是创建请求时使用的方法 支持post/get/put/delete方法，不区分大小写，默认为get方法
method: 'get', // default

// `baseURL` 将自动加在 `url` 前面，除非 `url` 是一个绝对 URL。
// 它可以通过设置一个 `baseURL` 便于为 axios 实例的方法传递相对 URL
baseURL: 'https://some-domain.com/api/',
// `headers` 是即将被发送的自定义请求头

headers: {'Content-Type': 'application/json'},

// `params` 是即将与请求一起发送的 URL 参数
// 必须是一个无格式对象(plain object)或 URLSearchParams 对象
params: {
   ID: 12345
},
// `data` 是作为请求主体被发送的数据
// 只适用于这些请求方法 'PUT', 'POST', 和 'PATCH'
data: {
   firstName: 'Fred'
},

// `timeout` 指定请求超时的毫秒数(0 表示无超时时间)
// 如果请求超过 `timeout` 的时间，请求将被中断
timeout: 1000,

// `onUploadProgress` 允许为上传处理进度事件
onUploadProgress: function (progressEvent) {
   // 对原生进度事件的处理
},

// `onDownloadProgress` 允许为下载处理进度事件
onDownloadProgress: function (progressEvent) {
   // 对原生进度事件的处理
},


```
#### 错误码
- 网络请求异常时，catch方法接收到异常，异常错误码 [请点击查看](https://curl.se/libcurl/c/libcurl-errors.html)
- 错误常量

| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| NETWORK_MOBILE | number | 是 | 否 | 使用蜂窝网络时允许下载的位标志。 |
| NETWORK_WIFI | number | 是 | 否 | 使用WLAN时允许下载的位标志。 |
| ERROR_CANNOT_RESUME<sup>7+</sup> | number | 是 | 否 | 某些临时错误导致的恢复下载失败。 |
| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | 是 | 否 | 找不到SD卡等存储设备。 |
| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | 是 | 否 | 要下载的文件已存在，下载会话不能覆盖现有文件。 |
| ERROR_FILE_ERROR<sup>7+</sup> | number | 是 | 否 | 文件操作失败。 |
| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | 是 | 否 | HTTP传输失败。 |
| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | 是 | 否 | 存储空间不足。 |
| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | 是 | 否 | 网络重定向过多导致的错误。 |
| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | 是 | 否 | 无法识别的HTTP代码。 |
| ERROR_UNKNOWN<sup>7+</sup> | number | 是 | 否 | 未知错误。 |
| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | 是 | 否 | 下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。 |
| PAUSED_UNKNOWN<sup>7+</sup> | number | 是 | 否 | 未知原因导致暂停下载。 |
| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | 是 | 否 | 由于网络问题（例如网络断开）而暂停下载。 |
| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | 是 | 否 | 发生网络错误，将重试下载会话。 |
| SESSION_FAILED<sup>7+</sup> | number | 是 | 否 | 下载会话已失败，将不会重试。 |
| SESSION_PAUSED<sup>7+</sup> | number | 是 | 否 | 下载会话已暂停。 |
| SESSION_PENDING<sup>7+</sup> | number | 是 | 否 | 正在调度下载会话。 |
| SESSION_RUNNING<sup>7+</sup> | number | 是 | 否 | 下载会话正在进行中。 |
| SESSION_SUCCESSFUL<sup>7+</sup> | number | 是 | 否 | 下载会话已完成。 |

### GET 请求方法示例

```javascript
// 方式1，通过向 axios 传递相关配置来创建请求
axios({
  method: "get",
  url: 'http://www.xxx.com/info'
}).then(res => {
   console.info('result:' + JSON.stringify(res.data));
}).catch(error => {
   console.error(error);
})

// 方式2，通过别名来创建请求
axios.get("http://www.xxx.com/info", { params: { key: "value" } })
  .then(function (response) {
    console.info("result:" + JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.error(error);
  });

```

### POST 请求方法示例

```javascript
axios({
   url: 'http://www.xxx.com/post',
   method: 'post',
   data: {titleId: 2, typeId: 1},
}).then(res=>{
   console.info('result: ' + JSON.stringify(res.data));
}).catch((error)=>{
   console.info('error: ' +　JSON.stringify(error));
})

```

### 上传文件示例
- 上传文件需要单独导入FormData模块
- 当前版本只支持 Stage 模型
- 上传类型支持uri和ArrayBuffer，uri支持“dataability”和“internal”两种协议类型，但“internal”仅支持临时目录， 示例： dataability:///com.domainname.dataability.persondata/person/10/file.txt ;internal://cache/path/to/file.txt

#### 当上传的内容为ArrayBuffer时，必须指定文件名，用法如下

```javascript
import { axios, FormData } from '@ohos/axios'
import fileio from '@ohos.fileio';

// ArrayBuffer
  var formData = new FormData()
  let cacheDir = (getContext(this) as any).cacheDir
  try {
    // 写入
    let path = cacheDir + '/hello.txt';
    let fd = fileio.openSync(path, 0o100 | 0o2, 0o666);
    fileio.writeSync(fd, "hello, world");
    fileio.fsyncSync(fd);
    fileio.closeSync(fd);

    // 读取
    let fd2 = fileio.openSync(path, 0o2);
    let stat = fileio.lstatSync(path);
    let buf2 = new ArrayBuffer(stat.size);
    fileio.readSync(fd2, buf2);
    fileio.fsyncSync(fd2);
    fileio.closeSync(fd2);

    formData.append('file', buf2, 'hello.txt');
  }catch(err){
    console.info('err:' + JSON.stringify(err));
  }
  // 发送请求
   axios.post('http://www.xxx.com/upload', formData, {
       headers: { 'Content-Type': 'multipart/form-data' },
       context: getContext(this),
       onUploadProgress:(uploadedSize: number, total:number):void=> {
          console.info(Math.ceil(uploadedSize/total * 100) + '%');
       },
   }).then((res) => {
       console.info("result" + JSON.stringify(res.data));
   }).catch(error => {
       console.error("error:" + JSON.stringify(error));
   })
```

#### 当上传的uri时，用法如下

```javascript
import { axios, FormData } from '@ohos/axios'

var formData = new FormData()
formData.append('file', 'internal://cache/blue.jpg')

// 发送请求
axios.post('http://www.xxx.com/upload', formData, {
   headers: { 'Content-Type': 'multipart/form-data' },
   context: getContext(this),
   onUploadProgress:(uploadedSize: number, total:number):void=> {
      console.info(Math.ceil(uploadedSize/total * 100) + '%');
   },
}).then((res) => {
   console.info("result" + JSON.stringify(res.data));
}).catch(error => {
   console.error("error:" + JSON.stringify(error));
})
```

### 下载文件示例
设置下载路径filePath（默认在'internal://cache/'路径下）。
filePath:'workspace/test.txt'：默认路径下创建workspace路径，并将文件存储在workspace路径下。
filePath:'test.txt'：将文件存储在默认路径下。
filePath:'workspace/'：默认路径下创建workspace路径，并将文件存储在workspace路径下。

- 当前版本只支持 Stage 模型
  下载文件时，如果filePath已存在该文件则下载失败，下载之前需要先删除文件。

```javascript
let filePath = (getContext(this) as any).cacheDir + '/blue.jpg'
// 下载。如果文件已存在，则先删除文件。
try {
   fileio.accessSync(filePath);
   fileio.unlinkSync(filePath);
} catch(err) {}

axios({
   url: 'http://www.xxx.com/blue.jpg',
   method: 'get',
   context: getContext(this),
   filePath: filePath ,
   onDownloadProgress:  (receivedSize: number, total:number):void=> {
       console.info(Math.ceil( receivedSize/total * 100 ) + '%');
   },
   }).then((res)=>{
      console.info("result: " + JSON.stringify(res.data));
   }).catch((error)=>{=
      console.error(t"error:" + JSON.stringify(error));
   })
```

### 拦截器示例

```javascript
// 添加请求拦截器
axios.interceptors.request.use(config => {
   // 对请求数据做点什么
   return config;
}, error => {
   // 对请求错误做些什么
    return Promise.reject(error);
});


// 添加响应拦截器
axios.interceptors.response.use(function (response) {
   // 对响应数据做点什么
   return response;
}, function (error) {
   // 对响应错误做点什么
   return Promise.reject(error);
});

```

### 默认设置示例
#### 全局axios默认值
```javascript
axios.defaults.baseURL = 'http://www.xxx.com';
axios.defaults.headers['Authorization'] = 'Admin-Token';
```

#### 自定义实例默认值
```javascript
const instance = axios.create({
  baseURL: 'http://www.xxx.com',
  timeout: 1000,
  headers: {'Content-Type': 'application/json'}
});
```

## 已知bug
- 上传文件，服务器返回404/500等错误场景，onUploadProgress仍然可以监听到进度，并且进度有时可达到100%。
- 上传/下载文件，文件上传/下载成功，但有较小的概率进度达不到100%。
- 设置下载路径（filePath）地址不存在，axios catch不抛出异常信息。

## 8月22日前镜像可能存在的bug
- 下载文件，url非法，axios catch不抛出异常信息(已修复)。
- 下载，服务器返回404/500等错误场景，onDownloadProgress仍然可以监听到进度(已修复)。

## 兼容性

支持 OpenHarmony API version 9 及以上版本

## 目录结构
```javascript
|---- ohos_axios
|     |---- entry  # 示例代码文件夹
|     |---- screenshots #截图
|     |---- ohos_axios  # ohos_axios 库文件夹
|           |---- src  # ohos_axios 网络请求核心代码
|           |---- index.d.ts  # ohos_axios 接口类型定义
|           |---- index.js    # ohos_axios 适配axios源码
|     |---- README.MD  # 安装使用方法
```

## 贡献代码

使用过程中发现任何问题都可以提[Issue](https://gitee.com/openharmony-tpc/ohos-axios/issues) 给我们，当然，我们也非常欢迎你给我们提[PR](https://gitee.com/openharmony-tpc/ohos-axios/pulls)。

## 开源协议

本项目基于 [Apache License 2.0](https://gitee.com/openharmony-tpc/ohos-axios/blob/master/LICENSE)，请自由地享受和参与开源。