跳到主要内容
版本：3.0.0

请求日志

解决什么问题​

框架内置了 RequestLogFilter（IAsyncActionFilter），可以自动记录每个 Controller Action 的请求和响应日志，包括请求参数、响应内容、耗时、客户端 IP 等。接入方不需要手动写日志代码。

这个功能由 Aegis.Core.Infrastructure 提供，默认不开启。有两种开启方式：

  • 全局开启：在 appsettings.json 中配置 Enabled: true，所有 Controller Action 自动记录
  • 按需开启：在单个 Action 或 Controller 上标注 [TypeFilter(typeof(RequestLogFilter))]，只记录标注的接口

全局开启​

在 appsettings.json 中配置：

{
  "Aegis": {
    "RequestLog": {
      "Enabled": true
    }
  }
}

设为 true 后，RequestLogFilter 会被注册为全局 Filter，所有 Controller Action 的请求和响应都会被记录。

未配置或设为 false 时，Filter 不会注册到请求管线，对应用性能没有任何影响。

按需为单个接口开启​

如果不希望全局开启，只想对特定接口记录，可以在 Action 或 Controller 上手动标注：

using Aegis.Core.Infrastructure.Filters;
using Microsoft.AspNetCore.Mvc;

[TypeFilter(typeof(RequestLogFilter))]
[HttpGet("critical-order/{id}")]
public async Task<ApiResponse> GetCriticalOrder(string id)
{
    // 这个接口的请求和响应会被记录
}

这种方式不受全局 Enabled 开关的影响，即使 Enabled 为 false 也能正常工作。

也可以把标注放在 Controller 类上，该 Controller 下所有 Action 都会记录：

[TypeFilter(typeof(RequestLogFilter))]
public class PaymentController : ApiControllerBase
{
    // 所有 Action 都会记录请求日志
}

记录了什么​

请求日志​

  • RequestId
  • Controller / Action 名称
  • 客户端 IP
  • 请求参数（JSON 序列化）
  • 请求头

响应日志​

  • RequestId
  • Controller / Action 名称
  • 客户端 IP
  • 耗时（ms）
  • 响应内容（JSON 序列化）

日志格式示例​

[req-a1b2c3d4] Requesting Order/Create, IP:192.168.1.100, Params:{"orderId":"ORD-001"}, Headers:{}
[req-a1b2c3d4] Response Order/Create, IP:192.168.1.100, Duration:45ms, Result:{"code":200,"message":"ok"}

默认行为​

行为默认值
启用状态关闭，需要开启时设 Enabled: true 或使用 [TypeFilter]
日志级别Information
Body 截断长度2048 字符，超出追加 ...[truncated]
排除路径/swagger
排除 Body 的 Content-Typemultipart/form-data（记录为 [binary or non-text content]）
慢请求阈值关闭（-1）
异常请求自动提升到 Warning 级别

配置参考​

在 appsettings.json 中通过 Aegis:RequestLog 节调整行为：

{
  "Aegis": {
    "RequestLog": {
      "Enabled": true,
      "Level": "Information",
      "MaxBodyLength": 4096,
      "SlowRequestThresholdMs": 3000,
      "ExcludePaths": ["/swagger", "/health"],
      "ExcludeBodyContentTypes": ["multipart/form-data"]
    }
  }
}
配置项类型默认值说明
Enabledboolfalse是否全局启用，开启时设为 true
LevelLogLevelInformation日志输出级别，最高 Information
MaxBodyLengthint2048请求/响应 Body 截断长度，-1 不截断
SlowRequestThresholdMsint-1慢请求阈值（ms），超过此值的请求以 Warning 级别记录
ExcludePathsstring[]["/swagger"]不记录日志的请求路径前缀（不区分大小写）
ExcludeBodyContentTypesstring[]["multipart/form-data"]不记录 Body 的 Content-Type 前缀，命中时 Body 记录为 [binary or non-text content]

常见场景​

在开发环境看到请求日志​

在 appsettings.Development.json 中启用即可：

{
  "Aegis": {
    "RequestLog": {
      "Enabled": true
    }
  }
}

生产环境的 appsettings.json 不加这个配置，请求日志就不会在生产环境输出。

开启慢请求告警​

{
  "Aegis": {
    "RequestLog": {
      "Enabled": true,
      "SlowRequestThresholdMs": 3000
    }
  }
}

超过 3 秒的请求会以 Warning 级别记录。

排除健康检查路径​

{
  "Aegis": {
    "RequestLog": {
      "Enabled": true,
      "ExcludePaths": ["/swagger", "/health", "/metrics"]
    }
  }
}

边界与限制​

  • Level 最高只能设为 Information，不能设为更高级别。这是有意为之，避免在生产环境产生大量日志。
  • 请求参数序列化使用 Newtonsoft.Json，如果 Action 参数包含循环引用，可能导致序列化异常。这种情况下应把该 Action 的参数类型排除或调整。
  • 响应内容只记录 ObjectResult 的值。返回 ViewResult、EmptyResult 等类型时，Result 字段为空。
  • 全局模式下不能按 Controller 或 Action 单独关闭。如果需要精细控制，使用 ExcludePaths 排除，或改用 [TypeFilter] 按需标注。