From dbecb6049b816d9330876e389ffb56d11812887e Mon Sep 17 00:00:00 2001
From: "luk.lu" <luk.lu@faronear.org>
Date: Thu, 8 Jul 2021 13:33:09 +0800
Subject: [PATCH] rename apiHow to apiTodo

---
 index.js | 48 +++++++++++++++++++++++++++++-------------------
 1 file changed, 29 insertions(+), 19 deletions(-)

diff --git a/index.js b/index.js
index bfefa55..6d45e64 100644
--- a/index.js
+++ b/index.js
@@ -11,6 +11,7 @@
 import './ican-H5Api.js' // 对齐H5Api: https://ext.dcloud.net.cn/plugin?id=415 // 注意要取消默认自带的 showToast https://uniapp.dcloud.io/api/system/clipboard?id=%e6%b3%a8%e6%84%8f
 
 module.exports = {
+  // 用直观的色彩，代替 uview 的命名方式：
   RED: 'error',
   GREEN: 'success',
   BLUE: 'primary',
@@ -19,8 +20,7 @@ module.exports = {
   BLACK_TOAST: 'default',
   WHITE_BUTTON: 'default',
 
-  BACKEND: 'SERVER',
-
+  // 快速输出详尽提示，可用来取代 console.log
   clog(...message) {
     console.log(
       '【【【【【【【【【【',
@@ -30,6 +30,7 @@ module.exports = {
     )
   },
 
+  // 再次封装 uni.request，输入参数和 uni.request 保持基本一致。主要为了插入 _passtoken，简化 url 的组装，以及输出提示。
   async request({ method = 'POST', url, header = {}, data = {} }) {
     url = this.makeUrl(url)
     header._passtoken = uni.getStorageSync('_passtoken')
@@ -45,52 +46,61 @@ module.exports = {
     console.log('⬇️ ⬇️ ⬇️ ⬇️ < Response > ⬇️ ⬇️ ⬇️ ⬇️ ', response, '⬆️ ⬆️ ⬆️ ⬆️ < /Response > ⬆️ ⬆️ ⬆️ ⬆️')
     return [error, response]
   },
-
-  async callBackend({ backend = this.BACKEND, method = 'POST', apiVersion = 'api', apiWho, apiHow, apiWhat = {} }) {
-    console.log('👇 < BackendRequest > ', { apiWho, apiHow, apiWhat }, ' < /BackendRequest > 👇')
+ 
+  BACKEND: 'SERVER', // 通过变量来动态切换后台类型：服务器 SERVER，或云服务 CLOUD
+  /** 统一 uni.request 和 uniCloud.callFunction 的调用方法，提供统一、透明的后台调用
+   * 返回值：{ _state, 成功结果或错误结果 }，其中 _state 除了后台返回的，还可以是
+   * - CLIENT_BACKEND_BROKEN: 前端发现后台断线
+   * - CLIENT_BACKEND_TIMEOUT: 前端发现后台超时
+   * - CLINET_BACKEND_EXCEPTION: 前端发现后台异常
+  **/
+  async callBackend({ backend = this.BACKEND, httpMethod = 'POST', apiVersion = 'api', apiWho, apiTodo, apiWhat = {} }) {
+    console.log('👇 < BackendRequest > ', { apiWho, apiTodo, apiWhat }, ' < /BackendRequest > 👇')
     let result = {}
     if (backend === 'CLOUD') {
       let { /* success, header, requestedId, */ result: resultCloud = {} } = await uniCloud
         .callFunction({
           name: apiWho,
           data: {
-            apiHow,
+            apiTodo,
             apiWhat,
             _passtoken: uni.getStorageSync('_passtoken'),
-            // uniIdToken // uniCloud自动getStorageSync('uni_id_token')并传递为 uniIdToken；也可自行传入 uniIdToken
+            // uniIdToken // uniCloud自动getStorageSync('uni_id_token')并传递为 uniIdToken；也可自行组装传入 uniIdToken
           },
         })
-        .catch((exp) => {
-          // 断网或云端返回异常 {errMsg, stack} = error
-          if (/request:fail/.test(exp.errMsg)) {
+        .catch((error) => { // {errMsg, stack} = error
+          if (/request:fail/.test(error.errMsg)) { 
+            // 后台云服务无法连接
             return { result: { _state: 'CLIENT_BACKEND_BROKEN' } }
-          } else {
-            return { result: { _state: 'CLIENT_BACKEND_EXCEPTION' } }
+          } else {  
+            // 后台云服务返回异常
+            return { result: { _state: 'CLIENT_BACKEND_EXCEPTION', error } }
           }
         })
       result = resultCloud
     } else {
-      if (method === 'GET') {
+      if (httpMethod === 'GET') {
         // 如果不是 POST 方法,要额外把参数JSON化
         for (let key in apiWhat) {
           apiWhat[key] = JSON.stringify(apiWhat[key])
         }
       }
-      let [error, { data: resultServer = {}, statusCode, header, errMsg } = {}] = await uni.request({
-        method,
-        url: this.makeUrl(`${apiVersion}/${apiWho}/${apiHow}`),
+      let [error, { statusCode, header, errMsg, data: resultServer = {} } = {}] = await uni.request({
+        method: httpMethod,
+        url: this.makeUrl(`${apiVersion}/${apiWho}/${apiTodo}`),
         header: { _passtoken: uni.getStorageSync('_passtoken') },
         data: apiWhat,
       })
       if (error) {
         if (error.errMsg === 'request:fail') {
-          // 后台断线
+          // 后台服务器无法连接
           result = { _state: 'CLIENT_BACKEND_BROKEN' }
         } else if (error.errMsg === 'request:fail timeout') {
-          // 后台异常而超时返回
+          // 后台服务器超时
           result = { _state: 'CLIENT_BACKEND_TIMEOUT' }
         } else {
-          result = { _state: 'CLIENT_BACKEND_EXCEPTION' }
+          // 后台服务器返回异常
+          result = { _state: 'CLIENT_BACKEND_EXCEPTION', error }
         }
       } else {
         result = resultServer