// app/lib/api_log_sink.js 'use strict'; /** * 接口日志落盘器:接口流水经 Egg 日志写出(`wms_system_log` 表已下线删除)。 * * 设计要点: * 1. 只使用 Egg 自带 logger(`app.getLogger('apiLog')`),不自行操作 fs —— * egg-logger 的 FileTransport 以 O_APPEND 追加写、多 worker 共写同一文件、 * 自动创建目录并按天轮转,避免自建写流带来的「轮转后句柄失效 / ENOSPC 崩进程 / * 每请求建流导致 fd 泄漏 / 退出前未 flush」等问题。 * 2. 一行一条记录,形如 `HH:mm:ss {JSON}`: * 前缀是**本地时区的时分秒**,只给人眼定位用(tail/grep 时有个时间锚点), * 机器解析请用行内的 `created_at`(ISO 8601 UTC,无时区歧义,与前缀为同一时刻); * 前缀之后是沿用旧 `wms_system_log` 表结构的平铺 JSON(不嵌套,首字符是 `{`), * 可直接用 grep 搜索;用 jq 时先剥前缀:`jq -R 'sub("^[0-9:]+ "; "") | fromjson'`。 * 3. 写入失败绝不影响接口返回:异常由调用方兜底,只记 app logger。 */ /** body / result 截断长度:沿用旧 wms_system_log 入库时的长文本上限(65535) */ const TEXT_LIMIT = 65535; /** customLogger.apiLog 缺失的告警只打一次,避免每请求刷屏 */ let warnedApiLogMissing = false; /** * 归一化为字符串,必要时截断。 * @param {*} value 原始值。 * @param {number} [limit] 截断长度(正数才生效),默认不截断。 * @return {string} 字符串结果。 */ function toText(value, limit) { if (value === undefined || value === null) { return ''; } // 对象/数组一律 JSON 序列化:调用方若漏了 JSON.stringify(例如 controller 直接把 // 响应对象塞进 logData.result),String() 会得到 "[object Object]" 而丢掉内容。 let text; if (typeof value === 'string') { text = value; } else if (typeof value === 'object') { try { text = JSON.stringify(value); } catch (e) { text = String(value); } } else { text = String(value); } if (Number(limit) > 0 && text.length > Number(limit)) { return text.substring(0, Number(limit)); } return text; } /** * 构造一行平铺记录。 * * 字段与顺序沿用旧 `wms_system_log` 入库时的入参: * method / v / url / headers / auth / created_at / body / result / use_time / store_id / device。 * `created_at` 统一写 ISO 8601(UTC,带 Z):与原入库是同一时刻,但没有时区歧义。 * * @param {object} logData 原始日志数据。 * @param {object} [options] 选项。 * @param {number} [options.startTime] 请求开始时间戳(ms),用于计算 use_time。 * @param {number} [options.useTime] 直接指定耗时(ms),优先于 startTime。 * @param {string} [options.device] 设备标识。 * @param {Date} [options.createdAt] 记录时间,默认当前时间。 * @return {object} 平铺记录对象。 */ function buildRecord(logData, options = {}) { const source = logData && typeof logData === 'object' ? logData : {}; const createdAt = options.createdAt instanceof Date ? options.createdAt : new Date(); let useTime = 0; if (options.useTime !== undefined) { useTime = Number(options.useTime); } else if (Number(options.startTime) > 0) { useTime = Date.now() - Number(options.startTime); } if (!Number.isFinite(useTime) || useTime < 0) { useTime = 0; } return { method: toText(source.method), v: toText(source.v), url: toText(source.url), headers: toText(source.headers), auth: toText(source.auth), created_at: createdAt.toISOString(), body: toText(source.body, TEXT_LIMIT), result: toText(source.result, TEXT_LIMIT), use_time: useTime, store_id: source.store_id || null, device: toText(options.device), }; } /** * customLogger.apiLog 缺失时的显式告警(每个 worker 只打一次)。 * * egg 的 `app.getLogger(name)` 对未声明的 name 返回 null 而不抛错, * 若不处理就会「日志静默消失、且无任何报错」。 * 生产 config 不参与 deploy,「代码已上线、配套配置没上」极易发生,故必须显式报出来。 * * @param {Egg.Application} app Egg 应用实例。 * @return {void} */ function warnApiLogMissing(app) { if (warnedApiLogMissing) { return; } warnedApiLogMissing = true; const logger = app && typeof app.getLogger === 'function' ? app.getLogger('logger') : null; if (logger && typeof logger.error === 'function') { logger.error( '[api_log_sink] config.customLogger.apiLog 未配置,接口日志不会落盘!' + '请在 config.default.js 补上 customLogger.apiLog' + '(生产 config 不参与 deploy,需手工同步到线上)。' ); } } /** * 两位补零。 * @param {number} value 待补零的数字。 * @return {string} 补零后的字符串。 */ function pad2(value) { return String(value).padStart(2, '0'); } /** * 生成日志行的时间前缀(本地时区 `HH:mm:ss`)。 * * 整行内容本身是完整 JSON(首字符是 `{`),直接 tail/grep 时没有时间锚点, * 故在行首加一个本地时间的时分秒前缀。前缀只给人看: * 它与行内 `created_at` 取同一时刻,仅表达方式不同(本地 `HH:mm:ss` vs UTC ISO 8601)。 * 日期无需前缀 —— 日志按天轮转为 `wms-api.log.YYYY-MM-DD`,日期由文件名提供。 * * @param {Date|string} [value] 记录时间;缺省或非法时回退当前时间。 * @return {string} `HH:mm:ss` 形式的前缀。 */ function formatTimePrefix(value) { const parsed = value instanceof Date ? value : new Date(value || Date.now()); const date = Number.isNaN(parsed.getTime()) ? new Date() : parsed; return `${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`; } /** * 写出接口日志。 * * 只落 Egg 日志文件(`config.customLogger.apiLog`);wms_system_log 表已下线, * 不再存在任何入库分支。 * * @param {Egg.Application} app Egg 应用实例。 * @param {object} payload 负载。 * @param {object} payload.logData 原始日志数据。 * @param {number} [payload.startTime] 请求开始时间戳(ms)。 * @param {number} [payload.useTime] 直接指定耗时(ms)。 * @param {string} [payload.device] 设备标识。 * @param {Date} [payload.createdAt] 记录时间。 * @return {Promise} 实际写出的平铺记录。 */ async function write(app, payload = {}) { const record = buildRecord(payload.logData, { startTime: payload.startTime, useTime: payload.useTime, device: payload.device, createdAt: payload.createdAt, }); const logger = app && typeof app.getLogger === 'function' ? app.getLogger('apiLog') : null; if (logger) { // 一行一条:`HH:mm:ss {完整 JSON}`,前缀与行内 created_at 是同一时刻 logger.info(`${formatTimePrefix(record.created_at)} ${JSON.stringify(record)}`); } else { warnApiLogMissing(app); } return record; } module.exports = { TEXT_LIMIT, buildRecord, formatTimePrefix, write, };