diff --git a/docs/uniCloud/clientdb.md b/docs/uniCloud/clientdb.md index b466d1fac00adab32100418bb293dea3e2aeff25..f9a74842913dde998697ad045d9a0fa8e4b59d46 100644 --- a/docs/uniCloud/clientdb.md +++ b/docs/uniCloud/clientdb.md @@ -16,7 +16,7 @@ JQL语法相关文档已移至：[JQL语法](uniCloud/jql.md) 在`DB Schema`中，配置数据操作的权限和字段值域校验规则，阻止前端不恰当的数据读写。详见：[DB Schema](https://uniapp.dcloud.net.cn/uniCloud/schema) -如果想在数据库操作之前或之后需要在云端执行额外的动作（比如获取文章详情之后阅读量+1），`clientDB`提供了action云函数机制。在HBuilderX项目的`cloudfunctions/uni-clientDB-actions`目录编写上传js，参考：[action](uniCloud/database?id=action) +如果想在数据库操作之前或之后需要在云端执行额外的动作（比如获取文章详情之后阅读量+1），`clientDB`提供了action云函数机制。在HBuilderX项目的`cloudfunctions/uni-clientDB-actions`目录编写上传js，参考：[action](uniCloud/jql?id=action) **注意** @@ -59,7 +59,6 @@ JQL语法相关文档已移至：[JQL语法](uniCloud/jql.md) js API可以执行所有数据库操作。``组件是js API的再封装，进一步简化查询等常用数据库操作的代码量。 - 在HBuilderX 3.0+，``组件已经内置，可以直接使用。文档另见：[``组件](/uniCloud/unicloud-db) -- 在HBuilderX 3.0以前的版本，使用该组件需要在插件市场单独引用`插件`，另见：[https://ext.dcloud.net.cn/plugin?id=3256](https://ext.dcloud.net.cn/plugin?id=3256) 以下文章重点介绍`clientDB`的js API。至于组件的用法，另见[文档](uniCloud/unicloud-db.md)。 @@ -116,6 +115,53 @@ db.collection('list') - 更新数据时键值不可使用`{'a.b.c': 1}`的形式，需要写成`{a:{b:{c:1}}}`形式 +## 客户端事件@event + +### 刷新token@refreshtoken + +透传uni-id自动刷新的token给客户端 + +> HBuilderX 3.2.11及以上版本，clientDB会自动将刷新的token及过期时间保存在storage内。 + +**用法** + +```js +const db = uniCloud.database() + +function refreshToken({ + token, + tokenExpired +}) { + uni.setStorageSync('uni_id_token', token) + uni.setStorageSync('uni_id_token_expired', tokenExpired) +} +// 绑定刷新token事件 +db.on('refreshToken', refreshToken) +// 解绑刷新token事件 +db.off('refreshToken', refreshToken) +``` + +### 错误处理@error + +全局clientDB错误事件，HBuilderX 3.0.0起支持。 + +**用法** + +```js +const db = uniCloud.database() + +function onDBError({ + code, // 错误码详见https://uniapp.dcloud.net.cn/uniCloud/clientdb?id=returnvalue + message +}) { + // 处理错误 +} +// 绑定clientDB错误事件 +db.on('error', onDBError) +// 解绑clientDB错误事件 +db.off('error', onDBError) +``` + ## JQL语法@jql clientDB使用JQL在客户端编写查询语句，关于JQL语法请参考：[JQL语法](uniCloud/jql.md) diff --git a/docs/uniCloud/uni-clientDB.md b/docs/uniCloud/uni-clientDB.md deleted file mode 100644 index f8ef011d375a0893d26ed60cfe93e1d2d23abd8f..0000000000000000000000000000000000000000 --- a/docs/uniCloud/uni-clientDB.md +++ /dev/null @@ -1,631 +0,0 @@ -**重要：** clientDB重大升级，在HBuilderX 2.9.5+中已经内置，不再需要单独下载插件。并且新版增加大量功能。本文已过期，推荐使用clientDB的开发者升级到HBuilderX 2.9.5+，并阅读新文档：[https://uniapp.dcloud.net.cn/uniCloud/clientdb](https://uniapp.dcloud.net.cn/uniCloud/clientdb) - -## 旧版clientDB简介 - -uni-clientDB 2.0.0版本不兼容旧版，如果你依然需要使用旧版本请在此链接下载 [uni-clientDB 1.0.8](https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/839b6a50-fe54-11ea-81ea-f115fe74321c.zip) - -clientDB框架的目标：减少服务端代码开发。 - -如今的应用，不管是App、小程序、H5，均是前后端分离。 - -前端是轻不下去了，但后端有机会越来越轻。 - -serveless减少了服务器的运维工作量，能不能再进一步，减少服务器的开发工作量？ - -答案是肯定的。 - -过去，大多数服务端代码开发就是这几件事： -1. 接收客户端参数，校验参数 -2. 校验客户端身份和权限 -3. 操作数据库 -4. 对数据加工变成json返回给前端 - -后端工程师不停的写上述代码，不停的为前端提供各种接口。前后端要不停的联调，甚至引入postman这种多余的工具。 - -clientDB的目标，就是让上述无聊的服务端代码开发，从此消失！ - -怎么做到？ - -- 首先，在前端操作数据库。前端直接写数据库增删改查的代码。 -- 然后，在云端通过json配置权限和校验规则，不写代码，但保证数据库操作的安全。 -- 同时，如果遇到需要写云端代码的时候，也可以通过action机制编写云函数代码进行处理。 - -> 举例：在前端的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个明显优势： -- 安全：查询权限是在云端控制的，能查什么表、什么字段，在云端控制。如果全部放在前端，由于前端的不可信任，相当于无法控制权限了。 -- 灵活：基于uni-id而不是绑定小程序用户，权限除了可配置，也支持js编程。而某些小程序云提供的客户端权限，依赖小程序账户，并且不可编程，无法满足开发者的实际业务中灵活的权限需求。 -- 跨端：uniCloud的clientDB是全端均可使用的。 -- 包体积：某些小程序云的客户端操作数据库是一个数M大小的js sdk，如果迁移到H5和App，对应用的启动速度、性能、体积、网站流量的影响非常大。但clientDB的客户端jssdk只有几k， - -综上，本插件的优势在于： -1. 大幅减少服务端开发工作量 -2. 减少云函数数量 -3. 安全，可完整、灵活的控制权限 -4. 更轻的客户端体积 - -本项目包括云函数和客户端两部分，需要搭配使用，具体请参考下面文档。 - -插件地址：[https://ext.dcloud.net.cn/plugin?id=2314](https://ext.dcloud.net.cn/plugin?id=2314) - -**插件示例项目使用须知** - -1. 下载示例项目后选择服务空间 -2. 在db_init.json上右键初始化数据库 -3. 上传公共模块及云函数，公共模块用法参考[使用公共模块](https://uniapp.dcloud.net.cn/uniCloud/cf-common) -4. 运行项目即可 - -## 目录结构@structure - -uni-clientDB项目目录结构如下 - -
-	
-┌─cloudfunctions              云函数
-│  ├─common                   公共模块
-|  │  └─uni-id	              uni-id公共模块
-|  ├─uni-clientDB             在云函数中控制权限
-|  |   ├─action               调用数据库查询前后执行的操作
-|  |   |  └─action-name.js    action逻辑
-|  |   ├─db-permission        数据库权限规则
-|  |   |  └─table-name.js     表名作为文件名设置不同表的权限规则
-|  |   ├─validator            数据格式校验规则
-|  |   |  └─table-name.js     表名作为文件名设置不同表的数据校验规则
-|  |   ├─index.js             clientDB云函数入口
-|  |   └─package.json         clientDB云函数package.json
-|  └─db_init.json             初始化数据库
-├─js_sdk                      前端公共js目录
-|  └─uni-clientDB             前端的js库，封装了查询语法
-├─pages                       业务页面文件存放的目录
-├─main.js                     Vue初始化入口文件
-├─App.vue                     应用配置，用来配置App全局样式以及监听 应用生命周期
-├─manifest.json               配置应用名称、appid、logo、版本等打包信息，详见
-└─pages.json                  配置页面路由、导航条、选项卡等页面类信息，详见
-	
-
- - -## clientDB框架图解 - -![](https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/b673c28f-c41b-406d-8b7a-c3f4bfbf4b31.jpg) - -上图中紫色部分为clientDB框架，它分为前端部分和云端部分。 - -下面将详细展开描述。 - -## 前端部分@jssdk - -clientDB的前端js-sdk主要负责提供API，允许前端编写数据库操作指令，以及处理一些客户端不太方便表示的字段，比如用户ID（详情看下面语法扩展部分） - -**示例代码** - -这段示例代码，在一个前端页面，直接查询了云数据库的`list`表，并且指定了`name`和`time`的`where`查询条件，then的res即为返回的查询结果。 - -```js -// 引入公共模块 -import db from '@/js_sdk/uni-clientDB/index.js' -const dbCmd = db.command - -// 使用uni-clientDB -db.collection('list') - .where({ - name: "hello-uni-app" - }).get() - .then((res)=>{ - // res 为数据库查询结果 - }).catch((err)=>{ - - }) -``` - -**使用说明** - -语法与云函数写查询数据库一致，目前有以下限制： - -- uni-clientDB 2.0.3以下版本，不可使用db.serverDate、db.Geo、db.RegExp，建议升级新版本 -- 上传时会对query进行序列化，除Date类型、RegExp之外的所有不可序列化的参数类型均不支持（例如：undefined） -- 为方便控制禁止前端使用set方法，一般情况下也不需要前端使用set -- 更新数据库时不可使用更新操作符`db.command.inc`等 -- 更新数据时键值不可使用`{'a.b.c': 1}`的形式（后续会对此进行优化） - -### 前端sdk语法扩展 - -clientDB目前内置了3个变量可以供客户端使用，客户端并非直接获得这三个变量的值，而是需要传递给clientDB云函数，云函数解析之后给赋予真正的值。 - -|参数名 |说明 | -|:-: |:-: | -|db.env.uid |用户uid，依赖uni-id | -|db.env.now |服务器时间戳 | -|db.env.clientIP|当前客户端IP | - -使用这些变量，将可以避免过去在服务端代码中写代码获取用户uid、时间和客户端ip的麻烦。 - -### 查询条件扩展@jsquery - -自uni-clientDB 2.0.5版本起，支持使用类js语法进行查询条件的编写。具体看以下示例 - -```js -import db from '@/js_sdk/uni-clientDB/index.js' -const dbCmd = db.command - -// 上面的示例中的where条件可以使用以下写法 -db.collection('list') - .where('name == "hello-uni-app"') - .get() - .then((res)=>{ - // res 为数据库查询结果 - }).catch((err)=>{ - - }) -``` - -**条件内可以使用的变量** - -|变量名 |说明 | -|:-: |:-: | -|auth.uid |用户id | -|auth.role |用户角色数组，参考[uni-id 角色权限](/uniCloud/uni-id?id=rbac)，注意`admin`为clientDB内置的角色，如果用户角色列表里包含`admin`则认为此用户有完全数据访问权限| -|auth.permission|用户权限数组，参考[uni-id 角色权限](/uniCloud/uni-id?id=rbac) | -|now |当前时间戳（单位：毫秒），时间戳可以进行额外运算，如publish\_date > now - 60000表示publish\_date在最近一分钟 | - - -**条件语句内可以使用的运算符** - -|运算符 |说明 |示例 |示例解释(集合查询) | -|:-: |:-: |:-: |:-: | -|== |等于 |name == 'abc' |查询name属性为abc的记录，左侧为数据库字段 | -|!= |不等于 |name != 'abc' |查询name属性不为abc的记录，左侧为数据库字段 | -|> |大于 |age>10 |查询条件的 age 属性大于 10，左侧为数据库字段 | -|>= |大于等于 |age>=10 |查询条件的 age 属性大于等于 10，左侧为数据库字段 | -|< |小于 |age<10 |查询条件的 age 属性小于 10，左侧为数据库字段 | -|<= |小于等于 |age<=10 |查询条件的 age 属性小于等于 10，左侧为数据库字段 | -|in |存在在数组中 |status in ['a','b'] |查询条件的 status 是['a','b']中的一个，左侧为数据库字段 | -|! |非 |!(status in ['a','b']) |查询条件的 status 不是['a','b']中的任何一个 | -|&& |与 |uid == auth.uid && age > 10 |查询记录uid属性 为 当前用户uid 并且查询条件的 age 属性大于 10| -||| |或 |uid == auth.uid||age>10|查询记录uid属性 为 当前用户uid 或者查询条件的 age 属性大于 10| -|test |正则校验 |/abc/.test(content) |查询 content 内包含abc的记录 。可用于替代sql中的like。还可以写更多正则实现更复杂的功能 | - - -### 刷新token - -透传uni-id自动刷新的token给客户端 - -**用法** - -```js -// 引入公共模块 -import db from '@/js_sdk/uni-clientDB/index.js' - -function refreshToken({ - token, - tokenExpired -}) { - uni.setStorageSync('uni_id_token', token) - uni.setStorageSync('uni_id_token_expired', tokenExpired) -} -// 绑定刷新token事件 -db.auth.on('refreshToken', refreshToken) -// 解绑刷新token事件 -db.auth.off('refreshToken', refreshToken) -``` - -## 云端部分 - -clientDB的云端部分较多，包含一个公共模块uni-curd，还有一个很大的云函数uni-clientDB。 - -云函数uni-clientDB主要负责接收客户端的请求，根据db-permission里的配置做权限校验、根据validator里的配置对即将写库的数据做格式合法性校验、执行前端执行的某个action、执行具体的数据库操作。 - -它有若干子目录，解释如下： - -1. db-permission目录用于存放权限规则。db-permission下每个文件对应一个表的权限，文件名为对应的表名。所谓数据权限，即什么样的用户身份，可以访问、操作哪些表、哪些字段。 -2. validator目录用于存放字段数据校验规则。和db-permission一样，validator目录下每个文件的文件名对应一个表名。 -3. action目录下存放各种action，action的作用是额外触发一段云函数逻辑。支持在操作数据库前触发action.before，也称为预处理，支持在操作数据库后触发action.after，也称为后处理。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，需要获取不同角色用户拥有的权限（在权限规则内使用auth.permission），请先查阅[uni-id 角色权限](https://uniapp.dcloud.net.cn/uniCloud/uni-id?id=rbac) - -clientDB云端默认返回值形式如下，开发者可以在action的after内用js修改返回结果，传入after内的result不带code和message。 - -```js -{ - code: "", // 错误码 - message: "" // 错误信息 - ... // 数据库指令执行结果 -} -``` - -**错误码列表** - -|错误码 |描述 | -|:-: |:-: | -|TOKEN_INVALID_INVALID_CLIENTID |token校验未通过（设备特征校验未通过） | -|TOKEN_INVALID |token校验未通过（云端已不包含此token） | -|TOKEN_INVALID_TOKEN_EXPIRED |token校验未通过（token已过期） | -|TOKEN_INVALID_WRONG_TOKEN |token校验未通过（token校验未通过） | -|SYNTAX_ERROR |db-permission语法错误 | -|PERMISSION_ERROR |权限校验未通过 | -|VALIDATION_ERROR |数据格式未通过 | -|SYSTEM_ERROR |系统错误 | - - - -为了更好的控制客户端行文，客户端在db-permission不为公有读（并非true时）时写法有以下限制： - -- 不使用聚合时collection方法之后需紧跟一个where方法，这个where方法内传入的条件必须满足权限控制规则 -- 使用聚合时aggregate方法之后需紧跟一个match方法，这个match方法内的条件需满足权限控制规则 -- 使用lookup时只可以使用拼接子查询的写法（let+pipeline模式），做这个限制主要是因为需要确保访问需要lookup的表时也会传入查询条件，即pipeline参数里面`db.command.pipeline()`之后的match方法也需要像上一条里面的match一样限制 -- 上面用于校验权限的match和where后的project和field是用来确定本次查询需要访问什么字段的（如果没有将会认为是在访问所有字段），访问的字段列表会用来确认使用那些字段权限校验。这个位置的project和field只能使用白名单模式 -- 上面用于校验权限的match和where内如果有使用`db.command.expr`，那么在进行权限校验时expr方法内部的条件会被忽略，整个expr方法转化成一个不与任何条件产生交集的特别表达式，具体表现请看下面示例 - -可以参考db-permission内的使用示例说明 - -### db-permission - -db-permission目录内存放数据表权限的配置文件，以表名作为文件名，clientDB会自动读取要访问的表的权限。 - -实际运行时， -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配置示例** - -```js -// db-permission/order.js -module.exports = { - // 关于权限中用到的auth对象及doc对象请看下方说明 - // 新增数据时的权限 - '.create': false, // 禁止新增数据记录 - // 读取数据时的权限 - '.read': 'doc.uid == auth.uid', // 每个用户只能读取用户自己的数据。前提是要操作的数据doc，里面有一个字段存放了uid，即uni-id的用户id。 - // 更新数据时的权限 - '.update': false, // 禁止更新数据 - // 删除数据时的权限 - '.delete': false, // 禁止删除数据 - // secret_field字段的权限，需要注意的是字段只有读写权限 - // 访问一个子节点时会使用所有上级权限，所有上级权限及字段本身权限都满足时才可以操作 - 'secret_field': { // 这是一个字段，叫secret_field - // secret_field字段的读权限 - '.read': false, // 禁止读取secret_field字段的数据 - // secret_field字段的写权限 - '.write': false // 禁止写入secret_field字段的数据 - } -} -``` - -```js -// db-permission/book.js -module.exports = { - // 未配置的权限默认为false - // 读取数据时的权限 - '.read': 'doc.status == "OnSell"' // 所有人均可读取字段status="ObSell"的数据 -} -``` - -**请求示例** - -```js -import db from '@/js_sdk/uni-clientDB/index.js' -const dbCmd = db.command -const $ = dbCmd.aggregate -db.collection('order') - .aggregate() - // 此match方法内的条件会和order表对应的权限规则进行校验 - .match({ - uid: db.env.uid - }) - // 此project方法是为了确定查询需要访问order表的哪些字段 - .project({ - _id: true, - book_id: true - }) - .lookup({ - from: 'book', - let: { - book_id: '$book_id' - }, - pipeline: $.pipeline() - // 此match方法内的条件会和book表对应的权限规则进行校验，{status: 'OnSell'}会参与校验，整个expr方法转化成一个不与任何条件产生交集的特别表达式。这里如果将dbCmd.and换成dbCmd.or会校验不通过 - .match(dbCmd.and([ - { - status: 'OnSell' - }, - // 指定book表的_id等于order表的book_id - dbCmd.expr( - $.eq(['$_id', '$$book_id']) - ) - ])) - // 此project方法是为了确定查询需要访问book表的哪些字段 - .project({ - book_name: true - }) - .done() - }) - .end() - -``` - -**权限规则内可以使用的全局变量** - -|变量名 |说明 | -|:-: |:-: | -|auth.uid |用户id | -|auth.role |用户角色数组，参考[uni-id 角色权限](/uniCloud/uni-id?id=rbac)，注意`admin`为clientDB内置的角色，如果用户角色列表里包含`admin`则认为此用户有完全数据访问权限| -|auth.permission|用户权限数组，参考[uni-id 角色权限](/uniCloud/uni-id?id=rbac) | -|doc |记录内容，用于匹配记录内容/查询条件（需要注意的是，规则内的doc对象并不是直接去校验存在于数据库的数据，而是校验客户端的查询条件） | -|now |当前时间戳（单位：毫秒），时间戳可以进行额外运算，如doc.publish\_date > now - 60000表示publish\_date在最近一分钟 | -|action |当前客户端指定的action | - -db-permission为对数据的操作权限，如果要封装业务权限，可以在uni-id的业务权限表里进行配置。业务权限进一步可组装为角色。然后每个具体的uni-id用户可以被赋予某个角色。 - -如果在uni-id里定义了业务权限和角色，也可以在db-permission中通过auth.permission和auth.role来使用，以实现更灵活的配置定义。 - -**权限规则内可以使用的运算符** - -|运算符 |说明 |示例 |示例解释(集合查询) | -|:-: |:-: |:-: |:-: | -|== |等于 |auth.uid == 'abc' |用户id为abc | -|!= |不等于 |auth.uid != 'abc' |用户id不为abc | -|> |大于 |doc.age>10 |查询条件的 age 属性大于 10 | -|>= |大于等于 |doc.age>=10 |查询条件的 age 属性大于等于 10 | -|< |小于 |doc.age<10 |查询条件的 age 属性小于 10 | -|<= |小于等于 |doc.age<=10 |查询条件的 age 属性小于等于 10 | -|in |存在在数组中 |doc.status in ['a','b'] |查询条件的 status 是['a','b']中的一个，数组中所有元素类型需一致 | -|! |非 `2.0.5+` |!(doc.status in ['a','b']) |查询条件的 status 不是['a','b']中的任何一个，数组中所有元素类型需一致| -|&& |与 |auth.uid == 'abc' && doc.age>10 |用户id 为 abc 并且查询条件的 age 属性大于 10 | -||| |或 |auth.uid == 'abc'||doc.age>10|用户Id为abc或者查询条件的 age 属性大于 10 | - -**权限规则内可以使用的方法** - -目前权限规则内仅可使用get方法，作用是根据id获取数据库中的数据。get方法接收一个字符串作为参数字符串形式为`database.表名.记录ID` - -用法示例: - -```js -"get(`database.shop.${doc.shop_id}`).owner == auth.uid" -``` - -使用get方法时需要注意get方法的参数必须是唯一确定值，以上述示例为例 - -```js -// 可以使用的查询条件，此条件内doc.shop_id只能是'123123' -db.collection('street').where({ - shop_id: '123123' -}).get() - -// 不可使用的查询条件，此条件内doc.shop_id可能是'123123'也可能是'456456' -const dbCmd = db.command -db.collection('street').where(dbCmd.or([ - { - shop_id: '123123' - }, - { - shop_id: '456456' - } -])).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主要用于在云端数据库操作前后的编程处理。 - -它是一个可选模块。当一个前端操作数据库的方式不能完全满足需求，仍然同时需要在云端再执行一些云函数时，就在前端发起数据库操作时，通过db.action("someactionname")方式要求云端同时执行这个叫someactionname的action。 - -每个action在action目录下存放一个以action名称命名的js文件。 - -在这个js文件中，包括before和after两部分。 - -- before部分的常用用途： - * 对前端传的数据进行二次处理 - * 在此处开启数据库事务，万一操作数据库失败，可以在after里回滚 - -- after部分的常用用途： - * 对将要回传给前端的数据进行二次处理 - * 也可以在此处处理错误，回滚数据库事务 - * 对数据库进行二次操作，比如前端查询一篇文章详情后，在此处对文章的阅读数+1。因为db-permission里定义，一般是要禁止前端操作文章的阅读数字段的，此时就应该通过action，在云函数里对阅读数+1 - -示例： - -```js -// 客户端发起请求，给todo表新增一行数据，同时指定action为add-todo -import db from '@/js_sdk/uni-clientDB/index.js' -db.action('add-todo') - .collection('todo') - .add({ - title: 'todo title' - }) - .then(res => { - console.log(res) - }).catch(err => { - console.error(err) - }) -``` - -```js -// 一个action文件示例 action/add-todo.js -module.exports = { - // 在数据库操作之前执行 - before: async(state,event)=>{ - // state为当前clientDB操作状态其格式见下方说明 - // event为传入云函数的event对象 - - // before内可以操作state上的newData对象对数据进行修改，比如： - state.newData.create_time = Date.now() - // 指定插入或修改的数据内的create_time为Date.now() - // 执行了此操作之后实际插入的数据会变成 {title: 'todo title', create_time: xxxx} - // 实际上，这个场景，有更简单的实现方案：在db schema、validator内配置defaultValue或者forceDefaultValue，即可自动处理新增记录使用当前服务器时间 - }, - // 在数据库操作之后执行 - after:async (state,event,error,result)=>{ - // state为当前clientDB操作状态其格式见下方说明 - // event为传入云函数的event对象 - // error为执行操作的错误对象，如果没有错误error的值为null - // result为执行command返回的结果 - - if(error) { - throw error - } - - // after内可以对result进行额外处理并返回，如果有after方法，则云函数返回值会是after方法的返回值 - result.msg = 'hello' - return result - } -} -``` - -**state**参数说明 - -```js -// state参数格式如下 -{ - command: { - // getMethod('where') 获取所有的where方法，返回结果为[{$method:'where',$param: [{a:1}]}] - getMethod, - // 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控制台数据库表结构生成。 - -一个典型的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: "变量名"}`的形式指定默认值为一些特殊变量，目前有以下可选变量名 - -```js -// 指定默认值为当前时间戳 -forceDefaultValue: { - $env: 'now' -} - -// 指定默认值为当前用户ID -forceDefaultValue: { - $env: 'uid' -} - -// 指定默认值为当前客户端IP地址 -forceDefaultValue: { - $env: 'clientIP' -} -``` - - -