next-api
一个通用的API客户端,通过简单的配置可以让很方便地提交ajax请求。
使用异步函数,使得API调用变得方便,可读性大幅提高
更新动态
2017年08月21日18:24:25
- 修正.d.ts中的部分定義錯誤
2017年08月19日21:02:12
- 增加文件上传进度支持,参见文件上传进度显示
- 修复fetchAPI中跨域请求默认值问题(不小心将cors写成cros)
- 整个项目重新使用typescript实现
2017年08月13日01:31:43
- 增加base64文件上传,参见base64文件上传方式
- api增加typescript支持,参见typescript中的API定义
安装和配置
npm install --save next-api
安装完成后其实已经可以使用了。 不过为了更加方便的使用,最好先进行一些配置
下面是一个配置的示例:
let api config apiType = ; //配置服务器响应数据类型,这里配置的是jsonconfigapiType = apiTypejson //配置API基地址,配置之后以后写url的时候,可以不用写前面的部分configbaseUrl = 'http://localhost:3000/api/' //配置fetch选项,fetch选项的具体内容请参考 fetch api 相关类容//这里假设在FetchAPI的header中添加一个tokenconfigfetchOption = headers: token:'xxxxxxxxx' //接收到数据时的数据处理配置,//可以将接收到的数据进行转换,并返回一个新的数据,//同时还可以在这个函数中抛出异常,所抛出的异常会在FetchAPI的catch中捕获//这个函数返回的数据也就是API调用的结果(在下一节会介绍)。config{ //如果服务器返回了错误则抛出异常 ifdataerror throw dataerror //否则将服务器得到的数据取出来 return datadata;} //错误处理配置//当发生错误时会调用此函数。//此函数接受一个Error对象和当前状态码(可能没有状态码),并返回一个新的Error对象//错误的来源可能有:服务器关闭,服务器返回了其他状态码,API返回的错误(该错误有onData函数处理并抛出),以及其他用户代码中的错误//这个函数必须返回一个Error对象,否则API调用时捕获到的错误可能不好处理。config{ //服务器返回403,跳转到登录 ifstatus && status==403 windowlocationhref = '/login' return '身份过期,正在跳转到登录页面' else return err; }
如何使用
使用API分成两步,API的定义和API的调用,
目前此api接口的请求方式有5种:get、post、put、del(delete)、pacth,通过api.xxx来生成对应请求方式的API。
一般来说,将API的定义统一放在一个文件中,方便调用。
假如说有两组API:用户API和分组API,用户API包括登录和修改个人信息, 分组API包括创建和删除分组。
那么可以有这样一个目录机构进行存放(当然也可以是其他的结构,按个人需求而定):
api (api目录)
| user.js (用户管理API)
| group.js (分组管理API)
那么user.js可以这么写(group.js就不做演示了)
//导入next-api的api对象,该对象用于创建apilet api = //定义登录API,该api以get方式进行请求//登录并返回用户信息exportslogin = api //定义修改用户信息API,该API以post方式进行请求//修改个人信息exportsupdateInfo = api
API定义完成后使用就非常简单了,下面给出一个简单的例子来演示用户登录:
let login = //假如用户点击登录按钮的时候调用这个函数//这个函数必须是一个异步函数(前面有async),否则调用接口时只能使用then,而不能使用await。//接收两个参数:账号和密码{ try //调用登录API得到用户信息,注意必须加上await关键字 let myInfo = await console catche console }
上面介绍的是异步函数的调用方法,使用这种可以让代码看起来更清晰明了。
但是如果你不想使用异步函数,怎么办呢?
因为api返回的结果是一个Promise对象,因此你可以用then和catch来进行处理。
上面例子的另一种写法:
let login = //假如用户点击登录按钮的时候调用这个函数{ //调用登录API得到用户信息,注意必须加上await关键字 //登录结果处理 //出错处理 }
除此之外,还可以通过引入script标签,例如
<!--导入next-api --> <!--一般来说需要进行配置 --> <!--使用 -->
base64文件上传方式
这里说明一下base64文件上传的使用方式。
base64文件上传使用的场景最常见的估计就是进行用户头像的设置了, 目前许多头像设置控件都是在浏览器端进行图片剪裁,得到一个base64的图片, 考虑到这个问题,增加了base64文件上传。
- 首先,需要构建一个Base64File对象,
- 然后,就没有然后了,直接像使用普通文件一样使用Base64File对象。
下面是一个示例:
//太长,所以后面的省略了let str = "data:image/jpeg;base64,/9j/4AAQSkZJRgAB..." //先定义一个APIlet uploadAvatar = api //架设点击某个按钮调用这个函数进行设置头像async { //创建文件,第一个参数是base64字符串,第二个参数是文件名称,两个参数都是必须的 let file = base64str 'avatar.png' //提交头像 await }
typescript中的API定义
相信很多人在使用typescript的时候都会感受到它的牛逼之处,所以我就不再多说了。
这里使用了typescript的泛型来定义API的参数和返回值, 可以在目前的绝大多数代码编辑器中实现代码提示。
接收两个类型,第一个是参数类型,第二个是返回值类型。
使用typescript可以这样定义API:
//定义用户登录API,}>'/user/token'
这样定义之后,就能有很好的代码提示以及参数校验效果了。
文件上传进度使用说明
文件上传使用的是传统的XMLHttpRequest来实现的,以便于获取上传进度。
用法和之前的API基本一致,仅有一下几点不同
- config中的fetchOption无效,取而代之的是xhrOption,具体细节可以参考 index.d.ts中的定义
- 调用上传API时增加了两个参数,用于标识上传的文件以及进度的获取
简单用法:
//创建APIlet setAvatar = upload //调用API{ //调用API设置头像,第2、3个参数可以不用传递 let result = await //如果不适用第2、3个参数,则和之前的API没什么区别了 // let result = await setAvatar({file:inputDom.files[0], user:user.id}) console}
除此之外,文件上传API提供了一个上传列表,如果有需要,你可以方便地使用它。
简单用法如下:
//假设这个dom用于展示上传列表let fileUploadListDom = document//设置一个定时器,定期检测文件进度,并展示到界面上