1. 为什么我要自己动手写一个日志框架
.NET 项目里几乎离不开日志。排查线上问题、跟踪用户请求链路、分析系统瓶颈，第一步都是翻日志。但很多开发者对日志的认知停留在“调一下 Log4Net 的配置”“用一下 ILogger 的扩展方法”，一旦出现日志丢失、时序错乱、性能骤降、格式不统一这类问题，就完全不知道从哪里下手。
我之前接诊过一个典型的“日志疑难杂症”：某个服务在高峰期日志直接断层，查了半天发现是异步队列积压、丢消息丢得悄无声息。为了彻底搞懂背后的机制，我决定不依赖任何现成第三方库，从零手写一个最小可用的日志框架。这个过程非常值得推荐给每一位做 .NET 开发的同行，因为日志框架看起来简单，真正动手实现之后，你对依赖注入、多线程同步、内存分配、I/O 优化、异常处理这些基础话题的理解都会上一个台阶。
这篇文章会分成几个层次来讲：先拆解一个日志框架必须具备的模块和设计思路，再从零开始手写核心代码，然后加入性能优化手段，最后分享我在实践过程中踩过的坑和排查技巧。无论你是初学者还是有一定经验的开发，看完整篇都能获得一套可以直接复用的认知框架和代码骨架。
2. 日志框架的整体设计：它到底在解决什么问题
2.1 三个核心角色：生产者、格式化器、输出目标
一套日志框架最基础的分工可以抽象成三块：生产者负责接收日志数据，格式化器负责把数据变成可读的文本或结构化数据，输出目标负责把格式化后的内容写到控制台、文件、数据库或其他地方。
听起来很简单，但实际工程里有大量细节。比如：调用方可能同时来自多线程，格式化器要考虑到时间戳精度和文化差异，输出目标面临磁盘满、权限不足、I/O 阻塞的异常场景。任何一个环节处理不好，日志框架反而会成为故障源。
拿我手写的框架举例，我把它拆成了四个接口层级：
ILogger：对外暴露的日志记录入口，调用方只需要使用它，不需要知道后面的实现细节。ILogFormatter：负责把日志条目转换成字符串。这个接口允许扩展不同的输出风格，常见有纯文本、JSON、按域名的自定义格式。ILogAppender：负责把格式化后的字符串写入目标介质。例如控制台输出器、文件输出器、内存环形缓冲输出器。ILoggerFactory：负责组装上面三者，并提供日志级别过滤、缓存等全局能力。
这样的分层设计参考了成熟框架的做法，但保留了自己的简化逻辑。它的好处非常直接：替换输出目标时不需要动调用方代码，调整格式时也不需要动输出目标。这就是面向接口而不是面向实现的威力。
2.2 日志级别为何值得单独设计
很多初学者觉得日志级别就是“Info、Debug、Error 五种字符串”，随便枚举一下就行。但真正到了生产环境，日志级别决定了系统的写盘量、故障定位效率以及隐私合规边界。
我的框架里把日志级别设计成可比较的整数枚举，从左到右逐渐提高严重程度。过滤逻辑很简单：只有当事件的级别大于等于当前配置的全局阈值时，才允许进入后续管道。这样，当生产环境遇到问题，可以在配置中心动态把阈值从Info降到Debug，快速抓取更多细节，而不需要修改代码。
在设计这个枚举时，我额外加了几个考量：
- 每个级别对应一个短名称，格式化时直接输出名称而不是数字，日志可读性更好。
- 级别带有数值区间，方便不同框架之间做映射。比如用标准日志级别规范来对齐，避免自定义惹来的兼容麻烦。
- 异常对象单独作为一个参数传入，而非拼装在消息文本里。这为后续的结构化日志输出留下扩展点。
实际项目中，很多人不分级别什么都写Info，导致日志文件膨胀得飞快，真正要排查时却找不到关键错误。我自己的习惯是：
Debug：只记录对排查有用、但正常运行时不需要看的详细变量状态。Info：记录系统边界事件，比如服务启动、请求完成、定时任务执行结果。Warn：记录不直接影响本次请求，但可能影响后续健康度的事件，比如重试成功、资源占用偏高。Error：记录异常发生、业务失败的情况。Fatal：记录系统无法继续运行、必须立刻人工介入的情况。
这套划分是经过多次线上故障总结出来的，比单纯“能用”的定义要实用得多。
2.3 为什么格式化要独立出来而不是直接拼接字符串
如果你写过日志，大概率见过这种代码：$"{DateTime.Now} [{level}] {message}"。这样写的问题不在于慢，而在于无法复用一个格式策略。
举个例子，有一天需求变了，要求日志全部输出成 JSON 方便下游采集。如果格式化逻辑散落在各个 Appender 里，你就得把所有输出目标都改一遍。而独立成ILogFormatter之后，只需要新增一个JsonLogFormatter，然后在工厂里换一下注入的对象，所有输出目标自动切换。
除此之外，独立格式化器还有一个性能意义：格式化是否执行，可以由日志级别先过滤掉。也就是说，日志级别不够时，压根就不应该调用格式化逻辑。这样能把昂贵的字符串分配延后到必需的时刻。
我手写的DefaultLogFormatter内部采用StringBuilder池化策略，避免每次记录都重新分配缓冲区。这一点在大流量场景下业绩差异极大，后面章节我会详细展开。
3. 手写日志框架的核心实现：从接口到可运行代码
3.1 定义日志级别和日志事件
在动手写代码之前，先把日志事件的数据结构定义清楚。这一层尽量简洁，但几个字段不能少：时间戳、日志级别、消息文本、可选异常对象、可选调用者信息、可选上下文数据。
我用 C# 定义如下：
public enum LogLevel { Debug = 1, Info = 2, Warn = 3, Error = 4, Fatal = 5 } public sealed class LogEvent { public DateTime Timestamp { get; set; } public LogLevel Level { get; set; } public string? Message { get; set; } public Exception? Exception { get; set; } public string? LoggerName { get; set; } public IReadOnlyDictionary<string, object?>? ScopeData { get; set; } public LogEvent(LogLevel level, string? message) { Timestamp = DateTime.Now; Level = level; Message = message; } }这里有一个经验点：时间戳的获取放到事件构造函数里，而不是格式化的时候。原因是事件创建时刻更接近真实发生时间，如果排队时间较长，写入文件的时间可能已经晚了几百毫秒甚至几秒。
异常为什么要单独存字段？因为当你输出日志时，很多时候不希望把堆栈拼成一长串放进消息框；反而希望把Exception对象交给格式化器，按需决定是要完整堆栈还是仅消息。格式化成 JSON 时，异常也可以序列化成结构化的属性，便于采集分析。
3.2 定义日志器接口和工厂
日志器的核心接口我会尽量精简，方便调用方记忆：
public interface ILogger { void Log(LogLevel level, Exception? exception, string? message, params object?[] args); void Debug(string? message, params object?[] args); void Info(string? message, params object?[] args); void Warn(string? message, params object?[] args); void Error(string? message, params object?[] args); void Error(Exception exception, string? message, params object?[] args); void Fatal(string? message, params object?[] args); void Fatal(Exception exception, string? message, params object?[] args); bool IsEnabled(LogLevel level); }Log方法内部会先做级别判断，如果级别不够，直接返回，不分配格式化资源。每个级别还有自己的快捷方法，这样调用方写logger.Info("用户 {UserId} 已登录", userId)会比写logger.Log(LogLevel.Info, null, "user...", userId)直观得多。
IsEnabled是为了让调用方在拼接复杂消息前先判断一下，减少无谓的字符串操作。比如：
if (logger.IsEnabled(LogLevel.Debug)) { logger.Debug("当前对象完整状态: {State}", JsonSerializer.Serialize(obj)); }这一点在日志参数本身需要消耗 CPU 或内存时尤其重要。普通用户没在意，但我们在手写框架时把这个接口暴露出来，就是为了承载这种性能友好的调用模式。
工厂接口负责创建和缓存日志器实例。因为实际项目中 Logger 数量可以很多，每次都 new 一个是浪费的。工厂内部维护一个ConcurrentDictionary，以 logger 名称作为键，共享同一个配置对象和 Appender 集合。
public interface ILoggerFactory { ILogger CreateLogger(string categoryName); }categoryName通常传入类的全名。比如typeof(UserService).FullName。这样日志里能直接看到是哪个类产出，排查时定位极快。
3.3 核心日志器的实现细节
Logger类的实现是整个框架的心脏。它负责串联：级别判断 → 创建事件 → 格式化 → 分发到所有 Appender。
public sealed class Logger : ILogger { private readonly LoggerConfig _config; public Logger(string name, LoggerConfig config) { Name = name; _config = config; } public string Name { get; } public void Log(LogLevel level, Exception? exception, string? message, params object?[] args) { if (!IsEnabled(level)) { return; } var resolvedMessage = message; if (args is { Length: > 0 }) { resolvedMessage = string.Format(CultureInfo.InvariantCulture, message ?? string.Empty, args); } var logEvent = new LogEvent(level, resolvedMessage) { Exception = exception, LoggerName = Name }; foreach (var appender in _config.Appenders) { try { appender.Append(logEvent, _config.Formatter); } catch (Exception ex) { // 单个 Appender 的异常不能拖垮业务线程 TryEmitInternalError(ex); } } } public bool IsEnabled(LogLevel level) { return level >= _config.MinLevel; } // 省略 Debug/Info/Warn/Error/Fatal 的简洁实现 }这段代码里最关键的工程决策是：单个 Appender 的异常被捕获，且不能影响业务线程。日志框架本身是支撑设施，如果日志写入失败导致主业务抛出异常，那就属于本末倒置。但捕获之后，不能什么都不干，至少要尝试把内部错误输出到控制台或者一个单独的错误日志文件，否则开发者会稀里糊涂地发现日志总是不完整。
有些读者可能会问：string.Format不是有文化差异问题吗？这个问到了点子上。我在格式化的消息里之所以用CultureInfo.InvariantCulture，是为了保证在中文环境、英文环境下日志输出的一致性，避免不同服务器因区域设置不同导致小数点、日期格式错乱。这一点很多人踩过坑，建议所有格式化统一固定文化。
3.4 实现一个线程安全的文件 Appender
文件输出器应该是用得最多、坑也最多的 Appender。核心要求包括：
- 如果日志文件不存在，自动创建目录。
- 写入必须是线程安全的，因为多线程同时写同一个文件会产生交错内容。
- 支持按文件大小或日期滚动，避免单个文件无限膨胀。
- 防止频繁打开关闭文件句柄，最好有缓冲区。
最朴素且稳妥的方案是：每次写入时加lock，然后以追加方式写文件。这个方案在低并发场景完全够用。实现如下：
public sealed class FileAppender : ILogAppender { private readonly object _syncRoot = new object(); private readonly string _baseDirectory; private readonly string _fileNameTemplate; private readonly long _maxFileSizeBytes; private StreamWriter? _writer; private string? _currentFilePath; private long _currentFileSize; public FileAppender(string baseDirectory, string fileNameTemplate, long maxFileSizeBytes = 20 * 1024 * 1024) { Directory.CreateDirectory(baseDirectory); _baseDirectory = baseDirectory; _fileNameTemplate = fileNameTemplate; _maxFileSizeBytes = maxFileSizeBytes; } public void Append(LogEvent logEvent, ILogFormatter formatter) { string line = formatter.Format(logEvent); lock (_syncRoot) { EnsureWriterOpened(); _writer!.WriteLine(line); _writer.Flush(); _currentFileSize += Encoding.UTF8.GetByteCount(line) + 2; } } // 省略 EnsureWriterOpened 的详细滚动逻辑 }lock的做法简单粗暴，但保证了一个进程内写入文件不会互相穿插。有人可能尝试用ReaderWriterLockSlim或直接用File.AppendAllText来解决，实测下来，File.AppendAllText每次打开文件、写入、关闭，在高频日志下开销非常大。我们手写框架时干脆维护一个StreamWriter引用，配合锁和手动Flush，兼顾性能和一致性。
文件滚动逻辑要注意：不能等到写入时才判断大小，因为如果滚动时文件正在被其他程序占用，就会抛异常。我采取的策略是：写下一行之前，如果当前文件大小超过阈值，关闭当前 writer，创建新文件。为了简化，文件名模板里支持{date}占位符。例如：
logs/app-{date}.log这样每天一个文件，排查问题按日期找文件非常直观。
3.5 设计可扩展的格式化器和工厂装配
为了不写死格式逻辑，我把格式化器抽成接口：
public interface ILogFormatter { string Format(LogEvent logEvent); } public sealed class DefaultLogFormatter : ILogFormatter { public string Format(LogEvent logEvent) { var sb = StringBuilderPool.Rent(); try { sb.Append(logEvent.Timestamp.ToString("yyyy-MM-dd HH:mm:ss.fff", CultureInfo.InvariantCulture)); sb.Append(" ["); sb.Append(logEvent.Level.ToString().ToUpperInvariant()); sb.Append("] "); sb.Append(logEvent.LoggerName); sb.Append(": "); sb.Append(logEvent.Message); if (logEvent.Exception != null) { sb.Append(" | ").Append(logEvent.Exception.ToString()); } return sb.ToString(); } finally { StringBuilderPool.Return(sb); } } }这个格式化器里有很多可以优化的点：时间戳使用固定格式且毫秒精度保留，错误日志一定要带异常信息。更关键的是StringBuilderPool，这是我们自己实现的一个简单的对象池，用ConcurrentBag<StringBuilder>来复用一个动态增长的 StringBuilder。日志都是高频、短寿命的小文本，频繁new StringBuilder()会产生大量短命对象，给 GC 增加压力。池化之后，分配次数大幅下降，这在吞吐测试里能看到明显差异。
最后在工厂里装配这些组件。我并没有引入完整的依赖注入容器，而是提供了一个极简的配置入口：
var config = LoggerConfig.Create() .SetMinLevel(LogLevel.Debug) .AddAppender(new FileAppender("logs", "app-{date}.log")) .AddAppender(new ConsoleAppender()) .SetFormatter(new DefaultLogFormatter()); ILoggerFactory factory = new LoggerFactory(config); ILogger logger = factory.CreateLogger("MyApplication"); logger.Info("系统启动成功");调用方只需要通过工厂创建一次 logger，后续在任何类里注入使用即可。
4. 性能优化与诊断技巧：日志不光要能用，还要快
4.1 异步日志：为什么不能让业务线程在日志上排队等待
我最初的手写版本是同步写入的。每一个记录日志的调用，都会在锁内执行StreamWriter.WriteLine然后Flush，实测在磁盘较慢的机器上，一次调用会造成几毫秒甚至十几毫秒的阻塞。对于高频业务，这是不可接受的。
解决办法是引入异步队列：业务线程只负责生成LogEvent，然后把事件扔进一个内存队列并立即返回；后台有一个专门的线程从队列中取事件并批量写入文件。这样业务线程的耗时只包含入队操作和少量内存分配，量级在微秒级别，而不是毫秒级别。
我在代码里采用了一个有界队列，避免无界队列导致内存爆炸。如果队列已满，策略是“丢日志并计数”，因为与其让业务线程等待拖垮整个服务，不如牺牲一部分日志精度。这里给一个重要的设计决策说明：
- 全阻塞策略：队列满则业务线程等待，能保证日志不丢，但会抬高请求延迟。
- 丢弃策略：队列满则新事件直接丢弃，保证业务顺畅，但会丢失日志。
- 混合策略：根据日志级别分开，比如 Error 级别以上使用阻塞写入，Info 及以下使用丢弃策略。
生产环境中，我推荐混合策略，因为错误日志的可靠性远高于普通 Info 日志。为了体现这一点，我在异步 Appender 内部加了两个通道或者按优先级处理，异常日志优先出队。
实现异步 Appender 还有一个容易忽略的细节：后台线程退出。应用关闭时，队列里可能还有未写入的日志，必须在进程退出前显式调用一个Flush方法，循环清空队列并写入。否则就会出现“最后几条日志神秘失踪”的情况。我见过不少人查半天最后发现是优雅退出没处理好。
4.2 日志内容优化的取舍：结构化、信息密度与隐私
写日志时，信息密度是要有取舍的。记录的信息太少，排查时缺上下文；记录的信息太多，不仅日志膨胀，还可能把敏感数据泄进文件。
我总结了一套实用的日志内容清单：
- 请求级别的日志，记录请求路径、耗时、状态码、用户标识（脱敏过的）这些关键维度。
- 系统级定时任务，记录任务开始时间、结束时间、总耗时、处理条数。
- 数据库操作日志，记录 SQL 模板、参数值（脱敏）、耗时、结果行数。
- 异常日志，永远带上异常类型和堆栈，但不要在消息里拼上完整敏感请求参数。
性能方面，输出 JSON 格式虽然可解析性好，但体积通常比纯文本多 50% 到 100%。我之前做过实测对比：同一批 100 万条日志，纯文本大约 400MB，JSON 格式超过 900MB。如果你的日志采集系统要求 JSON，可以在采集端做二次转换，也可以在本地先输出纯文本、传输时再转换。关键要按项目实际需求选择。
4.3 动态调整日志级别：用诊断技巧替代盲目重启
一个成熟的日志框架应该支持运行时调整级别。真实场景是这样的：服务起在凌晨，白天流量高峰时突然某个接口报错，你想打开 Debug 日志看细节，但又不确定哪一帧开始出错，又不能重启服务让连接全部断开。
此时，动态调整能力很重要。我在手写框架里预留了LoggerConfig.SetMinLevel的线程安全版本，并且让 logger 在每次判断IsEnabled时读取最新配置。这样，运维同学可以通过一个内部接口或配置中心推送新的日志级别，几秒内就能在生产环境开启更细粒度的日志。
实操时我建议发布消息到配置中心后等待 10 秒左右再观察新日志，避免日志缓冲和采集延迟造成的错觉。同时，开启 Debug 日志带来的写盘量、采集量一定要有心理预期，用完之后立刻调回Info或Warn，否则磁盘很快会被塞满。
我还有一个习惯：用日志框架记录一个“日志级别切换事件”本身。把“谁在什么时间把级别改成了什么”写入日志，方便后续审计。否则 Debug 开了一晚上，第二天排查时根本不知道是哪一步操作引起的。
5. 常见问题与排查技巧实录
5.1 日志丢失：查不出原因的时候先怀疑队列策略
丢失日志最常见的原因有三类：异步队列丢弃、应用退出未清空、磁盘已满导致写入异常被吞掉。我在排查时有一套固定流程：
- 先确认日志事件是否进入队列：在异步入队的地方加一个计数器，观察生产端计数和消费端计数是否一致。
- 检查队列是否满：如果有丢弃策略，计数器会显示丢弃数量。如果丢弃量很大，说明消费端写盘太慢，要解决磁盘性能问题而不是增加队列容量。
- 检查应用退出时是否调用了
Flush：这一条最简单也最容易忽略。写一个伪代码示意：
// 关闭 Host 前 loggerFactory.Dispose(); // Dispose 内部遍历全部异步 Appender，触发剩余队列清洗实际排查时，我最常遇到的是第二条。流量一冲上来，磁盘转速跟不上，队列直接爆掉，丢弃数量上千，但是日志表面上看起来只是“少了几条”。一旦知道是队列满了，优化的方向就清晰了：升级异步批处理、压缩日志体积、提高日志级别过滤掉低价值条目。
5.2 日志乱序：多线程写入的经典坑
有朋友吐槽自己写的日志“偶尔时间戳是乱的”，其实原因是多线程各自持有独立的日志管道，或者在入队之前做了太多耗时操作。时间先后顺序不能完全依赖日志到达时间来判断。
解决办法有两种：
- 在事件入队前统一分配一个单调递增的序列号，日志内容里带上这个序列号，采集端排序时参考它。
- 保证所有线程共用同一队列和统一的后台消费线程，这样写入文件的顺序基本就是事件产生顺序。
第二种更简单实用。我手写框架选择的就是单消费线程模式。虽然单线程消费可能成为瓶颈，但只要日志产出速度不高于磁盘写入速度，单线程足够应对绝大多数业务。如果真的高到单线程写不赢，那就应该考虑把文件 Appender 分片或升级存储介质，而不是粗暴开多个线程写同一个文件，那样只会制造乱序和锁竞争。
5.3 日志引起的性能雪崩：格式化与字符串分配是隐形杀手
我见过一次线上事故：某服务开启 Debug 级别日志后，吞吐量直接下降 40% 以上。看到这个数字，第一反应是日志写盘太多，但实测磁盘占用并不大。后来定位发现，问题出在调用方代码大量使用字符串插值拼接日志参数：
logger.Debug($"User={user} Price={totalPrice:F2} Time={elapsed:g}");即使日志级别是Info，Debug(...)内部的$""插值会先执行，字符串已经拼完了，才进入日志框架判断级别。这就白做了大量格式化。我给出的解决方案是使用占位符参数形式：
logger.Debug("User={User} Price={Price:F2} Time={Time:g}", user, totalPrice, elapsed);这样，字符串格式化延迟到日志框架确认需要记录时才执行。同理，对性能敏感的代码路径，建议调用前先做IsEnabled判断。
这套实战方案贯彻到框架里之后，我把它应用到某个模拟高并发项目中，吞吐量在开启完整日志时改善非常明显，GC 分配速率更是肉眼可见地下降。这也说明，日志框架的性能不仅取决于框架本身，更取决于调用方的使用姿势。
5.4 解决重复日志与日志串台的定位经验
重复日志是指同一条日志被写了多次。最常见原因是工厂里重复 AddAppender，或者父 Logger 与子 Logger 都会输出。我在手写框架里通过配置去重来规避：
config.AddAppender(new FileAppender(...)); config.AddAppender(new FileAppender(...)); // 同路径同文件再被添加重名 Appender 应当忽略后续添加，或者至少保留一次并发出警告。这只在配置阶段处理一次，不影响运行时性能。
日志串台是指多条日志内容混在一起，或者 A 请求的日志里混进了 B 请求的数据。这种现象通常发生在统一使用静态全局日志器，却把请求级别的上下文数据也写进了全局字段。正确做法是使用ScopeData或者显式传递上下文，事件对象中保留独立的字典。这样每个请求的日志携带自己的上下文，不会互相污染。
我的日志框架里给LogEvent留了这个字段，就是为了支持场景化排查。实际使用中，引入简单的请求 ID 或链路 ID 之后，日志串联立刻变得清晰，排障效率翻倍。
6. 手写日志框架的复盘与扩展建议
写到这里，框架已经具备一个商用日志框架的核心骨架：级别过滤、格式化器、多输出端、线程安全、异步队列、运行时动态级别调整。我用它支撑过一个模拟订单系统的日志输出，稳定运行下来没有出现丢失和错乱。
基于这段经历，我想分享几个带有个人偏好的建议：
第一，不要盲目引入重量级第三方框架。如果项目只是中小规模，一个几百行的自研日志框架完全够用，可控性更强。一旦遇到第三方库隐藏的兼容问题，排查成本远比写框架本身高。
第二，如果决定自研，一定要把接口抽象做好。最怕的是把所有逻辑写死在某个类里，后面想加一个新输出端就到处改代码。把ILogger、ILogFormatter、ILogAppender三件套定义好，扩展就变成了加类，而不是改代码。
第三，日志框架要对自身错误负责。日志系统不应该因为自己的故障拖垮业务，这是我反复强调的点。实现时，凡是可能抛异常的代码路径，全部要有兜底逻辑，同时预留一个“紧急情况也能看到的错误出口”，比如直接在控制台输出一条粗体提示。
第四，日志不是写得越多越好，也不是级别越低越好。把合适的日志放在合适的位置，配合合理的级别和结构化方式，才能让日志真正成为系统的眼睛。给后续开发者留一句注释：修改日志级别前评估磁盘容量，修改日志格式前评估采集管道。
之后如果要继续扩展，可以从这几个方向入手：支持分布式链路 ID 自动传递、支持按采样率记录日志、支持基于文件大小和日期的自定义滚动策略、支持将日志发送到内存环形缓冲区以应对突发流量。每一条都是真实生产场景中的硬需求，值得作为下一个练习项目。
最后再分享一个个人心得：手写日志框架最困难的部分不是写代码，而是设计“失败时的表现”。正常路径谁都能写漂亮，真正拉开差距的是磁盘满、队列堵、线程退出时系统是否仍然可控。动手实现一遍，远比阅读十篇博客印象更深。如果你正在做 .NET 后端开发，我建议你也花半天时间自己搭一个最小版本，感受一下从设计到落地的全过程。
