# Gears **Repository Path**: chao_yang_wang12138_admin_admin/gears ## Basic Information - **Project Name**: Gears - **Description**: .Net齿轮：Gears 是一个轻量级的模块化 Web 应用框架，旨在帮助开发者快速构建可扩展的应用程序。它采用依赖注入模式，提供了灵活的配置管理和模块化支持。 - **Primary Language**: C# - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-03 - **Last Updated**: 2026-04-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Gears 模块化应用程序框架 ## 简介 Gears 是一个轻量级的模块化 Web 应用程序框架，基于 .NET 平台开发。它采用现代化的依赖注入模式，为开发者提供了一套完整的工具集，帮助快速构建可扩展、易维护的分布式应用程序。该框架设计简洁但功能强大，适用于各种规模的项目开发。 框架的核心设计理念是模块化与解耦。通过定义清晰的接口和规范，开发者可以将应用程序拆分为独立的模块，每个模块负责特定的功能域。模块之间通过依赖注入进行通信，降低了组件间的耦合度，提高了代码的可测试性和可维护性。Gears 框架不仅提供了基础的依赖注入功能，还包含了配置管理、HTTP 上下文访问等实用功能，大大简化了企业级应用的开发流程。 ## 核心功能 ### 模块化架构 Gears 框架的模块化设计是其最具特色的功能之一。框架通过 `IGearsModule` 接口定义了一套标准的模块规范，开发者只需实现该接口即可创建自定义模块。每个模块可以独立配置自己的服务注册和中间件设置，实现了关注点分离的目标。模块化架构支持按需加载，开发者可以根据应用程序的实际需求启用或禁用特定模块，这种灵活性使得框架能够适应各种复杂的业务场景。此外，框架还支持模块间的依赖管理，确保模块按照正确的顺序进行初始化和配置。 模块化设计带来的另一个重要优势是代码的可重用性。开发者可以将常用的功能封装为独立的模块，在不同的项目中复用这些模块，从而提高开发效率。例如，可以将身份认证、日志记录、缓存管理等通用功能封装为模块，供多个项目共享使用。这种设计模式在大型团队协作开发中尤为重要，它使得团队成员可以并行开发不同的模块，最后通过框架将它们整合在一起。 ### 依赖注入 Gears 内置了功能完整的依赖注入容器，基于 Microsoft.Extensions.DependencyInjection 构建。框架提供了服务注册扩展方法 `GearsInject`，简化了服务的注册和管理过程。开发者可以使用多种生命周期模式注册服务，包括瞬态（Transient）、作用域（Scoped）和单例（Singleton），满足不同场景的需求。框架自动管理服务的创建和销毁，开发者无需手动处理复杂的对象生命周期问题。依赖注入容器还支持构造函数注入、属性注入等多种注入方式，使得代码更加简洁和易于测试。 框架的依赖注入系统与 .NET 生态系统的其他组件完美兼容。开发者可以直接使用 Microsoft 提供的各种扩展库，如 Entity Framework Core、Identity 等，无需担心集成问题。Gears 在此基础上提供了便捷的静态访问类 `GearsApp`，通过它可以轻松获取已注册的服务实例，无需在每个类中显式注入依赖。这种设计在某些场景下特别有用，例如在静态方法或全局访问点获取服务时。 ### 配置管理 Gears 提供了统一且灵活的配置管理机制。框架集成了 .NET 的配置系统，支持多种配置源，包括 JSON 文件、环境变量、命令行参数等。开发者可以使用标准的 IConfiguration 接口访问配置，也可以使用 `GearsApp` 提供的扩展方法获取配置值。框架还支持强类型配置绑定，开发者可以将配置绑定到具体的类实例中，获得编译时类型检查的好处。这种设计使得配置管理更加安全和可靠，减少了运行时错误的可能性。 配置系统还支持配置节的层次结构，开发者可以按照逻辑功能对配置进行分组。框架在模块初始化时，会将当前模块的配置节传递给模块的 ConfigureServices 方法，模块可以读取自己专属的配置，无需关心其他模块的配置细节。这种设计实现了配置的关注点分离，使得配置文件更加清晰和易于维护。框架还支持配置的热重载，在开发环境下修改配置文件后，无需重启应用程序即可生效。 ### HTTP 上下文访问 Web 应用程序经常需要访问当前的 HTTP 请求上下文，Gears 框架为此提供了便捷的访问方式。通过 `GearsApp.HttpContext` 静态属性，开发者可以随时获取当前的 HttpContext 实例，无论是在控制器中还是在服务类中。这种统一访问方式简化了代码，避免了通过层层传递获取上下文对象的繁琐操作。框架在内部使用 IHttpContextAccessor 服务来提供此功能，确保了与 ASP.NET Core 中间件管道的正确集成。 HTTP 上下文访问功能在实现横切关注点时特别有用。例如，在记录请求日志时需要获取请求的 URL、方法、用户信息等；在实现用户上下文时需要获取当前用户身份；在处理多语言支持时需要获取请求的 Accept-Language 头。通过 Gears 框架，这些信息都可以轻松获取。框架还确保了 HttpContext 的正确作用域，在异步操作中上下文对象能够正确传递，避免了常见的"此异步操作当前没有上下文"错误。 ## 项目结构 ``` Gears/ ├── Gears.Core/ # 核心框架模块 │ ├── GearsApp.cs # 应用静态入口和服务访问类 │ ├── GearsBoots.cs # 模块注册引导类 │ ├── GearsInject.cs # 服务注册扩展方法 │ └── IGearsModule.cs # 模块接口定义 └── Gears.Web/ # Web 应用程序模块 ├── Program.cs # 应用启动入口点 ├── OrderEmailHandler.cs # 消息队列处理器示例 ├── Gears.Web.http # HTTP 请求文件 ├── appsettings.json # 应用程序配置文件 └── Properties/ # 启动配置目录 └── launchSettings.json # 启动设置文件 ``` Gears.Core 是框架的核心库，包含了所有基础设施代码。GearsApp 类提供了静态访问点，开发者可以通过它获取服务实例、配置值和 HTTP 上下文。GearsBoots 类负责模块的注册和配置管理，它记录了已启用的模块列表，并提供了链式 API 用于配置。GearsInject 类包含了扩展方法，用于将框架服务注册到 DI 容器中。IGearsModule 接口是所有模块必须实现的接口，它定义了模块生命周期的两个关键方法。 Gears.Web 是一个示例 Web 应用程序，展示了如何在实际项目中使用 Gears 框架。Program.cs 是标准的 ASP.NET Core 启动点，通过调用 GearsInject 的扩展方法完成框架初始化。OrderEmailHandler 是一个消息处理器示例，展示了如何使用消息队列功能。这些示例代码为开发者提供了参考，帮助他们快速上手框架的使用。 当前示例宿主已接入 `Email`、`SqlSugar`、`Log`、`Http`、`Encrypt`、`Queue` 六个模块，并暴露以下演示接口： - `/weatherforecast` - `/email` - `/log/demo` - `/sqlsugar/config` - `/sqlsugar/demo` - `/sqlsugar/demo/{tenantId}` - `POST /sqlsugar/demo` - `/md5` - `/queue` ## 快速开始 ### 环境要求 在开始使用 Gears 框架之前，请确保开发环境满足以下要求。首先，需要安装 .NET SDK（软件开发工具包），建议使用 .NET 6.0 或更高版本。可以通过在终端运行 `dotnet --version` 命令来检查已安装的 SDK 版本。其次，建议使用 Visual Studio 2022 或 Visual Studio Code 作为开发环境，它们都提供了良好的 .NET 开发支持。最后，确保已安装 Git 工具，用于克隆和管理项目代码。 对于生产环境部署，Gears 框架没有特殊的运行时要求，它可以在任何支持 .NET 的平台上运行，包括 Windows、Linux 和 macOS。部署时只需发布应用程序，框架的所有依赖都会包含在发布输出中。如果使用容器化部署，可以基于官方的 .NET Docker 镜像构建应用程序镜像，部署过程与普通 ASP.NET Core 应用程序完全相同。 ### 安装与克隆 获取 Gears 框架源码的第一步是克隆代码仓库。打开终端或命令提示符，执行以下 Git 命令将仓库克隆到本地： ```bash git clone https://gitee.com/chao_yang_wang12138_admin_admin/gears.git cd gears ``` 克隆完成后，可以在本地目录中看到整个项目结构。如果计划为框架贡献代码，建议先 fork 仓库，然后在克隆的仓库中添加 fork 的远程地址。项目的目录结构符合标准的 .NET 解决方案布局，可以使用任何 .NET IDE 打开 Gears.slnx 解决方案文件查看和编辑代码。对于命令行用户，可以使用 `dotnet restore` 命令还原所有依赖包，使用 `dotnet build` 命令编译项目。 如果只是想在项目中使用 Gears 框架的某些组件，也可以直接将 Gears.Core 项目添加到现有解决方案中。框架的模块化设计允许开发者灵活选择需要的组件，而不必引入整个框架。这种灵活性使得 Gears 可以渐进式地引入到现有项目中，降低了技术迁移的风险和成本。 ### 创建 Web 应用程序 使用 Gears 框架创建新的 Web 应用程序非常简单。首先，使用 dotnet new 命令创建一个基本的 ASP.NET Core Web 应用程序项目： ```bash dotnet new webapi -n MyGearsApp cd MyGearsApp ``` 创建项目后，需要添加对 Gears.Core 项目的引用。如果 Gears 框架在独立的目录中，可以使用项目引用命令添加依赖： ```bash dotnet add reference ../Gears/Gears.Core/Gears.Core.csproj ``` 或者，如果希望将 Gears 框架发布为 NuGet 包，可以先在 Gears.Core 目录中执行打包命令，然后在项目中通过包引用方式添加： ```bash dotnet pack -c Release dotnet add package Gears.Core --source ./bin/Release/ ``` 完成项目配置后，修改 Program.cs 文件以集成 Gears 框架。框架会自动配置依赖注入容器和中间件管道，开发者只需调用相应的扩展方法即可完成集成。这种设计使得框架的上手成本非常低，开发者可以在几分钟内完成框架的集成并开始开发业务功能。 ## 使用方法 ### 注册 Gears 服务 在应用程序启动时，需要将 Gears 框架注册到依赖注入容器中。这一步通过调用 `AddGears` 扩展方法完成，它位于 `Gears.Core` 命名空间中。该方法接受 IServiceCollection 和 IConfiguration 两个参数，同时支持通过委托方式配置模块注册行为。以下是一个完整的启动配置示例： ```csharp using Gears.Core; var builder = WebApplication.CreateBuilder(args); // 注册 Gears 框架服务 builder.Services.AddGears(builder.Configuration, gears => { // 可选：配置模块注册行为 gears.UseModule("MyCustomModule"); gears.UseModules("ModuleA", "ModuleB", "ModuleC"); gears.UseModule("ModuleD", "ModuleA", "ModuleB"); }); var app = builder.Build(); // 使用 Gears 中间件 app.UseGears(); // 配置其他中间件和端点 app.MapGet("/", () => "Hello Gears!"); app.Run(); ``` `AddGears` 方法内部执行了多个重要的初始化操作。首先，它创建并配置了 GearsBoots 实例，用于管理模块的注册。其次，它注册了框架所需的基础服务，包括 IHttpContextAccessor、ILoggerFactory 等。接下来，它扫描已注册的模块程序集，调用每个模块的 ConfigureServices 方法完成服务注册。最后，它保存配置和 IServiceProvider 的引用，供后续通过 GearsApp 静态类访问。 `UseGears` 当前并不是一个承载业务逻辑的中间件。按照当前代码实现，它主要负责在应用启动完成后保存根服务提供者，以便 `GearsApp` 可以在静态访问场景下解析服务和获取当前 `HttpContext`。`IHttpContextAccessor` 的注册发生在 `AddGears(...)` 阶段，而不是 `UseGears()` 阶段。因此当前建议将它理解为“初始化 GearsApp 访问入口”的应用启动步骤，而不是模块级中间件机制。 ### 创建自定义模块 模块是 Gears 框架的核心概念，每个模块都应该实现 `IGearsModule` 接口。按照当前仓库实现，模块生命周期目前只有 `ConfigureServices(IServiceCollection, IConfiguration)` 一个入口，用于注册模块所需服务；仓库中尚未实现模块级 `Configure(IApplicationBuilder, IWebHostEnvironment)` 生命周期。因此当前应将模块理解为“服务注册单元”，而不是已经具备完整中间件生命周期的模块系统。下面示例使用当前真实接口形式： ```csharp using Gears.Core; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Configuration; public class CustomModule : IGearsModule { public void ConfigureServices(IServiceCollection services, IConfiguration configuration) { // 注册业务服务 services.AddSingleton(); services.AddScoped(); // 配置选项模式 services.Configure(configuration.GetSection("OrderSettings")); // 注册消息处理器 services.AddSingleton, OrderEmailHandler>(); } } ``` 模块设计应该遵循单一职责原则，每个模块只负责一个特定的功能域。这种设计使得模块高度内聚，易于测试和维护。模块之间如果有依赖关系，可以通过依赖注入解决。当前框架能够保证模块按白名单顺序完成 `ConfigureServices(...)` 注册，但还没有实现模块级中间件或模块级路由配置阶段。建议在模块文档中注明模块依赖关系，帮助使用者正确配置模块加载顺序。 当前版本还引入了轻量的模块元数据和依赖校验机制：如果模块实现 `IGearsModuleWithMetadata`，就可以声明模块名称、展示名称、描述、配置节和依赖模块列表。与此同时，`GearsBoots.UseModule(...)` 也支持在启用模块时显式声明依赖项。`AddGears(...)` 在服务注册前会校验两件事：一是依赖模块是否已经启用，二是依赖模块是否已经排在当前模块之前完成注册。如果不满足条件，会直接抛出明确异常，而不是静默继续执行。 一个符合当前实现风格的元数据示例如下： ```csharp using Gears.Core; using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection; public class CustomModule : IGearsModuleWithMetadata { public GearsModuleMetadata Metadata => new() { Name = "MyCustomModule", DisplayName = "My Custom Module", Description = "示例模块", ConfigurationSection = "Gears:MyCustomModule", Dependencies = new[] { "Gears.Log", "Gears.Http" } }; public void ConfigureServices(IServiceCollection services, IConfiguration configuration) { services.AddSingleton(); } } ``` 如果宿主侧希望显式声明依赖顺序，也可以这样写： ```csharp builder.Services.AddGears(builder.Configuration, gears => { gears.UseLogModule(); gears.UseHttpModule(); gears.UseModule("MyCustomModule", "Gears.Log", "Gears.Http"); }); ``` 模块程序集的加载是一个重要的实现细节。Gears 框架使用程序集名称来加载模块，默认情况下会加载所有引用的程序集。如果模块在独立的程序集中，需要确保在 UseModules 方法中指定正确的程序集名称。程序集名称是区分大小写的，在 Linux 系统上尤其需要注意这一点。框架使用 System.Reflection.Assembly.Load 方法加载程序集，因此可以使用完整的程序集显示名称或简短名称。 ### 获取服务实例 Gears 框架提供了便捷的静态方法来获取已注册的服务实例。`GearsApp.GetService` 方法返回指定类型的服务的实例，如果服务未注册则返回 null。`GearsApp.GetRequiredService` 方法在服务未注册时会抛出 InvalidOperationException 异常，适用于必须存在才能正常工作的服务。以下是多种使用场景的示例： ```csharp using Gears.Core; // 尝试获取可选服务（可能返回 null） var logger = GearsApp.GetService>(); // 获取必需服务（未注册时抛出异常） var orderService = GearsApp.GetRequiredService(); // 在服务类中使用依赖注入 public class MyService { private readonly IOrderRepository _orderRepository; public MyService() { _orderRepository = GearsApp.GetRequiredService(); } public async Task ProcessOrderAsync(string orderId) { var order = await _orderRepository.GetByIdAsync(orderId); // 处理订单逻辑 } } ``` 虽然 Gears 提供了静态访问服务的方式，但在实际开发中仍然推荐优先使用构造函数注入。这种方式更加显式，依赖关系一目了然，也更容易进行单元测试。静态访问方式适合在静态类、扩展方法或无法直接注入依赖的场景中使用。需要注意的是，在请求处理过程中使用 GearsApp 访问服务是安全的，但如果在应用程序启动完成之前调用，可能无法获取正确的服务实例。 框架还支持获取泛型服务实例，这对于使用泛型仓储模式或策略模式的代码特别有用。可以使用相同的语法获取任意已注册的泛型服务，如 `GearsApp.GetService>()`。泛型服务的注册和解析遵循与普通服务相同的规则，但需要注意泛型类型定义必须完全匹配。 ### 获取应用程序配置 Gears 框架的配置系统支持多种获取配置值的方式。对于简单的字符串配置，可以使用 `GetConfig(string key)` 方法；对于复杂的配置对象，可以使用 `GetConfig(string key)` 方法进行强类型绑定。以下是配置获取的详细示例： ```csharp using Gears.Core; // 获取字符串配置值 var apiKey = GearsApp.GetConfig("ApiKey"); var databaseConnection = GearsApp.GetConfig("Database:ConnectionString"); // 获取强类型配置对象 var settings = GearsApp.GetConfig("ApplicationSettings"); // 使用配置节访问子配置 var cacheSettings = GearsApp.GetConfig("Cache"); // 在配置类中使用选项模式 public class ApplicationSettings { public string ApplicationName { get; set; } = string.Empty; public int MaxCacheSize { get; set; } public bool EnableLogging { get; set; } } // 通过 IOptions 获取配置 public class SettingsService { private readonly ApplicationSettings _settings; public SettingsService(IOptions options) { _settings = options.Value; } public string GetApplicationName() => _settings.ApplicationName; } ``` 配置系统与 Microsoft 的配置体系完全兼容，因此可以使用标准的配置绑定语法。选项模式（Options Pattern）是推荐的做法，它支持配置更改通知和配置验证。在模块的 ConfigureServices 方法中，使用 services.Configure(configuration.GetSection("SectionName")) 绑定配置节，然后在需要的地方通过 IOptions 或 IOptionsSnapshot 注入配置对象。IOptions 是单例，值在应用程序启动时固定；IOptionsSnapshot 是作用域对象，在每个请求中读取最新配置。 对于需要动态更新的配置，可以使用 IOptionsMonitor 接口，它支持配置热重载。当 JSON 配置文件在开发环境中修改时，IOptionsMonitor 会自动通知使用方配置已更改。这种机制对于实现配置驱动的功能特别有用，例如功能开关（Feature Flags）或动态阈值调整。 ## API 参考 ### GearsApp 静态类 GearsApp 是框架的主要入口类，提供了访问核心功能的静态方法和属性。该类在 Gears.Core 命名空间中定义，无需实例化即可使用。所有方法都设计为线程安全，可以在多线程环境中使用。以下是 GearsApp 类的完整 API 说明： **Configuration 属性** — 获取应用程序的配置对象。通过此属性可以访问完整的配置树，使用标准的配置 API 查询配置值。该属性在框架初始化后设置，在之前访问会返回 null。 **RootServices 属性** — 获取根服务提供器。这是应用程序的顶层 IServiceProvider，所有注册的服务都可以通过它或其子作用域获取。该属性主要用于框架内部目的，普通开发者应使用 GetService 方法访问服务。 **HttpContext 属性** — 获取当前 HTTP 请求上下文。如果当前没有 HTTP 请求上下文（例如在后台线程中），该属性返回 null。在 MVC 控制器或中间件中，该属性总是返回有效的 HttpContext 对象。 **GetService() 方法** — 泛型方法，返回指定类型的服务实例。如果服务未注册，返回该类型的默认值（null 或 default）。该方法不抛出异常，适合在不确定服务是否已注册时使用。 **GetRequiredService() 方法** — 泛型方法，返回指定类型的服务实例。如果服务未注册，抛出 InvalidOperationException 异常。使用此方法表示服务是必需的，未注册表示应用程序配置错误。 **GetConfig(string key) 方法** — 根据配置键获取字符串配置值。如果键不存在或值为空，返回 null。该方法支持配置节的点号分隔语法，如 "Section:SubSection:Key"。 **GetConfig(string key) 方法** — 泛型方法，将指定配置节绑定到指定类型并返回实例。如果绑定失败或配置节不存在，返回 null。该方法内部使用 IConfiguration.Get 扩展方法。 ### GearsBoots 类 GearsBoots 类负责模块的注册和配置管理，是框架模块化功能的核心实现。每个 GearsBoots 实例关联一个 IServiceCollection，用于收集模块注册的服务。该类提供了流畅的 API，支持链式调用来配置模块加载行为： **Services 属性** — 获取关联的服务集合。所有通过 ConfigureServices 方法注册的服务都会添加到此集合中。此属性为只读，无法直接替换服务集合。 **EnabledModules 属性** — 获取已启用的模块名称列表。此列表在 UseModule 或 UseModules 方法调用后填充，内部用于跟踪哪些模块已被注册。该属性主要用于调试和诊断目的。 **GearsBoots 构造函数** — 接受一个 IServiceCollection 参数，创建新的 GearsBoots 实例并关联服务集合。框架在调用 AddGears 时会自动创建此实例。 **UseModule(string assemblyName) 方法** — 启用单个模块。参数是模块程序集的显示名称。该方法返回当前的 GearsBoots 实例，支持链式调用。模块程序集必须是已加载的程序集或可从引用的程序集中解析。 **UseModules(params string[] assemblyNames) 方法** — 启用多个模块。参数是可变数量的程序集名称。该方法是 UseModule 的便捷封装，适合一次性启用多个已知模块。传入的程序集名称必须是有效的程序集名称。 **UseModule(string assemblyName, params string[] dependencies) 方法** — 启用单个模块并显式声明它依赖哪些模块。当前实现会在注册阶段验证这些依赖是否已启用，以及是否已排在前面完成注册。 **IGearsModuleWithMetadata 接口** — `IGearsModule` 的扩展接口。实现该接口后，模块可以暴露 `GearsModuleMetadata`，用于声明模块名称、展示名称、描述、配置节和依赖模块列表。当前框架会优先使用这里的依赖信息做校验。 ### GearsInject 静态类 GearsInject 类包含了框架的扩展方法，用于将 Gears 框架集成到标准 .NET 应用程序中。这些方法遵循 .NET 扩展方法的约定，提供了声明式的配置方式： **AddGears(this IServiceCollection, IConfiguration, Action?) 方法** — 将 Gears 框架服务注册到 DI 容器中。这是框架初始化的主要入口点。第一个参数是 IServiceCollection 实例，第二个参数是 IConfiguration 实例，第三个可选参数是模块配置委托。此方法执行以下操作：创建 GearsBoots 实例，调用模块配置委托，注册基础服务，保存配置和服务提供器的引用。 **UseGears(this IApplicationBuilder) 方法** — 初始化 `GearsApp.RootServices`。当前实现并不会注册额外中间件，也不会执行模块级管道配置；它只是把应用构建完成后的根服务提供者保存到 `GearsApp`，供静态访问场景使用。返回 `IApplicationBuilder` 实例，支持链式调用。 ## 许可证 Gears 框架采用 **MIT 许可证** 开源。这是一个宽松的开源许可证，允许在任何项目中自由使用、修改和分发本软件，包括商业用途。MIT 许可证只需保留版权声明和许可证文本，无需公开衍生作品的源代码。 MIT 许可证是开源社区最受欢迎的许可证之一，它对使用者的限制极少，给予了开发者充分的自由。这意味着您可以将 Gears 框架用于开源项目或闭源商业产品，可以在不修改许可证的情况下分发修改后的版本。当然，我们欢迎但不强制要求您为项目贡献改进建议。 使用本框架即表示您已阅读并同意许可证条款。如果您对许可证有任何疑问，请联系项目维护者获取澄清。我们希望 Gears 框架能够帮助您构建出色的应用程序，期待看到您的作品！ ## 贡献指南 Gears 框架欢迎社区贡献代码、文档和问题报告。如果您发现了 bug 或者有功能建议，请在代码仓库的 Issues 页面提交。对于代码贡献，请先fork 仓库，创建特性分支，编写清晰的提交信息，然后提交 Pull Request。我们会在收到后尽快审查您的贡献。 在贡献代码之前，建议先查看项目的 TODO 列表和未解决的问题，了解当前开发的方向和优先事项。所有的贡献都应该遵循项目的代码风格和命名规范，确保代码质量符合项目标准。对于重大改动，建议先在 Issues 中讨论您的方案，获得维护者的认可后再开始实现。