@serverless-devs/s 2.0.92 → 2.0.93-beta.4

package/spec/zh/0.0.1/serverless_user_model/3.user_model.md

@@ -0,0 +1,218 @@
+# 开发者模型
+
+Serverless User Model 部分介绍了 Serverless Application 规范以 Serverless Package Component 使用规范。
+
+- [Serverless Application 模型](#serverless-application-模型)
+    - [元数据](#元数据)
+    - [变量赋值](#变量赋值)
+    - [服务顺序](#服务顺序)
+    - [行为描述](#行为描述)
+- [Serverless Package Component 使用规范](#serverless-package-component-使用规范)
+
+## Serverless Application 模型
+
+Serverless Application 模型的定义，基于Serverless Devs开发者工具可识别的资源/行为描述文件。该文件仅支持`.yaml`和`.yml`两种格式，且需要符合Yaml的标准规范。与此同时，Serverless Application 模型规定，一个Serverless Devs开发者工具可识别的资源/行为描述文件表示一个Serverless应用。
+
+同时，需要注意的是，Serverless Application模型对应的Yaml格式文件默认名称为`s.yaml`与`s.yml`，且`s.yaml`的优先级大于`s.yml`，即在一个Serverless应用下，同时出现`s.yaml`与`s.yml`时，系统会优先识别和使用`s.yaml`，除非用户在使用时指定了其他Yaml格式的文件，作为默认文件。
+
+关于Serverless Application模型对应的Yaml文件格式，也是有着比较严格的要求，其格式为：
+
+```yaml
+edition: 1.0.0          #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
+name: applicationName   #  应用名称
+access: xxx-account1    #  秘钥别名
+
+vars: # [全局变量，提供给各个服务使用]
+  Key: Value
+
+Service:
+  ServiceName: # 服务名称
+    access: xxx-account1      #  秘钥别名，如果和项目的access相同，可省略
+    component: componentName  #  组件名称
+    props: serviceProp        #  组件的属性值
+    actions: serviceActions   #  自定义执行逻辑
+```
+
+一个完整的符合Serverless Application模型
+
+```yaml
+edition: 1.0.0        #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
+name: FullStack       #  项目名称
+access: xxx-account1  #  秘钥别名
+
+vars: # [全局变量，提供给各个服务使用]
+  logo: https://image.aliyun.com/xxxx.png
+
+services:
+  nextjs-portal: #  服务名称
+    access: xxx-account1  #  秘钥别名，如果和项目的access相同，可省略
+    component: vue-component  # 组件名称
+    props: #  组件的属性值
+      src: ./frontend_src
+      url: url
+    actions: # 自定义执行逻辑
+      pre-deploy: # 在deploy之前运行
+        - run: s exec -- publish  # 要运行的命令行
+          path: ./backend_src # 命令行运行的路径
+        - run: s build  # 要运行的命令行
+          path: ./backend_src # 命令行运行的路径
+      post-deploy: # 在deploy之后运行
+        - run: s clean
+          path: ./frontend_src
+
+  assets:
+    component: static
+    props:
+      cache-control: "public, max-age=604800, immutable"
+      www: "./public"
+
+  express-blog:
+    component: express
+    props:
+      app: ./express-blog
+      url: ${vars.domain}
+    actions:
+      pre-deploy:
+        - run: npm run build
+          path: ./express-blog
+
+  gateway:
+    component: serverless-gateway # 路由组件：HTTP URL和服务之间的映射规则
+    props:
+      routes:
+        - route: /~assets
+          value: ${assets.output.url}
+        - route: /
+          value: ${nextjs-portal.output.url}
+          index: index.html
+        - route: /~portal
+          value: ${nextjs-portal.output.url}
+          inex: index.html
+        - route: /~blog
+          value: ${express-blog.output.url}
+```
+
+### 元数据
+
+在该格式中：
+
+| 参数名 |  代表含义   | 
+|  ----  | ----  | 
+| edition  | 命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范 | 
+| name  | 应用名称 | 
+| access  | 秘钥别名 |
+| vars  | 全局变量，提供给各个服务使用，是一个Key-Value的形式 |
+| Service  | 应用所包含的服务，是一个Key-Value的形式 |
+
+关于Service参数：
+
+| 参数名 |  代表含义   | 
+|  ----  | ----  | 
+| access  | 秘钥别名，如果和项目的access相同，可省略 | 
+| component  | 组件名称 | 
+| actions  | 自定义执行逻辑 |
+| props  | 组件的属性值 |
+
+### 变量赋值
+
+Serverless Application模型对应的Yaml文件支持多种变量格式：
+
+- 获取当前机器中的环境变量：${env(环境变量)}，例如${env(secretId)}
+- 获取外部文档的变量：${file(路径)}，例如${file(./path)}
+- 获取全局变量：${vars.*}
+- 获取其他项目的变量：${projectName.props.*}
+- 获取Yaml中其他项目的结果变量：${projectName.output.*}
+
+### 服务顺序
+
+如果一个Serverless Application模型对应的Yaml文件中有过多的服务，系统会默认分析部署顺序，该部署顺序分为两个步骤：
+
+1. 分析项目中的依赖关系
+2. 有依赖关系的按照依赖关系从前到后部署，无依赖关系的按Yaml配置的从上到下部署
+
+### 行为描述
+
+在Serverless Application模型对应的Yaml文件中，可以针对服务，提供对应的行为操作，其基本格式是：
+
+```yaml
+actions: # 自定义执行逻辑
+  pre-命令: # 在命令之前运行
+    - run: command  # 要运行的操作
+      path: ./path # 运行操作的路径
+  post-命令: # 在命令之后运行
+    - run: command  # 要运行的操作
+      path: ./path # 运行操作的路径
+```
+
+例如：
+
+```yaml
+actions: # 自定义执行逻辑
+  pre-deploy: # 在deploy之前运行
+    - run: s exec -- publish  # 要运行的命令行
+      path: ./backend_src # 命令行运行的路径
+    - run: s build  # 要运行的命令行
+      path: ./backend_src # 命令行运行的路径
+  post-deploy: # 在deploy之后运行
+    - run: s clean
+      path: ./frontend_src
+```
+
+当Serverless Devs开发者工具执行到该服务时，会在进行相关的命令之行之前，优先按照顺序执行`pre-命令`的操作，所有内容完成执行之后，再执行`post-命令`的操作。
+
+以下面的Yaml为例：
+
+```yaml
+edition: 1.0.0        #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
+name: FullStack       #  项目名称
+
+services:
+  nextjs-portal: #  服务名称
+    access: xxx-account1  #  秘钥别名，如果和项目的access相同，可省略
+    component: vue-component  # 组件名称
+    props: #  组件的属性值
+      src: ./frontend_src
+      url: url
+    actions: # 自定义执行逻辑
+      pre-deploy: # 在deploy之前运行
+        - run: s exec -- publish  # 要运行的命令行
+          path: ./backend_src # 命令行运行的路径
+        - run: s build  # 要运行的命令行
+          path: ./backend_src # 命令行运行的路径
+      post-deploy: # 在deploy之后运行
+        - run: s clean
+          path: ./frontend_src
+```
+
+当开发者在当前应用下执行了`deploy`命令，系统将会按照以下顺序进行操作：
+1. 在`./backend_src`目录下执行`s exec -- publish`
+2. 在`./backend_src`目录下执行`s build`
+3. 调用组件`vue-component`的`deploy`方法，并将`props`和项目的基本信息传入到组件`vue-component`的`deploy`方法中
+4. 在`./frontend_src`目录下执行`s clean`
+
+以上顺序仅适用于整个流程没有出错的前提下，如果流程出现错误，系统将会进行报错，并终止后续流程的执行。
+
+## Serverless Package Component 使用规范
+
+Serverless 开发者模型，规定了Serverless Package Component的使用规范。对于一个符合Serverless Application模型的Yaml文件：
+
+```yaml
+edition: 1.0.0          #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
+name: applicationName   #  应用名称
+access: xxx-account1    #  秘钥别名
+
+vars: # [全局变量，提供给各个服务使用]
+  Key: Value
+
+Service:
+  ServiceName: # 服务名称
+    access: xxx-account1      #  秘钥别名，如果和项目的access相同，可省略
+    component: componentName  #  组件名称
+    props: serviceProp        #  组件的属性值
+    actions: serviceActions   #  自定义执行逻辑
+```
+在规范中，不同的Service都需要明确需要使用的component。此时的component格式将会分为几种：
+- 一个存在与指定registry的组件，例如`fc`组件等；
+- 一个存在Github的仓库，且按照规Serverless Package Component规范发布了Release，例如`devsapp/fc`
+- 一个本地的且符合Serverless Package Component规范的组件路径，例如`./../start-component/`
+

package/spec/zh/0.0.1/serverless_user_model/4.application_scopes.md

@@ -0,0 +1,4 @@
+# 适用范围
+
+以上规范适用于条件仅限于 Serverless Devs 开发者工具 所支持、所识别的Serverless应用。Serverless应用开发者，可以通过上述的规范，快速通过Serverless Devs开发者工具，进行Serverless应用的创建、开发、运维等全生命周期的管理。
+ 

package/spec/zh/0.0.1/serverless_user_model/5.design_principles.md

@@ -0,0 +1,3 @@
+# 设计原则
+
+为了给Serverless开发者更加规范和科学的Serverless应用开发流程，可以让Serverless开发者更好的通过Serverless Devs开发者工具对Serverless Devs应用进行全生命周期的管理，Serverless User Model从开发者角度出发，提出Serverless Application规范以及Serverless Package Component规范，可以帮助开发者快速管理和操作Serverless应用。

package/spec/zh/0.0.1/serverless_user_model/readme.md

@@ -0,0 +1,12 @@
+# 用户模型
+
+一个关于 Serverless 应用的开发规范，也是Serverless开发者规范。Serverless developer 需要遵循该规范进行应用开发，通过法规范，可以快速使用Serverless Devs开发者工具，进行相关业务功能的实现。。
+
+- [目的和目标](1.purpose_and_goals.md)
+- [概述和术语](2.overview_and_terminology.md)
+  - [模型概述](2.overview_and_terminology.md#模型概述)
+- [User 模型](./3.user_model.md)
+  - [Serverless Application 模型](./3.user_model.md#serverless-application-模型)
+  - [Serverless Package Component 使用规范](./3.user_model.md##serverless-package-component-使用规范)
+- [适用范围](4.application_scopes.md)
+- [设计原则](5.design_principles.md)

package/bin/s-set-locale

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-require('../lib/set/locale');

package/readme_zh.md

@@ -1,72 +0,0 @@
-# Serverless Devs 帮助文档
-
-<div align=center> <img src="https://images.devsapp.cn/devs-github/logo.jpg" width="100%"/> </div>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@serverless-devs/s">
-    <img src="https://img.shields.io/npm/v/@serverless-devs/s" alt="npm version">
-  </a>
-  <a href="https://github.com/Serverless-Devs/Serverless-Devs/blob/master/LICENSE">
-    <img src="https://img.shields.io/badge/License-MIT-green" alt="license">
-  </a>
-</p>
-
-
-
-<p align="center">
-  <span>像使用手机一样使用Serverless</span><br>
-    <span>中文文档 ｜<a href="./readme.md">English</a> </span>
-</p>
-
-## 项目简介
-
-```text
-  _________                               .__                         ________                     
- /   _____/ ______________  __ ___________|  |   ____   ______ ______ \______ \   _______  ________
- \_____  \_/ __ \_  __ \  \/ // __ \_  __ \  | _/ __ \ /  ___//  ___/  |    |  \_/ __ \  \/ /  ___/
- /        \  ___/|  | \/\   /\  ___/|  | \/  |_\  ___/ \___ \ \___ \   |    `   \  ___/\   /\___ \ 
-/_______  /\___  >__|    \_/  \___  >__|  |____/\___  >____  >____  > /_______  /\___  >\_//____  >
-        \/     \/                 \/                \/     \/     \/          \/     \/         \/ 
-```
-
-Serverless Devs 是一个开源开放的 Serverless 开发者平台，致力于为开发者提供强大的工具链体系。通过该平台，开发者可以一键体验多云 Serverless 产品，极速部署 Serverless 项目。
-
-
-
-### 可支持主流 Serverless 服务/框架
-
-Serverless Devs 是一个组件化与插件化的 Serverless 开发者平台，在该平台中，每个使用者都可以可插拔式的使用不同 Serverless 的服务和框架，同时每个使用者都可以参与开发组件和插件。在 Serverless Devs 中无论是工业级的 Serverless 服务，还是各类开源的 Serverless 框架，都可以得到非常友好的支持。开发者无需对市面上每一款 Serverless 工具进行研究和学习，只需通过 Serverless Devs ，就可以简单、快捷的“上手”主流 Serverless 服务和框架；
-
-### 灵活与开放的使用方法
-
-与绝大部分的开发者工具不同的是，Serverless Devs 在进行项目描述时不仅仅可以对函数计算、API 网关、对象存储等资源进行描述，也可以通过 Serverless Devs 提供的插件以及 Hook 进行Install, Build, Publish等行为描述。与此同时 Serverless Devs 不会对每个组件的命令进行限制，而是鼓励开发者针对不同的组件，开发不同的能力来应对更多、更复杂的场景，例如阿里云函数计算组件，不仅仅支持函数的部署和移除这样的传统能力，还支持日志查询，指标查询，本地构建，依赖安装，调试等更多定制化的能力。Serverless Devs 的这种灵活与开放的使用方法，可以在自动化部署、运维等领域发挥非常大的作用，将Serverless Devs与项目全生命周期进行有机融合，可使得 Serverless 项目的开发运维效能提升 90%。
-
-
-## 帮助文档
-
-- [安装文档](https://github.com/Serverless-Devs/docs/blob/master/zh/install.md)
-- [命令行指令文档](https://github.com/Serverless-Devs/docs/blob/master/zh/command.md)
-- [Yaml规范文档](https://github.com/Serverless-Devs/docs/blob/master/zh/yaml.md)
-- [Package开发者文档](https://github.com/Serverless-Devs/docs/blob/master/zh/dev.md)
-- [源文档](https://github.com/Serverless-Devs/docs/blob/master/zh/registry.md)
-
-## 相关资源
-
-[组件/应用Awesome](https://github.com/Serverless-Devs/package-awesome/blob/main/README_zh.md)
-
-## 快速体验
-
-### 零基础部署一个博客系统
-
-- 下载命令行工具：npm install -g @serverless-devs/s
-- 初始化一个模版项目：s init devsapp/start-zblog
-- 进入项目后部署项目：cd start-zblog && s deploy
-
-### 零基础部署一个企业官网
-
-- 下载命令行工具：npm install -g @serverless-devs/s
-- 初始化一个模版项目：s init devsapp/start-metinfo
-- 进入项目后部署项目：cd start-metinfo && s deploy
-
-更多案例： `s init`
-