VassasCo.Utility.LogHelper 2.0.0

VassasCo.Utility.LogHelper

轻量级异步文件日志库（桌面端/服务端通用），零外部依赖。
「分类」决定文件、「级别」写入时配置，支持按天分目录、跨天自动切换、批量刷盘、定时清理与可靠关闭。

目录

• 功能总览
• 目标框架与依赖
• 快速开始
• 核心设计：分类与级别
• 写入 API
• 文件组织与日志格式
• 配置参考
• 可靠性特性
• 安全策略
• API 速查
• 测试

功能总览

目标框架与依赖

快速开始

using VassasCo.Utility;

// 启动全局日志器
LogManager.Current = LogHelper.Build()
    .SetLogPath("D:/Logs")
    .SetMinLevel(LogLevel.Info)
    .SetRetentionDays(30)
    .Start();

// 扩展方法：方法名即分类，级别作为参数
"用户登录成功".LogSecurity(LogLevel.Info);
"数据库连接失败".LogDatabase(LogLevel.Error);
"接口响应超时".LogApi(LogLevel.Error, "订单服务");   // 模块为可选字段

// 程序退出时可靠关闭（排空队列不丢日志）
LogManager.Shutdown();

核心设计：分类与级别

「分类」与「级别」是两个正交维度：

LogLevel 枚举：Trace < Debug < Info < Warning < Error < Fatal。

LogCategories 常量：

写入 API

扩展方法（按分类命名，方法名决定文件）

message.Log()                    // General
message.LogSecurity(level)       // Security
message.LogPerformance(level)    // Performance
message.LogBusiness(level)       // Business
message.LogAudit(level)          // Audit
message.LogOperation(level)      // Operation
message.LogTimerTask(level)      // TimerTask
message.LogSystem(level)         // System
message.LogDatabase(level)       // Database
message.LogApi(level)            // Api
message.LogNetwork(level)        // Network

统一签名：

Log{Category}(this string message, LogLevel level = LogLevel.Info, string? module = null)

直接写入（任意自定义分类）

logger.AddLog("Payment", LogLevel.Error, "支付失败", "微信支付");
//             ↑分类(决定文件)  ↑级别        ↑消息       ↑可选模块

异常写入

exception.LogError(LogCategories.Api);   // Error 级别，递归展开 InnerException

文件组织与日志格式

LogPath/
└── 2025-06/
    └── 06-17/
        ├── General.log
        ├── Api.log
        ├── Database.log
        ├── Security.log
        └── ...

按「分类」分文件、按「天」分目录（yyyy-MM/MM-dd）。

日志格式：

[2025-06-17 12:30:45.123] [Error] [订单服务] 接口响应超时

• 分类体现在文件名里，不再写入每行内容。
• [级别] 始终写入；[模块] 仅在传入 module 时出现。

配置参考

LogHelperBuilder（链式配置）

可靠性特性

• 异步写入：有界队列 + 后台单线程消费，AddLog 立即返回不阻塞调用方。
• 跨天自动切换：StreamWriter 按「分类 + 日期」缓存，零点后自动关闭旧文件、新建当天文件，杜绝日志写进前一天的 bug。
• 批量刷盘：不再每条 Flush，改为定时批量落盘，显著降低 IO 开销。
• 定时清理：按「月/日」目录安全解析并删除过期日志。
• 可靠关闭：Dispose / Shutdown 先停止接收、再排空队列、最后关闭所有 writer，不丢日志。

安全策略

API 速查

LogHelper（实例）

LogManager（静态门面）

LogHelperExtensions（扩展方法）

测试

cd VassasCo.Utility
dotnet test

12 个单元测试覆盖：基本写入、按分类分文件、最低级别过滤、空分类回退、模块字段、分类文件名清洗、写入失败回调、可靠关闭排空、并发线程安全、分类扩展方法、异常链记录、全局管理器生命周期。

许可证

MIT