云平台适配

Malagu 框架是平台无关的，可以部署在各种 Serverless 平台、传统服务器之上。Malagu 框架抽象了一套统一的后端接口，不同平台只需要适配统一的后端接口即可。一般一个平台对应着一个适配器组件（可以多个），使用不同平台的适配组件，适配并部署到不同的平台。适配器组件屏蔽掉平台底层细节，让平台的学习成本几乎为零。目前框架已经适配的平台：

• express-adapter 传统服务器
• fc-adapter 阿里云函数计算
• scf-adapter 腾讯云云函数
• lambda-adapter AWS Lambda
• vercel-adapter Vercel 平台

使用方法

首先，确定我们需要运行和部署的平台，选择合适的适配器组件添加到项目依赖中。比如 @malagu/express 、 @malagu/fc-adapter 、 @malagu/scf-adapter 、 @malagu/vercel-adapter 。Malagu 组件是一个普通的 npm 包，可以通过以下命令安装：

# 安装阿里云函数计算适配器组件
yarn add @malagu/fc-adapter # 或者 npm i @malagu/fc-adapter

安装好后，默认不需要任何配置，我们也不必知道该组件与函数计算的底层细节。当我们使用 malagu deploy 命令进行部署的时候，该组件会按照约定的部署规则将我们的代码部署到对应的平台。

对于阿里云函数计算，约定的部署规则是创建的服务名为 malagu，函数名为项目的名称，别名为 test 等等。约定的部署规则可以通过组件之间的属性覆盖自定义。

首次部署

当我们首次部署应用到平台，框架自动判断并提示我们输入平台账号相关的信息，对于阿里云函数计算、腾讯云云函数等云计算厂商平台，我们需要输入 AKSK 信息，告诉框架部署到平台哪个账号下。

下次部署的时候，我们不需要再次输入账号相关信息，这些账号相关的信息会持久化在合适的位置。

适配器组件职责

一个适配器组件往往包含两个主要职责：应用入口文件适配和构建后的代码部署。不同的平台，应用入口的定义往往是不同的，比如阿里云函数计算与腾讯云云函数的入口是不一样，甚至阿里云函数计算自身的 API 网关与 HTTP 函数对应的入口定义也是不一样。

不同平台的部署实现也不一样，使用框架提供的 Deploy 插件能力，结合平台提供的 SDK 或者工具实现部署功能。

任意平台适配器组件，框架都是基于约定大于配置原则，在尽量保证不同平台风格统一的情况下，零配置，开箱即用，且无需关心平台底层细节。

传统服务器

如果我们想把应用部署在传统服务器上，我们可以选择 @malagu/express-adapter 组件。构建输出产物在 .malagu 目录下，其中 backend 为后端构建目标输出目录； frontend 为前端构建目标输出目录。运行后端应用直接使用 node 命令即可：

node .malagu/backend/dist/index.js

阿里云函数计算

我们可以使用 @malagu/fc-adapter 组件把应用部署到阿里云函数计算平台。基于约定大于配置原则，零配置，开箱即用。

云资源

适配器组件有一套默认的部署规则，该规则可以被覆盖。适配器组件在执行部署任务的时候，使用平台提供的 SDK，根据部署规则，创建需要的云资源。如果发现云资源已经存在，则差异更新云资源。适配器组件总是以尽可能安全的方式，创建或更新我们的云资源。比如，当我们配置了自定义域名，适配器组件则尝试创建或更新该自定义域名资源。

适配器组件将应用部署到一个函数中，也就是说一个应用对应着一个函数，如果我们的应用很大，我们应该将大应用拆解成一个个小的微应用或者微服务。就像微服务架构的粒度拆分原则一样，合理的粒度拆分，对我们的应用管理是有很多好处的。框架会保证一个应用在一个函数中的运行性能。

环境隔离

在 Malagu 框架中，提供了一个顶级配置属性 stage 表示环境。而在 @malagu/fc-adapter 组件约定的部署规则中，为了简化环境配置，使用 mode 属性映射 stage 属性。默认提供了三套环境：测试、预发和生产。表达式规则如下：

stage: "${'test' in mode ? 'test' : 'pre' in mode ? 'pre' : 'prod' in mode ? 'prod' : cliContext.prod ? 'prod' : 'test'}" # test, pre, prod

stage 取值规则如下：

• test 测试环境。当 mode 属性包含 test 模式，或者 mode 都不包含 test、pre、prod，且命令行参数 -p,--prod 没有被指定
• pre 预发环境。当 mode 属性包含 pre 模式
• prod 生产环境。当 mode 属性包含 prod 模式，或者命令行参数 -p,--prod 被指定

通过指定特殊的 mode 表示不同的部署环境：

# 部署到测试环境
malagu deploy -m test # 或者 malagu deploy
# 部署到预发环境，我们也可以直接跳过预发环境的部署，直接部署到生产环境
malagu deploy -m pre
# 部署到生成环境
malagu deploy -m prod

隔离级别

环境的隔离级别是可控制的。我们可以使用账号隔离环境：不同环境对于不同配置文件，不同配置文件分别配置不同的云账号。同理，我们也可以使用 Region、服务别名来隔离环境。框架默认提供的是服务别名隔离环境。隔离方式可以互相叠加。

stage 属性值与服务别名关联（以下是默认规则，无需配置）：

malagu:
  faas-adapter:
    alias:
      name: ${stage}

如果我们使用 API 网关的方式部署函数，与 API 网关的 stage 关联（以下是默认规则，无需配置）：

malagu:
  fc-adapter:
    apiGateway:
      stage:
        name: "${stage != 'prod' ? 'release' : stage}"

部署类型

适配器组件通过 type 属性定义部署类型，支持的部署类型如下：

• **api-gateway** 基于 API 网关的部署类型。部署过程中，创建或更新 API 网关、服务、函数等云资源
• **http** HTTP 触发器 + HTTP 函数。部署过程中，创建或更新 HTTP 触发器、服务、函数、自定义域名等云资源
• **custom** 默认值，HTTP 触发器 + Custom 函数（推荐）。部署过程中，创建或更新 HTTP 触发器、服务、函数、自定义域名等云资源

  malagu:
  faas-adapter:
    type: custom

自定义部署规则

我们可以通过同名覆盖自定义部署规则。

默认规则

默认规则定义在 @malagu/fc-adapter 组件的 malagu-remote.yml 配置文件中。

自定义部署类型**

malagu:
    faas-adapter:
    type: api-gateway # 默认值是 custom，支持 custom、api-gateway、http

自定义服务名

malagu:
    faas-adapter:
    service:
      name: xxxx # 默认值是 malagu

服务的其他属性也是类似的方式配置。

自定义函数名

malagu:
    faas-adapter:
    function:
      name: xxxx # 默认值是 ${pkg.name}

函数的其他属性也是类似的方式配置。

腾讯云云函数

我们可以使用 @malagu/scf-adapter 组件把应用部署到腾讯云函数计算平台。基于约定大于配置原则，零配置，开箱即用。

云资源

适配器组件有一套默认的部署规则，该规则可以被覆盖。适配器组件在执行部署任务的时候，使用平台提供的 SDK，根据部署规则，创建需要的云资源。如果发现云资源已经存在，则差异更新云资源。适配器组件总是以尽可能安全的方式，创建或更新我们的云资源。比如，当我们配置了自定义域名，适配器组件则尝试创建或更新该自定义域名资源。

适配器组件将应用部署到一个函数中，也就是说一个应用对应着一个函数，如果我们的应用很大，我们应该将大应用拆解成一个个小的微应用或者微服务。就像微服务架构的粒度拆分原则一样，合理的粒度拆分，对我们的应用管理是有很多好处的。框架会保证一个应用在一个函数中运行的性能。

环境隔离

在 Malagu 框架中，提供了一个顶级配置属性 stage 表示环境。而在 @malagu/scf-adapter 组件约定的部署规则中，使用 mode 属性映射 stage 属性。默认提供了三套环境：测试、预发和生产。表达式规则如下：

stage: "${'test' in mode ? 'test' : 'pre' in mode ? 'pre' : 'prod' in mode ? 'prod' : cliContext.prod ? 'prod' : 'test'}" # test, pre, prod

stage 取值规则如下：

• test 测试环境。当 mode 属性包含 test 模式，或者 mode 都不包含 test、pre、prod，且命令行参数 -p,--prod 没有被指定
• pre 预发环境。当 mode 属性包含 pre 模式
• prod 生产环境。当 mode 属性包含 prod 模式，或者命令行参数 -p,--prod 被指定

通过指定特殊的 mode 表示不同的部署环境：

# 部署到测试环境
malagu deploy -m test # 或者 malagu deploy
# 部署到预发环境，我们也可以直接跳过预发环境的部署，直接部署到生产环境
malagu deploy -m pre
# 部署到生成环境
malagu deploy -m prod

隔离级别

环境的隔离级别是可控制的。我们可以使用账号隔离环境：不同环境对于不同配置文件，不同配置文件分别配置不同的云账号。同理，我们也可以使用 Region、服务别名来隔离环境。框架默认提供的是服务别名隔离环境。隔离方式可以互相叠加。

stage 属性值与服务别名关联（以下是默认规则，无需配置）：

malagu:
  faas-adapter:
    alias:
      name: ${stage}

API 网关的 environment 关联（以下是默认规则，无需配置）：

malagu:
  faas-adapter:
    apiGateway:
      release:
        environmentName: "${stage == 'pre' ? 'prepub' : stage == 'prod' ? 'release' : stage}"

部署类型

适配器组件通过 type 属性定义部署类型，支持的部署类型如下：

• **api-gateway** 基于 API 网关的部署类型。部署过程中，创建或更新 API 网关、命名空间、函数等云资源

  malagu:
  faas-adapter:
    type: api-gateway

自定义部署规则

我们可以通过同名覆盖自定义部署规则。

默认规则

默认规则定义在 @malagu/scf-adapter 组件的 malagu-remote.yml 配置文件中。

自定义部署类型**

malagu:
    faas-adapter:
    type: api-gateway # 默认值是 api-gateway，目前只支持 api-gateway

自定义命名空间

malagu:
    faas-adapter:
      namespace:
        name: xxxx # 默认值是 default

命名空间的其他属性也是类似的方式配置。

自定义函数名

malagu:
    faas-adapter:
    function:
      name: xxxx # 默认值是 ${pkg.name}

函数的其他属性也是类似的方式配置。

AWS Lambda

我们可以使用 @malagu/lambda-adapter 组件把应用部署到 aws lambda 平台。基于约定大于配置原则，零配置，开箱即用。

云资源

适配器组件有一套默认的部署规则，该规则可以被覆盖。适配器组件在执行部署任务的时候，使用平台提供的 SDK，根据部署规则，创建需要的云资源。如果发现云资源已经存在，则差异更新云资源。适配器组件总是以尽可能安全的方式，创建或更新我们的云资源。比如，当我们配置了自定义域名，适配器组件则尝试创建或更新该自定义域名资源。

适配器组件将应用部署到一个函数中，也就是说一个应用对应着一个函数，如果我们的应用很大，我们应该将大应用拆解成一个个小的微应用或者微服务。就像微服务架构的粒度拆分原则一样，合理的粒度拆分，对我们的应用管理是有很多好处的。框架会保证一个应用在一个函数中运行的性能。

环境隔离

在 Malagu 框架中，提供了一个顶级配置属性 stage 表示环境。而在 @malagu/scf-adapter 组件约定的部署规则中，使用 mode 属性映射 stage 属性。默认提供了三套环境：测试、预发和生产。表达式规则如下：

stage: "${'test' in mode ? 'test' : 'pre' in mode ? 'pre' : 'prod' in mode ? 'prod' : cliContext.prod ? 'prod' : 'test'}" # test, pre, prod

stage 取值规则如下：

• test 测试环境。当 mode 属性包含 test 模式，或者 mode 都不包含 test、pre、prod，且命令行参数 -p,--prod 没有被指定
• pre 预发环境。当 mode 属性包含 pre 模式
• prod 生产环境。当 mode 属性包含 prod 模式，或者命令行参数 -p,--prod 被指定

通过指定特殊的 mode 表示不同的部署环境：

# 部署到测试环境
malagu deploy -m test # 或者 malagu deploy
# 部署到预发环境，我们也可以直接跳过预发环境的部署，直接部署到生产环境
malagu deploy -m pre
# 部署到生成环境
malagu deploy -m prod

隔离级别

环境的隔离级别是可控制的。我们可以使用账号隔离环境：不同环境对于不同配置文件，不同配置文件分别配置不同的云账号。同理，我们也可以使用 Region、服务别名来隔离环境。框架默认提供的是服务别名隔离环境。隔离方式可以互相叠加。

stage 属性值与函数别名关联（以下是默认规则，无需配置）：

malagu:
  faas-adapter:
    alias:
      name: ${stage}

API 网关的 stage 关联（以下是默认规则，无需配置）：

malagu:
  faas-adapter:
    apiGateway:
      stage:
        name: ${stage}

部署类型

适配器组件通过 type 属性定义部署类型，支持的部署类型如下：

• **api-gateway** 基于 API 网关的部署类型。部署过程中，创建或更新 API 网关、函数等云资源

  malagu:
  faas-adapter:
    type: api-gateway

自定义部署规则

我们可以通过同名覆盖自定义部署规则。

默认规则

默认规则定义在 @malagu/lambda-adapter 组件的 malagu-remote.yml 配置文件中。

自定义部署类型**

malagu:
    faas-adapter:
    type: api-gateway # 默认值是 api-gateway，目前只支持 api-gateway

自定义函数名

malagu:
    faas-adapter:
    function:
      name: xxxx # 默认值是 ${pkg.name}

函数的其他属性也是类似的方式配置。

Vercel 平台

Vercel 是国外一个用户体验很棒的 Serverless 平台。我们可以使用 @malagu/vercel-adapter 组件把应用部署到 Vercel 平台。基于约定大于配置原则，零配置，开箱即用。适配器组件基于 Vercel CLI 工具实现部署，所有部署的体验与该工具是一样的，甚至部署规则也是简单适配该工具的配置，只是采用了框架的配置文件方式。

云资源

适配器组件有一套默认的部署规则，该规则可以被覆盖。适配器组件在执行部署任务的时候，使用平台提供的 Vercel CLI 工具，根据部署规则，创建需要的云资源。

部署规则

我们可以通过同名覆盖自定义部署规则。默认规则定义在 @malagu/vercel-adapter 组件的 malagu-remote.yml 配置文件中。部署规则的配置项与 Vercel CLI 工具的配置文件 vercel.json 是相同的。默认配置如下：

malagu:
  vercel:
    config:
      version: 2
frontend:
  malagu:
    vercel:
      config:
        builds:
          - src: 'frontend/dist/**'
            use: '@now/static'
        routes:
          - src: /(.*)
            dest: frontend/dist/$1
backend:
  malagu:
    vercel:
      config:
        builds:
          - src: 'backend/dist/**'
            use: '@now/node'
        routes:
          - src: /api
            dest: backend/dist/index.js

**