评论

从文档出发,来聊一聊小程序的服务端开发

云开发中 3 类 API 文档的介绍

前面两篇内容分别介绍了云函数的开发与测试。原本这篇文章想介绍云数据库的开发,然而发现云数据库的开发,并没有什么特别的内容,大抵就是学会几个 API 的使用,看看文档就行了。

说到云开发的文档,就想再叨叨几句,其实文档写得很不错了,但是对于没有全栈开发经验的新手来说,还是难免有点迷糊。例如下图,其实是同一个东西,整出三份文档,而且很多内容都是重复的。

这只是文档呈现的问题,并不是文档本身的问题,反而,我觉得这样的呈现方式挺好。分门别类,你是哪种开发场景,直接进入对应的文档目录查看就行了,其他两份根本就不用看。

关键是,很多初学者,并不知道自己是哪种开发场景。这篇文章就来介绍一下这三类文档的差别。(嗯,有点意思,介绍文档的文档)

小程序端 API 文档

小程序端,顾名思义,就是在小程序端调用,准确的说,是在小程序页面的逻辑层中调用。注意:虽然云函数目录似乎和小程序的目录在一块,但一定要区别对待。其实,我更喜欢下面这样的目录结构。(原谅我一开始没有讲,循序渐进比较好)

云函数一个单独目录,小程序一个单独目录,通过 project.config.json 文件关联起来,关联的两个设置项如下:

"miniprogramRoot": "miniprogram/",
"cloudfunctionRoot": "cloudfunctions/",

如果你是在小程序的逻辑层(也就是每个页面的 js 文件)中调用,就看「小程序端 API 文档」,在使用 API 之前,需要进行初始化,放在小程序的启动事件函数 onLanuch 中就行了,示例代码如下:

wx.cloud.init({
  env: 'test-x1dzi'
})

其他,就是调用云函数,调用存储,调用数据库,参照文档学会 API 的使用就可以了。

服务端 API 文档

服务端,顾名思义就是在服务端调用,这里其实指的就是在云函数中调用。

在云函数中调用,需要借助 wx-server-sdk npm 包,毕竟云函数也是运行在**非小程序官方(腾讯云)**的第三方 Node 服务下,它初始化的方式有一些不同,至少要引入 wx-server-sdk,示例代码如下:

const cloud = require('wx-server-sdk')
cloud.init()
exports.main = async (event) => {
  const { ENV, OPENID, APPID } = cloud.getWXContext()
  // 更新默认配置,将默认访问环境设为当前云函数所在环境
  cloud.updateConfig({
    env: ENV
  })
  // ...
  return {
    ENV,
    OPENID,
    APPID,
  }
}

从这段代码,可以看出它有一些天然的优势,也就是小程序官方宣称的那样:

开发者可以在云函数内使用 wx-server-sdk 提供的 getWXContext 方法获取到每次调用的上下文(appid、openid 等),无需维护复杂的鉴权机制,即可获取天然可信任的用户登录态(openid)。

除了这个,从文档中看出,还有一些特殊的开放能力,例如:getVoIPSign 获取实时语音签名。

HTTP API 文档

HTTP API,顾名思义是使用 HTTP 来调用。换句话说,就是第三方服务通过 https 请求的方式调用。

这块的 API 应该都是早期 H5 产品使用的,那会还没有小程序。每一个 API 就是一个 https 协议的 URL,例如云函数的调用:

POST https://api.weixin.qq.com/tcb/invokecloudfunction?access_token=ACCESS_TOKEN&env=ENV&name=FUNCTION_NAME

通过 POST 方法,请求后面的 URL 就可以了。这种方式都要首先获取授权,也就是 access_token,这个相对云函数来说,确实要麻烦不少。现在做小程序的开发,应该很少使用这种调用方式了。

还有另外一种情况,假如我的小程序配合有一个后台管理系统,而这个后台管理系统是使用 Java 语言开发的,那么,就需要使用「HTTP API」了。例如,提供商城小程序的有赞,以及知识付费小程序的小鹅通,它们在给商家提供小程序,都会配有后台管理系统,其后台管理系统的开发,就避免不了要使用这种调用方式。

对于小团队或是个人开发者,直接使用云函数开发就可以了,「HTTP API 文档」可以忽略不看。

总结

讲了这么多,应该大概知道,云开发文档为什么要整成三份了吧。如果我再把文档目录这样给你对比一下,是不是更加清晰了呢?

可以看出,「服务端 API 文档」多出来的部分,就是它的独特优势。看到这里,你大概知道自己是哪种开发场景了,知道去哪个部分查看文档了。

问题来了:开发过程中,你会发现,很多功能的实现,即可以在小程序端调用,又可以在云函数中调用,到底该怎么选择?

嗯,这是个问题。我的建议是:尽量在小程序端调用。如何尽量?具体问题具体分析;为什么?因为毕竟少一次调用就能获得结果,谁又愿意整到云函数上呢。

更多文章:https://github.com/pengloo53/miniprogram-articles

最后一次编辑于  09-13  
点赞 1
收藏
评论

2 个评论

  • shuffle
    shuffle
    10-22

    问个问题,我不想在小程序端调用,就像在服务端调用。 看了服务端API文档,是写在哪里?写在云函数js里?那怎么调用,还要再再逻辑层调用? 还是有点糊涂,能单独针对  服务端API文档  举个完整的案例吗?

    10-22
    赞同
    回复 3
  • 米布吉斯
    米布吉斯
    09-13

    你好,我想请问个有点幼稚的问题。。我的小程序使用云开发,没有搭建服务器,但现在调用腾讯OCR识别接口的时候,发现必须向该接口传入access_token(文档上显示该值不能通过云函数获得),这是不是说明我仍需要搭建服务器呢?或者在云函数中能通过某种方式得到吗?可否指点一二。。谢谢!

    09-13
    赞同
    回复 2
    • 鲁鹏
      鲁鹏
      09-13

      access_token 是针对 HTTP API 的,OCR 是支持云函数直接调用的,在云函数中通过 wx-server-sdk,有对应的 API 可以使用。


      09-13
      回复
    • 米布吉斯
      米布吉斯
      09-13回复鲁鹏
      好的,非常感谢,我再学习学习,中秋快乐~
      09-13
      回复