f.yml 定义

概述

经过阿里集团标准化小组的讨论，结合社区 serverless.yml 的已有设计，通过一个描述文件 (f.yml) 来描述整个仓库中的函数信息，现有的发布构建工具，运行时都会基于此文件进行各种处理。

描述文件结构基于 serverless.yml，目标是在现有社区化复用能力之上，希望各个平台的代码能尽可能统一，一套代码可以多处部署，并向上扩展。

大体结构

由于不同平台的触发器不同，配置信息也不同，配置略微有些差别，但是整体基本一致。

目前第一层字段包括：

• service 当前的服务（函数分组），对标应用
• provider 当前的服务提供商，比如 aliyun，tencent 等。
• functions 函数的具体信息
• layers 具体的layer 层配置
• resources 引用的资源
• plugins 引用的插件，serverless 预留
• aggregation 聚合部署字段
• package 构建的配置信息
• custom 其他自定义信息

大体如下：

service: serverless-hello-world
provider:
  name: aliyun
  runtime: nodejs10
  role: acs:ram::1647796581073291:role/aoneserverlesstestrole
functions:
  hello1:
    handler: entry.handler
    events:
      - http:
          path: /foo
          method:
            - GET
            - POST
  hello2:
      handler: entry.handler2
      events:
        - http:
            path: /foo
            method:
              - GET
              - POST
  hello3:
      handler: test.handler2
      events:
        - http:
            path: /foo
            method:
              - GET
              - POST
layers:
  test:
    path: npm:@midwayjs/egg-layer@latest
custom:
  customDomain:
    domainName: midway-fc.xxxx.com

平台字段支持

由于字段非常多，下面的表格统计了所有当前支持的字段，具体的字段描述可以在下面更详细的表格中查找。

√ 代表工具链已经支持，○ 代表部分支持平台支持，但是工具链尚未支持。

• 附1：CLI 工具链在本地开发时支持此参数，但是发布时不会读取，需要去网关配置；阿里云云开发平台已经支持此参数进行发布

  service

主要是服务名信息，一个服务可以包含多个函数。

结构

export type ServiceStructure = string | {
  name: string;
  description?: string;
};

字段描述

示例

service: serverless-hello-world // 简写

service: 
  name: serverless-hello-world
  description: 'some description'

provider

描述云平台，运行时，权限，以及所有函数复用的信息。

结构

export interface ProviderStructure {
  name: string;
  runtime: string;
  stage?: string;
  region?: string;
  timeout?: number;
  memorySize?: number;
  description?: string;
  role?: string;
  environment?: {
    [key: string]: string;
  };
  serviceId?: string;
  vpcConfig?: {
    vpcId: string;
    vSwitchIds: string[];
    securityGroupId: string;
  };
  internetAccess?: boolean;
  policies?: string | string[];
  logConfig?: {
    project: string;
    logstore: string;
  };
  nasConfig?:
    | 'auto'
    | {
        userId: number;
        groupId: number;
        mountPoints: Array<{
          serverAddr: string;
          mountDir: string;
        }>;
      };
}

字段描述

:::info 腾讯云的 Node.js Runtime 版本我们做了映射，对应关系如下：

• nodejs10 -> Node.js10.15
• nodejs8 -> Node.js8.9
• node.js6 -> Node.js6.10 :::

  示例

aliyun fc 下

provider:
  name: aliyun
  runtime: nodejs10
  memorySize: 128
  policies:
    - AliyunECSNetworkInterfaceManagementAccess
  vpcConfig:
    vpcId: 'vpc-j6cfu2g6tslzekh8grfmk'
    vSwitchIds: [ 'vsw-j6chkgsg9naj6gx49espd' ]
    securityGroupId: 'sg-j6ceitqs6ljyssm1apom'
  logConfig:
      project: localtestlog
      logstore: localteststore
  nasConfig:
    userId: 10003
    groupId: 10003
    mountPoints:
      - serverAddr: '012194b28f-xxxxx.cn-hangzhou.nas.aliyuncs.com:/'
        mountDir: '/mnt/test'

tencent

provider:
  name: tencent
  runtime: Nodejs10
  memorySize: 128
  timeout: 10
  serviceId: xxxxx
  region: ap-shanghai

functions

一个 functions 结构中包含多个 函数（function）。每个函数是一个对象（function）结构。

functions/function 结构

functions 和 function 结构是包含的关系，定义如下。

export interface FunctionsStructure {
  [functionName: string]: FunctionStructure;
}
export interface FunctionStructure {
  handler: string;
  name?: string;
  description?: string;
  memorySize?: number;
  timeout?: number;
  runtime?: string;
  initTimeout?: number;
  environment?: {
    [key: string]: string;
  };
  events?: EventStructureType[];
  concurrency?: number;
  stage?: string;
}

字段描述

Functions 是一个由多个 function 组成的对象（非数组），以函数名作为 key，函数信息作为值。

单个函数结构如下：

示例

以下结构描述了三个函数，每个函数的入口不同，内存限制不同。

functions:
  hello1:
    handler: index.handler1
    memorySize: 128
  hello2:
    handler: index.handler2
    memorySize: 256
  hello3:
    handler: index.handler3
    memorySize: 512

events

export interface HTTPEvent {
  path?: string;
  method?: string | string[];
  role?: string;
  version?: string;
  serviceId?: string;
  cors?: boolean;
  timeout?: number;
  integratedResponse?: boolean;
}
export interface APIGatewayEvent extends HTTPEvent {}
export interface TimerEvent {
  type?: 'cron' | 'every' | 'interval';
  value: string;
  payload?: string;
  version?: string;
  enable?: boolean;
}
export interface LogEvent {
  source: string;
  project: string;
  log: string;
  retryTime?: number;
  interval?: number;
  role?: string;
  version?: string;
}
export interface OSEvent {
  name?: string;
  bucket: string;
  events: string;
  filter: {
    prefix: string;
    suffix: string;
  };
  enable?: boolean;
  role?: string;
  version?: string;
}
export interface MQEvent {
  topic: string;
  tags?: string;
  region?: string;
  strategy?: string;
  role?: string;
  version?: string;
  enable?: boolean;
}

字段描述

events 是一个由不同事件（触发器）组成的对象数组。这个对象的 key 为事件类型，值为事件描述。

示例

两个函数。

functions:
  hello1:
    handler: index.handler1
    events:
      - http:                    # http 触发器
          path: /foo
          method: get
  hello3:
    handler: index.handler3
    events:
      - mq:
            topic: mytopic

HTTP 示例

functions:
  hello1:
    handler: index.handler1
    events:
      - http:
          path: /foo
          method: get,post        // 阿里云支持同时多个，腾讯只支持单个

functions:
  hello1:
    handler: index.handler1
    events:
      - http:
          path: /foo
          method: all                    // 所有method

timer 示例

service: serverless-hello-world
provider:
  name: fc
  runtime: nodejs8
  stage: dev
functions:
  hello3: 
    handler: bbbbbb
    events:
      - timer:
          type: 'cron'
          value: '0 0 8 * * *'
          payload: 'test'

layers

layer 作为 runtime 的扩展能力，用于在不同层面扩展 runtime 的接口。

结构

export interface LayersStructure {
  [layerName: string]: {
    path: string;
    name?: string;
  };
}

字段描述

layers 是一个由多个 layer 组成的对象（非数组），以 layer 名作为 key，信息作为值。

示例

layers:
  egg-layer:
    path: npm:@midwayjs/egg-layer@latest

package

用于控制打包时，包含或者忽略某些文件，以及指定打包的最终产物的名称。

示例

package:                                        # 打包配置
  include:                                        # 打包包含文件列表，默认为 package.json、构建后的代码和依赖
      - resource/*
  exclude:                                        # 打包剔除文件列表
      - test/*
  artifact: code.zip                            # 打包后的压缩包文件名

aggregation

设置聚合部署的结构，指定一些函数聚合在一起部署为一个新函数。

示例

aggregation:                                    # 聚合部署，详细内容请查看 聚合部署部分
  index:                                            # 聚合部署聚合名称
    deployOrigin: false                # 是否部署原始方法
    functions:                                # 聚合部署方法列表，比functionsPattern优先级要高
      - index                                    # 聚合部署方法名
      - hello
    functionsPattern:         # 聚合部署方法匹配规则，配置 functions 时无效
      - 'render*'             # 使用 micromatch 匹配规则，即任何以render开头的函数
      - '!render2'

resource

各个子项目依赖的资源信息配置。

custom

待定。