# 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.  **敏感信息脱敏**：
    *   严禁在日志中明文记录密码、密钥、身份证号、银行卡号等敏感信息。