TJC.Cyclops.Orm 2026.5.11.1

🗄️ Cyclops.Orm

📝 项目概述

Cyclops.Orm 是企服版框架中的ORM核心专家，为您的应用程序提供强大、灵活的数据访问和实体管理功能！ 🚀

我们精心设计的库基于SqlSugar、Mapster和Yitter.IdGenerator进行封装，采用仓储模式、工作单元模式和代码生成器，简化数据库操作，支持多租户、数据权限控制等企业级特性。无论是简单的CRUD操作，还是复杂的企业级应用，Cyclops.Orm都能为您提供出色的支持。

✨ 为什么选择 Cyclops.Orm？

• 强大的ORM功能：基于SqlSugar，提供丰富的数据库操作能力
• 简化开发：采用仓储模式和工作单元模式，简化数据访问层代码
• 企业级特性：支持多租户、数据权限控制等企业级需求
• 代码生成：内置代码生成器，自动生成实体和仓储代码
• 高性能：优化的数据库操作，提升应用性能
• 易于集成：与.NET依赖注入系统无缝集成

🎯 核心功能模块

🏗️ 实体基础

• EntityBase.cs：实体基类，提供审计字段和基础属性
• EntityBaseId.cs：带ID的实体基类，简化ID管理
• EntityTenant.cs：支持租户的实体基类，实现多租户功能
• EntityTenantId.cs：支持租户和ID的实体基类，整合租户和ID管理
• EntityeDataScoreBase.cs：支持数据权限的实体基类，实现细粒度数据权限控制

📦 仓储模式

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

⚙️ ORM核心配置

• CyclopsOrm.cs：ORM核心配置类，提供数据库初始化和配置功能
• DbConnectionOptions.cs：数据库连接配置类，管理数据库连接信息
• CyclopsOrmConst.cs：ORM常量定义，统一管理常量值
• OrmResource.resx：ORM资源文件，管理多语言资源

🏷️ 自定义属性

• IgnoreTableAttribute.cs：标记实体不生成表，灵活控制表生成
• LogTableAttribute.cs：标记日志表，特殊处理日志数据
• UnitOfWorkAttribute.cs：标记方法使用工作单元，自动管理事务
• OwnerUserAttribute.cs：标记用户所属字段，实现用户级数据权限
• OwnerOrgAttribute.cs：标记组织所属字段，实现组织级数据权限
• SysTableAttribute.cs：标记系统表，特殊处理系统数据
• CustomAttribute.cs：自定义属性基类，支持扩展自定义属性
• ExistsAttribute.cs：验证字段是否存在，确保数据完整性
• IncreSeedAttribute.cs：标记增量种子，支持增量数据处理
• IncreTableAttribute.cs：标记增量表，优化增量数据存储

🤖 代码生成器

• CodeGenerator.cs：代码生成器，用于生成实体、仓储等代码，提高开发效率
• CSTemplateConst.cs：C#代码模板常量，定义代码生成模板

📚 实体集合

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

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

📋 枚举定义

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

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

🛠️ 辅助工具

• SqlUtil.cs：SQL辅助工具类，提供SQL操作辅助功能
• MapsterExtention.cs：Mapster映射扩展方法，简化对象映射

🛠️ 技术栈

• .NET 8.0：基础开发框架，利用最新的.NET特性
• SqlSugarCore 5.1.4.210：强大的ORM框架，提供丰富的数据库操作能力
• Mapster 7.4.0：高性能对象映射工具，简化对象转换
• Yitter.IdGenerator 1.0.14：高效的分布式ID生成器，确保ID唯一性
• Cyclops.Common：框架核心公共组件
• Cyclops.DI：依赖注入库，简化依赖管理
• Cyclops.Linq：LINQ扩展库，增强查询能力

📦 环境依赖

• .NET 8.0 或更高版本
• 数据库：SQL Server、MySQL、PostgreSQL、Oracle等SqlSugar支持的数据库
• 其他Cyclops框架库：确保与其他Cyclops组件的兼容性
• 支持的平台：Windows、Linux、macOS
• IDE推荐：Visual Studio 2022、Visual Studio Code

🚀 安装配置

🔍 安装方式

NuGet包管理器

Install-Package TJC.Cyclops.Orm

.NET CLI

dotnet add package TJC.Cyclops.Orm

PackageReference

<PackageReference Include="TJC.Cyclops.Orm" Version="1.0.0" />

⚙️ 配置

配置文件设置

在应用程序配置文件中添加数据库配置（以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
      }
    ]
  }
}

依赖注入配置

在ASP.NET Core应用中，通过依赖注入进行配置：

// 在Program.cs或Startup.cs中
using Cyclops.Orm;

var builder = WebApplication.CreateBuilder(args);

// 读取数据库配置
var dbConnectionOptions = new DbConnectionOptions();
builder.Configuration.GetSection("DbConnection").Bind(dbConnectionOptions);

// 配置依赖注入
builder.Services.AddSingleton(dbConnectionOptions);
builder.Services.AddScoped(typeof(IUnitOfWork), typeof(UnitOfWork));
builder.Services.AddScoped(typeof(BaseRepository<>));

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

var app = builder.Build();

// ...

app.Run();

🎯 配置建议

• 连接字符串安全：建议将连接字符串存储在安全的配置管理系统中，避免硬编码
• 数据库选择：根据应用需求选择合适的数据库类型
• 读写分离：对于高流量应用，配置读写分离以提高性能
• 连接池：合理配置连接池大小，优化数据库连接管理

📝 使用示例

🏗️ 实体定义

以下示例展示了如何使用 Cyclops.Orm 定义实体类：

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; }
}

📦 仓储使用

以下示例展示了如何使用 Cyclops.Orm 的仓储模式进行数据操作：

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);

🔄 工作单元使用

以下示例展示了如何使用 Cyclops.Orm 的工作单元模式管理事务：

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;
}

🤖 代码生成

以下示例展示了如何使用 Cyclops.Orm 的代码生成器自动生成代码：

using Cyclops.Orm.Generating;

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

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

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

🏢 多租户支持

以下示例展示了如何使用 Cyclops.Orm 的多租户功能：

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

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

🔒 数据权限过滤

以下示例展示了如何使用 Cyclops.Orm 的数据权限过滤功能：

// 设置用户数据权限范围
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; // 示例：添加自定义过滤逻辑
    }
}

🤝 贡献者

我们欢迎社区贡献！如果您有任何改进建议或功能需求，欢迎提交PR或Issue。

• yswenli：核心开发者

📋 版本信息

• 当前版本：
• 作者：yswenli
• 描述：企服版框架中ORM核心，基于YitIdHelper、Mapster、SqlSugar封装
• 更新频率：定期更新，持续改进

📄 许可证

保留所有权利

🎉 结语

Cyclops.Orm 致力于为您的应用程序提供强大、灵活的数据访问和实体管理功能。我们相信，通过简化数据库操作的复杂性，您可以更专注于业务逻辑的实现，构建出更强大、更可靠的企业级应用。

如果您有任何问题或建议，欢迎与我们联系！让我们一起构建更好的ORM解决方案！ 🚀