后端云原生IaC【免费下载链接】serverless-application-modelThe AWS Serverless Application Model (AWS SAM) transform is a AWS CloudFormation macro that transforms SAM templates into CloudFormation templates.项目地址https://gitcode.com/gh_mirrors/se/serverless-application-model点击查看免费下载导读AWS Serverless Application ModelAWS SAM作为 CloudFormation 的宏macro转换器其整套AWS::Serverless::*资源规范specification由一份 JSON Schema 定义。本文以仓库文档 docs/schema.md 为主线结合仓库源码完整解析这份 schema 的生成流程它如何从 CloudFormation 资源规范、CloudFormation 官方文档与 SAM 自身文档三个数据源融合而来如何在 samtranslator/schema/schema.json 中形成最终的统一 schema以及这套机制如何支撑 IDE 智能提示、模板静态校验与自动化持续更新。读完本文你将掌握 schema 产物的构成、生成命令链与验证用法。背景SAM 规范与 JSON SchemaAWS SAM 规范SAM specification定义了AWS::Serverless::Function、AWS::Serverless::Api、AWS::Serverless::HttpApi、AWS::Serverless::StateMachine等资源的属性、事件源与Globals语法。由于 SAM 模板最终会被转换为 CloudFormation 模板因此这份规范必须同时覆盖两套语义SAM 特有的资源与属性如AWS::Serverless::Function的Events、PoliciesSAM 属性与 CloudFormation 属性之间的透传pass-through关系SAM 属性如何映射到生成的AWS::ApiGateway::RestApi等资源上。仓库用一份 JSON Schema 来机器化地表达这套规范它既是编辑器的补全/校验基础也是程序化验证 SAM 模板的依据。文档开篇即点明SAM 规范由 JSON Schema 定义这份 schema 被持续维护并定期自动更新。生成流程总览三条数据流汇成一份 Schema文档给出了 schema 生成的高层流程图Mermaid整条链路本质上分为两个合并阶段CloudFormation 侧合并awslabs/goformation项目产出的 CloudFormation JSON Schema覆盖所有AWS::*资源类型与属性类型与aws/aws-cdk项目维护的 CloudFormation 文档属性说明、类型、必填性等合并生成带文档的 CloudFormation schemacfnschemadocs。SAM 侧合并由 pydantic 模型生成的 SAM schemasamschema与 SAM 官方文档samdocs合并生成带文档的 SAM schemasamschemadocs。最终合并将带文档的 CloudFormation schema 注入 SAM schema产出同时覆盖 SAM 资源与 CloudFormation 资源、且每个属性都带 Markdown 文档的最终 schemafinal。以下各节将逐一对应仓库中的真实实现。CloudFormation Schema 生成器goformation 的 Python 移植仓库中的 schema_source/cfn_schema_generator.py 是awslabs/goformation的 Go 版 CloudFormation schema 生成器的最小可用 Python 移植模块 docstring 明确写着Minimal working port of the Go goformation schema generator。它的工作方式是拉取 AWS 官方的 CloudFormation Resource Specificationgzip JSON并转换为 JSON Schema默认数据源为官方 CDN 上的CloudFormationResourceSpecification.json见CloudFormationSchemaGenerator.__init__的spec_url参数generate()下载规格 →_generate_schema()构建 schema → 按indent4, sort_keysTrue写出 JSON并将、转义为\u003c、\u003e为了与预期输出格式一致见 cfn_schema_generator.py生成时把 CloudFormation 的类型系统映射为 JSON Schema 类型String→string、Long/Integer/Double→number、Boolean→boolean、Timestamp/Json/Map→string/object等见type_map模板主结构MAIN_SCHEMA_TEMPLATE定义了AWSTemplateFormatVersion、Description、Parameters上限 50 个、Mappings、Conditions、Outputs160 个、Resources等顶层区块且Resources的patternProperties通过anyOf引用全部资源定义为所有资源补充Type、Properties、Condition、DeletionPolicy、DependsOn、Metadata、UpdateReplacePolicy等模板级包装属性CFN_TEMPLATE_PROPERTIES对少数支持CreationPolicy/UpdatePolicy的资源如AWS::AutoScaling::AutoScalingGroup、AWS::EC2::Instance额外附加对应策略属性特殊处理多态属性PrimitiveTypes/ItemTypes等组合见_is_polymorphic与列表/映射属性并统一复用全局Tag定义。执行python3 schema_source/cfn_schema_generator.py即可在.tmp/cloudformation.schema.json生成新鲜的 CloudFormation schema见 Makefile 的fetch-schema-data目标。仓库中已落盘的产物为 schema_source/cloudformation.schema.json约 15.9 MB覆盖全部AWS::*资源。CloudFormation 文档注入CDK 文档源与合并脚本仅有类型约束还不够编辑器提示需要属性说明。仓库从aws/aws-cdk维护的 CloudFormation 文档源获取每个属性的详细描述保存在 schema_source/cloudformation-docs.json约 7.4 MB其结构为properties.ResourceType.Property到 Markdown 文本的映射。Makefile中对应的数据更新链路为update-schema-data: # 解析 CDK 文档stdin 输入 .tmp/cfn-docs.json输出 schema_source/cloudformation-docs.json bin/parse_cdk_cfn_docs.py .tmp/cfn-docs.json schema_source/cloudformation-docs.json # 将文档注入 CloudFormation schema python bin/add_docs_cfn_schema.py --schema .tmp/cloudformation.schema.json \ --docs schema_source/cloudformation-docs.json schema_source/cloudformation.schema.json于是 schema_source/cloudformation.schema.json 中的每个属性除了类型约束外还带上了title与markdownDescription例如AWS::ACMPCA::Certificate的ApiPassthrough等属性均有完整描述这正是流程图中cfnschema -- cfnschemadocs一步的实现。SAM Schema 生成pydantic 模型驱动的带文档 SAM schemaSAM 侧的核心实现在 samtranslator/internal/schema_source/schema.py 与 samtranslator/internal/schema_source/common.py。资源模型即规范每个 SAM 资源类型都对应一个 pydantic 模型文件samtranslator/internal/schema_source/ 下的aws_serverless_function.py、aws_serverless_api.py、aws_serverless_httpapi.py、aws_serverless_statemachine.py、aws_serverless_connector.py、aws_serverless_graphqlapi.py等 14 个资源模块所有模型汇总为SamModelclass SamModel(_ModelWithoutResources): Resources: dict[str, Union[Resources, any_cfn_resource.Resource]]Resources联合类型列出全部 SAM 资源模型见 schema.pyany_cfn_resource.Resource用于忽略非AWS::Serverless::*的资源即 SAM 转换不负责的普通 CloudFormation 资源也允许出现在模板中Globals模型对应Function、Api、HttpApi、WebSocketApi、SimpleTable、NetworkConnector、StateMachine、LayerVersion、CapacityProvider、MicrovmImage十类全局配置BaseModel.Config.extra forbid严格模式未知属性在 schema 校验阶段即报错。get_schema(model)调用 pydantic 的model.schema()生成 JSON Schema并做两处关键修正见 schema.py把$schema固定为http://json-schema.org/draft-04/schema#draft-04兼容性考虑删除PassThroughProp定义中的title避免 VS Code 的 YAML 插件在提示透传属性时错误地显示PassThroughProp作为标题。文档如何进入 SAM Schemacommon.py加载了仓库自带的 samtranslator/internal/schema_source/sam-docs.json对应流程图中的samdocs数据源其结构与cloudformation-docs.json类似但内容为 SAM 专属说明例如sam-property-api-apiauth: { ApiKeyRequired: If set to true then an API key is required for all API events. ... *Type*: Boolean *Required*: No ..., ... }模型中的每个属性通过_get_prop(stem, name)注入title与markdownDescription而透传属性SAM 属性直接映射到 CloudFormation 资源属性通过passthrough_prop()特殊处理它写入一个自定义标记__samPassThrough记录目标 CloudFormation schema 中的schemaPath与 SAM 侧文档覆盖值markdownDescriptionOverride留待统一合并阶段替换见 common.py。从 SAM schema 到统一 schemaschema.py的main()是最终入口对应make schemapython -m samtranslator.internal.schema_source.schema \ --sam-schema schema_source/sam.schema.json \ --cfn-schema schema_source/cloudformation.schema.json \ --unified-schema samtranslator/schema/schema.json它执行两步由SamModel生成纯 SAM schema写出到schema_source/sam.schema.json约 818 KB由Model不包含any_cfn_resource宽松项的精简模型生成统一 schema 雏形再调用extend_with_cfn_schema()完成融合见 schema.pydef extend_with_cfn_schema(sam_schema, cfn_schema): # 1. 把 CloudFormation 资源定义追加到 SAM schema 的 Resources.anyOf cfn_resources cfn_props[Resources][patternProperties][^[a-zA-Z0-9]$][anyOf] sam_props[Resources][additionalProperties][anyOf].extend(cfn_resources) # 2. 补齐顶层属性Conditions、Outputs 等 # 3. 合并 definitions重名直接抛异常防止冲突 # 4. 为受支持的 CloudFormation 资源注入 Connectors 属性嵌入式 Connector 支持 # 5. 用 __samPassThrough 标记替换为 CloudFormation 属性 schema SAM 文档覆盖 # 6. 统一 schema 全量关闭额外属性additionalProperties False其中嵌入式 Connector注入依赖 samtranslator/model/connector_profiles/profiles.json 中声明的源资源列表使相应 CloudFormation 资源获得Connectors属性支持。最终产物 samtranslator/schema/schema.json约 16.7 MB即流程图中的final同时包含 SAM 与 CloudFormation 资源定义、且每个属性带文档的 draft-04 schema。产物文件一览文件大小约内容schema_source/cloudformation.schema.json15.9 MB带文档的 CloudFormation 资源 schemacfnschemadocsschema_source/cloudformation-docs.json7.4 MBCDK 来源的 CloudFormation 属性文档schema_source/sam.schema.json818 KB带文档的 SAM 资源 schemasamschemadocssamtranslator/internal/schema_source/sam-docs.json—SAM 属性文档源samtranslator/schema/schema.json16.7 MB最终统一 schemafinal自动更新机制CI 定期重建文档明确指出 schema以固定间隔自动更新。仓库通过 Makefile 把整条数据链路封装为三个目标fetch-schema-data: # 下载 CDK 文档 运行 Python 生成器产出新 CloudFormation schema update-schema-data: # 解析文档 注入文档到 CloudFormation schema schema: # 生成 sam.schema.json 与统一 schema.json schema-all: fetch-schema-data update-schema-data schema # 一键全量更新仓库的 CI.github/workflows/schema.yml会定期执行schema-all将更新后的 schema 提交回仓库保证 samtranslator/schema/schema.json 始终与最新 CloudFormation 资源规范保持同步。此外仓库还通过make的check-schema见 Makefile 附近的 diff 校验在 CI 中核对已提交的 schema 是否过期——若源码模型或上游数据有更新而 schema 未重新生成diff -u会失败从而强制开发者提交时同步刷新 schema。Schema 的消费方式校验与 IDE 提示1. 程序化验证仓库内的验证器是 samtranslator/validator/validator.py 的SamTemplateValidator基于jsonschema库Draft7Validator 扩展默认加载 samtranslator/validator/sam_schema/schema_new.json并通过RefResolver解析definitions/目录下的api.json、cfn.json、common.json、parameter.json子 schema跨平台路径安全地以文件名作为$ref键为校验器重定义了类型检查器object类型排除只含单个 intrinsic 键Ref、Fn::If、Fn::GetAtt等的字典另增intrinsic类型——这样模板中大量使用的 intrinsic 函数不会被误判为对象或字符串见is_object/is_intrinsic/has_intrinsic_attrintrinsic 全集在INTRINSIC_ATTRschema_new.json顶层还利用 draft-07 的if/then/else约束资源Type命名规范Custom::X自定义资源、X::Y::Z标准 CloudFormation 资源、AWS::Serverless::*枚举白名单。调用方式旧式静态方法已标记 deprecated但保持向后兼容validator SamTemplateValidator() errors validator.get_errors(template_dict)2. 编辑器智能提示sam.schema.json与最终schema.json中每个属性都带titlemarkdownDescription可直接配置到 VS Code 等编辑器的 YAML JSON Schema 关联中实现 SAM 模板编写时的属性补全、文档悬浮提示与错误标红。3. 测试保障仓库用 tests/schema/test_validate_schema.py 对 schema 本身做回归验证把 tests/translator/input/、tests/validator/input/、integration/resources/templates下数百个 YAML 模板逐一用jsonschema.validate跑sam.schema.json少数已知不匹配用例显式跳过见SKIPPED_TESTS对统一 schema 额外验证结构顶层 10 个属性齐全、Resources.anyOf引用数 1000、SAM 定义集合被统一 schema 完全包含等见test_structure提供正反样例test_sanity_valid/test_sanity_invalid确认统一 schema 对 SAM 与 CloudFormation 资源的未知属性、缺失必填属性、错误类型都能正确报错。Makefile 中make默认还会执行python -m samtranslator.internal.schema_source.schema ...并diff -u校验已提交 schema 与重新生成结果一致从机制上保证源码模型 ↔ schema 产物永不漂移。小结docs/schema.md描绘的虽然只是一条简短的高层流程但其背后是仓库中一条完整、可复现、可持续的工程链路数据源goformation 风格的 CloudFormation schemaschema_source/cfn_schema_generator.py CDK 来源的文档schema_source/cloudformation-docs.json SAM 文档samtranslator/internal/schema_source/sam-docs.json生成pydantic 资源模型samtranslator/internal/schema_source/→ SAM schema再经extend_with_cfn_schema融合为统一 schemasamtranslator/schema/schema.json更新make schema-all一键重建CI 定期自动刷新消费编辑器补全/校验、SamTemplateValidator程序化验证、以及 tests/schema/test_validate_schema.py 的全量模板回归测试。理解这条链路后无论是调试 SAM 模板校验报错、为编辑器配置 schema 提示还是给仓库新增 SAM 资源属性改模型 →make schema→ 提交新 schema都能精准定位到对应环节。赞分享后端云原生IaC【免费下载链接】serverless-application-modelThe AWS Serverless Application Model (AWS SAM) transform is a AWS CloudFormation macro that transforms SAM templates into CloudFormation templates.项目地址https://gitcode.com/gh_mirrors/se/serverless-application-model点击查看免费下载相关推荐Pydantic JSON Schema 生成与自定义完全指南从模型到规范化的 JSON SchemaPydantic JSON Schema 生成与自定义完全指南从模型到规范化的 JSON Schema Pydantic 能从模型自动生成并深度定制 JSON后端序列化Trigger.dev schema-to-json 深度解析多 Schema 校验库到 JSON Schema 的统一转换与版本演进Trigger.dev schema to json 深度解析多 Schema 校验库到 JSON Schema 的统一转换与版本演进 trigger.deAI Agent后端任务调度开发工具可观测性AI 应用vega-schema解析 Vega 可视化规范的 JSON Schema 生成器vega schema解析 Vega 可视化规范的 JSON Schema 生成器 本指南围绕 Vega 可视化语法项目中 packages/vega sch数据可视化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
