当前位置：首页 > news >正文

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

news 2026/5/12 15:16:27

基于 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);}}