Skip to content

Latest commit

 

History

History
284 lines (189 loc) · 11.8 KB

API.md

File metadata and controls

284 lines (189 loc) · 11.8 KB

LeanEngine Node SDK

在 express 应用中使用：

var app = require('express')();
var AV = require('leanengine');

AV.init({
  appId: process.env.LEANCLOUD_APP_ID,
  appKey: process.env.LEANCLOUD_APP_KEY,
  masterKey: process.env.LEANCLOUD_APP_MASTER_KEY
  hookKey: process.env.LEANCLOUD_APP_HOOK_KEY
});

app.use(AV.express());

app.listen(process.env.LEANCLOUD_APP_PORT);

路由框架

目前 Node SDK 支持 express、koa、koa2 三种路由框架，可以通过下面的 3 种方法创建中间件并挂载到你的路由框架上：

AV.express(options?: object)
AV.koa(options?: object)
AV.koa2(options?: object)

options 的属性包括：

  • onError?: function(err: Error)：全局错误处理器，当云函数和 Hook 抛出异常时会调用该回调，可用于统一的错误报告。
  • ignoreInvalidSessionToken?: boolean：忽略客户端发来的错误的 sessionToken（X-LC-Session 头），而不是抛出 401 错误 {"code": 211, "error": "Verify sessionToken failed, maybe login expired: ..."}。

AV.Object

  • AV.Object#disableBeforeHook()
  • AV.Object#disableAfterHook()

LeanEngine SDK 为 AVObject 提供了这两个方法来防止死循环，当在一个 AVObject 实例上调用了这个方法，就不会触发对应的 Hook（需要 masterKey 权限）。详见文档：云函数开发指南：防止死循环调用。

AV.Cloud

AV.Cloud.define

AV.Cloud.define(name: string, func: function)
AV.Cloud.define(name: string, options: object, func: function)

定义云函数有两种签名，其中 options 是一个可选的参数，func 是接受一个 Request 对象作为参数，返回 Promise 的函数，Promise 的值即为云函数的响应。在 Promise 中可以抛出使用 AV.Cloud.Error 构造的异常表示客户端错误，如参数不合法；如果抛出其他类型的异常则视作服务器端错误，会打印错误到标准输出。

options 的属性包括：

  • fetchUser: boolean：是否自动抓取客户端的用户信息，默认为 true，若设置为 false 则 request 上将不会有 user 属性。
  • internal: boolean：只允许在云引擎内（使用 AV.Cloud.run 且未开启 remote 选项）或 masterKey 调用（使用 AV.Cloud.run 时传入 useMasterKey），不允许客户端直接调用，默认 false。

Request 上的属性包括：

  • params: object：客户端发送的参数，当使用 rpc 调用时，也可能是 AV.Object.
  • currentUser?: AV.User：客户端所关联的用户（根据客户端发送的 X-LC-Session 头）。
  • user?: AV.User：同 currentUser.
  • meta: {remoteAddress}：meta.remoteAddress 是客户端的 IP.
  • sessionToken?: string：客户端发来的 sessionToken（X-LC-Session 头）。

1.x 兼容模式：在早期版本中，云函数和 before 类的 Hook 是接受两个参数（request 和 response）的，我们会继续兼容这种用法到下一个大版本，希望开发者尽快迁移到 Promise 风格的云函数上。

AV.Cloud.Error

new AV.Cloud.Error(message: string, options?)

继承自 Error，用于在云函数和 Class Hook 中表示客户端错误，其中第二个参数支持：

  • status?: number：设置 HTTP 响应代码（默认 400）
  • code?: number：设置响应正文中的错误代码（默认 1）

AV.Cloud.run

运行已定义的云函数，与 JavaScript SDK 中会发起 HTTP 请求不同，在云引擎中默认变成直接调用指定的函数。

AV.Cloud.run(name: string, params: object, options?: object): Promise

options 的属性包括：

  • user?: AV.User：以特定的用户运行云函数（建议在 remote: false 时使用）。
  • sessionToken?: string：以特定的 sessionToken 调用云函数（建议在 remote: true 时使用）。
  • remote?: boolean：通过网络请求来调用云函数，默认 false.
  • req?: http.ClientRequest 或 Express 的 Request 对象，以便被调用的云函数得到 remoteAddress 等属性。

更多有关云函数的内容请参考文档 云函数开发指南：云函数。

AV.Cloud.rpc

兼容 JavaScript SDK 的同名函数，是 AV.Cloud.run 的一个别名。

AV.Cloud.enqueue

在队列中运行云函数。

AV.Cloud.enqueue(name: string, params: object, options?: object): Promise<{uniqueId: string}>

options 的属性包括：

  • attempts?: number：最大重试次数，默认 1
  • backoff?: number：重试间隔（毫秒），默认 60000（一分钟）
  • delay?: number：延时执行（毫秒）
  • deliveryMode?: string：超时时的行为，值是 atLeastOnce（至少一次，可能会重试多次）、atMostOnce（至多一次，不会重试），默认是 atLeastOnce
  • keepResult?: number 在队列中保留结果的时间（毫秒），默认 300000（五分钟）
  • priority?: number：优先级，默认是当前时间戳，设置为更小的值可以在队列拥堵时让特定任务更快地被执行
  • timeout?: number：超时时间（毫秒），默认 15000，目前最大也是 15000，后续会提供更长的时间
  • uniqueId?: string：任务的唯一 ID，会据此进行去重，最长 32 个字符，默认是随机的 UUID

AV.Cloud.getTaskInfo

查询队列任务结果。

AV.Cloud.getTaskInfo(uniqueId: string): Promise<TaskInfo>

TaskInfo 的属性包括：

  • uniqueId: string：任务的唯一 ID
  • status: string：任务的状态，包括 queued（等待或正在执行）、success（执行成功）、failed（执行失败）

执行完成的 TaskInfo 会有：

  • finishedAt?: string 执行完成（成功或失败）的时间
  • statusCode?: number 云函数响应的 HTTP 状态码
  • result?: object 来自云函数的响应

执行失败的 TaskInfo 会有：

  • error?: string 错误提示
  • retryAt?: string 下次重试的时间

定义 Class Hook

  • AV.Cloud.beforeSave
  • AV.Cloud.afterSave
  • AV.Cloud.beforeUpdate
  • AV.Cloud.afterUpdate
  • AV.Cloud.beforeDelete
  • AV.Cloud.afterDelete

这些函数的签名：function(className: string, func: function)，其中 func 是接受一个 Request 对象作为参数，返回 Promise 的函数。在 before 类 Hook 中如果没有抛出异常则视作接受这次操作。如果抛出使用 AV.Cloud.Error 构造的异常表示客户端错误，拒绝本次操作；如果抛出其他类型的异常则视作服务器端错误，返回 500 响应并打印错误到标准输出，也会拒绝本次操作。

Request 上的属性包括：

  • object: AV.Object：被操作的对象。
  • currentUser?: AV.User：发起操作的用户。
  • user?: AV.User：同 currentUser.

LeanEngine 中间件会为这些 Hook 函数检查「Hook 签名」，确保调用者的确是 LeanCloud 或本地调试时的命令行工具。

更多有关 Hook 函数的内容请参考文档 云函数开发指南：Hook 函数。

登录和认证 Hook

  • AV.Cloud.onVerified
  • AV.Cloud.onLogin

这两个函数的签名：function(func: function)，其中 func 是接受一个 Request 对象作为参数，返回 Promise 的函数，如果没有抛出异常则视作接受这次操作。

Request 上的属性包括：

  • currentUser: AV.User：被操作的用户。
  • user: AV.User：同 currentUser.
  • object: AV.User：同 currentUser，因为登录认证 hook 被操作的对象正好是发起操作的用户。
  • authData: {[provider: string]: any}，客户端发送的第三方登录信息（仅 onAuthData）。

AV.Cloud.onAuthData

这个函数的签名：function(func: function)，其中 func 是接受一个 Request 对象作为参数，返回新的 authData 的异步函数，如果抛出异常会中断第三方登录。

Request 上的属性包括：

  • authData: {[provider: string]: any}，客户端发送的第三方登录信息。

实时通信 Hook 函数

包括：

  • AV.Cloud.onIMMessageReceived
  • AV.Cloud.onIMReceiversOffline
  • AV.Cloud.onIMMessageSent
  • AV.Cloud.onIMMessageUpdate
  • AV.Cloud.onIMConversationStart
  • AV.Cloud.onIMConversationStarted
  • AV.Cloud.onIMConversationAdd
  • AV.Cloud.onIMConversationAdded
  • AV.Cloud.onIMConversationRemove
  • AV.Cloud.onIMConversationRemoved
  • AV.Cloud.onIMConversationUpdate
  • AV.Cloud.onIMClientOnline
  • AV.Cloud.onIMClientOffline
  • AV.Cloud.onIMClientSign

LeanEngine 中间件会为这些 Hook 函数检查「Hook 签名」，确保调用者的确是 LeanCloud 或本地调试时的命令行工具。

这些 Hook 函数签名是 function(func: function)，其中 func 是接受一个 Request 对象作为参数，返回 Promise 的函数，详见文档 实时通信概览：云引擎 Hook

启动和停止

单独运行云函数时，可以使用 AV.Cloud.start() 启动应用。如果该方法调用时 AV 对象尚未初始化，则 LeanEngine 中间件会使用 LEANCLOUD_APP_ID 等环境变量进行初始化。

在需要的时候，可以调用 AV.Cloud.stop() 来停止新链接的创建，但是已有链接不会主动断开。

Middlewares

因为 Node SDK 同时支持多种路由框架，需要你在创建中间件时指定类型，默认为 express：

app.use(AV.Cloud.LeanCloudHeaders({framework: 'express'}));
app.use(AV.Cloud.LeanCloudHeaders({framework: 'koa'}));
app.use(AV.Cloud.LeanCloudHeaders({framework: 'koa2'}));

leancloud-headers

该中间件会将 X-LC 系列的头解析为 request.AV 上的属性，在 Express 中：

app.use(AV.Cloud.LeanCloudHeaders());

express 的 Request（或 koa 的 ctx）上会有这些属性可用：

  • AV.id?：App ID
  • AV.key?：App Key
  • AV.masterKey?：App Master Key
  • AV.prod：0 或 1
  • AV.sessionToken?：Session Token

cookie-session

该中间件提供了在 Express 或 Koa 中维护用户状态的能力，在 Express 中：

app.use(AV.Cloud.CookieSession({secret: 'my secret', maxAge: 3600000, fetchUser: true}));

其他参数包括：

  • secret: string：对 Cookie 进行签名的密钥，请选用一个随机字符串。
  • name?: string：Cookie 名称，默认为 avos.sess。
  • maxAge?: number：Cookie 过期时间。
  • fetchUser?: boolean：是否自动查询用户信息，默认为 false，即不自动查询，这种情况下只能访问用户的 id 和 sessionToken.
  • httpOnly?: boolean: 不允许客户端读写该 Cookie，默认 false.

express 的 Request（或 koa 的 ctx）上会有这些属性可用：

  • currentUser?: AV.User：和当前客户端关联的用户信息（根据 Cookie），如未开启 cookie-session 的 fetchUser 选项则只可以访问 id 和 sessionToken.
  • sessionToken?: string：和当前客户端关联的 sessionToken（根据 Cookie）。

express 的 Response（或 koa 的 ctx）上会有这些属性可用：

  • saveCurrentUser(user: AV.User)：将当前客户端与特定用户关联（会写入 Cookie）。
  • clearCurrentUser()：清除当前客户端关联的用户（删除 Cookie）。

更多有关在 express 维护用户状态的技巧见文档：网站托管开发指南：处理用户登录和登出。

https-redirect

该中间件会自动将 HTTP 请求重定向到 HTTPS 上，在 Express 中：

app.enable('trust proxy');
app.use(AV.Cloud.HttpsRedirect());

Koa 中：

app.proxy = true;
app.use(AV.Cloud.HttpsRedirect({framework: 'koa'}));