Galosys.Foundation.Compliance.AspNetCore 26.9.16.1

Galosys.Foundation.Compliance.AspNetCore

ASP.NET Core 合规框架衔接包：UseComplianceAuditing() 中间件（对标 ABP UseAuditing()）+ Controller/Action 标注 + EnableComplianceRedaction() 日志自动脱敏 + SensitiveDataFilter 基于 MaskingHelper 的 [Sensitive] 标注自动脱敏。零破坏性变更，薄层引用 Galosys.Foundation.Compliance 核心包与 Galosys.Foundation.AspNetCore 基础包。

设计文档：能力缺口与行动清单 §行动 1 Phase 2 依赖包：Galosys.Foundation.Compliance（核心抽象）+ Galosys.Foundation.AspNetCore（基础 MVC）+ Galosys.Foundation.Actuator（ILogChannel<AuditLog> 复用）

特性

• 自动审计中间件：UseComplianceAuditing() 一行接入，全局捕获 HTTP Method/Path/StatusCode/Duration/IpAddress/UserId + EF EntityChangeInterceptor 写入 HttpContext.Items["Compliance.EntityChanges"] 的字段级 diff，自动组装 AuditLog 经 ILogChannel<AuditLog> 异步投递
• 细粒度标注：[DisableAuditing]（禁用）/ [AuditedOnly]（Lenient 白名单）/ [ComplianceAllow("reason")]（GYS001 + Strict 双豁免）
• 日志自动脱敏：EnableComplianceRedaction() 封装 Microsoft.Extensions.Telemetry.EnableRedaction() + AddRedaction()，默认注册 ErasingRedactor 作为 fallback，ILogger/Serilog/NLog 自动按 DataClassification 脱敏
• SensitiveDataFilter：基于 MaskingHelper 静态门面，[Sensitive(SensitiveDataType)] 标注属性在 OnResultExecuting 阶段自动脱敏
• AuditLogAttribute 过渡：标记 [Obsolete("推荐用 UseComplianceAuditing() 自动中间件")]（仅文档引导，不抛警告）
• 中间件等级联动：Level = Lenient 时中间件仅审计 [AuditedOnly] 标注 action；Level = Standard 全审计；Level = Strict 配合 compliance-strict-runtime-block 规范触发运行期阻断
• 异常容错：中间件投递 AuditLog 抛异常时仅记录日志，不中断 HTTP 响应（业务请求优先于审计）

快速开始

// Program.cs
using Galosys.Foundation.Compliance;
using Galosys.Foundation.Compliance.AspNetCore;  // UseComplianceAuditing 扩展
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// 1) 注册合规核心能力
builder.Services.AddCompliance(opts =>
{
    opts.Level = ComplianceLevel.Standard;
    opts.IsEnabled = true;
});

// 2) 注册 ASP.NET Core 衔接服务
builder.Services.AddComplianceAspNetCore();

// 3) 注册日志自动脱敏（可选）
builder.Services.EnableComplianceRedaction();

var app = builder.Build();

// 4) 接入中间件（必须在 UseRouting 之后、UseEndpoints 之前）
app.UseRouting();
app.UseComplianceAuditing(opts =>
{
    opts.Level = ComplianceLevel.Standard;
    opts.ExcludedActions.Add("HealthController.Ping");  // 排除健康检查
});
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run();

Controller/Action 标注

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;  // 标注命名空间

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    // 默认行为：Standard 模式全部审计；Lenient 模式仅审计 [AuditedOnly]
    [HttpGet("{id}")]
    public IActionResult Get(int id) => Ok();

    // [DisableAuditing] 跳过审计（如：高频读操作）
    [HttpGet("hot")]
    [DisableAuditing]
    public IActionResult Hot() => Ok();

    // [AuditedOnly] 仅 Lenient 模式生效（白名单）
    [HttpPost]
    [AuditedOnly]
    public IActionResult Create() => Ok();
}

EntityChange 集成

中间件会在 await next() 之后从 HttpContext.Items["Compliance.EntityChanges"] 读取由 EntityChangeInterceptor 缓存的字段级 diff，自动拼装 OriginalValues/CurrentValues/Changes 字段后投递。

// Program.cs 启用 EF 拦截器
builder.Services.AddDbContext<AppDbContext>(opts =>
{
    opts.UseSqlServer(connectionString);
    opts.AddInterceptors(new EntityChangeInterceptor(Options.Create(
        new ComplianceOptions { Level = ComplianceLevel.Standard })));
});

EnableComplianceRedaction 用法

// Program.cs 启用日志自动脱敏
builder.Services.EnableComplianceRedaction();

// 使用：日志参数自动按 DataClassification 脱敏
logger.LogInformation("用户手机号: {Phone}", user.Phone);
// 输出: 用户手机号: ***

// 自定义 Redactor（可选）
builder.Services.AddRedaction(redaction =>
{
    redaction.SetRedactor<MyHmacRedactor>(DataClassifications.PrivateData);
});

SensitiveDataFilter 自动接管

注册 AddCompliance() 后，AddSensitiveDataFilter() 通过 MaskingHelper 静态门面按 SensitiveDataType 路由脱敏，无需业务方修改：

// Program.cs
builder.Services.AddCompliance(opts =>
{
    opts.Level = ComplianceLevel.Standard;
    opts.ExcludedActions.Add("HealthController.Ping");
});
builder.Services.AddControllers()
    .AddSensitiveDataFilter(opts =>
    {
        opts.MaxDepth = 5;
    });

[Sensitive] 属性标注自动走 MaskingHelper.MaskPhone / MaskIdCard / MaskEmail / MaskPartial 路由。

最小标注片段

using Galosys.Foundation.Compliance.AspNetCore;

public class OrderDto
{
    public int Id { get; set; }

    [Sensitive(SensitiveDataType.Phone)]   // 138****8000
    public string Phone { get; set; } = "";

    [Sensitive(SensitiveDataType.IdCard)]  // 110101********1234
    public string IdCard { get; set; } = "";

    [Sensitive(SensitiveDataType.Email)]   // u***@example.com
    public string Email { get; set; } = "";
}

// 响应序列化时，AddSensitiveDataFilter 自动按 [Sensitive] 路由脱敏

测试覆盖

46 个集成测试位于 framework/test/Galosys.Foundation.Compliance.AspNetCore.Tests/，覆盖：

• 中间件全链路（HTTP 200 / 500 / DisableAuditing / Lenient / ExcludedActions / IsDisabled / LogChannel 异常容错）
• EnableComplianceRedaction（fallback ErasingRedactor / 用户自定义覆盖）
• SensitiveDataFilter 兼容（MaskingHelper 路由 + DI 注册）

依赖

• Microsoft.Extensions.Telemetry（EnableComplianceRedaction 依赖）
• Microsoft.AspNetCore.App（FrameworkReference）
• Galosys.Foundation.Compliance（核心抽象）
• Galosys.Foundation.AspNetCore（SensitiveDataFilter / HttpContextExtensions）
• Galosys.Foundation.Actuator（ILogChannel<AuditLog> + AuditLog 实体）

相关能力

• Galosys.Foundation.Compliance — 合规核心包（数据分类/EntityChange/MaskingHelper/合规等级）
• Galosys.Foundation.Compliance.Analyzers — GYS001 Roslyn Analyzer 编译期诊断
• compliance-aspnetcore-middleware — 中间件规范
• compliance-aspnetcore-annotations — 标注规范
• sensitive-data-masking — SensitiveDataFilter 改造规范