You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

352 lines
11 KiB

package common.ecommerce.shared.raw;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.time.Instant;
/**
* 一次 HTTP 往返的原始留痕(不可变)。
*
* <p>只承载「平台真正回了什么」,不做业务解释:请求元信息、响应原文、
* 体积摘要与耗时。原文超过上限时<b>整份丢弃</b>而不截断——半截 JSON
* 既不能入库也不能排查,还会让人误以为拿到了完整数据,因此只保留
* 字节数与 SHA-256,由 {@link BodyState} 显式表达。</p>
*
* <p><b>敏感信息约定</b>:{@link #toString()} 不输出正文;正文里可能含买家
* 姓名、地址、电话等个人信息,禁止直接打日志。请求体默认不采集
* ({@link RawCapturePolicy#includeRequest()} 默认 false),因为领星请求体含签名。</p>
*/
public final class RawExchange {
/** 响应原文的保留状态。 */
public enum BodyState {
/** 平台没有返回响应体。 */
EMPTY,
/** 原文完整保留,见 {@link #responseBody()}。 */
FULL,
/** 超过体积上限,正文已丢弃;只有 {@link #bodyBytes()} 与 {@link #bodySha256()} 可信。 */
OMITTED_TOO_LARGE
}
/** 同一业务调用内的往返序号,从 1 开始;列表接口恒为 1。 */
private final int sequence;
/** 操作名,如 {@code salesOrders.pull}。 */
private final String operation;
/** HTTP 方法。 */
private final String httpMethod;
/** 请求地址;领星没有 query token,可原样保留。 */
private final String url;
/** 请求体;未开启采集时为 null。 */
private final String requestBody;
/** HTTP 状态码。 */
private final int httpStatus;
/** 平台业务码,如领星 {@code code=0};无则为 null。 */
private final String platformCode;
/** 平台业务消息。 */
private final String platformMessage;
/** 平台侧工单号(领星顶层 {@code request_id});无则为 null。 */
private final String platformRequestId;
/** 我方链路 ID。 */
private final String requestId;
/** 响应到达时间。 */
private final Instant fetchedAt;
/** 本次往返耗时(毫秒)。 */
private final long durationMillis;
/** 响应原文;超限或为空时为 null。 */
private final String responseBody;
/** 响应原文的 UTF-8 字节数(丢弃前)。 */
private final long bodyBytes;
/** 响应原文全文的 SHA-256(丢弃前),用于去重与校验。 */
private final String bodySha256;
/** 原文保留状态。 */
private final BodyState bodyState;
/** 由 Builder 装配;无必填字段,缺失即为 null。 */
private RawExchange(Builder b) {
this.sequence = b.sequence;
this.operation = b.operation;
this.httpMethod = b.httpMethod;
this.url = b.url;
this.requestBody = b.requestBody;
this.httpStatus = b.httpStatus;
this.platformCode = b.platformCode;
this.platformMessage = b.platformMessage;
this.platformRequestId = b.platformRequestId;
this.requestId = b.requestId;
this.fetchedAt = b.fetchedAt;
this.durationMillis = b.durationMillis;
this.responseBody = b.responseBody;
this.bodyBytes = b.bodyBytes;
this.bodySha256 = b.bodySha256;
this.bodyState = b.bodyState;
}
public static Builder builder() {
return new Builder();
}
/** 往返序号,从 1 开始;列表接口恒为 1。 */
public int sequence() {
return sequence;
}
/** 操作名,如 {@code salesOrders.pull}。 */
public String operation() {
return operation;
}
/** HTTP 方法。 */
public String httpMethod() {
return httpMethod;
}
/** 请求地址。 */
public String url() {
return url;
}
/** 请求体;未开启采集时为 null。 */
public String requestBody() {
return requestBody;
}
/** HTTP 状态码。 */
public int httpStatus() {
return httpStatus;
}
/** 平台业务码;无则为 null。 */
public String platformCode() {
return platformCode;
}
/** 平台业务消息。 */
public String platformMessage() {
return platformMessage;
}
/** 平台侧工单号;无则为 null。 */
public String platformRequestId() {
return platformRequestId;
}
/** 我方链路 ID。 */
public String requestId() {
return requestId;
}
/** 响应到达时间。 */
public Instant fetchedAt() {
return fetchedAt;
}
/** 本次往返耗时(毫秒)。 */
public long durationMillis() {
return durationMillis;
}
/** 响应原文;超限或为空时为 null。 */
public String responseBody() {
return responseBody;
}
/** 响应原文的 UTF-8 字节数(丢弃前)。 */
public long bodyBytes() {
return bodyBytes;
}
/** 响应原文全文的 SHA-256(丢弃前)。 */
public String bodySha256() {
return bodySha256;
}
/** 原文保留状态。 */
public BodyState bodyState() {
return bodyState;
}
/** 是否因超限丢弃了正文。 */
public boolean truncated() {
return bodyState == BodyState.OMITTED_TOO_LARGE;
}
/** 只有元信息与摘要,不含正文——可直接用于日志排查。 */
@Override
public String toString() {
return "RawExchange{" + (httpMethod == null ? "?" : httpMethod) + " " + url
+ " op=" + operation
+ " seq=" + sequence
+ " status=" + httpStatus
+ " code=" + platformCode
+ " requestId=" + requestId
+ " platformRequestId=" + platformRequestId
+ " bytes=" + bodyBytes
+ " sha256=" + bodySha256
+ " body=" + bodyState
+ " cost=" + durationMillis + "ms"
+ '}';
}
/** 可变构建器;{@link #body(String, int)} 负责算体积、摘要与保留状态。 */
public static final class Builder {
private int sequence = 1;
private String operation;
private String httpMethod;
private String url;
private String requestBody;
private int httpStatus;
private String platformCode;
private String platformMessage;
private String platformRequestId;
private String requestId;
private Instant fetchedAt;
private long durationMillis;
private String responseBody;
private long bodyBytes;
private String bodySha256;
private BodyState bodyState = BodyState.EMPTY;
/** 往返序号,从 1 开始。 */
public Builder sequence(int sequence) {
this.sequence = sequence;
return this;
}
/** 操作名,如 {@code salesOrders.pull}。 */
public Builder operation(String operation) {
this.operation = operation;
return this;
}
/** HTTP 方法。 */
public Builder httpMethod(String httpMethod) {
this.httpMethod = httpMethod;
return this;
}
/** 请求地址。 */
public Builder url(String url) {
this.url = url;
return this;
}
/** 请求体;不采集时传 null。 */
public Builder requestBody(String requestBody) {
this.requestBody = requestBody;
return this;
}
/** HTTP 状态码。 */
public Builder httpStatus(int httpStatus) {
this.httpStatus = httpStatus;
return this;
}
/** 平台业务码。 */
public Builder platformCode(String platformCode) {
this.platformCode = platformCode;
return this;
}
/** 平台业务消息。 */
public Builder platformMessage(String platformMessage) {
this.platformMessage = platformMessage;
return this;
}
/** 平台侧工单号。 */
public Builder platformRequestId(String platformRequestId) {
this.platformRequestId = platformRequestId;
return this;
}
/** 我方链路 ID。 */
public Builder requestId(String requestId) {
this.requestId = requestId;
return this;
}
/** 响应到达时间。 */
public Builder fetchedAt(Instant fetchedAt) {
this.fetchedAt = fetchedAt;
return this;
}
/** 本次往返耗时(毫秒)。 */
public Builder durationMillis(long durationMillis) {
this.durationMillis = durationMillis;
return this;
}
/**
* 记录响应原文,同时算体积、SHA-256 与保留状态。
*
* <p>{@code maxBytes} 为正且原文超过它时,正文整份丢弃、状态为
* {@link BodyState#OMITTED_TOO_LARGE};传 0 或负数表示不限制。</p>
*
* @param rawBody 平台原始响应体,可为 null
* @param maxBytes 单份原文的字节上限
*/
public Builder body(String rawBody, int maxBytes) {
if (rawBody == null) {
this.responseBody = null;
this.bodyBytes = 0L;
this.bodySha256 = null;
this.bodyState = BodyState.EMPTY;
return this;
}
byte[] bytes = rawBody.getBytes(StandardCharsets.UTF_8);
this.bodyBytes = bytes.length;
this.bodySha256 = sha256Hex(bytes);
if (maxBytes > 0 && bytes.length > maxBytes) {
this.responseBody = null;
this.bodyState = BodyState.OMITTED_TOO_LARGE;
} else {
this.responseBody = rawBody;
this.bodyState = BodyState.FULL;
}
return this;
}
public RawExchange build() {
return new RawExchange(this);
}
/** 十六进制 SHA-256;JDK 自带实现,不引额外依赖。 */
private static String sha256Hex(byte[] bytes) {
try {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(bytes);
StringBuilder sb = new StringBuilder(hash.length * 2);
for (byte b : hash) {
sb.append(Character.forDigit((b >> 4) & 0xF, 16));
sb.append(Character.forDigit(b & 0xF, 16));
}
return sb.toString();
} catch (NoSuchAlgorithmException e) {
// JDK 必须提供 SHA-256;走到这里说明运行环境异常
throw new IllegalStateException("SHA-256 is not available", e);
}
}
}
}