前言
核心思路：平台侧合规调用 + 本地架构限流 / 幂等 / 熔断 + 异步任务队列 + 缓存兜底 + 全链路监控告警 + 业务数据校验，分层保障选品拉取、商品信息解析、批量上货全链路稳定，规避限流、账号封禁、重复铺货、商品数据错乱等问题。
一、基础层：遵循 1688 开放平台 API 调用规范（前提）
- 必须使用官方开放平台 API，禁止爬虫 爬虫极易触发风控、IP 封禁，页面改版直接中断服务；官方 API 有明确 QPS 配额、错误码体系，是生产环境稳定的基础。 提前申请 AppKey，确认接口权限、调用额度，高并发场景联系小二申请扩容；在开放平台后台查看流量消耗，必要时自助重置流量。
- 流量控制，主动限速，不打满配额
- 按平台 QPS 限制做令牌桶 / 漏桶本地限流，预留 20% 余量，不要压满上限；
- 选品查询（商品列表、搜索）、商品详情、图片、上货发布接口分开独立限流，上货写接口优先级更低、更保守；
- 多任务分时调度，批量任务拆分成小批次，错开高峰（大促时段 1688 平台本身波动大，降低并发）。
- 请求规范
- 统一 HTTPS，设置合理超时：查询接口 5s，批量上货接口 8~12s，防止线程池被阻塞耗尽；
- 签名、时间戳、参数严格按照 TOP 协议，避免参数错误导致 400、403；
- 区分可重试异常和不可重试异常： ✅ 可重试：网络超时、502/503 平台临时抖动 ❌ 禁止重试：401 鉴权、403 权限封禁、429 限流、参数错误、商品下架、类目不存在；这类重试会加速账号封禁
二、架构层：异步队列 + 幂等设计，防止重复上货
选品上货属于写操作 API，幂等是重中之重，网络抖动重试极易造成重复铺货。
- MQ 异步任务化（推荐 RabbitMQ/RocketMQ） 不要同步循环调用 API 做批量上货：
- 选品任务：同步 / 轻量拉取商品基础信息，写入候选商品库；
- 上货任务：推送到 MQ 队列，消费者串行 / 有限并发消费；
- 任务状态机：待处理 → 调用中 → 成功 / 失败 → 重试中 / 已终止，持久化每个任务状态；失败任务进入死信队列人工排查，避免消息丢失。
- 幂等机制，防止重复创建商品
- 每个上货任务生成全局唯一幂等号，每次 API 请求携带；
- 本地数据库：商品来源1688商品ID + 目标店铺ID建立唯一索引；
- 调用前先查询本地状态：如果该 1688 商品已经在目标店铺上架成功，直接返回成功，不再调用上货 API；
上货 API 返回示例（业务幂等场景）
{ "code":0, "msg":"success", "requestId":"20261102-1688-publish-xxxx", "data":{ "taskId":"task_10001", "idempotentKey":"idem_abc123456", "source1688ItemId":"67890123456", "targetShopItemId":"156789", "status":"success", "publishTime":"2026-11-02 14:30:00", "warning":"" } }
{ "code":0, "msg":"success", "data":{ "taskId":"task_10001", "idempotentKey":"idem_abc123456", "source1688ItemId":"67890123456", "status":"skip", "reason":"商品已上架，幂等命中，跳过重复上货", "targetShopItemId":"156789" } }
三、容错层：重试、熔断、降级，防止雪崩
- 指数退避重试策略 仅针对网络 / 平台临时故障，最大重试次数 2~3 次；间隔：1s →3s →8s； 遇到 429 限流错误，休眠更长时间，禁止立刻重试。
- 熔断降级（Sentinel/Hystrix）
- 统计接口失败率，连续多次失败触发熔断，熔断窗口内不再调用 1688 API；
- 降级方案： 选品查询：返回 Redis 缓存的商品数据； 上货任务：暂停新任务，积压到队列，记录告警，等待熔断窗口结束后半开探测恢复。
- 多级缓存减轻 API 压力 Redis 缓存商品详情、价格、库存、SKU 信息，设置 TTL（比如 5~30 分钟）；
- 选品列表优先读缓存；缓存失效再调用 API 拉取；
- 缓存更新策略：增量更新，避免全量刷新。
缓存返回 JSON 示例
{ "cacheKey":"1688_item_67890123456", "cacheExpireTime":"2026-11-02 15:00:00", "data":{ "itemId":"67890123456", "title":"纯棉T恤", "price":"12.5", "stock":2300, "skuList":[{"skuId":"s1","price":12.5,"stock":1000}] } }
四、业务数据校验层：提前拦截脏数据，减少无效 API 调用
很多 API 失败不是平台问题，而是商品本身数据异常，调用前做校验：
- 校验：标题长度、类目 ID、图片地址、SKU 规格、价格下限、起订量；
- 校验库存状态：1688 商品下架、库存为 0、商家关闭代发，直接标记为不可上货，不再发起上货请求；
- 图片预处理：图片大小、格式校验，大图压缩；部分图片链接失效提前过滤；
- 业务规则校验：供应商店铺勋章、买家保障、发货时效，过滤高风险货源。
数据校验失败返回示例
{ "code":4001, "msg":"商品校验不通过，禁止上货", "data":{ "source1688ItemId":"67890123456", "checkResult":false, "errorList":[ {"field":"stock","message":"商品库存为0，货源缺货"}, {"field":"imgUrl","message":"主图链接访问失败"} ] } }
五、可观测层：日志、指标、告警，快速定位故障
- 全链路日志 每条请求记录：requestId、AppKey、请求参数、响应体、耗时、错误码、任务 ID；日志持久化，用于问题回溯。
- 监控指标（核心指标）
- API 调用成功率、平均响应时间、P95 耗时；
- 限流次数、熔断触发次数、失败任务数量；
- 缓存命中率、队列堆积长度；
- 告警 失败率超过阈值、队列积压、403 权限异常、流量接近配额，触发短信 / 钉钉告警。
监控上报 JSON 示例
{ "metricType":"1688_api_monitor", "apiName":"alibaba.1688.product.publish", "timestamp":"2026-11-02T14:30:00+08:00", "success":1, "costMs":780, "errorCode":"", "appKey":"xxx", "taskId":"task_10001" }
六、业务兜底与风险控制
- 灰度发布：新上货逻辑先小批量测试，验证稳定后再放大任务量；
- 多 AppKey 隔离（谨慎使用）：选品查询、上货发布使用不同 AppKey 分摊流量，但严禁恶意多账号刷量，否则会全部封禁；
- 库存与价格同步补偿：上货成功后，定时增量调用商品 API 同步库存价格，防止下游店铺超卖；
- 故障补偿机制：失败任务人工重试入口，重试时再次校验商品实时状态；
- 平台规则持续跟进：1688 开放平台接口、字段、风控策略会迭代，定期回归测试。
七、稳定性指标参考（SLA）
- 选品查询 API 成功率 ≥99.5%
- 商品上货 API 成功率 ≥99%
- 接口 P95 响应时间＜1.5s
- 消息队列任务丢失率：0
