WxJava 小程序云开发(CloudBase)实战指南:从 Maven 依赖到云函数、云数据库与云存储全接口调用
WxJava 小程序云开发(CloudBase)实战指南:从 Maven 依赖到云函数、云数据库与云存储全接口调用
导读
本文面向使用 WxJava(weixin-java-miniapp 模块)开发微信小程序的 Java 后端工程师,完整讲解如何在项目中接入微信小程序·云开发(CloudBase)能力。云开发是微信与腾讯云联合推出的基于 Serverless 架构的一站式后端云服务,涵盖云函数、云数据库、云存储与 CDN 等能力,免鉴权即可调用微信开放能力。读完本文,你将掌握:引入 Maven 依赖、构造配置类与 Service、通过 WxMaCloudService 触发云函数、操作云数据库(增删改查、聚合、集合管理、数据导入导出)、管理云存储文件(上传/下载/删除),以及如何与 Spring 框架整合。文中所有接口说明均以当前仓库源码为基准,并给出对应的源码文件路径供深入研读。
一、云开发与小程序云开发简介
云开发(CloudBase)是基于 Serverless 架构构建的一站式后端云服务,涵盖函数、数据库、存储、CDN 等服务,免后端运维,支持小程序、Web 和 APP 开发。其中,小程序·云开发是微信和腾讯云联合推出的云端一体化解决方案:
- 在微信开发者工具中即可开通使用,无需自建服务器;
- 基于云开发可以免鉴权调用微信所有开放能力;
- 云函数、云数据库、云存储开箱即用,天然适配小程序后端业务。
在 WxJava 中,与云开发相关的全部能力被收敛在 WxMaCloudService 接口中,由 WxMaCloudServiceImpl 实现(接口定义、实现类)。该接口自 2020-01-22 起随 weixin-java-miniapp 模块提供,覆盖云函数、数据库、存储、腾讯云凭证、集合管理、短信等能力,且每个 HTTP 接口的请求地址集中定义在 WxMaApiUrlConstants.java 的 Cloud 常量组 中,统一走 https://api.weixin.qq.com/tcb/* 路径。
二、第一步:引入 Maven 依赖
在小程序后端项目中,首先需要在 pom.xml 中引入 weixin-java-miniapp 依赖:
<dependency>
<groupId>com.github.binarywang</groupId>
<artifactId>weixin-java-miniapp</artifactId>
<version>4.8.6.B</version>
</dependency>
说明:原文档示例中的版本为
3.7.1.B,当前仓库 weixin-java-miniapp/pom.xml 中该模块版本已演进为4.8.6.B(父工程wx-java版本),建议以你实际使用的 Maven 中央仓库最新版本为准,本文示例统一使用当前仓库版本。weixin-java-miniapp 依赖 weixin-java-common,并可选使用 jodd-http、okhttp、httpclient5 等 HTTP 实现。
三、第二步:构造配置类,填入相关参数
云开发接口调用同样依赖小程序的全局配置。通过 WxMaDefaultConfigImpl 构造配置对象并填入基础参数:
WxMaDefaultConfigImpl config = new WxMaDefaultConfigImpl();
config.setAppid("..."); // 微信小程序的 appid
config.setSecret("..."); // 微信小程序的 Secret
config.setToken("..."); // 微信小程序消息服务器配置的 token,如果程序不涉及相关功能,可以忽略
config.setAesKey("..."); // 微信小程序消息服务器配置的 EncodingAESKey,同上,如果不涉及,可以忽略
config.setMsgDataFormat("JSON"); // 消息数据格式,可以为 XML 或者 JSON
config.setCloudEnv("..."); // 云开发环境 ID(env),调用不带 env 参数的云开发接口时默认使用该值
各参数说明:
| 参数 | 含义 | 是否必填 |
|---|---|---|
appid |
微信小程序 AppID | 必填 |
secret |
微信小程序 AppSecret | 必填 |
token |
消息服务器配置 Token,仅涉及消息收发时需要 | 按需 |
aesKey |
消息服务器配置 EncodingAESKey,仅涉及加解密消息时需要 | 按需 |
msgDataFormat |
消息数据格式,XML 或 JSON |
按需 |
cloudEnv |
云开发环境 ID,决定云函数/数据库/存储操作落在哪个环境 | 使用云开发时强烈建议配置 |
其中 cloudEnv 由 WxMaConfig 接口声明(getCloudEnv()),在 WxMaDefaultConfigImpl 中通过 setCloudEnv(String) 设置、getCloudEnv() 读取。
云环境 ID 的两种指定方式(对应源码设计):WxMaCloudService 中几乎每个接口都提供了「带 env 参数」和「不带 env 参数」两个重载。不带 env 的版本内部会自动从 config.getCloudEnv() 取值。例如 invokeCloudFunction(String name, String body) 的实现为:
String cloudEnv = this.wxMaService.getWxMaConfig().getCloudEnv();
return invokeCloudFunction(cloudEnv, name, body);
这意味着:若你的项目只使用一个云环境,配置好 cloudEnv 后调用单参数版本即可;若需在多个云环境间切换,则显式传入 env 参数调用双参数版本。该模式同样适用于 databaseAdd、databaseQuery、uploadFile、batchDeleteFile 等全部云开发接口。
四、第三步:构造 Service 类并关联配置
WxMaService 是进入小程序全部能力(含云开发)的门面。构造方式如下:
WxMaService wxMaService = new WxMaServiceImpl();
wxMaService.setWxMaConfig(config);
WxMaServiceImpl 继承自 BaseWxMaServiceImpl,后者在初始化时便创建了云开发服务实例:
private final WxMaCloudService cloudService = new WxMaCloudServiceImpl(this);
并通过 getCloudService() 暴露给调用方(见 BaseWxMaServiceImpl.java)。之后所有云开发操作都通过 wxMaService.getCloudService() 完成。
五、第四步:调用云开发接口
5.1 触发云函数
以触发云函数为例,invokeCloudFunction 方法签名如下:
String invokeCloudFunction(String env, String name, String body) throws WxErrorException;
env:云开发环境 ID;name:云函数名称;body:云函数的传入参数,具体结构由开发者定义(通常为 JSON 字符串)。
调用示例:
String result = wxMaService.getCloudService()
.invokeCloudFunction("rcn", "login", "{}"); // 拿到 result 之后,可以在后续加入自己的处理逻辑代码
从源码实现看,该方法最终向 https://api.weixin.qq.com/tcb/invokecloudfunction?env=%s&name=%s 发起 POST 请求,并从响应 JSON 中取出 resp_data 字段作为返回值(WxMaCloudServiceImpl.java#L50-L55)。接口的 JavaDoc 同时提示:HTTP API 途径触发云函数不包含用户信息,如需用户身份请在小程序端使用云函数 SDK 调用。
5.2 云数据库操作
WxMaCloudService 对云数据库提供了两套风格的方法:
- 面向集合的封装方法(底层自动拼接数据库查询语句):
add(collection, list/obj)、delete(collection, whereJson)、update(collection, whereJson, updateJson)、query(collection, whereJson, orderBy, skip, limit)、count(collection, whereJson)。这些方法内部通过字符串拼接生成db.collection('...')....查询语句后调用 HTTP 接口; - 直接传数据库查询语句的方法(与微信官方 HTTP API 对齐):
databaseAdd、databaseDelete、databaseUpdate、databaseQuery、databaseAggregate、databaseCount。
以 query 为例,源码中会按 where、orderBy、skip、limit 的顺序拼装查询语句,limit 缺省为 100、skip 缺省为 0;排序条件通过 Map<String, String> orderBy 表达(key 为字段名,value 为 asc/desc)。更完整的查询语句示例可直接参考 WxMaCloudServiceImplTest 测试类,例如数据库查询:
WxCloudDatabaseQueryResult result = wxMaService.getCloudService().databaseQuery(
"db.collection(\"geo\").where({done:false}).limit(10).skip(1).get()");
聚合示例:
JsonArray result = wxMaService.getCloudService().databaseAggregate(
"db.collection(\"geo\").aggregate().match({tags:\"cloud\"}).limit(10).end()");
5.3 云存储(文件)操作
云存储能力覆盖文件上传、批量下载、批量删除:
// 获取文件上传链接(拿到 url/token/authorization/fileId 后再执行实际上传)
WxCloudUploadFileResult upload = wxMaService.getCloudService().uploadFile(env, path);
// 批量获取文件下载链接:fileIds 与 maxAges(有效期,单位秒)一一对应
WxCloudBatchDownloadFileResult download = wxMaService.getCloudService()
.batchDownloadFile(env, new String[]{"cloud://.../a.png"}, new long[]{7200});
// 批量删除文件
WxCloudBatchDeleteFileResult del = wxMaService.getCloudService()
.batchDeleteFile(env, new String[]{"cloud://.../test.json"});
返回值封装在 bean/cloud 目录 下的结果对象中,例如 WxCloudUploadFileResult 包含 url、token、authorization、file_id、cos_file_id 等字段(WxCloudUploadFileResult.java),测试类中对各字段均有非空断言。
5.4 腾讯云 API 调用凭证
当业务需要直接调用腾讯云 API 时,可通过 getQcloudToken(long lifeSpan) 获取临时凭证,lifeSpan 为有效期(单位秒,最大 7200):
WxCloudGetQcloudTokenResult token = wxMaService.getCloudService().getQcloudToken(1800);
// token.getSecretId() / token.getSecretKey() / token.getToken() / token.getExpiredTime()
对应请求地址为 https://api.weixin.qq.com/tcb/getqcloudtoken,返回的 secretid、secretkey、token、expired_time 字段映射见 WxCloudGetQcloudTokenResult.java。
六、已支持的云开发接口总览
WxMaCloudService 当前已支持以下云开发 HTTP API(完整清单以 接口定义 为准;若官方后续新增接口,会在后续版本中跟进):
| 接口描述 | 方法名 |
|---|---|
| 删除文件 | batchDeleteFile(String env, String[] fileIds) |
| 获取文件下载链接 | batchDownloadFile(String env, String[] fileIds, long[] maxAges) |
| 数据库插入记录 | databaseAdd(String env, String query) |
| 数据库聚合记录 | databaseAggregate(String env, String query) |
| 新增集合 | databaseCollectionAdd(String env, String collectionName) |
| 删除集合 | databaseCollectionDelete(String env, String collectionName) |
| 获取特定云环境下集合信息 | databaseCollectionGet(String env, Long limit, Long offset) |
| 统计集合记录数或统计查询语句对应的结果记录数 | databaseCount(String env, String query) |
| 数据库删除记录 | databaseDelete(String env, String query) |
| 数据库导出 | databaseMigrateExport(String env, String filePath, int fileType, String query) |
| 数据库导入 | databaseMigrateImport(String env, String collectionName, String filePath, int fileType, boolean stopOnError, int conflictMode) |
| 数据库迁移状态查询 | databaseMigrateQueryInfo(String env, Long jobId) |
| 数据库查询记录 | databaseQuery(String env, String query) |
| 数据库更新记录 | databaseUpdate(String env, String query) |
| 获取腾讯云API调用凭证 | getQcloudToken(long lifeSpan) |
| 触发云函数 | invokeCloudFunction(String env, String name, String body) |
| 变更数据库索引 | updateIndex(String env, String collectionName, List<WxCloudDatabaseCreateIndexRequest> createIndexes, List<String> dropIndexNames) |
| 获取文件上传链接 | uploadFile(String env, String path) |
| 发送携带 URL Link 的短信 | sendSmsV2(WxCloudSendSmsV2Request request) |
补充几个关键参数的取值说明(均来自接口 JavaDoc 与实现代码):
fileType:导入/导出文件类型,1为 JSON,2为 CSV;conflictMode:导入冲突处理模式,1为 INSERT,2为 UPSERT;stopOnError:导入时是否遇到错误即停止;databaseCollectionGet的limit默认值 10、offset默认值 0;databaseMigrateImport的导入文件需先上传到同环境的云存储中,databaseMigrateExport的导出文件会落到同环境云存储,可用batchDownloadFile获取下载链接;sendSmsV2通过 WxCloudSendSmsV2Request 携带urlLink、templateId、templateParamList、phoneNumberList等参数,未指定 env 时自动取配置中的cloudEnv(见 WxMaCloudServiceImpl#sendSmsV2)。
七、源码级佐证:单元测试
仓库为云开发能力提供了完整的 TestNG 测试类 WxMaCloudServiceImplTest.java,覆盖了上述绝大部分接口,可作为方法调用与查询语句写法的直接参照。例如:
testInvokeCloudFunction:invokeCloudFunction("login", "{}")并断言返回非空;testDatabaseQuery/testDatabaseAggregate:展示db.collection(...)...get()、aggregate()...end()查询语句写法;testUpdateIndex:通过WxCloudDatabaseCreateIndexRequest构造新增索引、以字符串列表声明待删除索引;testUploadFile/testBatchDownloadFile/testBatchDeleteFile:验证上传、下载、删除结果的各字段;testGetQcloudToken:验证secretId、secretKey、token、expiredTime非空;testSendSmsV2:演示短信请求构造方式。
提示:这些测试需要真实的小程序云开发环境与有效配置才能运行,可参考测试类顶部的
ApiTestModule注入方式准备测试配置。
八、Spring 框架整合
WxMaCloudService 是普通 Java 接口,与 Spring 的整合方式与 WxJava 其他模块一致:将 WxMaConfig、WxMaService 声明为 Spring Bean,再注入到业务 Service 即可。仓库官方示例项目(weixin-java-miniapp-demo)基于 Spring Boot 展示了完整整合流程;如果你的项目使用 Spring MVC,参照示例适当改造(去掉自动配置、手动装配 Bean)即可。若希望以 Starter 方式快速接入,仓库还提供了 wx-java-miniapp-spring-boot-starter 与 wx-java-miniapp-multi-spring-boot-starter(多租户模式),可直接查看对应 README 了解配置项。
九、小结与延伸阅读
本文以「依赖引入 → 配置构造 → Service 装配 → 接口调用」为主线,完整还原了 WxJava 接入小程序云开发的五步流程,并基于仓库源码补充了云环境 ID 的传递机制、数据库查询语句拼装规则、文件与凭证接口的返回结构以及测试用例佐证。建议读者:
- 以 WxMaCloudService.java 为接口索引,按需查阅每个方法的 JavaDoc;
- 对照 WxMaCloudServiceImplTest.java 编写自己的调用代码;
- 涉及多环境时,优先使用带
env参数的重载,并确保config.setCloudEnv(...)已正确配置。