背景和优势
20年前，restful接口开发开始流行，服务器编写接口，客户端调用接口，传输json。
现在，替代restful的新模式来了。
云对象，服务器编写API，客户端调用API，不再开发传输json的接口。思路更清晰、代码更精简。
比如服务端编写一个云对象todo，该对象有add、get、remove、update等方法。客户端的js则可以直接import这个todo云对象，直接调用add等方法。
服务器示例代码如下：
HBuilderX中在uniCloud/cloudfunctions目录新建云函数，选择类型为云对象，起名为todo。打开云对象入口index.obj.js，添加一个add方法。
// 云对象名：todo
module.exports = {
add(title, content) {
title = title.trim()
content = content.trim()
if(!title || !content) {
return {
errCode: 'INVALID_TODO',
errMsg: 'TODO标题或内容不可为空'
}
}
// ...其他逻辑
return {
errCode: 0,
errMsg: '创建成功'
}
}
}
复制代码
然后在客户端的js中，import这个todo对象，调用它的add方法
const todo = uniCloud.importObject('todo') //第一步导入云对象
async function addTodo () {
try {
const res = await todo.add('title demo', 'content demo') //导入云对象后就可以直接调用该对象的方法了，注意使用异步await
uni.showToast({
title: '创建成功'
})
} catch (e) {
// 符合uniCloud响应体规范 https://doc.dcloud.net.cn/uniCloud/cf-functions?id=resformat，自动抛出此错误
uni.showModal({
title: '创建失败',
content: e.errMsg,
showCancel: false
})
}
}
复制代码
可以看到云对象的代码非常清晰，代码行数也只有33行。
而同样的逻辑，使用传统的接口方式则需要更多代码，见下：
// 传统方式调用云函数-云函数代码
// 云函数名：todo
// 云函数入口index.js内容如下
'use strict';
exports.main = async (event, context) => {
const {
method,
params
} = event
switch(method) {
case 'add': {
let {
title,
content
} = params
title = title.trim()
content = content.trim()
if(!title || !content) {
return {
errCode: 'INVALID_TODO',
errMsg: 'TODO标题或内容不可为空'
}
}
// ...省略其他逻辑
return {
errCode: 0,
errMsg: '创建成功'
}
}
}
return {
errCode: 'METHOD_NOT_FOUND',
errMsg: Method[${method}] not found
}
};
// 传统方式调用云函数-客户端代码
async function addToDo () {
try {
const res = await uniCloud.callFunction({
name: 'todo',
data: {
method: 'add',
params: {
title: 'title demo',
content: 'content demo'
}
}
})
const {
errCode,
errMsg
} = res.result
if(errCode) {
uni.showModal({
title: '创建失败',
content: errMsg,
showCancel: false
})
return
}
uni.showToast({
title: '创建成功'
})
} catch (e) {
uni.showModal({
title: '创建失败',
content: e.message,
showCancel: false
})
}
}
复制代码
以上传统开发需要68行代码，对比云对象的33行代码，不但工作量大，而且逻辑也不如云对象清晰。
_注：以上例子仅用于方便初学者理解。实际开发中对于简单的数据库操作，使用clientDB在前端直接操作数据库是更简单、代码更少的方案，都不需要写云端代码。
总结下云对象带来的好处：
更清晰的逻辑
更精简的代码
更少的协作成本（以及矛盾~）
客户端调用时在ide里有完善的代码提示，方法参数均可提示。（传输json可没法在ide里提示）
默认支持uniCloud响应体规范，方便错误拦截和统一处理
快速上手
创建云对象
云对象，其实是对云函数的封装。和创建云函数一样，在uniCloud/cloudfunctions目录右键新建云函数，选择云对象类型，输入云对象名称创建云对象，此处以云对象todo为例，创建的云对象包含一个index.obj.js。
创建云对象
一个空的云对象内容如下
// cloudfunctions/todo/index.obj.js
module.exports = {
}
复制代码
默认云对象模板是不包含任何方法的，我们为此对象添加一个add方法作为示例。
// cloudfunctions/todo/index.obj.js
module.exports = {
add: function(title = '', content = '') {
title = title.trim()
content = content.trim()
if(!title || !content) {
return {
errCode: 'INVALID_TODO',
errMsg: 'TODO标题或内容不可为空'
}
}
// ...其他逻辑，如操作todo数据表添加数据
return {
errCode: 0,
errMsg: '创建成功'
}
}
}
复制代码
至此云对象todo已经有了一个可以访问的方法了。接下来看如何使用客户端调用此云对象内的方法
客户端调用
客户端通过uniCloud.importObject方法获取云对象的实例，并可以通过此实例调用云对象内的方法。用法如下
const todo = uniCloud.importObject('todo')
const res = await todo.add('title demo', 'content demo')
复制代码
通过代码块cco可以快捷的输入以下代码：
const todo = uniCloud.importObject('todo')
复制代码
实际业务中需要考虑错误捕获，调用方式有两种：
try catch
const todo = uniCloud.importObject('todo')
try {
const res = await todo.add('title demo', 'content demo') //导入云对象后就可以直接调用该对象的方法了，注意使用异步await
console.log(res)
} catch (e) {
console.log(e.errCode)
console.log(e.errMsg)
}
复制代码
then catch(promise写法)
const todo = uniCloud.importObject('todo')
todo.add('title demo', 'content demo').then(res => {
console.log(res)
}).catch(e => {
console.log(e.errCode)
console.log(e.errMsg)
})
复制代码
importObject参数说明
interface ImportObjectOptions {
/**
- 是否移除自动展示的ui
*/
customUI?: boolean;
/**
- loading界面配置
*/
loadingOptions?: ImportObjectLoadingOptions;
/**
- 错误提示配置
*/
errorOptions?: ImportObjectErrorOptions;
/**
- 使用安全网络的方法及安全网络类型
*/
secretMethods?: Record<string, 'none' | 'request' | 'response' | 'both'>;
/**
- 转化云对象内未捕获的错误或客户端网络错误
*/
parseSystemError?: (params: ParseSystemErrorParams) => Promise<ParsedSystemError> | ParsedSystemError;
}
复制代码
云对象的API
云对象作为云函数的一种，可以调用所有node的API和uniCloud的API。
uniCloud有众多API，另见：uniCloud的API清单
除上述API之外，云对象的this对象还有一批专用方法来获取当前请求的上下文信息。
与云函数入参时的context不同，云对象没有context。它通过this对象挂载的几个内置方法来获取上下文信息。请注意开发者避免在this上挂载同名方法。
获取客户端信息
HBuilderX 3.4.9起此接口可获取所有客户端getSystemInfo返回的客户端信息，完整字段列表参考：getSystemInfo
接口形式
this.getClientInfo()
示例：
module.exports = {
add: function() {
const clientInfo = this.getClientInfo()
// clientInfo = {
// clientIP,
// appId,
// deviceId,
// source,
// //... 其他getSystemInfoSync返回值
// }
}
}
复制代码
返回值
getClientInfo返回的信息，是在客户端的uni.getSystemInfo的基础之上，增加了一些额外的信息。
除了getSystemInfo返回字段外，还包含以下信息
属性名 类型 说明
clientIP string 客户端ip
userAgent string 客户端ua，注意非本地运行环境下客户端getSystemInfoSync也会获取ua参数并上传给云对象，但是云对象会从http请求头里面获取ua而不是clientInfo里面的ua
source string 调用来源，返回值见下。HBuilderX 3.5.1+
requestId string 请求id。HBuilderX 3.5.1+
scene string 场景值。客户端uni.getLaunchOptionsSync返回的scene参数，新增于HBuilderX 3.5.1
getClientInfo().source，返回云函数调用来源，它的值域为：
取值 说明
client uni-app客户端导入云对象调用
function 由其他云函数或云对象调用
http 云对象URL化后通过http访问调用 HBuilderX 3.5.2+
timing 定时任务调用云对象 HBuilderX 3.5.2+
server 云函数上传并运行
注意事项
客户端上报的信息在理论上存在被篡改可能，实际业务中应验证前端传来的数据的合法性
除了clientIP外，其他客户端信息只有使用uni-app客户端以云对象的方式调用才能获取
云对象与云函数内获取客户端platform稍有不同，云函数未拉齐vue2、vue3版本app平台的platform值，vue2为app-plus，vue3为app。云对象无论客户端是vue2还是vue3，在app平台获取的platform均为app。这一点在使用uni-id时需要特别注意，详情见：uni-id文档 preferedAppPlatform
获取云端信息
接口形式
this.getCloudInfo()
示例
