@yixinshuke/node-log 0.0.0-stage → 0.0.1

package/src/logger.ts

@@ -0,0 +1,427 @@
+/**
+ * 全局日志器（单例）—— 实现 AGENTS.md §0 的两条最高原则：
+ *
+ * 1. 写日志 = **先写环形内存缓冲，立即返回**；后台定时/攒批，在互斥下**追加写**到目标目录的文件；
+ * 2. **写日志的任何异常都不影响业务**：不抛错、不阻塞，最坏只是这段日志没记下来。
+ */
+import { hostname } from 'os';
+import {
+  LoggerConfig,
+  LogLevel,
+  mergeConfig,
+  validateConfig,
+  resolveMaxBufferSize,
+} from './config.js';
+import { RingBuffer, LogEntry } from './buffer.js';
+import { FileWriter } from './writer.js';
+import { buildRelPath } from './path.js';
+import { beijingTimestamp } from './time.js';
+import { createLocker, WriteLocker } from './lock.js';
+
+export interface LogContext {
+  merchantId: string | number;
+  storeId: string | number;
+  system: string;
+  /** 业务主键（订单号），决定写入哪个文件 */
+  bizKey: string;
+  /** 单据日期 YYYYMMDD；缺省时从 bizKey 前 8 位解析 */
+  bizDate?: string;
+  /**
+   * 类别路径段（可选）：传入后路径改为 `{年}/{年月}/{年月日}/{category}/{bizKey}.log`，
+   * 替代默认的「商户/门店/system」三段（见 path.ts）。不传则保持旧结构，向后兼容。
+   */
+  category?: string;
+  userId?: string;
+  requestId?: string;
+  extra?: Record<string, any>;
+}
+
+export interface WriteOptions {
+  /** true = 立即触发一次刷盘（仍走后台，不阻塞业务） */
+  immediate?: boolean;
+  metadata?: Record<string, any>;
+}
+
+export interface LoggerStats {
+  buffered: number;
+  dropped: number;
+  writeFailures: number;
+  lockBusy: number;
+}
+
+const LEVELS: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+
+/** Node 定时器上限（2^31-1 ms），超过会被截断成 1ms */
+const MAX_INTERVAL_MS = 2_147_483_647;
+
+/** 单次 flush 的最大轮数（防死循环） */
+const MAX_FLUSH_ROUNDS = 1000;
+
+/** 写失败退避上限（5 分钟） */
+const MAX_BACKOFF_MS = 300_000;
+
+interface Chunk {
+  text: string;
+  count: number;
+}
+
+export class GlobalLogger {
+  private static instance: GlobalLogger | null = null;
+
+  private config: Required<LoggerConfig>;
+  private buffer: RingBuffer;
+  private writer: FileWriter;
+  private timer: NodeJS.Timeout | null = null;
+  private locker: WriteLocker | null = null;
+  private closed = false;
+  private flushing = false;
+  private rerun = false;
+  private readonly warned = new Set<string>();
+  private readonly host: string;
+  private readonly pid = process.pid;
+  private counters = { writeFailures: 0, lockBusy: 0 };
+  /** 写失败退避：rel → 下次可重试的时间戳（故障期间不反复死磕同一文件） */
+  private readonly retryAfter = new Map<string, number>();
+  /** rel → 连续失败次数（用于指数退避） */
+  private readonly failureStreak = new Map<string, number>();
+
+  private constructor(config: Required<LoggerConfig>) {
+    this.config = config;
+    this.host =
+      config.host || process.env.NODE_LOG_HOST || process.env.POD_NAME || hostname();
+    this.buffer = new RingBuffer(resolveMaxBufferSize(config));
+    this.writer = new FileWriter({
+      baseDir: config.baseDir,
+      writeTimeoutMs: config.writeTimeoutMs,
+      maxFileSizeBytes: config.maxFileSizeBytes,
+      onWarn: msg => this.warnOnce(`write:${msg}`, `[node-log] ${msg}`),
+    });
+    this.applyLock(); // 锁由外部注入（node-lock 实例），没注入就是无锁直写
+  }
+
+  /** 装配写入互斥：注入了锁实例才互斥，否则无锁直写（不告警，属预期用法） */
+  private applyLock(): void {
+    this.locker = createLocker(this.config.lock, this.config.lockTtlMs, msg =>
+      this.warnOnce(`lock:${msg}`, msg)
+    );
+    this.writer.setLocker(this.locker, this.config.lockTtlMs);
+  }
+
+  // ---------------------------------------------------------------- 生命周期
+
+  static init(config: LoggerConfig): void {
+    if (GlobalLogger.instance) {
+      throw new Error('GlobalLogger 已初始化，请勿重复调用 init()');
+    }
+    const merged = mergeConfig(config);
+    validateConfig(merged); // 唯一允许抛错的地方：启动期暴露配置问题
+    const instance = new GlobalLogger(merged);
+    GlobalLogger.instance = instance;
+    instance.startFlushTimer();
+  }
+
+  static getInstance(): GlobalLogger {
+    if (!GlobalLogger.instance) {
+      throw new Error('请先调用 GlobalLogger.init() 初始化');
+    }
+    return GlobalLogger.instance;
+  }
+
+  static updateConfig(overrides: Partial<LoggerConfig>): void {
+    const instance = GlobalLogger.getInstance();
+    const merged = mergeConfig({ ...instance.config, ...overrides });
+    validateConfig(merged); // 配置错误在启动/变更期暴露，运行期写路径不抛错
+    instance.config = merged;
+    instance.writer.setBaseDir(merged.baseDir);
+    instance.writer.setWriteTimeoutMs(merged.writeTimeoutMs);
+    instance.writer.setMaxFileSizeBytes(merged.maxFileSizeBytes);
+    instance.applyLock();
+    instance.startFlushTimer();
+  }
+
+  static async shutdown(): Promise<void> {
+    const instance = GlobalLogger.instance;
+    if (!instance) return;
+    GlobalLogger.instance = null;
+    await instance.close();
+  }
+
+  private async close(): Promise<void> {
+    this.closed = true;
+    this.stopTimer();
+    try {
+      await this.flushAll();
+    } catch {
+      /* 关闭阶段不再抛错 */
+    }
+    try {
+      await this.writer.drain();
+    } catch {
+      /* ignore */
+    }
+    // 锁实例由外部注入，生命周期归宿主项目，这里不做关闭
+  }
+
+  // ---------------------------------------------------------------- 定时刷盘
+
+  private startFlushTimer(): void {
+    this.stopTimer();
+    const base = Math.min(Math.max(50, this.config.flushIntervalMs), MAX_INTERVAL_MS);
+    const jitter = Math.max(0, this.config.flushJitterMs);
+    // 递归 setTimeout 而非 setInterval：每轮都带随机抖动，避免多进程同相位抢同一把锁
+    const schedule = (): void => {
+      const delay = Math.min(base + Math.floor(Math.random() * (jitter + 1)), MAX_INTERVAL_MS);
+      this.timer = setTimeout(() => {
+        void this.tick().finally(schedule);
+      }, delay);
+      this.timer.unref?.();
+    };
+    schedule();
+  }
+
+  private stopTimer(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /** 一轮刷盘；并发调用合并（期间来的 immediate 只标记 rerun，结束后补一轮） */
+  private async tick(): Promise<void> {
+    if (this.closed) return;
+    if (this.flushing) {
+      this.rerun = true;
+      return;
+    }
+    this.flushing = true;
+    try {
+      do {
+        this.rerun = false;
+        await this.flushOnce();
+      } while (this.rerun && !this.closed);
+    } catch (err: any) {
+      this.warnOnce(`flush:${err?.message ?? ''}`, `[node-log] 刷盘失败：${err?.message ?? err}`);
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  /** 手动刷盘（进程退出前、请求结束时调用） */
+  async flush(): Promise<void> {
+    if (this.closed) return;
+    await this.flushAll();
+  }
+
+  private async flushAll(): Promise<void> {
+    // 手动/关闭前刷盘：**忽略退避**（调用方显式要求立刻写，不能被退避窗口挡住）
+    for (let i = 0; i < MAX_FLUSH_ROUNDS; i++) {
+      const written = await this.flushOnce(true);
+      if (written === 0) break;
+    }
+    await this.writer.drain();
+  }
+
+  private async flushOnce(ignoreBackoff = false): Promise<number> {
+    const groups = this.buffer.drainByKey(this.config.flushBatchSize);
+    if (groups.size === 0) return 0;
+    const now = Date.now();
+    let written = 0;
+    for (const [rel, entries] of groups) {
+      const until = this.retryAfter.get(rel) ?? 0;
+      if (!ignoreBackoff && now < until) {
+        this.buffer.pushBack(rel, entries); // 退避窗口内不重试；条目仍在缓冲，恢复后补写
+        continue;
+      }
+      written += await this.writeGroup(rel, entries);
+    }
+    return written;
+  }
+
+  /** 写入一个文件的整批；失败/繁忙时保留未写出的条目（下轮再写，顺序不变） */
+  private async writeGroup(rel: string, entries: LogEntry[]): Promise<number> {
+    const chunks = this.buildChunks(entries);
+    let consumed = 0;
+    for (const chunk of chunks) {
+      const status = await this.writer.write(rel, chunk.text);
+      if (status === 'ok') {
+        consumed += chunk.count;
+        continue;
+      }
+      if (status === 'busy') {
+        this.counters.lockBusy += 1; // 锁繁忙不算故障：不设退避，下轮正常再抢
+      } else {
+        this.counters.writeFailures += 1;
+        this.backoff(rel);
+      }
+      // 未写出的部分放回队首，下轮优先重试（不重复已写出的内容）
+      this.buffer.pushBack(rel, entries.slice(consumed));
+      return consumed;
+    }
+    // 整批成功 → 清除该文件的退避与失败计数
+    this.retryAfter.delete(rel);
+    this.failureStreak.delete(rel);
+    return consumed;
+  }
+
+  /** 写失败后指数退避（上限 5 分钟）：磁盘/挂载故障期间不每轮死磕同一个文件 */
+  private backoff(rel: string): void {
+    const streak = (this.failureStreak.get(rel) ?? 0) + 1;
+    this.failureStreak.set(rel, streak);
+    const base = Math.max(0, this.config.retryBackoffMs);
+    const delay = Math.min(base * 2 ** (streak - 1), MAX_BACKOFF_MS);
+    this.retryAfter.set(rel, Date.now() + delay);
+  }
+
+  /** 按 maxFlushBytes 切块（不切断行） */
+  private buildChunks(entries: LogEntry[]): Chunk[] {
+    const limit = Math.max(1, Math.floor(this.config.maxFlushBytes));
+    const chunks: Chunk[] = [];
+    let lines: string[] = [];
+    let size = 0;
+    for (const entry of entries) {
+      const line = this.formatEntry(entry);
+      const lineSize = Buffer.byteLength(line, 'utf8') + 1;
+      if (lines.length > 0 && size + lineSize > limit) {
+        chunks.push({ text: lines.join('\n') + '\n', count: lines.length });
+        lines = [];
+        size = 0;
+      }
+      lines.push(line);
+      size += lineSize;
+    }
+    if (lines.length > 0) chunks.push({ text: lines.join('\n') + '\n', count: lines.length });
+    return chunks;
+  }
+
+  // ---------------------------------------------------------------- 日志 API
+
+  debug(context: LogContext, message: string, options?: WriteOptions): void {
+    this.write('debug', context, message, options);
+  }
+
+  info(context: LogContext, message: string, options?: WriteOptions): void {
+    this.write('info', context, message, options);
+  }
+
+  warn(context: LogContext, message: string, options?: WriteOptions): void {
+    this.write('warn', context, message, options);
+  }
+
+  error(context: LogContext, message: string, options?: WriteOptions): void {
+    this.write('error', context, message, options);
+  }
+
+  /** 运行状态（供监控：丢弃条数、写失败次数、锁繁忙次数） */
+  stats(): LoggerStats {
+    return {
+      buffered: this.buffer.size,
+      dropped: this.buffer.droppedCount,
+      writeFailures: this.counters.writeFailures,
+      lockBusy: this.counters.lockBusy,
+    };
+  }
+
+  private write(level: LogLevel, context: LogContext, message: string, options?: WriteOptions): void {
+    if (this.closed) return;
+    if (!this.shouldLog(level)) return;
+
+    const entry: LogEntry = {
+      level,
+      context,
+      message,
+      timestamp: new Date(),
+      metadata: options?.metadata,
+    };
+
+    try {
+      // 阶段一：只写内存，同步入队后立即返回（不做任何 IO）
+      this.buffer.push(this.buildRelPath(entry), entry);
+    } catch (err: any) {
+      this.warnOnce(`buffer:${err?.message ?? ''}`, `[node-log] 入缓冲失败（已丢弃该条）：${err?.message ?? err}`);
+      return;
+    }
+
+    // 关键日志：立即触发一次刷盘（后台执行，不阻塞业务）
+    if (options?.immediate || LEVELS.indexOf(level) >= LEVELS.indexOf(this.config.immediateLevel)) {
+      void this.tick();
+    }
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LEVELS.indexOf(level) >= LEVELS.indexOf(this.config.minLevel);
+  }
+
+  // ---------------------------------------------------------------- 路径与格式
+
+  private buildRelPath(entry: LogEntry): string {
+    return buildRelPath(
+      {
+        merchantId: entry.context.merchantId,
+        storeId: entry.context.storeId,
+        system: entry.context.system,
+        bizKey: entry.context.bizKey,
+        bizDate: entry.context.bizDate,
+        category: entry.context.category,
+      },
+      { fileScope: this.config.fileScope, host: this.host },
+      entry.timestamp
+    );
+  }
+
+  private formatEntry(entry: LogEntry): string {
+    const { timestamp, level, context, message, metadata } = entry;
+    const record: Record<string, any> = {
+      timestamp: beijingTimestamp(timestamp), // 固定 +08:00，不依赖运行环境 TZ
+      host: this.host,
+      pid: this.pid,
+      level,
+      message,
+    };
+    // 类别模式：仅输出 category，不输出 商户/门店/system（避免噪声）
+    if (context.category) {
+      record.category = context.category;
+    } else {
+      record.merchantId = context.merchantId;
+      record.storeId = context.storeId;
+      record.system = context.system;
+    }
+    record.bizKey = context.bizKey;
+    if (context.userId) record.userId = context.userId;
+    if (context.requestId) record.requestId = context.requestId;
+    if (context.extra) record.extra = context.extra;
+    if (metadata) record.metadata = metadata;
+    // 容错序列化：单条脏数据只影响这一条，绝不影响整批
+    return stringifySafe(record);
+  }
+
+  private warnOnce(key: string, message: string): void {
+    if (this.warned.has(key)) return;
+    this.warned.add(key);
+    try {
+      console.warn(message);
+    } catch {
+      /* console 不可用时静默 */
+    }
+  }
+}
+
+/**
+ * 容错 JSON 序列化：循环引用替换为 `[Circular]`、BigInt 转字符串、其余异常降级为占位文本。
+ */
+function stringifySafe(value: unknown): string {
+  const seen = new WeakSet<object>();
+  try {
+    return (
+      JSON.stringify(value, (_key, val) => {
+        if (typeof val === 'bigint') return val.toString();
+        if (typeof val === 'object' && val !== null) {
+          if (seen.has(val)) return '[Circular]';
+          seen.add(val);
+        }
+        return val;
+      }) ?? '{}'
+    );
+  } catch (err: any) {
+    return JSON.stringify({ message: '[node-log] 日志序列化失败', reason: String(err?.message ?? err) });
+  }
+}

package/src/path.ts

@@ -0,0 +1,124 @@
+/**
+ * 目录与文件路径拼装 + 安全过滤。
+ *
+ * 规则（AGENTS.md §3）：
+ *   {baseDir}/{年}/{年月}/{年月日}/商户{merchantId}/门店{storeId}/{system}/{bizKey}.log
+ * 日期目录 = **单据创建日期**（本项目无跨天订单），保证同一单据永远写到同一个文件。
+ */
+import { beijingDateKey, beijingDateParts } from './time.js';
+
+export interface PathInput {
+  merchantId: string | number;
+  storeId: string | number;
+  system: string;
+  bizKey: string;
+  /** 单据日期 YYYYMMDD；缺省时从 bizKey 前 8 位解析，再缺省用当前北京时间 */
+  bizDate?: string;
+  /**
+   * 类别路径段（可选）：用于按业务类别分子目录（如 `db/sql`、`db/msql`、`db/shardorm`）。
+   * 传入后「商户/门店/system」三段被整段替换为该类别路径，便于按 docs/日志.md 的类别约定归档。
+   * 为空（不传）时走默认「商户{id}/门店{id}/{system}」结构，向后兼容既有调用。
+   */
+  category?: string;
+}
+
+export type FileScope = 'shared' | 'host';
+
+export interface BuildPathOptions {
+  /** shared = 多机多进程写同一个文件（默认）；host = 每台机器各写各的（彻底免锁） */
+  fileScope?: FileScope;
+  /** fileScope='host' 时追加的主机标识 */
+  host?: string;
+}
+
+/** 商户/门店 ID：只保留数字，杜绝路径遍历 */
+export function sanitizeId(value: string | number): string {
+  const digits = String(value ?? '').replace(/[^0-9]/g, '');
+  return digits || '0';
+}
+
+/**
+ * 路径片段通用清洗：保留「字母/数字/._-」（含中文等 Unicode 字母数字），
+ * 其余（含 `/`、`\`、空格）统一替换为 `-`；再消除 `..` 与前导点，杜绝路径穿越。
+ */
+function sanitizeSegment(value: string, maxLen: number): string {
+  return String(value ?? '')
+    .replace(/[^\p{L}\p{N}._-]/gu, '-')
+    .replace(/\.{2,}/g, '-')
+    .replace(/^\.+/, '')
+    .slice(0, maxLen);
+}
+
+/** 业务系统名（如「支付系统」）：清洗后为空则 default */
+export function sanitizeSystem(system: string): string {
+  return sanitizeSegment(system, 64) || 'default';
+}
+
+/** 业务主键：清洗后为空则 unknown */
+export function sanitizeBizKey(bizKey: string): string {
+  return sanitizeSegment(bizKey, 200) || 'unknown';
+}
+
+/**
+ * 类别路径段（可选）：用于按业务类别分子目录（如 `db/sql`、`db/msql`、`db/shardorm`）。
+ * 允许字母/数字/._-/ 与 `/`（支持多级子目录），但阻断路径穿越：
+ * 去掉 `..`、裁掉前导 `/`（避免绝对路径）、折叠连续 `/`、裁掉首尾 `-`、超长截断。
+ * 为空时返回 ''，调用方据此走默认的「商户/门店/system」结构，向后兼容。
+ */
+export function sanitizeCategory(value: string | undefined): string {
+  if (!value) return '';
+  return String(value)
+    .replace(/[^\p{L}\p{N}._\/-]/gu, '-')
+    .replace(/\.{2,}/g, '-')
+    .replace(/^\/+/, '')
+    .replace(/\/+/g, '/')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '')
+    .slice(0, 120);
+}
+
+/**
+ * 解析单据日期 YYYYMMDD：显式 bizDate > bizKey 前 8 位数字 > 当前北京时间。
+ * 与展示侧一致：全部节点统一北京时间，保证同一单据永远命中同一目录。
+ */
+export function resolveBizDate(input: PathInput, now: Date = new Date()): string {
+  const explicit = String(input.bizDate ?? '').trim();
+  if (/^\d{8}$/.test(explicit)) return explicit;
+
+  const fromKey = String(input.bizKey ?? '').match(/^(\d{8})/);
+  if (fromKey) return fromKey[1];
+
+  return beijingDateKey(now);
+}
+
+/**
+ * 拼装相对路径（不含 baseDir），如：
+ * 2026/202609/20260929/商户1/门店1/支付系统/202609290001.log
+ */
+export function buildRelPath(
+  input: PathInput,
+  options: BuildPathOptions = {},
+  now: Date = new Date()
+): string {
+  const date = resolveBizDate(input, now);
+  const year = date.slice(0, 4);
+  const yearMonth = date.slice(0, 6);
+
+  const merchantId = sanitizeId(input.merchantId);
+  const storeId = sanitizeId(input.storeId);
+  const system = sanitizeSystem(input.system);
+  const bizKey = sanitizeBizKey(input.bizKey);
+  const suffix = options.fileScope === 'host' && options.host ? `.${options.host}` : '';
+
+  // 类别模式：整段替换「商户/门店/system」为类别路径（支持多级子目录，如 db/sql）
+  const category = sanitizeCategory(input.category);
+  const middle = category ? [category] : [`商户${merchantId}`, `门店${storeId}`, system];
+
+  return [
+    year,
+    yearMonth,
+    date,
+    ...middle,
+    `${bizKey}${suffix}.log`,
+  ].join('/');
+}

package/src/time.ts

@@ -0,0 +1,46 @@
+/**
+ * 北京时间工具。
+ *
+ * 组件内所有时间（日志字段、目录日期）**固定 +08:00**，不依赖运行环境的 `TZ`：
+ * Docker/K8s 容器默认是 UTC，直接用 `toISOString()` 会整体差 8 小时，
+ * 表现为「日志时间不对」和「每天 00:00–08:00 的日志落到前一天的目录」。
+ */
+
+const BEIJING_OFFSET_MS = 8 * 3600 * 1000;
+
+/** 北京时间的 Date 视图（把时间轴平移 +8h 后用 UTC 取值） */
+function beijingDate(d: Date): Date {
+  return new Date(d.getTime() + BEIJING_OFFSET_MS);
+}
+
+/** ISO-8601 毫秒，固定 +08:00 偏移，如 2026-09-29T10:00:00.123+08:00 */
+export function beijingTimestamp(d: Date = new Date()): string {
+  return beijingDate(d).toISOString().replace(/Z$/, '+08:00');
+}
+
+export interface BeijingDateParts {
+  /** 2026 */
+  year: string;
+  /** 09 */
+  month: string;
+  /** 29 */
+  day: string;
+  /** 202609 */
+  yearMonth: string;
+  /** 20260929 */
+  date: string;
+}
+
+/** 北京时间的日期各段（目录分层用） */
+export function beijingDateParts(d: Date = new Date()): BeijingDateParts {
+  const b = beijingDate(d);
+  const year = String(b.getUTCFullYear());
+  const month = String(b.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(b.getUTCDate()).padStart(2, '0');
+  return { year, month, day, yearMonth: `${year}${month}`, date: `${year}${month}${day}` };
+}
+
+/** 北京时间的 YYYYMMDD */
+export function beijingDateKey(d: Date = new Date()): string {
+  return beijingDateParts(d).date;
+}