编程语言编译器云原生语言运行时【免费下载链接】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 仓库中 Hangar E2E 测试框架生成的编译快照 cycle.test.w_compile_tf-aws.md 为主体完整解读tests/sdk_tests/api/cycle.test.w在wing compile -t tf-aws下合成的 Terraform 模板main.tf.json并结合 SDK 源码剖析 Wing 如何通过“手工拼接 ARN 与 URL 环境变量 lift”消除 API Gateway 与 Lambda 函数之间的 Terraform 循环依赖帮助读者掌握 Wing 在 AWS 目标下 API 资源的落地机制与快照回归测试原理。这份快照文件是什么该文件并不是手工编写的文档而是 HangarWing 工具链 E2E 测试套件见 tools/hangar/README.md自动生成的文件快照file snapshot。文件标题行本身就携带了元信息# [cycle.test.w](https://link.gitcode.com/i/248431cc098046c1007f3ee6aa2e19a1) | compile | tf-aws其含义是对测试源文件 cycle.test.w 执行compile用例、目标平台为tf-aws随后把产物目录中的关键文件逐段嵌入 Markdown 并做快照比对。生成逻辑可以从源码中得到确认tools/hangar/src/generated_test_targets.ts 中的compileTest()是快照生产者它在tests/sdk_tests目录下执行wing compile -t tf-aws产物输出到文件名.tfaws目标目录然后收集main.tf.json以及.wing目录下匹配preflight.、inflight.、extern/、proc、.Struct.js的编译产物交给createMarkdownSnapshot()写快照。tools/hangar/src/utils.ts 中的createMarkdownSnapshot()负责拼装 Markdown 标题并按toMatchFileSnapshot写入__snapshots__/test_corpus/...目录tools/hangar/src/paths.ts 定义了snapshotDir tools/hangar/__snapshots__。测试用例本身由 tools/hangar/src/generate_tests.ts 为tests/sdk_tests下每个.w文件自动生成每个文件都会得到wing compile -t tf-aws与wing test -t sim两个 vitest 用例。注意该目录传入了includeJavaScriptInSnapshots: false因此本快照只包含main.tf.json不含.wing目录下的 JS 编译产物。快照在写入前还会经过 sanitize_json_paths() 的确定性清洗理解这一点是读懂快照的关键清洗规则作用在快照中的体现asset.*key 替换为占位符屏蔽随构建变化的资产哈希aws_s3_object的key: ASSET_KEYassets/...source 替换为占位符屏蔽本地构建产物绝对路径source: ASSET_SOURCE删除terraform块与metadata.version去除 cdktf 版本与后端配置噪声快照只保留backend: local、stackName: root的元数据也就是说快照中凡是ASSET_KEY、ASSET_SOURCE之类的尖括号占位符都来自 sanitizer 而非真实 Terraform 输出。被测 Wing 源码一个刻意制造“循环”的 API 路由cycle.test.w 全文如下注释已经点明了测试意图bring cloud; bring http; bring util; // This test checks that an API can have a route whose handler // references the APIs URL. if [sim, tf-aws, awscdk].contains(target) { let api new cloud.Api(); api.get(/my_url, inflight () { return { status: 200, body: api.url }; }); test GET /my_url { let resp http.get({api.url}/my_url); assert(resp.status 200); } }这段代码在基础设施层面制造了一个天然的循环依赖api.get(/my_url, ...)会把闭包编译成一个 Lambda 函数API Gateway 的 OpenAPI 集成x-amazon-apigateway-integration.uri需要这个 Lambda 的 ARN——API 依赖 Lambda闭包内引用了api.urlLambda 的环境变量又必须注入 API 的 URL——Lambda 依赖 API。如果按 Terraform 的常规依赖建模两者会形成不可解的环。这正是cycle.test.w存在的意义验证 Wing 的tf-aws目标能合成出合法、无环的main.tf.json。下面的快照内容就是它合成的结果。快照 main.tf.json 全量解读快照正文是一份完整的 Terraform JSON 模板。为便于阅读下面按顶层块拆解并给出解码后的关键资源超长单行的 OpenAPIbody字段做展开说明其原始内容是压缩过的单行 JSON 字符串。元数据与输出{ //: { metadata: { backend: local, stackName: root }, outputs: { root: { Default: { Default: { Api: { Endpoint: { Url: Api_Endpoint_Url_473FEE9F } } } } } } }, output: { Api_Endpoint_Url_473FEE9F: { value: https://${aws_api_gateway_rest_api.Api_api_91C07D84.id}.execute-api.${data.aws_region.Region.name}.amazonaws.com/${aws_api_gateway_stage.Api_api_stage_E0FA39D6.stage_name} } } }//.metadata.outputs记录的是 Wing 应用树application tree到 Terraform 输出的映射路径root/Default/Default/Api/Endpoint/Url与每个资源内//.metadata.path一一对应。值得注意的是顶层output的 valueURL 不是引用stage.invoke_url而是用api.id、region、stage_name手工拼出来的字符串插值——这是打破循环的关键设计之一后文结合源码详述。数据源账号与区域data: { aws_caller_identity: { account: { //: { metadata: { path: root/Default/account, uniqueId: account } } } }, aws_region: { Region: { //: { metadata: { path: root/Default/Region, uniqueId: Region } } } } }这两个data源分别提供 AWS 账号 ID 与区域名。它们被用于两处“手工拼接”Lambda ARN写入 OpenAPI 集成 URI与 API 调用 URL。拼接发生在 preflightWing 编译期而非 deploy 期——源码注释明确说明了这一意图见 target-tf-aws/api.ts。资源清单快照共包含 12 个 Terraform 资源与 utils.ts 中的 tfResourcesOf() 统计口径一致即resource下的一级 keyTerraform 资源快照中的资源名职责aws_api_gateway_rest_apiApi_api_91C07D84REST API 本体body为 OpenAPI 3.0.3 规范aws_api_gateway_deploymentApi_api_deployment_7FB64CC4API 部署快照triggers.redeployment取sha256(body)aws_api_gateway_stageApi_api_stage_E0FA39D6发布阶段stage_name: prodaws_lambda_functionApi_get_my_url0_7A7AAD6C/my_url路由的 inflight 闭包aws_lambda_permissionApi_api_permission-GET-1cdff2e7_A9CF8DD9授权 API Gateway 调用 Lambdaaws_iam_role/aws_iam_role_policy/aws_iam_role_policy_attachmentApi_get_my_url0_*Lambda 执行角色、空策略、AWSLambdaBasicExecutionRole附加策略aws_cloudwatch_log_groupApi_get_my_url0_CloudwatchLogGroup_03778440Lambda 日志组保留 30 天aws_s3_bucket/aws_s3_objectCode/Api_get_my_url0_S3Object_1398834C代码桶与 Lambda 代码包对象各资源名中的 8 位大写十六进制后缀如91C07D84是对资源名计算的稳定哈希保证不同应用下命名不冲突。API 网关三件套aws_api_gateway_rest_api: { Api_api_91C07D84: { body: {...压缩的 OpenAPI 3.0.3 规范...}, lifecycle: { create_before_destroy: true }, name: api-c8f613f0 } }, aws_api_gateway_deployment: { Api_api_deployment_7FB64CC4: { lifecycle: { create_before_destroy: true }, rest_api_id: ${aws_api_gateway_rest_api.Api_api_91C07D84.id}, triggers: { redeployment: ${sha256(aws_api_gateway_rest_api.Api_api_91C07D84.body)} } } }, aws_api_gateway_stage: { Api_api_stage_E0FA39D6: { deployment_id: ${aws_api_gateway_deployment.Api_api_deployment_7FB64CC4.id}, rest_api_id: ${aws_api_gateway_rest_api.Api_api_91C07D84.id}, stage_name: prod } }三点细节值得注意create_before_destroy同时出现在rest_api与deployment上保证 API 更新时先建新资源再销毁旧资源减少部署期不可用窗口对应源码 WingRestApi._initApiGatewayRestApi()/_initApiGatewayDeployment()。deployment 的 redeployment 触发器取sha256(body)即 OpenAPI 规范内容一变就会强制重新部署而不是依赖 deployment 资源的属性 diff。stage 名固定为prod来自 shared-aws/api.ts 中的export const STAGE_NAME prod。把body字段解码后它是单行 minified JSON本例只有两条路径{ paths: { /my_url: { get: { operationId: get-my_url, responses: { 200: { description: 200 response, content: {} } }, x-amazon-apigateway-integration: { uri: arn:aws:apigateway:${data.aws_region.Region.name}:lambda:path/2015-03-31/functions/arn:aws:lambda:${data.aws_region.Region.name}:${data.aws_caller_identity.account.account_id}:function:get_my_url0-c8ebe364/invocations, type: aws_proxy, httpMethod: POST, responses: { default: { statusCode: 200 } }, passthroughBehavior: when_no_match, contentHandling: CONVERT_TO_TEXT } } }, /{proxy}: { x-amazon-apigateway-any-method: { x-amazon-apigateway-integration: { type: mock, requestTemplates: { application/json: \n {\statusCode\: 404}\n }, passthroughBehavior: never, responses: { 404: { statusCode: 404, responseTemplates: { application/json: {\statusCode\: 404, \message\: \Error: Resource not found\} } } } }, responses: { 404: { description: 404 response, headers: { Content-Type: { type: string } } } } } } }, openapi: 3.0.3 }/my_url的集成 URI 正是循环依赖的“断点”所在Lambda ARN 中的function:get_my_url0-c8ebe364是编译期直接写死的字符串region/account 用 data 源插值并不是对aws_lambda_function.Api_get_my_url0_7A7AAD6C.arn的属性引用。由此 API Gateway 在 Terraform 图中不依赖Lambda 函数资源。未定义路径则落入/{proxy}的 mock 404 集成其生成逻辑见 shared-aws/api.default.ts 中的createApiDefaultResponse()——没有 CORS 配置时即退化为快照中看到的纯 404 mock。Lambda 函数与循环的另一半aws_lambda_function: { Api_get_my_url0_7A7AAD6C: { architectures: [arm64], environment: { variables: { NODE_OPTIONS: --enable-source-maps, WING_FUNCTION_NAME: get_my_url0-c8ebe364, WING_TARGET: tf-aws, WING_TOKEN_HTTPS_TFTOKEN_TOKEN_8_EXECUTE_API_TFTOKEN_TOKEN_0_AMAZONAWS_COM_TFTOKEN_TOKEN_9: ${jsonencode(\https://${aws_api_gateway_rest_api.Api_api_91C07D84.id}.execute-api.${data.aws_region.Region.name}.amazonaws.com/${aws_api_gateway_stage.Api_api_stage_E0FA39D6.stage_name}\)} } }, function_name: get_my_url0-c8ebe364, handler: index.handler, logging_config: { log_format: JSON }, memory_size: 1024, publish: true, role: ${aws_iam_role.Api_get_my_url0_IamRole_2A08E79F.arn}, runtime: nodejs20.x, s3_bucket: ${aws_s3_bucket.Code.bucket}, s3_key: ${aws_s3_object.Api_get_my_url0_S3Object_1398834C.key}, timeout: 60, vpc_config: { security_group_ids: [], subnet_ids: [] } } }环境变量WING_TOKEN_HTTPS_TFTOKEN_TOKEN_8_...就是闭包中api.url的落地形式。它有三层含义命名规则WING_TOKEN_前缀 由 URL 字符按 ResourceNames 生成的大写下划线名非法字符被过滤.与/变成TOKEN等段因此每个不同的 token 值都有独立且确定的变量名取值方式Terraform 端是jsonencode(https://...)插值deploy 期解析为带引号的 JSON 字符串inflight 运行时代码按process.env[WING_TOKEN_...]读取见 shared-aws/api.ts 的 _liftedState()依赖方向Lambda 依赖rest_api.id与stage.stage_name但这两个资源都不反过来依赖 Lambda因为 URI 是手工拼的所以整图无环。其余参数均可在 target-tf-aws/function.ts 中找到出处runtime: nodejs20.x、handler: index.handler、architectures: [arm64]、JSON 日志格式、超时timeout: 60默认 1 分钟、内存 1024 MB、NODE_OPTIONS--enable-source-maps、以及 Cloudwatch 日志组默认 30 天保留。代码包经 createBundle TerraformAsset 打成归档上传到名为Code的 S3 桶bucket_prefix: code-c84a50b1-aws_s3_object的 key/source 即被 sanitizer 替换为ASSET_KEY/ASSET_SOURCE的那两个字段。IAM 与 Lambda 调用授权aws_iam_role: { Api_get_my_url0_IamRole_2A08E79F: { assume_role_policy: {\Version\:\2012-10-17\,\Statement\:[{\Action\:\sts:AssumeRole\,\Principal\:{\Service\:\lambda.amazonaws.com\},\Effect\:\Allow\}]} } }, aws_iam_role_policy: { Api_get_my_url0_IamRolePolicy_04BD1959: { policy: {\Version\:\2012-10-17\,\Statement\:[{\Effect\:\Allow\,\Action\:\none:null\,\Resource\:\*\}]}, role: ${aws_iam_role.Api_get_my_url0_IamRole_2A08E79F.name} } }, aws_iam_role_policy_attachment: { Api_get_my_url0_IamRolePolicyAttachment_291D6C17: { policy_arn: arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole, role: ${aws_iam_role.Api_get_my_url0_IamRole_2A08E79F.name} } }, aws_lambda_permission: { Api_api_permission-GET-1cdff2e7_A9CF8DD9: { action: lambda:InvokeFunction, function_name: ${aws_lambda_function.Api_get_my_url0_7A7AAD6C.function_name}, principal: apigateway.amazonaws.com, source_arn: ${aws_api_gateway_rest_api.Api_api_91C07D84.execution_arn}/*/GET/my_url, statement_id: AllowExecutionFromAPIGateway-GET-1cdff2e7 } }aws_iam_role_policy中的Action:none:null是空权限占位本路由未申请任何额外权限日志能力由AWSLambdaBasicExecutionRole托管策略提供aws_lambda_permission的source_arn精确到*/GET/my_url防止 API Gateway 上的其他方法越权调用该函数。资源名里的1cdff2e7是路径的 sha1 短哈希生成逻辑在 WingRestApi._addHandlerPermissions()。循环依赖是如何在源码层面被拆开的快照只是结果真正的设计在 SDK 源码里。cloud.Api的抽象定义见 cloud/api.tsurlgetter 委托给_endpointAWS 侧实现链为target-tf-aws.Api → shared-aws.Api → cloud.Api。拆环靠两个“拒绝让 Terraform 建立属性依赖”的手工构造其一Lambda ARN 手工拼接使 API 不依赖 Lambda。target-tf-aws/api.ts 的 _createApiSpecExtension() 中的注释直白了当The ARN of the Lambda function is constructed by hand so that it can be calculated during preflight, instead of being resolved at deploy time. By doing this, the API Gateway does not need to take a dependency on its Lambda functions, making it possible to write Lambda functions that reference the API Gateways URL in their inflight code.这正是快照中/{proxy}之外那条集成 URI 的由来——function:get_my_url0-c8ebe364是 preflight 已知值于是aws_api_gateway_rest_api.body里没有任何指向aws_lambda_function的引用。其二调用 URL 手工拼接使 URL 不依赖 stage 的 invoke_url。WingRestApi._constructInvokeUrl() 的注释解释了原因Intentionally not usingthis.stage.invokeUrl, it looks like its shared with theinvokeUrlfrom the api deployment, which gets recreated on every deployment. When thisinvokeUrlis referenced somewhere else in the stack, it can cause cyclic dependencies in Terraform. Hence, were creating our own url here.拼接公式为https://{api.id}.execute-api.{region}.amazonaws.com/{stageName}与快照顶层output及 Lambda 环境变量中的插值完全一致region 用data.aws_region、stageName 是常量prod因此这条 URL 的依赖链上始终不含 Lambda。其三api.url进入 inflight 闭包的 lift 通道。shared-aws/api.ts 的 onLift()/_liftedState() 定义了提升行为当闭包引用api.url时preflight 把该值作为环境变量WING_TOKEN_...命名注入宿主 Lambdainflight 代码通过process.env[...]读回。cloud.Api基类的 url getter 则保证 Wing 层api.url与这套机制对接。路由注册、OpenAPI 端点扩展、Lambda 权限的完整调用链是Api.get() → httpRequests() → addHandler() → WingRestApi.addEndpoint()target-tf-aws/api.tsApiEndpointHandler.toFunctionHandler()shared-aws/api.ts负责把 Wing 的 inflight 闭包适配为 AWS API Gateway proxy 事件的 Lambda handler。把三件事串起来Terraform 依赖图是单向的aws_api_gateway_rest_api ──┐ (body 内 ARN 为编译期字符串无属性引用) ▼ aws_api_gateway_deployment ── aws_api_gateway_stage ▲ aws_lambda_function ────────────────────┘ (环境变量 jsonencode 引用 rest_api.id / stage.stage_name) aws_lambda_permission ── aws_api_gateway_rest_api.execution_arn没有任何边回指环被消除——这就是快照能通过terraform validate级别合成的结构性原因。sim 侧验证与复现方式同一测试文件还生成了 sim 目标的执行快照 cycle.test.w_test_sim.md内容是wing test -t sim的标准化输出经 sanitizeOutput() 去除耗时等波动值pass ─ cycle.test.wsim » root/Default/test:GET --my_url Tests 1 passed (1) Snapshots 1 skipped Test Files 1 passed (1) Duration DURATION它证明在本地模拟器中路由处理函数返回api.url的断言resp.status 200真实通过与 tf-aws 编译快照构成“可部署 可运行”的双重回归保障。复现本快照的等价操作是进入tests/sdk_tests/api目录后执行wing compile cycle.test.w -t tf-awsHangar 在 runWingCommand() 中正是以该目录为工作目录、附加-t tf-aws参数调用wing二进制的。产物落在cycle.test.w.tfaws/下的main.tf.json。由于资源名哈希、资产 key 等具有确定性在 SDK 版本不变的前提下重新编译应能得到与快照一致的模板差异会由 vitest 的toMatchFileSnapshot比对捕获需要更新快照时按 vitest 常规流程以-u重新生成。小结这份 cycle.test.w_compile_tf-aws.md 是 Hangar 测试框架对wing compile -t tf-aws产物的文件快照其清洗规则ASSET_KEY占位符、剔除terraform块与版本元数据由 sanitize_json_paths() 实现保证快照可复现、可回归比对快照内容完整呈现了 Wing 在 AWS 上的 API 合成形态OpenAPI 3.0.3 规范的rest_apideploymentsha256 触发器、create_before_destroyprodstage、arm64/nodejs20.x 的 Lambda、空权限 IAM 角色、精确到方法与路径的aws_lambda_permission、代码 S3 资产桶与 30 天 CloudWatch 日志组其技术核心在于两处 preflight 期的手工拼接——Lambda ARNtarget-tf-aws/api.ts与 API URLtarget-tf-aws/api.ts——把本会形成 Terraform 环的“API ↔ Lambda”依赖降为单向引用再配合onLift的WING_TOKEN_...环境变量通道把 URL 送进 inflight 闭包对编写 Wing 应用的开发者而言这份快照也是cloud.Api在 tf-aws 目标下的“事实标准答案”当你需要审计自己 API 编译出的基础设施、排查权限或 URL 行为时可直接对照本快照逐项核验。赞分享编程语言编译器云原生语言运行时【免费下载链接】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 云 API 的 tf-aws 编译产物剖析从 post.test.w 快照看 API Gateway Lambda 落地Wing 云 API 的 tf aws 编译产物剖析从 post.test.w 快照看 API Gateway Lambda 落地 导读 本文以 Wing编程语言编译器云原生语言运行时Wing 编译快照解析cloud.Bucket.addObject 如何生成 Terraform S3 资源tf-aws 平台Wing 编译快照解析cloud.Bucket.addObject 如何生成 Terraform S3 资源tf aws 平台 本文以 Wing 仓库中的编程语言编译器云原生语言运行时Wing 编译快照解析cloud.Bucket 的 list 行为与 tf-aws Terraform 输出Wing 编译快照解析cloud.Bucket 的 list 行为与 tf aws Terraform 输出 本文以 Wing 仓库中的编译快照文件 buck编程语言编译器云原生语言运行时创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考