基于 OpenAPI 规范生成亚马逊广告（Amazon Ads）Java SDK

基于 OpenAPI 规范生成亚马逊广告（Amazon Ads）SDK 的工程化实践

注意：JDK最低要求11，本演示使用JDK17进行，可以在配置中指定JDK的位置。

一、背景：为什么需要自己生成 Amazon Ads SDK

在实际项目中接入Amazon Ads API时，通常会遇到几个现实问题：

1. 接口数量极多
   • Sponsored Products
   • Sponsored Brands
   • Sponsored Display
   • Reports
   • Profiles / OAuth
2. 官方 Java SDK 更新慢
3. 手写接口：
   • 参数易错
   • DTO 维护成本高
   • Ads API 升级时改动巨大
4. 多项目、多系统复用成本高

👉 本质问题只有一个：

接口是标准的，但我们一直在“重复造轮子”。

---

二、Amazon Ads 官方 OpenAPI 规范能力

Amazon Ads 官方已经提供了完整的 OpenAPI 规范文件：

• OpenAPI JSON 下载地址
  https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/AmazonAdsAPIALLMerged_prod_3p.json
• 官方 API 文档
  https://advertising.amazon.com/API/docs/en-us/amazon-ads/1-0/apis

这个 JSON 文件中已经完整描述了：

• 所有 API Path
• Request / Response Model
• 参数校验规则
• HTTP Method 与返回码

👉 这意味着：
Amazon Ads API 天然适合“代码生成”。

---

三、为什么选择 OpenAPI Generator

我们最终选择了openapi-generator，原因非常明确：

• 支持 OpenAPI 3.x
• 支持 Java / Spring 生态
• 可生成完整 Maven 工程
• 可作为 SDK 独立发布
• 最主要的是官方也是使用这个工具去生成的但是生成的JS，并不是Java

相比手写接口，生成 SDK 可以解决：

问题	生成 SDK 的价值
DTO 重复维护	自动生成
参数错误	编译期校验
接口升级	重新生成即可
多项目复用	Maven 依赖
团队协作	统一协议

---

四、工程化目标设计

在实践中，我们给自己设定了几个明确目标：

• ✅ 使用JDK 17
• ✅ SDK 与业务系统解耦
• ✅ 可独立打包为Jar
• ✅ 通过Maven 依赖引入
• ❌ 不把业务逻辑写进 SDK
• ❌ 不在 SDK 中处理 OAuth

最终定位很清晰：

SDK = 协议层（HTTP + Model），不是业务层

---

五、生成 Amazon Ads Java SDK（实战）

cli可以去maven仓库下载，地址：https://mvnrepository.com/artifact/org.openapitools/openapi-generator-cli/7.18.0

准备：
1、下载好生成器openapi-generator-cli.jar
2、openapi规范文件，AmazonAdsAPIALLMerged_prod_3p.json
准备好以上的文件之后可以进行下面的步骤了。

1. 使用 openapi-generator-cli

注意：

# 设置 JDK 路径（根据实际情况调整）$JAVA_HOME="C:\Users\Administrator\.jabba\jdk\zulu@1.17.0-0"# 执行生成命令&"$JAVA_HOME\bin\java.exe"`-jar openapi-generator-cli.jar generate`-i AmazonAdsAPIALLMerged_prod_3p.json`-g java`-o amazon-ads-client`--library resttemplate`--group-id com.sifan.integration`--artifact-id amazon-ads-client`--artifact-version1.0.0`--api-package com.sifan.integration.amazonads.api`--model-package com.sifan.integration.amazonads.model`--invoker-package com.sifan.integration.amazonads.client`--additional-propertiesjava17=true,useJakartaEe=true,dateLibrary=java8,serializationLibrary=jackson,hideGenerationTimestamp=true ` --skip-validate-spec

这一步会直接生成一个完整的 Maven Java 工程。

---

2. 生成结果结构

amazon-ads-client ├── pom.xml └── src/main/java └── com/sifan/integration/amazonads ├── api ├── model └── client

此时它已经具备了：

• Api 接口类
• Request / Response Model
• HTTP Client 封装

下面是它生成后的代码结构，是一个完整的maven项目。

六、JDK 17 + Maven 打包成 SDK

由于项目目标是Java 17，需要确保 Maven 使用的 JDK 也是 17。

mvn cleaninstall-DskipTests

成功后即可得到：

amazon-ads-client-1.0.0.jar

并自动安装到本地 Maven 仓库。

---

七、在业务系统中使用 SDK

在主系统中，只需要像普通依赖一样引入：

<dependency><groupId>com.sifan.integration</groupId><artifactId>amazon-ads-client</artifactId><version>1.0.0</version></dependency>

然后在manager 层封装使用：

@ComponentpublicclassSponsoredProductsManager{privatefinalCampaignsApicampaignsApi;publicSponsoredProductsManager(ApiClientapiClient){this.campaignsApi=newCampaignsApi(apiClient);}}

👉 OAuth、Token 刷新、Header 注入全部放在业务系统中完成，SDK 保持“纯净”。

---

八、生成 SDK 带来的实际收益

1️⃣ 开发效率显著提升

• 不再手写几十上百个接口
• DTO 全自动生成
• IDE 自动补全参数

2️⃣ 降低维护成本

• Amazon Ads API 升级 → 重新生成 SDK
• 不再人工 diff 接口变更

3️⃣ 工程结构更清晰

• Ads SDK = 基础设施
• 业务系统 = 业务逻辑
• 职责边界明确

4️⃣ 避免重复造轮子

• 一个 SDK
• 多个系统复用
• 多人协作无冲突

---

九、总结

Amazon Ads API 本身已经通过 OpenAPI 规范标准化，与其手写接口、维护 DTO，不如直接用规范驱动代码生成。

通过 openapi-generator 生成 Amazon Ads SDK，并以 Maven 依赖的形式引入系统，是一种：

更工程化、更稳定、长期成本更低的解决方案。

这套方式不仅适用于 Amazon Ads，也同样适用于SP-API(官方有提供SDK)*、第三方平台 API、内部微服务 SDK。