From c3f369f0b33f1f1c7fc9f199536d2959f94c0273 Mon Sep 17 00:00:00 2001 From: zuiidea Date: Mon, 12 Nov 2018 23:30:56 +0800 Subject: [PATCH] :memo: Add documentation for API configuration. --- docs/API-configuration.md | 86 +++++++++++++++++++++++++++++++++ docs/_sidebar.md | 1 + docs/configuration.md | 2 +- docs/zh-cn/API-configuration.md | 86 +++++++++++++++++++++++++++++++++ docs/zh-cn/_sidebar.md | 1 + docs/zh-cn/configuration.md | 2 +- src/services/api.js | 4 +- 7 files changed, 177 insertions(+), 5 deletions(-) create mode 100644 docs/API-configuration.md create mode 100644 docs/zh-cn/API-configuration.md diff --git a/docs/API-configuration.md b/docs/API-configuration.md new file mode 100644 index 0000000..82e6e32 --- /dev/null +++ b/docs/API-configuration.md @@ -0,0 +1,86 @@ +# API configuration + +## Why + +In the use of `redux` or `dva` projects, we often write functions like the following `service` layer to make the code structure clearer, but it is easy to see that we will write a lot of similar code in `antd -admin@5.0`, using the more concise configuration method to achieve the same function. + +```javascript +Export async function login(data) { +  Return request({ +    Url: '/api/v1/user/login', +    Method: 'post', +    Data, +  }) +} +``` + +## Configuration and use + +In the `src/services/api.js` file, you will see the following configuration object, the object's key is used to call the function name, the object's value is the requested `url`, the default request method is `GET`, The format of the value of the other request mode object is `'method url'`. + +```javascript +Export default { +  ... +  queryUser: '/user/:id', +  queryUserList: '/users', +  updateUser: 'Patch /user/:id', +  createUser: 'POST /user/:id', +  removeUser: 'DELETE /user/:id', +  removeUserList: 'POST /users/delete', +  ... +} +``` + +Used in other files + +```javascript +Import { queryUser } from 'api' + +// in the general file +... +queryUser(option).then(data => console.log(data)) +... + +/ / Model file +... +Yield call(queryUser, option) +... +``` + +## Method to realize + +Refer to the `src/services/index.js` file to traverse the api configuration. Each property returns the corresponding encapsulated request function. + +```javascript +Import request from 'utils/request' +Import { apiPrefix } from 'utils/config' + +Import api from './api' + +Const gen = params => { +  Let url = apiPrefix + params +  Let method = 'GET' + +  Const paramsArray = params.split(' ') +  If (paramsArray.length === 2) { +    Method = paramsArray[0] +    Url = apiPrefix + paramsArray[1] +  } + +  Return function(data) { +    Return request({ +      Url, +      Data, +      Method, +    }) +  } +} + +Const APIFunction = {} +For (const key in api) { +  APIFunction[key] = gen(api[key]) +} + +Module.exports = APIFunction + +``` \ No newline at end of file diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 5a05267..5f4cfb8 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -2,6 +2,7 @@ - [Quick Start](getting-started.md) - Customization - [Configuration](configuration.md) + - [API Configuration](API-configuration.md) - Guide - [Deploy](deploy.md) - [Change Log](change-log.md) diff --git a/docs/configuration.md b/docs/configuration.md index 5aa10cf..2d58b14 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -24,7 +24,7 @@ You can do some custom configuration in `/src/utils/config.js`: - Type： `String` - Configure the prefix of the interface in the project. The interface related documents can be viewed [API configuration]() + Configure the prefix of the interface in the project. The interface related documents can be viewed [API configuration](API-configuration.md) ## fixedHeader diff --git a/docs/zh-cn/API-configuration.md b/docs/zh-cn/API-configuration.md new file mode 100644 index 0000000..19913ac --- /dev/null +++ b/docs/zh-cn/API-configuration.md @@ -0,0 +1,86 @@ +# 接口配置 + +## 为什么 + +在使用了`redux`或者`dva`项目中，我们经常会写类似下面的`service`层的函数，使代码结构更清晰，但是很容易看出，我们会写很多相似的代码，在`antd-admin@5.0`中，使用了更加简洁的配置方式实现了相同的功能。 + +```javascript +export async function login(data) { + return request({ + url: '/api/v1/user/login', + method: 'post', + data, + }) +} +``` + +## 配置和使用 + +在`src/services/api.js`文件中，你会看到如下配置对象，对象的键用于调用时的函数名称，对象的值为请求的`url`，默认请求方式为`GET`，如果是其他请求方式对象的值的格式则为`'method url'`。 + +```javascript +export default { + ... + queryUser: '/user/:id', + queryUserList: '/users', + updateUser: 'Patch /user/:id', + createUser: 'POST /user/:id', + removeUser: 'DELETE /user/:id', + removeUserList: 'POST /users/delete', + ... +} +``` + +在其他文件中使用 + +```javascript +import { queryUser } from 'api' + +// 一般文件中 +... +queryUser(option).then(data => console.log(data)) +... + +// model文件中 +... +yield call(queryUser, option) +... +``` + +## 实现方式 + +参考`src/services/index.js`文件，对api配置进行遍历，每个属性都返回对应的封装后的request函数。 + +```javascript +import request from 'utils/request' +import { apiPrefix } from 'utils/config' + +import api from './api' + +const gen = params => { + let url = apiPrefix + params + let method = 'GET' + + const paramsArray = params.split(' ') + if (paramsArray.length === 2) { + method = paramsArray[0] + url = apiPrefix + paramsArray[1] + } + + return function(data) { + return request({ + url, + data, + method, + }) + } +} + +const APIFunction = {} +for (const key in api) { + APIFunction[key] = gen(api[key]) +} + +module.exports = APIFunction + +``` \ No newline at end of file diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md index f38aecb..3b2672a 100644 --- a/docs/zh-cn/_sidebar.md +++ b/docs/zh-cn/_sidebar.md @@ -2,6 +2,7 @@ - [快速上手](zh-cn/getting-started.md) - 定制化 - [配置项](zh-cn/configuration.md) + - [接口配置](zh-cn/API-configuration.md) - 指南 - [部署](zh-cn/deploy.md) - [更新日志](zh-cn/change-log.md) diff --git a/docs/zh-cn/configuration.md b/docs/zh-cn/configuration.md index 69450fa..771acca 100644 --- a/docs/zh-cn/configuration.md +++ b/docs/zh-cn/configuration.md @@ -24,7 +24,7 @@ - 类型： `String` - 配置项目中接口的前缀，接口相关文档可查看 [接口配置化]() + 配置项目中接口的前缀，接口相关文档可查看 [接口配置](API-configuration.md) ## fixedHeader diff --git a/src/services/api.js b/src/services/api.js index 14c9d41..f745bd2 100644 --- a/src/services/api.js +++ b/src/services/api.js @@ -1,4 +1,4 @@ -const api = { +export default { queryRouteList: '/routes', queryUserInfo: '/user', @@ -16,5 +16,3 @@ const api = { queryDashboard: '/dashboard', } - -export default api