@iscdev/easy-api NPM

easy-api

简易的api请求封装，基于fetch

附带接口集合生成器(gen-api)

安装

npm i -S @iscdev/easy-api

使用

import {callApi} from '@iscdev/easy-api'

callApi('https://xxx.com/aaa/bbb', {...options})

api

`callApi` 调用api接口

定义：function callApi(url: string, options?: CallApiOptions)

参数

url: string，待请求的链接，相对路径和绝对路径皆可
options?: CallApiOptions，配置

`CallApiOptions` 配置属性

method?: 'GET' | 'POST' | 'DELETE' | 'PUT'，请求方法, 默认：'GET'
headers?: 键值对，头信息
params?: 任何，数据
requestContentType?: 'form-data' | 'form-urlencoded' | 'json' | 'raw' | 'binary'，请求体类型，默认：'json'
plugins?: Plugin[]，插件集合
parseResponseFunc?: ResponseParseFunc，响应体解析方法，默认为code/data的风格

返回值

Promise<any>

默认情况下，如果请求成功则返回data字段，如果失败或者网络异常则抛出异常，具体看parseResponseFunc配置的解析风格

`pollingApi` 轮询api接口

定义：pollingApi<T>(callApiFunc: () => Promise<T>, options?: PollingApiOptions<T>): () => void

参数

callApiFunc: () => Promise<T>，一个callApi的请求
options?: PollingApiOptions<T>，配置

`PollingApiOptions` 配置属性

interval?: number，间隔，默认：1000ms
times?: number，次数，小于0表示无限轮询，大于0表示有限次数轮询，等于0表示不请求也不轮询，默认：-1
onResponse?: (data: T) => boolean | void，消息回调方法，如果方法返回true则终止轮询
onError?: (error: Error | CodeError) => boolean | void，错误回调方法，如果方法返回true则继续轮询，优先级高于interruptWhenError
interruptWhenError?: boolean，当发生错误时终止轮训，默认：true

返回值

返回一个方法，调用即可终止轮询

插件

支持插件系统

内置了一个插件：apiLogger，用于在控制台打印接口调用日志

也可以自己开发插件，只要实现如下接口即可：

interface Plugin {
    /*请求初始化*/
    init?: (context: FetchContext) => boolean | void
    /*请求前*/
    beforeCall?: (context: FetchContext) => boolean | void
    /*遇到网络错误*/
    onCatchNetError?: (context: FetchContext) => boolean | void
    /*请求后*/
    afterCall?: (context: FetchContext) => boolean | void
    /*遇到接口错误*/
    onCatchError?: (context: FetchContext) => boolean | void
}

使用

插件的使用分为全局设置和单次设置

全局设置

callApi.plugins = [apiLogger({ beauty: true })];
只要在设置callApi.plugins即可直接修改全局的插件列表，此后的所有请求都会应用这些插件

单次设置

callApi('https://xxx.com/aaa/bbb', {plugins:[apiLogger({ beauty: true })]})
这样设置的插件仅对该次请求有效

注意：单次设置的插件先于全局设置的插件

接口集合生成器cli

call-api只是暴露出来的较为低级的api，实际开发中会将其进行二次封装。本库提供了buildApiCollection方法，来生成接口集合

接口集合构造器

定义：function buildApiCollection<T>(apiConfigs:any, apis?:any): Proxy<T>

参数

apiConfigs:键值对，接口配置，会通过生成器生成的
apis?:object，传入原始的api集合对象

返回值

Proxy<T> 返回一个代理对象即为接口集合实例，泛型是调用时传入的，泛型类型也是生成器生成的，可以直接在对象上点出接口分组和接口名( 如果调用时传入泛型T的话)

接口集合实例说明

为了能通过字面量来编写调用代码，所以分组名和接口名都会转换成驼峰式的
如果同一个接口链接通过method来区分功能的，则会直接使用形如.get, .post, .delete的方法名来补全
如果链接完整，也会使用method来做为方法名的前缀，如：getStatusList, postSaveByProductKey

返回值为Promise<xxx>，其中xxx为传入的泛型类型

cli使用

只要安装了@isc-dev/easy-api就可以使用该cli，也可以全局安装

目前仅支持swagger的文档转换

参数

-i --input 文档接口地址或者导出的json文档
-o --output 输出目录, 如: "src/api" (默认: ".")
-r --root-path 接口url的根路径, 如: "/api/bios/ibms-basic" (默认: "")
-n --namespace 命名空间, 如: "basic" (默认: "")
-h --headers <string...> 头部信息，一般用于鉴权 , 如: "Cookie:abc=123"

例子：
gen-api -o src/api -n basic -r /api/bios/ibms-basic -i 'http://10.30.30.87:38080/api/bios/ibms-basic/v3/api-docs' -h 'Cookie: X-Isyscore-Permission-Sid=1e4617a5-394c-44ba-be7a-fbde72cfce08'
或使用本地swagger导出的json文件
gen-api -o src/api -n basic -r /api/bios/ibms-basic -i '/aaa/bbb.json'

如果生成成功，则会在输出目录写入两个文件，这两个文件需配合使用

命名空间-types.d.ts 接口定义文件
命名空间-configs.json 接口配置文件

命名空间即为命令行执行是传入的-n参数，下面以basic举例

然后就可以暴露出接口集合实例了：

import basicConfig from './basic-configs.json';
import {basic} from '@/api/basic-types';

export const basicApi = buildApiCollection<basic.IApis>(basicConfig);

随后即可使用，且有智能提示