TJC.Cyclops.Orm 2026.1.15.1

Cyclops.Orm

项目概述

Cyclops.Orm是企服版框架中的ORM核心库，基于SqlSugar、Mapster和Yitter.IdGenerator进行封装，提供强大的数据访问和实体管理功能。该库采用仓储模式、工作单元模式和代码生成器，简化数据库操作，支持多租户、数据权限控制等企业级特性。

核心功能模块

1. 实体基础

• EntityBase.cs：实体基类，提供审计字段和基础属性
• EntityBaseId.cs：带ID的实体基类
• EntityTenant.cs：支持租户的实体基类
• EntityTenantId.cs：支持租户和ID的实体基类
• EntityeDataScoreBase.cs：支持数据权限的实体基类

2. 仓储模式

• BaseRepository.cs：基础仓储类，提供通用的CRUD操作
• DbTran.cs：数据库事务类，用于管理事务操作
• IUnitOfWork.cs：工作单元接口，提供事务管理和仓储访问
• UnitOfWork.cs：工作单元实现，集成多仓储事务管理

3. ORM核心配置

• CyclopsOrm.cs：ORM核心配置类，提供数据库初始化和配置功能
• DbConnectionOptions.cs：数据库连接配置类
• CyclopsOrmConst.cs：ORM常量定义
• OrmResource.resx：ORM资源文件

4. 自定义属性

• IgnoreTableAttribute.cs：标记实体不生成表
• LogTableAttribute.cs：标记日志表
• UnitOfWorkAttribute.cs：标记方法使用工作单元
• OwnerUserAttribute.cs：标记用户所属字段
• OwnerOrgAttribute.cs：标记组织所属字段
• SysTableAttribute.cs：标记系统表
• CustomAttribute.cs：自定义属性基类
• ExistsAttribute.cs：验证字段是否存在
• IncreSeedAttribute.cs：标记增量种子
• IncreTableAttribute.cs：标记增量表

5. 代码生成器

• CodeGenerator.cs：代码生成器，用于生成实体、仓储等代码
• CSTemplateConst.cs：C#代码模板常量

6. 实体集合

Entities命名空间包含框架内置的实体类，如：

• 用户与权限：DbUser、DbRole、DbMenu、DbUserRole、DbRoleMenu
• 组织管理：DbOrg、DbUserExtOrg、DbRoleOrg
• 系统配置：DbConfig、DbDictType、DbDictData
• 通知系统：DbNotice、DbNoticeUser
• 流程管理：DbApprovalFlow、DbApprovalFlowRecord
• 租户管理：DbTenant
• 日志记录：DbLogDiff、DbSmsLog
• 微信集成：DbWechatUser、DbWechatPay、DbWechatTemplateMsg

7. 枚举定义

Enums命名空间包含系统中使用的枚举类型，如：

• 用户相关：EnumGender、EnumUserAuditStatus
• 组织相关：EnumDataScope
• 菜单相关：EnumMenuType
• 通知相关：EnumNoticeType、EnumNoticeStatus
• 租户相关：EnumTenantType

8. 辅助工具

• SqlUtil.cs：SQL辅助工具类
• MapsterExtention.cs：Mapster映射扩展方法

技术栈

• .NET 8.0：基础开发框架
• SqlSugarCore 5.1.4.210：ORM框架
• Mapster 7.4.0：对象映射工具
• Yitter.IdGenerator 1.0.14：分布式ID生成器
• Cyclops.Common：公共库依赖
• Cyclops.DI：依赖注入库依赖
• Cyclops.Linq：LINQ扩展库依赖

环境依赖

• .NET 8.0或更高版本
• SQL Server或其他SqlSugar支持的数据库
• 其他Cyclops框架库

安装配置

安装

通过NuGet包管理器安装：

Install-Package TJC.Cyclops.Orm

或通过.NET CLI安装：

dotnet add package TJC.Cyclops.Orm

配置

在应用程序配置文件中添加数据库配置（以appsettings.json为例）：

{
  "DbConnection": {
    "Default": {
      "ConnectionString": "Server=localhost;Database=MyDatabase;User Id=sa;Password=your_password;",
      "DbType": "SqlServer",
      "IsAutoCloseConnection": true
    },
    "Read": [
      {
        "ConnectionString": "Server=localhost;Database=MyDatabase;User Id=readonly;Password=your_password;",
        "DbType": "SqlServer",
        "IsAutoCloseConnection": true
      }
    ]
  }
}

初始化

在应用启动时初始化ORM：

// 配置依赖注入
 services.AddSingleton(provider =>
 {
     var options = new DbConnectionOptions();
     // 从配置中读取数据库连接信息
     return options;
 });

// 初始化CyclopsOrm
CyclopsOrm.Init(options);

使用示例

1. 实体定义

using Cyclops.Orm.Attributes;
using Cyclops.Orm.Models;

[SugarTable("tb_product")]
public class Product : EntityBaseId
{
    [SugarColumn(ColumnDescription = "产品名称")]
    public string Name { get; set; }
    
    [SugarColumn(ColumnDescription = "产品价格")]
    public decimal Price { get; set; }
    
    [SugarColumn(ColumnDescription = "产品描述")]
    public string Description { get; set; }
    
    [SugarColumn(ColumnDescription = "是否启用")]
    public bool IsEnabled { get; set; }
    
    [OwnerUser]
    [SugarColumn(ColumnDescription = "创建人")]
    public long CreateUser { get; set; }
    
    [OwnerOrg]
    [SugarColumn(ColumnDescription = "所属组织")]
    public long OrgId { get; set; }
}

2. 仓储使用

using Cyclops.Orm;
using Cyclops.Orm.Models;

// 创建仓储实例
var productRepository = new BaseRepository<Product>();

// 添加产品
var product = new Product
{
    Name = "测试产品",
    Price = 99.9M,
    Description = "这是一个测试产品",
    IsEnabled = true,
    CreateUser = 1,
    OrgId = 1
};
var newId = await productRepository.InsertReturnSnowflakeIdAsync(product);

// 查询产品
var query = await productRepository.GetListAsync(p => p.IsEnabled == true);

// 更新产品
product.Price = 129.9M;
await productRepository.UpdateAsync(product);

// 删除产品
await productRepository.DeleteByIdAsync(newId);

3. 工作单元使用

using Cyclops.Orm.Interfaces;
using Cyclops.Orm.Attributes;

// 通过构造函数注入工作单元
private readonly IUnitOfWork _unitOfWork;

public ProductService(IUnitOfWork unitOfWork)
{
    _unitOfWork = unitOfWork;
}

// 使用工作单元管理事务
[UnitOfWork]
public async Task<bool> UpdateProductWithStockAsync(Product product, int stockChange)
{
    var productRepository = _unitOfWork.GetRepository<Product>();
    var stockRepository = _unitOfWork.GetRepository<Stock>();
    
    // 更新产品信息
    await productRepository.UpdateAsync(product);
    
    // 更新库存信息
    var stock = await stockRepository.GetByIdAsync(product.Id);
    stock.Quantity += stockChange;
    await stockRepository.UpdateAsync(stock);
    
    // 工作单元会自动提交事务，如果发生异常会自动回滚
    return true;
}

4. 代码生成

using Cyclops.Orm.Generating;

// 生成代码
var generator = new CodeGenerator();

// 生成实体代码
await generator.GenerateEntitiesAsync("ConnectionString", "OutputPath");

// 生成仓储代码
await generator.GenerateRepositoriesAsync("ConnectionString", "OutputPath");

5. 多租户支持

// 设置当前租户ID
CyclopsOrm.SetCurrentTenant(1001);

// 后续操作会自动过滤当前租户数据
var products = await productRepository.GetListAsync();

6. 数据权限过滤

// 设置用户数据权限范围
CyclopsOrm.SetUserScope(userId, EnumDataScope.OrgAndChild);

// 查询会自动应用数据权限过滤
var users = await userRepository.GetListAsync();

扩展指南

创建自定义仓储

public class ProductRepository : BaseRepository<Product>
{
    // 添加自定义查询方法
    public async Task<List<Product>> GetHotProductsAsync(int top = 10)
    {
        return await Context.Queryable<Product>()
            .Where(p => p.IsEnabled == true)
            .OrderBy(p => p.CreateTime, OrderByType.Desc)
            .Take(top)
            .ToListAsync();
    }
}

创建自定义实体过滤器

public class CustomDataFilter : IEntityFilter
{
    public Expression<Func<T, bool>> GetFilter<T>() where T : class, new()
    {
        // 返回自定义过滤条件
        return entity => true; // 示例：添加自定义过滤逻辑
    }
}

版本信息

• 当前版本
• 作者：yswenli
• 描述：企服版框架中ORM核心，基于YitIdHelper、Mapster、SqlSugar封装

贡献者

• yswenli

许可证

保留所有权利