Serverless Registry Model

一个开放的 Serverless Registry Model。Package 的开发者可以将自己开发的组件，或者待分享的应用发布到该平台。该平台可以使用目前 Serverless Devs 所支持的 Github Resitry， Gitee Registry， Serverless Registry，也可以按照该规范搭建私有的 Registry 以完成部分能力。

目的和目标

Serverless Registry Model(简称 SRM，下文将使用 SRM 代替)的目标是定义一种 Serverless 架构下的 Registry 的规范，与 Python 中的 pypi， Nodejs 中的 npm 等类似，将以此来开放和分享 Serverless Package，建设 Serverless 生态。

为了让大家更简单的理解 Serverless Registry， 可以通过与 Python Pypi， Nodejs NPM 的对比，进行深入探索：

本规范，提供了对 Serverless 应用开发和部署的相关生态的支持，通过本规范可以快速的创建公开的/私有化的 Serverless Registry，并通过 Serverless Devs 开发者工具 进行使用，助力 Serverless 应用开发者可以更简单，更快速，更方便的使用不同平台的 Serverless 产品，可以提升功能效能。

概述和术语

本节讲述了 SRM 及其术语。它首先是一个 Serverless Devs Model(SDM) 中不可或缺的概念，它代表的是 Serverless 的一种开发者生态，Serverless Devs 开发者工具 开发者工具将会通过 Serverless Registry 进行应用案例的拉取，或者组件的下载和使用，而 Serverless Registry Model(SRM) 则是 Serverless Registry 的规范和标准。

模型概述

该规范提出了一个模型，定义 Serverless Registry 如下：

Serverless Registry 是承载 Serverless 生态的抽象概念，与 Python Pypi，Nodejs NPM 等类似，Serverless Registry 用于开放和共享 Serverless Package。

在当前版本中，Serverless Registry 定义了以下内容：

• Serverless Registry 将会同时承载应用和组件；

• 应用和组件在 Serverless Registry 上将会具有不同数据结构的元数据；

• Serverless Registry 的应用可以通过规范的 API 进行查询和获取；

• Serverless Registry 可以且仅可以承载符合 Serverless Package Model 规范的 Package （包括应用与组件）；

• Serverless Registry 所承载的内容可以在之后的版本进行拓展；

• Serverless Registry 可以根据 Registry 建设者/组织的需求增加符合自身需要的权限鉴定策略；

• Serverless Registry 中的 Package （包括应用与组件）应当具备版本的划分能力，以及 Package 的增加、删除的能力；

Registry 模型

元数据规范

Serverless Reigstry 需要获得并存储 Package 以下信息：

除了以上基础规范，Serverless Registry 的提供者/组织还可以根据具体需求，存储更多的数据/信息，包括不限于用于鉴权使用的 Package 贡献者 id，用户确定 Package 状态的 status 等；

Registry 规范

Package 开发者和 Serverless 开发者在发布 Package 以及使用 Package 的流程可以简化为：

通过上述流程，可以看到对于 Package 开发者而言，需要按照 Serverless Package Model 规范提供相对应的 Package 到 Serverless Registry，而对于 Serverless 开发者而言，则需通过 Serverless Devs 开发者工具 工具中，进行 Package 的下载和使用。在整个过程中，涉及到的核心规范如下：

• Serverless Registry 在接受 Package 开发者贡献的组件与应用时，接受且只接受标准 zip 格式的压缩包，且压缩包中包括的代码等内容符合且必须符合符合 Serverless Package Model 规范；

• 对于发布在 Serverless Registry 上的应用和组件，Serverless Registry 需要按照以下规范提供对应 Package 版本查询功能以及相对应的下载功能：

• 全部版本查询：

• Method：GET

• URI：{package-name}/releases/latest

• Response：

      {          "tag_name": "1.1.13",          "created_at": "2021-01-04T07:41:23Z",          "zipball_url": "https://api.github.com/repos/Serverless-Devs/Serverless-Devs/zipball/1.1.13",          "body": "- 中文\r\n  - 修复边界条件下临时密钥获取失败的BUG\r\n- English: \r\n  - Fix the bug that the temporary key acquisition fails under boundary conditions"      }

• 最新版本查询：

• Method：GET

• URI：{package-name}/releases/latest

• Response：

      {          "tag_name": "1.1.13",          "created_at": "2021-01-04T07:41:23Z",          "zipball_url": "https://api.github.com/repos/Serverless-Devs/Serverless-Devs/zipball/1.1.13",          "body": "- 中文\r\n  - 修复边界条件下临时密钥获取失败的BUG\r\n- English: \r\n  - Fix the bug that the temporary key acquisition fails under boundary conditions"      }

• Package 下载：

• Method：GET

• URI：{package-name}/zipball/{version}

• Response：组件压缩包

除了以上基础规范，Serverless Registry 的提供者/组织还可以根据具体需求，提供 Package 更新，删除以及权限变更等相关的额外能力。

适用规范

以上规范适于条件仅限于 Serverless Devs 开发者工具 所支持、所识别的文件格式，以及所必须的流程接口。用户/组织可以通过上述的规范可以建立的 Serverless Registry 可以直接被 Serverless Devs 开发者工具 所识别和使用。

但是并不代表 Serverless Registry 的功能仅如此，作为 Serverless Registry 的建设者和维护者，有权在保证符合上述规范的前提下丰富相对应的接口以及能力。包括不限于所春初的元数据的丰富，所支持的接口能力的丰富等，这些额外的能力将作为 Serverless Registry 的拓展能力存在，并不作为 Serverless Registry Model 的一部分。

设计原则

为了更加公平和开放，上述的设计规范参照于 Github 相关接口设计，所以可以认为 Serverless Devs 开发者工具 天然支持 Github 作为其默认的 Serverless Registry ( https://api.github.com/repos/ )。

Serverless Package Model

目的和目标

Serverless Package Model(简称 SPM，下文将使用 SPM 代替)的目标是定义一种 Serverless Package 开发模型以及开发者规范；核心目的是基于这套模型或者规范所开发的项目，可以被 Serverless Registry 所接受，并且被 Serverless Devs 开发者工具所识别，按照 Serverless 开发者的预期实现实现预定的功能。

概述和术语

Serverless Package Model(SPM) 是 Package 开发者所需要使用的模型，以及遵循的规范。从形态组成纬度包括应用与组件两部分；同文件树组成来看包括用于自描述的publish.yaml文件，以及业务代码`：

Package 与 Package Model

相对来说，Package 是一个实际的产物，由规范的代码组成，目的是完成某个功能或者表示一个案例；而 Package Model 相对来说是抽象的存在，表示的是一种规范与规则。

• Package 是由指符合 SPM 规范的代码，其目标是用来实现模型功能，包括不限于部署业务逻辑到 Serverless 平台，调试 Serverless 应用代码等；

• Package Model 是 Serverless Devs 的 Package 开发规范，只有按照该模型，遵循该规范的 Serverless Package 才可以被 Serverless Devs 开发者工具 所识别，并且可以成功的发布在符合 Serverless Registry Model 规范的 Serverless Registry 平台上；

Package 模型

模型的组成

Serverless Package Model 包括两个部分：

• Component Model：组件模型，即通过 Serverless Devs，可以被应用所引用，并按照用户的输入，执行预定的功能。例如某个应用中引用了 FC 组件，那么此时，用户可以通过传入 Deploy 命令进行函数的部署，而这里的 FC 组件，则是需要建立在组件模型基础之上，即要符合组件的开发规范；

• Application Model：应用模型，即通过 Serverless Devs，可以被初始化的应用案例，通常一个应用案例包括了一个 yaml 文件，在该文件中可以包括一个或多个组件来共同完成某个业务。这里所说的应用，就是需要建立在应用模型基础之上的，或者说是需要符合应用开发规范的；

模型的规范

组件模型规范

Component Model，即组件模型是需要通过指定的文件进行模型的规范和定义的。在这里，推荐的组件模型目录结构为：

|- src # 目录名字可以变更|   └── 代码目录  |- package.json: 需要定义好main   |- publish.yaml: 项目的资源描述   |- readme.md: 项目简介  |- version.md: 版本更新内容

其中：

组件模型元数据

组件模型元数据将会在publish.yaml中进行描述，并在 Serverless Registry 和 Serverless Devs 开发者工具侧进行识别和引用。

publish.yaml文件的基本格式如下所示：

Type: ComponentName: 名称Provider:  - 云厂商名称 Version: 版本，例如0.0.1Description: 简短的描述/介绍HomePage: 项目首页地址Tags: #标签详情  - 部署函数  - 部署组件Category: 分类 # 基础云服务/Web框架/Web应用/人工智能/音视频处理/图文处理/监控告警/大数据/IoT/新手入门/其他Service: # 使用的服务  - Name: 服务名 # 函数计算/容器服务/镜像服务/消息队列/工作流/CDN/对象存储/表格存储/MNS/日志服务/API网关/数据库/解析服务/云应用/其他    # Runtime: Python 3.6 如果服务是函数，还需要增加Runtime    Authorities: #权限描述      - 创建函数 # 所需要的权限Commands: # 指令，格式为指令：指令描述，例如：  deploy: 部署函数  invoke: 调用函数Properties:  Region: # 参数    Description: 参数描述    Required: true # 参数必选，true/false    Type: # 参数类型      - String

参数详解

Provider

取值范围：阿里云, 百度智能云, 华为云, 腾讯云, AWS, Azure, Google Cloud, 其它

格式参考：

Provider:    - 阿里云    - 百度智能云

Category

取值范围：基础云服务, Web框架, 全栈应用, 人工智能, 音视频处理, 图文处理, 监控告警, 大数据, IoT, 新手入门, 其他

格式参考：

Category: 基础云服务

Service

取值范围：函数计算, 容器服务, 镜像服务, 消息队列, 工作流, CDN, 对象存储, 表格存储, MNS, 日志服务, API网关, 数据库, 解析服务, 云应用, 其他

格式参考：

Service: # 使用的服务  - Name: 函数计算    # Runtime: Python 3.6 如果服务是函数，还需要增加Runtime，取值包括：Node.JS, Python, PHP, Java, Go, 其它    Authorities: #权限描述      - 创建函数 # 所需要的权限

Properties

Properties 是对组件的属性进行描述的，所以相对比较负责，主要包括：

关于参数 Type(类型)的额外定义：

基本参数类型：String, Number, List, Enum, Struct, Boolean, Null, Any

复杂参数类型：List<数据类型>

另外，当 Type 是 List 类型时，可以针对不同的元素做别名：数据类型[别名]

格式参考：

• 简单格式：

  Properties:    Region: # 参数      Description: 参数描述      Required: true # 参数必选，true/false      Type: # 参数类型        - String

用户侧表现是：

  Region: cn-hangzhou

• 复杂格式：

  Properties:    Region: # 参数      Description: 地区      Required: true # 参数必选，true/false      Type: # 参数类型        - String[简单配置]        - List<String>[多地域配置]        - Struct[分别配置]:             APIGW:              Description: API网关部署的地区              Required: true               Type:                 - String            Function:              Description: 函数部署的地区              Required: true               Type:                 - String

用户侧表现是：

• 当 Type 为 String[简单配置]时：

    Region: cn-hangzhou

• 当 Type 为 List<String>[多地域配置]时：

    Region:       - cn-hangzhou      - cn-beijing

• 当 Type 为 Struct[分别配置]时：

    Region:       APIGW: cn-beijing      Function: cn-shanghai

组件模型代码规范

在组件模型中，代码组成规范有两个部分：

• package.json中需要描述清楚入口文件所在地址；例如{"main": "./dist/index.js"}；

• 在代码中实现对应的用户方法。例如 Package 开发者希望用户可以通过 deploy 命令，进行项目的部署，那么就可以实现一个 deploy 的方法，并在方法内实现对应的部署能力；

关于代码规范部分，可以参考如下案例：

import logger from './common/logger';import { InputProps } from './common/entity';
export default class ComponentDemo {  /**   * demo 实例   * @param inputs   * @returns   */  public async test(inputs: InputProps) {    logger.debug(`input: ${JSON.stringify(inputs.props)}`);    logger.info('command test');    return { hello: 'world' };  }}

其中入参inputs的结构为：

{    "command": "",     "project": {        "projectName": "",         "component": "",        "provider": "",        "access": ""    },    "credentials": {},    "prop": {},    "args": "",    "argsObj": []}

在上面的案例代码中，可以看到有一个 test 方法，该方法就是功能实现的方法。此时当用户使用 test 命令时，系统就会携带参数调用该方法。以一个真实案例作为举例说明：

该组件名为hexo，组件核心代码如上所示，具备一个 test 方法，此时用户侧的 Yaml 为：

edition: 1.0.0        #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范name: FullStack       #  项目名称access: xxx-account1  #  秘钥别名
services:  HexoComponent:    component: hexo    props:      region: 'cn-hangzhou'      codeUri: './src'

当用户执行s test mytest -a -b abc，此时，组件代码中的test方法，收到的inputs参数实际上是：

{    "command": "test",     "project": {        "projectName": "HexoComponent",         "component": "hexo",        "provider": "alibaba",        "access": "release"    },    "credentials": {        "AccountID": "********",        "AccessKeyID": "********",        "AccessKeySecret": "********"    },    "prop": {        "Region": "cn-hangzhou",        "CodeUri": "./src"    },    "args": "mytest -a -b abc",    "argsObj": [      "mytest", "-a", "-b", "abc"    ]}

此时 test 方法会打印日志信息等，并返回最终的结果给命令行工具：{ "hello": "world" }

应用模型规范

Application Model，即组件模型是需要通过指定的文件进行模型的规范和定义的。在这里，推荐的组件模型目录结构为：

|- src # 目录名字不可以变更|   └── 应用目录|   └── s.yml: 应用描述文件|- publish.yaml: 项目的资源描述   |- readme.md: 项目简介  |- version.md: 版本更新内容

其中：

应用模型元数据

应用模型元数据将会在publish.yaml中进行描述，并在 Serverless Registry 和 Serverless Devs 开发者工具侧进行识别和初始化。

publish.yaml文件的基本格式如下所示：

Type: ApplicationName: 名称Provider:  - 云厂商名称 Version: 版本，例如0.0.1Description: 简短的描述/介绍HomePage: 项目首页地址Tags: #标签详情  - 部署函数  - 部署组件Category: 分类 # 基础云服务/Web框架/Web应用/人工智能/音视频处理/图文处理/监控告警/大数据/IoT/新手入门/其他Service: # 使用的服务  - Name: 服务名 # 函数计算/容器服务/镜像服务/消息队列/工作流/CDN/对象存储/表格存储/MNS/日志服务/API网关/数据库/解析服务/云应用/其他    # Runtime: Python 3.6 如果服务是函数，还需要增加Runtime    Authorities: #权限描述      - 创建函数 # 所需要的权限

参数详解

Provider

取值范围：阿里云, 百度智能云, 华为云, 腾讯云, AWS, Azure, Google Cloud, 其它

格式参考：

Provider:    - 阿里云    - 百度智能云

Category

取值范围：基础云服务, Web框架, 全栈应用, 人工智能, 音视频处理, 图文处理, 监控告警, 大数据, IoT, 新手入门, 其他

格式参考：

Category: 基础云服务

Service

取值范围：函数计算, 容器服务, 镜像服务, 消息队列, 工作流, CDN, 对象存储, 表格存储, MNS, 日志服务, API网关, 数据库, 解析服务, 云应用, 其他

格式参考：

Service: # 使用的服务  - Name: 函数计算    # Runtime: Python 3.6 如果服务是函数，还需要增加Runtime，取值包括：Node.JS, Python, PHP, Java, Go, 其它    Authorities: #权限描述      - 创建函数 # 所需要的权限

特殊格式：在应用模型中，需要存在src/s.yaml文件，作为 Serverless Devs 识别和使用的资源、行为描述文件，在该文件中，可能涉及到部分内容是需要用户进行填写的，例如用户的密钥名字，用户部署业务的地域等。此时可以参考：

• "{{ access }}" ：直接提醒用户需要输入 access 这样的一个参数，作为 Yaml 中所必须的参数；

• '{{ bucket | alibaba oss bucket }}' ： ：直接提醒用户需要输入 bucket 这样的一个参数，作为 Yaml 中所必须的参数，并以|之后的内容"alibaba oss bucket"作为解释这个参数的含义；例如，在某应用的s.yaml中表现为：

edition: 1.0.0
access: "{{ access }}"

services:
  website-starter:
   component: devsapp/website
    actions:
      pre-deploy:
        - run: npm install
          path: ./
        - run: npm run build
          path: ./
    props:
      bucket: '{{ bucket | alibaba oss bucket }}'
      src:
        codeUri: ./
        publishDir: ./build
        index: index.html
      region: cn-hangzhou
      hosts:
        - host: auto

适用范围

以上规范适于条件仅限于 Serverless Registry 以及 Serverless Devs 开发者工具 所支持、所识别的文件格式，以及所必须的流程接口。用户/组织可以通过上述的规范可以建立的 Serverless Pacakges 可以直接发布到 Serverless Registry 并被 Serverless Devs 开发者工具 所识别和使用。

设计原则

为了给 Serverless 开发者更简单、更方便、更快速的上手体验，Serverless Devs 以开发者为核心，提出了 Serverless Package 的概念，为了让 Serverless Package 的开发者，可以更简单、快速的开发出满足 Serverless 开发者诉求的组件、应用，Serverless Package Model 致力于提供更细致化，更规范化的模型基础。