粘贴 {{title}} 链接…

无标题

# 目的和目标

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

通过与 Python `pypi`， Nodejs `npm`的对比：

|    | **Serverless Reigstry** | Python Pypi | Nodejs NPM |
|----|----|----|----|
| 存储内容 | **Serverless packages** **(包括 Components, Project 以及 Plugin)** | Python packages | Nodejs packages |
| 是否开放标准 | **是** | 是 | 是 |
| 官方源 | **[registry.devsapp.cn/simple](http://registry.devsapp.cn/simple)** | [pypi.python.org](http://pypi.python.org) | [registry.npmjs.org](http://registry.npmjs.org) |
| 其它源举例 | **Github registry** , **Gitee registry** | 清华源，豆瓣源 | tnpm, cnpm |
| 是否支持私有化 | **支持** | 支持 | 支持 |
| 配套工具 | **Serverless Devs 开发者工具** | Python包管理工具 | Node.js打包管理工 |
| 配套命令 | **s** | pip | npm |
| 如何使用 | **在**`s.yaml`中直接引用，或通过 `s` 命令直接使用 | 安装之后，在代码中引用 | 安装之后，在代码中引用 |

本规范，提供了对 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 的内容可以通过 OpenAPI 进行查询和获取；
* Serverless Registry 可以且仅可以承载符合 Serverless Package Model 规范的 Package （包括项目案例、组件和插件）；
* Serverless Registry 所承载的内容可以在之后的版本进行拓展；
* Serverless Registry 可以根据 Registry 建设者/组织的需求增加符合自身需要的权限鉴定策略；
* Serverless Registry 中的 Package （包括项目案例、组件和插件）应当具备版本的划分能力，以及 Package 的基础管理能力；

## **概念区分**

Serverless Registry 应提供项目案例、组件和插件三种 Package 不同元数据存储能力，针对三者关系可以简单如下理解：

1. 项目案例：本质是一个符合 Serverless Package Model 规范的案例，例如：一个博客项目案例，一个函数计算连接数据库项目案例，一个基于人工智能技术的人脸识别项目案例；该项目案例通常会包括项目代码，帮助文档以及相关描述信息，例如：项目可以部署的地区，项目的运行时等；
2. 组件：本质是一段具有业务属性的脚本或者工程，与项目进行结合，用于处理项目中资源内容。例如函数计算组件，可以将用户的业务逻辑通过所声明的属性，进行部署、移除、版本发布、日志获取等操作；
3. 插件：用于辅助一段资源部署前后的操作，例如，部署函数计算之前，通过 OSS 打包插件，将业务代码进行压缩和和上传。与单纯的 Hook 等功能的区别是，插件可以获取到资源描述文件的输入，并可以将输出内容流转到下一个阶段；

为了更方表了解他们之间的概念，可以参考下面的图片：

 ![image-20230404170400395](https://www.images.wiki/ActtC7z7Sd3A1GyefGlB.png)

# Registry 模型

Registry 模型部分介绍了 Serverless Registry Model (SRM) 的建设模型，包括了：

* 元数据规范
* Registry 规范

## **元数据规范**

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

| 数据名 | 类型 | 描述 |
|----|----|----|
| edition | string | 当前规范和版本 |
| name | string | Package 名称 |
| type | string | Pacakge 类型，主要包括： `project`, `component` 以及 `plugin` |
| provider | list | 厂商类型，主要包括：`阿里云`, `百度智能云`, `华为云`, `腾讯云`, `AWS`, `Azure`, `Google Cloud Platform`, `Laf`, `OpenFunction`, `其它` |
| version | string | 需要符合`主版本号.子版本号.修正版本号`格式或 `dev.子版本号`格式 |
| description | string | 描述信息 |
| service | object | 服务与权限信息，用于描述所需要的服务以及对应的权限内容 |
| tags | list | 标签信息 |
| command | object | 当前版本的 Package 命令文档（只针对 `component` 生效） |
| properties | object | 当前版本的 Package 属性文档 |
| readme | string | 当前版本的 Package 描述文档 |
| home | string | 项目首页或开源地址 |
| create_time | number | 创建时间，时间戳 |
| grayscale | number | 当前应用版本灰度比例 |

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

## **Registry 规范**

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

[ ![img](https://www.images.wiki/i7z8g7r8kb27yfE3arxv.png)]()

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

* Serverless Registry 在接受 Package 开发者贡献的组件与应用时，接受且只接受标准zip格式的压缩包，且压缩包中包括的代码等内容符合且必须符合符合 Serverless Package Model 规范；
* 对于发布在 Serverless Registry 上的应用和组件，Serverless Registry 需要按照以下规范提供对应 Package 版本查询功能以及相对应的下载功能

### 获取 Package 全部版本

**Method**: `GET`

**URI**: `{package_name}/releases`

**Request**:

Path parameters

| 参数 | 类型 | 必填 | 描述 | 默认值 |
|----|----|----|----|----|
| package_name | string | required | Package 名称 | - |

**Response**:

```json
[
  {
      "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"
  },
  {
      "tag_name": "1.1.12",
      "created_at": "2021-01-03T07:41:23Z",
      "zipball_url": "https://api.github.com/repos/Serverless-Devs/Serverless-Devs/zipball/1.1.12"
  }
]
```

**HTTP response status codes**:

| 状态码 | string |
|----|----|
| 200 | OK |
| 404 | 未找到资源 |

### 获取 Package 指定版本

**Method**: `GET`

**URI**: `{package_name}/releases/tags/{version}`

**Request**:

Path parameters

| 参数 | 类型 | 必填 | 描述 | 默认值 |
|----|----|----|----|----|
| package_name | string | required | Package 名称 | - |
| version | string | required | Package 版本 | - |

> 未了更好的适配各类开源项目，当前 API 规范参考 Github Releases 相关 API 设计，针对 tags 参数，在 Github 中表示的是 Release 时的 tag 参数，在当前规范中，默认对应版本信息

**HTTP response status codes**:

| 状态码 | string |
|----|----|
| 200 | OK |
| 404 | 未找到资源 |

**Response**:

```json
{
  "name": "包名称",
  "tag_name": "包版本",
  "created_at": "2021-01-04T07:41:23Z",
  "zipball_url": "https://api.github.com/repos/Serverless-Devs/Serverless-Devs/zipball/1.1.13",
  "description": "描述信息",
  "type": "component",
  "provider": ["AWS"],
  "service": {},
  "tags": ["AWS"],
  "command": {"deploy": "部署"},
  "properties": {},
  "readme": "当前版本的 Package 描述文档",
  "home": "项目首页或开源地址"
}
```

### 获取 Package 最新版本

**Method**: `GET`

**URI**: `{package_name}/releases/latest`

**Request**:

Path parameters

| 参数 | 类型 | 必填 | 描述 | 默认值 |
|----|----|----|----|----|
| package_name | string | required | Package 名称 | - |

**Response**:

```json
{
  "name": "包名称",
  "tag_name": "包版本",
  "created_at": "2021-01-04T07:41:23Z",
  "zipball_url": "https://api.github.com/repos/Serverless-Devs/Serverless-Devs/zipball/1.1.13",
  "description": "描述信息",
  "type": "component",
  "provider": ["AWS"],
  "service": {},
  "tags": ["AWS"],
  "command": {"deploy": "部署"},
  "properties": {},
  "readme": "当前版本的 Package 描述文档",
  "home": "项目首页或开源地址"
}
```

**HTTP response status codes**:

| 状态码 | string |
|----|----|
| 200 | OK |
| 404 | 未找到资源 |

### 创建 Package 和对应版本

**Method**: `POST`

**URI**: `/releases`

**Request**:

Headers

| 参数 | 类型 | 必填 | 描述 | 默认值 |
|----|----|----|----|----|
| Registry-Token | string | required | 用户密钥信息 | - |

Path parameters

| 参数 | 类型 | 必填 | 描述 | 默认值 |
|----|----|----|----|----|
| package_name | string | required | Package 名称 | - |

Body parameters

| 参数 | 类型 | 必填 | 描述 | 默认值 |
|----|----|----|----|----|
| edition | string | required | 当前规范和版本 | 3.0.0 |
| type | string | required | Package 类型，主要包括： `project`, `component` 以及 `plugin` | project |
| name | string | required | Package 名称，最长64位 |    |
| provider | list | required | 厂商类型，主要包括：`阿里云`, `百度智能云`, `华为云`, `腾讯云`, `AWS`, `Azure`, `Google Cloud Platform`, `Laf`, `OpenFunction`, `其它` |    |
| version | string | required | 需要符合`主版本号.子版本号.修正版本号`格式或 `dev.子版本号`格式 |    |
| description | string | required | 描述信息 |    |
| service | object | - | 服务与权限信息，用于描述所需要的服务以及对应的权限内容 |    |
| tags | list | - | 标签信息 |    |
| command | object | - | 当前版本的 Package 命令文档（只针对 `component` 生效） |    |
| properties | object | - | 当前版本的 Package 属性文档 |    |
| readme | string | - | 当前版本的 Package 描述文档 |    |
| home | string | - | 项目首页或开源地址 |    |
| grayscale | number | - | 当前版本灰度比例（取值范围0-1） | 1 |

**Response**:

```json
{
  "name": "包名称",
  "tag_name": "包版本",
  "created_at": "2021-01-04T07:41:23Z",
  "zipball_url": "https://api.github.com/repos/Serverless-Devs/Serverless-Devs/zipball/1.1.13",
  "description": "描述信息",
  "type": "component",
  "provider": ["AWS"],
  "service": {},
  "tags": ["AWS"],
  "command": {"deploy": "部署"},
  "properties": {},
  "readme": "当前版本的 Package 描述文档",
  "home": "项目首页或开源地址"
}
```

**HTTP response status codes**:

| 状态码 | string |
|----|----|
| 201 | 创建成功 |
| 422 | 验证失败，包括登录失败，格式校对失败等 |

### 搜索 Package 指定信息

**Method**: `DELETE`

**URI**: `/releases`

**Request**:

Query parameters

| 参数 | 类型 | 必填 | 描述 | 默认值 |
|----|----|----|----|----|
| search | string | required | 搜索内容 | - |

**Response**:

```json
[
  {
      "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"
  },
  {
      "tag_name": "1.1.12",
      "created_at": "2021-01-03T07:41:23Z",
      "zipball_url": "https://api.github.com/repos/Serverless-Devs/Serverless-Devs/zipball/1.1.12"
  }
]
```

**HTTP response status codes**:

| 状态码 | string |
|----|----|
| 201 | 完成搜索 |

### 删除 Package 指定版本

**Method**: `DELETE`

**URI**: `{package_name}/releases/tags/{version}`

**Request**:

Path parameters

| 参数 | 类型 | 必填 | 描述 | 默认值 |
|----|----|----|----|----|
| package_name | string | required | Package 名称 | - |
| version | string | required | Package 版本 | - |

> 未了更好的适配各类开源项目，当前 API 规范参考 Github Releases 相关 API 设计，针对 tags 参数，在 Github 中表示的是 Release 时的 tag 参数，在当前规范中，默认对应版本信息

**HTTP response status codes**:

| 状态码 | string |
|----|----|
| 204 | 操作成功 |
| 404 | 未找到对应资源 |

**Response**:

```json
No Content
```

### 下载 Package 指定版本

**Method**: `GET`

**URI**: `{package_name}/zipball/{version}`

**Request**:

Path parameters

| 参数 | 类型 | 必填 | 描述 | 默认值 |
|----|----|----|----|----|
| package_name | string | required | Package 名称 | - |
| version | string | required | Package 版本 | - |

> 未了更好的适配各类开源项目，当前 API 规范参考 Github Releases 相关 API 设计，针对 tags 参数，在 Github 中表示的是 Release 时的 tag 参数，在当前规范中，默认对应版本信息

**HTTP response status codes**:

| 状态码 | string |
|----|----|
| 204 | 响应成功 |
| 404 | 未找到对应资源 |

**Response**:

```json
二进制 Zip 包
```

除了以上基础规范，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/> )。