HZY.Framework.Core 10.1.19

HZY.Framework

模块化 .NET 10 插件框架：AOP、依赖注入、EF Core 仓储、动态 API 控制器、定时任务、Redis、服务器监控。

• 源码与完整文档：https://gitee.com/hzy6/HZY.Framework
• 完整实战案例（HzyAdmin 后台管理系统）：https://gitee.com/hzy6/HzyAdmin

包清单

快速开始

// 1. 定义启动模块（可组合多个模块，按 Order 排序执行）
[ImportStartupModule(typeof(RepositoryStartupModule))]
public class AppStartup : StartupModule<AppStartup>
{
    public override void ConfigureServices(WebApplicationBuilder builder)
    {
        // 动态 API 控制器：实现 IDynamicApiController 的服务自动注册为控制器
        builder.Services.AddControllers().AddDynamicApiController();

        // 扫描 [Component] 特性自动注册服务
        builder.Services.AddDependencyInjectionByComponent([typeof(Program).Assembly]);
    }
}

// 2. Program.cs —— 一行启动
var builder = WebApplication.CreateSlimBuilder(args);
HzyApplication.Run<AppStartup>(builder);

功能速查（AI 友好索引）

依赖注入

[Component]                                              // 默认 Transient
[Component(ServiceLifetime.Scoped)]                      // 指定生命周期
[Component(typeof(IUserService), ServiceLifetime.Singleton)] // 指定接口注册
public class UserService : IUserService { }

public class OrderService
{
    [Autowired]                                          // 属性注入（AOP 拦截 get）
    public IUserService UserService { get; set; } = null!;
}

注册入口：services.AddDependencyInjectionByComponent([typeof(Program).Assembly])

AOP 拦截器

自定义拦截器继承 AopMoAttribute（基于 Rougamo.Fody 编译期织入，零运行时代理）：

public class LogAttribute : AopMoAttribute
{
    public override void OnEntry(MethodContext context) { /* 方法进入 */ }
    public override void OnSuccess(MethodContext context) { /* 方法成功 */ }
    public override void OnException(MethodContext context) { /* 方法异常 */ }
    public override void OnExit(MethodContext context) { /* 方法退出（重写时必须调 base） */ }
}

// 内置拦截器
[Time]                                                   // 记录方法耗时日志
[MemoryCache(CacheKey = "user:{id}", CacheDuration = 60)] // 内存缓存（秒，0=永久）

方法缓存（HZY.Framework.Caching 独立包）

声明式方法缓存 + 可扩展分布式提供者；标签版本号批量失效（O(1)，不扫描缓存）；single-flight 防击穿：

// 1. 注册（启动模块中，重复调用幂等）
builder.Services.AddHzyCaching();
// 或切换自定义分布式提供者：builder.Services.AddHzyCaching(o => o.DefaultProviderName = "Redis");

// 2. 方法缓存：显式 Key 模板支持 {参数} 与 {参数.属性}；未设置 Key 时按"方法全名+签名+参数值"生成
[Cacheable(Key = "member:{id}", ExpirationSeconds = 300)]
public virtual Task<Member?> GetMemberAsync(long id) { ... }

[Cacheable(Tags = new[] { "member-list" })]              // 打标签，支持批量失效
public virtual List<Member> GetMembers(string kw) { ... }

// 3. 缓存清理：精确 Key + 标签批量失效（递增标签版本号即让整组键不可达）
[CacheEvict(Keys = new[] { "member:{id}" }, Tags = new[] { "member-list" })]
public virtual Task UpdateMemberAsync(long id, Member m) { ... }

// 4. 非 AOP 场景异步门面（全异步 I/O，同样支持标签与 single-flight）
var member = await cacheService.GetOrCreateAsync("member:1", () => LoadAsync(1), tags: ["member-list"]);

// 5. 扩展分布式：实现 ICacheProvider（含标签版本读写），注册后切换 DefaultProviderName

默认不缓存 null / 空集合（防穿透，可通过 CacheNullValues / CacheEmptyCollections 开启）；方法异常不写缓存。

执行模型：异步方法（Task/Task<T>）上的拦截为真异步（缓存读写与 single-flight 等待均为 await，不阻塞线程，支持网络型提供者）；同步方法上的拦截钩子为同步执行，要求提供者 IsSynchronous = true（如内存提供者），网络型提供者会抛 NotSupportedException —— 此时请改用异步方法或 ICacheService 异步 API。ICacheService 与 AOP 特性按 CachingOptions.DefaultProviderName 从全部已注册的 ICacheProvider 中解析同一提供者，与注册顺序无关。

EF Core 仓储

// 注册（MySql 为例，其他数据库换对应 Provider 包）
builder.AddRepository<AppDbContext>(new RepositoryOptions
{
    DefaultDatabaseType = DefaultDatabaseType.MySql,
    ConnectionString = builder.Configuration.GetConnectionString("Default")!
});

// 使用：任意服务构造函数注入 IRepository<T>
public class MemberService(IRepository<Member> memberRepository)
{
    // 查询（软删除自动过滤）
    var page = await memberRepository.Queryable
        .WhereIf(!string.IsNullOrWhiteSpace(keyword), w => w.Name.Contains(keyword))
        .ToPageAsync(1, 20);

    // 增删改（雪花 ID、审计字段自动填充，[Transactional] 事务保护）
    await memberRepository.InsertAsync(entity);
    await memberRepository.UpdateAsync(entity);
    await memberRepository.DeleteByIdAsync(id);          // 软删除：改写为 UPDATE
}

实体特性（标记在属性上即生效，无需配置）：

方法级特性：

[Transactional]                                          // 事务（支持嵌套复用、多 DbContext）
[Transactional(typeof(AppDbContext), typeof(OtherDbContext))] // 多库事务
public async Task CreateOrderAsync(Order order) { ... }

动态 API 控制器

// 实现该接口（或标记 [DynamicApiController]）→ 自动注册为控制器
// 路由 kebab-case，方法名前缀推断 HTTP 方法（Get*/Query*→GET，Add*/Create*→POST，...）
public class MemberAppService : IDynamicApiController
{
    public async Task<List<MemberDto>> GetListAsync(string? keyword) { ... }
    // → GET /member/list?keyword=xxx  （具体规则可配）
}

定时任务

[Component]
public class JobService
{
    [Scheduled("0/5 * * * * ?")]                          // 每 5 秒（Quartz Cron）
    public void SyncData() { ... }
}

全局服务网关

App.Services                  // IServiceCollection
App.ServiceProvider           // IServiceProvider（根容器）
App.HttpContext               // 当前 HttpContext
App.CreateScope()             // 创建服务作用域
App.GetJobTaskInfoList()      // 定时任务信息

认证授权与 Web 安全基线（Authentication / Web.Security 独立包）

// 1. JWT 认证（配置节 "HzyJwt"：Issuer/Audience/SigningKey/ClockSkewSeconds/RequireHttpsMetadata...）
builder.Services.AddHzyJwtAuthentication(builder.Configuration.GetSection("HzyJwt"));

// 2. 权限授权：未注册 checker 时默认安全拒绝（DenyAll），绝不放行
builder.Services.AddHzyPermissionAuthorization()
    .AddHzyPermissionChecker<MyPermissionChecker>(); // 业务权限校验器（如查角色/菜单/API 权限表）

[RequirePermission("system:user:read")]                    // 单权限
[RequirePermission("system:user:read", "system:user:write")] // 任一命中（OR）
[RequireAllPermissions("a", "b")]                          // 全部满足（AND）
[AllowAnonymous]                                           // 始终优先

// 3. Web 安全基线（CORS/安全头/ForwardedHeaders/限流/健康检查，全部默认关闭，逐项开启）
builder.AddHzyWebSecurity(o =>
{
    o.Cors.Enabled = true;                              // 默认拒绝跨域；必须显式 Origin 白名单
    o.Cors.AllowedOrigins.AddRange(["https://admin.example.com"]);
    o.Headers.Enabled = true;                           // nosniff/XFO/Referrer-Policy/CSP，可按路径排除
    o.ForwardedHeaders.Enabled = true;                  // 反向代理场景：仅信任显式配置的代理网段
    o.ForwardedHeaders.KnownNetworks.Add("10.0.0.0/8");
    o.RateLimiting.Enabled = true;                      // 复用 Core AddFrameworkRateLimiter 的 IP/用户/路径分区
    o.HealthChecks.Enabled = true;                      // /health/live + /health/ready（readiness 按 tag）
});

// 4. 管线（顺序有启动期诊断；重复调用幂等）
app.UseHzyWebSecurity();     // ForwardedHeaders → CORS → 安全头 + 健康检查端点
app.UseHzyAuthentication();
app.UseAuthorization();
app.UseHzyRateLimiter();

// 401/403 统一 JSON（与 ApiResult 同构）：
// {"code":401,"errorMessage":"令牌已过期，请重新登录","data":{"errorCode":"token_expired"}}
// 自有前端协议可通过 HzyJwtOptions.WriteResponseAsync 钩子适配

安全默认：签名校验不可关闭；SigningKey ❤️2 字符或生产环境使用示例密钥 → 启动期快速失败（错误信息不回显密钥）； AllowAnyOrigin + AllowCredentials → 启动期抛异常；ForwardedHeaders 未开启不信任伪造 X-Forwarded-*； 健康检查默认只返回聚合状态；429 限流响应为统一 ApiResult JSON（多实例部署需自行接入分布式限流 provider）。

可观测性基线（HZY.Framework.Observability 独立包）

// 1. 配置节 "HzyObservability"：CorrelationIdHeader/AcceptClientCorrelationId(false)/
//    MaxCorrelationIdLength(64)/WriteToResponseHeader(true)/EnableActivity(true)/EnableLogScope(true)
builder.Services.AddHzyObservability(builder.Configuration);

// 2. 管线：ForwardedHeaders 之后、CORS/Authentication 之前
app.UseHzyObservability();

// 3. 业务/HttpClient 共用同一 ActivitySource
using var activity = HzyObservability.ActivitySource.StartActivity("order-process");

// 4. 可选 OTEL 导出（本包零默认网络副作用）：AddSource(HzyObservability.ActivitySourceName)

更多文档

完整功能说明、数据库 Provider 配置、读写分离、分表、并发控制、服务器监控等，见仓库 README： https://gitee.com/hzy6/HZY.Framework