sfyyy
/
axios-miniprogram
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 介绍 response

pull/41/head
zjx0905 2023-04-15 12:20:09 +08:00
parent d93d949a3b
commit afc02415ee
27 changed files with 184 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -5,6 +5,7 @@ node_modules
# Docs
dist
docs/.vitepress/cache
docs/pages/intro.md
# Mac OS
.DS_Store

36
README.md
View File

@ -20,33 +20,9 @@
[中文文档](https://axios-miniprogram.com)
## 安装
## 什么是 axios-miniprogram ？
使用 npm：
```bash
$ npm i axios-miniprogram
```
yarn
```bash
$ yarn add axios-miniprogram
```
pnpm
```bash
$ pnpm i axios-miniprogram
```
[原生小程序也可以直接下载源码包](https://github.com/zjx0905/axios-miniprogram/releases)
# 简介
## 什么是 axios-miniprogram？
axios-miniprogram 是一款为小程序平台量身定制的轻量级请求库，支持跨平台使用，同时也支持多种导入方式，可用于原生小程序项目，也可用于第三方框架项目，用法上同 [axios](git@github.com:axios/axios.git) 类似。
axios-miniprogram 是一款为小程序平台量身定制的轻量级请求库，支持跨平台使用，同时也支持多种导入方式，可用于原生小程序项目，也可用于第三方框架项目，用法上同 [axios](https://github.com/axios/axios.git) 类似。
## 特性
@ -58,11 +34,11 @@ axios-miniprogram 是一款为小程序平台量身定制的轻量级请求库
- 支持 自定义参数序列化。
- 支持 自定义转换数据。
- 支持 自定义错误处理。
- 支持 自定义平台适配器
- 支持 上传/下载
- 支持 派生领域
- 支持 自定义平台适配器。
- 支持 上传/下载。
- 支持 派生领域。
## 目前支持的平台
## 目前内部支持的平台
- [微信小程序](https://developers.weixin.qq.com/miniprogram/dev/framework/?from=axios-miniprogram)
- [支付宝小程序](https://opendocs.alipay.com/mini/developer/getting-started?from=axios-miniprogram)

1
docs/.vitepress/config.ts
View File

@ -99,6 +99,7 @@ function sidebar() {
{ text: 'DELETE 请求', link: '/basics/delete' },
{ text: 'TRACE 请求', link: '/basics/trace' },
{ text: 'CONNECT 请求', link: '/basics/connect' },
{ text: '响应体', link: '/basics/response' },
],
},

2
docs/pages/api/axios.md
View File

@ -4,7 +4,7 @@
`axios.Axios`是一个类，其实`axios`就是`axios.Axios`类的实例改造而来的，`axios.create(defaults)`创建的也是`axios.Axios`的实例。
直接实例化`axios.Axios`可以得到一个`原始实例`，不能当函数调用，传入的自定义配置就是`原始实例`的默认配置，而不会像`axios.create(defaults)`一样去合并`axios`中的默认配置。
直接实例化`axios.Axios`可以得到一个`原始实例`，不能当函数调用，传递的自定义配置就是`原始实例`的默认配置，而不会像`axios.create(defaults)`一样去合并`axios`中的默认配置。
```ts
const instance = new axios.Axios({

2
docs/pages/api/create.md
View File

@ -2,7 +2,7 @@
## `axios.create(defaults)`
创建一个`自定义实例`，传入的自定义默认配置`defaults`会和`axios`的默认配置`axios.defaults`合并成`自定义实例`的默认配置。
创建一个`自定义实例`，传递的自定义默认配置`defaults`会和`axios`的默认配置`axios.defaults`合并成`自定义实例`的默认配置。
`自定义实例`拥有和`axios`相同的调用方式和请求方法的别名。

2
docs/pages/api/fork.md
View File

@ -4,7 +4,7 @@
现在很多公司后端采用的是微服务架构，您可以为每个服务单独派生一个领域进行请求管理。
派生领域，如果传入 `defaults.baseURL` 为相对路径，则会对 `axios.defaults.baseURL` 和 `defaults.baseURL` 进行拼接。
派生领域，如果传递 `defaults.baseURL` 为相对路径，则会对 `axios.defaults.baseURL` 和 `defaults.baseURL` 进行拼接。
`domain` 除了拥有和 `axios` 相同的调用方式和请求方法的别名之外，同时还可以复用 `axios` 上的拦截器，这一点是 `axios.create(defaults)` 做不到了。

4
docs/pages/basics/connect.md
View File

@ -10,7 +10,7 @@ title: CONNECT 请求
## 普通的 `CONNECT` 请求
您可以传入第一个参数 `url` 发送 `CONNECT` 请求。
您可以传递第一个参数 `url` 发送 `CONNECT` 请求。
```ts
import axios from 'axios-miniprogram';
@ -27,7 +27,7 @@ axios
## 携带自定义配置的 `CONNECT` 请求
您也可以额外传入第二个参数 `config` 发送携带自定义配置的 `CONNECT` 请求。
您也可以额外传递第二个参数 `config` 发送携带自定义配置的 `CONNECT` 请求。
```ts
import axios from 'axios-miniprogram';

6
docs/pages/basics/delete.md
View File

@ -10,7 +10,7 @@ HTTP DELETE 请求方法用于删除指定的资源。
## 普通的 `DELETE` 请求
您可以传入第一个参数 `url` 发送 `DELETE` 请求。
您可以传递第一个参数 `url` 发送 `DELETE` 请求。
```ts
import axios from 'axios-miniprogram';
@ -27,7 +27,7 @@ axios
## 携带参数的 `DELETE` 请求
您也可以额外传入第二个参数 `params` 发送携带参数的 `DELETE` 请求。
您也可以额外传递第二个参数 `params` 发送携带参数的 `DELETE` 请求。
```ts
import axios from 'axios-miniprogram';
@ -46,7 +46,7 @@ axios
## 携带自定义配置的 `DELETE` 请求
您也可以额外传入第三个参数 `config` 发送携带自定义配置的 `DELETE` 请求。
您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `DELETE` 请求。
```ts
import axios from 'axios-miniprogram';

6
docs/pages/basics/get.md
View File

@ -10,7 +10,7 @@ HTTP GET 方法请求指定的资源。使用 GET 的请求应该只用于获取
## 普通的 `GET` 请求
您可以传入第一个参数 `url` 发送 `GET` 请求。
您可以传递第一个参数 `url` 发送 `GET` 请求。
```ts
import axios from 'axios-miniprogram';
@ -27,7 +27,7 @@ axios
## 携带参数的 `GET` 请求
您也可以额外传入第二个参数 `params` 发送携带参数的 `GET` 请求。
您也可以额外传递第二个参数 `params` 发送携带参数的 `GET` 请求。
```ts
import axios from 'axios-miniprogram';
@ -46,7 +46,7 @@ axios
## 携带自定义配置的 `GET` 请求
您也可以额外传入第三个参数 `config` 发送携带自定义配置的 `GET` 请求。
您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `GET` 请求。
```ts
import axios from 'axios-miniprogram';

6
docs/pages/basics/head.md
View File

@ -10,7 +10,7 @@ HTTP HEAD 方法请求资源的头部信息，并且这些头部与 HTTP GET 方
## 普通的 `HEAD` 请求
您可以传入第一个参数 `url` 发送 `HEAD` 请求。
您可以传递第一个参数 `url` 发送 `HEAD` 请求。
```ts
import axios from 'axios-miniprogram';
@ -27,7 +27,7 @@ axios
## 携带参数的 `HEAD` 请求
您也可以额外传入第二个参数 `params` 发送携带参数的 `HEAD` 请求。
您也可以额外传递第二个参数 `params` 发送携带参数的 `HEAD` 请求。
```ts
import axios from 'axios-miniprogram';
@ -46,7 +46,7 @@ axios
## 携带自定义配置的 `HEAD` 请求
您也可以额外传入第三个参数 `config` 发送携带自定义配置的 `HEAD` 请求。
您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `HEAD` 请求。
```ts
import axios from 'axios-miniprogram';

4
docs/pages/basics/options.md
View File

@ -10,7 +10,7 @@ HTTP OPTIONS 方法用于获取目的资源所支持的通信选项。客户端
## 普通的 `OPTIONS` 请求
您可以传入第一个参数 `url` 发送 `OPTIONS` 请求。
您可以传递第一个参数 `url` 发送 `OPTIONS` 请求。
```ts
import axios from 'axios-miniprogram';
@ -27,7 +27,7 @@ axios
## 携带自定义配置的 `OPTIONS` 请求
您也可以额外传入第二个参数 `config` 发送携带自定义配置的 `OPTIONS` 请求。
您也可以额外传递第二个参数 `config` 发送携带自定义配置的 `OPTIONS` 请求。
```ts
import axios from 'axios-miniprogram';

6
docs/pages/basics/patch.md
View File

@ -12,7 +12,7 @@ title: PATCH 请求
## 普通的 `PATCH` 请求
您可以传入第一个参数 `url` 发送 `PATCH` 请求。
您可以传递第一个参数 `url` 发送 `PATCH` 请求。
```ts
import axios from 'axios-miniprogram';
@ -29,7 +29,7 @@ axios
## 携带数据的 `PATCH` 请求
您也可以额外传入第二个参数 `data` 发送携带数据的 `PATCH` 请求。
您也可以额外传递第二个参数 `data` 发送携带数据的 `PATCH` 请求。
```ts
import axios from 'axios-miniprogram';
@ -49,7 +49,7 @@ axios
## 携带自定义配置的 `PATCH` 请求
您也可以额外传入第三个参数 `config` 发送携带自定义配置的 `PATCH` 请求。
您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `PATCH` 请求。
```ts
import axios from 'axios-miniprogram';

6
docs/pages/basics/post.md
View File

@ -10,7 +10,7 @@ HTTP POST 方法发送数据给服务器。请求主体的类型由 Content-Type
## 普通的 `POST` 请求
您可以传入第一个参数 `url` 发送 `POST` 请求。
您可以传递第一个参数 `url` 发送 `POST` 请求。
```ts
import axios from 'axios-miniprogram';
@ -27,7 +27,7 @@ axios
## 携带数据的 `POST` 请求
您也可以额外传入第二个参数 `data` 发送携带数据的 `POST` 请求。
您也可以额外传递第二个参数 `data` 发送携带数据的 `POST` 请求。
```ts
import axios from 'axios-miniprogram';
@ -47,7 +47,7 @@ axios
## 携带自定义配置的 `POST` 请求
您也可以额外传入第三个参数 `config` 发送携带自定义配置的 `POST` 请求。
您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `POST` 请求。
```ts
import axios from 'axios-miniprogram';

6
docs/pages/basics/put.md
View File

@ -10,7 +10,7 @@ HTTP PUT 请求方法使用请求中的数据创建或者替换目标资源。
## 普通的 `PUT` 请求
您可以传入第一个参数 `url` 发送 `PUT` 请求。
您可以传递第一个参数 `url` 发送 `PUT` 请求。
```ts
import axios from 'axios-miniprogram';
@ -27,7 +27,7 @@ axios
## 携带数据的 `PUT` 请求
您也可以额外传入第二个参数 `data` 发送携带数据的 `PUT` 请求。
您也可以额外传递第二个参数 `data` 发送携带数据的 `PUT` 请求。
```ts
import axios from 'axios-miniprogram';
@ -48,7 +48,7 @@ axios
## 携带自定义配置的 `PUT` 请求
您也可以额外传入第三个参数 `config` 发送携带自定义配置的 `PUT` 请求。
您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `PUT` 请求。
```ts
import axios from 'axios-miniprogram';

12
docs/pages/basics/request.md
View File

@ -10,7 +10,7 @@ title: 发送请求
## 基础用法
您可以直接传入 `url` 发送请求，默认发送的是 `GET` 方法请求。
您可以直接传递 `url` 发送请求，默认发送的是 `GET` 方法请求。
```ts
import axios from 'axios-miniprogram';
@ -27,7 +27,7 @@ axios
## 携带自定义配置
您也可以传入第二个参数 `config`，用于指定请求方法以及其他配置项。
您也可以传递第二个参数 `config`，用于指定请求方法以及其他配置项。
```ts
import axios from 'axios-miniprogram';
@ -50,7 +50,7 @@ axios
## 仅有自定义配置
您也可以忽略以上示例，直接传入 `config` 发送请求。
您也可以忽略以上示例，直接传递 `config` 发送请求。
```ts
import axios from 'axios-miniprogram';
@ -69,3 +69,9 @@ axios
// 失败之后做些什么
});
```
## 说明
您可能发现 `axios.request()` 和 `axios()` 使用方式完全一致，为什么？
其实他们本就是同一个请求函数，`axios` 是基于 `axios.request` 添加了一系列工具函数改造而来，其目的是为了简化使用。

64
docs/pages/basics/response.md Normal file
View File

@ -0,0 +1,64 @@
---
title: 响应体
---
# {{ $frontmatter.title }}
::: tip {{ $frontmatter.title }}
response 是响应正文。返回的数据类型为 String/Object/ArrayBuffer。这取决于请求的 responseType 属性。
:::
## 通用属性
请求成功返回的 `response` 带有这些属性。
```ts
import axios from 'axios-miniprogram';
axios('https//api.com')
.then((response) => {
const {
// 开发者服务器返回的 HTTP 状态码
status,
// 状态文本
statusText,
// 开发者服务器返回的数据
data,
// 开发者服务器返回的响应头
headers,
// 请求配置
config,
// 请求任务
request,
} = response;
})
.catch((error) => {
// 失败之后做些什么
});
```
## 平台属性
请求成功返回的 `response` 可能还带有平台特有的属性，具体情况取决于平台特性。
微信小程序示例:
```ts
import axios from 'axios-miniprogram';
axios('https//api.com')
.then((response) => {
const {
// 开发者服务器返回的 cookies，格式为字符串数组
cookies,
// 网络请求过程中一些调试信息
profile,
// 开发者服务器返回的数据
} = response;
})
.catch((error) => {
// 失败之后做些什么
});
```
想要了解更多请自行参阅对应的小程序文档。

4
docs/pages/basics/trace.md
View File

@ -10,7 +10,7 @@ HTTP TRACE 方法实现沿通向目标资源的路径的消息环回（loop-back
## 普通的 `TRACE` 请求
您可以传入第一个参数 `url` 发送 `TRACE` 请求。
您可以传递第一个参数 `url` 发送 `TRACE` 请求。
```ts
import axios from 'axios-miniprogram';
@ -27,7 +27,7 @@ axios
## 携带自定义配置的 `TRACE` 请求
您也可以额外传入第二个参数 `config` 发送携带自定义配置的 `TRACE` 请求。
您也可以额外传递第二个参数 `config` 发送携带自定义配置的 `TRACE` 请求。
```ts
import axios from 'axios-miniprogram';

2
docs/pages/config/download.md
View File

@ -19,7 +19,7 @@ axios
},
)
.then((response) => {
// 用户文件路径 (本地路径)。传入 filePath 时会返回，跟传入的 filePath 一致
// 用户文件路径 (本地路径)。传递 filePath 时会返回，跟传递的 filePath 一致
response.data.filePath;
// 用户文件路径 (本地临时路径)。
response.data.tempFilePath;

2
docs/pages/config/error-handler.md
View File

@ -18,7 +18,7 @@ const instance = axios.create({
});
```
也可以发送请求时通过自定义配置传入。
也可以发送请求时通过自定义配置传递。
```ts
axios('/user', {

2
docs/pages/config/preview.md
View File

@ -11,7 +11,7 @@ axios.defaults.headers.post['Content-Type'] =
## 自定义实例默认配置
可以创建时传入。
可以创建时传递。
```ts
const instance = axios.create({

2
docs/pages/config/upload.md
View File

@ -14,7 +14,7 @@ axios.post(
name: 'file',
// 文件路径，必填
filePath: '/file/image.png',
// 可以传入更多自定义字段，这些自定义字段最终会以 formData 的形式发送给服务端 (前提是平台支持)
// 可以传递更多自定义字段，这些自定义字段最终会以 formData 的形式发送给服务端 (前提是平台支持)
custom1: 'name',
custom2: 'id',
},

190
docs/pages/start.md
View File

@ -22,62 +22,69 @@ $ pnpm install -D axios-miniprogram
::::
[原生小程序也可以直接下载源码包](https://github.com/zjx0905/axios-miniprogram/releases)
## 引用
:::: code-group
```ts [ES Module]
import axios from 'axios-miniprogram';
axios('test');
```
```ts [Commonjs]
const axios = require('axios-miniprogram').default;
axios('test');
```
::::
## 使用
### 如何引入
### `axios(url, config?)`
可以通过把 `url` 和 `config` 传递给 `axios` 来发送请求。
注意： `config` 为选填
```ts
// esm
import axios from 'axios-miniprogram';
// cjs
const axios = require('axios-miniprogram');
// 使用
axios('/user');
// 默认发送 GET 请求
axios('https://api.com/test')
.then((response) => {
// 请求成功后做些什么
})
.catch((error) => {
// 请求失败后做些什么
});
// 发送 POST 请求
axios('https://api.com/test', {
method: 'POST',
})
.then((response) => {
// 请求成功后做些什么
})
.catch((error) => {
// 请求失败后做些什么
});
```
### `axios(config)`
可以通过将相关配置传递给`axios`来发送请求。
也可以直接把 `config` 传递给 `axios` 来发送请求。
```ts
// 发送 GET 请求
axios({
url: '/user',
method: 'get',
params: {
id: 1,
},
})
.then((response) => {
// 请求成功后做些什么
})
.catch((error) => {
// 请求失败后做些什么
});
import axios from 'axios-miniprogram';
// 发送 POST 请求
axios({
url: '/user',
method: 'post',
data: {
id: 1,
},
})
.then((response) => {
// 请求成功后做些什么
})
.catch((error) => {
// 请求失败后做些什么
});
```
### `axios(url, config?)`
也可以通过直接把`url`传给`axios`来发送请求。
```ts
// 默认发送 GET 请求
axios('/user')
axios({
url: 'https://api.com/test',
})
.then((response) => {
// 请求成功后做些什么
})
@ -86,8 +93,9 @@ axios('/user')
});
// 发送 POST 请求
axios('/user', {
method: 'post',
axios({
url: 'https://api.com/test',
method: 'POST',
})
.then((response) => {
// 请求成功后做些什么
@ -99,82 +107,20 @@ axios('/user', {
还可以使用请求方法的别名来简化请求。
- ##### axios.request(config)
- ##### axios.options(url, config?)
- ##### axios.get(url, params?, config?)
- ##### axios.head(url, params?, config?)
- ##### axios.post(url, data?, config?)
- ##### axios.put(url, data?, config?)
- ##### axios.delete(url, params?, config?)
- ##### axios.trace(url, config?)
- ##### axios.connect(url, config?)
- [axios.request(url, config?) | axios.request(config)](./basics/request.md)
- [axios.options(url, config?)](./basics/options.md)
- [axios.get(url, params?, config?)](./basics/get.md)
- [axios.head(url, params?, config?)](./basics/head.md)
- [axios.post(url, data?, config?)](./basics/post.md)
- [axios.put(url, data?, config?)](./basics/put.md)
- [axios.patch(url, data?, config?)](./basics/patch.md)
- [axios.delete(url, params?, config?)](./basics/delete.md)
- [axios.trace(url, config?)](./basics/trace.md)
- [axios.connect(url, config?)](./basics/connect.md)
常用例子，其他同理：
还提供了一系列工具方法。
```ts
// 发送 GET 请求
axios.get('/user');
// 携带参数
axios.get('/user', {
test: 1,
});
// 携带额外配置
axios.get(
'/user',
{
id: 1,
},
{
headers: {
'Content-Type': 'application/json; charset=utf-8',
},
},
);
// 发送 POST 请求
axios.post('/user');
// 携带数据
axios.post('/user', {
id: 1,
});
// 携带额外配置
axios.post(
'/user',
{
id: 1,
},
{
headers: {
'Content-Type': 'application/json; charset=utf-8',
},
},
);
```
## 动态 URL
您可以使用动态 URL 提高 RESTful API 的书写体验。
```ts
axios.get('/user/:id', {
id: 1,
});
```
## 响应体`response`
非全平台兼容的属性只会在平台支持的情况下生效。
| 属性 | 类型 | 说明 | 全平台兼容 |
| :--------- | :------------------------ | :------------------------------------------- | :--------- |
| status | Number | 状态码 | 是 |
| statusText | String | 状态文本 | 是 |
| data | String/Object/ArrayBuffer | 开发者服务器返回的数据 | 是 |
| headers | Object | 响应头 | 是 |
| config | Object | Axios 请求配置 | 是 |
| cookies | Array<.String> | 开发者服务器返回的 cookies，格式为字符串数组 | |
| profile | Object | 网络请求过程中一些关键时间点的耗时信息 | |
- `axios.create(defaults?)` 创建新的 `axios` 实例
- `axios.createAdapter(platform)` 创建平台适配器
- `axios.isCancel(error)` 判断异常是否来自取消请求
- `axios.isAxiosError(error)` 判断异常是否来自请求响应

2
src/axios.ts
View File

@ -41,8 +41,6 @@ export interface AxiosStatic extends AxiosInstance {
create(defaults?: AxiosRequestConfig): AxiosInstance;
/**
* 创建适配器
*
* @param platform 平台
*/
createAdapter: typeof createAdapter;
/**

2
test/core/AxiosDomain.test.ts
View File

@ -106,7 +106,7 @@ describe('src/core/AxiosDomain.ts', () => {
expect(cb.mock.calls.length).toBe(l);
});
test('应该可以直接传入 config 调用请求方法', () => {
test('应该可以直接传递 config 调用请求方法', () => {
const cb = vi.fn();
const d = {
baseURL: 'http://api.com',

2
test/core/cancel.test.ts
View File

@ -17,7 +17,7 @@ describe('src/helpers/cancel.ts', () => {
expect(c.toString()).toBe('Cancel');
});
test('传入参数时应该有正确的返回结果', () => {
test('传递参数时应该有正确的返回结果', () => {
const c = new Cancel('error');
expect(c.message).toBe('error');

2
test/core/createError.test.ts
View File

@ -14,7 +14,7 @@ describe('src/core/createError.ts', () => {
expect(checkStack(err)).toBeTruthy();
});
test('应该支持传入更多参数', () => {
test('应该支持传递更多参数', () => {
const c = {};
const res = {};
const req = {} as any;

2
test/helpers/ignore.test.ts
View File

@ -2,7 +2,7 @@ import { describe, test, expect } from 'vitest';
import { ignore } from '@/helpers/ignore';
describe('src/helpers/ignore.ts', () => {
test('不应该改变传入的对象', () => {
test('不应该改变传递的对象', () => {
expect(ignore({ v1: 1 })).toEqual({ v1: 1 });
});