leancloud/leanengine-node-sdk

LeanEngine Node.js SDK

LeanEngine Node.js SDK

安装

npm install --save leanengine leancloud-storage@3 --save

建议使用 Node.js 8.0 以上的版本（可在 package.json 中设置 engines.node 为 8.x）。

文档

• 快速入门：https://leancloud.cn/docs/leanengine_quickstart.html
• 网站托管开发指南：https://leancloud.cn/docs/leanengine_webhosting_guide-node.html
• 云函数开发指南：https://leancloud.cn/docs/leanengine_cloudfunction_guide-node.html
• 云引擎命令行工具使用详解：https://leancloud.cn/docs/leanengine_cli.html
• API 参考文档：https://github.com/leancloud/leanengine-node-sdk/blob/master/API.md

项目示例

• 项目模板：https://github.com/leancloud/node-js-getting-started
• Node.js Demo 汇总：https://github.com/leancloud/leanengine-nodejs-demos
• 微信公众平台：https://leancloud.cn/docs/webhosting_weixin.html
• 微博 OAuth 授权验证：https://leancloud.cn/docs/webhosting_oauth.html

历史版本

见 Releases

• npm install leanengine@2 --save 升级说明见 v3.0.0
• npm install leanengine@1 --save 升级说明见 v2.0.0
• npm install leanengine@0 --save 升级说明见 升级到云引擎 Node.js SDK 1.0

若有意参与开发请看 CONTRIBUTING.md。

leanengine-node-sdk's Issues

beforeUpdate 支持用户指定允许更新的字段

经过和晓丹的讨论 https://github.com/leancloud/uluru-platform/issues/2101 ，beforeUpdate 中支持：

res.success(['a', 'b']); // 允许更新 a, b 两列
res.success(); // 兼容原有写法，等价于 res.success(req.object.updatedKeys);

然后 Node SDK 向云存储返回一个数组结果表示允许更新的列，旧版本会返回 req.object.

beforeSave hook导致object内容错误

在数据库中，有beforeSave hook的新创建的User是这样的：

{
  "result": {
    "email": "xxxxxxxx",
    "username": "xxxx",
    "emailVerified": false,
    "__before": 1432921032633,
    "mobilePhoneVerified": false,
    "somecustomattr": "somevalue"
  },
  "ACL": {
    "*": {
      "write": true,
      "read": true
    }
  },
  "objectId": "5568a3c8e4b0a9a97408bfbe",
  "createdAt": "2015-05-30T01:37:12.676Z",
  "updatedAt": "2015-05-30T01:37:12.676Z"
}

回滚LeanEngine SDK 仍然 出现此问题。

回滚到CloudCode 2.0版本，没有 出现此问题。

使用在线定义函数，没有 问题。

猜测是由于beforeSave返回的数据格式不对，不应该带有{"result": data}.

在leanengine/lib/leanengine.js中:

beforeSave hook中将obj返回给callback：

324       Cloud.__code[hook + className]({
325         user: user,
326         object: obj
327       }, {
328         success: function() {
329           if ('__before_delete_for_' === hook) {
330             return cb(null, {});
331           } else {
332             return cb(null, obj);
333           }
334         },
335         error: function(err) {
336           cb(new Error(err));
337         }
338       });

这个callback在此定义：

196       var cb = function(err, data) {
197         if (err) {
198           return respError(res, err);
199         }
200         return resp(res, data);
201       };

resp返回{"result": data}，将刚创建的object给返回了

247 var resp = function(res, data) {
248   res.setHeader('Content-Type', 'application/json; charset=UTF-8');
249   res.statusCode = 200;
250   return res.end(JSON.stringify({"result": data}));
251 };

Please use AV._config.APIServerURL to replace AV.serverURL

[bug] 应该在登录时处理异常的请求

https://github.com/leancloud/leanengine-node-sdk/blob/master/lib/avosExpressCookieSession/index.js#L73

如果用户的 cookie 已经失效（比如在服务端用户被删掉/更换了 secret key），
av.Cloud.logInByIdAndSessionToken 无法正确返回，而这里也未做任何异常处理，导致用户直接拿到 500（应该清除 cookie）。

通过 stg- 开头的域名请云函数时访问预备环境

https://forum.leancloud.cn/t/leancloud-app-env/8160/4

高并发跳号问题

leanengine-node-sdk/lib/av-extra.js

AV.User._saveCurrentUser = function(user) {
  debug('_saveCurrentUser %s', user.get('username'));
  if (process.domain) {
    if (process.domain._currentUser === user) {
      return;
    }
    if (process.domain._currentUser) {
      AV.User.logOut();
    }
    if (user) {
      user._isCurrentUser = true;
    }
    process.domain._currentUser = user;
    return;
  }
  throw new Error('请添加 AV.Cloud.CookieSession 中间件以支持 AV.User 的操作。');
};

先设置了_isCurrentUser在高并发情况下会导致串号

AV.User._saveCurrentUser = function(user) {
  debug('_saveCurrentUser %s', user.get('username'));
  if (process.domain) {
    if (process.domain._currentUser === user) {
      return;
    }
    if (process.domain._currentUser) {
      AV.User.logOut();
    }
    if (user) {
      process.domain._currentUser = user;
      user._isCurrentUser = true;
    }  
    return;
  }
  throw new Error('请添加 AV.Cloud.CookieSession 中间件以支持 AV.User 的操作。');
};

对实例异常退出的情况增加告警邮件

来源：https://forum.leancloud.cn/t/topic/14171

用户表示：要不然我们都不知道，是在上线新版本时才发现这个问题，吓出一身冷汗。

Hook 回调不支持 File 类型

leanengine-node-sdk/lib/leanengine.js

Line 270 in 4bfec51

switch (className) {

hook 回调中的 request.object 没有正确处理 _File 类型。所以 url() 等 api 不可用。

https://forum.leancloud.cn/t/topic/2973

使用 koa-connect 转换后，/engine/ping 响应 404 的状态码

似乎不显式 200 就会被 koa 认为是 404 ...

请遵守Node的Callback返回模式，用 (err, data) 参数返回Callback！

RT

hook 被非法调用时，会抛出 attrs.sessionToken 异常

https://leanticket.cn/t/leancloud/1706?show=all

本地环境下可以正常使用superAgent向豆瓣网发起请求，部署后无法获取主页，会变为403

superAgent
.get(bookUrl)
.set({
Referer: "http://book.douban.com/",
'User-Agent': 'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:39.0) Gecko/20100101 Firefox/39.0'
}).end(function (err, res) {
console.log('begin parsing',err);
})
在部署到实例后会获得403错误的页面

leanengine 里 hack 的 avoscloud-sdk 方法实现不一样

https://github.com/leancloud/leanengine-node-sdk/blob/master/lib/leanengine.js#L266

Cloud.run = function(name, data, options) {
  try {
    Cloud.__code[name]({params: data, user: AV.User.current()}, options );
  } catch (err) {
    console.log('Run function \'' + name + '\' failed with error:', err);
    options.error(err);
  }
};

这里返回的是 promise
https://github.com/leancloud/javascript-sdk/blob/master/lib/cloudfunction.js#L28

    run: function(name, data, options) {
      var request = AV._request("functions", name, null, 'POST',
                                   AV._encode(data, null, true));

      return request.then(function(resp) {
        return AV._decode(null, resp).result;
      })._thenRunCallbacks(options);
    },

导致我迁移后的代码都不能用了

Usage with koa?

koa needs a generator function.So I couldn't make it works like the example:

// cloud.js
var AV = require('leanengine');
AV.Cloud.define('hello', function(request, response) {
  response.success('Hello world!');
});
module.exports = AV.Cloud;

var koa = require("koa");
var cloud = require('./cloud');
var app = koa();
app.use(cloud);

module.exports = app

It throw an error:AssertionError: app.use() requires a generator function.

云函数提供 Promise 支持

之前曾在 https://github.com/leancloud/cloud-code/issues/756 讨论过，结论是因为 Promise 只能够表示「成功」和「不成功」两种状态，而我们的云函数实际上有「成功」、「失败」、「出现异常」三种情况。

目前云函数会用 domain 捕捉异步的异常，但因为 domian 本身的不确定性，在之后的 Node 版本中不好保证一定有效。@leeyeh 提议支持用 Promise 去表示「出现异常」的情况，即也去捕捉通过 Promise 传递出的异常，保持和同步异常一样的处理方式。

「未捕获异常处理器」的相关文档

将这部分文档说明补充到 云引擎指南 的文档，说明下这个东西的意义和相关代码。

不是所有的 request 参数都有 meta 信息

从代码看，目前只有「自定义函数」与所有「after」类型的 hook 的 request 参数带有 meta 信息。

调用本地云函数，返回的 Promise 一直处于 pending 状态

「未捕获异常处理器」更改实现

Node.js 4.0 已经不推荐使用 domain 模块，所以我们未处理异常的处理方式要修改了。可能还是要使用 https://nodejs.org/api/process.html#process_event_uncaughtexception ，顺便看下 https://nodejs.org/api/process.html#process_event_unhandledrejection ，关于 promise 未处理异常的处理。

TypeScript Declaration File

有关实现不依赖 domain 的用户状态管理的几种方案

每次操作都需要传 sessionToken 参数

var Topic = AV.Object.extend('Topic');

AV.Cloud.define('func', function(request, response) {
  var query = new AV.Query(Topic);
  query.find({
    sessionToken: request.user._sessionToken,
    success: function(results) {
      response.success(results);
    }
  })
});

实现简单、容易理解；但用户需要修改现有代码，很容易遗漏某些地方，需要在函数间传递 user.

为每个请求提供一个 AV 实例

AV.Cloud.define('func', function(request, response) {
  var Topic = request.AV.Object.extend('Topic');
  var query = new AV.Query(Topic);
  query.find({
    success: function(results) {
      response.success(results);
    }
  })
});

可以通过改写 AV._request 来实现，用户需要修改一部分代码，也需要在函数间传递 AV.

[bug] 在云函数中使用 include 后查询的结果会丢失

例如

query = new AV.Query(Post)
query.include('comment').find().then(function(post){
  res.sucess(post)
})

前端接受到的 post 的 comment 字段会丢失

向普通 Express 路由提供 parse authInfo 和 authorization 的支持

有用户希望在普通 Express 路由中使用这两个中间件（

leanengine-node-sdk/lib/leanengine.js

Lines 85 to 181 in 5d9532e

	// parse authInfo
	Cloud.use(route, function(req, res, next) {
	var appId, appKey, masterKey, contentType, param, prod, prodHeader, prodValue, sessionToken;
	contentType = req.headers['content-type'];
	if (/^text\/plain.*/i.test(contentType)) {
	if (req.body && req.body !== '') {
	req.body = JSON.parse(req.body);
	}
	appId = req.body._ApplicationId;
	appKey = req.body._ApplicationKey;
	masterKey = req.body._MasterKey;
	prodValue = req.body._ApplicationProduction;
	sessionToken = req.body._SessionToken;
	for (param in req.body) {
	if (param.charAt(0) === '_') {
	delete req.body[param];
	}
	}
	prod = 1;
	if (prodValue === 0 || prodValue === false) {
	prod = 0;
	}
	req.AV = {
	id: appId,
	key: appKey,
	masterKey: masterKey,
	prod: prod,
	sessionToken: sessionToken
	};
	} else {
	appId = req.headers['x-lc-id'] ||
	req.headers['x-avoscloud-application-id'] ||
	req.headers['x-uluru-application-id'];
	appKey = req.headers['x-lc-key'] ||
	req.headers['x-avoscloud-application-key'] ||
	req.headers['x-uluru-application-key'];
	masterKey = req.headers['x-avoscloud-master-key'] || req.headers['x-uluru-master-key'];
	prodHeader = req.headers['x-lc-prod'] ||
	req.headers['x-avoscloud-application-production'] ||
	req.headers['x-uluru-application-production'];
	sessionToken = req.headers['x-lc-session'] ||
	req.headers['x-uluru-session-token'] ||
	req.headers['x-avoscloud-session-token'];
	prod = 1;
	if (prodHeader === '0' || prodHeader === 'false') {
	prod = 0;
	}
	if (appKey && (appKey.indexOf(',master') > 0)) {
	masterKey = appKey.slice(0, appKey.indexOf(','));
	appKey = null;
	}
	req.AV = {
	id: appId,
	key: appKey,
	masterKey: masterKey,
	prod: prod,
	sessionToken: sessionToken
	};
	}
	return next();
	});
	// authorization
	Cloud.use(route, function(req, res, next) {
	var key, master, requestSign, sign, timestamp, validSign, _ref;
	if (!req.AV.id) {
	return unauthResp(res);
	}
	if (AV.applicationId === req.AV.id &&
	(AV.applicationKey === req.AV.key ||
	AV.masterKey === req.AV.key ||
	AV.masterKey === req.AV.masterKey)) {
	if (AV.masterKey === req.AV.masterKey) {
	req.AV.authMasterKey = true;
	}
	return next();
	}
	requestSign = req.headers['x-lc-sign'] || req.headers['x-avoscloud-request-sign'];
	if (requestSign) {
	_ref = requestSign.split(',');
	sign = _ref[0];
	timestamp = _ref[1];
	master = _ref[2];
	key = master === 'master' ? AV.masterKey : AV.applicationKey;
	validSign = signByKey(timestamp, key);
	if (validSign === sign.toLowerCase()) {
	if (master === 'master') {
	req.AV.authMasterKey = true;
	req.AV.masterKey = key;
	} else {
	req.AV.key = key;
	}
	return next();
	}
	}
	return unauthResp(res);
	});

），可以考虑将 leanengine.js 中主要的中间件都拆分到单独的文件，以便用户可以自行使用。

我们的 Bug 给用户清晰的「请升级 SDK」提示

https://forum.leancloud.cn/t/hook/14512

这个问题， @jysperm 说是：2.0 和命令行工具配合的一个 Bug，升级到最新版可解。

既然界定为我们的锅的 bug，能否主动在云引擎日志里告知用户升级 SDK。 @aisk @sdjcw 大佬们来出出主意。

avos-express-https-redirect 中间件不支持 leanapp.cn

向文档补充打开请求日志的方法

我看到 JavaScript SDK 最新的代码已经会用 debug 模块记录每个请求的参数和响应了，可以在文档上补充一个段落告诉用户如何打开（加环境变量）。

https://github.com/leancloud/javascript-sdk/blob/master/src/request.js

支持async await 吗？

用leancloud存储功能查询后能不能不返回promise，我想用async await 来处理

无法正常使用七牛pili的部分api

相关 ticket：https://ticket.leancloud.cn/tickets/8461

提供 API 文档。

向 res.saveCurrentUser 传入没有 sessionToken 的用户时需要向用户发出警告

https://leanticket.cn/t/leancloud/2134

如果没有 sessionToken，写入的 Cookie 是无法起作用的，可以考虑：抛出异常、打印警告、自动根据 id 获取 sessionToken.

自动测试不可靠

https://travis-ci.org/leancloud/leanengine-node-sdk/builds

cookie-session 中向 req 添加了 sessionCookies、sessionOptions、sessionKey 属性

https://github.com/leancloud/leanengine-node-sdk/blob/0.4.0/lib/avosExpressCookieSession/index.js#L39-L43

但似乎这三个属性并没有被用到，却会增加和其他 session 中间件冲突的风险。

支持 beforeUpdate

类似 beforeSave，约定保持一致，只是名字换了

@sdjcw

今天凌晨上线。

beforeSave 的 request.object 是将更新作用到当前对象后的临时新对象，它不保证是对象更新后的状态，而只是“当时”的最新状态。

本地 avoscloud 调试工具无法测试 call

这里是发出 /functions 的请求。

@jysperm @sdjcw

查询条件notContainedIn不支持objecId字段了

query.notContainedIn('objectId', [array])会错误，而且错误都是undefined

Variable 'masterKey' implicitly declared.

Codacy detected an issue:

Message: Variable 'masterKey' implicitly declared.

Occurred on:

• Commit: 8166b13
• File: lib/leanengine-sdk.js
• LineNum: 86
• Code: masterKey = req.body._MasterKey;

Currently on:

• Commit: 26a7432
• File: lib/leanengine.js
• LineNum: 94

koa 发起save请求 提示 response: { error: 'Config not found.' }

我想知道这个配置文件是什么 我在函数初始化时候已经传入了必要参数

除了模块依赖之外。
的代码
//init leanCloud
lg.init({
    appId: process.env.LEANCLOUD_APP_ID || 'GcEEi4mef5f6LjXb....省略',
    appKey: process.env.LEANCLOUD_APP_KEY || 'PI2khm4E6....省略',
    masterKey: process.env.LEANCLOUD_APP_MASTER_KEY || '1EXlsv8....省略'
});
lg.Cloud.useMasterKey();

// 声明一个 Todo 类型
var Todo = lg.Object.extend('Todo');
// 新建一个 Todo 对象
var todo = new Todo();
todo.set('title', '工程师周会');
todo.set('content', '每周工程师会议，周一下午2点');
todo.save().then(function(todo) {
    // 成功保存之后，执行其他逻辑.
    console.log('New object created with objectId: ' + todo.id);
}, function(error) {
    // 异常处理
    console.error(error);
});

请说明环境基本运行情况

比如：入口文件、启动顺序、安装了哪些到哪个目录？这些隐含的步骤

指定 avoscloud-sdk 为 peerDependency

由用户自己安装维护 avoscloud-sdk 的版本，避免出现现在 sdk 会自动升级的问题。

leanengine-sdk 本身不再持有 AV，需要用户初始化传进来：

var AV = require('leanengine')(require('avoscloud-sdk'));

检查将 Node SDK 作为客户端使用时的 currentUser

#106 (review)

考虑让 JS SDK 版本用户可自定

AV.Cloud.run 本地调用云函数时 request 上缺少 currentUser 等属性

https://leanticket.cn/t/leancloud/2057

统计调用存储服务的请求

记录包括：请求次数，响应时间，响应码等信息。

分为 5 秒钟的实时信息和 5 分钟的持久化信息。

梳理调用 response.error 时指定 code 的逻辑并补充文档

因为 JS SDK 取消了 AV.Error：

AV.Error() is deprecated, and will be removed in next release.

很多用户会疑惑应该如何在 response.error 时指定 code，目前的替代方案是（注意是 message 而不是 error）：

response.error({"code":"4444","message":"请先登录!"})

可能需要改进一下这个 API（例如将 code 作为第二个参数）并补充到文档上。

支持 koa2

增加本地调试 Cloud 函数的功能

类似命令行工具之前的 localhost:3000/avos 页面。

使用 node 0.12 + 后，V8 自带的 Promise 处理异步时会丢失 process.domain，导致用户登录信息丢失

如题，建议更改目前用户登录的设计。

process.domain在未来会被废弃，其他会导致 process.domain 丢失的情况暂不明确

Class Hook 现在会限制对象的大小不能超过 100k

leanengine.js 中 Cloud.use(route, bodyParser.json()); 使用了 limit 的默认值 100k.

有用户遇到了这个问题： https://forum.leancloud.cn/t/string/5881

Node SDK 2.0 计划

主要是为了在更新 JavaScript SDK 2.0 的时候顺便做一些不兼容的修改，尽量能够在一个月内发布：

• 更新 JavaScript SDK 2.0（不兼容，小程序相关支持）
• 移除 AV.Cloud.httpRequest（不兼容）
• 云函数 Promise 支持、移除 domain、onError（少量不兼容） #90 #67 #96
• 向 res.saveCurrentUser 传入没有 sessionToken 的用户时需要向用户发出警告（细微不兼容） #80
• 不正确的云函数名称、重复的云函数抛异常（细微不兼容）

还有一些不太可能引起不兼容的修改，可以做也可以往后放一放：

• beforeUpdate 支持用户指定允许更新的字段（细微不兼容） #59
• 提供一个根据 Header 中的 sessionToken 获取用户的中间件，主要是为了对微信小程序提供支持 https://forum.leancloud.cn/t/leancloud/11434
• koa2 支持（可能有细微不兼容）
• 新的 Hook Key 重构（可能有细微不兼容） https://github.com/leancloud/uluru-platform/issues/2384
• TypeScript 定义文件 #98
• 包装 _messageReceived 等实时通讯 hook

添加一个 AV.Cloud.onError 的方法来监听云函数的错误以便用户实现自己的错误处理逻辑

AV.Cloud.run 支持 Promise 方式调用