Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

next-api

2.0.4 • Public • Published

next-api

一个通用的API客户端,通过简单的配置可以让很方便地提交ajax请求。

使用异步函数,使得API调用变得方便,可读性大幅提高

更新动态

2017年08月21日18:24:25

  1. 修正.d.ts中的部分定義錯誤

2017年08月19日21:02:12

  1. 增加文件上传进度支持,参见文件上传进度显示
  2. 修复fetchAPI中跨域请求默认值问题(不小心将cors写成cros)
  3. 整个项目重新使用typescript实现

2017年08月13日01:31:43

  1. 增加base64文件上传,参见base64文件上传方式
  2. api增加typescript支持,参见typescript中的API定义

安装和配置

npm install --save next-api

安装完成后其实已经可以使用了。 不过为了更加方便的使用,最好先进行一些配置

下面是一个配置的示例:

let {api, config, apiType} = require('next-api');
 
//配置服务器响应数据类型,这里配置的是json
config.apiType = apiType.json
 
//配置API基地址,配置之后以后写url的时候,可以不用写前面的部分
config.baseUrl = 'http://localhost:3000/api/'
 
//配置fetch选项,fetch选项的具体内容请参考 fetch api 相关类容
//这里假设在FetchAPI的header中添加一个token
config.fetchOption = {
    headers:{
        token:'xxxxxxxxx'
    }
}
 
//接收到数据时的数据处理配置,
//可以将接收到的数据进行转换,并返回一个新的数据,
//同时还可以在这个函数中抛出异常,所抛出的异常会在FetchAPI的catch中捕获
//这个函数返回的数据也就是API调用的结果(在下一节会介绍)。
config.onData = data=>{
    //如果服务器返回了错误则抛出异常
    if(data.error) throw new Error(data.error)
    //否则将服务器得到的数据取出来
    return data.data;
}
 
//错误处理配置
//当发生错误时会调用此函数。
//此函数接受一个Error对象和当前状态码(可能没有状态码),并返回一个新的Error对象
//错误的来源可能有:服务器关闭,服务器返回了其他状态码,API返回的错误(该错误有onData函数处理并抛出),以及其他用户代码中的错误
//这个函数必须返回一个Error对象,否则API调用时捕获到的错误可能不好处理。
config.onError = (err, status)=>{
    //服务器返回403,跳转到登录
    if(status && status==403){
        window.location.href = '/login'
        return new Error('身份过期,正在跳转到登录页面')
    }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对象,该对象用于创建api
let {api} = require('next-api')
 
//定义登录API,该api以get方式进行请求
//登录并返回用户信息
exports.login = api.get('/user/login')
 
//定义修改用户信息API,该API以post方式进行请求
//修改个人信息
exports.updateInfo = api.post('/user/info/update')

API定义完成后使用就非常简单了,下面给出一个简单的例子来演示用户登录:

let {login} = require('./api/user')
 
//假如用户点击登录按钮的时候调用这个函数
//这个函数必须是一个异步函数(前面有async),否则调用接口时只能使用then,而不能使用await。
//接收两个参数:账号和密码
async function handleLogin(number, passwd){
    try{
        //调用登录API得到用户信息,注意必须加上await关键字
        let myInfo = await login({number, passwd})
        console.log('登录成功,用户信息是', myInfo)
    }catch(e){
        console.log('登录失败,原因:' + e.message)
    }
}

上面介绍的是异步函数的调用方法,使用这种可以让代码看起来更清晰明了。

但是如果你不想使用异步函数,怎么办呢?

因为api返回的结果是一个Promise对象,因此你可以用then和catch来进行处理。

上面例子的另一种写法:

let {login} = require('./api/user')
 
//假如用户点击登录按钮的时候调用这个函数
function handleLogin(number, passwd){
    //调用登录API得到用户信息,注意必须加上await关键字
    login({number, passwd})
        //登录结果处理
        .then(myInfo=>{
            console.log('登录成功,用户信息是', myInfo)
        })
        //出错处理
        .catch(e=>{
            console.log('登录失败,原因:' + e.message)
        })
}

除此之外,还可以通过引入script标签,例如

<!--导入next-api  -->
<script src="js/next-api/dist/next-api.min.js"></script>
 
<!--一般来说需要进行配置  -->
<script>
//这里可以对next-api进行一些初始的配置操作
//包括设置header、设置跨域请求、服务器数据以及错误处理,等等。。。
</script> 
 
<!--使用  -->
<script>
//定义登录接口
var login = nextApi.api.get('/user/login')
 
//调用登录接口
login({number:'admin', passwd:'admin'})
    .then(function(myInfo){
        console.log(myInfo)
    })
    .catch(function(e){
        console.error(e)
    })
</script> 

base64文件上传方式

这里说明一下base64文件上传的使用方式。

base64文件上传使用的场景最常见的估计就是进行用户头像的设置了, 目前许多头像设置控件都是在浏览器端进行图片剪裁,得到一个base64的图片, 考虑到这个问题,增加了base64文件上传。

  1. 首先,需要构建一个Base64File对象,
  2. 然后,就没有然后了,直接像使用普通文件一样使用Base64File对象。

下面是一个示例:

import {Base64File, api} from 'next-api'
//太长,所以后面的省略了
let str = "data:image/jpeg;base64,/9j/4AAQSkZJRgAB..."
 
//先定义一个API
let uploadAvatar = api.post('/user/avatar')
 
//架设点击某个按钮调用这个函数进行设置头像
async handleSetAvatar(base64str){
    //创建文件,第一个参数是base64字符串,第二个参数是文件名称,两个参数都是必须的
    let file = new Base64File(base64str, 'avatar.png')
    //提交头像
    await uploadAvatar({avatar:file})
}
 

typescript中的API定义

相信很多人在使用typescript的时候都会感受到它的牛逼之处,所以我就不再多说了。

这里使用了typescript的泛型来定义API的参数和返回值, 可以在目前的绝大多数代码编辑器中实现代码提示。

接收两个类型,第一个是参数类型,第二个是返回值类型。

使用typescript可以这样定义API:

import {api} from 'next-api'
 
//定义用户登录API,
export userLogin = api.get<{
    number:string, //账号参数
    passwd:string //密码参数
    tokenOnly?:boolean, //是否只获取token,可选参数
}, {
    token:string, //获取到的token
    userInfo?:{ //用户信息,可能会没有
        id:number, //用户id
        number:string, //用户账号
        name:string, //用户姓名
        //其他的就不写了
    }
}>('/user/token')
 

这样定义之后,就能有很好的代码提示以及参数校验效果了。

文件上传进度使用说明

文件上传使用的是传统的XMLHttpRequest来实现的,以便于获取上传进度。

用法和之前的API基本一致,仅有一下几点不同

  1. config中的fetchOption无效,取而代之的是xhrOption,具体细节可以参考 index.d.ts中的定义
  2. 调用上传API时增加了两个参数,用于标识上传的文件以及进度的获取

简单用法:

import {upload} from 'next-api'
 
//创建API
let setAvatar = upload.post('/user/avatar')
 
//调用API
async function handleSetAvatar(user, inputDom){
    //调用API设置头像,第2、3个参数可以不用传递
    let result = await setAvatar({file:inputDom.files[0], user:user.id}, {
        //这里可以是任意数据,这里设置的数据可以在上传列表中得到
        //如果不设置数据,则上传列表中没有数据
        fileName:inputDom.files[0].name
    }, (loaded, total)=>{
        //这里可以取得上传进度
        console.log(`已上传${loaded}/${total}`)
    })
    //如果不适用第2、3个参数,则和之前的API没什么区别了
    // let result = await setAvatar({file:inputDom.files[0], user:user.id})
    console.log(result)
}
 

除此之外,文件上传API提供了一个上传列表,如果有需要,你可以方便地使用它。

简单用法如下:

import {upload} from 'next-api'
 
//假设这个dom用于展示上传列表
let fileUploadListDom = document.getElementById('file-upload-list')
//设置一个定时器,定期检测文件进度,并展示到界面上
setInterval(()=>{
    let html = '<ul class="FileList">'
    upload.list.forEach(item=>{
        //这里的item.data就是上一个例子中API调用时设置的第二个参数的数据
        html += `<li class="FileItem">
            <div class="FileName">${ item.data.fileName }</div>
            <div class="Persent">${ item.total ? parseInt ( item.loaded * 100 / item.total ) : 0 }%</div>
        </li>`
    })
    html += '</ul>'
    fileUploadListDom.innerHTML = html
}, 100)

Install

npm i next-api

DownloadsWeekly Downloads

4

Version

2.0.4

License

ISC

Last publish

Collaborators

  • avatar