Galosys.Foundation.AspNetCore 26.7.18.2

Galosys.Foundation.AspNetCore

目标框架: net10.0

成熟度: 🟢 稳定 — 生产可用，测试充分，活跃维护

简介

Galosys.Foundation.AspNetCore 是 ASP.NET Core 核心扩展模块，提供 MVC 过滤器、身份认证、权限管理、SignalR 中间件等功能。

特性

MVC 过滤器

• GlobalResponseLoggingResultFilter - 响应日志记录
• GlobalLogExceptionFilter - 全局异常日志
• GlobalModelStateValidationActionFilter - 模型状态验证
• AuditLogAttribute - 审计日志
• RequestLogAttribute - 请求日志
• CacheableAttribute - 响应缓存（支持多租户 Key 隔离，HybridCache 内置击穿保护，可选布隆过滤器）
• CacheEvictAttribute - 缓存清除（支持多租户 Key 隔离）
• CachePutAttribute - 缓存写入（支持多租户 Key 隔离）
• SensitiveAttribute + SensitiveDataFilter - API 响应敏感字段自动脱敏（手机/身份证/邮箱等）
• RateLimitAttribute - 声明式限流元数据，配合 GlobalLimiter 按用户/租户粒度限流
• IdempotentAttribute - 幂等性验证

身份认证

• JWT Bearer - JWT 认证支持
• HttpBasic - HTTP 基本认证
• ApiKey - API Key 认证

权限管理

• PermissionAuthorizationHandler - 权限授权处理器
• PermissionScanner - 权限扫描器
• DynamicAuthorizationPolicyProvider - 动态授权策略

SignalR

• SignalR Hub - 实时通信
• SignalR Client - 客户端支持

中间件

• CorrelationIdMiddleware - 跨服务请求链路 CorrelationId 生成与透传
• GlobalExceptionHandlerMiddleware - 全局异常处理
• MultiTenancyMiddleware - 多租户支持
• LoginUserMiddleware - 登录用户中间件
• CorsMiddleware - CORS 配置
• SensitiveDataFilter - API 响应敏感字段自动脱敏（IAlwaysRunResultFilter）

安装

dotnet add package Galosys.Foundation.AspNetCore

使用

注册服务

services.AddAspNetCore(); // 注册所有服务

配置 JWT 认证

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://auth.example.com";
        options.Audience = "api.example.com";
    });

配置 SignalR

services.AddSignalR();

app.UseEndpoints(endpoints =>
{
    endpoints.MapHubs();
});

使用审计日志

[AuditLog("创建订单")]
public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
{
    // 业务逻辑，审计日志自动通过 ReliableLogChannel 异步持久化
}

// 设置审计前后值
HttpContext.SetAuditValues(originalValues, currentValues, targetId);

审计日志持久化

审计日志通过 Tier 2 可靠通道异步持久化，失败自动重试（指数退避，最多 3 次）。需注册通道和实现 IAuditLogRepository：

// 注册通道 + 消费者（通常在 Startup 中）
services.AddAuditLogChannel();

// 实现持久化接口
public class AuditLogRepository : IAuditLogRepository
{
    public Task AddAsync(AuditLog auditLog, CancellationToken ct = default)
    {
        // 写入 lc.lc_audit_log 表
    }
}

使用请求日志

[RequestLog("订单API")]
public async Task<IActionResult> ListOrders([FromQuery] OrderQuery query)
{
    // 请求日志自动通过 ObservableLogChannel 批量持久化
}

请求日志持久化

请求日志通过 Tier 1 可观测通道批量持久化。需注册通道和实现 IRequestLogRepository：

services.AddRequestLogChannel();

public class RequestLogRepository : IRequestLogRepository
{
    public Task AddRangeAsync(IReadOnlyList<RequestLogCreateInput> inputs, CancellationToken ct = default)
    {
        // 批量写入 lc.lc_api_request_log 表
    }
}

使用登录日志

// 替代旧版 GetUserLoginEvent + publisher.PublishAsync
await HttpContext.PublishLoginLogAsync(realName, status: 1, remark: "登录成功");

登录日志通过 Tier 2 可靠通道持久化。需注册通道和实现 ILoginLogRepository（AddCore() 内置注册通道）。

使用 CorrelationId 链路透传

CorrelationIdMiddleware 已自动集成在 UseAspNetCore() 管道中（位于 UseLocalization() 之后），无需手动注册。支持自定义 Header 名称：

app.UseCorrelationId(options =>
{
    options.Header = "X-Request-Id";          // 读取的请求 Header
    options.ResponseHeader = "X-Request-Id";   // 写入的响应 Header
    options.IncludeInResponse = true;           // 是否在响应中包含
});

CorrelationId 自动写入 HttpContext.Items["CorrelationId"] 和日志上下文（ILogger.BeginScope）。

使用敏感数据脱敏

在 Model 属性上标注 [Sensitive]，API 返回时自动脱敏：

public class UserDto
{
    public string Name { get; set; }
    [Sensitive(SensitiveDataType.Phone)]
    public string Phone { get; set; }
    [Sensitive(SensitiveDataType.IdCard)]
    public string IdCard { get; set; }
    [Sensitive(SensitiveDataType.Email)]
    public string Email { get; set; }
}

在 Program.cs 中注册：

builder.Services.AddSensitiveDataFilter(options =>
{
    options.MaxDepth = 5; // 递归扫描最大深度，默认 5
});

使用幂等性验证

[Idempotent]
public async Task<IActionResult> SubmitOrder([FromBody] SubmitOrderRequest request)
{
    // 幂等操作
}

使用 RateLimit 声明式限流

[RateLimit] 配合内置 GlobalLimiter 自动生效，无需额外注册。

[RateLimit(By = "User", Limit = 10, WindowSeconds = 60)]
public IActionResult Get() => Ok();

[RateLimit(By = "Tenant", Limit = 100, WindowSeconds = 60)]
public IActionResult List() => Ok();

使用缓存 Attribute（基于 HybridCache）

// 基本用法 — Cache Key: "dict-type:{表达式结果}"，HybridCache 自动管理 L1/L2 缓存和击穿保护
[Cacheable("dict-type", Key = "query.Code")]
public async Task<UnifiedResponse> GetDictType(DictTypeQuery query) { }

// 多租户隔离 — Cache Key: "dict-type:{tenantId}:{表达式结果}"
[Cacheable("dict-type", Key = "query.Code", TenantAware = true)]
public async Task<UnifiedResponse> GetDictType(DictTypeQuery query) { }

// 布隆过滤器防穿透 — 缓存键不存在时直接返回，跳过 DB
[Cacheable("dict-type", Key = "query.Code", EnableBloomFilter = true)]
public async Task<UnifiedResponse> GetDictType(DictTypeQuery query) { }

// 缓存清除
[CacheEvict("dict-type", Key = "command.Code", TenantAware = true)]
public async Task<UnifiedResponse> UpdateDictType(UpdateDictTypeCommand command) { }

// 缓存写入
[CachePut("dict-type", Key = "command.Code", TenantAware = true)]
public async Task<UnifiedResponse> CreateDictType(CreateDictTypeCommand command) { }

TenantAware Key 格式

前提：使用 TenantAware=true 需确保已调用 services.AddCore() 注册 ITenantContext。

权限控制

[Authorize(Policy = "RequirePermission")]
public async Task<IActionResult> DeleteOrder(string orderNo)
{
    // 需要特定权限
}

SignalR Hub

public class NotificationHub : Hub
{
    public async Task SendMessage(string user, string message)
    {
        await Clients.User(user).SendAsync("ReceiveMessage", message);
    }
}

核心类

依赖

• Microsoft.AspNetCore.Authentication.JwtBearer
• Microsoft.AspNetCore.SignalR
• Galosys.Foundation.Core