跳至主要內容

Func Stateless 开发指南

Func Stateless 开发指南

完整示例代码：代码仓库

开发指南

环境配置

Node.js 环境配置与云函数开发脚手架 usf-cli

在启用 Func Stateless 应用时，您需要选择相应的脚本语言运行环境（参见 示例教程 ）。如果您在开发云函数过程中有本地调试的需求，可以前往 Node.js 历史版本 下载相应版本的Node.js；或者直接通过 brew 进行安装，例如：

brew install node@18.15

配置完 Node.js 环境后，您可以通过 npm 指令安装的云函数开发脚手架 usf-cli，用于快速创建项目和本地调试函数：

npm install -g usf-cli

您可以通过查看 usf-cli 的版本来确认安装成功与否：

usf-cli -v

创建项目与函数形态

首先您需要为您的云函数项目创建一个工作区文件夹，并在文件夹中进行项目的初始化：

# 创建项目路径
mkdir <工作区名称>
cd <工作区名称>
# 初始化项目
usf-cli -i
# 或者使用 npm 进行初始化
npm init

在创建并且初始化工作区文件夹之后，即可根据业务需求创建各个云函数各自的文件夹和函数入口（参考 代码示例）。建议采用 usf-cli 来快速创建云函数：

usf-cli -c --function=<函数名称>

如果需要创建用于连接 UOS CRUD Storage 的云函数，可以参考 CRUD 连接指南

在 index.js 文件中输出一个 main 函数即可作为被 Func Stateless 识别的云函数：

'use strict';

exports.main = async function (event, context) {
    const { httpMethod,headers, body } = event;

    console.log('Http method:', httpMethod);
    console.log('Http headers:', JSON.stringify(headers));
    console.log('Request body', JSON.stringify(body));

    return 'hello world';
};

或者，也可以在 Shell 中手动创建函数文件夹与函数入口：

mkdir <函数名称>
cd <函数名称>
# macOs or Linux
touch index.js
 # Windows
echo >index.js

Func Stateless 支持在一个项目工作区创建多个函数（参考 代码示例）。只需要在工作区文件夹的根目录下为各个函数单独创建文件夹，并在 index.js 文件中输出 main 函数，即可在部署时被 Func Stateless 单独识别。

函数参数

在云函数输出的main函数中添加 event 参数，可以用于接收调用时传递的参，数据，或者调用时的HTTP请求信息：

exports.main = async function (event) {
    console.log("show event detail", event);
};

Func Stateless 会将云函数调用时的相关信息封装成 event 并以参数的形式向函数内部传递。event 的类型为 字典，其中包含了触发函数执行的基本信息（包括 HTTP 请求中的 Method, Header, Body, Params等信息）。函数被触发开始执行后，可以在代码内部对 event 进行处理。

event 示例

输出参数说明

参数名描述类型
httpMethod调用云函数时的HTTP方法（例如：GET, POST, DELETE, PUT等）string
body调用云函数时的消息体(Body)string
headers调用云函数时的消息头(Headers)[Key: string]: string
queryString调用云函数时的参数[Key: string]: string

在实际函数编写过程，可以采用解构的方式来获取调用云函数时的参数等相关信息：

exports.main = async function (event) {
    const body = JSON.parse(event.body);
    const { username, password } = body;
};

函数返回

Func Stateless 支持在云函数中通过 return 来返回函数响应信息，或者通过 throw 来返回错误信息。

// getting params

if (!username || !password) {
    return { msg: 'cannot found username or password' };
}

// process results with valid params
if (result.acknowledged !== true || result.insertedId === undefined) {
    throw new Error('fail to create user');
}

云函数部署

完成函数开发后，即可通过 usf-cli 将云函数部署至 Func Stateless 平台。在部署前，需要先对 UOS App 进行授权：

usf-cli -a --id=4c28a54f-0d1e-4873-996e-0f5b64eac4a9 --secret=10805a62cedd47ed957ce78082b2422a

Func Stateless 支持在上传函数时设置部署时在线安装依赖项，用户可以在部署云函数时指定自动获取依赖项。

# 上传云函数并自动获取依赖项
usf-cli -d --installDependency

此外，也可以在本地安装安装依赖项后一并打包至 Func Stateless 平台：

# 通过 npm 安装依赖项
npm install .
# 将云函数项目协同依赖项 node_modules 一并上传
usf-cli -d

Func Stateless 目前只支持 50MB 以内的项目。因此，函数依赖项过大时，请在上传项目时请指定 installDependency

此外，Func Stateless 也支持用户自行将项目打包成 zip 文件在 Func Stateless 的页面进行上传和自动部署（参见 示例教程 ）。

本地调试

在项目开发过程中，您可以使用云函数脚手架 usf-cli 在本地环境中便捷地进行运行调试：

usf-cli -r --function=<函数名称>

如果您是通过 usf-cli 来创建函数的话，在函数创建时 usf-cli会在项目中以 JSON 的形式为您创建 event 数据，用于本地调试的传参：

 // ./.uos_test/<函数名称>_event.json
{
  "body": "",
  "headerParameters": {},
  "headers": {},
  "httpMethod": "GET",
  "isBase64Encoded": false,
  "pathParameters": {},
  "queryString": {
    "playername": "test"
  },
  "queryStringParameters": {}
}

您可以通过编辑相应的测试文件对函数的传参进行调整：

vim ./.uos_test/<函数名称>_event.json

此外，usf_cli 也支持在调用时指定测试数据的路径：

usf-cli -r --f=helloWorld --e=./.uos_test/<函数名称>_event.json

您可以自行创建 JSON 数据文件来代替默认的测试数据文件用于本地调试时的参数传递，只需要在调用时通过 --e 或 --event 制定该测试数据文件的路径即可。为了与云函数在真实调试环境中的参数传递方式保持一致，请在自行创建测试数据文件时参考上述自动生成的测试文件的参数形式。

云函数调试

Func Stateless 在完成部署之后会为您上传的项目中的每个函数单独分配 URL，然后就可以使用curl、Postman 或任何 HTTP 客户端通过该 URL 对函数进行调试。

自动化部署脚本示例

基于以上开发指南中提供的 usf-cli 和步骤介绍，我们提供了以下自动部署脚本示例，以供开发者们在实际开发过程中应用：

函数配置

成为正式用户后可以对云函数的调用运行属性进行配置，联系我们 进行开通

在完成了函数的开发与部署之后，可以在 Func Stateless 的云函数页面对每个云函数的属性进行单独配置来灵活地应对各种业务需求和调用场景。

请求方法

请求方法，是指当前云函数接受的 HTTP 请求方式。目前 Func Stateless 支持给云函数设置 GET, POST, PUT, DELETE, HEAD, PATCH 等调用方式。倘若未对云函数的调用方式进行配置，那么 默认值为 ANY，即接受上述所有的调用方式。

集成响应

集成响应，是指 Func Stateless 网关会将云函数的返回内容进行解析，并根据解析内容构造 HTTP 响应。通过使用集成响应，可以通过代码自主控制响应的状态码、headers、body 内容，可以实现自定义格式的内容响应，例如响应 XML、HTML、JSON 甚至 JS 内容。在使用集成响应时，函数的返回值需要符合特定的数据结构，才可以 Func Stateless 成功解析。

返回数据结构示例

exports.main = async (event, context) => {
  // process
  // ...
  return {
    "isBase64Encoded":  false,
    "statusCode": 200,
    "headers": {"Content-Type":"text/html"},
    "body": "<html><body><h1>Hello world!</h1><p>hello uos.</p></body></html>",
  }
}

返回数据结构参数说明

参数名描述类型
isBase64Encoded指明 body 内的内容是否为 Base64 编码后的二进制内容boolean
statusCodeHTTP 返回的状态码integer
headersHTTP 返回的头部内容[Key: string]: string
bodyHTTP 返回的 body 内容string

集成响应的 默认值为 FALSE，即默认不启用该功能配置。

Base64 编码

Func Stateless 的云函数不支持直接上传二进制文件，必须经过 Base64 编码后上传。Func Stateless 网关支持将客户端请求体 Base64 编码后传递给云函数。启用 "Base64 编码" 功能后，您无需改造客户端代码即可将二进制文件上传至云函数。默认不启用"Base64 编码" 的功能配置。

CORS 跨域

跨域资源共享（Cross-Origin Resource Sharing，CORS）是 W3C 的标准。CORS 允许 Web 应用进行跨域访问控制，从而使跨域数据传输得以安全进行。目前新上传的云函数会 默认启用CORS 跨域功能配置，以便在平台页面上进行便捷的在线调试。 若未启用 "CORS 跨域"，将无法再 Web应用(包括小程序) 中调用云函数，同时在线调试功能会失效。

执行超时时间

为了避免陷入无限的调用等待时间，云函数执行超过执行超时时间后会被终止（视作调用失败）。执行超时时间 默认为3秒。

环境变量

在函数上传部署后，可以通过增加、编辑环境变量来修改云函数在后续执行过程中获取到的环境变量，从而来应对业务场景的变动。在代码中获取环境变量的代码示例：

在代码中可以通过 process.env 来读取当前运行环境中的变量，可以直接通过环境变量的"变量名"来访问，亦可通过 JS 的解构方式进行获取。

云函数中内置了以下 UOS 相关的环境变量提供开发者使用。

变量名说明示例
UOS_APP_ID云函数对应的 UOS APP 的 ID955c****-****-419a-****-e778****01d9
UOS_APP_SECRET配合 APPID 用于客户端SDK或客户端API集成时使用d77b****fe29****b05d****3a13****
UOS_APP_SERVICE_SECRET配合 APPID 用于服务端SDK或服务端API集成时使用13e2****35e8****8cb7****f177****