一、先说清楚：搜「亚马逊数据管道 API」的人在躲什么

这个关键词背后站着三种人，他们的诉求不一样，但痛点高度重合。

第一种：被爬虫维护拖住的团队

他们已经有一套能跑的采集系统，问题是这套系统每周要吃掉一到两个工程师日。改版、验证码、代理封禁、浏览器指纹、内存泄漏，每一项单独看都不致命，加起来就是持续失血。他们搜这个词的真实意图是：有没有一种方式，让这件事从「我们的工程问题」变成「别人的服务问题」。

第二种：要建数据平台的团队

他们还没有亚马逊数据源，正在做技术选型。这类人最怕的不是成本，是选错之后的沉没成本——爬 halfway 发现维护不了，等于前面全白干。他们需要的是一条已经被验证过的架构路径，而不是一个产品广告。

第三种：被账单吓到的团队

他们已经接了第三方数据服务，但每月账单和预期对不上。原因通常是没算重试放大：请求数乘以平均尝试次数，再除以可用记录率，才是真实单价。这类人需要的不是换供应商，是把成本口径修对。

三者的共同点是：他们想甩掉的从来不是「采集」这个动作，而是「维护」这个状态。所以评估任何方案时该问的不是「它能不能取到数据」，而是「接上它之后，我还需要养几个人来盯这件事」。这个问题决定了后面所有架构决策。

在往下读之前，建议先做一件事：把过去八周团队花在数据采集维护上的工程师小时数统计出来，除以八，得到周均维护工时。这个数字是所有后续决策的分母——它让你能把「迁移到 API 的月费」和「继续自维护的人力成本」放在同一个尺度上比较。多数团队第一次算出来都会愣一下，因为这个数字通常比直觉高得多：它不只是修 bug 的时间，还包括排查误报、处理运营提问、更新依赖、救火上下文切换。不做这次统计，你后面的成本讨论会一直停留在感觉层面。

二、不养爬虫的四条路线，各自的账单长什么样

先把路线性质量化。以下不点名具体供应商、不引用任何二手价格，只讲成本结构的差别——因为结构差别是稳定的，价格数字是会变的。

这张表里最该看的是第三列和第四列。维护责任在哪，你的工程师就得盯着哪；典型失败模式是什么，你的告警就得围绕它设计。很多团队选路线时只比第一列，结果接上之后发现第四列的故障自己没有监控手段。

路线一：自建爬虫栈

典型构成是 headless 浏览器集群加代理池加解析器。优点是可控性最高——页面上肉眼能看到的字段，理论上你都能取；没有单条计费，边际成本随规模摊薄。缺点是成本项错位：你以为你在花服务器钱，你在花的是工程时间。一个维护中的爬虫栈，年度真实成本里服务器通常只占小头，大头是工程师的排障时间和机会成本。另一个常被低估的点是反爬对抗是持续军备竞赛，你今天绕过去的方法，不保证半年后还有效。

路线二：托管爬虫平台或自运维开源框架

用 Scrapy、Playwright 集群，或者托管的 Actor 市场。优点是起步快，社区生态成熟，很多解析逻辑有人写过。缺点是维护责任没有转移——托管平台替你管了浏览器和运行环境，但解析逻辑、选择器、失败重试、反爬策略仍然是你自己的代码。而且托管型通常按计算时长计费，这意味着反爬越难，你的账单越高，成本与难度正相关，这一点无法写进预算模型。

路线三：官方 SP-API 打底

优点是稳定且合规，schema 明确，不用对抗反爬。缺点是覆盖面被授权模型严格限定：它给的是卖家主动授权账户上的订单、库存、履约、自家广告数据。你拿不到竞品价格，拿不到市场级搜索排名，拿不到别人的评论。这不是「暂不支持」，是设计上就不提供。所以 SP-API 通常是管道的一部分，不是全部。

路线四：垂直亚马逊数据 API

把解析与反爬外包给专业服务商，你拿到的是结构化 JSON。优点是维护责任转移了——页面改版是供应商要修的事，代理池是供应商要养的事，你的工程师不用再盯选择器。缺点是质量治理责任没转移，而且各家字段覆盖差异巨大，这个差异不会写在功能对比表里。评估方法我们在 最佳亚马逊数据 API 怎么选：4 个数字让宣传口径现原形 里完整讲过，核心是同一批 ASIN 跑盲测，量字段覆盖率、非空填充率、可用记录率与每千条可用记录成本。

现实中的终局通常是混合。自有经营数据走 SP-API，市场与竞品数据走垂直 API，极少数长尾页面可能仍需要自建补充。把「选一条路线」换成「划清哪些走哪条」，这个决策会清晰很多。

划边界时有一个简单的判据：凡是「我有没有授权」能回答的问题，走官方渠道；凡是「市场上正在发生什么」类的问题，走数据服务。前者是授权问题，后者是采集问题，两者的失败模式、成本结构、合规要求都不同，混在一条技术路径里会让两边的复杂度都上升。需要保留自建爬虫的场景，通常只剩下极长尾、且没有供应商覆盖的页面——把这部分控制在一两个对象以内，它的维护成本才是可接受的。

三、迁移之后你会发现：维护没消失，只是换了位置

这一节是全文的核心前提。如果你不接受这个判断，后面的架构设计会显得过度。

从「解析失败」变成「字段缺失」

自建爬虫失败时很吵：抛异常、返回空、日志刷屏，你立刻知道。API 失败时很安静：HTTP 200，合法 JSON，schema 校验通过，但其中 12 个字段是 null。区别在于，前者的故障信号在传输层，后者的故障信号只存在于业务语义层——而业务语义层的校验，没人替你写。

从「被反爬挡住」变成「悄悄变旧」

爬虫被挡住，你会拿到明确的失败。API 侧的对应故障是数据新鲜度退化：供应商缓存策略调整、某个市场采集频次下降、上游任务积压，都会让你拿到的值还是三天前的。数值格式合法，只是不再反映现实。这类问题只能通过新鲜度 SLO + staleness 分布监控发现，没有别的办法。

从「代理成本」变成「重试放大成本」

自建时代你的成本主要在代理和机器，相对固定。API 时代的成本是单价乘以尝试次数，而尝试次数是被失败率、退避策略、幂等实现共同放大的。一个可用记录率 70%、平均尝试 1.8 次的管道，实际单位成本是标价的 2.57 倍。这个放大系数不监控就会失控，而且它通常是缓慢上升的——没人改动代码，某天你发现账单涨了 40%。

把这三条放一起看，结论很直接：采集可以外包，判断力不能外包。采集层交出去之后，你需要自建的是一套「判断数据还能不能用」的机制。下面六层架构里，第五层的质量门就是这套机制。

我们见过一个很典型的迁移案例。一个六人数据团队把自建爬虫换成第三方 API，第一年确实省下了大概两个工程师日的周维护量，团队很高兴。但第三个月开始，运营反馈报表里的竞品价格「有点怪」——查下去发现是某两个市场的价格字段填充率从 96% 掉到了 61%，而这个过程持续了五周没有任何告警，因为所有请求都返回 200，成功率指标一直是 99% 以上。修这个坑花了他们两周，其中一周半是在做归因：没有原始响应快照，无法确定是从哪天开始掉的。

这个案例的教训不是「不该迁移」，而是迁移的同时必须把质量监控一起建起来。如果他们在迁移时就落了原始归档和字段级填充率监控，这个退化会在第一周就被发现，修起来是改个参数的事，而不是两周的考古。

四、参考架构：六层，每层只做一件事

下面的分层不是理论模型，是我们见过跑得稳的团队实际收敛出来的形状。原则是每层只有一个职责，故障能被定位到具体一层。

业务目标
   │  字段契约 · 新鲜度 SLO · 成本预算
   ▼
┌───────────────────────────────────────┐
│ L1 采集层    取回原始响应，不做业务判断      │
├───────────────────────────────────────┤
│ L2 原始归档   原样落盘，可复现的唯一依据      │
├───────────────────────────────────────┤
│ L3 队列重试   幂等键 · 退避 · 死信分流       │
├───────────────────────────────────────┤
│ L4 标准化存储 契约校验 · 幂等 upsert         │
├───────────────────────────────────────┤
│ L5 质量门    四个数字决定是否放行            │
├───────────────────────────────────────┤
│ L6 监控预算   面板 · 告警 · 周回归 · 成本归因  │
└───────────────────────────────────────┘
   │
   ▼
下游：报表 / 模型 / Agent / 告警

第 0 层：输入不是需求，是三张契约

在写任何代码之前，先把三件事写下来，且必须是可判定的：字段契约（业务依赖的字段清单，按 P0/P1/P2 分级）、新鲜度 SLO（P0 字段的 P95 staleness 上限，比如 6 小时）、成本预算（每千条可用记录的上限金额）。这三张契约是所有后续自动化判定的依据。没有它们，质量门就只能拍脑袋设阈值，而拍脑袋设的阈值会在第一次误报之后被人关掉。

写字段契约时最容易犯的错是什么都想要。一份列了 80 个字段、全部标为 P0 的契约，等价于没有契约——因为可用记录率会被压到接近零，质量门永远报警，最后被人关掉。P0 的正确定义是「缺了它这条记录就不能进下游报表」的字段，通常不超过 15 个。P1 是「有了更好、缺了能接受」，P2 是「偶尔用得上，可以为空」。分级不是形式主义，它直接决定了重试策略、降级档位和质量门阈值。

第 1 层：采集器只取回原始响应

采集器的职责边界要划得很硬：发请求、拿响应、交给下一层。它不做字段校验、不做业务判断、不做清洗。理由是可归因——如果采集器里混了业务逻辑，当数据出问题时你无法判断是取错了还是判错了。采集器只应该产出两样东西：原始响应体，以及这次调用的元数据（耗时、状态码、时间戳、尝试次数）。

第 2 层：原始归档是可复现性的唯一依据

把原始响应原样落盘，按对象加市场加日期分区，保留 30 到 90 天。这一层的价值在出事的时候才体现：当你怀疑某条记录有问题，能不能回到三个月前那个具体的响应体去看？如果不能，你做的所有归因分析都是猜测。存储成本很低，压缩后的 JSON 通常比你想的便宜得多。

保留期的选择有个实用判据：它必须长于你的问题发现周期。如果你的团队平均要三周才发现数据异常，那保留 30 天就只够看一次，保留 90 天才能支撑对比。压缩后的原始 JSON 按对象存储，成本通常远低于同等时间跨度的聚合指标重算成本，所以这一层宁可多留也别省。

第 3 层：队列与重试

队列层负责调度、并发控制、限流与重试。关键设计是按错误类型分流：限流与服务端错误进重试，参数错误与鉴权错误直接进死信，返回 200 但关键字段全空进软失败队列。把这三种混在一个重试循环里，是重试放大成本失控的主要原因。详细实现见第五节。

第 4 层：标准化与存储

把原始响应映射到你的内部 schema，做类型强校验，然后以幂等方式写入。写入必须幂等——同一对象同一天被处理多次，结果应该一致。实践中用「对象标识 + 市场 + 数据日期 + 契约版本」做唯一键，用 upsert 而非 insert。这一层还要把 P0 字段的缺失情况记录下来，供下一层使用。

第 5 层：质量门决定放行与否

这是你自己必须建、且无法外包的一层。它按批次计算四个数字：字段覆盖率、非空填充率、可用记录率、新鲜度达标率。低于阈值就不放行到下游，或者降级标记为「参考值」。质量门的存在意义不是保证数据完美，而是让退化变成一个会响的警报，而不是一个慢慢被接受的事实。第六节给可直接运行的实现。

第 6 层：监控与预算

把四个数字做成趋势图，配告警；把成本按业务对象归因；每周跑一次固定样本的回归测试。周回归这一项最容易被跳过，也最有用——一次性验收只能证明「现在能用」，周回归才能证明「一直在能用」。同时把预算守卫做进这一层：当日累计成本超过阈值时自动降级采样频次，而不是等月末看账单。

面板上值得长期保留的只有五张图：可用记录率趋势（按对象类型分线）、P0 填充率趋势（按市场分线）、P95 数据龄期趋势、重试放大系数趋势、每千条可用记录成本趋势。五张够了，再多就没人看。前三张回答「数据还能不能用」，后两张回答「代价是多少」。把成功率单独做成一张大图是常见误区——它几乎恒定为 99% 以上，提供不了任何信息，却会占据面板上最显眼的位置。

贯穿多层的两件事：并发建模与数据血缘

有两件事不属于任何单独一层，但每一层都受影响，单独拿出来说。

并发与限流要按操作类型建模。一个常见错误是用一个全局 QPS 做规划。官方渠道与多数专业数据服务采用按操作类型独立的令牌桶——不同操作的配额不同、补充速率不同。你需要的不是「我们每秒发多少请求」，而是一张按操作类型列出的配额表，以及在客户端实现的按操作退避。没有这张表，你的并发规划就是拍脑袋，压测结果也不可信：压测时用一种操作跑出的吞吐，换另一种操作会得到另一个数字。

数据血缘要能回溯到具体那次调用。每条落地记录都应该带上来源元数据：请求 ID、供应商响应时间戳、尝试次数、契约版本、采集批次号。字段不多，但缺了它，当用户问「这个价格是什么时候取的」你就答不上来。血缘信息同时是归因分析的基础——当某个字段开始退化，你能立刻按批次、按市场、按时间切分定位，而不是全量重跑一遍碰运气。

五、重试与幂等：这一段最容易写错

重试逻辑看起来简单，实际是亚马逊数据管道里最容易写错、后果最持久的一段。错误主要出在三个地方：不分错误类型、退避没有抖动、幂等键设计不对。

三类错误，三种处理

第一类是可重试：限流响应、服务端 5xx、网络超时。这类应该退避重试，且有次数上限。第二类是不可重试：鉴权失败、参数错误、请求格式问题。这类重试一万次也是同样结果，只会放大成本，应该直接进死信队列并告警。第三类是软失败：HTTP 200 但关键字段缺失。这类不应该当作成功，也不应该无限重试，应该进单独的软失败队列，由质量门按批次判断是偶发还是系统性问题。

退避必须有抖动

指数退避是标配，但没有抖动的指数退避会造成重试风暴——一批请求同时失败、同时等待、同时重试，把限流阈值瞬间打满。加抖动（在退避时长上乘一个随机系数）能把重试请求摊平。上限也要设，否则尾部延迟会失控。

for attempt in range(1, MAX_ATTEMPTS + 1):
    try:
        resp = fetch(item)
        raw_store.save(item.id, resp, meta=build_meta(attempt))
        return ok(resp)
    except Retryable as e:        # 429 / 5xx / timeout
        sleep(backoff(attempt))
    except NonRetryable as e:     # 401 / 422 / bad params
        dead_letter.push(item, reason=e.code)
        return fail(e)
    except EmptyButOk as e:       # 200 但 P0 字段全空
        soft_fail.push(item, reason="p0_empty")
        return fail(e)
dead_letter.push(item, reason="attempts_exhausted")

def backoff(attempt):
    # 指数退避 + 抖动：CAP 防止尾部延迟失控，random 打散重试风暴
    return min(CAP_SECONDS, BASE_SECONDS * 2 ** (attempt - 1)) * (0.5 + random.random())

幂等键怎么选

幂等键必须包含契约版本。很多团队用「ASIN + 市场 + 日期」，这在契约不变时没问题；但当你新增了 P0 字段，历史记录已经不满足新契约了，如果不带版本号，重跑时会被误判为「已处理过」而跳过。加上契约版本后，契约升级会自动触发全量重跑，这才是正确行为。

超时设置比重试次数更容易被忽略

团队通常会反复调重试次数，却把超时值设成一个随手写的数字。超时设置对成本和吞吐的影响更大。超时太短，会让本来能成功的请求被判失败进入重试，既放大成本又产生重复工作；在数据服务场景下，某些复杂对象的响应时间天然偏长，一刀切的短超时会系统性地抬高你的失败率。超时太长，失败请求会长时间占用并发槽位，队列积压，反而降低整体吞吐。

合理的做法是按操作类型的历史响应时长分布来设：取 P99 作为超时基准，再留出余量。这个数字要从你自己的调用日志里算，不要沿用默认值。同时区分连接超时与读取超时——前者应该短（几秒），后者应该按响应分布来定。

死信队列不是垃圾桶

死信队列里的内容必须被消费，否则它就只是一个延迟丢弃机制。最低要求是：按失败原因聚合，每天出一份清单，并对「原因分布突变」告警。原因分布的变化往往比失败率本身更早暴露问题——比如「attempts_exhausted」突然增多，通常意味着上游成功率在下降，而这时你的整体成功率指标可能还没跌破阈值。

六、质量门：四个数字加一个新鲜度 SLO

质量门的核心是把「数据能不能用」这个主观判断，拆成五个可自动计算的量。以下实现可直接运行，输入是你的原始记录列表。

字段覆盖率与非空填充率要分开算

字段存在不等于字段有值。覆盖率衡量 schema 层面有没有这个路径，填充率衡量实际交付时取没取到值。两者都低说明字段根本不支持；覆盖率高但填充率低，说明字段在契约上、但供应商取不到值的情况居多——后者更危险，因为 schema 校验会放行。

def field_present(rec, path):
    cur = rec
    for part in path.split("."):
        if not isinstance(cur, dict) or part not in cur:
            return False
        cur = cur[part]
    return True

def field_filled(rec, path):
    if not field_present(rec, path):
        return False
    cur = rec
    for part in path.split("."):
        cur = cur[part]
    if cur is None: return False
    if isinstance(cur, str) and cur.strip() == "": return False
    if isinstance(cur, list) and len(cur) == 0: return False
    return True

def coverage(records, fields):
    total = len(records) * len(fields)
    return sum(1 for r in records for f in fields if field_present(r, f)) / total if total else 0.0

def fill_rate(records, fields):
    total = len(records) * len(fields)
    return sum(1 for r in records for f in fields if field_filled(r, f)) / total if total else 0.0

可用记录率：按整条记录判定

前面两个指标是字段级的，但下游消费的是整条记录。可用记录率定义为：所有 P0 字段都被填充的记录占比。这是唯一直接对应「这条数据能不能进报表」的指标，也应该是质量门的主阈值。

def usable_rate(records, p0_fields):
    if not records: return 0.0
    ok = sum(1 for r in records if all(field_filled(r, f) for f in p0_fields))
    return ok / len(records)

def staleness_p95(records, ts_field, now=None):
    """返回 P95 数据龄期（小时）；None 表示无有效时间戳。"""
    now = now or datetime.now(timezone.utc)
    deltas = []
    for r in records:
        ts = r.get(ts_field)
        if not ts: continue
        t = datetime.fromisoformat(str(ts).replace("Z", "+00:00"))
        deltas.append((now - t).total_seconds() / 3600)
    if not deltas: return None
    deltas.sort()
    return deltas[max(0, int(round(0.95 * len(deltas))) - 1)]

新鲜度 SLO 要写成分布，不要写成布尔值

「数据是不是实时的」这个问题无法告警，因为「实时」没有量化定义。可执行的写法是：P0 字段的 P95 数据龄期 ≤ X 小时。用 P95 而不是平均值，是因为平均值会掩盖长尾——一个 P50 为 20 分钟、P95 为 31 小时的分布，平均值可能很好看，但你的报表里就是有相当一部分数据是隔天的。

把五个量装进一个函数

单独看五个数字没有意义，质量门需要的是一个布尔结论。下面是一个完整的门函数，输入一批记录，输出各项指标与是否放行。

P0 = ["asin", "title", "price.amount", "availability.status"]
P1 = ["brand", "rating.value", "review_count", "bsr.rank_main"]
FRESHNESS_FIELD, SLO_P95_HOURS = "collected_at", 6.0

def gate(records):
    m = {
        "n":             len(records),
        "coverage_p0":   coverage(records, P0),
        "fill_p0":       fill_rate(records, P0),
        "fill_p1":       fill_rate(records, P1),
        "usable":        usable_rate(records, P0),
        "staleness_p95": staleness_p95(records, FRESHNESS_FIELD),
    }
    m["pass"] = (
        m["fill_p0"] >= 0.95
        and m["usable"] >= 0.90
        and m["staleness_p95"] is not None
        and m["staleness_p95"] <= SLO_P95_HOURS
    )
    return m

注意最后那个 is not None 判断。时间戳字段缺失时 staleness_p95 返回 None，如果不显式排除，None <= 6.0 在 Python 3 里会直接抛异常，而在一些弱校验的实现里会被当成 False 静默放行——后者更危险，因为它会让「一条时间戳都没有」的数据看起来像是通过了新鲜度检查。

质量门该在哪个粒度上跑

一个设计选择会显著影响质量门的可用性：按批次判定还是按记录判定。按记录判定适合写入前的清洗——单条记录不满足 P0 就不写入，干净但会丢数据，且无法区分「这批整体有问题」和「这一条碰巧有问题」。按批次判定适合放行决策——一个批次的可用记录率低于阈值就整体拦截，能捕捉系统性退化，但会连带拦掉批次里本来正常的记录。

实践中的做法是两个粒度都要：记录级做标记（这条记录是否满足契约），批次级做决策（这个批次是否放行）。把两者混成一个开关，要么丢数据，要么漏告警。顺序上先记录级标记、再批次级判定，这样拦截发生时你能立刻说出是哪一类记录拖低了整批。

样本必须分层，聚合指标会骗你

这是质量门最隐蔽的一个坑。假设你的样本里七成是图书、三成是服饰，图书的价格字段填充率是 96%，服饰因为变体多、部分变体缺价，填充率只有 58%。聚合后你看到的是 84%——一个看起来还行、却掩盖了服饰这个品类已经不可用的数字。

所以固定回归样本必须按对象特征分层：按品类、按是否有变体、按市场、按价格区间各取一定数量，然后分别计算指标。分层的维度取决于你的业务——如果你的价值集中在少数几个品类，就按品类分；如果集中在特定市场，就按市场分。关键是要让每个分层都有足够的样本量单独出结论，而不是只看总量。

阈值怎么定才不会被关掉

质量门最常见的死法是阈值定得太严，第一次误报就有人把它关了。正确做法是先观测两周再设阈值：第一周只记录不拦截，拿到四个数字的基线分布；第二周按基线往下取一个合理的容差区间作为告警线，再往下取更大容差作为拦截线。阈值应该来自你自己的数据分布，而不是来自某个通用最佳实践。

七、成本：把账单归因到业务对象

多数团队只知道月度总账单，不知道每个业务对象花了多少。这导致成本优化无从下手——你不知道该砍哪个市场、哪个对象、哪类请求。

有效成本公式

要优化的不是单价，是每千条可用记录的有效成本：单价乘以每条可用记录的平均尝试次数，再除以可用记录率。这个公式把三个变量串起来了——单价、稳定性、完整性。一个单价便宜但可用率低的供应商，算下来可能更贵；一个单价贵但字段全、重试少的，可能反而划算。

重试放大系数必须实测

在采集层记录每条记录的尝试次数，按对象类型与市场聚合出平均值。这个数字通常会让第一次看到它的人意外：很多团队以为自己的放大系数接近 1，实测下来在 1.5 到 2.5 之间。它上升的原因往往不是失败率变高，而是退避策略不合理导致重试被提前触发。

成本归因到业务对象的最小实现

归因不需要复杂系统。在采集层把每次调用的成本估算写进记录元数据（调用次数乘以单价，加上这次调用归属的对象与市场），在存储层按「对象类型 / 市场 / 日期」三个维度聚合。三个字段的聚合就足够回答绝大多数成本问题：哪个市场最贵、哪类对象在烧钱、成本是在哪一周开始上升的。

加上可用记录数之后，你就能算出每个对象、每个市场的每千条可用记录成本，而不是只有一个总数。这个颗粒度会直接改变优化方向——实践中经常出现的情况是，占比最大的那个对象并不是单位成本最高的，而团队一直在优化错的地方。

预算守卫：把降级策略写进代码

当日累计成本超过阈值时，自动降低非 P0 对象的采样频次，保留 P0 对象的完整采集。这个策略要提前写好并测过，不能等超支了再临时决定——临时决定通常只有两个选项：全停或者继续烧，两个都不好。

八、schema 变更：管道里的契约测试

上游字段变更是静默发生的——改名、改类型、枚举新增、字段合并。它对下游的破坏不体现在传输层，只体现在你的报表里某个数字突然不对。管道层能做的防御有三层。

第一层：存在性与类型强校验

在标准化层对每个契约字段做显式断言，不只是检查存在，还要检查类型。类型从字符串变成对象是最常见的破坏性变更，而弱类型语言的隐式转换会让它悄悄通过。校验失败不应静默跳过，应写入软失败队列。

第二层：周度差异快照

每周对固定样本保存一份响应快照，与上周做结构 diff：新增了哪些路径、消失了哪些路径、哪些类型变了。把 diff 结果推送到告警通道。这份快照同时也是归因分析的依据——当你需要回溯「这个字段是从什么时候开始取不到的」，没有快照就只能靠记忆。

第三层：契约版本与回归重跑

字段契约本身要有版本号。契约变更时，幂等键跟着变，自动触发受影响对象的重跑。没有版本号机制的话，契约升级后历史数据会以「已处理」为由被跳过，导致新旧数据混在一起而无人察觉。

九、降级路径：上游不可用时管道该怎么表现

这一节几乎没人写进架构文档，但它决定了事故当天你的团队是慌乱还是有序。任何上游都会出问题——供应商故障、你自己配额打满、网络分区、上游限流收紧。区别在于出问题的时候，你的管道是「明确地少给了一些数据」还是「假装给全了」。

降级不是「全停」或「继续烧」两条路

没有预设策略时，团队临场只有两个选项：停掉管道等恢复，或者放任重试把账单烧穿。两个都不好。正确做法是预先定义好降级档位，让系统自己按条件切换。

三档降级策略

第一档P0 保真：P0 对象的采集频次不变，P1、P2 对象降频。触发条件是成本超阈值或上游错误率上升。第二档只保 P0：只采集 P0 对象且降低频次，P1/P2 全部暂停。触发条件是上游持续不可用超过设定时长。第三档只读归档：停止全部采集，下游切换到最近一次通过质量门的归档快照，并对外显式标记为「数据龄期已超 SLO」。三个档位的切换条件、生效范围、恢复条件都要写进配置，而不是写进某个人的记忆里。

降级状态必须显式暴露给下游

降级时最危险的不是少给数据，是下游不知道数据少了。质量门放行的记录里应该带一个采集状态标记，写明这一批是在哪个档位下采集的、覆盖的对象范围是什么。报表层读到降级标记就该显示提示，模型层读到就该调整置信度。把降级状态藏在管道内部，等于让下游用降级数据当完整数据用——这正是我们在第三节说的那类静默失败。

十、Pangolinfo 在这一架构里负责哪一层

把话说清楚，避免误解：我们负责第 1 层，以及第 1 层带来的稳定性。第 5 层那道质量门，不管你用谁的采集服务，都得自己建。

我们负责的部分

采集层交给我们，意味着页面改版、反爬对抗、代理池运维、浏览器指纹这些事不再是你的工程问题。我们的公开指标是：中位延迟约 3 秒、调用成功率 99%、日调用量 3000 万以上。在广告位这个公认最难采的对象上，我们跨 13 个市场的整体采集率为 91.4%，这个数字是我们把「采集覆盖率」当成产品指标持续投入的结果，而不是顺带得到的。商品、搜索、评论三类公开对象的返回字段在文档里逐字段列出，你可以直接用上面第六节的脚本去量我们的覆盖率和填充率。

我们不做的三件事

第一，账户域数据不做——订单、库存、自家广告这类数据属于官方 SP-API 的授权范围，我们既不提供也不提供绕过方式。第二，不采集买家个人身份信息。第三，不采集任何登录后可见的数据。这三条是设计边界，不是路线图上的待办。

还有一种情况：你可能根本不需要建管道

如果你的消费方是 AI Agent 而不是固定报表，建一条完整管道可能是过度工程。Agent 的取数模式是按需、交互式、字段范围不固定，这与管道的批量、固定 schema、周期性采集假设不匹配。这种情况下更合适的做法是把数据能力直接暴露成工具，让 Agent 在需要时调用——我们的 Amazon Data MCP 就是按这个思路设计的，19 个工具通过远程 HTTP 接入，零安装。Agent 场景同样需要质量判断，只是判断的位置从「管道里的质量门」变成了「Agent 侧的字段校验提示」。

什么时候不该用我们

有三类场景直说不合适：其一，你只需要极少量、低频次的数据，用我们不如自己写几行脚本；其二，你的需求落在自有账户范围内，SP-API 是更合规也更便宜的选择；其三，你需要的是登录后才可见的数据或买家个人信息，这个我们不做，也不会有供应商应该做。排除掉不合适的场景，剩下的才是能省下维护成本的部分。

十一、90 分钟落地清单

如果你要在下周把这套东西跑起来，按下面的顺序做，每一步都有明确的产出物。

五步做完，你就有了一条「数据退化会响」的管道。剩下的优化——成本归因、schema 契约测试、周回归——都是在这套骨架上加的。

最后提醒一句：这套清单里最容易半途而废的是第四步的基线观测。团队常有的冲动是跳过基线直接上告警，理由是「先跑起来再说」。但跳过基线的代价是阈值只能拍脑袋定，而拍脑袋的阈值必然会在第一次误报后被关掉——质量门一旦被关过一次，重新建立信任要比第一次建立难得多。宁可晚两周上线告警，也不要早两周上线一个会被关掉的告警。

外部参考：Amazon Selling Partner API 官方文档（授权模型与按操作限流）、Amazon 使用条款与 robots 说明、Pangolinfo 服务公开指标与自测数据。