TJC.Cyclops.Reporting 2026.6.11.2

📊 Cyclops.Reporting

📖 项目概述

Cyclops.Reporting 是 Cyclops.Framework 框架中的报表生成组件，提供两种报表模式：

• 静态报表：基于泛型 List<T>，通过特性标注快速导出 CSV/Excel
• 动态报表：基于数据库配置 + Lua 列转换脚本，支持运行时 SQL 查询与灵活的数据转换

🎯 核心功能

静态报表

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

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

动态报表

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

• 报表配置持久化到数据库（db_report_config 表）
• SQL 模板直接编写纯 SQL，支持参数化查询防注入
• 列配置持久化到数据库（db_report_column_config 表）
• 三种列转换方式：None（原值输出）、ValueMap（JSON 值映射）、LuaScript（Lua 脚本转换）
• 支持预览前 N 行数据
• 支持导出为 CSV 和 Excel 格式
• 自动检测重复列名并提示使用别名

Lua 脚本引擎内置函数

🛠️ 技术栈

• .NET 8.0
• MoonSharp v2.0.0 - Lua 脚本引擎
• SqlSugar - 通过 Cyclops.Orm 封装的 ORM
• Cyclops.Common - 框架核心组件（CsvUtil、ExcelUtil 等）

📦 安装

Install-Package TJC.Cyclops.Reporting

🚀 快速开始

1. 注册服务

using Cyclops.Reporting.Extensions;

builder.Services.AddCyclopsReporting();

注册的服务：

• LuaScriptEngine - Singleton（全局复用）
• DynamicReportService - Scoped
• ReportConfigService - Scoped
• DynamicReportRepository - Scoped

2. 静态报表示例

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

// 定义数据模型
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; }
}

// 准备数据并导出
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 = "市场部" }
};

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

3. 动态报表示例

创建报表配置

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 模板：纯 SQL，支持参数化查询
            SqlTemplate = @"
                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
                AND (@dept_id IS NULL OR u.dept_id = @dept_id)
                AND (@start_time IS NULL OR u.last_login_time >= @start_time)
            ",
            // 列转换 Lua 脚本：定义转换函数
            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)"
            },
            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
        );

        return Ok(dataTable);
    }

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

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

4. Lua 列转换脚本示例

4.1 基础转换示例

-- 示例1：头像转 HTML 标签
if value ~= nil and type(value) == "string" and value ~= "" then
    return string_format('<img src="https://www.nuget.org/%s" width=25 />', {value})
end
return ""

-- 示例2：金额格式化
local amount = tonumber(value) or 0
if amount > 0 then
    return string_format('%.2f 元', {amount / 100})
end
return '0.00 元'

-- 示例3：日期截取
if value and #value >= 10 then
    return string.sub(value, 1, 10)
end
return value or ""

4.2 通过 userid 获取用户姓名（带认证的 POST 请求）

接口信息

• 地址：POST https://api.example.com/user/getFullName
• 认证：Authorization: Bearer {token}
• 请求体：

{
  "userId": "88888888"
}

• 响应：

{
  "fullName": "yswenli"
}

前置条件：需通过 luaEngine.RegisterFunction 注册 auth_post(url, token, body) 自定义函数（支持 Bearer Token 认证）。

LuaScript 示例

-- 通过 userid 获取用户全名（带 Bearer Token 认证的 POST 请求）
function GetFullNameByUserId(userId)
    if not userId or userId == '' then
        return ''
    end

    -- 认证 Token（建议从配置或环境变量读取）
    local token = 'your-bearer-token-here'

    -- 构造 POST 请求体
    local requestBody = json_stringify({
        userId = userId
    })

    -- 发送带认证的 POST 请求
    local resp = auth_post('https://api.example.com/user/getFullName', token, requestBody)

    -- 解析返回结果
    if resp and resp ~= '' then
        local result = json_parse(resp)
        if result and result.fullName then
            return result.fullName
        end
    end

    return '未知用户'
end

列配置使用：ConverterType = "LuaScript"，ConverterConfig = "GetFullNameByUserId(value)"

📂 项目结构

Cyclops.Reporting/
├── Report.cs                              # 静态报表入口 Report<T>
├── GlobalUsing.cs                         # 全局 using 声明
├── Attrs/
│   ├── ReportDescriptionAttribute.cs      # 列描述特性（标题、排序、格式）
│   └── ReportIgnoreAttribute.cs           # 忽略导出特性
├── Core/                                  # 静态报表核心
│   ├── ReportBase.cs                      # 报表基类（属性解析、数据转换）
│   ├── ReportColumn.cs                    # 列信息模型
│   ├── ReportCsv.cs                       # CSV 导出实现
│   └── ReportExcel.cs                     # Excel 导出实现
├── Dynamic/                               # 动态报表模块
│   ├── Entities/
│   │   ├── DbReportConfig.cs              # 报表配置实体（db_report_config 表）
│   │   └── DbReportColumnConfig.cs        # 列配置实体（db_report_column_config 表）
│   ├── Models/
│   │   ├── EnumConverterType.cs           # 转换类型枚举（None/ValueMap/LuaScript）
│   │   ├── ExportFormat.cs                # 导出格式枚举（CSV/Excel）
│   │   ├── ReportPreviewInput.cs          # 预览请求参数
│   │   ├── ReportExportInput.cs           # 导出请求参数
│   │   └── DynamicReportResult.cs         # 动态报表结果模型
│   ├── Services/
│   │   ├── LuaScriptEngine.cs             # Lua 脚本引擎（MoonSharp 封装）
│   │   ├── DynamicReportService.cs        # 动态报表服务（预览、导出）
│   │   └── ReportConfigService.cs         # 配置管理服务（CRUD）
│   └── Repository/
│       └── DynamicReportRepository.cs     # 数据访问层（SqlSugar）
├── Extensions/
│   └── ServiceCollectionExtensions.cs     # DI 注册扩展
└── Cyclops.Reporting.csproj

📊 版本信息

• 当前版本：2026.6.11.1
• 作者：yswenli
• 描述：用于泛型列表数据导出指定格式数据快捷工具集合

📄 许可证

保留所有权利