perf(dgj): 平台请求节流 + 限流退避重试

线上取号/发货遇到服务商级限流:
`isv.request-limited 请求太频繁…配置限流QPS:600, 当前访问QPS:687`。
QPS 额度是整个 ISV 共享的,单靠降我们的并发压不住,所以两手都做:
削自己峰值 + 被限流时退避重试而不是直接判失败。

- dgj.request():所有平台调用的唯一出口,统一排队,相邻请求至少间隔
  DGJ_REQUEST_INTERVAL_MS(默认 100ms,单进程约 10 请求/秒)
- postPlatformForm():命中 isv.request-limited / 请求太频繁 / 访问QPS 时
  指数退避重试(DGJ_RATE_LIMIT_RETRY 默认 3 次、DGJ_RATE_LIMIT_BACKOFF_MS 默认 1000ms),
  仍限流则抛「店管家接口限流:…已自动退避重试 N 次仍被限流,请稍后重试」并保留原始返回
- waybillGet:批量取号并发 4 → 2(WAYBILL_CONCURRENCY 可调),
  每单 3 次平台调用(回读订单 + 模板校验 + ExpressPrint),并发越大突发越猛
- externalSendSync.recordFailure:平台限流不算这单的错,
  保持「待重试」且不累加 external_send_times,避免批量重试时一批单被打成「异常」
- 单测 dgjRateLimit.test.js(4 例):限流识别、退避后成功、重试耗尽报错、全局间隔生效
- 文档:请求量控制一节补 QPS 限流口径与全部节流开关

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 09:46:45 +08:00
parent da468f6cb2
commit 9e1c476a55
5 changed files with 236 additions and 17 deletions

View File

@ -81,6 +81,61 @@ function buildPlatformError(message, res) {
return error;
}
/**
* 单进程内相邻两次平台请求的最小间隔(毫秒)
*
* 店管家按服务商维度限流(实测配置 600 QPS),批量取号/发货时容易把突发打满,
* 这里平滑一下节奏;置 0 可关闭。默认 100ms(单进程约 10 请求/秒,远低于平台额度,
* 但足以削掉并发突发造成的瞬时峰值)。
* @return {number} 间隔毫秒
*/
function requestIntervalMs() {
return Math.max(0, Number(process.env.DGJ_REQUEST_INTERVAL_MS == null ? 100 : process.env.DGJ_REQUEST_INTERVAL_MS) || 0);
}
/**
* 被平台限流(isv.request-limited)时的自动重试次数
* @return {number} 重试次数
*/
function rateLimitRetryCount() {
return Math.max(0, Number(process.env.DGJ_RATE_LIMIT_RETRY == null ? 3 : process.env.DGJ_RATE_LIMIT_RETRY) || 0);
}
/**
* 限流退避基数(毫秒):第 n 次重试等待 base * 2^(n-1)
* @return {number} 退避毫秒
*/
function rateLimitBackoffMs() {
return Math.max(0, Number(process.env.DGJ_RATE_LIMIT_BACKOFF_MS || 1000) || 0);
}
/** 下一次允许发请求的时间戳(模块级,进程内共享) */
let nextRequestAt = 0;
/**
* 等待到本进程允许发下一条请求(平滑突发)
* @return {Promise<void>} 无返回值
*/
async function waitRequestTurn() {
const interval = requestIntervalMs();
if (!(interval > 0)) return;
const now = Date.now();
const startAt = Math.max(now, nextRequestAt);
nextRequestAt = startAt + interval;
if (startAt > now) await new Promise(resolve => setTimeout(resolve, startAt - now));
}
/**
* 平台返回是否为限流(服务商级 QPS 超限)
* @param {Object|null} json 平台响应
* @return {boolean} 是否限流
*/
function isRateLimited(json) {
if (!json) return false;
const text = `${json.Message == null ? '' : json.Message} ${json.ErrorCode == null ? '' : json.ErrorCode}`;
return /isv\.request-limited|请求太频繁|访问QPS|限流/i.test(text);
}
/**
* 提取发货回传的逐单失败(平台是「整包 Success + Data.Orders[] 逐单结果」)
* @param {Object} json 平台响应
@ -892,6 +947,8 @@ class DgjService extends PrintPlatformService {
* @return {Promise<{status: number, json: Object|null, text: string, setCookies: string[]}>} 响应
*/
async request(url, options = {}) {
// 全局限流:平台按服务商维度限流(实测 600 QPS),所有请求(取号/校验/发货/回读/商品)统一排队
await waitRequestTurn();
const res = await fetch(url, {
redirect: 'follow',
...options,
@ -3018,17 +3075,42 @@ class DgjService extends PrintPlatformService {
};
if (this.cookie) headers.cookie = this.cookie;
const res = await this.request(`https://${host}${path}?${query.toString()}`, {
method: 'POST',
headers,
body: form.toString(),
});
const url = `https://${host}${path}?${query.toString()}`;
const options = { method: 'POST', headers, body: form.toString() };
const retryCount = rateLimitRetryCount();
let res = await this.request(url, options);
// 服务商级 QPS 限流(isv.request-limited)属于瞬时拒绝,请求未被处理,可以安全退避重试
for (let attempt = 1; attempt <= retryCount; attempt += 1) {
if (res.status === 401 || !isRateLimited(res.json)) break;
const wait = rateLimitBackoffMs() * Math.pow(2, attempt - 1);
if (this.logger && typeof this.logger.warn === 'function') {
this.logger.warn('[dgj] %s 被平台限流,%dms 后第 %d 次重试', path, wait, attempt);
}
if (wait > 0) await new Promise(resolve => setTimeout(resolve, wait));
res = await this.request(url, options);
}
if (res.status === 401) {
throw new Error(`店管家登录已失效:${(res.json && res.json.Message) || 'token is invalid'}`);
}
if (isRateLimited(res.json)) {
const message = (res.json && res.json.Message) || '请求太频繁';
throw buildPlatformError(
`店管家接口限流:${message};已自动退避重试 ${retryCount} 次仍被限流,请稍后重试`,
res
);
}
return res;
}
/**
* 平台返回是否为限流(服务商级 QPS 超限)
* @param {Object|null} json 平台响应
* @return {boolean} 是否限流
*/
static isRateLimited(json) {
return isRateLimited(json);
}
/**
* 订单是否已在平台侧发货或已终结(供脚本/上层按落库的平台原始结构复用同一口径)
* @param {Object} row 店管家订单原始结构

View File

@ -57,8 +57,14 @@ const BUSINESS_KEY_PATHS = [
/** 单次批量上限(避免一次回调过大、平台侧限流) */
const MAX_BATCH = 100;
/** 并发处理数(平台取号是网络请求,适度并发缩短总耗时) */
const CONCURRENCY = 4;
/**
* 并发处理数(平台取号是网络请求,适度并发缩短总耗时)
*
* 店管家按服务商维度限流(实测 600 QPS),并发越大突发越猛、越容易被判 `isv.request-limited`;
* 单进程另有全局请求间隔(`DGJ_REQUEST_INTERVAL_MS`)兜底,这里默认压到 2。
* 可用 `WAYBILL_CONCURRENCY` 调整。
*/
const CONCURRENCY = Math.max(1, Number(process.env.WAYBILL_CONCURRENCY || 2) || 2);
/** 取消 / 作废 / 归档等不可取号的状态 */
const BLOCKED_STATUS_LABELS = {

View File

@ -290,9 +290,21 @@ class ExternalSendSyncService extends Service {
*/
async recordFailure(order, err, now) {
const { ctx } = this;
const message = truncateText(err && err.message ? err.message : '同步失败', 500);
// 平台限流(服务商级 QPS 超限)不是这单的问题:不计入重试次数,等下一轮调度再试,
// 否则批量重试时容易一批单被限流打成「异常」,还得人工再清
const rateLimited = /isv\.request-limited|请求太频繁|访问QPS|接口限流/i.test(message);
if (rateLimited) {
await order.update({
external_send_status: SEND_STATUS.RETRY,
external_send_error: message,
external_send_at: now,
});
ctx.logger.warn('[external-send] %s 被平台限流,本轮跳过、不计重试次数:%s', order.order_no, message);
return { ok: false, message };
}
const times = Number(order.external_send_times || 0) + 1;
const exception = times >= MAX_SEND_TIMES;
const message = truncateText(err && err.message ? err.message : '同步失败', 500);
await order.update({
external_send_status: exception ? SEND_STATUS.EXCEPTION : SEND_STATUS.RETRY,
external_send_times: times,
@ -304,11 +316,6 @@ class ExternalSendSyncService extends Service {
return { ok: false, message };
}
/**
* 定位同步目标(打单账号 / 平台服务 / 分区)
* @param {Object} order 配送表订单行
* @return {Promise<Object|null>} 目标信息;非外部打单订单返回 null
*/
/**
* 最近一次**与本单运单号对得上**的成功取号记录(含运单号、快递编码、平台面单标识)
*

View File

@ -0,0 +1,115 @@
'use strict';
const { assert } = require('egg-mock/bootstrap');
const DgjService = require('../../../app/lib/printPlatform/dgj');
/** 线上真实返回(isv 服务商级限流) */
const RATE_LIMIT_JSON = {
Success: false,
ErrorCode: '500',
Message: 'isv.request-limited 请求太频繁,请稍后重试,详细信息:时间:2026-11-07 09:36:08, 配置限流QPS:600, 当前访问QPS:687',
};
const SUCCESS_JSON = { Success: true, ErrorCode: '200', Data: { ok: 1 } };
/**
* 造一个只用账号信息的服务实例(不落库)
* @return {Object} 店管家服务实例
*/
function buildService() {
return new DgjService({
platform: { code: 'dgj', name: '店管家', url: 'fxali.dgjapp.com', fetch_waybill_no: 1 },
account: { id: 1, account: 'tester', password: 'pwd', token: 'token', cookie: '' },
});
}
/**
* 记录每次平台调用的时刻
* @param {Array<Object>} responses 依次返回的响应
* @return {{calls: Array<number>, stub: Function}} 调用时刻与桩函数
*/
function stubRequest(responses) {
const calls = [];
const stub = async () => {
calls.push(Date.now());
const next = responses.length > 1 ? responses.shift() : responses[0];
return { status: 200, json: next, text: JSON.stringify(next), setCookies: [] };
};
return { calls, stub };
}
describe('lib/printPlatform/dgj 限流识别与退避重试', () => {
const originBackoff = process.env.DGJ_RATE_LIMIT_BACKOFF_MS;
const originRetry = process.env.DGJ_RATE_LIMIT_RETRY;
beforeEach(() => {
process.env.DGJ_RATE_LIMIT_BACKOFF_MS = '5';
process.env.DGJ_RATE_LIMIT_RETRY = '2';
process.env.DGJ_REQUEST_INTERVAL_MS = '0';
});
afterEach(() => {
if (originBackoff === undefined) delete process.env.DGJ_RATE_LIMIT_BACKOFF_MS;
else process.env.DGJ_RATE_LIMIT_BACKOFF_MS = originBackoff;
if (originRetry === undefined) delete process.env.DGJ_RATE_LIMIT_RETRY;
else process.env.DGJ_RATE_LIMIT_RETRY = originRetry;
delete process.env.DGJ_REQUEST_INTERVAL_MS;
});
it('识别服务商级限流返回', () => {
assert.strictEqual(DgjService.isRateLimited(RATE_LIMIT_JSON), true);
assert.strictEqual(DgjService.isRateLimited({ Message: '订单不是待发货状态' }), false);
assert.strictEqual(DgjService.isRateLimited(null), false);
});
it('限流后自动退避重试,成功则正常返回', async () => {
const service = buildService();
const { calls, stub } = stubRequest([ RATE_LIMIT_JSON, RATE_LIMIT_JSON, SUCCESS_JSON ]);
service.request = stub;
const res = await service.postPlatformForm('fxali.dgjapp.com', '/NewOrder/OnlineSend', new URLSearchParams('a=1'), 'trace', 'db');
console.log('重试后成功:调用次数 =', calls.length, '| Success =', res.json.Success);
assert.strictEqual(calls.length, 3, '两次限流 + 一次成功');
assert.strictEqual(res.json.Success, true);
});
it('重试仍被限流时抛出可读错误', async () => {
const service = buildService();
const { calls, stub } = stubRequest([ RATE_LIMIT_JSON ]);
service.request = stub;
let error = null;
try {
await service.postPlatformForm('fxali.dgjapp.com', '/TemplateSet/CheckTemplateAvaliable', new URLSearchParams('a=1'), 'trace', 'db');
} catch (err) {
error = err;
}
console.log('限流失败:调用次数 =', calls.length, '| 错误 =', error && error.message);
assert.ok(error, '应当抛错');
assert.match(error.message, /店管家接口限流/);
assert.match(error.message, /请稍后重试/);
assert.strictEqual(calls.length, 3, '首次 + 2 次重试');
assert.ok(error.rawResponse && error.rawResponse.Message, '保留平台原始返回便于留痕');
});
it('全局请求间隔生效(请求按 DGJ_REQUEST_INTERVAL_MS 排队)', async () => {
process.env.DGJ_REQUEST_INTERVAL_MS = '40';
const service = buildService();
const originFetch = global.fetch;
const stamps = [];
global.fetch = async () => {
stamps.push(Date.now());
return { status: 200, text: async () => '{}', headers: { getSetCookie: () => [] } };
};
try {
await service.request('https://fxali.dgjapp.com/a');
await service.request('https://fxali.dgjapp.com/b');
await service.request('https://fxali.dgjapp.com/c');
} finally {
global.fetch = originFetch;
}
const gaps = stamps.slice(1).map((time, index) => time - stamps[index]);
console.log('相邻请求间隔(ms):', gaps.join(', '));
assert.strictEqual(stamps.length, 3);
assert.ok(gaps.every(gap => gap >= 30), '每次请求至少间隔 40ms(留少量误差)');
});
});

View File

@ -120,14 +120,23 @@ NOT_MATCH_SEGMENT_CHANNEL#…此运单号非抖音的运单号…`。
| 772085215446719 | `#13`(更早) | 不再无脑取最新那条 |
| 760000000000000(不存在) | 无 | 返回 null 并 `warn`,报文不带别人的面单标识 |
**请求量控制(避免被平台判成刷单/攻击)**:
**请求量控制(避免被平台判成刷单/攻击,以及服务商级 QPS 限流)**:
店管家对请求量有两道闸:**风控/刷单判定**(行为特征)和 **服务商级 QPS 限流**
(实测返回 `isv.request-limited 请求太频繁…配置限流QPS:600, 当前访问QPS:687`)。
后者是全 ISV 共享的额度,我们自己的突发只是其中一部分,所以既要把自己的峰值削平,
也要在被限流时退避重试而不是直接判失败。
| 手段 | 说明 |
|---|---|
| 全局请求间隔 | `dgj.request()` 是所有平台调用的唯一出口,统一排队:相邻两次请求至少间隔 `DGJ_REQUEST_INTERVAL_MS`(默认 100ms → 单进程约 10 请求/秒) |
| 限流自动退避 | `postPlatformForm()`(订单/模板校验/取号/发货/回读都走它)命中 `isv.request-limited / 请求太频繁 / 访问QPS` 时自动退避重试:`DGJ_RATE_LIMIT_RETRY`(默认 3 次)、`DGJ_RATE_LIMIT_BACKOFF_MS`(默认 1000ms,指数退避);仍限流则抛「店管家接口限流:…;已自动退避重试 N 次仍被限流,请稍后重试」 |
| 取号并发 | `WAYBILL_CONCURRENCY`(默认 2,原 4):批量取号每单要 3 次平台调用(回读订单 + 模板校验 + ExpressPrint),并发越低突发越平 |
| 发货不回读订单行 | 快照拼报文,每单只有 1 次 `POST /NewOrder/OnlineSend` |
| 逐单间隔 | 同批相邻两单之间 `EXTERNAL_SEND_INTERVAL_MS`(默认 300ms) |
| traceId 缓存 | `getUserInfo` 按账号缓存(批量内只调 1 次),不再逐单取 |
| 取号侧同理 | `dgj.resolveTraceId()` 实例级缓存 5 分钟,批量取号不再每单一次 `getUserInfo` |
| 发货逐单间隔 | 同批相邻两单之间 `EXTERNAL_SEND_INTERVAL_MS`(默认 300ms) |
| 发货限流不计次 | 平台限流不是这单的问题:`external_send_status` 保持「待重试」,**不累加** `external_send_times`,等下一轮调度(2 分钟)再试,避免一批单被打成「异常」 |
| traceId 缓存 | `getUserInfo` 按账号缓存(批量内只调 1 次);`dgj.resolveTraceId()` 实例级缓存 5 分钟 |
| 模板校验不缓存 | `CheckTemplateAvaliable` 返回的 `DateNow / DayPrintBatchNumber` 会拼进 `RequestBatchNumber`,属于单次打印批次标识,跨单复用有风险,因此不做缓存 |
**失败单不转表**:进了配送说明仓库已打包发货,是既成事实,必须留在配送表可见/可导出;
只在配送表标记 `external_send_status`(2 待重试 / 3 同步异常),由「配送异常」视图筛出来处理。