TJC.Cyclops.Reporting 2026.6.9.2

📊 Cyclops.Reporting

📖 项目概述

Cyclops.Reporting 是 Cyclops.Framework 框架中的报表生成利器，为您的应用程序提供灵活、高效的数据导出能力！🚀

无论您是需要快速导出一份简单的数据列表，还是需要构建一个支持动态配置、多条件查询的企业级报表系统，Cyclops.Reporting 都能轻松应对。

我们提供两种报表模式：

• 静态报表：基于泛型 List<T>，通过特性标注，几行代码即可完成数据导出
• 动态报表：基于 Lua 脚本，支持运行时 SQL 生成、列值转换，满足复杂业务需求

✨ 为什么选择 Cyclops.Reporting？

• 两种模式，灵活选择：简单场景用静态报表，复杂场景用动态报表
• Lua 脚本驱动：SQL 生成、列值转换全部由 Lua 脚本控制，灵活强大
• 内置丰富函数：HTTP 调用、JSON 处理、加密、正则等开箱即用
• 易于集成：与 .NET 依赖注入系统无缝集成，一行代码注册服务
• 高性能：基于 SqlSugar 和 NPOI，优化的查询和导出性能

🎯 核心功能模块

📄 静态报表

适用于快速、简单的数据导出场景：

• 泛型导出：基于 List<T>，自动识别属性生成报表
• 特性标注：使用 [ReportDescription] 自定义列标题、排序、格式
• 类型转换：bool、DateTime、Enum 等类型自动转换为可读文本
• 多格式支持：CSV 和 Excel（.xlsx/.xls）格式

🔧 动态报表

适用于需要运行时配置的复杂报表场景：

• Lua 生成 SQL：支持动态条件拼接，告别繁琐的 SQL 拼接
• 列值转换：支持值映射（ValueMap）和 Lua 脚本转换
• 报表预览：支持前 N 行数据预览，快速验证数据
• 报表导出：支持 CSV 和 Excel 格式全量导出
• 配置管理：报表配置和列配置的 CRUD 操作

🛠️ Lua 引擎内置函数

开箱即用的工具函数，让您的 Lua 脚本更强大：

🛠️ 技术栈

• .NET 8.0：基础开发框架
• MoonSharp：纯 C# 实现的 Lua 脚本引擎，跨平台
• SqlSugar：通过 Cyclops.Orm 封装的 ORM 框架
• NPOI：Excel 文件处理库
• Cyclops.Common：框架核心公共组件
• Cyclops.Orm：框架 ORM 组件

📦 环境依赖

• .NET 8.0 SDK 或更高版本
• 支持的平台：Windows、Linux、macOS
• IDE推荐：Visual Studio 2022、Visual Studio Code

🚀 安装配置

NuGet 安装

Install-Package TJC.Cyclops.Reporting

基本配置

在应用程序启动时注册服务：

using Cyclops.Reporting.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 添加 Cyclops.Reporting 服务
builder.Services.AddCyclopsReporting();

var app = builder.Build();

📝 代码示例

📄 静态报表：快速导出

只需定义一个数据模型，几行代码即可完成导出：

using Cyclops.Reporting;
using Cyclops.Reporting.Attrs;

// 1. 定义数据模型
public class Employee
{
    [ReportDescription("员工姓名", 1)]
    public string Name { get; set; }

    [ReportDescription("是否在职", 2, "在职,离职")]
    public bool IsActive { get; set; }

    [ReportDescription("入职日期", 3, datetimeFormat: "yyyy-MM-dd")]
    public DateTime HireDate { get; set; }

    [ReportDescription("部门", 4)]
    public string Department { get; set; }

    [ReportIgnore]  // 忽略此字段，不导出
    public string InternalCode { get; set; }
}

// 2. 准备数据
var employees = new List<Employee>
{
    new Employee { Name = "张三", IsActive = true, HireDate = DateTime.Now.AddYears(-2), Department = "技术部" },
    new Employee { Name = "李四", IsActive = false, HireDate = DateTime.Now.AddYears(-1), Department = "市场部" }
};

// 3. 导出
var report = new Report<Employee>(employees);
report.Export("员工信息.xlsx");  // Excel 格式
report.Export("员工信息.csv");   // CSV 格式

🔧 动态报表：完整流程

第一步：配置报表

using Cyclops.Reporting.Dynamic.Entities;
using Cyclops.Reporting.Dynamic.Services;

public class ReportAdminController
{
    private readonly ReportConfigService _configService;

    public ReportAdminController(ReportConfigService configService)
    {
        _configService = configService;
    }

    // 创建报表配置
    public async Task<long> CreateReport()
    {
        var config = new DbReportConfig
        {
            Name = "用户活跃度报表",
            Description = "统计用户登录和操作情况",
            PreviewRows = 100,
            Status = 1,
            // SQL 模板：Lua 脚本生成 SQL
            SqlTemplate = @"
                local sql = 'SELECT u.user_name, u.last_login_time, d.dept_name FROM sys_user u LEFT JOIN sys_dept d ON u.dept_id = d.id WHERE 1=1'

                if params.dept_id then
                    sql = sql .. ' AND u.dept_id = @dept_id'
                end

                if params.start_time then
                    sql = sql .. ' AND u.last_login_time >= @start_time'
                end

                return sql
            ",
            // 列转换脚本：定义转换函数
            LuaScript = @"
                function FormatDateTime(value)
                    if value and value ~= '' then
                        return string.sub(value, 1, 19)
                    end
                    return '从未登录'
                end
            "
        };

        return await _configService.SaveConfigAsync(config);
    }

    // 配置列映射和转换
    public async Task ConfigureColumns(long reportId)
    {
        var columns = new List<DbReportColumnConfig>
        {
            new DbReportColumnConfig
            {
                ColumnName = "user_name",
                DisplayName = "用户名",
                SortNo = 1,
                ConverterType = "None"  // 不转换，原值输出
            },
            new DbReportColumnConfig
            {
                ColumnName = "last_login_time",
                DisplayName = "最后登录时间",
                SortNo = 2,
                ConverterType = "LuaScript",
                ConverterConfig = "FormatDateTime(value)"  // 调用 Lua 函数转换
            },
            new DbReportColumnConfig
            {
                ColumnName = "dept_name",
                DisplayName = "所属部门",
                SortNo = 3,
                ConverterType = "ValueMap",
                ConverterConfig = "{\"技术部\":\"研发部\",\"市场部\":\"营销部\"}"  // 值映射
            }
        };

        await _configService.SaveColumnConfigsAsync(reportId, columns);
    }
}

第二步：预览和导出

using Cyclops.Reporting.Dynamic.Models;
using Cyclops.Reporting.Dynamic.Services;

public class ReportController
{
    private readonly DynamicReportService _reportService;

    public ReportController(DynamicReportService reportService)
    {
        _reportService = reportService;
    }

    // 预览报表
    public async Task<IActionResult> Preview([FromBody] ReportPreviewInput input)
    {
        var dataTable = await _reportService.PreviewAsync(
            reportConfigId: input.ReportConfigId,
            sqlParams: input.SqlParameters,
            previewRows: 50  // 预览前 50 行
        );

        return Ok(dataTable);
    }

    // 导出报表
    public async Task<IActionResult> Export([FromBody] ReportExportInput input)
    {
        var stream = await _reportService.ExportAsync(
            reportConfigId: input.ReportConfigId,
            sqlParams: input.SqlParameters,
            format: ExportFormat.Excel  // 或 ExportFormat.CSV
        );

        var fileName = $"报表_{DateTime.Now:yyyyMMddHHmmss}.xlsx";
        return File(stream, "application/octet-stream", fileName);
    }
}

第三步：前端调用

// 预览报表
const previewData = {
    reportConfigId: 1,
    sqlParameters: {
        dept_id: 1001,
        start_time: "2024-01-01"
    }
};

fetch('/api/report/preview', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(previewData)
})
.then(response => response.json())
.then(data => console.log('预览结果:', data));

// 导出报表
const exportData = {
    reportConfigId: 1,
    sqlParameters: { dept_id: 1001 },
    format: "Excel"
};

fetch('/api/report/export', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(exportData)
})
.then(response => response.blob())
.then(blob => {
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = '报表.xlsx';
    a.click();
});

🌐 Lua 脚本示例：调用外部接口

在列转换脚本中调用外部接口获取数据：

-- 调用用户服务获取用户姓名
function GetUserName(userId)
    if not userId or userId == '' then
        return ''
    end

    local resp = http_get('https://api.example.com/users/' .. userId)
    if resp then
        return resp
    end

    return '未知用户'
end

-- 调用部门服务获取部门名称
function GetDeptName(deptId)
    if not deptId or deptId == '' then
        return ''
    end

    local resp = http_get('https://api.example.com/depts/' .. deptId)
    if resp then
        return resp
    end

    return '未知部门'
end

📂 项目结构

Cyclops.Reporting/
├── Core/                              # 静态报表核心
│   ├── ReportBase.cs                  # 报表基类
│   ├── ReportColumn.cs                # 列信息模型
│   ├── ReportCsv.cs                   # CSV 导出实现
│   └── ReportExcel.cs                 # Excel 导出实现
├── Dynamic/                           # 动态报表模块
│   ├── Entities/
│   │   ├── DbReportConfig.cs          # 报表配置实体
│   │   └── DbReportColumnConfig.cs    # 列配置实体
│   ├── Models/
│   │   ├── EnumConverterType.cs       # 转换类型枚举
│   │   ├── ExportFormat.cs            # 导出格式枚举
│   │   ├── ReportPreviewInput.cs      # 预览请求模型
│   │   ├── ReportExportInput.cs       # 导出请求模型
│   │   └── DynamicReportResult.cs     # 报表结果模型
│   ├── Services/
│   │   ├── LuaScriptEngine.cs         # Lua 脚本引擎
│   │   ├── DynamicReportService.cs    # 动态报表服务
│   │   └── ReportConfigService.cs     # 配置管理服务
│   └── Repository/
│       └── DynamicReportRepository.cs # 数据访问层
├── Attrs/
│   ├── ReportDescriptionAttribute.cs  # 列描述特性
│   └── ReportIgnoreAttribute.cs       # 忽略特性
├── Extensions/
│   └── ServiceCollectionExtensions.cs # DI 扩展方法
└── Report.cs                          # 静态报表入口

📊 版本信息

• 当前版本：
• 作者：yswenli
• 描述：企服版框架中报表生成组件，支持静态泛型报表和动态 SQL 报表

👥 贡献者

• yswenli：核心开发者

📄 许可证

保留所有权利

🎉 结语

Cyclops.Reporting 致力于为您的应用程序提供灵活、高效的报表生成能力。无论是简单的数据导出，还是复杂的动态报表系统，我们都能满足您的需求。

我们相信，通过简化报表生成的复杂性，您可以更专注于业务逻辑的实现，构建出更具洞察力的数据分析和展示应用。

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

（注：文档部分内容可能由 AI 生成）