1.5 云对象内容总结
1. 云对象概述
云对象是uniCloud提供的一种新型服务端开发模式，它允许开发者以面向对象的方式编写API，客户端可以直接调用这些API，无需手动处理请求和响应。
1.1 背景与优势
- 简化开发流程：替代传统的RESTful接口开发模式，减少代码量
- 更清晰的代码结构：以对象方法的形式组织API，逻辑更清晰
- 更好的类型提示：支持JSDoc注释，提供更好的代码提示
- 自动UI交互：自动处理loading、错误提示等UI交互
- 更接近本地开发体验：客户端调用方式与本地对象方法调用类似
1.2 基本结构
云对象的基本结构如下：
// 云对象名：todo
module.exports = {
// 方法1
method1(param1, param2) {
// 方法实现
return {
errCode: 0,
errMsg: '操作成功',
data: { /* 返回数据 */ }
}
},
// 方法2
method2(param1) {
// 方法实现
}
}
2. 云对象的创建与调用
2.1 创建云对象
- 在HBuilderX中，右键点击
uniCloud/cloudfunctions目录 - 选择"新建云函数"
- 选择类型为"云对象"
- 输入云对象名称（如
todo） - 创建完成后，编辑
index.obj.js文件
2.2 客户端调用
// 导入云对象
const todo = uniCloud.importObject('todo')
// 调用云对象方法
async function addTodo() {
try {
const res = await todo.add('标题', '内容')
uni.showToast({
title: '创建成功'
})
} catch (e) {
uni.showModal({
title: '创建失败',
content: e.errMsg,
showCancel: false
})
}
}
importObject参数说明
interface ImportObjectOptions {
/**
* 是否移除自动展示的ui
*/
customUI?: boolean;
/**
* loading界面配置
*/
loadingOptions?: ImportObjectLoadingOptions;
/**
* 错误提示配置
*/
errorOptions?: ImportObjectErrorOptions;
/**
* 使用安全网络的方法及安全网络类型
*/
secretMethods?: Record<string, 'none' | 'request' | 'response' | 'both'>;
/**
* 转化云对象内未捕获的错误或客户端网络错误
*/
parseSystemError?: (params: ParseSystemErrorParams) => Promise<ParsedSystemError> | ParsedSystemError;
}
2.3 云函数或云对象内调用
// 导入云对象
const todo = uniCloud.importObject('todo')
// 调用云对象方法
const result = await todo.add('标题', '内容')
3. 云对象的特殊功能
3.1 生命周期方法
云对象支持三个特殊的生命周期方法：
- _before：方法执行前的预处理
- _after：方法执行后的后处理
- _timing：定时执行的方法
module.exports = {
// 预处理方法
async _before() {
// 获取客户端信息
const clientInfo = this.getClientInfo()
console.log('客户端信息', clientInfo)
},
// 后处理方法
async _after(result) {
// 记录日志
console.log('方法执行结果', result)
return result
},
// 定时执行方法
async _timing() {
console.log('定时任务执行', new Date().toISOString())
// 执行定时任务
return {
errCode: 0,
errMsg: '定时任务执行成功'
}
}
}
3.2 内置API
云对象提供了多种内置API，用于获取上下文信息：
- getClientInfo()：获取客户端信息
- getCloudInfo()：获取云端信息
- getClientToken()：获取客户端Token
- getMethodName()：获取当前调用的方法名
- getParams()：获取当前参数列表
- getRequestId()：获取当前请求ID
- getHttpInfo()：获取URL化时的HTTP信息
- setCookie()：设置Cookie
- getCookie()：获取Cookie
- deleteCookie()：删除Cookie
3.3 自动UI交互
从HBuilderX 3.4.6起，调用云对象方法时默认会自动显示交互界面：
- 请求开始时显示loading等待框
- 请求结束后隐藏loading
- 请求出错时显示错误提示
可以通过配置自定义UI交互：
uniCloud.importObject('todo', {
customUI: false, // 是否取消自动展示的交互界面
loadingOptions: { // loading相关配置
title: '加载中...', // 显示的loading内的提示文字
mask: true // 是否使用透明遮罩
},
errorOptions: { // 错误界面相关配置
type: 'modal', // 错误信息展示方式：modal或toast
retry: false // 是否展示重试按钮
}
})
4. 云对象的高级特性
4.1 JSDoc注释与类型提示
云对象支持JSDoc注释，提供更好的代码提示：
/**
* 添加待办事项
* @param {string} title 待办事项标题
* @param {string} content 待办事项内容
* @returns {object} 返回结果
*/
async add(title, content) {
// 方法实现
}
4.2 多个方法共享逻辑
可以将多个方法共享的逻辑放到云对象导出的对象外部：
// 共享逻辑
async function pureAddTodo(title, content) {
// 添加待办事项的逻辑
}
module.exports = {
async addTodo(title, content) {
return pureAddTodo(title, content)
},
async tryAddTodo(title, content) {
try {
return await pureAddTodo(title, content)
} catch (e) {
return {
errCode: 'add-todo-failed',
errMsg: e.message
}
}
}
}
4.3 参数体积限制
不同云服务商的参数体积限制不同：
- 支付宝云：参数大小不可超过6MB
- 阿里云：参数大小不可超过2MB
- 腾讯云：参数大小不可超过5MB
4.4 多种调用方式
云对象支持多种调用方式：
- 客户端调用：使用
uniCloud.importObject导入后调用 - 云函数或云对象内调用：在云函数或云对象中使用
uniCloud.importObject导入后调用 - 定时触发：通过云函数定时触发器调用
_timing方法 - URL化调用：通过HTTP请求调用云对象
- 跨服务空间调用：调用其他服务空间的云对象
5. 最佳实践
5.1 何时使用云对象
uniCloud提供了三种服务器和客户端交互方式：
- 云函数：传统方式，不推荐使用
- 云对象：推荐用于复杂业务逻辑或不宜公开在前端的逻辑
- clientDB：推荐用于以数据库操作为主的场景
5.2 云对象开发建议
- 合理组织方法：按功能模块组织方法，保持代码结构清晰
- 使用生命周期方法：利用
_before和_after处理通用逻辑 - 添加JSDoc注释：为方法添加JSDoc注释，提供更好的代码提示
- 统一错误处理：使用统一的错误码和错误信息格式
- 参数验证：在方法开始处进行参数验证
- 使用私有方法：以
_开头的方法为私有方法，客户端不可访问
6. 注意事项
- 云对象的入口文件为
index.obj.js，云函数的入口文件为index.js - 云函数内不可存在
index.obj.js，云对象内也不可存在index.js - 所有
_开头的方法都是私有方法，客户端不可访问 - 云对象可以引用公共模块或npm包，引用方式与云函数一致
- 云对象导出的方法不可以是箭头函数，否则会导致
this指向不正确
7. 总结
云对象是uniCloud提供的一种新型服务端开发模式，它以面向对象的方式组织API，简化了开发流程，提高了开发效率。通过使用云对象，开发者可以更专注于业务逻辑的实现，而不必过多关注请求和响应的处理。
云对象提供了丰富的内置API和生命周期方法，支持自动UI交互、JSDoc注释、多种调用方式等特性，使其成为uniCloud开发中不可或缺的工具。
