6.1 KiB
6.1 KiB
本地文件队列(app.fileWriter)
本文档说明仓库中提供的本地文件队列写入能力(实现文件:app/lib/file_writer.js),用于把业务数据按 JSON Lines 追加到本地文件并由消费者按需读取处理,适合低延迟、本地持久化、批处理/异步消费场景。
实现要点(写入特性)
- 串行写入:同一进程内通过内部队列
enqueue串行化写入,保证单进程内顺序性。 - 强制落盘:每次写入使用文件句柄写入并调用
handle.sync()进行 fsync,尽量保证数据落盘。 - 自动轮转:当当前文件大小 + 待写入字节数 超过
maxFileSize时,会自增序号并切换到新文件(sequence)。 - 目录结构:默认 baseDir 下按业务与日期分区:
- baseDir////
- /
- baseDir////
- 文件命名:文件前缀包含业务段与进程标识(
<business>-<machine>-<worker>-p<pid>-<seq>),尾部带序号与扩展名(fileExtension,默认.log)。 - 进度(.progress)断点续传:每个消费者使用独立的隐藏进度文件(以
.<consumerName>.progress命名),写入采用临时文件+rename 的原子替换策略,消费端可通过进度恢复消费位置。 - Worker/进程隔离:写入文件名包含
machineId、workerId与pid,不同进程不会写入同一文件,避免互相竞争。 - 清理策略:基于
retentionDays定期删除过期的数据文件与进度文件。
目录与文件示例
- 目录:
/path/to/runtime/file-writer/orders/2026/04/09/ - 数据文件示例:
orders-myhost-worker1-p1234-0001.log - 进度文件示例:
.consumer-1.progress(位于同一分区目录下)
配置项说明(config.fileWriter)
baseDir:基础目录,默认path.join(app.baseDir, 'runtime', 'file-writer')。maxFileSize:单文件最大字节数,超过后轮转。支持数字(字节)或带单位字符串(如100M、1G)。默认100 * 1024 * 1024(100MB)。retentionDays:保留天数,超过则删除。设为0或负值可禁用清理。默认7。cleanupIntervalMs:触发清理的最小间隔(毫秒),写入时会基于此决定是否执行清理,设置为0或负值可禁用定期清理。默认3600000(1 小时)。sequenceWidth:文件序号宽度(零填充),默认4(例如0001)。fileExtension:数据文件扩展名,默认.log。progressExtension:进度文件扩展名,默认.progress。machineId、workerId(可选):可通过配置覆盖,默认使用主机名与process.env.EGG_WORKER_ID。
默认配置位置:config/config.default.js 的 config.fileWriter 节点。
示例(可放入 config/config.local.js 覆盖默认):
const path = require('path');
exports.fileWriter = {
baseDir: path.join(__dirname, '..', 'runtime', 'file-writer'),
maxFileSize: '200M',
retentionDays: 14,
cleanupIntervalMs: 60 * 60 * 1000,
sequenceWidth: 4,
fileExtension: '.log',
progressExtension: '.progress',
// machineId: 'my-host',
// workerId: 'worker-1',
};
写入示例(业务侧)
简单写入(在任何可以访问 app 的位置):
// 在 controller/service 中
await app.fileWriter.write('orders', { id: 123, event: 'created', payload: { /* ... */ } });
// 返回对象包含 filePath、sequence、bytesWritten 等信息
消费/读取示例(推荐使用 app.fileWriter 提供的 API)
推荐使用 getProgressFilePath + consumeFiles 提供的断点续传能力:
// 示例:定期或守护进程式消费 orders
async function consumeOrders(app) {
const writer = app.fileWriter;
const progressFile = writer.getProgressFilePath('orders', new Date(), 'order-consumer-1');
const result = await writer.consumeFiles({
businessName: 'orders',
progressFilePath: progressFile,
onRecord: async (record, meta) => {
// record: 解析后的对象
// meta: { filePath, offset, index }
// 在这里实现消息处理逻辑(去重、入库、调用外部服务等)
},
parseJson: true,
});
return result; // 包含 processedCount 与最新 progress
}
如需逐文件手动控制消费,也可使用 readRecords:
const res = await app.fileWriter.readRecords(filePath, { startOffset: 0 });
for (const rec of res.records) {
// 处理 rec
}
// 手动保存进度
await app.fileWriter.saveProgress(progressFilePath, {
filePath,
offset: res.nextOffset,
processedCount: (previousCount || 0) + res.records.length,
});
进度文件(.progress)格式
- 保存为 JSON,包含至少字段:
filePath、offset、processedCount、updatedAt。 - 写入采用临时文件写入 +
fsync+rename的方式尽量保证原子性。
注意事项 / 运行时建议
- 不要通过静态文件服务或外部 URL 直接暴露
baseDir(例如runtime/),避免被外部下载或篡改。 - 多 Worker / 多机部署:
- 默认每个进程生成独立的数据文件(文件名包含
machineId、workerId、pid),不会有多个进程同时写入同一文件。若你的设计需要跨进程全局严格顺序,请在上游统一入口合并写入或使用集中式队列(如 Kafka/Redis)。 - 消费者可以按进程拆分(针对单进程的文件)或由独立中心消费者按文件目录遍历处理。
- 可通过配置显式设置
machineId/workerId来标识不同实例。
- 默认每个进程生成独立的数据文件(文件名包含
- 关闭或调整清理策略:若需长期保留数据,请将
retentionDays设为合适值或禁用清理(0或负值)。 - 性能角度:每次写入触发 fsync 会有性能开销,适合需要高可靠性的场景;若对持久性要求不高,可考虑将写入逻辑改为批量 fsync(此处为实现约束,不建议直接修改核心行为)。
如果希望在项目首页或工具箱中添加跳转链接,建议把一行链接加入到 README.md 或 AI_TOOLBOX.md 的相关位置,指向本文件 docs/file-writer.md。
参考实现位置
- 代码实现:app/lib/file_writer.js
- 默认配置:config/config.default.js ->
config.fileWriter