Amazon Ads API 自建 SDK 架构升级实战：从手工生成 JAR 到可追溯构建体系

导读：很多团队在对接 Amazon Ads API 时，通常用 OpenAPI Generator 手工生成几个客户端 JAR 扔进私库完事。但在实际维护中，模型字段冲突、端点更新约束、版本无法追溯与构建环境依赖等问题会接踵而至。本文复盘一次真实的 SDK 架构重构：如何把官方 OpenAPI 规范、协议适配、可追溯 Maven 构建与上游更新检测整合为一套工程化体系。

一、痛点复盘：为什么自动生成了代码，依然维护困难？

初期，我们的业务系统依赖两个手工生成的独立客户端：amazon-ads-client（管理配置）与 amazon-offline-report-client（异步报表）。

系统运行不久，便暴露了三个致命问题：

1. 读取模型 ≠\neq= 更新模型

在一次暂停广告组的操作中，请求体携带了 adProduct 字段，直接被亚马逊服务端打回：

text 复制代码

object instance has properties which are not allowed by the schema: ["adProduct"]

查询实体时包含 adProduct，但更新端点严格限制只接收白名单字段（如 adGroupId 与 state）。如果业务层直接拿通用实体做序列化，端点约束就会泛滥散落到各个业务调用方。

2. 生成器的原生缺陷

在 OpenAPI Generator（7.18.0）结合官方快照生成 Java 代码时，内联 title 经常与顶层实体发生命名覆盖（如内联 campaign 覆盖顶层 Campaign 类）。如果每次生成后靠人工打补丁，代码便彻底丧失了复现性。

3. 本地构建地狱

两个 JAR 是开发者在本地用 CLI 命令行生成并 mvn install 到本机仓库的。新同事拉下代码无法编译，CI 服务器频繁报依赖缺失；同样叫 1.0.0 的版本，不同机器上的二进制内容甚至不一致。

二、三层职责架构：生成层、协议层与宿主层

"自建 SDK"并不是从零手写底层 HTTP 传输，而是用自动生成层维护官方契约，用手写适配层收敛业务通信语义。

复制代码

 ┌──────────────────────────────────────────────────────────────┐
 │                      业务服务 (宿主层)                       │
 │  • 认证授权 (Token 管理)          • 分布式限流与监控         │
 │  • 运营意图持久化与结果审计       • 报表任务调度与 MQ 消费   │
 └──────────────────────────────┬───────────────────────────────┘
                                │
                                ▼
 ┌──────────────────────────────────────────────────────────────┐
 │                  AmazonAdsClient (协议适配层)                │
 │  • entities()        • reports()        • changeHistory()    │
 │  ──────────────────────────────────────────────────────────  │
 │  • 端点字段白名单构造 (防 adProduct 等非法字段扩散)          │
 │  • 业务结果研判 (明确划分: SUCCEEDED / FAILED / UNKNOWN)     │
 │  • 操作语义分类 (READ / CONFIGURATION_WRITE / REPORT_CREATE)  │
 └──────────────────────────────┬───────────────────────────────┘
                                │
                                ▼
 ┌──────────────────────────────────────────────────────────────┐
 │                 自动生成代码 (OpenAPI Spec 层)               │
 │  • generated.management (管理端点模型与请求基础设施)         │
 │  • generated.reporting  (报表端点模型与请求基础设施)         │
 └──────────────────────────────────────────────────────────────┘

核心分工契约

架构层次	负责核心职责	坚决不负责（防腐边界）
自动生成层	映射 OpenAPI 官方声明的方法、基础 DTO 与枚举	不介入任何字段白名单修剪、重试与状态判断
协议适配层	实体 ID/Scope 校验、操作级字段白名单、多状态结果判定	不直接存储 Token、不管理 Redis、不侵入业务持久化
宿主执行层	Token 刷新与存储、全局限流、幂等控制、操作审计与任务调度	不在各业务服务中重复编写端点协议报文与序列化逻辑

关键语义治理

白名单构造更新报文 ：针对启停等高频操作，SDK 内部显式组装只含 adGroupId 和 state 的微型载荷，彻底屏蔽查询模型的冗余字段；
拆解 HTTP 207 Multi-Status ：亚马逊批量操作返回 207 并不代表全成功。适配层必须逐项解析，明确划分出三种状态：
- SUCCEEDED：远端明确生效；
- FAILED：远端明确拒绝；
- UNKNOWN：网络超时或响应缺损（严禁自动重试，必须由宿主安排对账回读，防止重复操作）。
按操作语义（Operation）区分限流重试 ：Ads 很多查询也采用 POST，不能仅按 HTTP Method 分类。SDK 显式标注 READ、CONFIGURATION_WRITE、REPORT_CREATE，使宿主能针对读请求退避重试，而对写请求进行严格保护。

三、工程收敛：可追溯的 Maven 构建与独立发布

彻底废弃"本地 CLI 脚本生成 JAR"的不可控流程，将 Spec 规范、构建与发布收归统一的 Maven 模块。

复制代码

项目 Git 源码结构
├─ amazon-ads-sdk/
│  ├─ openapi/
│  │  ├─ management.json          # 官方管理规范快照 (保持原汁原味)
│  │  ├─ reporting.json           # 官方报表规范快照
│  │  └─ manifest.json            # 来源 URL、版本、SHA-256 校验清单
│  ├─ src/main/java/...           # 手写协议适配层代码
│  ├─ src/test/java/...           # 契约测试与官方更新检测
│  ├─ target/
│  │  ├─ openapi/                 # Maven 自动生成的规范副本 (实施内联命名修复)
│  │  └─ generated-sources/       # OpenAPI Generator 插件编译期产物 (不入 Git)
│  └─ pom.xml                     # 绑定 generate-sources 阶段

1. 规避生成器命名冲突

针对 OpenAPI Generator 将内联 campaign 覆盖顶层 Campaign 类的固有缺陷：

原始官方 JSON 在 Git 中维持字节不动；
Maven 构建时，在 target/openapi/ 生成副本，自动为冲突的内联 title 追加前缀；
生成器以副本为输入生成代码，规避人工改动 Java 代码的痛点。

2. 利用 Flatten Plugin 产出独立消费 POM

如果在多模块 ERP 中直接发布子模块，外链项目引用时会因寻找不存在的 ERP 父工程 POM 而报红。

我们在 SDK 模块引入 flatten-maven-plugin，在打包时剥离父级继承关系，将属性内联展开，生成一份纯粹干净的 consumer-pom.xml 发布至私库。外部项目只需直接声明依赖即可拉取编译，彻底解除对特定机器开发环境的绑定。

四、上游监控：用 JUnit 自动化感知官方规范演变

很多团队要么直接使用 latest 规范导致线上突发编译故障，要么把规范固化死、几年不看更新。我们设计了基于哈希校验的官方更新检测测试：

日常构建使用本地 Git 固定的快照；在 CI 阶段，通过传入 -Dads.openapi.check=true，触发 OfficialOpenApiUpdateTest 联网对比官方源。

java 复制代码

@EnabledIfSystemProperty(named = "ads.openapi.check", matches = "true")
class OfficialOpenApiUpdateTest {
    private final ObjectMapper json = new ObjectMapper();

    @TestFactory
    List<DynamicTest> officialSpecificationsMatchPinnedHashes() throws Exception {
        JsonNode manifest = json.readTree(getClass().getResourceAsStream("/META-INF/amazon-ads/openapi/manifest.json"));
        var tests = new ArrayList<DynamicTest>();

        for (JsonNode spec : manifest.required("specifications")) {
            tests.add(DynamicTest.dynamicTest(spec.required("file").asText(), () -> {
                String sourceUrl = spec.required("source").asText();
                String baselineHash = spec.required("sha256").asText();

                // 1. 联网拉取官方最新 Spec 原文
                byte[] remoteBytes = fetchRemoteBytes(URI.create(sourceUrl));

                // 2. 计算 SHA-256
                String currentHash = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(remoteBytes));

                // 3. 校验基线，若官方变更则自动落盘待审查文件并报红
                if (!baselineHash.equals(currentHash)) {
                    Path candidate = Path.of("target", "openapi-upstream", spec.required("file").asText());
                    Files.createDirectories(candidate.getParent());
                    Files.write(candidate, remoteBytes);
                    fail("官方 OpenAPI 规范已更新！待审查快照已落盘至: " + candidate);
                }
            }));
        }
        return tests;
    }
}

规范升级的标准闭环

复制代码

CI 检测到 SHA-256 改变 ➔ 测试红条并沉淀 candidate 文件 ➔ 团队审查 Diff ➔
确认采纳 ➔ 更新 Git 快照与 manifest ➔ 本地构建与回归测试 ➔ 发布 SDK 新版本

开发团队拥有了完全自主的升级审查窗口，彻底避免被动遭遇破坏性变更。

五、方案权衡与实施总结

选型方案	优势	放弃原因 / 局限性
继续手工维护 2 个裸 JAR	改动成本低	本地环境强耦合，生成代码缺陷频出，无版本可追溯性
业务服务裸拼 HTTP 请求	随用随写，单个接口快	序列化、参数校验与 207 错误语义在各微服务中重复膨胀
直接跟随 latest 自动发布	无需人工介入	缺乏人工审查窗口，上游不兼容变更可能直接击穿生产写链路
工程化自建 SDK（本文方案）	兼顾规范强约束与业务扩展性，构建可追溯，感知上游变更	前期需投入时间梳理协议边界与规范预处理

核心收益

通过本次升级，我们将原本散落在多处的 HTTP 细节与脆弱的本地 JAR 彻底整合成体系：

输入受控：规范快照与来源 SHA-256 入库，任何人、任何环境构建出的 SDK 字节高度确定；
职责清晰：生成层管结构契约，协议层管白名单与状态归纳，宿主层管 Token、限流与审计；
演变可控：日常构建不依赖外网，CI 自动化监控上游变更并生成审查快照，兼具稳定性与灵敏度。

团队建议

托管在阿里：云效制品仓库 Packages。有免费的10GB的存储额度，完全够用了。