AWS 文档管道 Kotlin 元数据（Metadata）生成完整指南：以 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

元数据生成有三大硬性要求：

1. Specification First（规格优先）：动手前必须查阅服务规格说明书，获取精确的元数据键（metadata key）；
2. Snippet Tags 精确匹配：元数据中的 snippet tag 必须与代码中的标签逐字符一致；
3. 覆盖完整：规格中定义的全部 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}

模板中各占位符的含义与替换规则如下：

真实仓库中 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 示例代码中的标签分为四类：

操作函数标签（Action）

suspend fun {actionMethod}({service}Client: {Service}Client, param: String): {ActionName}Response { // Action implementation }

Actions 类标签

class {Service}Actions { // Actions class implementation }

场景标签（Scenario）

class {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 风格初始化；
• 挂起函数与 waiter：ddb.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};实体引用，常用缩写如下：

元数据分类体系

每个元数据条目都归属于一个category，共四种：

• Actions：独立的服务操作（CreateResource、GetResource 等），对应源码中的单个操作函数；
• Scenarios：演示服务用法的多步骤工作流，对应 Actions 类 + 交互式场景类；
• Hello：简单入门示例，帮助用户快速跑通 SDK；
• Cross-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 Guide

include 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}.kt
• Actions 类：{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：示例功能的简要说明
• ✅category：Actions、Scenarios、Hello 或 Cross-service
• ✅languages.Kotlin.versions：SDK 版本信息
• ✅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。

端到端生成工作流

完整的元数据生成流程共六步：

1. 读取规格说明书：阅读scenarios/basics/{service}/SPECIFICATION.md，获取精确的元数据需求；
2. 提取元数据表：从规格书中摘出 action/scenario 与 metadata key 的对应关系；
3. 创建元数据文件：按规格键编写.doc_gen/metadata/{service}_metadata.yaml；
4. 为代码添加 snippet 标签：在所有相关 Kotlin 源文件中补齐// snippet-start/end注释；
5. 用 writeme 校验元数据：运行python -m writeme --languages Kotlin:1 --services {service}；
6. 修复校验错误：在交付前解决所有问题。

小结

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 的源码标签，作为最直观的参考对。

• 示例工程
• 教程
• 后端