高质量函数生成助手

/**

• High-resolution time source: prefers performance.now(), falls back to Date.now() */ function nowMs() { const p = typeof performance !== 'undefined' && performance && typeof performance.now === 'function' ? performance : null; return p ? p.now() : Date.now(); }

/**

• Error for attempt timeout */ class TimeoutError extends Error { constructor(message = 'Attempt timed out') { super(message); this.name = 'TimeoutError'; } }

/**

• Error for external abort */ class AbortError extends Error { constructor(message = 'Operation aborted') { super(message); this.name = 'AbortError'; } }

/**

• A combined token-bucket (rate limit) + semaphore (concurrency) implementation.

• • tokens refill over time up to capacity; consuming a token does NOT return it on release.
• • permits enforce max concurrency; permits are returned on release.

• Multiple calls can share an instance to achieve global throttling. / class TokenBucket { /*

  • @param {number} capacity - Max burst tokens and max concurrency permits (>=1 integer)
  • @param {number} refillPerSec - Tokens refilled per second (>0) */ constructor(capacity, refillPerSec) { if (!Number.isFinite(capacity) || capacity < 1 || Math.floor(capacity) !== capacity) { throw new TypeError('TokenBucket: capacity must be an integer >= 1'); } if (!Number.isFinite(refillPerSec) || refillPerSec <= 0) { throw new TypeError('TokenBucket: refillPerSec must be a number > 0'); } this.capacity = capacity; this.refillPerSec = refillPerSec;

  // Rate budget this.tokens = capacity; this.lastRefillMs = nowMs();

  // Concurrency permits this.permits = capacity;

  // Waiters queue this._waiters = []; // FIFO of { resolve, reject, minTimeMs, signal, onAbort } this._timerId = null; this._scheduledAtMs = 0; }

_refill() { const n = nowMs(); const elapsedMs = n - this.lastRefillMs; if (elapsedMs <= 0) return; const add = (elapsedMs / 1000) * this.refillPerSec; this.tokens = Math.min(this.capacity, this.tokens + add); this.lastRefillMs = n; }

_timeUntilOneTokenMs() { // Assuming _refill has been called if (this.tokens >= 1) return 0; const deficit = 1 - this.tokens; // positive return (deficit / this.refillPerSec) * 1000; }

_processQueue() { this._refill(); const now = nowMs();

// Fulfill as many as possible (must satisfy both rate token and permit)
let progressed = false;
while (this.tokens >= 1 && this.permits >= 1) {
  // Find the first waiter whose minTimeMs <= now
  let idx = -1;
  for (let i = 0; i < this._waiters.length; i++) {
    const w = this._waiters[i];
    if (!w.signal || !w.signal.aborted) {
      if (w.minTimeMs <= now) {
        idx = i;
        break;
      }
    } else {
      // Clean aborted waiter
      if (w.onAbort) w.signal.removeEventListener('abort', w.onAbort);
      this._waiters.splice(i, 1);
      i--;
    }
  }
  if (idx === -1) break;
  const waiter = this._waiters.splice(idx, 1)[0];
  if (waiter.onAbort) waiter.signal.removeEventListener('abort', waiter.onAbort);
  // Grant
  this.tokens -= 1;
  this.permits -= 1;
  progressed = true;
  waiter.resolve(() => {
    // release permit only; tokens remain consumed (rate limit)
    this.permits = Math.min(this.capacity, this.permits + 1);
    // Try to fulfill more waiters that may now get concurrency
    this._processQueue();
  });
}

// Reschedule if there are pending waiters
if (this._waiters.length > 0) {
  // Next time when a token is expected to be available for the earliest waiter.
  // If permits are zero, we cannot know when a permit will be available; we rely on release() to trigger processing.
  const soonestWaiterTime = this._waiters.reduce((min, w) => Math.min(min, w.minTimeMs), Infinity);
  const waitMs = Math.max(0, soonestWaiterTime - now);
  // If tokens insufficient and we have waiters blocked on tokens, schedule a timer
  // Only schedule if waitMs is finite
  if (Number.isFinite(waitMs)) {
    // Avoid setting redundant timers if we already scheduled sooner
    const fireAt = now + waitMs;
    if (this._timerId != null) {
      if (this._scheduledAtMs <= fireAt) {
        // existing timer fires earlier or same time, keep it
        return;
      }
      clearTimeout(this._timerId);
      this._timerId = null;
    }
    this._scheduledAtMs = fireAt;
    this._timerId = setTimeout(() => {
      this._timerId = null;
      this._scheduledAtMs = 0;
      this._processQueue();
    }, waitMs);
  }
} else {
  // No waiters; cancel any timer
  if (this._timerId != null) {
    clearTimeout(this._timerId);
    this._timerId = null;
    this._scheduledAtMs = 0;
  }
}

}

/**

• Acquire both a rate token and a concurrency permit.
• Resolves with a release function to return the permit when the attempt finishes.
• Rejects with AbortError if the provided signal aborts while waiting.
• @param {AbortSignal|undefined} signal
• @returns {Promise<() => void>} release function */ acquire(signal) { this._refill(); // Immediate path if ((!signal || !signal.aborted) && this.tokens >= 1 && this.permits >= 1) { this.tokens -= 1; this.permits -= 1; return Promise.resolve(() => { this.permits = Math.min(this.capacity, this.permits + 1); this._processQueue(); }); } return new Promise((resolve, reject) => { if (signal && signal.aborted) { reject(new AbortError()); return; } const waiter = { resolve, reject, minTimeMs: nowMs() + this._timeUntilOneTokenMs(), signal, onAbort: null, }; if (signal) { waiter.onAbort = () => { // Remove the waiter and reject const i = this._waiters.indexOf(waiter); if (i >= 0) this._waiters.splice(i, 1); reject(new AbortError()); }; signal.addEventListener('abort', waiter.onAbort, { once: true }); } this._waiters.push(waiter); this._processQueue(); }); } }

// Global shared buckets keyed by config const _sharedBuckets = new Map(); /**

• Get a shared TokenBucket for given params, or use injected instance.
• @param {{ bucketSize: number, refillPerSec: number, bucket?: TokenBucket }} rateLimit */ function getBucket(rateLimit) { if (rateLimit && rateLimit.bucket instanceof TokenBucket) return rateLimit.bucket; const key = ${rateLimit.bucketSize}:${rateLimit.refillPerSec}; let b = _sharedBuckets.get(key); if (!b) { b = new TokenBucket(rateLimit.bucketSize, rateLimit.refillPerSec); _sharedBuckets.set(key, b); } return b; }

/**

• Sleep for given milliseconds. Rejects with AbortError if signal aborts during sleep.
• @param {number} ms
• @param {AbortSignal|undefined} signal
• @returns {Promise} */ function sleep(ms, signal) { if (ms <= 0) return Promise.resolve(); return new Promise((resolve, reject) => { const tid = setTimeout(() => { cleanup(); resolve(); }, ms); const onAbort = () => { clearTimeout(tid); cleanup(); reject(new AbortError()); }; const cleanup = () => { if (signal && onAbort) { signal.removeEventListener('abort', onAbort); } }; if (signal) { if (signal.aborted) { clearTimeout(tid); cleanup(); reject(new AbortError()); return; } signal.addEventListener('abort', onAbort, { once: true }); } }); }

/**

• @template T
• @typedef {Object} RetryResult
• @property {T} value - 任务成功返回值
• @property {number} attempts - 实际尝试次数（含成功一次）
• @property {number} lastDelayMs - 最后一次延迟毫秒（成功在第1次则为0）
• @property {number} durationMs - 从开始到成功的总耗时 */

/**

• 在令牌桶限流下执行带指数退避与抖动的重试。
• 参数校验：
• • retries: integer >= 0
• • baseDelayMs: number >= 0
• • jitter: 'none' | 'full'
• • rateLimit.bucketSize: integer >= 1
• • rateLimit.refillPerSec: number > 0
• • timeoutMs: number > 0
• 令牌桶说明：
• • bucketSize 同时用于突发容量与最大并发（通过内部的 permits 实现）。
• • refillPerSec 控制令牌补充速率（速率限流）。
• • 多个调用默认共享相同参数的全局桶；可通过 rateLimit.bucket 注入独立桶。
• 重试逻辑：
• 1. 每次尝试前 acquire：若无令牌或并发受限则等待；支持 AbortSignal 取消。
• 2. 执行 fn，应用 timeoutMs 超时控制；超时或取消立即释放并返回错误。
• 3. 失败进行指数退避：delay = baseDelayMs * 2^attemptIndex；抖动 full 则使用 [0, delay) 随机。
• 4. 达到最大重试仍失败，抛出 AggregateError，包含每次失败错误与尝试索引（1-based）。
• @template T
• @param {() => Promise} fn 需要重试的异步任务
• @param {number} retries 最大重试次数，>=0
• @param {'none'|'full'} jitter 抖动策略
• @param {{ bucketSize: number, refillPerSec: number, bucket?: TokenBucket }} rateLimit 令牌桶参数；可选注入 bucket 实例
• @param {number} baseDelayMs 初始延迟毫秒，用于指数退避
• @param {number} timeoutMs 每次尝试的超时毫秒
• @param {(err: any, attempt: number, delayMs: number) => void} [onRetry] 重试回调
• @param {AbortSignal} [signal] 可选取消信号，触发后立即终止
• @returns {Promise<RetryResult>} */ async function retryWithRateLimit(fn, retries, baseDelayMs, jitter, rateLimit, timeoutMs, onRetry, signal) { // Parameter validation if (typeof fn !== 'function') throw new TypeError('fn must be a function returning Promise'); if (!Number.isFinite(retries) || retries < 0 || Math.floor(retries) !== retries) { throw new TypeError('retries must be an integer >= 0'); } if (jitter !== 'none' && jitter !== 'full') { throw new TypeError("jitter must be 'none' or 'full'"); } if (!rateLimit || typeof rateLimit !== 'object') { throw new TypeError('rateLimit must be an object'); } const { bucketSize, refillPerSec } = rateLimit; if (!Number.isFinite(bucketSize) || bucketSize < 1 || Math.floor(bucketSize) !== bucketSize) { throw new TypeError('rateLimit.bucketSize must be an integer >= 1'); } if (!Number.isFinite(refillPerSec) || refillPerSec <= 0) { throw new TypeError('rateLimit.refillPerSec must be a number > 0'); } if (!Number.isFinite(baseDelayMs) || baseDelayMs < 0) { throw new TypeError('baseDelayMs must be a number >= 0'); } if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) { throw new TypeError('timeoutMs must be a number > 0'); }

const bucket = getBucket(rateLimit); const startMs = nowMs(); let lastDelayMs = 0; let attempts = 0; const errors = [];

// Helper to create a timeout promise const makeTimeoutPromise = () => new Promise((_, reject) => { const id = setTimeout(() => reject(new TimeoutError()), timeoutMs); // Return handle to clear makeTimeoutPromise._id = id; });

for (let attemptIndex = 0; attemptIndex <= retries; attemptIndex++) { // Before each attempt, honor external abort if (signal && signal.aborted) { throw new AbortError(); }

// Acquire rate token + concurrency permit
let release;
try {
  release = await bucket.acquire(signal);
} catch (e) {
  // Acquire can reject with AbortError
  throw e;
}
attempts++;

// Create abort and timeout races
const timeoutPromise = makeTimeoutPromise();
const timeoutId = makeTimeoutPromise._id;

const abortPromise = new Promise((_, reject) => {
  if (signal) {
    if (signal.aborted) {
      reject(new AbortError());
      return;
    }
    signal.addEventListener('abort', () => reject(new AbortError()), { once: true });
  }
});

try {
  const result = await Promise.race(
    signal ? [fn(), timeoutPromise, abortPromise] : [fn(), timeoutPromise]
  );
  // Success
  clearTimeout(timeoutId);
  release();
  const durationMs = nowMs() - startMs;
  return {
    value: result,
    attempts,
    lastDelayMs,
    durationMs,
  };
} catch (err) {
  clearTimeout(timeoutId);
  // Always release permit on failure/timeout/abort
  release();

  // Abort: terminate immediately
  if (err instanceof AbortError) {
    throw err;
  }

  // Record failure
  errors.push({ error: err, attempt: attemptIndex + 1 });

  // Exhausted?
  if (attemptIndex >= retries) {
    const agg = new AggregateError(
      errors.map(e => e.error),
      `All ${attempts} attempts failed`
    );
    // Attach attempt indices for diagnostics
    agg.attempts = errors.map(e => e.attempt);
    throw agg;
  }

  // Compute backoff delay
  const base = baseDelayMs * Math.pow(2, attemptIndex);
  const delayMs = jitter === 'full' ? Math.floor(Math.random() * base) : base;
  lastDelayMs = delayMs;

  if (typeof onRetry === 'function') {
    try {
      // attempt is 1-based count of the attempt that just failed
      onRetry(err, attemptIndex + 1, delayMs);
    } catch { /* ignore onRetry errors */ }
  }

  // Sleep before next attempt, respecting abort
  await sleep(delayMs, signal);
}

}

// Should never reach here throw new Error('Unexpected control flow in retryWithRateLimit'); }

// Export for Node/CommonJS if needed // module.exports = { retryWithRateLimit, TokenBucket, TimeoutError, AbortError };

下面给出一个完整可用的 Java 实现，包含核心函数 mergeConfigWithSchema、模式结构 SchemaField、返回结果结构 MergeResult，以及必要的工具与安全校验逻辑。代码遵从不可变与线程安全原则，不修改输入 Map；对对象与数组进行深度合并与类型校验/转换；收集应用默认、类型转换与回退的诊断信息；并提供循环引用与最大深度防护。

代码说明要点：

• 支持点号路径（如 "db.pool.size"），可从嵌套对象或扁平键两种形式读取值。
• userConfig 优先于 baseConfig；缺失且有 default 时应用默认。
• 类型校验与可选类型转换（coerce）：数字字符串、布尔字符串；对象/数组尝试 JSON 字符串解析（若运行环境有 Jackson）。
• 对象字段深度合并；数组字段支持 replace 或 concat（保留顺序、不去重）。
• 枚举与自定义校验不通过时回退到默认并记录警告；若无默认则保留原值并记录警告，以保证可用性。
• 返回的 config 为不可变视图（深度不可变）。
• 最大路径深度与递归深度防护；循环引用检测。
• 不修改输入 Map；所有新结构均为新建。

可直接复制到工程中使用。

/**

• 配置合并工具：按 Schema 安全合并 baseConfig 与 userConfig。
• 设计目标：
• • 线程安全：不修改输入 Map，所有写操作在新结构上完成。
• • 支持点号路径访问与路径创建。
• • 类型校验与可选类型转换；失败时记录警告并尽可能保持可用性。
• • 深度合并对象；数组按策略 replace 或 concat。
• • 支持枚举与自定义校验；不通过时回退默认并记录。
• • 防止无限递归与循环引用。 / import java.util.; import java.util.function.Predicate;

public final class ConfigMerger {

private static final int MAX_PATH_DEPTH = 64;
private static final int MAX_MERGE_DEPTH = 256;

public enum Type {
    STRING, NUMBER, BOOLEAN, OBJECT, ARRAY
}

public enum MergeStrategy {
    REPLACE, CONCAT
}

/**
 * Schema 字段定义。
 */
public static final class SchemaField {
    private final String name;                       // 点号路径，例如 "db.pool.size"
    private final Type type;                         // 期望类型
    private final boolean required;                  // 是否必需
    private final Object defaultValue;               // 默认值，可为 null 表示未提供
    private final List<Object> enumValues;           // 枚举约束，可为 null
    private final MergeStrategy mergeStrategy;       // 数组合并策略
    private final boolean coerce;                    // 是否允许类型转换
    private final Predicate<Object> validate;        // 自定义校验函数，可为 null

    private SchemaField(Builder builder) {
        this.name = Objects.requireNonNull(builder.name, "SchemaField.name");
        this.type = Objects.requireNonNull(builder.type, "SchemaField.type");
        this.required = builder.required;
        this.defaultValue = builder.defaultValue;
        this.enumValues = builder.enumValues == null ? null : new ArrayList<>(builder.enumValues);
        this.mergeStrategy = builder.mergeStrategy == null ? MergeStrategy.REPLACE : builder.mergeStrategy;
        this.coerce = builder.coerce;
        this.validate = builder.validate;
    }

    public String getName() { return name; }
    public Type getType() { return type; }
    public boolean isRequired() { return required; }
    public Object getDefaultValue() { return defaultValue; }
    public List<Object> getEnumValues() { return enumValues; }
    public MergeStrategy getMergeStrategy() { return mergeStrategy; }
    public boolean isCoerce() { return coerce; }
    public Predicate<Object> getValidate() { return validate; }

    public static Builder builder() { return new Builder(); }

    public static final class Builder {
        private String name;
        private Type type;
        private boolean required;
        private Object defaultValue;
        private List<Object> enumValues;
        private MergeStrategy mergeStrategy;
        private boolean coerce;
        private Predicate<Object> validate;

        public Builder name(String name) { this.name = name; return this; }
        public Builder type(Type type) { this.type = type; return this; }
        public Builder required(boolean required) { this.required = required; return this; }
        public Builder defaultValue(Object defaultValue) { this.defaultValue = defaultValue; return this; }
        public Builder enumValues(List<Object> enumValues) { this.enumValues = enumValues; return this; }
        public Builder mergeStrategy(MergeStrategy mergeStrategy) { this.mergeStrategy = mergeStrategy; return this; }
        public Builder coerce(boolean coerce) { this.coerce = coerce; return this; }
        public Builder validate(Predicate<Object> validate) { this.validate = validate; return this; }
        public SchemaField build() { return new SchemaField(this); }
    }
}

/**
 * 合并结果。
 */
public static final class MergeResult {
    private final Map<String, Object> config;            // 不可变视图（深度）
    private final List<String> warnings;                 // 警告信息
    private final Map<String, Object> appliedDefaults;   // 应用默认值映射（路径->默认）
    private final List<String> coercedFields;            // 完成类型转换的字段路径列表

    public MergeResult(Map<String, Object> config,
                       List<String> warnings,
                       Map<String, Object> appliedDefaults,
                       List<String> coercedFields) {
        this.config = config;
        this.warnings = warnings;
        this.appliedDefaults = appliedDefaults;
        this.coercedFields = coercedFields;
    }

    public Map<String, Object> getConfig() { return config; }
    public List<String> getWarnings() { return warnings; }
    public Map<String, Object> getAppliedDefaults() { return appliedDefaults; }
    public List<String> getCoercedFields() { return coercedFields; }
}

/**
 * 主函数：按给定 schema 安全合并 baseConfig 与 userConfig。
 *
 * 合并规则：
 * 1) 优先取 userConfig 值，其次 baseConfig；缺失且有 default 时应用默认。
 * 2) 类型校验与可选类型转换（coerce）：数字、布尔、JSON对象/数组；失败记录警告，仍保留原值或默认以保证可用性。
 * 3) 深度合并：对象字段递归合并（user 覆盖 base）；数组根据 mergeStrategy 替换或拼接（concat 保留顺序）。
 * 4) 枚举与自定义校验：不通过回退默认并记录警告；无默认则保留当前值并记录警告。
 * 5) 结果不可变：返回新的 Map 且深度不可变；收集诊断信息。
 * 6) 防护：最大深度与循环引用检测。
 *
 * 注意：仅处理 schema 中定义的字段；未在 schema 定义的字段不会出现在结果中。
 */
public static MergeResult mergeConfigWithSchema(Map<String, Object> baseConfig,
                                               Map<String, Object> userConfig,
                                               List<SchemaField> schema) {
    Map<String, Object> base = baseConfig == null ? Collections.emptyMap() : baseConfig;
    Map<String, Object> user = userConfig == null ? Collections.emptyMap() : userConfig;
    List<SchemaField> sch = schema == null ? Collections.emptyList() : schema;

    Map<String, Object> resultRoot = new LinkedHashMap<>();
    List<String> warnings = new ArrayList<>();
    Map<String, Object> appliedDefaults = new LinkedHashMap<>();
    List<String> coercedFields = new ArrayList<>();

    for (SchemaField field : sch) {
        String path = field.getName();
        if (path == null || path.trim().isEmpty()) {
            warnings.add("Schema field has empty path; skipped.");
            continue;
        }

        List<String> parts = splitPath(path);
        if (parts.size() > MAX_PATH_DEPTH) {
            warnings.add("Path depth exceeds limit (" + MAX_PATH_DEPTH + "): " + path);
            continue;
        }

        // 从 user 优先，再从 base；同时保留对象/数组的双源以便深度合并
        Object userVal = getValueByPath(user, parts, path);
        Object baseVal = getValueByPath(base, parts, path);

        Object finalVal;

        // 对象字段：进行深度合并
        if (field.getType() == Type.OBJECT) {
            Map<String, Object> oUser = toMapOrNull(userVal);
            Map<String, Object> oBase = toMapOrNull(baseVal);

            // 当缺失且有默认：默认可为 Map（优先作为初始 base）
            Map<String, Object> oDefault = toMapOrNull(field.getDefaultValue());

            Map<String, Object> merged;
            IdentityHashMap<Object, Boolean> visited = new IdentityHashMap<>();

            if (oUser == null && oBase == null && oDefault == null) {
                if (field.isRequired()) {
                    warnings.add("Required object field missing and no default: " + path);
                }
                merged = new LinkedHashMap<>();
            } else {
                Map<String, Object> baseForMerge = oBase != null ? oBase : (oDefault != null ? oDefault : new LinkedHashMap<>());
                merged = deepMergeMaps(baseForMerge, oUser, 0, visited, warnings, path);
                if (oUser == null && oBase == null && oDefault != null) {
                    appliedDefaults.put(path, deepCopyValue(oDefault, new IdentityHashMap<>(), 0, warnings, path));
                }
            }
            // 枚举/校验针对整个对象（一般不常用）；若失败，回退默认或保留并警告
            if (!checkEnum(field, merged)) {
                if (oDefault != null) {
                    merged = deepCopyValue(oDefault, new IdentityHashMap<>(), 0, warnings, pathMap(path));
                    warnings.add("Enum constraint failed on object; applied default for: " + path);
                    appliedDefaults.put(path, deepCopyValue(oDefault, new IdentityHashMap<>(), 0, warnings, path));
                } else {
                    warnings.add("Enum constraint failed on object and no default; kept value for: " + path);
                }
            }
            if (field.getValidate() != null && !safeValidate(field.getValidate(), merged)) {
                if (oDefault != null) {
                    merged = deepCopyValue(oDefault, new IdentityHashMap<>(), 0, warnings, pathMap(path));
                    warnings.add("Custom validation failed on object; applied default for: " + path);
                    appliedDefaults.put(path, deepCopyValue(oDefault, new IdentityHashMap<>(), 0, warnings, path));
                } else {
                    warnings.add("Custom validation failed on object and no default; kept value for: " + path);
                }
            }
            finalVal = merged;

        } else if (field.getType() == Type.ARRAY) {
            // 数组字段：按策略合并
            List<Object> aUser = toListOrNull(userVal, field, warnings, coercedFields, path);
            List<Object> aBase = toListOrNull(baseVal, field, warnings, coercedFields, path);
            List<Object> aDefault = toListOrNull(field.getDefaultValue(), field, warnings, coercedFields, path);

            List<Object> merged;
            if (field.getMergeStrategy() == MergeStrategy.CONCAT) {
                merged = new ArrayList<>();
                if (aBase != null) merged.addAll(deepCopyList(aBase, warnings, path));
                if (aUser != null) merged.addAll(deepCopyList(aUser, warnings, path));
                if (aBase == null && aUser == null) {
                    if (aDefault != null) {
                        merged.addAll(deepCopyList(aDefault, warnings, path));
                        appliedDefaults.put(path, deepCopyList(aDefault, warnings, path));
                    } else {
                        merged = new ArrayList<>();
                        if (field.isRequired()) {
                            warnings.add("Required array field missing and no default: " + path);
                        }
                    }
                }
            } else {
                // REPLACE
                if (aUser != null) {
                    merged = deepCopyList(aUser, warnings, path);
                } else if (aBase != null) {
                    merged = deepCopyList(aBase, warnings, path);
                } else if (aDefault != null) {
                    merged = deepCopyList(aDefault, warnings, path);
                    appliedDefaults.put(path, deepCopyList(aDefault, warnings, path));
                } else {
                    merged = new ArrayList<>();
                    if (field.isRequired()) {
                        warnings.add("Required array field missing and no default: " + path);
                    }
                }
            }

            // 枚举：针对数组元素，所有元素必须在 enum 中
            if (!checkEnumForArray(field, merged)) {
                if (aDefault != null) {
                    merged = deepCopyList(aDefault, warnings, path);
                    warnings.add("Enum constraint failed on array; applied default for: " + path);
                    appliedDefaults.put(path, deepCopyList(aDefault, warnings, path));
                } else {
                    warnings.add("Enum constraint failed on array and no default; kept value for: " + path);
                }
            }
            // 自定义校验
            if (field.getValidate() != null && !safeValidate(field.getValidate(), merged)) {
                if (aDefault != null) {
                    merged = deepCopyList(aDefault, warnings, path);
                    warnings.add("Custom validation failed on array; applied default for: " + path);
                    appliedDefaults.put(path, deepCopyList(aDefault, warnings, path));
                } else {
                    warnings.add("Custom validation failed on array and no default; kept value for: " + path);
                }
            }
            finalVal = merged;

        } else {
            // 标量类型：取 user/base/default，然后进行类型校验与可选转换
            Object candidate = userVal != null ? userVal : baseVal;
            boolean appliedDefaultNow = false;

            if (candidate == null) {
                if (field.getDefaultValue() != null) {
                    candidate = field.getDefaultValue();
                    appliedDefault.putSafe(appliedDefaults, path, field.getDefaultValue());
                    appliedDefaultNow = true;
                } else if (field.isRequired()) {
                    warnings.add("Required field missing and no default: " + path);
                }
            }

            Object normalized = normalizeScalar(candidate, field, warnings, coercedFields, path);
            // 枚举
            if (!checkEnum(field, normalized)) {
                if (field.getDefaultValue() != null) {
                    normalized = field.getDefaultValue();
                    if (!appliedDefaultNow) {
                        appliedDefault.putSafe(appliedDefaults, path, field.getDefaultValue());
                    }
                    warnings.add("Enum constraint failed; applied default for: " + path);
                } else {
                    warnings.add("Enum constraint failed and no default; kept value for: " + path);
                }
            }
            // 自定义校验
            if (field.getValidate() != null && !safeValidate(field.getValidate(), normalized)) {
                if (field.getDefaultValue() != null) {
                    normalized = field.getDefaultValue();
                    if (!appliedDefaultNow) {
                        appliedDefault.putSafe(appliedDefaults, path, field.getDefaultValue());
                    }
                    warnings.add("Custom validation failed; applied default for: " + path);
                } else {
                    warnings.add("Custom validation failed and no default; kept value for: " + path);
                }
            }
            finalVal = normalized;
        }

        // 写入结果，创建必要层级
        putValueByPath(resultRoot, parts, deepCopyValue(finalVal, new IdentityHashMap<>(), 0, warnings, path));
    }

    // 返回深度不可变视图
    Map<String, Object> immutable = asUnmodifiableDeep(resultRoot, new IdentityHashMap<>(), 0);
    return new MergeResult(immutable,
            Collections.unmodifiableList(new ArrayList<>(warnings)),
            Collections.unmodifiableMap(new LinkedHashMap<>(appliedDefaults)),
            Collections.unmodifiableList(new ArrayList<>(coercedFields)));
}

// ----------------- 工具与内部实现 -----------------

private static List<String> splitPath(String path) {
    String[] arr = path.split("\\.");
    List<String> parts = new ArrayList<>(arr.length);
    for (String p : arr) {
        if (!p.isEmpty()) parts.add(p);
    }
    return parts;
}

/**
 * 从 Map 按路径取值。支持两种形式：
 * - 嵌套对象：db -> pool -> size
 * - 扁平键：直接存在 "db.pool.size"
 */
@SuppressWarnings("unchecked")
private static Object getValueByPath(Map<String, Object> root, List<String> parts, String fullPathKey) {
    if (root == null) return null;
    if (root.containsKey(fullPathKey)) {
        return root.get(fullPathKey);
    }
    Map<String, Object> cur = root;
    for (int i = 0; i < parts.size(); i++) {
        Object v = cur.get(parts.get(i));
        if (v == null) return null;
        if (i == parts.size() - 1) return v;
        if (!(v instanceof Map)) return null;
        cur = (Map<String, Object>) v;
    }
    return null;
}

@SuppressWarnings("unchecked")
private static void putValueByPath(Map<String, Object> root, List<String> parts, Object value) {
    Map<String, Object> cur = root;
    for (int i = 0; i < parts.size() - 1; i++) {
        String p = parts.get(i);
        Object existing = cur.get(p);
        Map<String, Object> next;
        if (existing instanceof Map) {
            next = (Map<String, Object>) existing;
        } else {
            next = new LinkedHashMap<>();
            cur.put(p, next);
        }
        cur = next;
    }
    cur.put(parts.get(parts.size() - 1), value);
}

@SuppressWarnings("unchecked")
private static Map<String, Object> toMapOrNull(Object v) {
    return (v instanceof Map) ? (Map<String, Object>) v : null;
}

@SuppressWarnings("unchecked")
private static List<Object> toListOrNull(Object v, SchemaField field,
                                         List<String> warnings,
                                         List<String> coercedFields,
                                         String path) {
    if (v instanceof List) {
        return (List<Object>) v;
    }
    if (v instanceof String && field.isCoerce()) {
        String s = (String) v;
        Optional<Object> parsed = tryParseJson(s);
        if (parsed.isPresent() && parsed.get() instanceof List) {
            coercedFields.add(path);
            return (List<Object>) parsed.get();
        } else {
            warnings.add("Failed to coerce string to array (JSON parse missing or invalid): " + path);
        }
    }
    return null;
}

private static boolean checkEnum(SchemaField field, Object value) {
    List<Object> enums = field.getEnumValues();
    if (enums == null || enums.isEmpty()) return true;
    // 若为数组类型，在专用方法中处理；此处针对非数组类型
    if (field.getType() == Type.ARRAY) return true;
    for (Object e : enums) {
        if (Objects.equals(e, value)) return true;
    }
    return false;
}

private static boolean checkEnumForArray(SchemaField field, List<Object> arr) {
    if (field.getType() != Type.ARRAY) return true;
    List<Object> enums = field.getEnumValues();
    if (enums == null || enums.isEmpty()) return true;
    if (arr == null) return true;
    for (Object v : arr) {
        boolean ok = false;
        for (Object e : enums) {
            if (Objects.equals(e, v)) {
                ok = true; break;
            }
        }
        if (!ok) return false;
    }
    return true;
}

private static boolean safeValidate(Predicate<Object> validate, Object value) {
    try {
        return validate.test(value);
    } catch (Exception e) {
        return false;
    }
}

private static Object normalizeScalar(Object candidate,
                                      SchemaField field,
                                      List<String> warnings,
                                      List<String> coercedFields,
                                      String path) {
    if (candidate == null) return null;

    switch (field.getType()) {
        case STRING:
            if (candidate instanceof String) return candidate;
            if (field.isCoerce()) {
                coercedFields.add(path);
                return String.valueOf(candidate);
            } else {
                warnings.add("Type mismatch (expected string) for: " + path);
                return candidate;
            }

        case NUMBER:
            if (candidate instanceof Number) return candidate;
            if (candidate instanceof String && field.isCoerce()) {
                String s = ((String) candidate).trim();
                try {
                    Object num = parseNumber(s);
                    coercedFields.add(path);
                    return num;
                } catch (NumberFormatException ex) {
                    warnings.add("Failed to coerce string to number for: " + path);
                    return candidate;
                }
            } else {
                warnings.add("Type mismatch (expected number) for: " + path);
                return candidate;
            }

        case BOOLEAN:
            if (candidate instanceof Boolean) return candidate;
            if (field.isCoerce()) {
                Boolean b = coerceToBoolean(candidate);
                if (b != null) {
                    coercedFields.add(path);
                    return b;
                } else {
                    warnings.add("Failed to coerce to boolean for: " + path);
                    return candidate;
                }
            } else {
                warnings.add("Type mismatch (expected boolean) for: " + path);
                return candidate;
            }

        case OBJECT:
            if (candidate instanceof Map) return candidate;
            if (candidate instanceof String && field.isCoerce()) {
                Optional<Object> parsed = tryParseJson((String) candidate);
                if (parsed.isPresent() && parsed.get() instanceof Map) {
                    coercedFields.add(path);
                    return parsed.get();
                } else {
                    warnings.add("Failed to coerce string to object (JSON parse missing or invalid) for: " + path);
                    return candidate;
                }
            } else {
                warnings.add("Type mismatch (expected object) for: " + path);
                return candidate;
            }

        case ARRAY:
            if (candidate instanceof List) return candidate;
            if (candidate instanceof String && field.isCoerce()) {
                Optional<Object> parsed = tryParseJson((String) candidate);
                if (parsed.isPresent() && parsed.get() instanceof List) {
                    coercedFields.add(path);
                    return parsed.get();
                } else {
                    warnings.add("Failed to coerce string to array (JSON parse missing or invalid) for: " + path);
                    return candidate;
                }
            } else {
                warnings.add("Type mismatch (expected array) for: " + path);
                return candidate;
            }

        default:
            return candidate;
    }
}

private static Object parseNumber(String s) {
    if (s.matches("[-+]?\\d+")) {
        return Long.parseLong(s);
    } else if (s.matches("[-+]?\\d*\\.\\d+([eE][-+]?\\d+)?") || s.matches("[-+]?\\d+([eE][-+]?\\d+)?")) {
        return Double.parseDouble(s);
    }
    throw new NumberFormatException("Invalid numeric string: " + s);
}

private static Boolean coerceToBoolean(Object v) {
    if (v instanceof Boolean) return (Boolean) v;
    if (v instanceof Number) {
        int i = ((Number) v).intValue();
        if (i == 0) return Boolean.FALSE;
        if (i == 1) return Boolean.TRUE;
    }
    if (v instanceof String) {
        String s = ((String) v).trim().toLowerCase(Locale.ROOT);
        switch (s) {
            case "true": case "1": case "yes": case "on": return Boolean.TRUE;
            case "false": case "0": case "no": case "off": return Boolean.FALSE;
            default: return null;
        }
    }
    return null;
}

@SuppressWarnings("unchecked")
private static Map<String, Object> deepMergeMaps(Map<String, Object> base,
                                                 Map<String, Object> user,
                                                 int depth,
                                                 IdentityHashMap<Object, Boolean> visited,
                                                 List<String> warnings,
                                                 String path) {
    if (depth > MAX_MERGE_DEPTH) {
        warnings.add("Exceeded max merge depth at: " + path);
        return new LinkedHashMap<>();
    }
    Map<String, Object> result = new LinkedHashMap<>();
    // copy base
    if (base != null) {
        for (Map.Entry<String, Object> e : base.entrySet()) {
            Object copied = deepCopyValue(e.getValue(), visited, depth + 1, warnings, path + "." + e.getKey());
            result.put(e.getKey(), copied);
        }
    }
    // merge user
    if (user != null) {
        for (Map.Entry<String, Object> e : user.entrySet()) {
            Object uVal = e.getValue();
            Object bVal = result.get(e.getKey());
            String childPath = path + "." + e.getKey();

            if (uVal != null && bVal != null && uVal instanceof Map && bVal instanceof Map) {
                Map<String, Object> mergedChild = deepMergeMaps((Map<String, Object>) bVal, (Map<String, Object>) uVal, depth + 1, visited, warnings, childPath);
                result.put(e.getKey(), mergedChild);
            } else {
                Object copied = deepCopyValue(uVal, visited, depth + 1, warnings, childPath);
                result.put(e.getKey(), copied);
            }
        }
    }
    return result;
}

@SuppressWarnings("unchecked")
private static Object deepCopyValue(Object v,
                                    IdentityHashMap<Object, Boolean> visited,
                                    int depth,
                                    List<String> warnings,
                                    String path) {
    if (v == null) return null;
    if (depth > MAX_MERGE_DEPTH) {
        warnings.add("Exceeded max copy depth at: " + path);
        return null;
    }
    if (visited.containsKey(v)) {
        warnings.add("Detected cyclic reference while copying at: " + path);
        return null;
    }
    if (v instanceof Map) {
        visited.put(v, Boolean.TRUE);
        Map<String, Object> src = (Map<String, Object>) v;
        Map<String, Object> copy = new LinkedHashMap<>();
        for (Map.Entry<String, Object> e : src.entrySet()) {
            copy.put(e.getKey(), deepCopyValue(e.getValue(), visited, depth + 1, warnings, path + "." + e.getKey()));
        }
        visited.remove(v);
        return copy;
    } else if (v instanceof List) {
        visited.put(v, Boolean.TRUE);
        List<Object> src = (List<Object>) v;
        List<Object> copy = new ArrayList<>(src.size());
        for (int i = 0; i < src.size(); i++) {
            copy.add(deepCopyValue(src.get(i), visited, depth + 1, warnings, path + "[" + i + "]"));
        }
        visited.remove(v);
        return copy;
    } else {
        // immutable/simple
        return v;
    }
}

private static List<Object> deepCopyList(List<Object> src,
                                         List<String> warnings,
                                         String path) {
    return (List<Object>) deepCopyValue(src, new IdentityHashMap<>(), 0, warnings, path);
}

@SuppressWarnings("unchecked")
private static Map<String, Object> asUnmodifiableDeep(Map<String, Object> v,
                                                      IdentityHashMap<Object, Boolean> visited,
                                                      int depth) {
    if (v == null) return null;
    if (visited.containsKey(v)) return Collections.unmodifiableMap(v); // already processed
    visited.put(v, Boolean.TRUE);
    Map<String, Object> copy = new LinkedHashMap<>();
    for (Map.Entry<String, Object> e : v.entrySet()) {
        Object val = e.getValue();
        if (val instanceof Map) {
            copy.put(e.getKey(), asUnmodifiableDeep((Map<String, Object>) val, visited, depth + 1));
        } else if (val instanceof List) {
            copy.put(e.getKey(), asUnmodifiableDeepList((List<Object>) val, visited, depth + 1));
        } else {
            copy.put(e.getKey(), val);
        }
    }
    return Collections.unmodifiableMap(copy);
}

@SuppressWarnings("unchecked")
private static List<Object> asUnmodifiableDeepList(List<Object> v,
                                                   IdentityHashMap<Object, Boolean> visited,
                                                   int depth) {
    if (v == null) return null;
    if (visited.containsKey(v)) return Collections.unmodifiableList(v);
    visited.put(v, Boolean.TRUE);
    List<Object> copy = new ArrayList<>(v.size());
    for (Object val : v) {
        if (val instanceof Map) {
            copy.add(asUnmodifiableDeep((Map<String, Object>) val, visited, depth + 1));
        } else if (val instanceof List) {
            copy.add(asUnmodifiableDeepList((List<Object>) val, visited, depth + 1));
        } else {
            copy.add(val);
        }
    }
    return Collections.unmodifiableList(copy);
}

/**
 * 尝试解析 JSON 字符串为 Object（Map 或 List）。如果环境未提供 Jackson，则返回 empty。
 * 使用反射探测 com.fasterxml.jackson.databind.ObjectMapper 是否存在。
 */
@SuppressWarnings("unchecked")
private static Optional<Object> tryParseJson(String json) {
    try {
        Class<?> omClass = Class.forName("com.fasterxml.jackson.databind.ObjectMapper");
        Object om = omClass.newInstance();
        Object reader = omClass.getMethod("readValue", String.class, Class.class).invoke(om, json, Object.class);
        return Optional.ofNullable(reader);
    } catch (Throwable ignore) {
        return Optional.empty();
    }
}

// 小工具：避免重复 put 默认值时覆盖为不同对象引用
private static final class appliedDefault {
    static void putSafe(Map<String, Object> map, String path, Object val) {
        map.put(path, val);
    }
}

// 为 deepCopyValue 的 path 展开辅助
private static String pathMap(String path) { return path; }

// ----------------- JavaDoc 使用示例与测试建议 -----------------

/**
 * 使用示例：
 *
 * Map<String, Object> base = new HashMap<>();
 * base.put("db", new HashMap<String, Object>() {{
 *     put("pool", new HashMap<String, Object>() {{
 *         put("size", 5);
 *     }});
 * }});
 *
 * Map<String, Object> user = new HashMap<>();
 * user.put("db", new HashMap<String, Object>() {{
 *     put("pool", new HashMap<String, Object>() {{
 *         put("size", "10"); // 字符串将被转换为数字
 *     }});
 * }});
 *
 * List<SchemaField> schema = Arrays.asList(
 *     SchemaField.builder()
 *         .name("db.pool.size")
 *         .type(Type.NUMBER)
 *         .required(true)
 *         .defaultValue(10)
 *         .coerce(true)
 *         .build(),
 *     SchemaField.builder()
 *         .name("feature.enabled")
 *         .type(Type.BOOLEAN)
 *         .required(false)
 *         .defaultValue(true)
 *         .coerce(true)
 *         .build(),
 *     SchemaField.builder()
 *         .name("tags")
 *         .type(Type.ARRAY)
 *         .mergeStrategy(MergeStrategy.CONCAT)
 *         .defaultValue(Arrays.asList("base"))
 *         .coerce(true)
 *         .build()
 * );
 *
 * MergeResult result = ConfigMerger.mergeConfigWithSchema(base, user, schema);
 * Map<String, Object> config = result.getConfig(); // 深度不可变
 * List<String> warnings = result.getWarnings();
 * Map<String, Object> appliedDefaults = result.getAppliedDefaults();
 * List<String> coerced = result.getCoercedFields();
 *
 * 预期：
 * - config["db"]["pool"]["size"] == 10（来自 user 的 "10" 字符串转换为数字 10）
 * - appliedDefaults 在 "db.pool.size" 缺失且 default=10 时会包含 { "db.pool.size": 10 }
 */

/**
 * 单元测试建议（示例场景）：
 * 1) 标量类型转换：
 *    - NUMBER: "42" -> 42；"3.14" -> 3.14；非法字符串 -> 警告且保留原值。
 *    - BOOLEAN: "true"/"false"/"1"/"0"/"yes"/"no" -> 转换；未知字符串 -> 警告且保留原值。
 * 2) 对象深度合并：
 *    - base 中有 {a:{x:1}}，user 中有 {a:{y:2}} -> 合并为 {a:{x:1,y:2}}。
 *    - 循环引用：Map 自引用时检测并停止，记录警告。
 * 3) 数组合并：
 *    - REPLACE: user 覆盖 base；缺失使用 default。
 *    - CONCAT: base + user 保留顺序；两者缺失使用 default；无 default 返回空并警告若 required。
 * 4) 枚举与校验：
 *    - enum=["INFO","WARN"]，user="DEBUG" -> 回退 default 并记录警告；无 default 则保留并警告。
 *    - validate: 值必须为偶数，user=3 -> 回退 default 并警告；无 default 保留并警告。
 * 5) 路径与默认：
 *    - "db.pool.size" 缺失且 default=10 -> appliedDefaults 包含 {"db.pool.size":10}。
 *    - required 字段缺失且无 default -> warnings 有对应告警；config 仍生成。
 * 6) JSON 字符串：
 *    - ARRAY/OBJECT 字段在 coerce=true 时传入 JSON 字符串（需运行环境提供 Jackson），解析成功并记录 coercedFields；无 Jackson 或解析失败 -> 警告。
 * 7) 不可变性：
 *    - 对返回的 Map/List 进行修改尝试（应抛出 UnsupportedOperationException）。
 */

}