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