Cyclops.Common.Service

项目概述

Cyclops.Common.Service是企服版框架中的核心服务处理库，提供了服务层的基础设施和后台任务管理功能。该项目主要关注两个核心方面：

1. 为应用程序提供标准化的服务层实现模式
2. 提供强大且灵活的后台任务处理框架

通过统一的服务模式和后台任务管理，Cyclops.Common.Service使开发者能够轻松构建可靠、可扩展的企业级应用服务。

核心功能模块

1. 基础服务框架

1.1 基础服务类

• BaseService：所有服务类的基类，提供了服务的基本功能和生命周期管理
• BaseServiceT<T>：泛型版本的基础服务类，允许在服务中指定实体类型

1.2 服务特性

• 依赖注入集成：与Cyclops.DI深度集成，支持自动依赖注入
• 异常处理：内置统一的异常处理机制，确保服务层的异常能够被适当捕获和处理
• 日志记录：集成日志功能，便于服务操作的跟踪和调试

2. 后台任务框架

2.1 任务基类

• BaseJobService：后台任务的基础实现，所有后台任务都应继承此类
• BaseSubJobService：子任务的基类，用于实现可分解的复杂任务
• ParentJobService：父任务服务，用于管理和协调多个子任务

2.2 任务接口

• IJob：所有作业任务必须实现的接口，定义了作业的基本操作

2.3 任务管理

• JobServiceLoader：作业服务加载器，负责发现和初始化系统中的作业服务
• JobInfosCache：作业信息缓存，用于存储和管理作业的元数据
• JobInfo：作业信息模型，包含作业的各种属性和状态信息

2.4 后台服务基础设施

• BaseBackgroundService：基于.NET Core的BackgroundService的增强实现，提供更丰富的后台任务管理功能

技术栈

• 开发框架：.NET 8.0
• 项目类型：类库（Class Library）
• 核心依赖：
  • Cyclops.Common - 提供基础工具类
  • Cyclops.DI - 依赖注入框架
  • Microsoft.Extensions.Hosting - 后台服务支持

环境依赖要求

• .NET 8.0 SDK 或更高版本
• 引用的Cyclops.Common和Cyclops.DI项目

安装与配置

安装方式

可以通过以下方式安装Cyclops.Common.Service包：

1. NuGet包管理器：

   Install-Package TJC.Cyclops.Common.Service

2. .NET CLI：

   dotnet add package TJC.Cyclops.Common.Service

基本配置

在使用Cyclops.Common.Service之前，需要进行以下配置：

1. 依赖注入配置：在应用程序的启动类中配置服务注入
2. 后台服务配置：对于后台任务服务，需要在HostBuilder中注册

核心功能代码示例

1. 创建和使用基础服务

// 定义服务接口 public interface IUserService { Task<User> GetUserByIdAsync(int userId); Task CreateUserAsync(User user); } // 实现服务 public class UserService : BaseService, IUserService { // 可以注入依赖项 private readonly IRepository<User> _userRepository; public UserService(IRepository<User> userRepository) { _userRepository = userRepository; } public async Task<User> GetUserByIdAsync(int userId) { // 服务实现 return await _userRepository.FindByIdAsync(userId); } public async Task CreateUserAsync(User user) { // 服务实现 await _userRepository.InsertAsync(user); } } // 注册服务到DI容器 public void ConfigureServices(IServiceCollection services) { services.AddScoped<IUserService, UserService>(); // 其他服务注册... } // 在控制器或其他组件中使用服务 public class UserController : Controller { private readonly IUserService _userService; public UserController(IUserService userService) { _userService = userService; } [HttpGet("{id}")] public async Task<IActionResult> Get(int id) { var user = await _userService.GetUserByIdAsync(id); return Ok(user); } }

2. 创建和配置后台任务

2.1 基本后台任务

// 定义后台任务 public class CleanupJob : BaseJobService { protected override string JobName => "数据清理任务"; protected override async Task ExecuteAsync(CancellationToken stoppingToken) { Logger.Info($"[{JobName}] 开始执行"); try { // 执行实际的清理逻辑 await CleanupOldDataAsync(); Logger.Info($"[{JobName}] 执行完成"); } catch (Exception ex) { Logger.Error($"[{JobName}] 执行出错: {ex.Message}", ex); } } private async Task CleanupOldDataAsync() { // 清理逻辑实现 // 例如删除超过90天的日志数据 } } // 注册后台任务到Host public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureServices((hostContext, services) => { // 注册后台任务 services.AddHostedService<CleanupJob>(); // 其他服务注册... });

2.2 定时后台任务

public class ScheduleTask : BaseJobService { private readonly PeriodicTimer _timer; private readonly TimeSpan _interval; protected override string JobName => "定时同步任务"; public ScheduleTask() { // 设置定时间隔（每小时执行一次） _interval = TimeSpan.FromHours(1); _timer = new PeriodicTimer(_interval); } protected override async Task ExecuteAsync(CancellationToken stoppingToken) { Logger.Info($"[{JobName}] 启动，间隔: {_interval.TotalHours}小时"); while (!stoppingToken.IsCancellationRequested && await _timer.WaitForNextTickAsync(stoppingToken)) { try { Logger.Info($"[{JobName}] 开始执行"); // 执行定时任务逻辑 await SyncDataAsync(); Logger.Info($"[{JobName}] 执行完成"); } catch (Exception ex) { Logger.Error($"[{JobName}] 执行出错: {ex.Message}", ex); } } } private async Task SyncDataAsync() { // 同步数据逻辑实现 } }

2.3 父子任务模式

// 子任务实现 public class EmailSendSubJob : BaseSubJobService { private readonly string _emailAddress; private readonly string _subject; private readonly string _body; public EmailSendSubJob(string emailAddress, string subject, string body) { _emailAddress = emailAddress; _subject = subject; _body = body; } protected override string JobName => $"发送邮件到 {_emailAddress}"; protected override async Task ExecuteAsync(CancellationToken stoppingToken) { Logger.Info($"[{JobName}] 开始执行"); try { // 实际发送邮件的逻辑 await SendEmailAsync(); Logger.Info($"[{JobName}] 执行完成"); // 标记子任务完成 JobState = JobState.Completed; } catch (Exception ex) { Logger.Error($"[{JobName}] 执行出错: {ex.Message}", ex); // 标记子任务失败 JobState = JobState.Failed; ErrorMessage = ex.Message; } } private async Task SendEmailAsync() { // 发送邮件实现 } } // 父任务实现 public class BatchEmailJob : ParentJobService { protected override string JobName => "批量发送邮件任务"; public async Task StartBatchEmailAsync(List<(string email, string subject, string body)> emails) { Logger.Info($"[{JobName}] 开始处理，总邮件数: {emails.Count}"); // 创建子任务列表 var subJobs = emails.Select(e => new EmailSendSubJob(e.email, e.subject, e.body)).ToList(); // 添加子任务并启动 AddSubJobs(subJobs); // 等待所有子任务完成 await WaitForAllSubJobsAsync(); // 汇总结果 var completed = subJobs.Count(j => j.JobState == JobState.Completed); var failed = subJobs.Count(j => j.JobState == JobState.Failed); Logger.Info($"[{JobName}] 处理完成，成功: {completed}, 失败: {failed}"); } } // 使用父子任务 public class EmailService : BaseService { private readonly BatchEmailJob _batchEmailJob; public EmailService(BatchEmailJob batchEmailJob) { _batchEmailJob = batchEmailJob; } public async Task SendBatchEmailsAsync(List<(string email, string subject, string body)> emails) { await _batchEmailJob.StartBatchEmailAsync(emails); } }

使用注意事项

1. 服务命名和日志：

   • 所有继承自BaseService或BaseJobService的类，应当设置有意义的JobName或类名，便于日志跟踪
   • 确保在关键操作点添加适当的日志记录

2. 异常处理：

   • 在服务实现中捕获并处理异常，避免将未处理的异常传播到上层
   • 对于后台任务，特别注意异常处理，确保任务不会因为异常而意外终止

3. 资源释放：

   • 在长时间运行的后台任务中，确保适当释放资源，特别是数据库连接和文件句柄
   • 当任务被取消时，及时清理资源

4. 并发控制：

   • 对于可能被多个实例同时执行的任务，实现必要的分布式锁或任务调度机制
   • 避免多个任务实例同时修改同一数据

5. 任务监控：

   • 实现任务状态监控机制，及时发现任务执行异常
   • 对于关键任务，考虑添加告警机制

6. 依赖注入：

   • 确保所有服务依赖通过构造函数注入，便于测试和维护
   • 避免在服务内部直接实例化其他服务，应通过依赖注入获取

7. 性能考虑：

   • 对于频繁执行的任务，注意控制资源使用，避免系统过载
   • 考虑使用批处理和异步操作提高任务执行效率

8. 服务生命周期：

   • 了解并正确使用不同的服务生命周期（Singleton、Scoped、Transient）
   • 避免在Singleton服务中注入Scoped依赖

9. 配置外部化：

   • 将任务执行参数、定时间隔等配置信息外部化，便于运行时调整
   • 考虑使用配置中心动态更新任务配置

10. 测试策略：

    • 为服务层编写单元测试，确保业务逻辑正确
    • 使用模拟对象（Mock）隔离服务依赖，提高测试效率
    • 考虑为关键任务编写集成测试，验证端到端功能

贡献者

• yswenli

许可证

保留所有权利