MoneyTree.Web Web 集成

📋 概述

MoneyTree.Web 是框架的 Web 集成模块，统一所有模块的 Web 入口，提供静态启动方法（MoneyTreeHost）、全局异常处理、请求日志、ApiResult 自动包装、CurrentUser 自动填充、SSE 支持等中间件和过滤器，并以 NLog 作为默认日志组件。

🏗️ 项目文件结构

MoneyTree.Web/
├── MoneyTree.Web.csproj
├── GlobalUsings.cs
├── Host/
│   └── MoneyTreeHost.cs                 # 静态启动入口
├── Middlewares/
│   ├── GlobalExceptionMiddleware.cs     # 全局异常处理
│   ├── HmacAuthMiddleware.cs            # HMAC 认证中间件
│   └── RequestLoggingMiddleware.cs      # 请求日志记录
├── Extensions/
│   ├── ClaimsPrincipalExtensions.cs     # ClaimsPrincipal 扩展
│   ├── HmacHttpClientExtensions.cs      # HMAC HttpClient 扩展
│   ├── SseExtensions.cs                 # SSE 流式响应扩展
│   └── WebDefaultsExtensions.cs         # 默认 Web 配置扩展
├── Filters/
│   └── ApiResultFilter.cs               # ApiResult 自动包装过滤器
├── HttpHandlers/
│   └── HmacAuthHandler.cs               # HMAC 签名请求处理器
├── Options/
│   └── HmacAuthOptions.cs               # HMAC 认证配置选项
└── ProblemDetails/
    └── ProblemDetailsFactory.cs         # 标准 Problem Details 工厂

🎯 核心能力

🚀 静态 Program 入口

MoneyTreeHost 提供两种启动模式：

默认启动（推荐）

// 自动走 Aspire 原生路径，无需传 configureDefaults
MoneyTreeHost.Run(args, builder =>
{
    builder.Services.AddDbContext<MyDbContext>(...);
}, (builder, app) =>
{
    app.UseHmacAuth();
});

高级模块路径（精细控制）

MoneyTreeHost.Run(args, builder =>
{
    builder.Services.AddDbContext<MyDbContext>(...);
}, (builder, app) =>
{
    app.UseHmacAuth();
},
configureDefaults: d =>
{
    d.Resilience = r => r.WithRetry(3, 1).WithTimeout(30);
    d.Telemetry = t => t.WithServiceName("MyService").UseOpenTelemetryCollector();
    d.ServiceDiscovery = sd => sd.WithServiceName("MyService").UseConsul();
});

专家 API（不注入 ServiceDefaults）

// RunAdvanced 完全手动控制，不调用 AddMoneyTreeServiceDefaults
MoneyTreeHost.RunAdvanced(args, builder => { ... }, (builder, app) => { ... });

方式四：自定义配置类（推荐生产环境）

public class AppConfig : IMoneyTreeAppConfig
{
    public void ConfigureDatabase(DatabaseOptions db)
    {
        db.UsePostgreSql("Host=localhost;Database=mydb");
    }

    public void ConfigureMultiTenancy(MultiTenancyOptions mt)
    {
        mt.UseHeader("X-Tenant-Id");
    }

    public void ConfigureCaching(CachingOptions cache)
    {
        cache.UseRedis("localhost:6379");
    }

    public void ConfigureTelemetry(TelemetryOptions telemetry)
    {
        telemetry.UseOpenTelemetryCollector();
    }

    public void ConfigureResilience(ResilienceOptions resilience)
    {
        resilience.Defaults.SetRetry(3);
    }
}

// Program.cs — 一行启动
MoneyTreeHost.Run<AppConfig>();

方式五：带参数解析

// 自动解析命令行参数或环境变量
MoneyTreeHost.Run(args, app =>
{
    var connectionString = app.Configuration.GetConnectionString("Default");
    app.UsePostgreSql(connectionString!);
    app.UseRedis(app.Configuration["Redis:ConnectionString"]!);
});

📋 IMoneyTreeAppConfig 接口

业务系统只需实现关心的配置方法，其余使用框架默认值。

📖 使用示例

配置服务和中间件

// Program.cs
MoneyTreeHost.Run(args,
    configureBuilder: builder =>
    {
        builder.Services.AddScoped<IMyService, MyService>();
    },
    configureApp: (builder, app) =>
    {
        app.UseMiddleware<MyMiddleware>();
    });

抛出业务异常

在服务中抛出的异常自动被 GlobalExceptionMiddleware 捕获并转换为 ApiResult 格式：

public class OrderService
{
    public async Task<Order> GetAsync(string id)
    {
        var order = await _db.Orders.FindAsync(id);
        return order ?? throw new NotFoundException("订单", id);
    }

    public async Task CancelAsync(string id)
    {
        var order = await _db.Orders.FindAsync(id);
        if (order.Status == OrderStatus.Shipped)
        {
            throw new DomainException("已发货的订单无法取消", 409, "ORDER_SHIPPED");
        }
    }
}

获取当前用户

在 Controller 或 Minimal API 中：

app.MapGet("/api/me", (ClaimsPrincipal user) =>
{
    var currentUser = user.ToCurrentUser();
    return Results.Ok(new { currentUser.Id, currentUser.UserName });
});

在服务中使用（通过 IHttpContextAccessor）：

public class OrderService
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    private ICurrentUser CurrentUser =>
        _httpContextAccessor.HttpContext?.User.ToCurrentUser()
        ?? CurrentUser.Core.CurrentUser.Anonymous;
}

SSE 终结点

app.MapGet("/api/notifications", (HttpResponse response) =>
{
    var stream = GetNotificationStream();
    return stream.ToSseResult("notification");
});

📝 NLog 默认配置

框架预置 nlog.config，AddMoneyTreeDefaults() 自动注册 NLog：

<nlog>
  <targets>
    <target name="console" xsi:type="Console" />
    <target name="file" xsi:type="File"
            fileName="logs/${shortdate}.log"
            layout="${longdate}|${level}|${logger}|${message}|${exception:format=tostring}" />
  </targets>
  <rules>
    <logger name="Microsoft.*" maxLevel="Warn" final="true" />
    <logger name="*" minLevel="Info" writeTo="console,file" />
  </rules>
</nlog>

Hmac使用示例

方式一：直接指定密钥

// Program.cs builder.Services.AddHttpClient("PaymentService", client => { client.BaseAddress = new Uri("https://payment.example.com"); }) .AddHmacAuthHandler("order-service", "your-secret-key");

方式二：从配置中心读取密钥

// Program.cs builder.Services.AddHttpClient("NotificationService", client => { client.BaseAddress = new Uri("https://notification.example.com"); }) .AddHmacAuthHandler("order-service"); // 自动从 IConfiguration 读取密钥

方式三：在服务中使用

public class OrderService { private readonly IHttpClientFactory _httpClientFactory;

public OrderService(IHttpClientFactory httpClientFactory)
{
    _httpClientFactory = httpClientFactory;
}

public async Task CreatePaymentAsync(CreatePaymentRequest request)
{
    var client = _httpClientFactory.CreateClient("PaymentService");
    // 请求自动携带 HMAC 签名头，无需手动处理
    var response = await client.PostAsJsonAsync("/api/payment/create", request);
}

}