1.7.0 • Published 3 years ago
api-sharp v1.7.0
特性
- 基于 Promise
- 支持数据转换
- 支持自动解析 JSON
- 支持设置请求超时
- 支持缓存（内存缓存、持久化存储缓存、自定义缓存）
- 支持接口 mock
- 支持失败重试
- 支持自定义日志
- 支持 TypeScript
- 支持自定义 HTTP 引擎（可适配所有 JS 运行时环境）
- 支持跨平台（浏览器、node.js、小程序、ReactNative、Weex 等）
- 浏览器使用 XMLHttpRequest 请求
- node.js 使用 http 请求
- 即将到来...（更多平台将会内置支持，不支持的可自行实现，扩展非常简单）
 |  |  |  |  |  |
|---|---|---|---|---|---|
| Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 11 ✔ |
安装
使用 npm 安装
$ npm install api-sharp使用 yarn 安装
$ yarn add api-sharp示例
创建 ApiSharp 实例
import {ApiSharp} from "api-sharp"
// 创建实例，可以传入全局配置，省略使用默认配置
const apiSharp = new ApiSharp({...})发送 GET 请求
// 请求服务器时间
const response = await apiSharp.request({ url: "/json/server_date" })
console.log(response)
// {
// "data": {
// "timestamp": 1569685733048
// },
// "from": "network",
// "api": {
// "url": "/json/server_date",
// "method": "GET",
// ...
// },
// "status": 200,
// "statusText": "OK",
// "headers": {
// "content-type": "application/json",
// "content-length": "27"
// }
// }发送 POST 请求
const response = await apiSharp.request({
url: "/json/server_date",
method: "POST",
body: {
format: "json"
}
})开启缓存（仅支持 GET 请求）
import {memoryCache, localStorageCache, sessionStorageCache} from "api-sharp"
const apiDescriptor = {
url: "/json/server_date",
enableCache: true,
// 设置缓存时间，单位毫秒
cacheTime: 10 * 1000,
// 设置缓存存储位置，默认存储在内存
cache: memoryCache
}
const response1 = await apiSharp.request(apiDescriptor)
const response2 = await apiSharp.request(apiDescriptor)
expect(response1.from).toEqual("network")
expect(response2.from).toEqual("cache")
expect(response1.data).toEqual(response2.data)开启接口数据 mock
const response = await apiSharp.request({
url: "/json/server_date",
enableMock: true,
// 模拟数据，支持任意 JS 数据类型
mockData: "mock data"
})
expect(response.data).toEqual("mock data")开启失败重试
const response = await apiSharp.request({
url: "/json/server_date",
enableRetry: true,
// 最大重试次数
retryTimes: 3
})开启日志（默认开启）
const response = await apiSharp.request({
url: "/json/articles",
method: "GET",
description: "文章列表",
enableLog: true,
// 自定义日志输出
formatLog: (type, api, _data) => {
console.log(type, api, _data)
}
})默认日志如下：
api-sharp API
ApiSharp实例方法
class ApiSharp {
request(url: string): Promise<IResponse>
request(api: ApiDescriptor): Promise<IResponse>
}请求方法支持的接口配置项
export type ApiDescriptor = CommonApiDescriptor & WebXhrApiDescriptor
interface CommonApiDescriptor {
/**
* 请求地址
*
* 支持相对地址（如`"/a/b/c"`）和绝对地址（如`"http://xyz.com/a/b/c"`）
*/
url: string
/**
* 基地址
*
* 默认`""`
*
* 例如：`'http://xyz.com'`, `'http://xyz.com/a/b'`
*/
baseURL?: string
/**
* HTTP 请求方法
*
* 支持 `"GET" | "POST"`
*
* 默认`"GET"`
*/
method?: HttpMethod
/**
* HTTP 请求头
*
* 如果设置了全局 headers，接口中的 headers 将于全局 headers 合并，且接口中的 header 优先级更高
*
* 默认`{"Content-Type": "application/json"}`
*/
headers?: HttpHeader
/**
* 接口描述
*
* 默认`""`
*/
description?: string
/**
* 请求 URL 中的查询参数
*
* 对象会转换成 URL 查询字符串并拼接在 URL 后面，转换规则：encodeURIComponent(k1)=encodeURIComponent(v1)&encodeURIComponent(k2)=encodeURIComponent(v2)...
*
* 例如：`{a: 1, b: 2}`会转换成`"a=1&b=2"`
*/
query?: QueryType
/**
* 请求体中的数据
*
* 仅支持 POST 请求，数据会转换成字符串传输，转换规则由请求头`Content-Type`决定：
* 请求头包含`Content-Type: application/json`时，数据序列化为 JSON 字符串
*
* 例如：`{a: 1, b: 2}`
*/
body?: BodyType
/**
* 响应的数据类型
*
* 支持类型如下：
*
* `"text"`：返回字符串
* `"json"`：返回`JSON.parse()`后的结果，如果解析失败返回`null`
*
* 默认`"json"`
*/
responseType?: ResponseType
/**
* 转换请求数据
*/
transformRequest?: (body: BodyType, headers: Object) => any
/**
* 检查响应数据是否有效
*
* 检查函数返回 true 表示成功，返回 false 表示失败（失败信息为 HTTP 状态码描述)，返回 Error 也表示失败（失败信息为 Error 中的错误消息）
*
* 默认：`(res) => res.status >= 200 && res.status < 300`
*/
validateResponse?: (res: IResponse) => boolean | Error
/**
* 转换响应数据
*/
transformResponse?: (data: any) => any
/**
* 开启缓存
*
* 并发请求相同接口且参数相同时，实际只会发出一个请求，因为缓存的是请求的 Promise
*
* 默认`false`
*/
enableCache?: boolean
/**
* 缓存持续时间，单位毫秒
*
* 下次取缓存时，如果缓存已存在的的时间超过该值，则对应缓存失效
*
* 默认 `5*60*1000`ms
*/
cacheTime?: number
/**
* 开启接口数据模拟
*
* 默认`false`
*/
enableMock?: boolean
/**
* 模拟的接口数据
*
* 默认`undefined`
*
* 例如：`{id: 1, name: 'jim'}`
*/
mockData?: any
/**
* 开启失败重试
*
* 默认`false`
*/
enableRetry?: boolean
/**
* 重试最大次数
*
* 默认`1`
*/
retryTimes?: number
/**
* 接口超时时间，单位毫秒
*
* 从发出请求起，如果 timeout 毫秒后接口未返回，接口调用失败。
*
* 默认`60*1000`ms
*/
timeout?: number
/**
* 开启控制台日志
*
* 默认为`process.env.NODE_ENV !== "production"`
*/
enableLog?: boolean
/**
* 格式化日志
*/
formatLog?: (type: LogType, api: ProcessedApiDescriptor, data?: any) => void
}
interface WebXhrApiDescriptor {
/**
* 跨域请求时是否带上用户信息（如Cookie和认证的HTTP头）
*
* 默认`false`
*/
withCredentials?: boolean
}请求返回的数据结构
export interface IResponse<T = any> {
// HTTP 响应状态码
status: number
// HTTP 响应状态描述
statusText: string
// HTTP 响应数据
data: T
// HTTP 响应头
headers: HttpHeader
// 本次请求响应数据的来源
from: "network" | "cache" | "mock"
// 本次请求的接口描述符
api: ProcessedApiDescriptor
}