Muta.ApiExtensions.Core 1.0.2.5

Muta.ApiExtensions.Core 使用说明

Muta.ApiExtensions.Core 是一个面向 ASP.NET Core Web API 的增强库，提供：统一返回、异常处理、日志、限流、审计、Swagger 增强、Kestrel 配置、HTML 导航页等能力。

---

1. 安装

dotnet add package Muta.ApiExtensions.Core

或

Install-Package Muta.ApiExtensions.Core

---

2. 快速接入（Program.cs）

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddControllers()
    .AddMutaFilters(
        useApiResponseFilter: true,
        useExceptionFilter: true,
        useRequestResponseLogging: true,
        useRateLimitFilter: true,
        useAuditLogFilter: false);

builder.Services.AddMutaLogger(builder.Configuration);
builder.Services.AddMutaSwaggerDocumentation("My API", "v1", useBearer: true);
builder.Services.AddMutaKestrelServer(builder.Configuration);

// 注册导航首页（可选）
// builder.Services.AddMutaHtmlNavigationServices();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();

app.UseRouting();
app.UseAuthorization();

// 如需中间件级请求/响应日志，可启用
// app.UseMiddleware<MutaRequestResponseLoggingMiddleware>();

app.MapControllers();

// 注册 HTML 导航首页（可选）
// app.AddMutaHtmlNavigation(route: "/", includeSwagger: true);

app.Run();

---

3. 每个扩展/组件的具体用法

3.1 ControllerExtensions

文件：Framework/Extensions/ControllerExtensions.cs

AddMutaFilters(...)

批量启用全局过滤器（异常、响应包装、请求日志、限流、审计）。

builder.Services.AddControllers().AddMutaFilters(
    useApiResponseFilter: true,
    useExceptionFilter: true,
    useRequestResponseLogging: true,
    useRateLimitFilter: true,
    useAuditLogFilter: false);

SetExtraData(...)

给统一响应增加扩展字段 Extras。

this.SetExtraData(new { traceId = HttpContext.TraceIdentifier });

SetPagination(...)

给统一响应增加分页信息 Pagination。

this.SetPagination(totalCount: 120, pageSize: 10, pageNumber: 2);

OkWithPagination(...)

返回数据并附加分页。

return this.OkWithPagination(list, new MutaPaginationInfo(totalCount, pageSize, page));

JsonDateTimeConverter

在 AddMutaFilters() 中自动注册，支持多种日期字符串反序列化格式。

---

3.2 SwaggerServiceExtensions

文件：Framework/Extensions/SwaggerServiceExtensions.cs

AddMutaSwaggerDocumentation(...)

自动接入 Swagger，并默认注入响应包装文档过滤器。

builder.Services.AddMutaSwaggerDocumentation(
    title: "设备管理 API",
    version: "v1",
    xmlFileNames: new[] { "YourProject.xml" },
    useBearer: true,
    configure: c =>
    {
        // 这里可继续追加自定义 OperationFilter/SchemaFilter
    });

参数说明：

• xmlFileNames：额外 XML 注释文件名数组。
• useBearer：是否启用 Swagger 的 Bearer 鉴权输入。
• configure：透出 SwaggerGenOptions 二次扩展入口。

---

3.3 LoggerExtension

文件：Framework/Extensions/LoggerExtensions.cs

AddMutaLogger(...)

注册 Console + RollingFile 日志（依赖 NetEscapades.Extensions.Logging.RollingFile）。

builder.Services.AddMutaLogger(builder.Configuration);

appsettings.json 示例：

"Logging": {
  "LogLevel": {
    "Default": "Information",
    "Microsoft.AspNetCore": "Warning"
  },
  "File": {
    "FileName": "logs-",
    "LogDirectory": "Logs",
    "FileSizeLimit": 20971520,
    "FilesPerPeriodicityLimit": 100,
    "Extension": "txt",
    "Periodicity": "Daily"
  }
}

---

3.4 KestrelExtensions

文件：Framework/Extensions/KestrelExtensions.cs

AddMutaKestrelServer(...)

将 Kestrel 配置节绑定到 KestrelServerOptions。

builder.Services.AddMutaKestrelServer(builder.Configuration);

appsettings.json 示例：

"Kestrel": {
  "Certificates": {
    "Default": {
      "Path": "Certificate/SelfSignedCertificate.pfx",
      "Password": "12345678"
    }
  }
}

---

3.5 HtmlNavigationExtensions

文件：Framework/Extensions/HtmlNavExtensions.cs

AddMutaHtmlNavigation(...)

快速生成一个导航首页（默认路由 /），自动扫描 wwwroot 下的 .html 页面并生成按钮。

app.AddMutaHtmlNavigation(
    route: "/",
    title: "系统入口",
    desc: "请选择功能页面",
    includeSwagger: true,
    autoScan: true,
    exclude: new[] { "index.html" });

也可手动指定页面：

app.AddMutaHtmlNavigation(
    pages: new Dictionary<string, string>
    {
        ["/show.html"] = "设备实时控制台",
        ["/admin/test.html"] = "后台测试页"
    });

---

3.6 ExtensionForDateTime

文件：Framework/Extensions/ExtensionForDateTime.cs

ToMutaUnixTimestamp()

转 Unix 秒级时间戳。

long ts = DateTime.Now.ToMutaUnixTimestamp();

ToMutaDateTimeString(bool withMs = true)

输出时间字符串。

string s1 = DateTime.Now.ToMutaDateTimeString(); 

---

3.7 统一响应与异常相关过滤器

目录：Framework/Filters

MutaApiResponseActionFilter

自动将控制器返回包装成 MutaRestfulResult<T>。

SkipMutaApiResponseFilterAttribute

跳过统一响应包装。

[SkipMutaApiResponseFilter]
[HttpGet("raw")]
public IActionResult Raw() => Content("原始输出");

MutaApiExceptionFilter

全局异常捕获并转换为统一错误响应。

---

3.8 请求/响应日志过滤器

MutaApiRequestResponseLoggingFilter

记录 Action 执行前后的请求路径与状态码（Debug 级别）。

SkipMutaApiRequestResponseLoggingFilterAttribute

跳过日志过滤器。

[SkipMutaApiRequestResponseLoggingFilter]
public IActionResult Health() => Ok("ok");

---

3.9 限流过滤器

MutaApiRateLimitFilterAttribute

按接口/控制器配置限流策略。

[MutaApiRateLimitFilter(10, "1m", RateLimitScope.User)]
public IActionResult UserLimitApi() => Ok("每个用户每分钟 10 次");

[MutaApiRateLimitFilter(5, "10s", RateLimitScope.Token)]
public IActionResult TokenLimitApi() => Ok("每个 Token 每 10 秒 5 次");

RateLimitScope：

• Ip
• User
• Token
• Global

period 支持："10s"、"1m"。

---

3.10 审计日志过滤器

MutaAuditLogAttribute

标记需要审计的 Action/Controller。

IMutaAuditLogService

你需要实现此接口，定义日志落地方式（数据库、文件、MQ 等）。

MutaAuditLogActionFilter

读取用户、参数、请求体、结果、耗时、IP、状态码等并写入审计服务。

public class ConsoleAuditLogService : IMutaAuditLogService
{
    public Task WriteLogAsync(MutaAuditLogEntry entry)
    {
        Console.WriteLine($"[审计] 用户:{entry.UserId} 方法:{entry.Method} 成功:{entry.Succeeded}");
        return Task.CompletedTask;
    }
}

builder.Services.AddScoped<IMutaAuditLogService, ConsoleAuditLogService>();
builder.Services.AddControllers().AddMutaFilters(useAuditLogFilter: true);

[MutaAuditLog("登录")]
public IActionResult Login(LoginModel model) => Ok();

---

3.11 Swagger 文档增强过滤器

MutaResponseWrapperOperationFilter

将 Swagger 的返回类型展示为 MutaRestfulResult<原返回类型>，与真实输出一致。

MutaGenericTypeDescriptionSchemaFilter

从 XML 注释读取 MutaRestfulResult<> 的说明并写入 Swagger Schema。

这两个过滤器已在 AddMutaSwaggerDocumentation() 中自动接入。

---

3.12 统一返回模型

文件：Framework/Restful/MutaRestfulResult.cs

MutaRestfulResult<T>

统一响应结构：

• StatusCode
• Data
• Succeeded
• Message
• Errors
• Extras
• Pagination
• Timestamp

MutaPaginationInfo

分页信息结构：

• TotalCount
• PageSize
• PageNumber
• TotalPages

---

3.13 中间件：MutaRequestResponseLoggingMiddleware

文件：Framework/Middleware/MutaRequestResponseLoggingMiddleware.cs

用于中间件层完整记录请求头、Cookie、Body、响应头、响应体。

app.UseMiddleware<MutaRequestResponseLoggingMiddleware>();

建议只在调试环境或受控环境开启，避免日志量过大和敏感信息泄露风险。

---

3.14 工具类：AppsettingConfigTool

文件：Tools/AppsettingConfigTool.cs

PrintAppsettingsEffectiveConfig(...)

按 appsettings.json 中定义的键，打印最终生效值（包括被环境变量覆盖后的值）。

Muta.ApiExtensions.Core.Tools.AppsettingConfigTool
    .PrintAppsettingsEffectiveConfig(builder.Configuration, "appsettings.json");

---

4. 推荐使用顺序

1. AddControllers().AddMutaFilters(...)
2. AddMutaLogger(...)
3. AddMutaSwaggerDocumentation(...)
4. AddMutaKestrelServer(...)
5. 视需要启用 MutaRequestResponseLoggingMiddleware / AddMutaHtmlNavigation(...)

---

5. 常见问题

Q1：如何关闭统一返回包装？

对 Action 或 Controller 添加 [SkipMutaApiResponseFilter]。

Q2：如何关闭请求日志过滤器？

对 Action 或 Controller 添加 [SkipMutaApiRequestResponseLoggingFilter]。

Q3：审计日志为什么没写入？

确认三点：

• 已实现并注册 IMutaAuditLogService
• AddMutaFilters(useAuditLogFilter: true) 已开启
• 对目标 Action/Controller 添加了 [MutaAuditLog]