Node.js 函数入口

在函数计算服务使用 Node.js 编程，需要定义一个 Node.js 函数作为入口。Node.js 运行环境根据是否支持 HTTP 触发器分为 普通函数入口 和 设置 HTTP 触发器 两种函数入口，为函数设置 HTTP 触发器后的函数入口形式会不同，这是为了方便处理发来的 HTTP request 请求。其中 普通函数入口 又分为 处理函数入口 和 initializer 入口。

本文对 Node.js 的函数入口进行详细介绍：

• 普通函数入口
  • 处理函数入口
  • initializer 入口
• 设置 HTTP 触发器的函数入口

普通函数入口

处理函数入口

一个最简单的函数定义如下：

exports.handler = function(event, context, callback) {
  callback(null, 'hello world');
};

函数名

• exports.handler 需要与创建函数时的 “handler” 字段相对应：例如创建函数时指定的 handler 为index.handler，那么函数计算会去加载 index.js 文件中定义的 handler 函数。

event 参数

• event 参数是您调用函数时传入的数据，其类型是 Buffer，是函数的输入参数。
• 函数不对它的内容进行任何解释，传递给函数的 event 是 Buffer 类型。您在函数中可以根据实际情况对 event 进行转换：例如输入数据是一个 JSON string ，您可以把它转换成一个 object :例如：传入的 event :

  {
  "key": "value"
  }

  函数代码：

  exports.handler = function(event, context, callback) {
  var eventObj = JSON.parse(event.toString());
  callback(null, eventObj['key']);
  };

  返回结果为 value 。

context 参数

• context 参数中包含一些函数的运行时信息（例如 request id / 临时 AK 等）。您在代码中可以使用这些信息。其类型是 object
• 其定义如下：

{
  'requestId': 'b1c5100f-819d-c421-3a5e-7782a27d8a33',
  'credentials': {
    'accessKeyId': 'STS.access_key_id',
    'accessKeySecret': 'access_key_secret',
    'securityToken': 'security_token',
  },
  'function': {
    'name': 'my-func',
    'handler': 'index.handler',
    'memory': 128,
    'timeout': 10,
    'initializer': 'index.initializer',
    'initializationTimeout': 10,
  },
  'service': {
     'name': 'my-service',
     'logProject': 'my-log-project',
     'logStore': 'my-log-store',
     'qualifier': 'qualifier',
     'versionId': '1'
  },
  'region': 'cn-shanghai',
  'accountId': '123456'
}

可以看到 context 中包含了 6 个信息：

• requestId: 本次调用请求的唯一 id，您可以把它记录下来在出现问题的时候方便调查。
• function: 当前调用的函数的一些基本信息如函数名 / 函数入口 / 函数内存 / 超时时间。
• credentials: 函数计算服务通过扮演您提供的 服务角色 获得的一组临时密钥，其有效时间是 6 小时。您可以在代码中使用它去访问相应的服务（ 例如 OSS ），这就避免了您把自己的 AK 信息写死在函数代码里。
• service: 当前调用的函数所在的 service 的信息，包括 service 的名字，接入的 SLS 的 logProject 和 logStore 信息，service的版本信息qualifier和version_id，qualifier表示调用函数时指定的service版本或别名，version_id表示实际调用的service版本。
• region: 当前调用的函数所在区域，如 cn-shanghai。
• accountId: 当前调用函数用户的阿里云 account id。

下面的代码使用临时密钥，向 OSS 中上传了一个文件：

var OSSClient = require('ali-oss').Wrapper;
exports.handler = function (event, context, callback) {
    console.log(event.toString());
    var ossClient = new OSSClient({
        accessKeyId: context.credentials.accessKeyId,
        accessKeySecret: context.credentials.accessKeySecret,
        stsToken: context.credentials.securityToken,
        region: 'oss-cn-shanghai',
        bucket: 'my-bucket',
    });
    ossClient.put('my-object', new Buffer('hello, fc')).then(function (res) {
        callback(null, 'put object');
    }).catch(function (err) {
        callback(err);
    });
};

注意：使用临时密钥访问 OSS 时一定要带上第三个参数 securityToken。

callback 参数

• callback 参数用于返回调用函数的结果，其签名是 function(err, data)，与 Node.js 中惯用的 callback 一样，它的第一个参数是 error ，第二个参数 data 。如果调用时 err 不为空，则函数将返回 HandledInvocationError ，否则将返回 data 的内容。如果 data 是 Buffer 类型则它的数据将直接被返回，如果 data 是 object ，则会将其转换成 JSON 字符串返回，其他类型将被转换成 string 返回。

initializer 入口

一个最简单的 initializer 函数定义如下：

exports.my_initializer = function(context, callback) {
    console.log('hello world');
    callback(null, "");
};

initializer 函数名

• my_initializer 需要与添加初始化函数时的 “initializer” 字段相对应：例如创建函数时指定的 initializer 为 main.my_initializer，那么函数计算在配置初始化函数后首先会去加载 main.js 中定义的 my_initializer 函数。

initializer 特点

• initializer 输入参数有 context 和 callback 两个，具体含义和上文描述的处理函数中相关参数的含义是一致的。
• context 中 initializer 和 initializationTimeout 两个信息是为 initializer 设计的，当使用 initializer 功能时，会被设置为用户创建函数时所设置的值，否则为空，且不生效。

更多细节请参考 initializer 入口定义。

设置 HTTP 触发器的函数入口

注意：设置了 HTTP 触发器的函数入口与普通函数的入口不同

function(request, response, context)

其中的 context 参数与普通函数接口的 context 接口相同。

Request 结构体

• headers：map 类型，存放来自 HTTP 客户端的键值对。
• path：string 类型，为 HTTP URL。
• queries：map 类型，存放来自 HTTP URL 中的 query 部分的 key - value 键值对, value 的类型可以为字符串或是数组。
• method：string 类型，HTTP 方法。
• clientIP：string 类型，client 的 IP 地址。
• url：string 类型，request 的 url。

获取 HTTP body：HTTP 触发器中的 request 兼容 HTTP request，没有提供额外的 body 字段，直接使用 HTTP request 获取 body。

// 详见示例
var getRawBody = require('raw-body')
getRawBody(request, function(err, data){
      var body = data
})

说明：Headers key 中包含以下字段会被忽略掉，因为 FC 默认会带以下字段，不支持用户自定义。同时以 x-fc- 开头的 key 也会被忽略掉。

• accept-encoding
• connection
• keep-alive
• proxy-authorization
• te
• trailer
• transfer-encoding

Response 提供的方法

• response.setStatusCode(statusCode) ： 设置 status code
  • param statusCode : (required, type integer)
• response.setHeader(headerKey, headerValue) ：设置 header
  • paramheaderKey : (required, type string)
  • paramheaderValue : (required, type string)
• response.deleteHeader(headerKey) ：删除 header
  • paramheaderKey: (required, type string)
• response.send(body): 发送 body
  • parambody: (required, typeBuffer or a string or a stream.Readable )

说明：Headers key 中包含以下字段会被忽略掉，因为 FC 默认会带以下字段，不支持用户自定义。同时以 x-fc- 开头的 key 也会被忽略掉。

• connection
• content-length
• content-encoding
• date
• keep-alive
• proxy-authenticate
• server
• trailer
• transfer-encoding
• upgrade

限制项

Request 限制项

如果超过以下限制，会抛出 400 状态码和 InvalidArgument 错误码

• headers 的大小：headers 中的所有 key 和 value 的大小不得超过 4 KB。
• path 大小：包括各个 query params，path 的大小不得超过 4 KB。
• body 大小：HTTP body 的大小不得超过 6 MB。

Response 限制项

如果超过以下限制，会抛出 502 状态码和 BadResponse 错误码。

• headers 的大小：headers 中的所有 key 和 value 的大小不得超过 4 KB。
• body 大小：HTTP body 的大小不得超过 6 MB。

示例

示例代码中展示了如何在函数中获取 request 详细信息。

var getRawBody = require('raw-body')
module.exports.handler = function (request, response, context) {
    // get requset header
    var reqHeader = request.headers
    var headerStr = ' '
    for (var key in reqHeader) {
        headerStr += key + ':' + reqHeader[key] + '  '
    };
    // get request info
    var url = request.url
    var path = request.path
    var queries = request.queries
    var queryStr = ''
    for (var param in queries) {
        queryStr += param + "=" + queries[param] + '  '
    };
    var method = request.method
    var clientIP = request.clientIP
    // get request body
    getRawBody(request, function (err, data) {
        var body = data
        // you can deal with your own logic here
        // set response
        // var respBody = new Buffer('requestURI' + requestURI + ' path' + path +  ' method' + method + ' clientIP' + clientIP)
        var respBody = new Buffer('requestHeader:' + headerStr + '\n' + 'url: ' + url + '\n' + 'path: ' + path + '\n' + 'queries: ' + queryStr + '\n' + 'method: ' + method + '\n' + 'clientIP: ' + clientIP + '\n' + 'body: ' + body + '\n')
        // var respBody = new Buffer( )
        response.setStatusCode(200)
        response.setHeader('content-type', 'application/json')
        response.send(respBody)
    })
};

有关 Node.js 运行环境的详细信息，请参考文章 Node.js 运行环境。

您在使用中遇到任何问题，请 联系我们。