Serverless Framework Compose 完全指南多服务编排、依赖管理与共享状态【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverlessServerless Framework Compose 是 Serverless Framework 内置的多服务编排能力允许你在 monorepo 根目录用一个serverless-compose.yml管理多个 Serverless 服务实现并行部署、按依赖排序部署、跨服务输出共享以及跨多个服务的统一命令执行。本文以官方指南 Compose 文档 为主体结合仓库中sf-core运行器的源码实现compose.js、index.js与集成测试深入讲解 Compose 的配置语法、依赖解析、共享状态机制与各类命令的正确用法读完后可直接落地到多服务 monorepo 的部署编排。一、Compose 解决什么问题在较大团队中monorepo 内包含多个 Serverless 服务是常见模式。Compose 旨在简化和编排多个服务的部署让你可以并行部署多个服务Deploy multiple services in parallel按特定顺序部署服务Deploy services in a specific order混合部署不同类型的服务传统 Serverless 服务、SAM 或 CloudFormation 服务可放在一起跨服务共享输出Share outputs from one service to another跨多个服务运行命令Run commands across multiple services注意版本前提此处文档描述的 Compose 自 Serverless Frameworkv4.3.1起可用参见 v4 升级指南。更早的 v3.15.0 虽已引入 Compose但不在本文档覆盖范围内。二、Setup创建 Compose 项目假设你的应用包含多个 Serverless Framework 服务目录结构如下my-app/ service-a/ src/ ... serverless.yml service-b/ src/ ... serverless.yml在 monorepo 根目录创建一个serverless-compose.yml通过相对路径引用各个服务# serverless-compose.yml services: service-a: path: service-a service-b: path: service-bJS/TS 配置文件同样受支持文件名为serverless-compose.{yml,ts,js,json}。从源码看Compose 运行器通过类属性static configFileNames [serverless-compose]来识别配置文件前缀见 compose.js#L46并在shouldRun中判断!!config.services来决定是否按 Compose 项目运行见 compose.js#L49-L51。此外还支持--config/-c选项显式指定 Compose 配置文件路径见 compose.js#L53-L55集成测试中正是用c: configFilePath这样传入的见 simple-compose.test.js#L47-L56。一个值得注意的边界约束Compose 项目不允许嵌套在另一个 Compose 项目内运行。运行器在启动时会检查isWithinCompose若为真则抛出NESTED_COMPOSE_PROJECT错误见 compose.js#L73-L80。三、Usage一次性部署所有服务无需进入每个服务目录分别执行serverless deploy直接在根目录运行serverless deploy即可部署所有服务$ serverless deploy Serverless ϟ Compose Serverless Compose enables you to deploy multiple services in one command, in parallel, or ordered by dependencies. Docs: https://www.serverless.com/framework/docs/guides/compose ✔ service-a output1: ... output2: ... ✔ service-b output1: ... output2: ... Results: 2 services succeeded, 0 failed, 0 skipped, 2 total Time: 38s这段输出的各部分都有源码对应交互模式下首次deploy会打印一段介绍性文字见 compose.js#L288-L300每个服务成功后打印✔ 服务名及其输出键值见 index.js#L425-L447末尾的Results: ... succeeded, ... failed, ... skipped, ... total Time: ...汇总行由printRunReport生成见 index.js#L800-L818。四、跨服务变量${service.output}语法服务变量Service variables用于控制部署顺序并把一个服务的输出注入另一个服务。语法为${service.output}services: service-a: path: service-a service-b: path: service-b params: queueUrl: ${service-a.queueUrl}拆分为 3 个步骤理解第 1 步${service-a.queueUrl}会解析为service-a的queueUrl输出。Serverless 服务的输出解析自其CloudFormation Outputs。在service-a/serverless.yml中暴露该输出# service-a/serverless.yml # ... resources: Resources: MyQueue: Type: AWS::SQS::Queue # ... Outputs: queueUrl: Value: !Ref MyQueue第 2 步由于变量引入了依赖serverless deploy会自动先部署service-a再部署service-b。第 3 步解析出的值会作为名为queueUrl的参数parameter传给service-b参数机制详见 参数文档。参数在 Serverless 配置中通过${param:xxx}引用# service-b/serverless.yml provider: environment: # 把队列 URL 注入为 Lambda 环境变量 SERVICE_A_QUEUE_URL: ${param:queueUrl}跨服务变量是共享 API URL、队列 URL、数据库表名等资源的理想方式无需硬编码资源名或依赖 SSM。包与打印时的特殊行为对于serverless package和serverless print跨服务值从上一次部署的 state 中读取package要求被引用的服务已经部署过print对尚不存在的值显示NOT_AVAILABLE_IN_PRINT_COMMAND。源码印证了这些行为——运行器内置正则composeParamRegex /(?\$\{)[a-zA-Z0-9-]\.[a-zA-Z0-9-](?\})/识别${service.output}引用见 index.js#L18在执行图遍历时若引用值缺失print命令会注入字面量NOT_AVAILABLE_IN_PRINT_COMMAND见 index.js#L340-L342remove则注入空字符串以保证拆除流程不被阻断见 index.js#L343-L353而其他命令若依赖服务没有部署状态会抛出明确的错误提示先用serverless deploy --servicedep部署或用serverless dep info刷新其 state见 index.js#L371-L383若依赖服务已有状态但引用的输出键不存在通常是拼写错误错误信息会列出该服务当前可用的输出名方便排查见 index.js#L354-L370。五、显式依赖dependsOn如果只需要控制顺序而不需要传递值可用dependsOn选项声明显式依赖services: service-a: path: service-a service-b: path: service-b dependsOn: service-a service-c: path: service-c service-d: path: service-d dependsOn: - service-a - service-c如上例所示dependsOn既可写为字符串单个依赖也可写为列表多个依赖。源码级原理Compose 将两个来源的依赖合并进一个依赖集合——扫描每个服务的params等输入字段中所有${...}引用取.前的部分作为被引用服务名以及dependsOn声明的字符串或列表见 index.js#L98-L159。随后基于dagrejs/graphlib构建有向图见 index.js#L169-L188并用alg.isAcyclic做循环依赖校验一旦发现环会抛出COMPOSE_GRAPH_CIRCULAR_DEPENDENCY错误列出每条环的正反两个方向例如a -- b -- c -- a见 index.js#L197-L216。引用的服务若不存在于 Compose 配置中也会报错提示COMPOSE_GRAPH_SERVICE_DEPENDENCY_DOES_NOT_EXIST。部署顺序的执行方式也值得了解executeComponentsGraph从图的“无依赖节点”出发每完成一层就从图中移除这些节点并递归执行下一层同一层内的节点通过Promise.allSettled并行执行见 index.js#L272-L519。特别注意remove命令会反转拓扑顺序reverse true从graph.sources()开始拆保证先拆掉依赖方、再拆被依赖方见 index.js#L283-L286。六、全局命令Global commands除serverless deploy外以下命令可以跨所有服务全局执行命令作用serverless info查看所有服务的 infoserverless remove移除所有服务serverless print打印所有服务的配置serverless package打包所有服务源码中这份白名单是硬编码的supportedComposeCommands [deploy, info, remove, print, package]见 compose.js#L17-L23serverless help在 Compose 项目下也会展示同样的五个命令与--stage、--region、--service、--verbose、--debug等全局选项见 help.js#L13-L34。如果在不指定服务的情况下运行了白名单之外的命令Compose 会报错并给出提示例如把该命令作为单服务命令执行的写法见 compose.js#L205-L210。七、服务级命令Service-specific commands可以只针对某个服务运行命令。例如只部署一个服务serverless deploy --serviceservice-a # 快捷写法 serverless service-a deploy或跟踪单个函数的日志serverless logs --serviceservice-a --functionindex # 快捷写法 serverless service-a logs --functionindex所有Serverless Framework 命令都只能通过服务级命令形式执行包括插件的自定义命令例如serverless service-a offline从源码看快捷写法serverless service command的实现是若命令的第一个词恰好是 Compose 配置中的服务名则把它改写为options.service并从命令序列中剥离见 compose.js#L170-L177如果这个词不是已知服务但又是合法的框架命令名会提示The service ... does not exist in the Compose configuration见 compose.js#L178-L192。对dev这类交互式单服务命令Compose 有专门的教育性报错直接列出每个服务对应的启动命令如serverless service dev见 compose.js#L193-L204。在子集服务上运行命令--service接受逗号分隔的列表可一次性对多个命名服务执行命令serverless deploy --serviceservice-a,service-d命令精确作用于你命名的服务并在这些服务之间按依赖关系dependsOn与${service.output}引用排序——被依赖的服务先执行。未命名的服务完全不受影响既不会被部署也不会被移除但它们的输出仍可用于${param:xxx}解析即这些未命名依赖会先执行一次只读的 state 读取因此子集可以依赖已经在别处部署好的服务。典型场景项目内不同服务生命周期不同——例如把应用服务部署到个人/预览 stage同时保留一个共享的长生命周期服务不动serverless deploy --serviceservice-a,service-d --stage my-feature同样的列表写法也适用于remove、info、print、package。源码印证parseServiceOption负责把逗号列表解析成服务名数组见 compose.js#L120-L128若--service提供了值却解析不出任何有效服务名如--service,Compose 会显式报错而不是静默展开到全图见 compose.js#L224-L231。子集执行的完整语义在executeSubsetComponents中实现先对命名服务的传递闭包依赖做一轮只读get-state预热然后重建一张只含命名服务及其内部边的图再执行从而保证“绝不部署/移除未命名服务”的精确集合语义见 index.js#L672-L767。同时要注意子集列表只对全局命令开放——单服务交互命令如dev不能对列表展开会直接报错见 compose.js#L264-L276。使用参数时的服务级命令serverless service-a deploy等价于在 service-a 目录里运行serverless deploy两者皆可。但有一个关键区别如果 service-a 使用${param:xxx}引用了由serverless-compose.yml注入的参数则必须使用serverless service-a deploy——因为${param:xxx}只能在 Serverless Framework Compose 上下文中解析。此时所有命令都必须从根目录以serverless service-a command的形式运行。八、共享 StateShared State随着共享 State 的引入跨团队部署多个服务的协作体验显著改善。早期版本的 Compose 使用本地 state 管理在多个人或多个 CI/CD 系统独立部署服务时存在明显局限。共享 State 的核心收益改善协作输出始终保持同步。一个人部署了某服务后其输出对其他成员立即可用且一致。无需输出同步命令过去本地 state 需要serverless outputs和serverless refresh-outputs这类手动同步命令。这些命令已弃用因为共享 State 会实时自动保持同步。旧版 Compose 依赖的本地 state 已弃用由共享 State 取代去掉了手动刷新的环节简化了跨多个服务的部署编排流程。更多细节见 State 文档。源码印证运行器通过resolveStateStore从 resolver 提供的 state 存储中取得putServiceState/getServiceState两个操作见 compose.js#L239-L250单服务命令执行前会先对其依赖服务执行只读的get-state预热路径executeSingleComponent见 index.js#L590-L652resolveConfigAndGetState在 state 读取中把“栈不存在”STACK_DOES_NOT_EXIST视为预期的“无状态”情况而不是失败其余错误限流、鉴权等则继续抛出见 state.js#L18-L60。另一个重要的实现细节是写状态白名单只有deploy、info、remove三个命令STATE_WRITER_COMMANDS返回的 state 会被持久化到 state 存储见 index.js#L20-L29。package、print、logs、invoke等命令在构造上是只读的——它们返回的 state 会被丢弃localState回退到存储中的真实数据从而避免一次只读命令伪造出的空状态把已部署的输出冲掉见 index.js#L534-L572。集成测试 fixture 也展示了共享 State 的配置方式在serverless-compose.yml顶层声明state与按 stage 的 resolver如 S3 桶作为 state 存储见 simple-compose fixture。九、配置Configurationserverless-compose.yml中支持所有 Variable Resolvers例如 SSM Parameters、Secrets Manager、自定义变量等。详见 Variable Resolvers 文档。十、Stage 专属配置stages块与serverless.yml类似可以用stages块指定按 stage 区分的配置。组合后的服务即可在各自的serverless.yml中通过${param:key}引用这些变量无需在serverless-compose.yml里显式传参# serverless-compose.yml stages: dev: params: STRIPE_API_KEY: stripe-api-dev-key prod: params: STRIPE_API_KEY: stripe-api-prod-key services: service-a: path: service-a service-b: path: service-bSTRIPE_API_KEY会根据部署目标 stage 解析并自动对两个服务可见# serverless.ymlservice-a 和 service-b 均可 functions: hello: environment: STRIPE_API_KEY: ${param:STRIPE_API_KEY} # dev 解析为 stripe-api-dev-keyprod 解析为 stripe-api-prod-key十一、向单个服务传参paramsstages块让 stage 参数对所有服务可见但如果你需要向某个服务传递非来自其他服务输出的参数可以在该服务的params段直接定义services: service-a: path: service-a params: user: ${env:USER} # 这里也可以直接使用环境变量 description: This is a hard-coded description that you can pass to your service.在 service-a 的serverless.yml中引用# service-a/serverless.yml functions: hello: environment: USER: ${param:user} DESCRIPTION: ${param:description}params的值支持任意 resolver 语法比如${env:USER}而值为${service.output}形式时才会被识别为跨服务依赖并据此排序。源码中运行器会校验params必须是对象否则报COMPOSE_CONFIGURATION_INVALID并解析出其中的服务引用形成parsedParams见 index.js#L60-L90。仓库集成测试中的 service-a/serverless.yml 正是官方文档第 1 步的实例定义AWS::SQS::Queue并在Outputs中暴露apiUrl然后被service-b以apiUrl: ${service-a.apiUrl}引用见 simple-compose fixture。十二、与serverless.yml的差异serverless-compose.yml与serverless.yml的语法和功能不同。除非文档明确说明支持否则应假设serverless.yml的特性在serverless-compose.yml中不可用。例如serverless-compose.yml中无法包含插件plugins。如需 Compose 支持的特性可通过官方渠道提交 feature request。十三、移除服务Removing services删除整个项目及其全部服务在与serverless-compose.yml相同的目录运行serverless remove它会对每个服务目录执行serverless remove且按反转拓扑顺序执行见第五节源码说明。只删除单个服务时按以下三步操作确保没有其他服务依赖它否则那些服务会被破坏运行serverless service-name remove再将该服务从serverless-compose.yml中删除。如果跳过第 1 步直接编辑serverless-compose.yml该服务的资源仍会残留在你的 AWS 账号中。请记住对每个曾经部署过的 stage 都执行上述流程。十四、FAQ多区域部署通过 Compose 能否做多区域部署可以把不同服务部署到不同区域例如frontend部署到 us-east-1、backend部署到 eu-west-3。但目前 Compose不支持把同一个服务部署到多个区域。原因是每个服务的打包产物都位于.serverless/目录若同一服务并行部署到不同区域打包产物会互相冲突、覆盖。十五、验证与测试上述行为在仓库中有集成测试背书simple-compose.test.js 通过runSfCore依次执行deploy、remove并用 AWS Lambda SDK 的GetFunctionCommand逐个校验各服务函数命名规则service-stage-function确实被创建覆盖了“Compose 根目录一次命令 → 多个服务落地”的完整闭环。其 fixture 还演示了state顶层配置、stages内按 stage 的 resolver 以及跨服务${service-a.apiUrl}引用的真实组合写法。小结Serverless Framework Compose 的价值在于把 monorepo 多服务的“部署编排”收敛到根目录的单一配置与单一命令用${service.output}隐式建模数据依赖并自动排序用dependsOn显式建模顺序约束用--servicea,b精确控制作用子集用共享 State 取代本地 state 的手动同步。落地时建议记住三条规则跨服务引用前先确保被引用服务已部署否则用serverless dep info刷新 state依赖服务未命名进子集时不会被触碰但其输出仍可被解析任何插件命令和交互式命令如dev都必须走serverless service command的单服务形式。【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考