uni-app x 云函数调用指南：uniCloud.callFunction 完整用法、泛型传参与安全网络加密

uni-app x 云函数调用指南uniCloud.callFunction 完整用法、泛型传参与安全网络加密【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读本文基于 uni-app 开源仓库中的 uniCloud 云函数调用文档系统讲解 uni-app x 中通过uniCloud.callFunction(options)请求云函数的完整 API包括参数结构、返回值类型、各端兼容性、4.13 起新增的泛型支持以及 4.71 起的安全网络加密secretType。读者将掌握云函数调用的标准写法、在 UTS 中安全访问返回 JSON 数据的方法并能结合仓库中的真实示例echo-cf、encryption、verify-client 云函数直接落地到自己的工程中。一、callFunction 是什么客户端与服务端的桥梁在 uni-app x 中uniCloud.callFunction(options)用于请求云函数是客户端App、Web、微信小程序、HarmonyOS调用 uniCloud 云端 Node.js 云函数的核心入口。与之对应的引用云对象能力见 object.md二者构成 uniCloud 在 uni-app x 中两大远程调用形态。其调用链路为客户端携带云函数名name与参数data→ uniCloud 网关路由到目标云函数 → 云函数exports.main async (event, context)收到event即客户端传入的 data并执行 → 返回结果经网关回传客户端包装为UniCloudCallFunctionResult。二、callFunction 兼容性矩阵调用云函数需要各端 HBuilderX / 运行环境的版本支持各端起点如下| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 阿里云 3.9腾讯云 3.91支付宝云 3.98 | 4.11 | 4.61 |补充说明来自 unicloud READMEAndroid 端云函数能力按服务商区分3.9支持阿里云3.91支持腾讯云3.98支持支付宝小程序云当前 uniCloud 在 uni-app x 下暂不支持 schema2code且 uts 插件编译为 swift、arkts 时插件内不可调用 uniCloud规划云端能力时需留意这两项限制。三、参数详解UniCloudCallFunctionOptionscallFunction仅有一个必填参数options类型为UniCloudCallFunctionOptions| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :- | :- | | name | string (string.CloudFunctionString) | 是 | - | 云函数名 | | data | UTSJSONObject | 否 | - | 云函数参数 | | secretType | string | 否 | Web: x; 微信小程序: 4.41; Android: 4.71; iOS: 4.71; HarmonyOS: x | 加密类型指定加密请求、响应还是都加密 |3.1 name云函数名必填项。云函数名对应云端已部署的云函数目录名。仓库中的示例工程 src/uniCloud-aliyun/cloudfunctions 下部署了echo-cf、encryption、verify-client、univerify等云函数客户端页面 cloud-function.uvue 中即以name: echo-cf发起调用。3.2 data云函数参数可选。类型为UTSJSONObjectUTS 内置对象详见 UTSJSONObject 文档会被整体透传给云函数的event参数。以仓库中的 echo-cf 云函数 index.js 为例use strict; exports.main async (event, context) { // event 为客户端上传的参数 console.log(event : , event) return { event, context, showMessage: Hello uniCloud function, detail: { functionName: echo-cf, timestamp: Date.now() } } };客户端传data: { num: 1, str: ABC }时云函数侧event即为{ num: 1, str: ABC }。3.3 secretType安全网络加密类型4.41 / 4.71可选。用于指定加密请求、响应还是都加密是 uni-app x 安全网络能力的一部分| 合法值 | 兼容性 | | :- | :- | | request | Web: x; 微信小程序: 4.41; Android: 4.71; iOS: 4.71; HarmonyOS: x | | response | - | | both | - | | none | - |注意secretType目前仅微信小程序4.41与 Android / iOS4.71支持Web 与 HarmonyOS 标为x不支持同时安全网络功能需要打包自定义基座方可正常使用见示例页面的提示文本。仓库在 Android / iOS 条件编译下专门提供了加密调用示例 cloud-function.uvueuniCloud.callFunction({ name: encryption, data: {}, secretType: both }).then(res { uni.hideLoading() notify(JSON.stringify(res.result), 提示) }).catch((err : any | null) { // 处理 UniCloudError })对应的云端 encryption 云函数 index.js 会在服务端校验context.secretTypeuse strict; exports.main async (event, context) { const secretType context.secretType // secretType 是客户端调用 uniCloud.callFunction 传递的参数 secretType if (secretType ! both) { const error new Error(客户端指定的secretType不为both拒绝此次请求) error.code INVALID_SECRET_TYPE throw error // 拒绝本次请求 } return { returnBy: encyption } };从源码可以推断secretType会随请求上下文透传到云函数侧context.secretType云函数据此决定是否放行从而形成客户端声明加密 → 服务端校验加密类型的双向约束。四、返回值PromiseUniCloudCallFunctionResult调用返回PromiseUniCloudCallFunctionResult结构如下| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | result | UniCloudCallFunctionResult | 是 | 云函数返回结果 | | requestId | string | 否 | 云函数请求 id |requestId为本次调用的请求 ID可用于云端日志排查与问题定位result为云函数返回值默认类型为UTSJSONObject。4.1 UniCloudCallFunctionResult 的泛型与版本约束4.13 版本起安卓端使用UniCloudCallFunctionResult必须传入泛型例如UniCloudCallFunctionResultUTSJSONObject其中泛型类型即为result属性的类型。注意4.13 版本起支持泛型后仅安卓端会构造对应泛型的实例Web 端和 iOS 端泛型仅作为类型使用编译期类型约束运行时仍为 UTSJSONObject。五、调用云函数时传入泛型4.135.1 基本语法uniCloud.callFunction泛型类型({name: xxx, data: {}} as UniCloudCallFunctionOptions)类型推断规则不传泛型时返回类型为PromiseUniCloudCallFunctionResultUTSJSONObject传入泛型后返回类型为PromiseUniCloudCallFunctionResult泛型类型。这意味着传入自定义结构体后res.result可直接以属性方式访问无需再手动get()取值。5.2 官方代码示例文档原例云函数侧fn// 云函数fn代码 use strict; exports.main async (event, context) { return { errCode: 0, errMsg: , detail: call function detail }; };客户端侧// 客户端代码 type CallFunctionResult { errCode : number, errMsg : string, detail : string } uniCloud.callFunctionCallFunctionResult( { name: fn, data: { a: 1 } as UTSJSONObject, } as UniCloudCallFunctionOptions ).then(function (res) { const result res.result // result的类型为CallFunctionResult const detail result.detail // 可直接使用.detail访问 console.log(detail) }).catch(function (err : any | null) { console.error(err) })要点type定义的结构体字段需与云函数返回值一一对应data与options分别使用as UTSJSONObject/as UniCloudCallFunctionOptions断言以通过 UTS 类型检查泛型生效后result.detail可直接访问避免了 UTSJSONObject 的get()链式取值。5.3 仓库实战示例echo-cf 泛型调用仓库示例页 cloud-function.uvue 中callFunctionWithGeneric以EchoCfResult为泛型调用echo-cfasync function callFunctionWithGeneric(): Promisevoid { type EchoCfResult { showMessage : string } uni.showLoading({ title: 加载中... }) await uniCloud.callFunctionEchoCfResult({ name: echo-cf, data: { num: 1, str: ABC } }).then(res { const result res.result uni.hideLoading() data.genericDemoShowMessage result.showMessage notify(result.showMessage, 提示) }).catch((err : any | null) { const error err as UniCloudError data.callFunctionError { errCode: error.errCode, errMsg: error.errMsg } as UTSJSONObject uni.hideLoading() notify(error.errMsg, 错误) }) }由于 echo-cf 云函数 index.js 返回了showMessage字段泛型EchoCfResult即可与之对应result.showMessage直接可用。5.4 不传泛型时的 UTSJSONObject 取值方式对比仓库中同页面的普通调用 cloud-function.uvue不传泛型时result为UTSJSONObject需要通过get()或下标访问取值await uniCloud.callFunction({ name: echo-cf, data: { num: 1, str: ABC } }).then(res { const result res.result data.callFunctionResult result const detail result.get(detail) as UTSJSONObject data.callFunctionResult_Detail_functionName detail.get(functionName) as string notify(result[showMessage] as string, 提示) }).catch((err : any | null) { // err instanceof UniCloudError 判断后取出 errCode / errMsg })可以看出泛型方案在类型安全与编码体验上都优于手动get()推荐在结构确定的场景下优先使用。六、错误处理UniCloudError调用失败时 Promise 进入catch错误对象为UniCloudError可通过errCode、errMsg获取错误码与信息。仓库示例中的统一处理范式.catch((err : any | null) { if(err instanceof UniCloudError) { const error err as UniCloudError data.callFunctionError { errCode: error.errCode, errMsg: error.errMsg } as UTSJSONObject notify(error.errMsg, 错误) } else { console.error(err) } })encryption云函数抛出的INVALID_SECRET_TYPE即会以此形式返回给客户端。示例页面还暴露了jest_UniCloudError()用于测试环境校验UniCloudError的 instanceof 判断逻辑。七、与云对象调用importObject的关系云函数调用强调以函数为粒度而 importObject 则是以对象/方法为粒度引用云对象二者均属于 uni-app x 的云端远程调用体系callFunction单一入口参数通过data传入返回UniCloudCallFunctionResultimportObjectcallMethodT UTSJSONObject(methodName, args)按方法调用且支持secretMethods指定方法级加密、loadingOptions/errorOptions配置加载与错误 UI。需要方法级安全网络配置或自动 loading/错误提示时优先考虑云对象简单的函数请求则直接使用callFunction。八、参考与延伸阅读本文核心依据uniCloud 云函数调用 API 文档uniCloud 总体能力与兼容说明unicloud README云对象调用object.mdUTSJSONObject 内置对象UTSJSONObject 文档云函数返回结果类型UniCloudCallFunctionResult说明见上文返回值章节仓库实战页面cloud-function.uvue配套云函数实现src/uniCloud-aliyun/cloudfunctionsecho-cf、encryption、verify-client 等【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考