Wing 语言 cloud.OnDeploy 部署触发器：让代码在每次应用部署时自动执行

编程语言编译器云原生语言运行时【免费下载链接】wingA programming language for the cloud ☁️ A unified programming model, combining infrastructure and runtime code into one language ⚡项目地址https://gitcode.com/gh_mirrors/wi/wing点击查看免费下载导读cloud.OnDeploy是 Wing 标准库winglang/sdk中用于部署期执行的核心资源它把一段 inflight 代码与应用的部署生命周期绑定每当应用被部署时这段代码就会被自动运行一次。本文以 packages/winglang/sdk/src/cloud/on-deploy.md 为骨架结合 SDK 源码、平台实现与测试用例系统讲解它的基本用法、执行顺序控制executeBefore/executeAfter、完整配置项以及 Simulator 与 AWS 两个目标平台下的底层运行原理。读完后你可以在自己的 Wing 应用中编写初始化数据、清理旧资源、迁移状态等部署钩子并准确理解每个配置参数在部署时的实际作用。什么是 cloud.OnDeploycloud.OnDeploy是一个在每次应用部署时运行一段 inflight 代码的资源。它解决的核心问题是传统基础设施代码Terraform、CloudFormation只能声明资源长什么样却无法方便地在部署完成时执行一段业务逻辑而cloud.OnDeploy把部署触发器抽象为云资源让初始化、清理、迁移等一次性任务与资源编排融为一体。从抽象基类源码 packages/winglang/sdk/src/cloud/on-deploy.ts 可以看到OnDeploy继承自Resource其构造函数签名是new cloud.OnDeploy(handler: IOnDeployHandler, props?: OnDeployProps);其中handler是一个带handle()方法的 inflight 接口IOnDeployHandlerClient见 on-deploy.ts也就是你在 Wing 代码中写的inflight () { ... }闭包。它没有任何预置的 inflight 方法OnDeployInflightMethods为空枚举因为它本身只是一次性执行执行期间捕获的资源如bucket、counter通过 Wing 的 lift 机制自动完成权限与引用注入。基本用法部署时清空 Bucketcloud.OnDeploy最常见的用法是执行初始化或清理任务。下面是标准库文档中的第一个完整示例——每次应用部署时删除 Bucket 中的所有对象bring cloud; let bucket new cloud.Bucket(); // each time the application is deployed, all objects in the bucket are deleted let setup new cloud.OnDeploy(inflight () { for key in bucket.list() { bucket.delete(key); } });注意 inflight 闭包内直接调用了bucket.list()与bucket.delete(key)这与普通cloud.Function的捕获方式完全一致——Wing 编译器会自动为 OnDeploy 生成的函数授予对bucket的读写权限。该示例在仓库中也有对应的可编译验证文件 tests/doc_examples/valid/on-deploy.md_example_1/main.w由文档示例自动生成并纳入tests/valid的编译测试集确保这段代码在真实编译器下是合法可运行的。另一个真实用例出现在 tests/valid/store.wStore类在构造函数里用cloud.OnDeploy向 Bucket 预写入一个占位文件data.txt之后再允许用户在 inflight 方法中覆写该文件。这是一种典型的部署期初始化数据模式。控制执行顺序executeBefore 与 executeAfter用法示例cloud.OnDeploy通过两个可选属性控制它与其他资源的创建/更新先后关系executeBefore: [resource]——在其他资源被创建/更新之前运行本触发器executeAfter: [resource]——在其他资源被创建/更新之后运行本触发器。文档中的第二个完整示例利用计数器演示了顺序语义先执行setup1把计数器设为 10再执行setup2计数器加 1因此部署结束后计数器的值应为 11bring cloud; let counter new cloud.Counter(); let setup2 new cloud.OnDeploy(inflight () { counter.inc(); }) as setup2; let setup1 new cloud.OnDeploy(inflight () { counter.set(10); }, executeBefore: [setup2]) as setup1;该示例同样被提取为可编译验证文件 tests/doc_examples/valid/on-deploy.md_example_2/main.w。此外tests/sdk_tests/on_deploy/execute_after.test.w 展示了方向相反的executeAfter写法并用测试断言验证执行结果bring cloud; let counter new cloud.Counter(); let init1 new cloud.OnDeploy(inflight () { counter.set(10); }) as init1; let init2 new cloud.OnDeploy(inflight () { counter.inc(); }, executeAfter: [init1]) as init2; test counter { assert(counter.peek() 11); }由于init2声明在init1之后执行counter.peek()必然返回 11。两个方向相反的例子合在一起完整覆盖了顺序控制的正反语义。属性定义与底层依赖机制在抽象基类中这两个属性定义为OnDeployPropson-deploy.tsexport interface OnDeployProps extends FunctionProps { /** Execute this trigger only after these resources have been provisioned. */ readonly executeAfter?: Construct[]; /** Adds this trigger as a dependency on other constructs. */ readonly executeBefore?: Construct[]; }它们接收的是constructs.Construct数组——也就是说你可以传入仓库中任何已实例化的资源Bucket、Counter、Function 等而不是局限于 OnDeploy 实例之间。底层的实现方式因平台而异但语义一致tf-aws在 target-tf-aws/on-deploy.ts 中executeAfter会把目标构造的所有子节点中可表达 Terraform 依赖的对象ITerraformDependable收集进dependsOn数组追加到aws_lambda_invocation的depends_onexecuteBefore则反过来把 Lambda 调用数据源追加为那些子资源ITerraformResource的depends_on依赖。sim在 target-sim/on-deploy.ts 中通过 constructs 图的标准addDependency建立节点依赖Simulator 按拓扑顺序初始化资源。OnDeployProps 完整参数说明因为OnDeployProps extends FunctionPropscloud.OnDeploy除了顺序控制外还继承了函数资源的全部运行配置。以下参数均来自 cloud/function.ts 与自动生成的 API 参考 docs/api/04-standard-library/cloud/on-deploy.md参数类型默认值说明executeAfterMutArrayConstruct无额外依赖仅在这些资源完成部署后才执行触发器executeBeforeMutArrayConstruct无额外依赖把触发器作为其他构造的前置依赖envMutMapstr无环境变量传给执行函数的环境变量timeoutduration1m函数允许运行的最大时长memorynum1024分配给函数的内存单位 MBlogRetentionDaysnum30函数日志保留天数设为负数表示日志永不过期concurrencynum平台相关Simulator 上为 100同一时刻允许的最大并发调用数需要注意由于cloud.OnDeploy本质上会为每次部署生成一个可执行的函数其运行受timeout与memory约束如果部署任务耗时较长例如批量数据迁移应合理调大timeout避免部署期函数被平台超时中断。各目标平台的实现与差异Simulatorsim在 Simulator 目标下cloud.OnDeploy的实现包装了一个普通的cloud.Functiontarget-sim/on-deploy.ts并把函数句柄写入OnDeploySchemafunctionHandle字段见 schema-resources.ts。关键逻辑在 target-sim/on-deploy.inflight.tsSimulator 在初始化该资源实例时通过context.getClient(...)获取内部函数的客户端并立即调用functionClient.invoke()因此部署模拟器启动应用即触发代码执行。该文件的plan()方法始终返回UpdatePlan.REPLACE并注释说明OnDeploy runs on every deployment, so always replace即模拟器也遵循每次部署都运行的语义。对应的模拟器测试 packages/winglang/sdk/test/target-sim/on-deploy.test.ts 会启动模拟器、检查资源配置中的functionHandle字段并断言日志消息包含 inflight 闭包打印的内容。AWStf-aws 与 awscdk文档说明 AWS 实现使用 Amazon Lambda 函数并在 Terraform / CloudFormation 部署期间被调用。tf-aws 目标的源码在 target-tf-aws/on-deploy.ts 中完整展示了这一机制先创建new cloud.Function(this, Function, handler, props)把 inflight 闭包编译为一个标准 Lambda 函数再创建DataAwsLambdaInvocationaws_lambda_invocation数据源functionName指向该 Lambdainput为JSON.stringify({})即以空对象调用函数源码注释说明了设计取舍之所以选用 data source 而不是 resource是因为 data source 会在每次terraform apply时都执行如果未来希望只在满足条件时才执行可以改用aws_lambda_invocationresource。由此可以明确一个关键事实在 tf-aws 目标下cloud.OnDeploy的代码每次运行terraform apply都会重新执行包括幂等重放而不是像普通资源那样只在首次创建时运行。这在设计初始化/清理逻辑时需要留意幂等性。合成的 Terraform 结构可以通过测试快照 packages/winglang/sdk/test/target-tf-aws/snapshots/on-deploy.test.ts.snap 确认一个cloud.OnDeploy会展开为aws_lambda_functionnodejs20.x、memory_size: 1024、timeout: 60、配套的 IAM 角色/策略、CloudWatch 日志组、S3 代码资产以及data.aws_lambda_invocationinput: {}——完整的资源树FunctionInvocation也记录在 tree 快照中。tf-aws 的顺序控制在测试 packages/winglang/sdk/test/target-tf-aws/on-deploy.test.ts 中被逐一验证executeAfter: [bucket]时断言aws_lambda_invocation的depends_on包含aws_s3_bucket.my_bucket即 Lambda 调用发生在 Bucket 之后executeBefore: [bucket]时断言aws_s3_bucket的depends_on包含对data.aws_lambda_invocation...的引用即 Bucket 创建发生在 Lambda 调用之后两个场景都断言生成的aws_lambda_invocation数据源数量为 1。Azuretf-azure与 GCPtf-gcp截至当前仓库版本cloud.OnDeploy在 Azure 与 GCP 目标下尚未支持文档中标注为 Not supported yet分别由跟踪 issue 记录Azure: #3565GCP: #3564。在仓库源码的 cloud 模块注册表中ON_DEPLOY_FQN只在 simtarget-sim/app.ts与 tf-awstarget-tf-aws/platform.ts两个平台被映射这从代码层面印证了平台支持矩阵的现状。选择tf-azure/tf-gcp作为编译目标时应避免使用cloud.OnDeploy或等待对应平台的实现落地。使用建议与注意事项每次部署都运行是设计语义Simulator 的plan()返回REPLACE、tf-aws 选用aws_lambda_invocationdata source都指向同一结论——OnDeploy 不是一次性初始化而是部署钩子。代码应具备幂等性例如删除对象前先判断是否存在。善用顺序控制当初始化代码依赖某资源已就绪executeAfter或需要在资源创建前做前置准备executeBefore时务必显式声明依赖在 tf-aws 下这会被翻译为真实的 Terraformdepends_on避免部署竞态。参数按函数标准配置OnDeploy 生成的执行体受timeout、memory、env、logRetentionDays、concurrency约束长时间任务需调大timeout。注意平台支持边界目前只保证 sim 与 AWStf-aws/awscdk两个目标可用Azure、GCP 暂不支持。参考与进一步阅读标准库文档packages/winglang/sdk/src/cloud/on-deploy.md抽象基类与属性定义packages/winglang/sdk/src/cloud/on-deploy.ts函数参数来源packages/winglang/sdk/src/cloud/function.tstf-aws 实现packages/winglang/sdk/src/target-tf-aws/on-deploy.tssim 实现packages/winglang/sdk/src/target-sim/on-deploy.ts、packages/winglang/sdk/src/target-sim/on-deploy.inflight.tstf-aws 测试packages/winglang/sdk/test/target-tf-aws/on-deploy.test.tssim 测试packages/winglang/sdk/test/target-sim/on-deploy.test.ts顺序控制 SDK 测试tests/sdk_tests/on_deploy/execute_after.test.wAPI 参考docs/api/04-standard-library/cloud/on-deploy.md赞分享编程语言编译器云原生语言运行时【免费下载链接】wingA programming language for the cloud ☁️ A unified programming model, combining infrastructure and runtime code into one language ⚡项目地址https://gitcode.com/gh_mirrors/wi/wing点击查看免费下载相关推荐Wing语言CI/CD集成指南自动化部署云应用的最佳实践Wing语言CI/CD集成指南自动化部署云应用的最佳实践 Wing语言作为新兴的云原生编程语言其强大的CI/CD集成能力让开发者能够轻松实现云应用的自动化部编程语言编译器云原生语言运行时程序是如何运行的从双击图标到 CPU 执行指令的完整生命周期system-design-101 图解指南程序是如何运行的从双击图标到 CPU 执行指令的完整生命周期system design 101 图解指南 一个可执行文件静静躺在磁盘上当你双击它的那一刻编程语言编译器云原生语言运行时如何快速搭建在线问卷调查系统Vue-Questionnaire 简易教程 如何快速搭建在线问卷调查系统Vue Questionnaire 简易教程 Vue Questionnaire 是一个使用 Vue CI 开发的简易问编程语言编译器云原生语言运行时上一篇Podcastfy.ai自动扩展基于负载的容器实例动态调整下一篇Firecrawl MCP Server 在 VS Code 中的一键安装与配置完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考