示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载本指南以 aws-doc-sdk-examples 仓库的steering_docs/kotlin-tech/metadata.md为核心系统讲解如何为 Kotlin SDK 示例生成并维护与 AWS 文档管道Documentation pipeline集成的元数据文件实现代码片段snippet自动抽取与跨文档交叉引用。读完本文你将掌握从服务规格说明书SPECIFICATION.md中提取元数据表、编写{service}_metadata.yaml的标准结构与字段、为 Kotlin 源码添加匹配的 snippet 标签、以及使用 writeme 工具完成校验的完整工作流。元数据在文档管道中的作用在 aws-doc-sdk-examples 仓库中每个语言版本的示例代码都会被 AWS 文档系统按需抽取、嵌入开发者指南。这种抽取依赖两层约定元数据文件位于 .doc_gen/metadata 目录下的{service}_metadata.yaml描述这个示例对应哪个服务操作、用哪个语言的哪一段代码。源码中的 snippet 标签Kotlin 源码文件里的// snippet-start:[...]与// snippet-end:[...]注释圈定可被抽取的代码区间。两者通过 snippet tag 一一对应。例如 dynamodb_metadata.yaml 中声明了dynamodb.kotlin.create_table.main而 CreateTable.kt 源码中恰好存在同名标签包裹的createNewTable函数。任何一端缺失或改名都会导致文档中示例代码无法渲染。核心原则Specification First元数据生成有三大硬性要求Specification First规格优先动手前必须查阅服务规格说明书获取精确的元数据键metadata keySnippet Tags 精确匹配元数据中的 snippet tag 必须与代码中的标签逐字符一致覆盖完整规格中定义的全部 Actions 与 Scenarios 都要纳入元数据不得遗漏。其中第一点最为关键元数据文件的存放结构约定为.doc_gen/metadata/ ├── {service}_metadata.yaml # 服务元数据文件仓库内所有服务均已按此规范落地例如.doc_gen/metadata/下的dynamodb_metadata.yaml、ec2_metadata.yaml、s3_metadata.yaml、iam_metadata.yaml、sns_metadata.yaml、sqs_metadata.yaml等。第一步从服务规格说明书提取元数据表关键步骤始终先阅读scenarios/basics/{service}/SPECIFICATION.md从中提取元数据需求。仓库中已有该规格文件的示例包括 scenarios/basics/guardduty/SPECIFICATION.md、scenarios/basics/inspector/SPECIFICATION.md 等。规格书中通常会包含一张元数据表形如## Metadata |action / scenario |metadata file |metadata key | |--- |--- |--- | |CreateDetector |{service}_metadata.yaml |{service}_CreateDetector | |GetDetector |{service}_metadata.yaml |{service}_GetDetector | |Service Basics Scenario |{service}_metadata.yaml |{service}_Scenario |这张表是元数据文件的索引清单第一列是操作/场景名第二列指定元数据写入哪个文件第三列给出必须使用的 metadata key。严禁自造元数据键规则只要规格中已定义元数据键就绝不能创建自定义键。必须原样使用规格表中的键。自造键会造成元数据与规格脱节破坏文档管道对覆盖率的统计与交叉引用。第二步编写标准元数据文件下面是在 steering_docs/kotlin-tech/metadata.md 中定义的标准 YAML 模板展示了 Actions、Scenarios、Hello 三类条目的完整写法# .doc_gen/metadata/{service}_metadata.yaml {service}_CreateResource: title: Create a {ServiceAbbrev}; resource title_abbrev: Create a resource synopsis: create a {ServiceAbbrev}; resource. category: Actions languages: Kotlin: versions: - sdk_version: 1 github: kotlin/services/{service} sdkguide: excerpts: - description: snippet_tags: - {service}.kotlin.create_resource.main services: {service}: {CreateResource} {service}_GetResource: title: Get a {ServiceAbbrev}; resource title_abbrev: Get a resource synopsis: get a {ServiceAbbrev}; resource. category: Actions languages: Kotlin: versions: - sdk_version: 1 github: kotlin/services/{service} sdkguide: excerpts: - description: snippet_tags: - {service}.kotlin.get_resource.main services: {service}: {GetResource} {service}_Scenario: title: Get started with {ServiceAbbrev}; resources title_abbrev: Get started with resources synopsis: learn the basics of {ServiceAbbrev}; by creating resources and managing them. category: Scenarios languages: Kotlin: versions: - sdk_version: 1 github: kotlin/services/{service} sdkguide: excerpts: - description: Create a {Service} actions class to manage operations. snippet_tags: - {service}.kotlin.{service}_actions.main - description: Run an interactive scenario demonstrating {Service} basics. snippet_tags: - {service}.kotlin.{service}_scenario.main services: {service}: {CreateResource, GetResource, ListResources, DeleteResource} {service}_Hello: title: Hello {ServiceAbbrev}; title_abbrev: Hello {ServiceAbbrev}; synopsis: get started using {ServiceAbbrev};. category: Hello languages: Kotlin: versions: - sdk_version: 1 github: kotlin/services/{service} sdkguide: excerpts: - description: snippet_tags: - {service}.kotlin.hello.main services: {service}: {ListResources}模板中各占位符的含义与替换规则如下占位符含义替换示例{service}服务名全小写dynamodb、ec2、s3{ServiceAbbrev}服务缩写带实体引用DDB;、EC2;、S3;{CreateResource}具体操作 API 名CreateTable、CreateInstance{ServiceAbbrev};标题/简介中使用的服务名实体DDB;真实仓库中 dynamodb_metadata.yaml 的 Kotlin 条目与模板完全吻合Kotlin: versions: - sdk_version: 1 github: kotlin/services/dynamodb sdkguide: excerpts: - description: snippet_tags: - dynamodb.kotlin.create_table.main注意sdkguide:字段本身为空这并非错误——当存在对应的 SDK 文档链接时才填充该字段详见下文Kotlin 专属字段。Snippet 标签要求让代码与元数据对上号元数据中的 snippet tag 必须能精确命中源码中的标签区间。Kotlin 示例代码中的标签分为四类操作函数标签Actionsuspend fun {actionMethod}({service}Client: {Service}Client, param: String): {ActionName}Response { // Action implementation }Actions 类标签class {Service}Actions { // Actions class implementation }场景标签Scenarioclass {Service}Scenario { // Scenario class implementation }Hello 标签suspend fun main() { // Hello implementation }真实源码验证以 kotlin/services/dynamodb 为例源码中的标签与元数据一一对应。查看 CreateTable.kt其main标签包裹的正是可复用的操作函数// snippet-start:[dynamodb.kotlin.create_table.main] suspend fun createNewTable( tableNameVal: String, key: String, ): String? { val attDef AttributeDefinition { attributeName key attributeType ScalarAttributeType.S } // ... CreateTableRequest 构建与 createTable 调用 } // snippet-end:[dynamodb.kotlin.create_table.main]该函数还示范了两个 Kotlin SDK v1 的典型写法构建者模式AttributeDefinition { ... }、CreateTableRequest { ... }使用 Kotlin DSL 风格初始化挂起函数与 waiterddb.createTable(request)是挂起调用waitUntilTableExists同步等待表进入 ACTIVE 状态见 CreateTable.kt。同目录下其他文件也遵循同一模式DeleteItem.kt、DeleteTable.kt、DescribeTable.kt、GetItem.kt、ListTables.kt、PutItem.kt、UpdateItem.kt、QueryTable.kt等均以dynamodb.kotlin.{operation}.main格式命名标签。而 EC2 的标签在 ec2_metadata.yaml 中表现为ec2.kotlin.create_instance.main、ec2.kotlin.allocate_address.main、ec2.kotlin.scenario.start_instance.main等形式对应的源码标签则散落在 kotlin/services/ec2/src/main/kotlin/com/kotlin/ec2 的各个.kt文件中。服务缩写对照表元数据的title与synopsis中使用{ServiceAbbrev};实体引用常用缩写如下服务缩写GuardDutyGDDynamoDBDDBSimple Storage ServiceS3Elastic Compute CloudEC2Identity and Access ManagementIAMKey Management ServiceKMSSimple Notification ServiceSNSSimple Queue ServiceSQSInspectorInspector元数据分类体系每个元数据条目都归属于一个category共四种Actions独立的服务操作CreateResource、GetResource 等对应源码中的单个操作函数Scenarios演示服务用法的多步骤工作流对应 Actions 类 交互式场景类Hello简单入门示例帮助用户快速跑通 SDKCross-service跨多个 AWS 服务的示例仓库中对应 .doc_gen/metadata/cross_metadata.yaml。Kotlin 专属元数据字段相比其他语言Kotlin 条目有四条固定约定SDK 版本始终使用sdk_version: 1。Kotlin 示例基于 AWS SDK for Kotlin v1即aws.sdk.kotlin.services.*包名参见 CreateTable.kt 的 import 语句。GitHub 路径统一使用kotlin/services/{service}指向仓库的 kotlin/services 目录。SDK Guideinclude sdkguide:字段——当存在对应的 SDK 文档链接时才填充模板与现有示例中多数情况下该字段为空。Snippet 标签格式固定为{service}.kotlin.{operation}.main。场景类示例使用{service}.kotlin.{service}_scenario.main或{service}.kotlin.scenario.{operation}.main后者见 EC2 的ec2.kotlin.scenario.start_instance.main。包结构与文件命名约定Kotlin 示例按如下包结构组织kotlin/services/{service}/src/main/kotlin/com/kotlin/{service}/文件命名规则Hello 示例Hello{Service}.ktActions 类{Service}Actions.kt场景{Service}Basics.kt或{Service}Scenario.kt真实目录印证了这一点kotlin/services/dynamodb下按com/kotlin/dynamodb组织源码其中包含CreateTable.kt、GetItem.kt等操作文件以及scenario/Scenario.kt、scenario/ScenarioPartiQ.kt、scenario/ScenarioPartiQLBatch.kt等场景类文件见 kotlin/services/dynamodb/src/main/kotlin/com/kotlin/dynamodb。多片段Multiple Excerpts对复杂示例可在一条元数据下声明多个 excerpts每个 excerpt 各带描述与标签。例如{service}_Scenario拆成两段先抽取 Actions 类{service}.kotlin.{service}_actions.main再抽取交互式场景{service}.kotlin.{service}_scenario.main。这在文档渲染时会将代码按职责分段展示。元数据校验必填字段清单以下字段缺一不可✅title含服务缩写的描述性标题✅title_abbrev精简标题✅synopsis示例功能的简要说明✅categoryActions、Scenarios、Hello 或 Cross-service✅languages.Kotlin.versionsSDK 版本信息✅github示例代码路径✅snippet_tags与代码标签一致✅services使用的服务操作使用 writeme 工具校验仓库在 .tools/readmes 提供了名为 writeme 的校验工具入口脚本为 writeme.py校验命令为# 校验元数据 cd .tools/readmes python -m writeme --languages Kotlin:1 --services {service}--languages Kotlin:1指定校验 Kotlin 且 SDK 版本为 1与元数据中sdk_version: 1保持一致--services {service}指定要校验的服务。常见元数据错误排查根据 steering_docs/kotlin-tech/metadata.md 的总结以下问题最容易出现❌规格已存在时使用自定义元数据键——必须改用规格表中的精确键❌代码与元数据中的 snippet 标签不匹配——标签名称必须逐字符一致❌services 部分缺少服务操作——services下列出的操作应覆盖规格要求的所有操作❌github 路径错误——指向了不存在的示例代码目录❌标题中服务缩写错误——应使用上文缩写对照表中的标准实体❌元数据结构缺少必填字段——对照必填字段清单逐项检查❌SDK 版本错误——Kotlin 必须为 1。端到端生成工作流完整的元数据生成流程共六步读取规格说明书阅读scenarios/basics/{service}/SPECIFICATION.md获取精确的元数据需求提取元数据表从规格书中摘出 action/scenario 与 metadata key 的对应关系创建元数据文件按规格键编写.doc_gen/metadata/{service}_metadata.yaml为代码添加 snippet 标签在所有相关 Kotlin 源文件中补齐// snippet-start/end注释用 writeme 校验元数据运行python -m writeme --languages Kotlin:1 --services {service}修复校验错误在交付前解决所有问题。小结Kotlin 示例元数据的生成本质上是规格驱动、键值对齐的过程规格书定义键元数据文件组织键与描述源码标签落地键writeme 工具验证键。只要严格遵循specification → metadata → snippet_tags → validation这条链路并遵守 Kotlin 专属的sdk_version: 1、kotlin/services/{service}路径与{service}.kotlin.{operation}.main标签格式就能保证每个 Kotlin 示例稳定、准确地进入 AWS 文档管道被开发者指南正确抽取和引用。新手可以直接对照 .doc_gen/metadata/dynamodb_metadata.yaml 与 kotlin/services/dynamodb 的源码标签作为最直观的参考对。赞分享示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载相关推荐Flink 命令行接口CLI完全指南作业生命周期管理与 PyFlink 作业提交Flink 命令行接口CLI完全指南作业生命周期管理与 PyFlink 作业提交 Flink 提供了内置的命令行接口Command Line Inter示例工程教程后端为什么Awesome Agent Skills是AI技术发展的里程碑1000真实技能如何改变智能助手生态为什么Awesome Agent Skills是AI技术发展的里程碑1000真实技能如何改变智能助手生态 在人工智能技术快速发展的今天 Awesome A文档知识库AI 技能如何为Sendwithus开源项目贡献新模板从设计到提交的完整指南 如何为Sendwithus开源项目贡献新模板从设计到提交的完整指南 Sendwithus开源邮件模板项目是一个由社区驱动的免费邮件模板集合为开发者和设上一篇终极ESP8266硬件解析选型、电路设计与故障排除技巧下一篇AntennaPod动画效果实现提升用户体验的过渡动画创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/7 16:10:27 · 阅读 1.2k AWS 文档管道 Kotlin 元数据（Metadata）生成完整指南：以 aws-doc-sdk-examples 为例
示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载本指南以 aws-doc-sdk-examples 仓库的steering_docs/kotlin-tech/metadata.md为核心系统讲解如何为 Kotlin SDK 示例生成并维护与 AWS 文档管道Documentation pipeline集成的元数据文件实现代码片段snippet自动抽取与跨文档交叉引用。读完本文你将掌握从服务规格说明书SPECIFICATION.md中提取元数据表、编写{service}_metadata.yaml的标准结构与字段、为 Kotlin 源码添加匹配的 snippet 标签、以及使用 writeme 工具完成校验的完整工作流。元数据在文档管道中的作用在 aws-doc-sdk-examples 仓库中每个语言版本的示例代码都会被 AWS 文档系统按需抽取、嵌入开发者指南。这种抽取依赖两层约定元数据文件位于 .doc_gen/metadata 目录下的{service}_metadata.yaml描述这个示例对应哪个服务操作、用哪个语言的哪一段代码。源码中的 snippet 标签Kotlin 源码文件里的// snippet-start:[...]与// snippet-end:[...]注释圈定可被抽取的代码区间。两者通过 snippet tag 一一对应。例如 dynamodb_metadata.yaml 中声明了dynamodb.kotlin.create_table.main而 CreateTable.kt 源码中恰好存在同名标签包裹的createNewTable函数。任何一端缺失或改名都会导致文档中示例代码无法渲染。核心原则Specification First元数据生成有三大硬性要求Specification First规格优先动手前必须查阅服务规格说明书获取精确的元数据键metadata keySnippet Tags 精确匹配元数据中的 snippet tag 必须与代码中的标签逐字符一致覆盖完整规格中定义的全部 Actions 与 Scenarios 都要纳入元数据不得遗漏。其中第一点最为关键元数据文件的存放结构约定为.doc_gen/metadata/ ├── {service}_metadata.yaml # 服务元数据文件仓库内所有服务均已按此规范落地例如.doc_gen/metadata/下的dynamodb_metadata.yaml、ec2_metadata.yaml、s3_metadata.yaml、iam_metadata.yaml、sns_metadata.yaml、sqs_metadata.yaml等。第一步从服务规格说明书提取元数据表关键步骤始终先阅读scenarios/basics/{service}/SPECIFICATION.md从中提取元数据需求。仓库中已有该规格文件的示例包括 scenarios/basics/guardduty/SPECIFICATION.md、scenarios/basics/inspector/SPECIFICATION.md 等。规格书中通常会包含一张元数据表形如## Metadata |action / scenario |metadata file |metadata key | |--- |--- |--- | |CreateDetector |{service}_metadata.yaml |{service}_CreateDetector | |GetDetector |{service}_metadata.yaml |{service}_GetDetector | |Service Basics Scenario |{service}_metadata.yaml |{service}_Scenario |这张表是元数据文件的索引清单第一列是操作/场景名第二列指定元数据写入哪个文件第三列给出必须使用的 metadata key。严禁自造元数据键规则只要规格中已定义元数据键就绝不能创建自定义键。必须原样使用规格表中的键。自造键会造成元数据与规格脱节破坏文档管道对覆盖率的统计与交叉引用。第二步编写标准元数据文件下面是在 steering_docs/kotlin-tech/metadata.md 中定义的标准 YAML 模板展示了 Actions、Scenarios、Hello 三类条目的完整写法# .doc_gen/metadata/{service}_metadata.yaml {service}_CreateResource: title: Create a {ServiceAbbrev}; resource title_abbrev: Create a resource synopsis: create a {ServiceAbbrev}; resource. category: Actions languages: Kotlin: versions: - sdk_version: 1 github: kotlin/services/{service} sdkguide: excerpts: - description: snippet_tags: - {service}.kotlin.create_resource.main services: {service}: {CreateResource} {service}_GetResource: title: Get a {ServiceAbbrev}; resource title_abbrev: Get a resource synopsis: get a {ServiceAbbrev}; resource. category: Actions languages: Kotlin: versions: - sdk_version: 1 github: kotlin/services/{service} sdkguide: excerpts: - description: snippet_tags: - {service}.kotlin.get_resource.main services: {service}: {GetResource} {service}_Scenario: title: Get started with {ServiceAbbrev}; resources title_abbrev: Get started with resources synopsis: learn the basics of {ServiceAbbrev}; by creating resources and managing them. category: Scenarios languages: Kotlin: versions: - sdk_version: 1 github: kotlin/services/{service} sdkguide: excerpts: - description: Create a {Service} actions class to manage operations. snippet_tags: - {service}.kotlin.{service}_actions.main - description: Run an interactive scenario demonstrating {Service} basics. snippet_tags: - {service}.kotlin.{service}_scenario.main services: {service}: {CreateResource, GetResource, ListResources, DeleteResource} {service}_Hello: title: Hello {ServiceAbbrev}; title_abbrev: Hello {ServiceAbbrev}; synopsis: get started using {ServiceAbbrev};. category: Hello languages: Kotlin: versions: - sdk_version: 1 github: kotlin/services/{service} sdkguide: excerpts: - description: snippet_tags: - {service}.kotlin.hello.main services: {service}: {ListResources}模板中各占位符的含义与替换规则如下占位符含义替换示例{service}服务名全小写dynamodb、ec2、s3{ServiceAbbrev}服务缩写带实体引用DDB;、EC2;、S3;{CreateResource}具体操作 API 名CreateTable、CreateInstance{ServiceAbbrev};标题/简介中使用的服务名实体DDB;真实仓库中 dynamodb_metadata.yaml 的 Kotlin 条目与模板完全吻合Kotlin: versions: - sdk_version: 1 github: kotlin/services/dynamodb sdkguide: excerpts: - description: snippet_tags: - dynamodb.kotlin.create_table.main注意sdkguide:字段本身为空这并非错误——当存在对应的 SDK 文档链接时才填充该字段详见下文Kotlin 专属字段。Snippet 标签要求让代码与元数据对上号元数据中的 snippet tag 必须能精确命中源码中的标签区间。Kotlin 示例代码中的标签分为四类操作函数标签Actionsuspend fun {actionMethod}({service}Client: {Service}Client, param: String): {ActionName}Response { // Action implementation }Actions 类标签class {Service}Actions { // Actions class implementation }场景标签Scenarioclass {Service}Scenario { // Scenario class implementation }Hello 标签suspend fun main() { // Hello implementation }真实源码验证以 kotlin/services/dynamodb 为例源码中的标签与元数据一一对应。查看 CreateTable.kt其main标签包裹的正是可复用的操作函数// snippet-start:[dynamodb.kotlin.create_table.main] suspend fun createNewTable( tableNameVal: String, key: String, ): String? { val attDef AttributeDefinition { attributeName key attributeType ScalarAttributeType.S } // ... CreateTableRequest 构建与 createTable 调用 } // snippet-end:[dynamodb.kotlin.create_table.main]该函数还示范了两个 Kotlin SDK v1 的典型写法构建者模式AttributeDefinition { ... }、CreateTableRequest { ... }使用 Kotlin DSL 风格初始化挂起函数与 waiterddb.createTable(request)是挂起调用waitUntilTableExists同步等待表进入 ACTIVE 状态见 CreateTable.kt。同目录下其他文件也遵循同一模式DeleteItem.kt、DeleteTable.kt、DescribeTable.kt、GetItem.kt、ListTables.kt、PutItem.kt、UpdateItem.kt、QueryTable.kt等均以dynamodb.kotlin.{operation}.main格式命名标签。而 EC2 的标签在 ec2_metadata.yaml 中表现为ec2.kotlin.create_instance.main、ec2.kotlin.allocate_address.main、ec2.kotlin.scenario.start_instance.main等形式对应的源码标签则散落在 kotlin/services/ec2/src/main/kotlin/com/kotlin/ec2 的各个.kt文件中。服务缩写对照表元数据的title与synopsis中使用{ServiceAbbrev};实体引用常用缩写如下服务缩写GuardDutyGDDynamoDBDDBSimple Storage ServiceS3Elastic Compute CloudEC2Identity and Access ManagementIAMKey Management ServiceKMSSimple Notification ServiceSNSSimple Queue ServiceSQSInspectorInspector元数据分类体系每个元数据条目都归属于一个category共四种Actions独立的服务操作CreateResource、GetResource 等对应源码中的单个操作函数Scenarios演示服务用法的多步骤工作流对应 Actions 类 交互式场景类Hello简单入门示例帮助用户快速跑通 SDKCross-service跨多个 AWS 服务的示例仓库中对应 .doc_gen/metadata/cross_metadata.yaml。Kotlin 专属元数据字段相比其他语言Kotlin 条目有四条固定约定SDK 版本始终使用sdk_version: 1。Kotlin 示例基于 AWS SDK for Kotlin v1即aws.sdk.kotlin.services.*包名参见 CreateTable.kt 的 import 语句。GitHub 路径统一使用kotlin/services/{service}指向仓库的 kotlin/services 目录。SDK Guideinclude sdkguide:字段——当存在对应的 SDK 文档链接时才填充模板与现有示例中多数情况下该字段为空。Snippet 标签格式固定为{service}.kotlin.{operation}.main。场景类示例使用{service}.kotlin.{service}_scenario.main或{service}.kotlin.scenario.{operation}.main后者见 EC2 的ec2.kotlin.scenario.start_instance.main。包结构与文件命名约定Kotlin 示例按如下包结构组织kotlin/services/{service}/src/main/kotlin/com/kotlin/{service}/文件命名规则Hello 示例Hello{Service}.ktActions 类{Service}Actions.kt场景{Service}Basics.kt或{Service}Scenario.kt真实目录印证了这一点kotlin/services/dynamodb下按com/kotlin/dynamodb组织源码其中包含CreateTable.kt、GetItem.kt等操作文件以及scenario/Scenario.kt、scenario/ScenarioPartiQ.kt、scenario/ScenarioPartiQLBatch.kt等场景类文件见 kotlin/services/dynamodb/src/main/kotlin/com/kotlin/dynamodb。多片段Multiple Excerpts对复杂示例可在一条元数据下声明多个 excerpts每个 excerpt 各带描述与标签。例如{service}_Scenario拆成两段先抽取 Actions 类{service}.kotlin.{service}_actions.main再抽取交互式场景{service}.kotlin.{service}_scenario.main。这在文档渲染时会将代码按职责分段展示。元数据校验必填字段清单以下字段缺一不可✅title含服务缩写的描述性标题✅title_abbrev精简标题✅synopsis示例功能的简要说明✅categoryActions、Scenarios、Hello 或 Cross-service✅languages.Kotlin.versionsSDK 版本信息✅github示例代码路径✅snippet_tags与代码标签一致✅services使用的服务操作使用 writeme 工具校验仓库在 .tools/readmes 提供了名为 writeme 的校验工具入口脚本为 writeme.py校验命令为# 校验元数据 cd .tools/readmes python -m writeme --languages Kotlin:1 --services {service}--languages Kotlin:1指定校验 Kotlin 且 SDK 版本为 1与元数据中sdk_version: 1保持一致--services {service}指定要校验的服务。常见元数据错误排查根据 steering_docs/kotlin-tech/metadata.md 的总结以下问题最容易出现❌规格已存在时使用自定义元数据键——必须改用规格表中的精确键❌代码与元数据中的 snippet 标签不匹配——标签名称必须逐字符一致❌services 部分缺少服务操作——services下列出的操作应覆盖规格要求的所有操作❌github 路径错误——指向了不存在的示例代码目录❌标题中服务缩写错误——应使用上文缩写对照表中的标准实体❌元数据结构缺少必填字段——对照必填字段清单逐项检查❌SDK 版本错误——Kotlin 必须为 1。端到端生成工作流完整的元数据生成流程共六步读取规格说明书阅读scenarios/basics/{service}/SPECIFICATION.md获取精确的元数据需求提取元数据表从规格书中摘出 action/scenario 与 metadata key 的对应关系创建元数据文件按规格键编写.doc_gen/metadata/{service}_metadata.yaml为代码添加 snippet 标签在所有相关 Kotlin 源文件中补齐// snippet-start/end注释用 writeme 校验元数据运行python -m writeme --languages Kotlin:1 --services {service}修复校验错误在交付前解决所有问题。小结Kotlin 示例元数据的生成本质上是规格驱动、键值对齐的过程规格书定义键元数据文件组织键与描述源码标签落地键writeme 工具验证键。只要严格遵循specification → metadata → snippet_tags → validation这条链路并遵守 Kotlin 专属的sdk_version: 1、kotlin/services/{service}路径与{service}.kotlin.{operation}.main标签格式就能保证每个 Kotlin 示例稳定、准确地进入 AWS 文档管道被开发者指南正确抽取和引用。新手可以直接对照 .doc_gen/metadata/dynamodb_metadata.yaml 与 kotlin/services/dynamodb 的源码标签作为最直观的参考对。赞分享示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载相关推荐Flink 命令行接口CLI完全指南作业生命周期管理与 PyFlink 作业提交Flink 命令行接口CLI完全指南作业生命周期管理与 PyFlink 作业提交 Flink 提供了内置的命令行接口Command Line Inter示例工程教程后端为什么Awesome Agent Skills是AI技术发展的里程碑1000真实技能如何改变智能助手生态为什么Awesome Agent Skills是AI技术发展的里程碑1000真实技能如何改变智能助手生态 在人工智能技术快速发展的今天 Awesome A文档知识库AI 技能如何为Sendwithus开源项目贡献新模板从设计到提交的完整指南 如何为Sendwithus开源项目贡献新模板从设计到提交的完整指南 Sendwithus开源邮件模板项目是一个由社区驱动的免费邮件模板集合为开发者和设上一篇终极ESP8266硬件解析选型、电路设计与故障排除技巧下一篇AntennaPod动画效果实现提升用户体验的过渡动画创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考