日志这件事很多团队都是等到线上出问题才想起来补结果翻遍控制台输出发现关键信息早就被冲掉了。我在几个 .NET Core 的 WebAPI 项目里都踩过这个坑后来统一换成了 Log4net 做日志分级并且把重要级别直接落库排查效率提升非常明显。这篇就围绕“.NET Core WebAPI 中使用 Log4net 做日志级别分类并记录到数据库”这个主题把我实际落地的思路、配置细节、踩坑经验完整拆一遍。先说清楚这个内容是什么它解决的是 WebAPI 在生产环境下日志分散、级别混乱、关键错误无法追溯的问题。核心做法是用 Log4net 接管日志输出按 DEBUG、INFO、WARN、ERROR、FATAL 分级把不同级别写到不同目标其中 ERROR 及以上直接进数据库表方便后续查询和告警。适合已经上手 .NET Core、正在做接口服务、需要一套能落地的日志方案的开发者参考新手也能跟着配下来。1. 整体方案设计与选型考量1.1 为什么是 Log4net 而不是内置 ILogger.NET Core 自带的 ILogger 抽象很好用但它的定位是“日志抽象层”真正落盘、落库还得接具体 Provider。内置的 Console、Debug、EventSource 这些 Provider 功能偏基础要做“按级别分流到不同目标”这种细粒度控制配置起来比较绕。Log4net 是老牌方案Appender 体系成熟一个配置文件就能把“控制台输出 INFO、文件记录 DEBUG、数据库只收 ERROR”这类规则写清楚改配置不用动代码。我选它的另一个现实原因是团队熟悉度。很多老项目本来就在用 Log4net迁移到 .NET Core 时沿用同一套配置思路学习成本低。当然它不是唯一选择Serilog 的结构化日志也很强但如果你的诉求是“级别分类 落库 配置驱动”Log4net 完全够用而且资料多、坑都被踩过了。1.2 日志级别分类的设计逻辑级别分类不是随便分的得有明确的使用约定否则团队里有人 DEBUG 打业务数据、有人 ERROR 打提示信息分级就失去意义。我一般按这个原则定级别使用场景是否落库DEBUG开发调试、变量值、流程节点否INFO正常业务流转、接口进入退出否WARN可恢复异常、参数异常但已兜底视情况ERROR业务失败、未捕获异常是FATAL服务级故障、启动失败是这样设计的核心考虑是控制数据库写入量。如果把 INFO 也落库一个中等流量的接口一天几十万条表很快就撑爆查询也慢。只把 ERROR 及以上落库既保证了故障可追溯又不会给数据库带来无谓压力。WARN 是否落库看业务我一般先不落观察一段时间再决定。1.3 落库表结构的前期规划落库前先把表设计好别等数据写进去了再改字段。我用的表结构大致是这样CREATE TABLE ApiLogs ( Id BIGINT IDENTITY(1,1) PRIMARY KEY, LogDate DATETIME NOT NULL, LogLevel VARCHAR(10) NOT NULL, Logger VARCHAR(255), Message NVARCHAR(MAX), Exception NVARCHAR(MAX), Thread VARCHAR(50), RequestPath VARCHAR(500), CreateTime DATETIME DEFAULT GETDATE() );字段设计上有几个点值得说。LogLevel单独存方便按级别筛选Exception用 NVARCHAR(MAX) 存堆栈别用 VARCHAR 免得中文乱码RequestPath是我额外加的用来定位是哪个接口出的问题这个字段在实际排查中价值极高。索引建议在LogDate和LogLevel上建查询时按时间范围 级别过滤是最常见的组合。2. 核心配置与实操要点拆解2.1 引入依赖与初始化方式先装包Log4net 在 .NET Core 里通过 NuGet 引入dotnet add package log4net初始化时机很关键。老版本 .NET Framework 里习惯在 AssemblyInfo 写配置.NET Core 没有这套机制得手动初始化。我一般在 Program.cs 里做确保日志系统在应用启动最早阶段就绪var logRepository LogManager.GetRepository(Assembly.GetEntryAssembly()); XmlConfigurator.Configure(logRepository, new FileInfo(log4net.config));这里有个容易忽略的点log4net.config文件要设置成“复制到输出目录”否则发布后找不到配置文件日志直接不工作。我见过不止一个项目因为这个设置漏了线上一条日志都没有。2.2 配置文件的分级 Appender 设计配置文件是整个方案的核心我把它拆成三个 Appender控制台、滚动文件、数据库。关键配置如下log4net appender nameConsoleAppender typelog4net.Appender.ConsoleAppender layout typelog4net.Layout.PatternLayout conversionPattern value%date [%thread] %-5level %logger - %message%newline / /layout /appender appender nameRollingFileAppender typelog4net.Appender.RollingFileAppender file valuelogs/api.log / appendToFile valuetrue / rollingStyle valueSize / maxSizeRollBackups value10 / maximumFileSize value10MB / staticLogFileName valuetrue / layout typelog4net.Layout.PatternLayout conversionPattern value%date [%thread] %-5level %logger - %message%newline%exception / /layout filter typelog4net.Filter.LevelRangeFilter levelMin valueDEBUG / levelMax valueWARN / /filter /appender appender nameAdoNetAppender typelog4net.Appender.AdoNetAppender bufferSize value1 / connectionType valueMicrosoft.Data.SqlClient.SqlConnection, Microsoft.Data.SqlClient / connectionString value你的连接字符串 / commandText valueINSERT INTO ApiLogs (LogDate, LogLevel, Logger, Message, Exception, Thread, RequestPath) VALUES (log_date, log_level, logger, message, exception, thread, request_path) / !-- 参数定义省略见下文说明 -- filter typelog4net.Filter.LevelRangeFilter levelMin valueERROR / /filter /appender root level valueDEBUG / appender-ref refConsoleAppender / appender-ref refRollingFileAppender / appender-ref refAdoNetAppender / /root /log4net这里的设计逻辑值得展开。文件 Appender 用LevelRangeFilter限制在 DEBUG 到 WARN数据库 Appender 用levelMinERROR只收错误及以上这样两个目标各司其职不会重复。bufferSize设成 1 是为了错误日志实时落库如果设大了会攒批写入出故障时可能丢最后几条这个取舍在排查场景下不划算。2.3 数据库 Appender 的参数映射细节AdoNetAppender 的参数定义是最容易出错的地方每个占位符都要对应一个 parameter 节点parameter parameterName valuelog_date / dbType valueDateTime / layout typelog4net.Layout.RawTimeStampLayout / /parameter parameter parameterName valuelog_level / dbType valueString / size value10 / layout typelog4net.Layout.PatternLayout conversionPattern value%level / /layout /parameter parameter parameterName valuemessage / dbType valueString / size value4000 / layout typelog4net.Layout.PatternLayout conversionPattern value%message / /layout /parameter parameter parameterName valueexception / dbType valueString / size value4000 / layout typelog4net.Layout.ExceptionLayout / /parameterdbType必须和数据库字段类型对上size要和字段长度匹配否则写入会报截断错误。ExceptionLayout专门用来输出异常堆栈别用 PatternLayout 拼%exception格式会乱。连接类型这里用的是Microsoft.Data.SqlClient如果你项目里还是System.Data.SqlClient要对应改混用会报找不到类型。3. 完整实操流程与关键环节实现3.1 封装统一的日志调用入口直接在业务代码里到处LogManager.GetLogger会让代码很脏我一般封装一个静态帮助类public static class LogHelper { private static readonly ILog log LogManager.GetLogger(typeof(LogHelper)); public static void Info(string message) log.Info(message); public static void Warn(string message) log.Warn(message); public static void Error(string message, Exception ex null) log.Error(message, ex); public static void Fatal(string message, Exception ex null) log.Fatal(message, ex); }封装的好处是调用统一、后期换实现只改一处。但要注意GetLogger传的类型决定了日志里的 Logger 字段如果全用 LogHelper那 Logger 字段就都是同一个名字定位不到具体类。我的做法是保留一个带类型参数的版本业务里传当前类类型这样 Logger 字段能反映来源。3.2 在全局异常中间件里落库ERROR 日志最集中的来源是未捕获异常所以全局异常处理中间件是落库的关键入口public class ExceptionMiddleware { private readonly RequestDelegate _next; public ExceptionMiddleware(RequestDelegate next) _next next; public async Task InvokeAsync(HttpContext context) { try { await _next(context); } catch (Exception ex) { LogHelper.Error($接口异常: {context.Request.Path}, ex); context.Response.StatusCode 500; await context.Response.WriteAsync(服务器内部错误); } } }这里把RequestPath拼进 message配合表里的字段就能快速定位问题接口。中间件要注册在管道靠前的位置否则前面环节的异常捕获不到。实测下来这个中间件加上数据库 Appender线上 90% 的故障都能在表里直接查到堆栈。3.3 验证落库是否生效的实操步骤配置完别急着上线本地先验证。我的验证流程是故意在某个接口里throw new Exception(测试异常)调用一次然后查数据库表。如果表里没数据按这个顺序排查先看日志文件里有没有这条 ERROR确认日志系统本身工作再看数据库连接字符串对不对最后看 Appender 的 filter 有没有把级别挡掉。这个顺序能快速定位问题出在哪一层。4. 常见问题与排查技巧实录4.1 日志不写入数据库的典型原因现象可能原因解决方向文件有日志表无数据连接字符串错误检查 connectionString表无数据且无报错bufferSize 过大未刷新设为 1 或手动 Flush写入报截断错误size 与字段长度不匹配调整 size 或字段长度找不到连接类型驱动包未引用或类型名错核对 NuGet 包与类型全名最常见的是连接类型写错。Microsoft.Data.SqlClient和System.Data.SqlClient是两个不同的包类型全名不一样配错了运行时报“无法加载类型”而且这个错误有时被吞掉表现就是静默不写。4.2 性能与数据量的平衡经验数据库 Appender 是同步写入ERROR 多了会拖慢接口响应。我的经验是ERROR 落库保留但要在应用层控制 ERROR 的产生频率比如参数校验失败用 WARN 而不是 ERROR避免把业务性失败当系统故障记。另外定期归档老日志我一般保留 30 天用定时任务清理表太大查询会明显变慢。提示bufferSize 设 1 保证实时性但高并发下写入压力大可以在流量高峰期限流或改用异步 Appender这个取舍要根据实际 QPS 决定。4.3 配置文件路径与发布的坑发布到服务器后日志不工作八成是log4net.config没被复制过去。在 csproj 里加这段确保发布包含ItemGroup None Updatelog4net.config CopyToOutputDirectoryPreserveNewest/CopyToOutputDirectory /None /ItemGroup还有个隐蔽的坑配置文件里的相对路径logs/api.log是相对于工作目录的IIS 托管和命令行启动的工作目录可能不同导致日志写到意想不到的位置。我一般用绝对路径或基于AppContext.BaseDirectory拼接避免找不到文件。5. 进阶优化与长期维护建议5.1 按业务模块拆分 Logger项目大了以后所有日志混在一起不好查。可以在配置文件里按命名空间定义不同 Logger各自挂不同 Appender。比如订单模块的 ERROR 单独落一张表支付模块落另一张排查时直接查对应表效率高很多。这个做法在模块边界清晰的项目里收益明显。5.2 日志内容的规范化约定落库的 message 要有固定格式否则后期没法做统计分析。我团队的约定是“模块名 操作 结果 关键参数”比如“订单模块-创建订单-失败-订单号:xxx”。这样即使不看堆栈光看 message 也能大致判断问题范围。这个约定要写进团队规范靠自觉很难统一。5.3 与告警机制的衔接思路ERROR 落库只是第一步真正有价值的是能触发告警。我的做法是加一个后台任务定时扫描 ApiLogs 表里最近 5 分钟的 ERROR 数量超过阈值就发通知。这样不用改日志系统本身在数据库层面做监控灵活且不影响主流程。阈值要根据业务基线定别拍脑袋设个固定值。我在实际项目里最大的体会是日志方案的价值不在于配得多复杂而在于级别约定是否被团队真正执行、落库的数据是否真的有人去看。配了一套漂亮的 Log4net结果没人查表等于白做。所以落地时一定要把“谁看、多久看一次、看到什么要处理”这几件事定下来工具只是载体。另外一个小技巧表里加个IsHandled字段标记已处理的问题避免重复排查同一条错误这个字段在团队协作时特别省事。