refactor: ai+人工重构优化 framework

2026-03-11 12:10:50 +08:00 · 2025-02-23 03:06:06 +08:00
parent f9341fd2ac
commit 3e07ca822a
61 changed files with 2604 additions and 1260 deletions
--- a/Yi.Abp.Net8/framework/Yi.Framework.AspNetCore/Microsoft/AspNetCore/Builder/ApiInfoBuilderExtensions.cs
+++ b/Yi.Abp.Net8/framework/Yi.Framework.AspNetCore/Microsoft/AspNetCore/Builder/ApiInfoBuilderExtensions.cs
@@ -4,13 +4,23 @@ using Yi.Framework.AspNetCore.Microsoft.AspNetCore.Middlewares;

 namespace Yi.Framework.AspNetCore.Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// 提供API信息处理的应用程序构建器扩展方法
+    /// </summary>
    public static class ApiInfoBuilderExtensions
    {
-        public static IApplicationBuilder UseYiApiHandlinge([NotNull] this IApplicationBuilder app)
+        /// <summary>
+        /// 使用Yi框架的API信息处理中间件
+        /// </summary>
+        /// <param name="builder">应用程序构建器实例</param>
+        /// <returns>配置后的应用程序构建器实例</returns>
+        /// <exception cref="ArgumentNullException">当builder参数为null时抛出</exception>
+        public static IApplicationBuilder UseApiInfoHandling([NotNull] this IApplicationBuilder builder)
        {
-            app.UseMiddleware<ApiInfoMiddleware>();
-            return app;
-
+            // 添加API信息处理中间件到请求管道
+            builder.UseMiddleware<ApiInfoMiddleware>();
+            
+            return builder;
        }
    }
 }
--- a/Yi.Abp.Net8/framework/Yi.Framework.AspNetCore/Microsoft/AspNetCore/Builder/SwaggerBuilderExtensons.cs
+++ b/Yi.Abp.Net8/framework/Yi.Framework.AspNetCore/Microsoft/AspNetCore/Builder/SwaggerBuilderExtensons.cs
@@ -5,49 +5,101 @@ using Volo.Abp.AspNetCore.Mvc;

 namespace Yi.Framework.AspNetCore.Microsoft.AspNetCore.Builder
 {
-    public static class SwaggerBuilderExtensons
+    /// <summary>
+    /// Swagger构建器扩展类
+    /// </summary>
+    public static class SwaggerBuilderExtensions
    {
-        public static IApplicationBuilder UseYiSwagger(this IApplicationBuilder app, params SwaggerModel[] swaggerModels)
+        /// <summary>
+        /// 配置并使用Yi框架的Swagger中间件
+        /// </summary>
+        /// <param name="app">应用程序构建器</param>
+        /// <param name="swaggerConfigs">Swagger配置模型数组</param>
+        /// <returns>应用程序构建器</returns>
+        public static IApplicationBuilder UseYiSwagger(
+            this IApplicationBuilder app,
+            params SwaggerConfiguration[] swaggerConfigs)
        {
-            var mvcOptions = app.ApplicationServices.GetRequiredService<IOptions<AbpAspNetCoreMvcOptions>>().Value;
-
-            app.UseSwagger();
-            app.UseSwaggerUI(c =>
+            if (app == null)
            {
-                foreach (var setting in mvcOptions.ConventionalControllers.ConventionalControllerSettings)
+                throw new ArgumentNullException(nameof(app));
+            }
+
+            var mvcOptions = app.ApplicationServices
+                .GetRequiredService<IOptions<AbpAspNetCoreMvcOptions>>()
+                .Value;
+
+            // 启用Swagger中间件
+            app.UseSwagger();
+
+            // 配置SwaggerUI
+            app.UseSwaggerUI(options =>
+            {
+                // 添加约定控制器的Swagger终结点
+                var conventionalSettings = mvcOptions.ConventionalControllers.ConventionalControllerSettings;
+                foreach (var setting in conventionalSettings)
                {
-                    c.SwaggerEndpoint($"/swagger/{setting.RemoteServiceName}/swagger.json", setting.RemoteServiceName);
+                    options.SwaggerEndpoint(
+                        $"/swagger/{setting.RemoteServiceName}/swagger.json",
+                        setting.RemoteServiceName);
                }
-                if (mvcOptions.ConventionalControllers.ConventionalControllerSettings.Count==0&&swaggerModels.Length == 0)
+
+                // 如果没有配置任何终结点，使用默认配置
+                if (!conventionalSettings.Any() && (swaggerConfigs == null || !swaggerConfigs.Any()))
                {
-                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Yi.Framework");
+                    options.SwaggerEndpoint("/swagger/v1/swagger.json", "Yi.Framework");
+                    return;
                }
-                else
+
+                // 添加自定义Swagger配置的终结点
+                if (swaggerConfigs != null)
                {
-                    foreach (var k in swaggerModels)
+                    foreach (var config in swaggerConfigs)
                    {
-                        c.SwaggerEndpoint(k.Url, k.Name);
+                        options.SwaggerEndpoint(config.Url, config.Name);
                    }
                }
-
            });
+
            return app;
        }
-
    }
-    public class SwaggerModel
+
+    /// <summary>
+    /// Swagger配置模型
+    /// </summary>
+    public class SwaggerConfiguration
    {
-        public SwaggerModel(string name)
+        private const string DefaultSwaggerUrl = "/swagger/v1/swagger.json";
+
+        /// <summary>
+        /// Swagger JSON文档的URL
+        /// </summary>
+        public string Url { get; }
+
+        /// <summary>
+        /// Swagger文档的显示名称
+        /// </summary>
+        public string Name { get; }
+
+        /// <summary>
+        /// 使用默认URL创建Swagger配置
+        /// </summary>
+        /// <param name="name">文档显示名称</param>
+        public SwaggerConfiguration(string name)
+            : this(DefaultSwaggerUrl, name)
        {
-            this.Name = name;
-            this.Url = "/swagger/v1/swagger.json";
        }
-        public SwaggerModel(string url, string name)
+
+        /// <summary>
+        /// 创建自定义Swagger配置
+        /// </summary>
+        /// <param name="url">Swagger JSON文档URL</param>
+        /// <param name="name">文档显示名称</param>
+        public SwaggerConfiguration(string url, string name)
        {
-            this.Url = url;
-            this.Name = name;
+            Url = url ?? throw new ArgumentNullException(nameof(url));
+            Name = name ?? throw new ArgumentNullException(nameof(name));
        }
-        public string Url { get; set; }
-        public string Name { get; set; }
    }
 }
--- a/Yi.Abp.Net8/framework/Yi.Framework.AspNetCore/Microsoft/AspNetCore/Middlewares/ApiInfoMiddleware.cs
+++ b/Yi.Abp.Net8/framework/Yi.Framework.AspNetCore/Microsoft/AspNetCore/Middlewares/ApiInfoMiddleware.cs
@@ -1,39 +1,61 @@
 using System.Diagnostics;
-using System.Net.Http;
 using Microsoft.AspNetCore.Http;
-using Microsoft.Extensions.DependencyInjection;
 using Volo.Abp.DependencyInjection;
-using Volo.Abp.Json;
 using Yi.Framework.Core.Extensions;
-using static System.Net.WebRequestMethods;

 namespace Yi.Framework.AspNetCore.Microsoft.AspNetCore.Middlewares
 {
+    /// <summary>
+    /// API响应信息处理中间件
+    /// 主要用于处理特定文件类型的响应头信息
+    /// </summary>
    [DebuggerStepThrough]
    public class ApiInfoMiddleware : IMiddleware, ITransientDependency
    {
-       
+        /// <summary>
+        /// 处理HTTP请求的中间件方法
+        /// </summary>
+        /// <param name="context">HTTP上下文</param>
+        /// <param name="next">请求处理委托</param>
+        /// <returns>异步任务</returns>
        public async Task InvokeAsync(HttpContext context, RequestDelegate next)
        {
-            context.Response.OnStarting([DebuggerStepThrough] () =>
+            // 在响应开始时处理文件下载相关的响应头
+            context.Response.OnStarting(() =>
            {
-                if (context.Response.StatusCode == StatusCodes.Status200OK
-                && context.Response.Headers["Content-Type"].ToString() == "application/vnd.ms-excel")
-                {
-                    context.FileAttachmentHandle($"{DateTime.Now.ToString("yyyy-MM-dd_HH-mm-ss")}.xlsx");
-                }
-                if (context.Response.StatusCode == StatusCodes.Status200OK &&
-                context.Response.Headers["Content-Type"].ToString() == "application/x-zip-compressed")
-                {
-                    context.FileAttachmentHandle($"{DateTime.Now.ToString("yyyy-MM-dd_HH-mm-ss")}.zip");
-                }
+                HandleFileDownloadResponse(context);
                return Task.CompletedTask;
            });

+            // 继续处理管道中的下一个中间件
            await next(context);
+        }

+        /// <summary>
+        /// 处理文件下载响应的响应头信息
+        /// </summary>
+        /// <param name="context">HTTP上下文</param>
+        private static void HandleFileDownloadResponse(HttpContext context)
+        {
+            // 仅处理状态码为200的响应
+            if (context.Response.StatusCode != StatusCodes.Status200OK)
+            {
+                return;
+            }

+            var contentType = context.Response.Headers["Content-Type"].ToString();
+            var timestamp = DateTime.Now.ToString("yyyy-MM-dd_HH-mm-ss");

+            // 处理Excel文件下载
+            if (contentType == "application/vnd.ms-excel")
+            {
+                context.FileAttachmentHandle($"{timestamp}.xlsx");
+            }
+            // 处理ZIP文件下载
+            else if (contentType == "application/x-zip-compressed")
+            {
+                context.FileAttachmentHandle($"{timestamp}.zip");
+            }
        }
    }
 }
--- a/Yi.Abp.Net8/framework/Yi.Framework.AspNetCore/Microsoft/Extensions/DependencyInjection/SwaggerAddExtensions.cs
+++ b/Yi.Abp.Net8/framework/Yi.Framework.AspNetCore/Microsoft/Extensions/DependencyInjection/SwaggerAddExtensions.cs
@@ -9,129 +9,193 @@ using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
 using Volo.Abp.AspNetCore.Mvc;
+using Volo.Abp.AspNetCore.Mvc.Conventions;
 using Volo.Abp.DependencyInjection;
 using Volo.Abp.Options;

 namespace Yi.Framework.AspNetCore.Microsoft.Extensions.DependencyInjection
 {
+    /// <summary>
+    /// Swagger生成器扩展类
+    /// </summary>
    public static class SwaggerAddExtensions
    {
-        public static IServiceCollection AddYiSwaggerGen<Program>(this IServiceCollection services,
-            Action<SwaggerGenOptions>? action = null)
+        /// <summary>
+        /// 添加Yi框架的Swagger生成器服务
+        /// </summary>
+        /// <typeparam name="TProgram">程序入口类型</typeparam>
+        /// <param name="services">服务集合</param>
+        /// <param name="setupAction">自定义配置动作</param>
+        /// <returns>服务集合</returns>
+        public static IServiceCollection AddYiSwaggerGen<TProgram>(
+            this IServiceCollection services,
+            Action<SwaggerGenOptions>? setupAction = null)
        {
+            // 获取MVC配置选项
            var mvcOptions = services.GetPreConfigureActions<AbpAspNetCoreMvcOptions>().Configure();
            
-            var mvcSettings =
-                mvcOptions.ConventionalControllers.ConventionalControllerSettings.DistinctBy(x => x.RemoteServiceName);
-
+            // 获取并去重远程服务名称
+            var remoteServiceSettings = mvcOptions.ConventionalControllers
+                .ConventionalControllerSettings
+                .DistinctBy(x => x.RemoteServiceName);

            services.AddAbpSwaggerGen(
                options =>
                {
-                    if (action is not null)
-                    {
-                        action.Invoke(options);
-                    }
+                    // 应用外部配置
+                    setupAction?.Invoke(options);

-                    // 配置分组,还需要去重,支持重写,如果外部传入后，将以外部为准
-                    foreach (var setting in mvcSettings.OrderBy(x => x.RemoteServiceName))
-                    {
-                        if (!options.SwaggerGeneratorOptions.SwaggerDocs.ContainsKey(setting.RemoteServiceName))
-                        {
-                            options.SwaggerDoc(setting.RemoteServiceName,
-                                new OpenApiInfo { Title = setting.RemoteServiceName, Version = "v1" });
-                        }
-                    }
+                    // 配置API文档分组
+                    ConfigureApiGroups(options, remoteServiceSettings);

-                    // 根据分组名称过滤 API 文档
-                    options.DocInclusionPredicate((docName, apiDesc) =>
-                    {
-                        if (apiDesc.ActionDescriptor is ControllerActionDescriptor controllerActionDescriptor)
-                        {
-                            var settingOrNull = mvcSettings
-                                .Where(x => x.Assembly == controllerActionDescriptor.ControllerTypeInfo.Assembly)
-                                .FirstOrDefault();
-                            if (settingOrNull is not null)
-                            {
-                                return docName == settingOrNull.RemoteServiceName;
-                            }
-                        }
-
-                        return false;
-                    });
+                    // 配置API文档过滤器
+                    ConfigureApiFilter(options, remoteServiceSettings);

+                    // 配置Schema ID生成规则
                    options.CustomSchemaIds(type => type.FullName);
-                    var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
-                    if (basePath is not null)
-                    {
-                        foreach (var item in Directory.GetFiles(basePath, "*.xml"))
-                        {
-                            options.IncludeXmlComments(item, true);
-                        }
-                    }

-                    options.AddSecurityDefinition("JwtBearer", new OpenApiSecurityScheme()
-                    {
-                        Description = "直接输入Token即可",
-                        Name = "Authorization",
-                        In = ParameterLocation.Header,
-                        Type = SecuritySchemeType.Http,
-                        Scheme = "bearer"
-                    });
-                    var scheme = new OpenApiSecurityScheme()
-                    {
-                        Reference = new OpenApiReference() { Type = ReferenceType.SecurityScheme, Id = "JwtBearer" }
-                    };
-                    options.AddSecurityRequirement(new OpenApiSecurityRequirement()
-                    {
-                        [scheme] = new string[0]
-                    });
+                    // 包含XML注释文档
+                    IncludeXmlComments<TProgram>(options);

-                    options.OperationFilter<AddRequiredHeaderParameter>();
-                    options.SchemaFilter<EnumSchemaFilter>();
+                    // 配置JWT认证
+                    ConfigureJwtAuthentication(options);
+
+                    // 添加自定义过滤器
+                    ConfigureCustomFilters(options);
                }
            );

-
            return services;
        }
+
+        /// <summary>
+        /// 配置API分组
+        /// </summary>
+        private static void ConfigureApiGroups(
+            SwaggerGenOptions options, 
+            IEnumerable<ConventionalControllerSetting> settings)
+        {
+            foreach (var setting in settings.OrderBy(x => x.RemoteServiceName))
+            {
+                if (!options.SwaggerGeneratorOptions.SwaggerDocs.ContainsKey(setting.RemoteServiceName))
+                {
+                    options.SwaggerDoc(setting.RemoteServiceName, new OpenApiInfo 
+                    { 
+                        Title = setting.RemoteServiceName, 
+                        Version = "v1" 
+                    });
+                }
+            }
+        }
+
+        /// <summary>
+        /// 配置API文档过滤器
+        /// </summary>
+        private static void ConfigureApiFilter(
+            SwaggerGenOptions options,
+            IEnumerable<ConventionalControllerSetting> settings)
+        {
+            options.DocInclusionPredicate((docName, apiDesc) =>
+            {
+                if (apiDesc.ActionDescriptor is ControllerActionDescriptor controllerDesc)
+                {
+                    var matchedSetting = settings
+                        .FirstOrDefault(x => x.Assembly == controllerDesc.ControllerTypeInfo.Assembly);
+                    return matchedSetting?.RemoteServiceName == docName;
+                }
+                return false;
+            });
+        }
+
+        /// <summary>
+        /// 包含XML注释文档
+        /// </summary>
+        private static void IncludeXmlComments<TProgram>(SwaggerGenOptions options)
+        {
+            var basePath = Path.GetDirectoryName(typeof(TProgram).Assembly.Location);
+            if (basePath is not null)
+            {
+                foreach (var xmlFile in Directory.GetFiles(basePath, "*.xml"))
+                {
+                    options.IncludeXmlComments(xmlFile, true);
+                }
+            }
+        }
+
+        /// <summary>
+        /// 配置JWT认证
+        /// </summary>
+        private static void ConfigureJwtAuthentication(SwaggerGenOptions options)
+        {
+            options.AddSecurityDefinition("JwtBearer", new OpenApiSecurityScheme
+            {
+                Description = "请在此输入JWT Token",
+                Name = "Authorization",
+                In = ParameterLocation.Header,
+                Type = SecuritySchemeType.Http,
+                Scheme = "bearer"
+            });
+
+            var scheme = new OpenApiSecurityScheme
+            {
+                Reference = new OpenApiReference 
+                { 
+                    Type = ReferenceType.SecurityScheme, 
+                    Id = "JwtBearer" 
+                }
+            };
+
+            options.AddSecurityRequirement(new OpenApiSecurityRequirement
+            {
+                [scheme] = Array.Empty<string>()
+            });
+        }
+
+        /// <summary>
+        /// 配置自定义过滤器
+        /// </summary>
+        private static void ConfigureCustomFilters(SwaggerGenOptions options)
+        {
+            options.OperationFilter<TenantHeaderOperationFilter>();
+            options.SchemaFilter<EnumSchemaFilter>();
+        }
    }

-
    /// <summary>
-    /// Swagger文档枚举字段显示枚举属性和枚举值,以及枚举描述
+    /// Swagger文档枚举字段显示过滤器
    /// </summary>
    public class EnumSchemaFilter : ISchemaFilter
    {
        /// <summary>
-        /// 实现接口
+        /// 应用枚举架构过滤器
        /// </summary>
-        /// <param name="model"></param>
-        /// <param name="context"></param>
-        public void Apply(OpenApiSchema model, SchemaFilterContext context)
+        /// <param name="schema">OpenAPI架构</param>
+        /// <param name="context">架构过滤器上下文</param>
+        public void Apply(OpenApiSchema schema, SchemaFilterContext context)
        {
-            if (context.Type.IsEnum)
+            if (!context.Type.IsEnum) return;
+
+            schema.Enum.Clear();
+            schema.Type = "string";
+            schema.Format = null;
+
+            var enumDescriptions = new StringBuilder();
+            foreach (var enumName in Enum.GetNames(context.Type))
            {
-                model.Enum.Clear();
-                model.Type = "string";
-                model.Format = null;
+                var enumValue = (Enum)Enum.Parse(context.Type, enumName);
+                var description = GetEnumDescription(enumValue);
+                var enumIntValue = Convert.ToInt64(enumValue);

-
-                StringBuilder stringBuilder = new StringBuilder();
-                Enum.GetNames(context.Type)
-                    .ToList()
-                    .ForEach(name =>
-                    {
-                        Enum e = (Enum)Enum.Parse(context.Type, name);
-                        var descrptionOrNull = GetEnumDescription(e);
-                        model.Enum.Add(new OpenApiString(name));
-                        stringBuilder.Append(
-                            $"【枚举：{name}{(descrptionOrNull is null ? string.Empty : $"({descrptionOrNull})")}={Convert.ToInt64(Enum.Parse(context.Type, name))}】<br />");
-                    });
-                model.Description = stringBuilder.ToString();
+                schema.Enum.Add(new OpenApiString(enumName));
+                enumDescriptions.AppendLine(
+                    $"【枚举：{enumName}{(description is null ? string.Empty : $"({description})")}={enumIntValue}】");
            }
+            schema.Description = enumDescriptions.ToString();
        }

+        /// <summary>
+        /// 获取枚举描述特性值
+        /// </summary>
        private static string? GetEnumDescription(Enum value)
        {
            var fieldInfo = value.GetType().GetField(value.ToString());
@@ -140,22 +204,30 @@ namespace Yi.Framework.AspNetCore.Microsoft.Extensions.DependencyInjection
        }
    }

-
-    public class AddRequiredHeaderParameter : IOperationFilter
+    /// <summary>
+    /// 租户头部参数过滤器
+    /// </summary>
+    public class TenantHeaderOperationFilter : IOperationFilter
    {
-        public static string HeaderKey { get; set; } = "__tenant";
+        /// <summary>
+        /// 租户标识键名
+        /// </summary>
+        private const string TenantHeaderKey = "__tenant";

+        /// <summary>
+        /// 应用租户头部参数过滤器
+        /// </summary>
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
-            if (operation.Parameters == null)
-                operation.Parameters = new List<OpenApiParameter>();
+            operation.Parameters ??= new List<OpenApiParameter>();
+            
            operation.Parameters.Add(new OpenApiParameter
            {
-                Name = HeaderKey,
+                Name = TenantHeaderKey,
                In = ParameterLocation.Header,
                Required = false,
                AllowEmptyValue = true,
-                Description = "租户id或者租户名称（可空为默认租户）"
+                Description = "租户ID或租户名称（留空表示默认租户）"
            });
        }
    }