👁 Image
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="%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
• 描述：用于泛型列表数据导出指定格式数据快捷工具集合

📄 许可证

保留所有权利