Skip to content
/ tua-api Public

🏗 一款可配置的通用 api 请求函数生成工具(A common tool helps converting configs to api functions)

License

Notifications You must be signed in to change notification settings

tuax/tua-api

Repository files navigation

tua-api

让我们优雅地调用 api~

👉完整文档地址点这里👈

Build Status Coverage Status dependencies Downloads per month Version Next Version License

tua-api 是什么?

tua-api 是一个针对发起 api 请求提供辅助功能的库。采用 ES6+ 语法,并采用 jest 进行了完整的单元测试。

目前已适配:

  • web 端:axios, fetch-jsonp
  • Node 端:axios
  • 小程序端:wx.request
Edit tua-api github example

安装

web 端

安装本体

$ npm i -S tua-api
# OR
$ yarn add tua-api

然后直接导入即可

import TuaApi from 'tua-api'

配置武器

配置“武器”分为两种情况:

  • 已配置 CORS 跨域请求头,或是没有跨域需求时,无需任何操作(默认采用的就是 axios)。

  • 若是用不了 CORS,那么就需要设置 reqType: 'jsonp' 借助 jsonp 实现跨域

但是 jsonp 只支持使用 get 的方式请求,所以如果需要发送 post 或其他方式的请求,还是需要使用 axios(服务端还是需要配置 CORS)。

小程序端

安装本体即可

$ npm i -S tua-api
# OR
$ yarn add tua-api
import TuaApi from 'tua-api'

小程序还用不了 npm?@tua-mp/service 了解一下?

tua-api 能干什么?

tua-api 能实现统一管理 api 配置(例如一般放在 src/apis/ 下)。经过处理后,业务侧代码只需要这样写即可:

import { fooApi } from '@/apis/'

fooApi
    .bar({ a: '1', b: '2' }) // 发起请求,a、b 是请求参数
    .then(console.log)       // 收到响应
    .catch(console.error)    // 处理错误

不仅如此,还有一些其他功能:

  • 参数校验
  • 默认参数
  • 中间件(koa 风格)
  • ...
// 甚至可以更进一步和 tua-storage 配合使用
import TuaStorage from 'tua-storage'
import { getSyncFnMapByApis } from 'tua-api'

// 本地写好的各种接口配置
import * as apis from '@/apis'

const tuaStorage = new TuaStorage({
    syncFnMap: getSyncFnMapByApis(apis),
})

const fetchParam = {
    key: fooApi.bar.key,
    syncParams: { a: 'a', b: 'b' },

    // 过期时间,默认值为实例化时的值,以秒为单位
    expires: 10,

    // 是否直接调用同步函数更新数据,默认为 false
    // 适用于需要强制更新数据的场景,例如小程序中的下拉刷新
    isForceUpdate: true,

    // ...
}

tuaStorage
    .load(fetchParam)
    .then(console.log)
    .catch(console.error)

怎么写 api 配置?

拿以下 api 地址举例:

  • https://example-base.com/foo/bar/something/create
  • https://example-base.com/foo/bar/something/modify
  • https://example-base.com/foo/bar/something/delete

地址结构划分

以上地址,一般将其分为3部分:

  • baseUrl: 'https://example-base.com/foo/bar'
  • prefix: 'something'
  • pathList: [ 'create', 'modify', 'delete' ]

文件结构

api/ 一般是这样的文件结构:

.
└── apis
    ├── prefix-1.js
    ├── prefix-2.js
    ├── something.js // <-- 以上的 api 地址会放在这里,名字随意
    └── index.js

基础配置内容

// src/apis/something.js

export default {
    // 接口基础地址
    baseUrl: 'https://example-base.com/foo/bar',

    // 接口的中间路径
    prefix: 'something',

    // 接口地址数组
    pathList: [
        { path: 'create' },
        { path: 'modify' },
        { path: 'delete' },
    ],
}

更多配置请点击这里查看

配置导出

最后来看一下 apis/index.js 该怎么写:

import TuaApi from 'tua-api'

// 初始化
const tuaApi = new TuaApi({ ... })

// 使用中间件
tuaApi
    .use(async (ctx, next) => {
        // 请求发起前
        console.log('before: ', ctx)

        await next()

        // 响应返回后
        console.log('after: ', ctx)
    })
    // 链式调用
    .use(...)

export const fakeGet = tuaApi.getApi(require('./fake-get').default)
export const fakePost = tuaApi.getApi(require('./fake-post').default)

小程序端建议使用 @tua-mp/cli 一键生成 api。

$ tuamp add api <api-name>

配置的构成

tua-api 中配置分为四种:

其中优先级自然是:

默认配置 < 公共配置 < 自身配置 < 运行配置

👉更多配置点击这里👈

Contributors ✨

Thanks goes to these wonderful people (emoji key):

StEve Young
StEve Young

💻 📖 🚇
evinma
evinma

💻

This project follows the all-contributors specification. Contributions of any kind welcome!

About

🏗 一款可配置的通用 api 请求函数生成工具(A common tool helps converting configs to api functions)

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published