Update uni-clientDB.md

docs/uniCloud/uni-clientDB.md

@@ -6,7 +6,7 @@ clientDB框架的目标：减少服务端代码开发。
 
 如今的应用，不管是App、小程序、H5，均是前后端分离。
 
-前端是轻不下去了，但后端是可以越来越轻的。
+前端是轻不下去了，但后端有机会越来越轻。
 
 serveless减少了服务器的运维工作量，能不能再进一步，减少服务器的开发工作量？
 
@@ -18,7 +18,7 @@ serveless减少了服务器的运维工作量，能不能再进一步，减少
 3. 操作数据库
 4. 对数据加工变成json返回给前端
 
-后端工程师不停的做上述代码的逻辑，不停的为前端提供各种接口。前后端要不停的联调，甚至引入postman这种多余的工具。
+后端工程师不停的写上述代码，不停的为前端提供各种接口。前后端要不停的联调，甚至引入postman这种多余的工具。
 
 clientDB的目标，就是让上述无聊的服务端代码开发，从此消失！
 
@@ -28,27 +28,27 @@ clientDB的目标，就是让上述无聊的服务端代码开发，从此消失
 - 然后，在云端通过json配置权限和校验规则，不写代码，但保证数据库操作的安全。
 - 同时，如果遇到需要写云端代码的时候，也可以通过action机制编写云函数代码进行处理。
 
-使用clientDB也将大大减少云函数的数量，避免超过云函数的数量上限。
-
-> 举例：在前端的list.vue列表页面，可以调用本框架，传入列表查询条件。然后写content.vue详情页面时，无需再新建一个云函数，可以直接在content.vue页面继续调用相同的本云函数，传入详情的查询条件。
+> 举例：在前端的list.vue列表页面，可以引入clientDB的前端jssdk，编写数据查询。然后写content.vue详情页面时，无需再新建一个云函数，可以直接在content.vue页面继续写详情的查询。
 
 客户端的查询条件语法，与云函数里查询数据库的语法是相同的。[查询api手册](https://uniapp.dcloud.io/uniCloud/cf-database?id=%e6%9f%a5%e8%af%a2%e6%96%87%e6%a1%a3)
 
 与某些小程序云的客户端直接操作数据库不同，本方案有2个明显优势：
-- 安全：查询权限是在云端控制的，能查什么表、什么字段，在云端控制。如果全部放在前端，由于前端的不可信任，相当于无法控制权限了。而某些小程序云提供的客户端权限，并不可编程，无法满足开发者的实际业务权限需求
-- 包体积：某些小程序云的客户端操作数据库是一个数M大小的js sdk，如果迁移到H5和App，对应用的启动速度、性能、体积影响非常大。但clientDB的客户端jssdk只有几k，
+- 安全：查询权限是在云端控制的，能查什么表、什么字段，在云端控制。如果全部放在前端，由于前端的不可信任，相当于无法控制权限了。
+- 灵活：基于uni-id而不是绑定小程序用户，权限除了可配置，也支持js编程。而某些小程序云提供的客户端权限，依赖小程序账户，并且不可编程，无法满足开发者的实际业务中灵活的权限需求。
+- 跨端：uniCloud的clientDB是全端均可使用的。
+- 包体积：某些小程序云的客户端操作数据库是一个数M大小的js sdk，如果迁移到H5和App，对应用的启动速度、性能、体积、网站流量的影响非常大。但clientDB的客户端jssdk只有几k，
 
 综上，本插件的优势在于：
 1. 大幅减少服务端开发工作量
 2. 减少云函数数量
-3. 安全，可控制权限
+3. 安全，可完整、灵活的控制权限
 4. 更轻的客户端体积
 
 本项目包括云函数和客户端两部分，需要搭配使用，具体请参考下面文档。
 
 插件地址：[https://ext.dcloud.net.cn/plugin?id=2314](https://ext.dcloud.net.cn/plugin?id=2314)
 
-**示例项目使用须知**
+**插件示例项目使用须知**
 
 1. 下载示例项目后选择服务空间
 2. 在db_init.json上右键初始化数据库
@@ -69,7 +69,7 @@ uni-clientDB项目目录结构如下
 |  |   |  └─action-name.js    action逻辑
 |  |   ├─db-permission        数据库权限规则
 |  |   |  └─table-name.js     表名作为文件名设置不同表的权限规则
-|  |   ├─validator            数据校验规则
+|  |   ├─validator            数据格式校验规则
 |  |   |  └─table-name.js     表名作为文件名设置不同表的数据校验规则
 |  |   ├─index.js             clientDB云函数入口
 |  |   └─package.json         clientDB云函数package.json
@@ -84,12 +84,23 @@ uni-clientDB项目目录结构如下
 	</code>
 </pre>
 
-## 客户端js-sdk@jssdk
 
-客户端js-sdk主要负责组装查询逻辑，以及处理一些客户端不太方便表示的字段，比如用户ID（详情看下面语法扩展部分）
+## clientDB框架图解
+
+![](https://static-eefb4127-9f58-4963-a29b-42856d4205ee.bspapp.com/clientdb.jpg)
+
+上图中紫色部分为clientDB框架，它分为前端部分和云端部分。
+
+下面将详细展开描述。
+
+## 前端部分@jssdk
+
+clientDB的前端js-sdk主要负责提供API，允许前端编写数据库操作指令，以及处理一些客户端不太方便表示的字段，比如用户ID（详情看下面语法扩展部分）
 
 **示例代码**
 
+这段示例代码，在一个前端页面，直接查询了云数据库的list表，并且指定了name和time的where条件，then的res即为返回的查询结果。
+
 ```js
 // 引入公共模块
 import db from '@/js_sdk/uni-clientDB/index.js'
@@ -121,36 +132,36 @@ db.action('get-info') // 不使用action时可以不调用action方法
 - 更新数据库时不可使用更新操作符`db.command.inc`等
 - 更新数据时键值不可使用`{'a.b.c': 1}`的形式（后续会对此进行优化）
 
-### 语法扩展
+### 前端sdk语法扩展
 
 clientDB目前内置了3个变量可以供客户端使用，客户端并非直接获得这三个变量的值，而是需要传递给clientDB云函数，云函数解析之后给赋予真正的值。
 
 |参数名					|说明					|
 |:-:						|:-:					|
-|db.env.uid			|用户uid			|
+|db.env.uid			|用户uid，依赖uni-id			|
 |db.env.now			|服务器时间戳	|
 |db.env.clientIP|当前客户端IP	|
 
 使用这些变量，将可以避免过去在服务端代码中写代码获取用户uid、时间和客户端ip的麻烦。
 
-## 云函数clientDB
+## 云端部分
 
-云函数uni-clientDB主要负责解析客户端数据库操作逻辑，对客户端行为做权限以及数据格式上的限制。除了`uni-curd`之外还有以下三部分:
+clientDB的云端部分较多，包含一个公共模块uni-curd，还有一个很大的云函数uni-clientDB。
 
-1. db-permission目录用于存放权限规则。db-permission下每个文件对应一个表的权限，文件名为对应的表名。
+云函数uni-clientDB主要负责接收客户端的请求，根据db-permission里的配置做权限校验、根据validator里的配置对即将写库的数据做格式合法性校验、执行前端执行的某个action、执行具体的数据库操作。
+
+它有若干子目录，解释如下：
+
+1. db-permission目录用于存放权限规则。db-permission下每个文件对应一个表的权限，文件名为对应的表名。所谓数据权限，即什么样的用户身份，可以访问、操作哪些表、哪些字段。
 2. validator目录用于存放字段数据校验规则。和db-permission一样，validator目录下每个文件的文件名对应一个表名。
-3. action目录下的预处理后处理逻辑。action下每个目录对应一个操作，前端页面在callFunction时传入action参数指明当前操作需要使用哪个action（可以在权限规则内指定某些操作必须使用指定的action，比如`"action in ['action-a','action-b']"`）
+3. action目录下存放各种action，action的作用是额外触发一段云函数逻辑。支持在操作数据库前触发action.before，也称为预处理，支持在操作数据库后触发action.afer，也称为后处理。action下每个目录对应一个action操作，前端页面在执行数据库操作时，可使用.action方法传入action参数，这样就会执行action目录下的云函数。还可以在权限规则内指定某些操作必须使用指定的action，比如`"action in ['action-a','action-b']"`，来达到更灵活的权限控制。
 
 **注意**
 
-- clientDB依赖uni-id提供用户身份，如果你不了解uni-id，请参考[uni-id文档](https://uniapp.dcloud.net.cn/uniCloud/uni-id)
+- clientDB依赖uni-id提供用户身份和权限校验，如果你不了解uni-id，请参考[uni-id文档](https://uniapp.dcloud.net.cn/uniCloud/uni-id)
 - 通常在管理控制台使用clientDB，需要获取不同角色用户拥有的权限（在权限规则内使用auth.permission），请先查阅[uni-id 角色权限](https://uniapp.dcloud.net.cn/uniCloud/uni-id?id=rbac)
 
-**云函数内部执行顺序**
-
-![](https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/b7d96a10-ff35-11ea-8ff1-d5dcf8779628.jpg)
-
-云函数默认返回值形式如下，开发者可以在action的after内修改返回结果，传入after内的result不带code和message。
+clientDB云端默认返回值形式如下，开发者可以在action的after内用js修改返回结果，传入after内的result不带code和message。
 
 ```js
 {
@@ -170,10 +181,10 @@ clientDB目前内置了3个变量可以供客户端使用，客户端并非直
 |TOKEN_INVALID_WRONG_TOKEN			|token校验未通过（token校验未通过）			|
 |SYNTAX_ERROR										|db-permission语法错误									|
 |PERMISSION_ERROR								|权限校验未通过													|
-|VALIDATION_ERROR								|数据校验未通过													|
+|VALIDATION_ERROR								|数据格式未通过													|
 |SYSTEM_ERROR										|系统错误																|
 
-**我们推荐试用web控制台的数据库表结构来统一管理permission和validator，uniCloud web控制台可以通过表结构一键生成前端页面和clientDB权限及验证规则，后续HBuilderX也会内置此功能**
+<!--我们推荐试用web控制台的数据库表结构来统一管理permission和validator，uniCloud web控制台可以通过表结构一键生成前端页面和clientDB权限及验证规则，后续HBuilderX也会内置此功能-->
 
 为了更好的控制客户端行文，客户端在db-permission不为公有读（并非true时）时写法有以下限制：
 
@@ -187,9 +198,16 @@ clientDB目前内置了3个变量可以供客户端使用，客户端并非直
 
 ### db-permission
 
-db-permission内为数据表权限，以表名作为文件名，clientDB会自动读取要访问的表的权限。
+db-permission目录内存放数据表权限的配置文件，以表名作为文件名，clientDB会自动读取要访问的表的权限。
 
-使用db-permission之前需要先了解以下db-permission的原理。db-permission会对客户端上传的数据库指令进行校验，即客户端的查询条件应该满足db-permission内规定的条件。比如db-permission内规定doc.a > 1,那么查询条件里面就必须有a且条件内的a也满足a>1，`{a:2}`、`{a:db.command.gt(3)}`都是满足条件的查询。
+实际运行时，
+1. db-permission模块会解析前端传递的参数，分析前端操作人员的uni-id身份、要操作的数据表、字段和增删改查动作。
+2. 然后从云端配置，也即db-permission目录下的配置，读取数据表、字段、增删改查动作的权限配置
+3. 最后根据用户身份和权限配置进行比对，以决定是否有权进行前端发起的这次数据库操作
+
+db-permission规则，可以对整个表的增删改查进行控制，也可以针对字段进行控制；可以简单的配置true/false，也可以配置
+
+比如db-permission内规定doc.a > 1,那么查询条件里面就必须有a且条件内的a也满足a>1，`{a:2}`、`{a:db.command.gt(3)}`都是满足条件的查询。
 
 **db-permission配置示例**
 
@@ -198,28 +216,30 @@ db-permission内为数据表权限，以表名作为文件名，clientDB会自
 module.exports = {
   // 关于权限中用到的auth对象及doc对象请看下方说明
   // 新增数据时的权限
-  '.create': false,
+  '.create': false, // 禁止新增数据记录
   // 读取数据时的权限
-  '.read': 'doc.uid == auth.uid',
+  '.read': 'doc.uid == auth.uid', // 每个用户只能读取用户自己的数据。前提是要操作的数据doc，里面有一个字段存放了uid，即uni-id的用户id。
   // 更新数据时的权限
-  '.update': false,
+  '.update': false, // 禁止更新数据
   // 删除数据时的权限
-  '.delete': false,
+  '.delete': false, // 禁止删除数据
   // secret_field字段的权限，需要注意的是字段只有读写权限
   // 访问一个子节点时会使用所有上级权限，所有上级权限及字段本身权限都满足时才可以操作
-  'secret_field': {
+  'secret_field': { // 这是一个字段，叫secret_field
     // secret_field字段的读权限
-    '.read': false,
+    '.read': false, // 禁止读取secret_field字段的数据
     // secret_field字段的写权限
-    '.write': false
+    '.write': false // 禁止写入secret_field字段的数据
   }
 }
+```
 
+```js
 // db-permission/book.js
 module.exports = {
   // 未配置的权限默认为false
   // 读取数据时的权限
-  '.read': 'doc.status == "OnSell"'
+  '.read': 'doc.status == "OnSell"' // 所有人均可读取字段status="ObSell"的数据
 }
 ```
 
@@ -277,6 +297,10 @@ db.collection('order')
 |now						|当前时间戳（单位：毫秒），时间戳可以进行额外运算，如doc.publish\_date > now - 60000表示publish\_date在最近一分钟																						|
 |action					|当前客户端指定的action																																																																			|
 
+db-permission为对数据的操作权限，如果要封装业务权限，可以在uni-id的业务权限表里进行配置。业务权限进一步可组装为角色。然后每个具体的uni-id用户可以被赋予某个角色。
+
+如果在uni-id里定义了业务权限和角色，也可以在db-permission中通过auth.permission和auth.role来使用，以实现更灵活的配置定义。
+
 **权限规则内可以使用的运算符**
 
 |运算符	|说明						|示例																|示例解释(集合查询)																	|
@@ -322,12 +346,93 @@ db.collection('street').where(dbCmd.or([
 ])).get()
 ```
 
+
+db-permission的配置文件是js，虽然主要配置方式为json，但可以编程，实现批处理等操作。
+
+### validator
+
+validator用于写库时，对准备写入的数据进行合法性校验，以及在新增数据记录时指定默认值。
+
+validator与db-permission不同，validator只校验字段合法性，比如某个字段保存手机号，则必须符合手机号的正则才能写入这个数据。
+
+如果数据库操作是查询和删除，则不会执行validator校验。只有新增记录和修改记录等涉及字段内容变化的操作才涉及validator。
+
+validator目录下，同样是一个表名一个js文件，以处理该表的字段写入合法性校验。
+
+一个典型的validator文件形式如下
+
+```js
+// validator/article.js
+module.exports = {
+  "title": {
+    label: '标题', // 可选
+    rules: [{
+      // 校验title字段为string类型，更多校验规则详见 https://uniapp.dcloud.net.cn/uniCloud/schema
+      format: 'string'
+    }]
+  },
+  "user_id": {
+    // 新增数据时将user_id指定为当前用户Id，客户端不可修改
+		forceDefaultValue: {
+			$env: 'uid'
+		}
+	},
+  "is_public": {
+    // 新增数据时默认is_public指定为true，客户端可以修改
+		defaultValue: true
+	}
+}
+```
+
+defaultValue和forceDefaultValue均为字段默认值，区别在于defaultValue会被客户端传值覆盖，而forceDefaultValue不允许被客户端覆盖（如果客户端传递了与forceDefaultValue不一样的值会无法通过校验）
+
+defaultValue/forceDefaultValue内除了直接指定值之外，还可以通过`{$env: "变量名"}`的形式指定默认值为一些特殊变量，目前有以下可选变量名
+
+如果配置了forceDefaultValue，那么实际开发时可以少写很多代码。
+
+```js
+// 指定默认值为当前时间戳
+forceDefaultValue: {
+  $env: 'now'
+}
+
+// 指定默认值为当前用户ID
+forceDefaultValue: {
+  $env: 'uid'
+}
+
+// 指定默认值为当前客户端IP地址
+forceDefaultValue: {
+  $env: 'clientIP'
+}
+```
+
+
+**不推荐自己编写validator配置！在uniCloud的web控制台的数据库管理界面，可以对每个表进行表结构配置，即db schema，编写schema后，可直接导出validator配置规则，详见：[https://uniapp.dcloud.net.cn/uniCloud/schema](https://uniapp.dcloud.net.cn/uniCloud/schema)**
+
 ### action
 
-action主要用于进行数据操作前后处理数据
+action主要用于在云端数据库操作前后的编程处理。
+
+它是一个可选模块。当一个前端操作数据库的方式不能完全满足需求，仍然同时需要在云端再执行一些云函数时，就在前端发起数据库操作时，通过db.action("someactionname")方式要求云端同时执行这个叫someactionname的action。
+
+每个action在action目录下存放一个以action名称命名的js文件。
+
+在这个js文件中，包括before和after两部分。
+
+- before部分的常用用途：
+	* 对前端传的数据进行二次处理
+	* 在此处开启数据库事务，万一操作数据库失败，可以在after里回滚
+	
+- after部分的常用用途：
+	* 对将要回传给前端的数据进行二次处理
+	* 也可以在此处处理错误，回滚数据库事务
+	* 对数据库进行二次操作，比如前端查询一篇文章详情后，在此处对文章的阅读数+1。因为db-permission里定义，一般是要禁止前端操作文章的阅读数字段的，此时就应该通过action，在云函数里对阅读数+1
+
+示例：
 
 ```js
-// 客户端指定action为add-todo
+// 客户端发起请求，给todo表新增一行数据，同时指定action为add-todo
 import db from '@/js_sdk/uni-clientDB/index.js'
 db.action('add-todo')
   .collection('todo')
@@ -339,8 +444,10 @@ db.action('add-todo')
   }).catch(err => {
     console.error(err)
   })
+```
 
-// 一个云函数内action文件示例 action/add-todo.js
+```js
+// 一个action文件示例 action/add-todo.js
 module.exports = {
   // 在数据库操作之前执行
   before: async(state,event)=>{
@@ -351,7 +458,7 @@ module.exports = {
     state.newData.create_time = Date.now()
     // 指定插入或修改的数据内的create_time为Date.now()
     // 执行了此操作之后实际插入的数据会变成 {title: 'todo title', create_time: xxxx}
-    // 如果是执行插入操作时指定当前时间为创建时间的场景，有更简单的实现方案：在validator内配置defaultValue或者forceDefaultValue
+    // 实际上，这个场景，有更简单的实现方案：在db schema、validator内配置defaultValue或者forceDefaultValue，即可自动处理新增记录使用当前服务器时间
   },
   // 在数据库操作之后执行
   after:async (state,event,error,result)=>{
@@ -402,6 +509,34 @@ module.exports = {
 }
 ```
 
+
+
+<!-- ## 参考
+
+在线通讯录项目，完整的演示了如何基于clientDB在客户端代码里实现数据的增删改查，是学习clientDB的重要示例项目。该项目插件地址：[https://ext.dcloud.net.cn/plugin?id=2574](https://ext.dcloud.net.cn/plugin?id=2574) -->
+// getMethod({name:'where',index: 0}) 获取第1个where方法的参数，结果为数组形式，例：[{a:1}]
+    getParam,
+    // setParam({name:'where',index: 0, param: [{a:1}]}) 设置第1个where方法的参数，调用之后where方法实际形式为：where({a:1})
+    setParam
+  },
+  // 需要注意的是clientDB可能尚未获取用户信息，如果权限规则内没使用auth对象且数据库指令里面没使用db.env.uid则clientDB不会自动取获取用户信息
+  auth: {
+    uid, // 用户ID，如果未获取或者获取失败uid值为null
+    role, // 通过uni-id获取的用户角色，需要使用1.1.9以上版本的uni-id，如果未获取或者获取失败role值为[]
+    permission, // 通过uni-id获取的用户权限，需要使用1.1.9以上版本的uni-id，如果未获取或者获取失败permission值为[]，注意登录时传入needPermission才可以获取permission，请参考 https://uniapp.dcloud.net.cn/uniCloud/uni-id?id=rbac
+    checked // 是否已经获取了用户信息
+  },
+  // 事务对象，如果需要用到事务可以在action的before内使用state.transaction = await db.startTransaction()传入
+  transaction,
+  // 更新或新增的数据
+  newData,
+  // 访问的集合
+  collection,
+  // 操作类型，可能的值'read'、'create'、'update'、'delete'
+  type
+}
+```
+
 ### validator
 
 validator主要是用于数据校验以及在新增数据时指定默认值，validator下的文件可以由web控制台数据库表结构生成。