AWS SDK for Java v2 Javadoc 编写指南API 分类、文档规范与代码示例实践【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2AWS SDK for Java v2本仓库是官方 AWS Java SDK 的第二代实现整个仓库包含数千个公共 API涵盖 core 核心模块、http-clients 传输层与 services 数百个服务客户端。为了让这些 API 的 Javadoc 在数量、格式与语义上保持高度一致项目在 docs/guidelines/javadoc-guidelines.md 中制定了系统化的 Javadoc 编写指南并通过 .kiro/steering/javadoc-guidelines.md 将指南自动关联到仓库内所有src/main/**/*.java源文件。读完本文你将掌握 SDK 的 API 分类注解体系SdkPublicApi/SdkProtectedApi/SdkInternalApi、公共 API 的强制文档要求、Javadoc 排版与标签规范以及可复制到生产代码中的类级、方法级与弃用方法文档示例。一、为什么 SDK v2 需要一份 Javadoc 指南AWS SDK for Java v2 是一个超大规模的多模块 Java 项目core 之下有 sdk-core、auth、regions、retries、protocols 等 20 余个子模块services 目录下包含数百个按服务划分的客户端模块s3、dynamodb、sqs、sts、lambda 等另有 services-custom 下的高封装层库如 s3-transfer-manager、dynamodb-enhanced。代码经过 codegen 代码生成器批量产出如果每个模块各自为政地写 Javadoc最终文档将杂乱无章直接影响开发者查阅 API 的效率第一句无法快速定位用途IDE 悬停提示与自动补全的可读性通过 Javadoc 工具 生成的在线 API 文档质量持续集成中 Javadoc 校验如 checkstyle / javadoc lint的可通过性。因此该指南在inclusion: fileMatch配置下通过fileMatchPattern: {**/src/main/**/*.java}将规则绑定到仓库所有主源码目录的 Java 文件从制度层面保证每个公共 API 都有合格文档。二、API 分类体系三种注解定位文档义务指南开篇即给出 SDK v2 的 API 分类法——用注解对每一个对外可见的类型进行稳定性与使用范围声明。三类注解均定义在 core/annotations 模块的software.amazon.awssdk.annotations包中且均被Documented标注因此会出现在生成的 Javadoc 页面中注解语义稳定性承诺文档义务SdkPublicApiSDK 面向用户的公共稳定 API向后兼容backward compatibleMUST必须SdkProtectedApiSDK 内部跨模块共享、不面向用户的 API必须保持向后兼容否则会破坏旧版本生成的客户端推荐SdkInternalApiSDK 内部实现仅限定义模块内使用无承诺任何版本可随时修改或删除推荐从源码看三者通过元注解层层嵌套形成了清晰的语义层级SdkPublicApi.java 声明public and stableSDK 用户构建应用时可安全使用SdkProtectedApi.java 特别强调受保护 API 是 SDK core 与生成代码之间的契约破坏性变更会破坏旧版本生成的客户端SdkInternalApi.java 则直接警告非公共 API可能在任意 minor/patch 版本中被修改或移除。除此之外仓库还提供了另外两类补充注解SdkPreviewApi预览 API不稳定可能变更见 SdkPreviewApi.javaSdkAdvancedApi面向高级用户的高级 API。在编写 Javadoc 时应先确认目标类型属于哪一分类再决定投入的文档工作量公共 API 是必修课内部 API 只需锦上添花。三、文档要求什么必须写、什么可以省略指南对必须/应当/可以三档要求界定得非常明确所有 SDK 公共 API类/接口必须有文档SDK 公共 API 中的所有公共方法必须有文档但有两类例外实现implements或覆写overrides接口方法的方法覆写父类方法的方法。这类方法通常可通过 IDE 或{inheritDoc}从被覆写的方法继承文档无需重复书写受保护 API 与内部 API文档是 recommended推荐而非 required必须高层库high-level libraries的公共 API Javadoc 应当包含代码片段——指南点名了 DynamoDB Enhanced Client 这类封装库实际上 services-custom 下的 s3-transfer-manager、s3-event-notifications 等同样遵循该惯例。四、风格指南格式、段落与句式4.1 遵循 Javadoc 标准段落用单p开头Javadoc 必须符合标准格式段落分隔符有明确的书写约定每个新段落第一段除外以单个p开头且不写闭合标签/p。指南给出的范例/** * First paragraph with no p tag. * * pSecond paragraph starts with a p tag. * * pThird paragraph also starts with a p tag. */对照仓库实践S3TransferManager.java 的类文档正是先写一句总述随后用h2小节与多个b加粗引导句组织实例化方式常见用法等分块内容块与块之间以p分隔。4.2 第一句即摘要第一句话应当是方法/类用途的摘要让读者以及 IDE 提示、搜索引擎一眼定位使用完整句子与正确的标点使用第三人称Returns the value返回……而不是祈使句 Return the value。4.3 Javadoc 标签规范标签用法补充说明param为所有参数提供清晰描述全部参数都应覆盖return描述返回值void 方法不写throws声明方法可能抛出的异常说明触发条件link/see指向相关方法/类建立 API 之间的导航关系deprecated标记弃用方法必须包含三要素见下文version/since避免使用版本信息由版本控制系统维护4.4deprecated三要素弃用方法的deprecated描述必须写清三点何时被弃用为什么弃用替代方法且必须用{link}链接指向替代品。此外还需配合Deprecated注解使用见第六节示例。五、代码片段snippet与外部片段优先原则使用snippet标签向 Javadoc 中嵌入可编译的示例代码外部代码片段external snippets应当优先于内联片段——外部片段独立存放、可被 javadoc 工具在编译期校验避免内联示例因代码库演进而悄然失效片段质量要求简洁聚焦于演示该 API 的用法可编译且正确注释充分解释关键点与代码库其余部分保持同一代码风格。仓库中 S3TransferManager.java 的类文档就是{snippet}的教科书级应用分别演示了使用 SDK 默认设置创建实例自定义S3AsyncClientCRT 客户端含targetThroughputInGbps、minimumPartSizeInBytes配置使用 S3 Multipart Async Client三种创建方式每个片段都是完整可运行的代码块。六、三份可直接复用的文档示例6.1 类文档示例含{snippet}指南给出的S3TransferManager类文档展示了公共 API 类注释的标准骨架总述 →p分段展开能力说明 → 指向配置类的{link}→ 示例片段 →see关联/** * A high-level library for uploading and downloading objects to and from Amazon S3. * This can be created using the static {link #builder()} method. * * pS3TransferManager provides a simplified API for efficient transfers between a local environment * and S3. It handles multipart uploads/downloads, concurrent transfers, progress tracking, and * automatic retries. * * pSee {link S3TransferManagerBuilder} for information on configuring an S3TransferManager. * * pExample usage: * {snippet : * S3TransferManager transferManager S3TransferManager.builder() * .s3ClientConfiguration(b - b.credentialsProvider(credentialsProvider) * .region(Region.US_WEST_2)) * .build(); * * // Upload a file * UploadFileRequest uploadRequest UploadFileRequest.builder() * .putObjectRequest(req - req.bucket(bucket).key(key)) * .source(Paths.get(file.txt)) * .build(); * * FileUpload upload transferManager.uploadFile(uploadRequest); * CompletedFileUpload uploadResult upload.completionFuture().join(); * } * * see S3TransferManagerBuilder */ SdkPublicApi public interface S3TransferManager extends SdkAutoCloseable { // ... }注意类级注解SdkPublicApi与文档的关系它把该类型标记为公共稳定 API从而触发MUST 有文档的义务同时其 javadoc 声明backward compatible也直接在生成页面中向使用者传达兼容性承诺。6.2 方法文档示例参数/返回值/异常全覆盖/** * Uploads a file from a specified path to an S3 bucket. * * pThis method handles large files efficiently by using multipart uploads when appropriate. * Progress can be tracked through the returned {link FileUpload} object. * * pExample: * {snippet : * UploadFileRequest request UploadFileRequest.builder() * .putObjectRequest(r - r.bucket(bucket-name).key(key)) * .source(Paths.get(my-file.txt)) * .build(); * * FileUpload upload transferManager.uploadFile(request); * CompletedFileUpload completedUpload upload.completionFuture().join(); * } * * param request Object containing the bucket, key, and file path for the upload * return A {link FileUpload} object to track the upload and access the result * throws S3Exception If any errors occur during the S3 operation * throws SdkClientException If any client-side errors occur * throws IOException If the file cannot be read */ FileUpload uploadFile(UploadFileRequest request);这份示例同时体现了第一句摘要、p分段、{snippet}示例、param/return/throws全覆盖。值得注意throws分层写法——服务端异常S3Exception、客户端异常SdkClientException、I/O 异常IOException分列让调用方对失败模式一目了然。6.3 弃用方法示例deprecated三要素 Deprecated/** * Returns the value of the specified header. * * pThis method provides direct access to the header value. * * param name The name of the header * return The value of the specified header * deprecated Use {link #firstMatchingHeader(String)} instead, as it properly handles * headers with multiple values. */ Deprecated String header(String name);该示例完整落实了 4.4 节的三要素要求说明弃用原因无法正确处理多值 header、给出替代方法并用{link}链接、配合Deprecated注解。唯一未显示的是何时弃用版本信息实际项目中通常以 Deprecated since SDK 2.x 之类措辞补充。七、仓库源码级佐证规范如何在真实代码中落地指南并非纸上谈兵仓库中的实际代码与之一一对应注解定义即文档范本三个注解自身的 Javadoc 就完全遵守了本指南——第一句摘要、p分段、加粗标签bStability guarantee:/b、bIMPORTANT:/b、bWARNING:/b、列表ul/li、以及see互相关联见 SdkPublicApi.java高层库大规模使用{snippet}S3TransferManager.java 的类注释与上传/下载方法注释中都嵌入了多个{snippet}块且示例代码直接使用本模块的真实 APIUploadFileRequest.builder()、LoggingTransferListener.create()等与可编译且正确的要求一致分类注解遍布全仓库在 s3-transfer-manager 模块中SdkPublicApi被用于S3TransferManager、TransferRequestOverrideConfiguration、DownloadFilter等面向用户的类型而internal包下的实现类如 GenericS3TransferManager.java、CrtS3TransferManager.java则统一标注为内部实现体现了公共 API 详写、内部 API 从简的文档分层策略团队协作入口完整指南同时存在于 docs/guidelines/javadoc-guidelines.md与之配套的还有 NamingConventions.md、ClientConfiguration.md、FavorStaticFactoryMethods.md 等编码约定文档共同构成 SDK 贡献者的编码契约aws-sdk-java-v2-general.md 则说明了在本地用 Maven 构建与验证这些代码的流程mvn clean install -pl :module -P quick --am。八、总结给 SDK 贡献者与库作者的检查清单无论你是在为本仓库贡献代码还是在自己维护的 Java 库中借鉴这套规范写 Javadoc 前请按以下清单自检分类先行用SdkPublicApi/SdkProtectedApi/SdkInternalApi明确类型归属公共 API 文档是硬性要求摘要可扫读第一句用第三人称完整句概括用途能在搜索结果和 IDE 悬停中独立成立排版统一段落以单个p开头、不写闭合标签善用ul、b组织要点标签齐全param全部参数、return非 void、throws按异常类别分层、link/see建立导航弃用必须交代替代品deprecated写清时间、原因与{link}指向的替代方法并配Deprecated示例可编译优先使用外部片段内联片段也要保证正确性并充分注释覆写免重复实现/覆写接口或父类方法时无需重复编写文档。按此规范产出的 Javadoc既是项目文档质量的保障也让 AWS SDK for Java v2 这套庞大 API 面在开发者手中保持一致的可发现性与可信赖感。【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AWS SDK for Java v2 Javadoc 编写指南：API 分类、文档规范与代码示例实践
AWS SDK for Java v2 Javadoc 编写指南API 分类、文档规范与代码示例实践【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2AWS SDK for Java v2本仓库是官方 AWS Java SDK 的第二代实现整个仓库包含数千个公共 API涵盖 core 核心模块、http-clients 传输层与 services 数百个服务客户端。为了让这些 API 的 Javadoc 在数量、格式与语义上保持高度一致项目在 docs/guidelines/javadoc-guidelines.md 中制定了系统化的 Javadoc 编写指南并通过 .kiro/steering/javadoc-guidelines.md 将指南自动关联到仓库内所有src/main/**/*.java源文件。读完本文你将掌握 SDK 的 API 分类注解体系SdkPublicApi/SdkProtectedApi/SdkInternalApi、公共 API 的强制文档要求、Javadoc 排版与标签规范以及可复制到生产代码中的类级、方法级与弃用方法文档示例。一、为什么 SDK v2 需要一份 Javadoc 指南AWS SDK for Java v2 是一个超大规模的多模块 Java 项目core 之下有 sdk-core、auth、regions、retries、protocols 等 20 余个子模块services 目录下包含数百个按服务划分的客户端模块s3、dynamodb、sqs、sts、lambda 等另有 services-custom 下的高封装层库如 s3-transfer-manager、dynamodb-enhanced。代码经过 codegen 代码生成器批量产出如果每个模块各自为政地写 Javadoc最终文档将杂乱无章直接影响开发者查阅 API 的效率第一句无法快速定位用途IDE 悬停提示与自动补全的可读性通过 Javadoc 工具 生成的在线 API 文档质量持续集成中 Javadoc 校验如 checkstyle / javadoc lint的可通过性。因此该指南在inclusion: fileMatch配置下通过fileMatchPattern: {**/src/main/**/*.java}将规则绑定到仓库所有主源码目录的 Java 文件从制度层面保证每个公共 API 都有合格文档。二、API 分类体系三种注解定位文档义务指南开篇即给出 SDK v2 的 API 分类法——用注解对每一个对外可见的类型进行稳定性与使用范围声明。三类注解均定义在 core/annotations 模块的software.amazon.awssdk.annotations包中且均被Documented标注因此会出现在生成的 Javadoc 页面中注解语义稳定性承诺文档义务SdkPublicApiSDK 面向用户的公共稳定 API向后兼容backward compatibleMUST必须SdkProtectedApiSDK 内部跨模块共享、不面向用户的 API必须保持向后兼容否则会破坏旧版本生成的客户端推荐SdkInternalApiSDK 内部实现仅限定义模块内使用无承诺任何版本可随时修改或删除推荐从源码看三者通过元注解层层嵌套形成了清晰的语义层级SdkPublicApi.java 声明public and stableSDK 用户构建应用时可安全使用SdkProtectedApi.java 特别强调受保护 API 是 SDK core 与生成代码之间的契约破坏性变更会破坏旧版本生成的客户端SdkInternalApi.java 则直接警告非公共 API可能在任意 minor/patch 版本中被修改或移除。除此之外仓库还提供了另外两类补充注解SdkPreviewApi预览 API不稳定可能变更见 SdkPreviewApi.javaSdkAdvancedApi面向高级用户的高级 API。在编写 Javadoc 时应先确认目标类型属于哪一分类再决定投入的文档工作量公共 API 是必修课内部 API 只需锦上添花。三、文档要求什么必须写、什么可以省略指南对必须/应当/可以三档要求界定得非常明确所有 SDK 公共 API类/接口必须有文档SDK 公共 API 中的所有公共方法必须有文档但有两类例外实现implements或覆写overrides接口方法的方法覆写父类方法的方法。这类方法通常可通过 IDE 或{inheritDoc}从被覆写的方法继承文档无需重复书写受保护 API 与内部 API文档是 recommended推荐而非 required必须高层库high-level libraries的公共 API Javadoc 应当包含代码片段——指南点名了 DynamoDB Enhanced Client 这类封装库实际上 services-custom 下的 s3-transfer-manager、s3-event-notifications 等同样遵循该惯例。四、风格指南格式、段落与句式4.1 遵循 Javadoc 标准段落用单p开头Javadoc 必须符合标准格式段落分隔符有明确的书写约定每个新段落第一段除外以单个p开头且不写闭合标签/p。指南给出的范例/** * First paragraph with no p tag. * * pSecond paragraph starts with a p tag. * * pThird paragraph also starts with a p tag. */对照仓库实践S3TransferManager.java 的类文档正是先写一句总述随后用h2小节与多个b加粗引导句组织实例化方式常见用法等分块内容块与块之间以p分隔。4.2 第一句即摘要第一句话应当是方法/类用途的摘要让读者以及 IDE 提示、搜索引擎一眼定位使用完整句子与正确的标点使用第三人称Returns the value返回……而不是祈使句 Return the value。4.3 Javadoc 标签规范标签用法补充说明param为所有参数提供清晰描述全部参数都应覆盖return描述返回值void 方法不写throws声明方法可能抛出的异常说明触发条件link/see指向相关方法/类建立 API 之间的导航关系deprecated标记弃用方法必须包含三要素见下文version/since避免使用版本信息由版本控制系统维护4.4deprecated三要素弃用方法的deprecated描述必须写清三点何时被弃用为什么弃用替代方法且必须用{link}链接指向替代品。此外还需配合Deprecated注解使用见第六节示例。五、代码片段snippet与外部片段优先原则使用snippet标签向 Javadoc 中嵌入可编译的示例代码外部代码片段external snippets应当优先于内联片段——外部片段独立存放、可被 javadoc 工具在编译期校验避免内联示例因代码库演进而悄然失效片段质量要求简洁聚焦于演示该 API 的用法可编译且正确注释充分解释关键点与代码库其余部分保持同一代码风格。仓库中 S3TransferManager.java 的类文档就是{snippet}的教科书级应用分别演示了使用 SDK 默认设置创建实例自定义S3AsyncClientCRT 客户端含targetThroughputInGbps、minimumPartSizeInBytes配置使用 S3 Multipart Async Client三种创建方式每个片段都是完整可运行的代码块。六、三份可直接复用的文档示例6.1 类文档示例含{snippet}指南给出的S3TransferManager类文档展示了公共 API 类注释的标准骨架总述 →p分段展开能力说明 → 指向配置类的{link}→ 示例片段 →see关联/** * A high-level library for uploading and downloading objects to and from Amazon S3. * This can be created using the static {link #builder()} method. * * pS3TransferManager provides a simplified API for efficient transfers between a local environment * and S3. It handles multipart uploads/downloads, concurrent transfers, progress tracking, and * automatic retries. * * pSee {link S3TransferManagerBuilder} for information on configuring an S3TransferManager. * * pExample usage: * {snippet : * S3TransferManager transferManager S3TransferManager.builder() * .s3ClientConfiguration(b - b.credentialsProvider(credentialsProvider) * .region(Region.US_WEST_2)) * .build(); * * // Upload a file * UploadFileRequest uploadRequest UploadFileRequest.builder() * .putObjectRequest(req - req.bucket(bucket).key(key)) * .source(Paths.get(file.txt)) * .build(); * * FileUpload upload transferManager.uploadFile(uploadRequest); * CompletedFileUpload uploadResult upload.completionFuture().join(); * } * * see S3TransferManagerBuilder */ SdkPublicApi public interface S3TransferManager extends SdkAutoCloseable { // ... }注意类级注解SdkPublicApi与文档的关系它把该类型标记为公共稳定 API从而触发MUST 有文档的义务同时其 javadoc 声明backward compatible也直接在生成页面中向使用者传达兼容性承诺。6.2 方法文档示例参数/返回值/异常全覆盖/** * Uploads a file from a specified path to an S3 bucket. * * pThis method handles large files efficiently by using multipart uploads when appropriate. * Progress can be tracked through the returned {link FileUpload} object. * * pExample: * {snippet : * UploadFileRequest request UploadFileRequest.builder() * .putObjectRequest(r - r.bucket(bucket-name).key(key)) * .source(Paths.get(my-file.txt)) * .build(); * * FileUpload upload transferManager.uploadFile(request); * CompletedFileUpload completedUpload upload.completionFuture().join(); * } * * param request Object containing the bucket, key, and file path for the upload * return A {link FileUpload} object to track the upload and access the result * throws S3Exception If any errors occur during the S3 operation * throws SdkClientException If any client-side errors occur * throws IOException If the file cannot be read */ FileUpload uploadFile(UploadFileRequest request);这份示例同时体现了第一句摘要、p分段、{snippet}示例、param/return/throws全覆盖。值得注意throws分层写法——服务端异常S3Exception、客户端异常SdkClientException、I/O 异常IOException分列让调用方对失败模式一目了然。6.3 弃用方法示例deprecated三要素 Deprecated/** * Returns the value of the specified header. * * pThis method provides direct access to the header value. * * param name The name of the header * return The value of the specified header * deprecated Use {link #firstMatchingHeader(String)} instead, as it properly handles * headers with multiple values. */ Deprecated String header(String name);该示例完整落实了 4.4 节的三要素要求说明弃用原因无法正确处理多值 header、给出替代方法并用{link}链接、配合Deprecated注解。唯一未显示的是何时弃用版本信息实际项目中通常以 Deprecated since SDK 2.x 之类措辞补充。七、仓库源码级佐证规范如何在真实代码中落地指南并非纸上谈兵仓库中的实际代码与之一一对应注解定义即文档范本三个注解自身的 Javadoc 就完全遵守了本指南——第一句摘要、p分段、加粗标签bStability guarantee:/b、bIMPORTANT:/b、bWARNING:/b、列表ul/li、以及see互相关联见 SdkPublicApi.java高层库大规模使用{snippet}S3TransferManager.java 的类注释与上传/下载方法注释中都嵌入了多个{snippet}块且示例代码直接使用本模块的真实 APIUploadFileRequest.builder()、LoggingTransferListener.create()等与可编译且正确的要求一致分类注解遍布全仓库在 s3-transfer-manager 模块中SdkPublicApi被用于S3TransferManager、TransferRequestOverrideConfiguration、DownloadFilter等面向用户的类型而internal包下的实现类如 GenericS3TransferManager.java、CrtS3TransferManager.java则统一标注为内部实现体现了公共 API 详写、内部 API 从简的文档分层策略团队协作入口完整指南同时存在于 docs/guidelines/javadoc-guidelines.md与之配套的还有 NamingConventions.md、ClientConfiguration.md、FavorStaticFactoryMethods.md 等编码约定文档共同构成 SDK 贡献者的编码契约aws-sdk-java-v2-general.md 则说明了在本地用 Maven 构建与验证这些代码的流程mvn clean install -pl :module -P quick --am。八、总结给 SDK 贡献者与库作者的检查清单无论你是在为本仓库贡献代码还是在自己维护的 Java 库中借鉴这套规范写 Javadoc 前请按以下清单自检分类先行用SdkPublicApi/SdkProtectedApi/SdkInternalApi明确类型归属公共 API 文档是硬性要求摘要可扫读第一句用第三人称完整句概括用途能在搜索结果和 IDE 悬停中独立成立排版统一段落以单个p开头、不写闭合标签善用ul、b组织要点标签齐全param全部参数、return非 void、throws按异常类别分层、link/see建立导航弃用必须交代替代品deprecated写清时间、原因与{link}指向的替代方法并配Deprecated示例可编译优先使用外部片段内联片段也要保证正确性并充分注释覆写免重复实现/覆写接口或父类方法时无需重复编写文档。按此规范产出的 Javadoc既是项目文档质量的保障也让 AWS SDK for Java v2 这套庞大 API 面在开发者手中保持一致的可发现性与可信赖感。【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考