feat: close #20 #21, upgrade deps and support runtimeOptions (#22)

* feat: close #20 #21, upgrade deps and support runtimeOptions
tuax · Feb 19, 2019 · 38c29bc · 38c29bc
1 parent c426bfd
commit 38c29bc
Show file tree

Hide file tree

Showing 31 changed files with 298 additions and 180 deletions.
diff --git a/README.md b/README.md
@@ -86,8 +86,14 @@ fooApi
 ```js
 // 甚至可以更进一步和 tua-storage 配合使用
 import TuaStorage from 'tua-storage'
+import { getSyncFnMapByApis } from 'tua-api'
 
-const storage = new TuaStorage({ ... })
+// 本地写好的各种接口配置
+import * as apis from '@/apis'
+
+const tuaStorage = new TuaStorage({
+    syncFnMap: getSyncFnMapByApis(apis),
+})
 
 const fetchParam = {
     key: fooApi.bar.key,
@@ -103,7 +109,7 @@ const fetchParam = {
     // ...
 }
 
-storage
+tuaStorage
     .load(fetchParam)
     .then(console.log)
     .catch(console.error)
@@ -155,7 +161,7 @@ export default {
 }
 ```
 
-[更多配置请点击这里查看](https://tuateam.github.io/tua-api/config/detail.html)
+[更多配置请点击这里查看](https://tuateam.github.io/tua-api/config/common.html)
 
 ### 配置导出
 最后来看一下 `apis/index.js` 该怎么写：
@@ -180,7 +186,8 @@ tuaApi
     // 链式调用
     .use(...)
 
-export const somethingApi = tuaApi.getApi(require('./something').default)
+export const fakeGet = tuaApi.getApi(require('./fake-get').default)
+export const fakePost = tuaApi.getApi(require('./fake-post').default)
 ```
 
 小程序端建议使用 [@tua-mp/cli](https://tuateam.github.io/tua-mp/tua-mp-cli/) 一键生成 api。
@@ -190,15 +197,16 @@ $ tuamp add api <api-name>
 ```
 
 ### 配置的构成
-在 `tua-api` 中配置分为三种：
+在 `tua-api` 中配置分为四种：
 
-* 默认配置（调用 `new TuaApi({ ... })` 时传递的）
-* 公共配置（和 `pathList` 同级的配置）
-* 自身配置（`pathList` 数组中的对象上的配置）
+* [默认配置（调用 `new TuaApi({ ... })` 时传递的）](https://tuateam.github.io/tua-api/config/default.html)
+* [公共配置（和 `pathList` 同级的配置）](https://tuateam.github.io/tua-api/config/common.html)
+* [自身配置（`pathList` 数组中的对象上的配置）](https://tuateam.github.io/tua-api/config/self.html)
+* [运行配置（在实际调用接口时传递的配置）](https://tuateam.github.io/tua-api/config/runtime.html)
 
 其中优先级自然是:
 
-`自身配置 > 公共配置 > 默认配置`
+`默认配置 < 公共配置 < 自身配置 < 运行配置`
 
 <p align="center">
     <a href="https://tuateam.github.io/tua-api/config/">👉更多配置点击这里👈</a>

diff --git a/babel.config.js b/babel.config.js
@@ -14,7 +14,7 @@ module.exports = {
                 ],
             ],
         },
-        prod: {
+        production: {
             presets: [
                 [
                     '@babel/preset-env',

diff --git a/commitlint.config.js b/commitlint.config.js
@@ -1,6 +1,6 @@
 module.exports = {
     // https://www.npmjs.com/package/@commitlint/config-conventional
     extends: ['@commitlint/config-conventional'],
-    "rules": {
+    rules: {
     },
 }
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -1,43 +1,45 @@
+const { name } = require('../../package.json')
+
+const description = '🏗 一款可配置的通用 api 请求函数生成工具'
+
 module.exports = {
-    base: '/tua-api/',
+    base: '/' + name + '/',
     locales: {
-        '/': {
-            title: 'tua-api',
-            description: '🏗 一款可配置的通用 api 请求函数生成工具'
-        }
+        '/': { title: name, description },
     },
     head: [
         ['link', { rel: 'icon', href: `/logo.png` }],
     ],
+    evergreen: true,
     serviceWorker: true,
     themeConfig: {
         repo: 'tuateam/tua-api',
         docsDir: 'docs',
         editLinks: true,
         lastUpdated: '上次更新',
+        sidebarDepth: 2,
         editLinkText: '在 GitHub 上编辑此页',
-        lastUpdated: '上次更新',
         nav: [
             {
-                text: '快速上手',
-                link: '/quick-start/',
+                text: '🌱指南',
+                link: '/guide/',
             },
             {
-                text: '配置',
+                text: '⚙️配置',
                 link: '/config/',
             },
             {
-                text: '生态系统',
+                text: '🔥生态系统',
                 items: [
-                    { text: '本地存储', link: 'https://tuateam.github.io/tua-storage/' },
-                    { text: '小程序框架', link: 'https://tuateam.github.io/tua-mp/' },
+                    { text: '📦本地存储', link: 'https://tuateam.github.io/tua-storage/' },
+                    { text: '🖖小程序框架', link: 'https://tuateam.github.io/tua-mp/' },
                 ],
             },
         ],
         sidebar: {
-            '/quick-start/': [
+            '/guide/': [
                 {
-                    title: '快速上手',
+                    title: '🌱指南',
                     collapsable: false,
                     children: [
                         'installation',
@@ -51,21 +53,22 @@ module.exports = {
             ],
             '/config/': [
                 {
-                    title: '配置',
+                    title: '⚙️配置',
                     collapsable: false,
                     children: [
                         '',
                         'default',
-                        'detail',
-                        'own',
+                        'common',
+                        'self',
+                        'runtime',
                     ],
                 },
             ],
         },
         serviceWorker: {
             updatePopup: {
-               message: 'New content is available.',
-               buttonText: 'Refresh',
+                message: 'New content is available.',
+                buttonText: 'Refresh',
             },
         },
     },

diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,7 @@
 ---
 home: true
 actionText: 快速上手 →
-actionLink: /quick-start/
+actionLink: /guide/
 features:
 - title: 支持多端
   details: 支持 web 端、Node 端和小程序端
@@ -16,17 +16,24 @@ features:
 footer: MIT Licensed | Copyright © 2018-present StEve Young
 ---
 
-<h4 align="center">
-    让我们优雅地调用 api~
-</h4>
+<h4 align="center">让我们优雅地调用 api~</h4>
 
 <p align="center">
-    <a href="https://github.com/feross/standard"><img :src="$withBase('/standard.svg')" alt="Standard - JavaScript Style"></a>
+    <a href="https://github.com/feross/standard" target="_blank">
+        <img :src="$withBase('/standard.svg')" alt="Standard - JavaScript Style">
+    </a>
 </p>
 
 <p align="center">
-    <a href="https://circleci.com/gh/tuateam/tua-api/tree/master"><img src="https://img.shields.io/circleci/project/github/tuateam/tua-api/master.svg" alt="Build Status"></a>
-    <a href="https://codecov.io/github/tuateam/tua-api?branch=master"><img src="https://img.shields.io/codecov/c/github/tuateam/tua-api/master.svg" alt="Coverage Status"></a>
-    <a href="https://www.npmjs.com/package/tua-api"><img src="https://img.shields.io/npm/v/tua-api.svg" alt="Version"></a>
-    <a href="https://www.npmjs.com/package/tua-api"><img src="https://img.shields.io/npm/l/tua-api.svg" alt="License"></a>
+    <a href="https://circleci.com/gh/tuateam/tua-api/tree/master" target="_blank">
+        <img src="https://img.shields.io/circleci/project/github/tuateam/tua-api/master.svg" alt="Build Status">
+    </a>
+    <a href="https://codecov.io/github/tuateam/tua-api?branch=master" target="_blank">
+        <img src="https://img.shields.io/codecov/c/github/tuateam/tua-api/master.svg" alt="Coverage Status">
+    </a>
+    <a href="https://www.npmjs.com/package/tua-api" target="_blank">
+        <img src="https://badgen.net/npm/dm/tua-api" alt="Downloads per month">
+        <img src="https://img.shields.io/npm/v/tua-api.svg" alt="Version">
+        <img src="https://img.shields.io/npm/l/tua-api.svg" alt="License">
+    </a>
 </p>
diff --git a/docs/config/README.md b/docs/config/README.md
@@ -1,10 +1,11 @@
 # 配置说明
-在 `tua-api` 中配置分为三种：
+在 `tua-api` 中配置分为四种：
 
-* 默认配置（调用 `new TuaApi({ ... })` 时传递的）
-* 公共配置（和 `pathList` 同级的配置）
-* 自身配置（`pathList` 数组中的对象上的配置）
+* [默认配置（调用 `new TuaApi({ ... })` 时传递的）](./default.md)
+* [公共配置（和 `pathList` 同级的配置）](./common.md)
+* [自身配置（`pathList` 数组中的对象上的配置）](./self.md)
+* [运行配置（在实际调用接口时传递的配置）](./runtime.md)
 
 其中优先级自然是:
 
-`默认配置 < 公共配置 < 自身配置`
+`默认配置 < 公共配置 < 自身配置 < 运行配置`
diff --git a/docs/config/detail.md → docs/config/common.md b/docs/config/detail.md → docs/config/common.md
@@ -1,4 +1,4 @@
-# 详细配置
+# 公共配置
 详细地址指的是填写在 `src/apis/foobar.js` 中的一级配置。这部分的配置优先级比默认配置高，但低于各个接口的自身配置。
 
 ## type 请求类型
@@ -37,7 +37,7 @@ export default {
 }
 ```
 
-详情参阅 [快速上手 - mock 章节](../quick-start/mock.md)
+详情参阅 [mock 章节](../guide/mock.md)
 
 ## prefix 接口中间地址
 建议与文件同名，方便维护。
@@ -93,7 +93,7 @@ export default {
 }
 ```
 
-详情参阅：[中间件进阶](../quick-start/middleware.md)
+详情参阅：[中间件进阶](../guide/middleware.md)
 
 ## beforeFn 发起请求前钩子函数
 在请求发起前执行的函数（例如小程序可以通过返回 `header` 传递 `cookie`），因为是通过 `beforeFn().then(...)` 调用，所以注意要返回 Promise。

diff --git a/docs/config/runtime.md b/docs/config/runtime.md
@@ -0,0 +1,27 @@
+# 运行配置
+运行配置指的是在接口实际调用时通过第二个参数传递的配置。这部分的配置优先级最高。
+
+以下接口以导出为 `exampleApi` 为例。
+
+```js
+exampleApi.foo(
+    { ... }, // 第一个参数传接口参数
+    { ... }  // 第二个参数传接口配置
+)
+```
+
+## callbackName 回调函数名称
+在通过 jsonp 发起请求时，为了使用缓存一般需要添加 callbackName，但是注意重复请求时会报错。
+
+```js
+exampleApi.foo(
+    { ... },
+    { callbackName: `foo` }
+)
+```
+
+## 其他参数
+公共配置一节中的所有参数（除了 `pathList` 外），以及自身配置一节中的所有参数均有效，且优先级最高。
+
+* 详情参阅[公共配置](./common.md)
+* 详情参阅[自身配置](./self.md)
diff --git a/docs/config/own.md → docs/config/self.md b/docs/config/own.md → docs/config/self.md
@@ -1,5 +1,5 @@
 # 自身配置
-自身配置指的是填写在 `pathList` 中的配置。这部分的配置优先级最高。
+自身配置指的是填写在 `pathList` 中的配置。这部分的配置优先级比公共配置高，但低于各个接口的运行配置。
 
 以下接口以导出为 `exampleApi` 为例。
 
@@ -67,6 +67,6 @@ export default {
 有时某个接口正好不需要上一级中 `commonParams` 的参数。那么可以传递 `null` 覆盖上一级中的 `commonParams`。
 
 ## 其他参数
-上一节中的所有参数（除了 `pathList` 外）均有效，且优先级最高。
+上一节中的所有参数（除了 `pathList` 外）均有效。
 
-详情参阅上一节 [详细配置](./detail.md)
+详情参阅上一节 [公共配置](./common.md)
diff --git a/docs/quick-start/README.md → docs/guide/README.md b/docs/quick-start/README.md → docs/guide/README.md
@@ -53,7 +53,7 @@ const fetchParam = {
     // ...
 }
 
-storage
+tuaStorage
     .load(fetchParam)
     .then(console.log)
     .catch(console.error)
@@ -62,15 +62,15 @@ storage
 ## 怎么写 `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
+* `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`部分：
 
-* host: `https://example-base.com/`
-* prefix: `foo/bar/something`
+* host: `'https://example-base.com/'`
+* prefix: `'foo/bar/something'`
 * pathList: `[ 'create', 'modify', 'delete' ]`
 
 ### 文件结构
@@ -91,7 +91,7 @@ storage
 
 export default {
     // 请求的公用服务器地址
-    host: 'https://example-base.com//',
+    host: 'https://example-base.com/',
 
     // 请求的中间路径
     prefix: 'foo/bar/something',
@@ -105,7 +105,7 @@ export default {
 }
 ```
 
-[更多配置请点击这里查看](../config/detail.md)
+[更多配置请点击这里查看](../config/common.md)
 
 ### 配置导出
 最后来看一下 `apis/index.js` 该怎么写：
@@ -130,7 +130,8 @@ tuaApi
     // 链式调用
     .use(...)
 
-export const somethingApi = tuaApi.getApi(require('./something').default)
+export const fakeGet = tuaApi.getApi(require('./fake-get').default)
+export const fakePost = tuaApi.getApi(require('./fake-post').default)
 ```
 
 ::: tip

diff --git a/docs/quick-start/export-utils.md → docs/guide/export-utils.md b/docs/quick-start/export-utils.md → docs/guide/export-utils.md
diff --git a/docs/quick-start/installation.md → docs/guide/installation.md b/docs/quick-start/installation.md → docs/guide/installation.md
diff --git a/docs/quick-start/middleware.md → docs/guide/middleware.md b/docs/quick-start/middleware.md → docs/guide/middleware.md
diff --git a/docs/quick-start/mock.md → docs/guide/mock.md b/docs/quick-start/mock.md → docs/guide/mock.md
-Original file line number
+Diff line change
@@ Expand Up / @@ -14,7 +14,7 @@ module.exports = { @@
                     ],
                 ],
             },
-            prod: {
+            production: {
                 presets: [
                     [
                         '@babel/preset-env',
@@ Expand Down @@