package com.nanri.aiimage.config; import java.util.List; import java.util.Map; /** * 业务日志结构化字段规范(task-178,spec 11 §2)。 * * 规范字段集与缺失占位:业务日志统一携带 traceId/taskId/moduleType/stage/submissionId/ * chunkIndex/chunkTotal/jobId/result/errorType;某条日志缺失某字段用 {@link #MISSING} 占位, * 保证字段名稳定、可检索。值写入前消毒(去除换行/控制字符、超长截断),防止日志注入与字段错乱。 * * 不删任何现有日志;本类作为字段名与渲染的单一来源,供后续可观测性埋点(180+)统一使用。 */ public final class StructuredLog { /** 规范字段名(顺序即输出顺序,与 spec 11 §2 一致)。 */ public static final List FIELD_NAMES = List.of( "traceId", "taskId", "moduleType", "stage", "submissionId", "chunkIndex", "chunkTotal", "jobId", "result", "errorType"); /** 缺失字段占位符。 */ public static final String MISSING = "-"; /** 单值最大展示长度(字节),避免超长字段撑爆日志。 */ public static final int MAX_VALUE_LENGTH = 256; private StructuredLog() { } /** 渲染单个字段值:null/空 → 占位;消毒换行与控制字符;截断到上限。 */ public static String field(Object value) { if (value == null) { return MISSING; } String text = String.valueOf(value); if (text.isEmpty()) { return MISSING; } text = text.replace('\r', ' ').replace('\n', ' ').replace('\t', ' '); StringBuilder cleaned = new StringBuilder(text.length()); for (int i = 0; i < text.length(); i++) { char c = text.charAt(i); if (c < 0x20 && c != ' ') { continue; // 丢弃其余控制字符 } cleaned.append(c); } String result = cleaned.toString().trim(); if (result.length() > MAX_VALUE_LENGTH) { result = result.substring(0, MAX_VALUE_LENGTH); } return result.isEmpty() ? MISSING : result; } /** 统一 Token 部分脱敏:≤10 位全打码,长 token 保留前6+后4,中间 ***(与既有 maskForLog 一致)。 */ public static String maskToken(String value) { if (value == null || value.isBlank()) { return ""; } String text = value.trim(); if (text.length() <= 10) { return "***"; } return text.substring(0, 6) + "***" + text.substring(text.length() - 4); } /** * 按规范字段集渲染 key=value 串:仅输出规范字段、顺序固定,缺失字段用占位符, * 避免不同日志字段漂移。 */ public static String format(Map fields) { StringBuilder sb = new StringBuilder(); for (String name : FIELD_NAMES) { if (sb.length() > 0) { sb.append(' '); } Object value = fields == null ? null : fields.get(name); sb.append(name).append('=').append(field(value)); } return sb.toString(); } }