Serverless Devs 命令行工具升级规划

[anycodes]

S Cli 改版说明

Serverless Devs Tool（即s-cli），自诞生之日起就承载了阿里云Serverless社区品牌建设的重任，目的是要打造一款可以在用户Serverless项目全生命周期发挥作用的工具，希望大家通过Serverless Devs，可以像使用手机一样来玩转Serverless。

经过小组内的探讨，Serverless Devs将会进行比较大的改版，其主要目的是：在项目初期，敢于试错，敢于改革，只要核心目的是可以为用户提供更完善的服务即可。

Yaml规范的改变

原来的Yaml的规范：

Global:
  全局变量Key: 全局变量Value

项目名:
  Component: 组件名
  Provider: 云厂商
  Access: 密钥信息
  Extends: # 拓展
    deploy: # 拓展指令
      - Hook: 执行的命令
        Path: 执行命令的路径
        Pre: 在拓展指令前后执行
  Properties: 属性 （组件所定义的参数）

新的Yaml规范：

Name: 项目名
Version: 规范的版本, 默认为0.1, 即最初版本
Provider: 全局变量云厂商，优先使用app里面的
Access: 全局变量密钥，优先使用app里面的
Global:
  全局变量Key: 全局变量Value
Applications: # 应用
  应用名:
    Component: 组件名
    Provider: 云厂商
    Access: 密钥信息
    Extends: # 拓展
      deploy: # 拓展指令
        - Hook: 执行的命令
          Path: 执行命令的路径
          Pre: 在拓展指令前后执行
    Properties: 属性 （组件所定义的参数）

举一个前后端的真实例子做对比：

改版之后的好处：

• 增加Version，便于后期规范升级和部分内容改造
• 将整体的业务逻辑理得更清晰，尤其是Applications的融入，会让用户对我们的Application的概念更加清楚
• 增加Name字段，便于我们建设云端资源管理等能力

特殊说明：

• Version，默认为：0.1， 即最初版本，不影响现在用户的使用行为和习惯。

命令行的改变

命令行的改变是比较大的，一方面更加符合command的规范，另一方面也进一步解决了一些冲突问题。
新增exec指令：

  config          Configure cloud service account.
  gui             Start GUI service.
  init            Initializing a project.
  search          Search the package.
  platform        Publish a(an) Component/Plugin/Application.
  set             Settings for the tool.
  exec            exec component method.

exec指令的意思是执行组件的内容。

例如项目：

Name: FullStack
Version: 0.2
Provider: Alibaba
Access: release
Global:
  Region: cn-beijing
Applications:
  Frontend:
    Component: vue-component
    Extends:
      deploy:
        - Hook: s exec -- build
          Path: ./frontend_src
          Pre: true
    Properties:
      Region: ${Global.Region}
      Src: ./frontend_src
  Backend:
    Component: express-component
    Extends:
      deploy:
        - Hook: s exec -- publish
          Path: ./backend_src
          Pre: false
    Properties:
      Region: ${Global.Region}
      Src: ./backend_src

原先我要执行所有的部署操作是：

s deploy

现在是：

s exec -- deploy

原先如果我执行某个App的build操作是：

s Backend build docker --runtime nodejs10

现在是：

s exec Backend -- build docker --runtime nodejs10

新老变化的区别是：

• 增加exec指令，变得更加清晰
• 增加--区分s-cli和component指令， -- 前面是s本身的能力，-- 后面是对应的组件的能力
• 解决了命令行指令冲突问题，例如fun组件有init和config操作，而s也有类似的操作，如果用户只写：

s config / s init

我们就很难判断是s的config/init还是fun组件的config/init，但是新版本的就可以容易判断区分：

s config 						// s
s init 							// s
s exec -- config		// 组件
s exec -- init 			// 组件

这种做法，会让整个项目的思路更加清晰啊，不至于混淆。

[hryang]

我设想的使用体验是这样的：

1. 我们需要提供一个开箱即用的组件集合，而不是要让开发者自己再去组合 debug，deploy 等能力。当然 s 本身还是组件化的，开发者可以定制，精简不需要的功能或者增加新功能。后续所有的建议都是针对集成了默认组件后的 s 工具。
2. 绝大多数情况下，开发者只需要执行 s up 即可
   • up 可以代表 build，deploy，release 3 个指令的集合，也可以是其中的一个或者多个。用户可以自由配置。比如对于 nodejs 这类解释型的语言，不需要 build；如果是在测试环境，也不需要通过 release 实现灰度发布功能。所以对于 nodejs 应用的测试环境，up 只代表 deploy。而对于 java 应用的生产环境，up 包含了 build，deploy，release 3 个指令。
   • 对初学者而言，s up提供了非常明晰的语义，只需要记住这一个指令就够了。而且在实际使用过程中，大部分时候也确实只需要执行 s up。
   • 从键盘敲击效率来看，s up 是最高效的命令，字少，简单，含义明确，不易出错。这是开发者使用 s 最高频的操作。在最高频的指令上做到极简会极大提高开发者的效率。
3. 当有 component 的指令和 s 的指令冲突时，使用 exec 的方式用户体验不是最优。比如 FC component 集成了 pulumi 的能力后，我想使用 s init template 来初始化一个模版。按照当前设计，是不是每次都需要 s exec --init template？用户使用 FC component 的 init 频率远远超过 s 本身的 init，但是高频操作却使用了一个更复杂，更诡异的指令方式，不合理。应该是 component 可以 overwrite s 原有的指令。我们可以为 s 原有的指令设计一个更复杂的形式。

可能上述内容放在这里不太合适，也可放在 FC component repo 的 discussion 中讨论。

[anycodes]

之前也考虑过component重写s的方法，但是实际上这种重写也不是一个非常好的解决方案。
和卷爷沟通过之后，也确实觉得，通过--来区分组件和原生指令会更好一些，而且这个也符合通用的命令行规范。

[hryang]

1. 如果说我每次使用 FC component，都要 s exec --init template，这个体验我很难接受。我使用 FC component init 的次数比 s init 高太多了。
2. 重写 s 的方法有什么问题呀？

[anycodes]

这不仅仅是二级指令的问题，还有一个 参数的问题。如果说二级指令可以重新，那么参数如果也要覆盖，那就会有比较大的问题了。

关于参数问题：

• 首先FC组件的Init，我理解应该是一个低频操作，如果是这种Init，更科学的做法应该是s init
• 例如Pulumi，fun这样的组件，他们本身也有Init和Config，这个时候用户如果写s config，那么系统就完全无法判断是要增加s的config还是fun的config，如果重写了，那么就会涉及到在这个场景下没办法为s进行config，要退出当前项目配置完成再进来。其实命令行工具，更多的时候还是要有一定规则的，而不是其他开发者可以随便重写的，没啥太大的问题，但是并不好。
• 如果涉及到了参数，这个就可能比较复杂了。例如fun组件指定template的参数是-t，s也是-t，当他在项目下写了s deploy -t demo.yaml，我们是把demo.yaml给谁，这就是一个问题了。但是在新的规范中，是可以通过--进行区分，这里要注意刚才你写的s exec --init template实际上应该是s exec -- init template。

[anycodes]

@hanxie-crypto @linux-china
寒斜，卷爷，我们可以一起来讨论一下这个问题

[rsonghuster]

@anycodes 不是有范指令的定义吗？

对于s和组件有相同的指令的情况下， 是如下规则:

• s init 默认是 s 的 init

• s FunDemo init 使用的是 fun 组件的 init

如果不相同， 直接使用组件的， 这个也可以兼容之前的， 不兼容直接改掉好不容易生成的习惯， 这个感觉也挺不好的

[anycodes]

对Yaml的进一步讨论结论：

Name: 项目名
Version: 规范的版本, 默认为0.1, 即最初版本
Provider: 全局变量云厂商，优先使用app里面的
Access: 全局变量密钥，优先使用app里面的
Global:
  全局变量Key: 全局变量Value
Service: # 应用
  服务名:
    Component: 组件名
    Provider: 云厂商
    Access: 密钥信息
    Extends: # 拓展
      deploy: # 拓展指令
        - Hook: 执行的命令
          Path: 执行命令的路径
          Pre: 在拓展指令前后执行
    Properties: 属性 （组件所定义的参数）

[linux-china]

属性名目前要求都必须大写开头否？ 这种大写名称开头在YAML见到的比较少。 另外Service是不是为services更正确一些？

[linux-china]

定稿的时候，最好请一个英文翻译过一下 :)

[anycodes]

刚才还在和hanxie沟通这两个事情：
1: service是否要复数
2: 是否首字母要大写

[anycodes]

Yaml标准：

name: 项目名
version: 规范的版本, 默认为0.1, 即最初版本
provider: 全局变量云厂商，优先使用app里面的
access: 全局变量密钥，优先使用app里面的
global:
  全局变量Key: 全局变量Value
services: # 应用
  服务名:
    component: 组件名
    provider: 云厂商
    access: 密钥信息
    extends: # 拓展
      deploy: # 拓展指令
        - hook: 执行的命令
           path: 执行命令的路径
           pre: 在拓展指令前后执行
    inputs: 属性 （组件所定义的参数）

案例：

name: MyProject
version: 0.2
provider: alibaba
access: release
global:
  Region: cn-hangzhou
services: # 服务
  DjangoService:
    component: django
    inputs:
      Region: ${Global.Region}
      Src: ./django
  VueService:
    component: vue
    inputs:
      Region: ${Global.Region}
      Src: ./vue
  DomainSetting:
    component: domain
    inputs:
      Region: ${Global.Region}
      Routes:
        - Route: /~function
          Function: ${DjangoService.Output.Function.Name}
        - Route: /~static
          Static: ${VueService.Output.Bucket}

[linux-china]

能否支持一个service多个路径匹配，这样做迁移和beta测试都比较方便。

      Routes:
        - Route: ["/~function", "/~function2"]
          Function: ${DjangoService.Output.Function.Name}
        - Route: ["/~static", "~/assets"]
          Static: ${VueService.Output.Bucket}

路由规则通常是一个， 之前写法也是正确的。

      Routes:
        - Route: /~function
          Function: ${DjangoService.Output.Function.Name}
        - Route: /~static
          Static: ${VueService.Output.Bucket}

[anycodes]

经过激烈的讨论，细心的思考，目前再次更新一下这部分改造升级的一个最新规范进展：

Yaml规范升级

Yaml的规范是Serverless Devs非常重要的一个部分，也是非常重要的一个点。这个部分最新的规范是：

Name: 项目名
Provider: 全局变量云厂商，优先使用app里面的
Access: 全局变量密钥，优先使用app里面的
Global:
  全局变量Key: 全局变量Value

服务名:
  Component: 组件名
  Provider: 云厂商
  Access: 密钥信息
  Extends: # 拓展
    deploy: # 拓展指令
      - Hook: 执行的命令
        Path: 执行命令的路径
        Pre: 在拓展指令前后执行
  Properties: 属性 （组件所定义的参数）

案例

• 案例1，全栈应用案例: 将full-stack模式做成一个组件，通过这个组件来实现这个能力，而这个组件内的Properties如何定义，是组件做的事情，不阻塞整个工具的开发：

Name: FullStack       #  [全局新增，非必填]
Provider: Alibaba     #  [全局新增，非必填]
Access: release       #  [全局新增，非必填]

Global:
  Region: cn-beijing

Fullstack:
  Component:  full-stack
  Properties:
    Stack: 
        Src: ./
    Funtions:
         - Function
         - Function
    Routes:
         - Route
         - Route

• 案例2，多组件相互依赖

Name: FullStack       #  [全局新增，非必填]
Provider: Alibaba     #  [全局新增，非必填]
Access: release       #  [全局新增，非必填]

Global:
  Region: cn-beijing

Frontend:
  Component: vue-component
  Extends:
    deploy:
      - Hook: s exec -- build
        Path: ./frontend_src
        Pre: true
  Properties:
    Region: ${Global.Region}
    Src: ./frontend_src
    Url: ${Backend.Output.Url}

Backend:
  Component: express-component
  Extends:
    deploy:
      - Hook: s exec -- publish
        Path: ./backend_src
        Pre: false
  Properties:
    Region: ${Global.Region}
    Src: ./backend_src

目前经过思考，这种做法是可以兼容大部分场景的，如果按照之前的规范，将一些内容收到service下，或者application下，虽然有一个统一的固定的Key了，但是实际上还是会觉得比较怪。概念会对整个规范产生比较大的冲击性。保留原来的基础格式：

• 改造成本比较低
• 更容易兼容之前的场景
• 对整体的使用，不会有概念冲击规范的情况

命令行的规范

命令行的规范是进行了拓展性变更。即提供最简使用方案同时+科学规范使用方案：

例如，一个项目：

Name: FullStack       #  [全局新增，非必填]
Provider: Alibaba     #  [全局新增，非必填]
Access: release       #  [全局新增，非必填]

Global:
  Region: cn-beijing

Frontend:
  Component: vue-component
  Extends:
    deploy:
      - Hook: s exec -- build
        Path: ./frontend_src
        Pre: true
  Properties:
    Region: ${Global.Region}
    Src: ./frontend_src
    Url: ${Backend.Output.Url}

Backend:
  Component: express-component
  Extends:
    deploy:
      - Hook: s exec -- publish
        Path: ./backend_src
        Pre: false
  Properties:
    Region: ${Global.Region}
    Src: ./backend_src

此时，用户可以使用Deploy进行部署：

$ s deploy
$ s exec -- deploy

也可以指定项目进行部署:

$ s Backend deploy
$ s exec Backend -- deploy

同时命令的帮助信息也进行部分的变更，现在的样子是：

Usage: s [options] [command]

  _________                               .__
 /   _____/ ______________  __ ___________|  |   ____   ______ ______
 \_____  \_/ __ \_  __ \  \/ // __ \_  __ \  | _/ __ \ /  ___//  ___/
 /        \  ___/|  | \/\   /\  ___/|  | \/  |_\  ___/ \___ \ \___ \
/_______  /\___  >__|    \_/  \___  >__|  |____/\___  >____  >____  >
        \/     \/                 \/                \/     \/     \/

Welcome to the Serverless Devs Tool.
You can use the corresponding function through the following instructions.


Options:
  -v, --version   Output the version number
  --skip-extends  Skip the extends section
  -h, --help      Display help for command

Commands:
  config          Configure cloud service account.
  gui             Start GUI service.
  init            Initializing a project.
  search          Search the package.
  platform        Publish a(an) Component/Plugin/Application.
  set             Settings for the tool.
  Frontend   [Custom]  vue-component@alibaba component command
  Backend    [Custom] django@alibaba component command

接下来的样子是：

Usage: s [options] [command]

  _________                               .__
 /   _____/ ______________  __ ___________|  |   ____   ______ ______
 \_____  \_/ __ \_  __ \  \/ // __ \_  __ \  | _/ __ \ /  ___//  ___/
 /        \  ___/|  | \/\   /\  ___/|  | \/  |_\  ___/ \___ \ \___ \
/_______  /\___  >__|    \_/  \___  >__|  |____/\___  >____  >____  >
        \/     \/                 \/                \/     \/     \/

Welcome to the Serverless Devs Tool.
You can use the corresponding function through the following instructions.

Options:
  -v, --version              Output the version number
        --skip-extends    Skip the extends section
  -h, --help                   Display help for command

System default sub commands:
   
  config              👤 Configure cloud service account.
  gui                   🌎  Start GUI service.
  init                    🏗 Initializing a project.
  search              🔍 Search the package.
  platform           📝 Publish a(an) Component/Plugin/Application.
  set                    🔧 Settings for the tool.
  exec                  🧑‍💻 Run a command on an app.
  completions     🤙 Generate shell completions for bash, zsh etc.
  validate             ✅ Validate an serverless template.
  upgrade            📥 Upgrade s command to last version.

Additional commands that you can use under the current project：
      
       For example:
           Deploy all: 
              $ s deploy 
           Only deploy Frontend: 
              $ s Frontend deploy

   Frontend       vue-component@alibaba component command
      deploy        **********
      remove       **********
   
   Backend         django@alibaba component command
      deploy         **********
      remove        **********

[linux-china]

Access: 全局变量密钥，优先使用app里面的
这个是保存密钥吗？ 密钥通常不写到应用级别的配置文件中，而是工具命令的配置一部分。 如果在这里提供啦，别人不小心填写啦，而且提供到git仓库中，那就是很大的安全漏洞。

[anycodes]

这个实际上是密钥的别名。

Serverless Devs的Yaml中的Access是创建密钥时所填写的别名（如果没写别名就是default）。所以这里不会因为被上传到Github而产生问题。

[hanxie-crypto]

对，现在秘钥的信息没有放到应用级别配置文件，所以不用担心，像我们应用的.s 文件也要移出去