3. 发布包结构：标准目录、元数据与资源定义

发布包是 Serverless Eventing 生命周期校验的载体。一个结构清晰、约定一致的发布包，能够确保校验工具、运行时环境和持续交付流水线对事件函数进行无歧义的解析与验证。本章定义发布包的标准目录结构、元数据文件 metadata.yaml 以及资源定义文件 resources.yaml 的规范。

3.1 标准目录结构

发布包采用扁平化与分层化相结合的目录布局，所有核心文件位于包根目录下，避免深层嵌套带来的解析歧义。标准结构如下：

eventing-package/
├── metadata.yaml          # 包元数据（必选）
├── resources.yaml         # 资源定义（必选）
├── functions/             # 函数代码目录（可选）
│   ├── order-processor/
│   │   ├── main.py
│   │   └── requirements.txt
│   └── payment-handler/
│       ├── index.js
│       └── package.json
├── schemas/               # 事件模式定义（可选）
│   ├── order.created.json
│   └── payment.failed.json
├── tests/                 # 本地测试用例（可选）
│   └── test_handlers.py
└── README.md              # 包说明文档（推荐）

3.2 元数据文件（metadata.yaml）

metadata.yaml 是发布包的身份证明，声明包的基本信息、版本、依赖关系以及校验策略。校验器在加载包时首先解析此文件，若格式或必填字段缺失，则直接拒绝整个包。

字段定义表：

示例文件：

apiVersion: eventing.io/v1
name: order-processing-package
version: 1.2.0
description: "订单处理与支付事件联动包"
maintainer:
  name: "Eventing Team"
  email: "eventing@example.com"
dependencies:
  - name: common-event-schemas
    version: ">=0.5.0"
lifecycle:
  phases:
    - validate
    - deploy
    - verify
  hooks:
    pre-validate: "scripts/pre-validate.sh"
    post-deploy: "scripts/post-deploy.sh"

3.3 资源定义文件（resources.yaml）

resources.yaml 描述发布包中包含的所有可部署资源，包括事件函数、触发器、事件源绑定以及目标服务。校验器依据此文件生成资源依赖图，并逐项检查资源定义的合法性。

资源类型与必填属性：

示例文件：

apiVersion: eventing.io/v1
kind: ResourceSet
resources:
  - type: Function
    name: order-processor
    runtime: python3.11
    handler: main.handle_order
    source: functions/order-processor
    environment:
      DB_CONNECTION_STRING: "${DB_CONNECTION_STRING}"
  - type: EventSource
    name: order-events
    type: Kafka
    config:
      topic: orders
      brokers:
        - kafka-1:9092
        - kafka-2:9092
      consumerGroup: eventing-group
  - type: Trigger
    name: order-trigger
    eventSource: order-events
    targetFunction: order-processor
    filters:
      - eventType: order.created
      - eventType: order.updated
  - type: Service
    name: inventory-service
    endpoint: http://inventory-svc:8080/api
    protocol: HTTP
    timeout: 30s

3.4 发布包结构关系图

下图展示了发布包内各文件与目录之间的逻辑关系，以及校验器如何通过 metadata.yaml 和 resources.yaml 驱动整个校验流程。

3.5 校验规则与常见错误

校验器在解析发布包结构时，会执行以下三类检查：

• 结构完整性检查：确认 metadata.yaml 和 resources.yaml 存在于根目录，且文件内容为合法的 YAML 格式。
• 字段合法性检查：验证必填字段是否存在、类型是否正确、枚举值是否在允许范围内。
• 资源引用一致性检查：确保 resources.yaml 中引用的函数名称在 functions/ 目录下有对应的代码目录，且触发器引用的事件源和函数均已定义。

通过严格遵循上述目录结构与文件规范，发布包可以在生命周期的早期阶段暴露配置错误，避免将不完整的包部署到生产环境。