TJC.Cyclops.DI 2026.4.14.2

Cyclops.DI

🧩 增强型依赖注入框架 🧩

Cyclops.DI 是企服版框架中的依赖注入核心库，提供了增强型的依赖注入功能，扩展了.NET标准依赖注入容器的能力。该库不仅支持标准的依赖注入模式，还提供了基于接口的自动注册、AOP代理拦截、生命周期管理以及丰富的配置选项，使开发者能够构建更加灵活、可维护的企业级应用。

🌟 核心特性

• 生命周期管理：支持瞬态(ITransient)、作用域(IScoped)、单例(ISingleton)三种生命周期
• 自动注册：基于接口的服务自动注册，简化配置
• AOP代理：内置方法拦截功能，支持日志记录、性能监控、异常处理等横切关注点
• 丰富的配置选项：支持多种注入模式、自定义代理、注入顺序等配置
• 依赖注入特性：通过特性标记配置服务注册行为
• 服务描述符工具：提供丰富的服务注册和管理功能
• 全局代理：支持全局方法拦截，统一处理横切关注点

🛠️ 技术栈

• 开发框架：.NET 8.0
• 项目类型：类库（Class Library）
• 核心依赖：
  • Microsoft.Extensions.DependencyInjection.Abstractions (10.0.0) - .NET依赖注入抽象
  • Cyclops.Common - 提供基础工具类支持

📦 安装

dotnet add package TJC.Cyclops.DI

🚀 快速开始

基本配置

在应用程序的启动类中进行配置：

using Cyclops.DI;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // 自动注入所有实现了IDependency的类型（包含ITransient、IScoped、ISingleton）
        services.AutoInjectAllCustomerServices();
        
        // 其他服务注册...
    }
}

服务定义

using Cyclops.DI;

// 定义服务接口
public interface IUserService
{
    User GetUserById(int id);
    void SaveUser(User user);
}

// 实现服务并指定生命周期
public class UserService : IUserService, IScoped
{
    private readonly IDbContext _dbContext;
    
    public UserService(IDbContext dbContext)
    {
        _dbContext = dbContext;
    }
    
    public User GetUserById(int id)
    {
        return _dbContext.Users.FirstOrDefault(u => u.Id == id);
    }
    
    public void SaveUser(User user)
    {
        if (user.Id == 0)
        {
            _dbContext.Users.Add(user);
        }
        else
        {
            _dbContext.Users.Update(user);
        }
        _dbContext.SaveChanges();
    }
}

📖 使用指南

使用注入特性

using Cyclops.DI;
using Cyclops.DI.Attrs;

// 使用InjectionAttribute配置注入行为
[Injection(Order = 10, Pattern = EnumInjectionPatterns.All)]
public class ProductService : IProductService, ISingleton
{
    // 服务实现...
}

// 抑制代理创建
[SuppressProxy]
public class LoggingService : ILoggingService, ITransient
{
    // 服务实现...
}

AOP代理实现

using Cyclops.DI;
using Cyclops.DI.Core;
using System.Reflection;

// 创建自定义代理类
public class LoggingProxy : AspectDispatchProxy
{
    public IServiceProvider Services { get; set; }
    public object Target { get; set; }
    
    private ILogger _logger;
    
    private ILogger Logger => _logger ??= Services.GetRequiredService<ILogger>();
    
    protected override object Invoke(MethodInfo targetMethod, object[] args)
    {
        // 方法调用前
        var methodName = targetMethod.Name;
        var className = Target.GetType().Name;
        
        Logger.Info($"[{className}.{methodName}] 开始执行");
        
        try
        {
            // 执行实际方法
            var result = targetMethod.Invoke(Target, args);
            
            // 方法调用后
            Logger.Info($"[{className}.{methodName}] 执行完成");
            
            return result;
        }
        catch (Exception ex)
        {
            // 异常处理
            Logger.Error($"[{className}.{methodName}] 执行出错: {ex.InnerException?.Message}", ex);
            throw ex.InnerException ?? ex;
        }
    }
}

// 在服务上指定自定义代理
[Injection(Proxy = typeof(LoggingProxy))]
public class OrderService : IOrderService, IScoped
{
    // 服务实现...
}

高级服务注册

using Cyclops.DI;
using Cyclops.DI.Attrs;

public void ConfigureServices(IServiceCollection services)
{
    // 自动注入所有实现了IDependency的服务
    services.AutoInjectAllCustomerServices();
    
    // 手动注册服务
    var injectionAttribute = new InjectionAttribute
    {
        Pattern = EnumInjectionPatterns.SelfWithFirstInterface,
        Action = EnumInjectionActions.Add
    };
    
    ServiceDescriptorUtil.Register(
        services,
        typeof(IScoped),
        typeof(CustomerService),
        injectionAttribute,
        typeof(ICustomerService)
    );
}

生命周期管理

using Cyclops.DI;

// 服务层 - 作用域生命周期
public class UserService : IUserService, IScoped
{
    private readonly IRepository _repository; // 假设也是IScoped
    private readonly ICacheService _cacheService; // 假设是ISingleton
    
    public UserService(IRepository repository, ICacheService cacheService)
    {
        _repository = repository;
        _cacheService = cacheService;
    }
    
    public User GetUser(int id)
    {
        // 优先从缓存获取
        var cacheKey = $"user:{id}";
        var user = _cacheService.Get<User>(cacheKey);
        
        if (user == null)
        {
            // 缓存未命中，从数据库获取
            user = _repository.GetById<User>(id);
            
            // 更新缓存
            if (user != null)
            {
                _cacheService.Set(cacheKey, user, TimeSpan.FromMinutes(30));
            }
        }
        
        return user;
    }
}

// 作用域创建和使用
public class SomeService
{
    private readonly IServiceProvider _serviceProvider;
    
    public SomeService(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }
    
    public void ProcessBatch(List<int> ids)
    {
        foreach (var id in ids)
        {
            // 为每个操作创建单独的作用域
            using (var scope = _serviceProvider.CreateScope())
            {
                var scopedService = scope.ServiceProvider.GetRequiredService<IScopedService>();
                scopedService.Process(id);
            }
        }
    }
}

🔧 配置说明

注入模式

• Self：仅注册自身类型
• All：注册自身类型和所有实现的接口
• SelfWithFirstInterface：注册自身类型和第一个实现的接口
• InterfacesOnly：仅注册实现的接口

注入操作

• Add：添加服务描述符
• TryAdd：尝试添加服务描述符，仅当不存在时添加
• Replace：替换已存在的服务描述符
• TryAddEnumerable：尝试添加可枚举服务

📋 核心接口

• IDependency：所有依赖注入类型的基础接口
• ITransient：瞬态生命周期接口，每次请求都会创建新实例
• IScoped：作用域生命周期接口，在同一作用域内共享一个实例
• ISingleton：单例生命周期接口，应用程序生命周期内只创建一次实例
• IDispatchProxy：调度代理接口，定义了代理的基本行为
• IGlobalDispatchProxy：全局调度代理接口，提供全局方法拦截功能

⚠️ 使用注意事项

1. 接口继承顺序：实现类在继承ITransient、IScoped或ISingleton时，应确保它们是最后继承的接口之一，以避免类型解析问题

2. 生命周期使用建议：

   • 无状态服务优先使用ITransient
   • 数据库上下文等使用IScoped
   • 配置、缓存等全局服务使用ISingleton

3. 代理使用注意：

   • 代理会增加一定的性能开销，对性能敏感的场景应谨慎使用
   • 使用SuppressProxyAttribute可以对特定类禁用代理

4. 依赖注入循环引用：避免服务之间形成循环依赖，这可能导致服务初始化失败

5. 线程安全：在使用ISingleton服务时，务必确保其是线程安全的，特别是在并发环境下

6. 作用域管理：在长生命周期的服务中使用作用域服务时，应手动创建和管理作用域

7. 异常处理：在代理中捕获和处理异常时，注意保留原始异常信息，以便于调试

8. 服务注册顺序：对于有依赖关系的服务，应确保先注册被依赖的服务

9. 日志记录：在代理中添加日志时，注意控制日志级别，避免过多的日志影响性能

10. 内存管理：长时间运行的应用程序中，注意监控单例服务的内存使用情况，避免内存泄漏

🤝 贡献

我们欢迎社区贡献！如果您有任何想法或建议，欢迎提交 Issue 或 Pull Request。

📄 许可证

MIT License

Cyclops.DI - 让依赖注入更加灵活强大，为企业级应用提供可靠的服务管理！✨