基于 OpenAPI 规范生成亚马逊广告（Amazon Ads）SDK 的工程化实践
注意：JDK最低要求11，本演示使用JDK17进行，可以在配置中指定JDK的位置。
一、背景：为什么需要自己生成 Amazon Ads SDK
在实际项目中接入Amazon Ads API时，通常会遇到几个现实问题：
- 接口数量极多
- Sponsored Products
- Sponsored Brands
- Sponsored Display
- Reports
- Profiles / OAuth
- 官方 Java SDK 更新慢
- 手写接口：
- 参数易错
- DTO 维护成本高
- Ads API 升级时改动巨大
- 多项目、多系统复用成本高
👉 本质问题只有一个：
接口是标准的，但我们一直在“重复造轮子”。
二、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。
)
