package common.ecommerce.xincang.http; import common.ecommerce.http.HttpResponse; import common.ecommerce.http.JsonCodec; import common.ecommerce.shared.error.AuthException; import common.ecommerce.shared.error.ChannelException; import common.ecommerce.shared.error.PlatformBusinessException; import common.ecommerce.shared.error.RateLimitException; import common.ecommerce.shared.error.TransientException; import common.ecommerce.shared.error.ValidationException; import common.ecommerce.xincang.XincangConstants; /** * 信仓响应信封校验。 * *

信仓统一外层(Apifox「OMS接口文档V2」):

*
 * { "rst": ..., "errno": 0, "err": "", "trace_id": "..." }
 * 
* *

两条成功判定:顶层 {@code errno} 为 0;业务接口的 {@code rst} 是 * {@code {"code":"0","msg":"","data":...}} 时还要求 {@code rst.code} 为 {@code "0"}。 * 登录是例外——它的 {@code rst} 直接是客户 / token 字段,没有 {@code code},缺失即视为通过。

* *

HTTP 401/403/429/5xx 仍按 HTTP 语义映射:网关或代理层直接拒绝时也要能正确分类。

*/ public final class XincangEnvelope { /** 原始响应体。 */ private final String rawBody; /** 信仓侧链路号 {@code trace_id};可能为 null。 */ private final String platformTraceId; private XincangEnvelope(String rawBody, String platformTraceId) { this.rawBody = rawBody; this.platformTraceId = platformTraceId; } /** * 校验 HTTP 状态与业务码。 * * @param response 传输层响应 * @param json 用于读 {@code errno} / {@code rst.code} / {@code trace_id} * @param operation 门面操作名,如 {@code token.fetch} * @param requestId 我方链路 ID * @throws AuthException 401 / 403 * @throws RateLimitException 429 * @throws TransientException 5xx * @throws ValidationException 其它非 2xx,或报文结构不符合预期 * @throws PlatformBusinessException errno 非 0,或 rst.code 非 0 */ public static XincangEnvelope of(HttpResponse response, JsonCodec json, String operation, String requestId) { int status = response.statusCode(); if (status == 401 || status == 403) { throw new AuthException(base(operation, requestId) .message("xincang auth failed: http " + status) .platformCode(String.valueOf(status)) .rawResponse(truncate(response.body())) .retryable(false)); } if (status == 429) { throw new RateLimitException(base(operation, requestId) .message("xincang rate limited") .platformCode(String.valueOf(status)) .retryable(true), retryAfterMillis(response)); } if (status >= 500) { throw new TransientException(base(operation, requestId) .message("xincang server error: http " + status) .platformCode(String.valueOf(status)) .retryable(true), null); } if (status < 200 || status >= 300) { throw new ValidationException(base(operation, requestId) .message("xincang request rejected: http " + status) .platformCode(String.valueOf(status)) .rawResponse(truncate(response.body())) .retryable(false)); } String body = response.body(); if (body == null || body.trim().isEmpty()) { throw new ValidationException(base(operation, requestId) .message("xincang returned an empty body") .retryable(false)); } String traceId = json.stringAt(body, "trace_id"); String errno = json.stringAt(body, "errno"); if (errno == null || errno.trim().isEmpty()) { throw new ValidationException(base(operation, requestId) .message("xincang response has no errno") .platformRequestId(traceId) .rawResponse(truncate(body)) .retryable(false)); } if (!XincangConstants.SUCCESS_ERRNO.equals(errno.trim())) { throw new PlatformBusinessException(base(operation, requestId) .message("xincang business error: errno=" + errno + ", err=" + json.stringAt(body, "err")) .platformCode(errno.trim()) .platformRequestId(traceId) .rawResponse(truncate(body)) .retryable(false)); } String rstCode = json.stringAt(body, "rst.code"); if (rstCode != null && !XincangConstants.SUCCESS_RST_CODE.equals(rstCode.trim())) { throw new PlatformBusinessException(base(operation, requestId) .message("xincang business error: rst.code=" + rstCode + ", rst.msg=" + json.stringAt(body, "rst.msg")) .platformCode(rstCode.trim()) .platformRequestId(traceId) .rawResponse(truncate(body)) .retryable(false)); } return new XincangEnvelope(body, traceId); } /** 原始响应体;不会是 null。 */ public String body() { return rawBody; } /** 信仓侧链路号 {@code trace_id};可能为 null。 */ public String platformTraceId() { return platformTraceId; } /** * 统一异常字段。 * *

返回 {@link ChannelException.Builder} 而不是 {@code WarehouseException.Builder}: * 仓库域的自定义异常仅有 {@code WarehouseException} 一个,其余分类(Auth / RateLimit / * Transient / Validation / PlatformBusiness)的构造器都收 {@code ChannelException.Builder}。

* *

{@code warehouseCode} 保留在签名里便于调用方一致传参,但 不写进 * {@code omsStoreId}——那是渠道域的店铺 ID,填仓编码会污染审计字段。 * 需要仓维度的错误请由适配器层包一层 {@code WarehouseException}。

*/ private static ChannelException.Builder base(String operation, String requestId) { return ChannelException.builder() .operation(operation) .provider(XincangConstants.ADAPTER_ID) .requestId(requestId); } /** {@code Retry-After} 秒折算毫秒;缺失按 1s。 */ private static long retryAfterMillis(HttpResponse response) { String header = response.header("Retry-After"); if (header == null || header.trim().isEmpty()) { return 1000L; } try { return Math.max(0L, Long.parseLong(header.trim()) * 1000L); } catch (NumberFormatException e) { return 1000L; } } private static String truncate(String body) { if (body == null) { return null; } return body.length() <= 2000 ? body : body.substring(0, 2000) + "..."; } }