IGeekFan.FreeKit.Web

ASP.NET Core Web 应用构建块，提供一站式启动配置、认证授权、Swagger、缓存等能力。

功能概览

功能	说明
服务注册	一站式服务注册扩展
应用构建	WebApplicationBuilder 配置扩展
模块注册	IModuleStartup 模块化启动
Autofac	自动 DI 容器注册
Swagger	API 文档与枚举过滤器

快速开始

最小启动

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFreeKitWeb();

var app = builder.Build();
app.UseFreeKitWeb();
app.Run();

完整启动

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFreeKitWebFull();

var app = builder.Build();
app.UseFreeKitWebFull();
app.Run();

一站式启动（推荐）

var builder = WebApplication.CreateBuilder(args);

// 一行代码完成所有配置
builder.UseFreeKit(
    moduleTypes: new Dictionary<string, Type>
    {
        ["identity"] = typeof(IdentityModuleStartup),
        ["cms"] = typeof(CmsKitModuleStartup),
        ["plat"] = typeof(PlatformModuleStartup)
    }
);

var app = builder.Build();
app.UseFreeKitWeb();
app.Run();

服务注册

UseFreeKit

一站式配置入口，自动完成：

功能	说明
Autofac	依赖注入容器
Serilog	日志框架
模块注册	IModuleStartup 自动扫描
Kestrel	大请求体支持

AddFreeKitHost

builder.Services.AddFreeKitHost(builder.Configuration);

自动注册：

AddFreeKitCore() — 核心服务
AddFreeKitService() — 业务服务
AddFreeKitOptional() — 可选服务
AddFreeKitThirdParty() — 第三方集成

AddFreeKitComplete

builder.Services.AddFreeKitComplete(configuration, options =>
{
    options.UseFreeSql = true;
    options.UseRedis = true;
    options.UseSwagger = true;
    options.UseAuth = true;
    options.UseCap = true;
    options.UseMediatR = true;
});

AddFreeKitService

条件注册以下服务：

服务	条件	说明
FreeSql	`UseFreeSql = true`	ORM
Redis + 缓存	`UseRedis = true`	分布式缓存
JWT 认证	`UseAuth = true`	认证授权
MVC + Swagger	`UseSwagger = true`	API 文档
IP2Region	`UseSwagger = true`	IP 地理定位
IP 限流	`UseSwagger = true`	请求限流
健康检查	`UseSwagger = true`	健康端点
本地化	`UseLocalization = true`	多语言
CAP	`UseCap = true`	分布式事件
MediatR	`UseMediatR = true`	中介者模式

AddFreeKitOptional

可选服务：

服务	说明
gRPC	gRPC 服务支持
Encryption	加密中间件

AddFreeKitThirdParty

第三方集成：

服务	说明
飞书 SDK	飞书 API 集成
WebSocket	飞书 WebSocket

认证授权

认证模式

public enum AuthMode
{
    Jwt = 0,        // JWT 自签发
    OpenIddict = 1 // OpenIddict 验证（SSO）
}

配置：

{
  "Security": {
    "AuthMode": 0
  }
}

JWT 配置

{
  "JwtSettings": {
    "Issuer": "https://localhost:5001",
    "Audience": "https://localhost:5001",
    "SecretKey": "your-secret-key-min-32-chars",
    "ExpireMinutes": 60
  }
}

CookieJwtBearerHandler

支持三种 Token 来源：

Query string (?access_token=...) — SignalR Hub
Authorization header — 标准 JWT
Cookie (access_token cookie)

第三方 OAuth

提供商	配置键	启用
GitHub	`Security:GitHub:Enable`	`true`
QQ	`Security:QQ:Enable`	`false`
Gitee	`Security:Gitee:Enable`	`false`
微信	`Security:Weixin:Enable`	`false`
Google	`Security:Google:Enable`	`false`
Microsoft	`Security:Microsoft:Enable`	`false`
KitSSO	`Security:KitSSO:Enable`	`false`

配置示例：

{
  "Security": {
    "GitHub": {
      "Enable": true,
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret"
    }
  }
}

授权策略

// 配置授权策略
services.AddAuthorization(options =>
{
    options.AddPolicy("Bearer", policy =>
    {
        policy.RequireAuthenticatedUser();
        policy.Requirements.Add(new ValidTokenRequirement());
    });
    options.DefaultPolicy = options.GetPolicy("Bearer");
});

Swagger

服务注册

services.AddSwagger(configuration, new List<string> { "Identity", "Platform", "CmsKit" });

Swagger 文档

文档	说明
`v1`	默认 API
`identity`	身份认证
`plat`	工具平台
`cms`	内容管理
`cms-admin`	内容管理后台
`im`	即时通讯
`mall-admin`	电商管理

JWT Bearer 配置

options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
    Description = "JWT authorization",
    Name = "Authorization",
    In = ParameterLocation.Header,
    Type = SecuritySchemeType.ApiKey
});

枚举 Schema 过滤器

自动将枚举的 [Description] 属性添加到 Swagger 文档：

public enum ArticleStatus
{
    [Description("草稿")]
    Draft = 0,
    
    [Description("已发布")]
    Published = 1
}

Swagger UI 配置

app.UseSwaggerUI(c =>
{
    c.RoutePrefix = "swagger";
    c.ConfigObject.DisplayOperationId = true;
    c.SwaggerEndpoint($"{vPath}/swagger/v1/swagger.json", "v1");
    c.SwaggerEndpoint($"{vPath}/swagger/identity/swagger.json", "identity");
    c.SwaggerEndpoint($"{vPath}/swagger/plat/swagger.json", "plat");
    c.SwaggerEndpoint($"{vPath}/swagger/cms/swagger.json", "cms");
});

RapiDoc UI 配置

app.UseRapiDocUI(c =>
{
    c.RoutePrefix = "r";
    c.GenericRapiConfig = new GenericRapiConfig
    {
        RenderStyle = "read",
        Theme = "light",
        ShowMethodInNavBar = "as-colored-text"
    };
});

缓存系统

两种缓存策略

策略	说明
`CacheStrategyType.Redis`	基于 FreeRedis
`CacheStrategyType.Memory`	基于 ConcurrentDictionary

注册缓存

services.AddCacheStrategy(CacheStrategyType.Redis);

AOP 缓存

通过 Cacheable 特性实现方法级缓存：

[Cacheable(CacheKey = "article:{id}", ExpireSeconds = 300)]
public async Task<Article> GetByIdAsync(Guid id)
{
    return await _repository.FindAsync(id);
}

缓存壳

public async Task<Article> GetByIdAsync(Guid id)
{
    return await _cache.CacheShell(
        $"article:{id}",
        async () => await _repository.FindAsync(id),
        expireSeconds: 300
    );
}

中间件管道

完整中间件顺序

app.UsePathBase(new PathString(vPath));
app.UseCors("CorsPolicy");
app.UseStaticFiles(new StaticFileOptions
{
    ContentTypeProvider = provider
});
app.UseDeveloperExceptionPage();
app.UseHttpsRedirection();
app.UseForwardedHeaders();
app.UseSerilogRequestLogging();
app.UseSwagger();
app.UseSwaggerUI();
app.UseRapiDocUI();
app.UseRequestLocalization();
app.UseAuthentication();
app.UseFreeSchedulerUI("job");
app.UseMiddleware<EncryptionMiddleware>();
app.UseCurrentUserAccessor();
app.UseCookiePolicy(new CookiePolicyOptions
{
    MinimumSameSitePolicy = SameSiteMode.Lax
});
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
    endpoints.MapGrpcService<AccessKeyService>();
    endpoints.MapHub<OnlineUserHub>("/hubs/onlineuser");
    endpoints.MapHealthChecks("/health");
});

中间件说明

中间件	说明
`UseCors`	跨域策略
`UseStaticFiles`	静态文件
`UseDeveloperExceptionPage`	开发者异常页
`UseHttpsRedirection`	HTTPS 重定向
`UseForwardedHeaders`	转发头处理
`UseSerilogRequestLogging`	请求日志
`UseSwagger`	Swagger UI
`UseRapiDocUI`	RapiDoc UI
`UseRequestLocalization`	本地化
`UseAuthentication`	认证
`UseFreeSchedulerUI`	任务调度 UI
`EncryptionMiddleware`	响应加密
`UseCurrentUserAccessor`	当前用户
`UseCookiePolicy`	Cookie 策略
`UseRouting`	路由
`UseAuthorization`	授权

端点配置

MVC 控制器

endpoints.MapControllers();

gRPC 服务

endpoints.MapGrpcService<AccessKeyService>();

SignalR Hub

endpoints.MapHub<OnlineUserHub>("/hubs/onlineuser");

健康检查

endpoints.MapHealthChecks("/health", new HealthCheckOptions
{
    Predicate = s => true,
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
});

模块端点

// 自动执行所有模块的 Configure 方法
app.ConfigureModules();

其他功能

IP 地理定位

services.AddIP2Region();

// 使用
public class LocationService
{
    private readonly Searcher _searcher;
    
    public string GetLocation(string ip)
    {
        return _searcher.Btree(ip);
    }
}

FreeSql 配置

services.AddDefaultFreeSql(configuration);

自动配置：

全局过滤器（ISoftDelete、ITenant）
AOP 审计（GUID、敏感词过滤）
SQL 日志
JSON 映射

Redis 客户端

services.AddRedisClient(configuration);

RedisClient 单例
IDistributedCache

CAP 分布式事件

services.AddCap(options =>
{
    options.UseMySql(configuration.GetConnectionString("Default"));
    options.UseRabbitMQ();
});

MediatR 中介者

services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssemblies(assemblies);
});

功能概览​

快速开始​

最小启动​

完整启动​

一站式启动（推荐）​

服务注册​

UseFreeKit​

AddFreeKitHost​

AddFreeKitComplete​

AddFreeKitService​

AddFreeKitOptional​

AddFreeKitThirdParty​

认证授权​

认证模式​

JWT 配置​

CookieJwtBearerHandler​

第三方 OAuth​

授权策略​

Swagger​

服务注册​

Swagger 文档​

JWT Bearer 配置​

枚举 Schema 过滤器​

Swagger UI 配置​

RapiDoc UI 配置​

缓存系统​

两种缓存策略​

注册缓存​

AOP 缓存​

缓存壳​

中间件管道​

完整中间件顺序​

中间件说明​

端点配置​

MVC 控制器​

gRPC 服务​

SignalR Hub​

健康检查​

模块端点​

其他功能​

IP 地理定位​

FreeSql 配置​

Redis 客户端​

CAP 分布式事件​

MediatR 中介者​

相关文档​

功能概览

快速开始

最小启动

完整启动

一站式启动（推荐）

服务注册

UseFreeKit

AddFreeKitHost

AddFreeKitComplete

AddFreeKitService

AddFreeKitOptional

AddFreeKitThirdParty

认证授权

认证模式

JWT 配置

CookieJwtBearerHandler

第三方 OAuth

授权策略

Swagger

服务注册

Swagger 文档

JWT Bearer 配置

枚举 Schema 过滤器

Swagger UI 配置

RapiDoc UI 配置

缓存系统

两种缓存策略

注册缓存

AOP 缓存

缓存壳

中间件管道

完整中间件顺序

中间件说明

端点配置

MVC 控制器

gRPC 服务

SignalR Hub

健康检查

模块端点

其他功能

IP 地理定位

FreeSql 配置

Redis 客户端

CAP 分布式事件

MediatR 中介者

相关文档