2.9 KiB
2.9 KiB
2.1 日志规约
【强制】
-
日志组件：
- 底层框架：Aegis.Core.Logs 使用 NLog 作为日志记录提供程序。
- 集中收集：生产环境必须配置 Seq或ELK 作为日志的集中收集与分析端点。
- 抽象使用：代码中应依赖
Microsoft.Extensions.Logging.ILogger<T>接口进行日志记录，避免直接依赖 NLog 的特定 API。
-
API 请求日志：
- 自动化记录：Web API 项目可以通过 AOP 过滤器（如
[TypeFilter(typeof(LogAttribute))]或全局过滤器）自动记录 HTTP 请求的入参、出参、执行时间及客户端信息。 - 避免冗余：禁止在 Controller 方法内部手动记录 "进入方法"、"离开方法" 等流水账日志，除非有特殊的业务追踪需求。
- 自动化记录：Web API 项目可以通过 AOP 过滤器（如
-
异常记录规范：
- 完整堆栈：记录异常时，必须将
Exception对象作为LogError方法的第一个参数传入。 - 反例：
_logger.LogError($"处理失败：{ex.Message}");（丢失堆栈信息） - 正例：
_logger.LogError(ex, "处理订单 {OrderId} 失败", orderId);
- 完整堆栈：记录异常时，必须将
-
结构化日志：
- 使用模板：必须使用消息模板（Message Templates）语法（使用
{Property}占位符），禁止使用字符串拼接或string.Format。这确保日志在 Seq 中可被索引和查询。 - 正例：
_logger.LogInformation("用户 {UserId} 修改了状态为 {Status}", userId, status);
- 使用模板：必须使用消息模板（Message Templates）语法（使用
-
默认上下文信息：
- 自动注入：框架层（
Aegis.Core.Logs）已统一配置日志 Layout，自动包含 RequestId (${request-id}) 和 调用方法名 (${callsite})。 - 无需手动记录：开发者在记录日志时，无需在消息体中重复记录当前方法名或 RequestId。
- 说明：默认 Layout 格式为
${date}|${level:uppercase=true}|${request-id}|${callsite:includeNamespace=false}|${message}|${exception}。
- 自动注入：框架层（
【推荐】
-
日志级别定义：
- Trace/Debug：仅用于开发环境调试，生产环境默认关闭。
- Information：记录系统关键流程节点（如：定时任务开始/结束、关键状态流转）。
- Warning：记录非预期的但系统可自动恢复的业务异常（如：参数校验失败、第三方接口偶尔超时）。
- Error：记录导致当前请求失败的系统异常（如：数据库连接失败、空指针异常）。
- Critical：记录导致系统崩溃或无法提供服务的致命错误。
-
日志保留策略：
- 本地文件日志建议按天滚动（
RollingFile），保留 7-15 天。 - Seq 服务器日志根据磁盘容量配置保留策略（通常 30 天）。
- 本地文件日志建议按天滚动（
-
敏感信息脱敏：
- 严禁在日志中明文记录密码、密钥、身份证号、银行卡号等敏感信息。