TJC.Cyclops.Reporting 2025.10.28.1

Cyclops.Framework

Cyclops.Framework 基于aspnetcore封装的api框架，集成了一线开发的常用设置和基础功能；可以用较少的时间代价，让开发人员将精力更多地集中在业务上。

• [√] 全局api调用和框架级异常日志，支持Swagger接口文档的查看、调试和代码生成
• [√] 接口入参校验，Cyclops.Framework中的接口参数校验完全基于System.ComponentModel.DataAnnotations，且在此基础上提供了验证数据是否存在ExistAttribute等扩展功能
• [√] 统一返回值，无论是使用Cyclops.Framework中的Result及其子类，或者CSharp中的裸类型都自动返回全局统一值，从框架上避免对接混乱
• [√] 标准化快捷文件上传、下载和excel的导入、导出，支持MS Azure和阿里OSS
• [√] 在安全方面集成jwt认证和SafeComparisonFilter防重放攻击，并且支持多租户权限
• [√] 标准化配置，支持Nacos

一、配置示例

{
  "HostingOptions": {
    
    "ServiceName": "Cyclops.WebApplication1",
    "Domain": "https://cyclops.yswenli.com/",
    "EnableHealthCheck": true,
    "AppOptions": {
      "Urls": [ "https://127.0.0.1:39654" ],
      "DisableSwagger": false,
      "HideConsoleLog": false,      
      //jwt TokenManagement
      "JwtAuthConfig": {
        "Secret": "base64:HU8MlQQDHfGaQ+k+0q3z4HKJvNQUTjK5uRGodDATyKc=",
        "Issuer": "yswenli.cnblogs.com",
        "Audience": "Cyclops.Framework",
        "AccessExpiration": 315576000
      },
      "MaxRequestSize": 134217728, //134217728,文件限制128M
      "UserStaticPath": true,
      "StaticPaths": [ "upload" ],
      //全局禁用防复放校验
      "DisableSafeComparisonFilter": false,
      "SafeComparisonExpired": 5,
      //全局验证码
      "GloabVerifyCode": "9365",
      //是否启用SignalR
      "EnableSignalR": true,
      //SignalR配置
      "SignalROptions": {
        //SignalR hub url
        "HubUrl": "/hubs/common",
        //握手超时时间
        "HandshakeTimeout": 30,
        //心跳间隔时间
        "KeepAliveInterval": 15,
        //空连接超时时间
        "FreeTimeout": 60,
        //每连接并行处理数量
        "ParallelCount": "1",
        //消息包大小
        "MaximumReceiveMessageSize": 32768
      }
    },
    "NacosConfig": {
      "Listeners": [
        {
          "Optional": false,
          "DataId": "Common",
          "Group": "DEFAULT_GROUP"
        },
        {
          "Optional": false,
          "DataId": "OperationService",
          "Group": "DEFAULT_GROUP"
        }
      ],
      "Namespace": "dev",
      "ServerAddresses": [ "http://127.0.0.1:8848" ],
      "UserName": "",
      "Password": "",
      "ConfigUseRpc": false,
      "NamingUseRpc": false
    }
  }
}

AppConfig节点以下的可以与nacos集成 其它各项如下：

"SnowId": {
  "WorkerId": 1, // 机器码 全局唯一
  "WorkerIdBitLength": 1, // 机器码位长 默认值6，取值范围 [1, 19]
  "SeqBitLength": 6 // 序列数位长 默认值6，取值范围 [3, 21]（建议不小于4，值越大性能越高、Id位数也更长）
},
//详细数据库配置见SqlSugar官网（第一个为默认库）
"DbConnectionOptions": {
  "EnableConsoleSql": true, // 启用控制台打印SQL
  "EnableDBLogs": true, // 启用日志入库
  "ConnectionConfigs": [
    {
      "ConfigId": "1300000000001", // 默认库标识-禁止修改
      //"DbType": "SqlServer", // MySql、SqlServer、Sqlite、Oracle、PostgreSQL、Dm、Kdbndp、Oscar、MySqlConnector、Access、OpenGauss、QuestDB、HG、ClickHouse、GBase、Odbc、Custom
      //"ConnectionString": "Data Source=10.10.0.214;Initial Catalog=tjc_dev_cyclopsdb;User Id=testuser;Password=testuser;Encrypt=True;TrustServerCertificate=True;",
      "DbType": "Sqlite",
      "ConnectionString": "Data Source=TJCES.Cyclops.db",
      "DbSettings": {
        "EnableInitDb": true, // 启用库初始化
        "EnableDiffLog": true, // 启用库表差异日志
        "EnableUnderLine": true // 启用驼峰转下划线
      },
      "TableSettings": {
        "EnableInitTable": true, // 启用表初始化
        "EnableIncreTable": false // 启用表增量更新-特性[IncreTable]
      },
      "SeedSettings": {
        "EnableInitSeed": true, // 启用种子初始化
        "EnableIncreSeed": false // 启用种子增量更新-特性[IncreSeed]
      }
    }
    // 日志独立数据库配置
    //,{
    //  "ConfigId": "1300000000002", // 日志库标识-禁止修改
    //  "DbType": "Sqlite",
    //  "ConnectionString": "DataSource=./TJCES.Cyclops.Log.db", // 库连接字符串
    //  "DbSettings": {
    //    "EnableInitDb": true, // 启用库初始化
    //    "EnableDiffLog": false, // 启用库表差异日志
    //    "EnableUnderLine": false // 启用驼峰转下划线
    //  },
    //  "TableSettings": {
    //    "EnableInitTable": true, // 启用表初始化
    //    "EnableIncreTable": false // 启用表增量更新-特性[IncreTable]
    //  },
    //  "SeedSettings": {
    //    "EnableInitSeed": false, // 启用种子初始化
    //    "EnableIncreSeed": false // 启用种子增量更新-特性[IncreSeed]
    //  }
    //}
    //// 其他数据库配置（可以配置多个）
    //,{
    //  "ConfigId": "test", // 库标识
    //  "DbType": "Sqlite", // 库类型
    //  "ConnectionString": "DataSource=./TJCES.Cyclops.Test.db", // 库连接字符串
    //  "DbSettings": {
    //    "EnableInitDb": true, // 启用库初始化
    //    "EnableDiffLog": false, // 启用库表差异日志
    //    "EnableUnderLine": false // 启用驼峰转下划线
    //  },
    //  "TableSettings": {
    //    "EnableInitTable": true, // 启用表初始化
    //    "EnableIncreTable": false // 启用表增量更新-特性[IncreTable]
    //  },
    //  "SeedSettings": {
    //    "EnableInitSeed": true, // 启用种子初始化
    //    "EnableIncreSeed": false // 启用种子增量更新-特性[IncreSeed]
    //  }
    //}
  ]
}

//图形验证码
"CaptchaOptions": {
  "CaptchaType": 2, // 验证码类型0、1、2、3、4、5、6、7、8、9、10、11
  "CodeLength": 4, // 验证码长度, 要放在CaptchaType设置后  当类型为算术表达式时，长度代表操作的个数, 例如2
  "ExpirySeconds": 60, // 验证码过期秒数
  "IgnoreCase": true, // 比较时是否忽略大小写
  "StoreageKeyPrefix": "", // 存储键前缀
  "ImageOption": {
    "Animation": false, // 是否启用动画
    "FontSize": 36, // 字体大小
    "Width": 150, // 验证码宽度
    "Height": 50, // 验证码高度
    "BubbleMinRadius": 5, // 气泡最小半径
    "BubbleMaxRadius": 10, // 气泡最大半径
    "BubbleCount": 3, // 气泡数量
    "BubbleThickness": 1.0, // 气泡边沿厚度
    "InterferenceLineCount": 3, // 干扰线数量
    "FontFamily": "kaiti", // 包含actionj,epilog,fresnel,headache,lexo,prefix,progbot,ransom,robot,scandal,kaiti
    "FrameDelay": 300, // 每帧延迟,Animation=true时有效, 默认300
    "BackgroundColor": "#ffffff", //  格式: rgb, rgba, rrggbb, or rrggbbaa format to match web syntax, 默认#fff
    "ForegroundColors": "", //  颜色格式同BackgroundColor,多个颜色逗号分割，随机选取。不填，空值，则使用默认颜色集
    "Quality": 100, // 图片质量（质量越高图片越大，gif调整无效可能会更大）
    "TextBold": true // 粗体
  },
  "DefaultCode": "9365"
}

//redis配置
"RedisOptions": {
  "SectionName": "Redis",
  "Type": 0,
  "Password": "12321",
  "Masters": "127.0.0.1:6379",
  "Slaves": null,
  "ServiceName": "mymaster",
  "DefaultDatabase": 0,
  "AllowAdmin": true,
  "KeepAlive": 180,
  "ConnectTimeout": 10000,
  "ConnectRetry": 1,
  "BusyRetry": 3,
  "BusyRetryWaitMS": 15000,
  "PoolSize": 1,
  "CommandTimeout": 60000,
  "Extention": null
}

//微信公众号/小程序
"WechatOptions": {
  // 公众号-正式版公众测试号
  "WechatAppId": "",
  "WechatAppSecret": "",
  // 小程序
  "WxOpenAppId": "",
  "WxOpenAppSecret": "",
  //企业微信
  "WechatCorpOptions": {
    "Type": 0,
    "CorpId": "",
    "SelfAppOptions": {
      "AgentId": ,
      "AgentSecret": "",
      "PushToken": "",
      "PushEncodingAESKey": ""
    },
    "DevelopersOptions": {
      "ProviderSecret": "",
      "PushToken": "",
      "PushEncodingAESKey": "",
      "SuiteOptions": [
          {
            "SuiteId": null,
            "SuiteSecret": null,
            "SuitePushToken": null,
            "SuitePushEncodingAESKey": null
          }
      ]
    },
    "SmartHardwareOptions": {
      "ModelId": null,
      "ModelSecret": null,
      "PushToken": null,
      "PushEncodingAESKey": null
    }
  }
},
// 微信支付
"WechatPayOptions": {
  "AppId": "", // 微信公众平台AppId、开放平台AppId、小程序AppId、企业微信CorpId
  "MerchantId": "", // 商户平台的商户号
  "MerchantV3Secret": "", // 商户平台的APIv3密钥
  "MerchantCertificateSerialNumber": "", // 商户平台的证书序列号
  "MerchantCertificatePrivateKey": "/WxPayCert/apiclient_key.pem", // 商户平台的API证书私钥(apiclient_key.pem文件内容)
  "WechatPayUrl": "/api/sysWechatPay/payCallBack" // 微信支付回调
}

//上传文件
"UploadOptions": {
  "Path": "upload/{yyyy}/{MM}/{dd}", // 文件上传目录
  "MaxSize": 5368709120, // 文件最大限制128M
  "MemoryBufferThreshold": 10485760, // 内存缓冲区大小,65536 64k
  "ExtensionNames": [ ".jpg", ".jpeg", ".png", ".gif", ".bmp", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".pdf", ".txt", ".zip", ".rar", ".7z" ],
  "EnableMd5": true, // 启用文件MDF5验证-防止重复上传
  "EnableCloudStorage": false, // 启用云存储
  //ms azure
  //"CloudStorageOptions": {
  //  "Id": "",
  //  "Key": "",
  //  "SupplierType": 2,
  //  "ContainerName": "",
  //  "Endpoint": "core.chinacloudapi.cn",
  //  "TimeOut": 60,
  //  "MaxErrorRetry": 3
  //}
  //阿里云
  "CloudStorageOptions": {
    "Id": "",
    "Key": "",
    "SupplierType": 1,
    "ContainerName": "cyclops",
    //"Endpoint": "oss-cn-shanghai-internal.aliyuncs.com",
    "Endpoint": "oss-cn-shanghai.aliyuncs.com",
    "TimeOut": 60,
    "MaxErrorRetry": 3
  }
}

//短信
"SmsOption": {
  "ZhuTong": {
    "UserName": "",
    "Password": "",
    "Signature": "【Cyclops管理平台】"
  }
}

//直播配置
"LiveOption": {
  "AppId": "",
  "AppSecret": "",
  "Url": "",
  "AuthorizeUrl": "",
  "AuthSecret": null,
  "UserName": null,
  "Password": null,
  "Salt": null
}

//语音转换
"SpeechConfig": {
  "SpeechType": 1,
  "ClientId": "",
  "ClientSecret": ""
}

//电子邮件
"EMailOptions": {
  "EMailClientConfigs": [
    {
      //发送邮件
      "ClientType": 1,
      //服务器
      "Host": "",
      //端口
      "Port": 465,
      //是否启用SSL
      "UseSsl": true,
      //用户名
      "Username": "",
      //密码
      "Password": ""
    }
  ]
}

/**轻流配置文件**/
"QingflowOptions": {
  //轻流api
  "Domain": "https://api.qingflow.com", 
  //工作空间id
  "WorkspaceId": "",
  //工作空间密钥
  "WorkspaceSecret": "",
  //超管Token
  "SuperAdminToken": ""
}

二、初始化代码示例

public class Program
{
    public static void Main(string args)
    {
        WebApp.OnStarted += WebApp_OnStarted;
        WebApp.OnStopped += WebApp_OnStopped;
        WebApp.RunWebHost<Startup>(args);
    }


    static void WebApp_OnStarted()
    {
        Logger.Info($"{WebApp.ServiceName}应用已启动");
    }


    static void WebApp_OnStopped()
    {
        Logger.Info($"{WebApp.ServiceName}应用已停止");
    }
}

    /// <summary>
    /// Startup
    /// </summary>
    public class Startup : BaseStartup
    {
        /// <summary>
        /// Startup
        /// </summary>
        /// <param name="configuration"></param>
        public Startup(IConfiguration configuration) : base(configuration)
        {

        }
    }

三、控制器示例

继承基类即可

[Route(RouteConst.ROUTE_TEMPLATE_MOBILE)]
public class AuthController : BaseApiController

方法示例

    /// <summary>
    /// Login
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    [AllowAnonymous, HttpPost, DisplayName("Login")]
    public async Task<Result> Login([Required(ErrorMessage = "请输入用户名或密码"), FromBody] UserLoginInput input)
    {
        var user = new SysUser();
        return SuccessResult(await CreateToken(user));
    }

    /// <summary>
    /// 获取验证码
    /// </summary>
    /// <returns></returns>
    [AllowAnonymous]
    [SuppressMonitor]
    [DisplayName("获取验证码"), HttpGet]
    public Result GetCaptcha()
    {
        ICaptcha captcha = ServiceProviderUtil.GetRequiredService<ICaptcha>();
        var codeId = YitIdHelper.NextId().ToString();
        var captchas = captcha.Generate(codeId, 180);
        return SuccessResult(new { Id = codeId, Img = captchas.Base64 });
    }

四、集成数据校验

/// <summary>
/// 登录信息
/// </summary>
public class UserLoginInput
{
    /// <summary>
    /// 请输入用户名
    /// </summary>
    [Required(ErrorMessage = "请输入用户名"), Exists("用户名不存在", TableName = "bus_user", ColumnName = "user_name")]
    public string UserName { get; set; }
    /// <summary>
    /// 请输入密码
    /// </summary>
    [Required(ErrorMessage = "请输入密码"), Custom<UserLoginInput>("密码不正确", "Valide")]
    public string Password { get; set; }

    /// <summary>
    /// 验证密码
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    public bool Valide(object? input)
    {
        if (input == null) return false;
        if (input is string password && password == "123456")
        {
            return true;
        }
        return false;

    }
}

五、防重放攻击示例

    /// <summary>
    /// 接口安全参数校验测试
    /// </summary>
    [SafeComparisonFilter]
    public class SafeController : BaseApiController
    {
        /// <summary>
        /// Test
        /// </summary>
        /// <param name="testInfo"></param>
        /// <returns></returns>
        [HttpPost]
        public Result Test([FromBody] TestInfo testInfo)
        {
            return SuccessResult(testInfo);
        }

        /// <summary>
        /// test2
        /// </summary>
        /// <returns></returns>
        [HttpGet, AllowAnonymous, NoSafeComparisonFilter]
        public Result Test2()
        {
            return SuccessResult();
        }
    }

六、文件上传下载Excel导入导出示例

   public class FileAdminController : BaseApiController
   {
       /// <summary>
       /// 导入
       /// </summary>
       /// <returns></returns>
       [HttpPost]
       [NoLoginAuth, AllowAnonymous]
       public Result Import(IFormCollection collection)
       {
           var data = collection.SaveAsDataTable();
           return SuccessResult(data);
       }


       /// <summary>
       /// 导出
       /// </summary>
       /// <returns></returns>
       [HttpPost]
       [NoLoginAuth, AllowAnonymous]
       public IActionResult Export()
       {
           return _env.Download("export.png");
       }

       /// <summary>
       /// 导出数据文件
       /// </summary>
       /// <returns></returns>
       [HttpGet]
       [NoLoginAuth, AllowAnonymous]
       public IActionResult ExportFile([FromQuery] bool isExcel = false)
       {
           var fileName = "export.xlsx";
           if (!isExcel)
           {
               fileName = "export.csv";
           }
           var dt = new DataTable();
           //return _env.ExportFile(dt, fileName);
           return Export(dt, fileName);
       }


       /// <summary>
       /// 导出数据文件
       /// </summary>
       /// <returns></returns>
       [HttpGet]
       [NoLoginAuth, AllowAnonymous]
       public IActionResult ExportDataFile([FromQuery] bool isExcel = false)
       {
           var fileName = "export.xlsx";
           if (!isExcel)
           {
               fileName = "export.csv";
           }
           var list = new List<BusUser>
           {
               new BusUser()
               {
                   Id = 1,
                   UserName = "张三"
               }
           };
           //return _env.ExportFile(list, fileName);
           return Export(list, fileName);
       }



       /// <summary>
       /// 测试上传文件大小
       /// </summary>
       /// <returns></returns>
       [HttpPost]
       public async Task<IActionResult> UploadFile(IFormCollection form)
       {
           var fileStream = await form.SaveAsStreamsAsync();

           return fileStream.First().Value.Download("test.jpg");
       }

       /// <summary>
       /// 测试限制上传文件大小
       /// </summary>
       /// <param name="form"></param>
       /// <returns></returns>

       [HttpPost, RequestSizeLimit(2 * 1024 * 1024)]
       public async Task<IActionResult> UploadFileByLimit(IFormCollection form)
       {
           var fileStream = await form.SaveAsStreamsAsync();

           return fileStream.First().Value.Download("test.jpg");
       }

       /// <summary>
       /// 测试不限制上传文件大小
       /// </summary>
       /// <param name="form"></param>
       /// <returns></returns>

       [HttpPost, DisableRequestSizeLimit]
       public async Task<IActionResult> UploadFileByNonLimit(IFormCollection form)
       {
           var fileStream = await form.SaveAsStreamsAsync();

           return fileStream.First().Value.Download("test.jpg");
       }       

      /// <summary>
      /// 示例获取流
      /// </summary>
      /// <returns></returns>
      [HttpGet]
      public async Task<Stream> GetStream()
      {
          var ms = new MemoryStream(RandomUtil.GetBytes(1024));
          return await Task.FromResult(ms);
      }

      /// <summary>
      /// 示例获取字节数组
      /// </summary>
      /// <returns></returns>
      [HttpGet]
      public async Task<byte> GetBytes()
      {
          return await Task.FromResult(RandomUtil.GetBytes(1024));
      }
   }

七、支持非api接口内容

        /// <summary>
        /// 返回指定内容结果
        /// </summary>
        /// <param name="controller"></param>
        /// <param name="text"></param>
        /// <param name="contentType"></param>
        /// <param name="statusCode"></param>
        /// <returns></returns>
        public async Task<IActionResult> ContentAsync(string text, string contentType = "text/plain", int statusCode = 200)
        {
            var contentResult = new ContentResult()
            {
                Content = text,
                ContentType = contentType,
                StatusCode = statusCode
            };
            return await Task.FromResult(contentResult);
        }

        /// <summary>
        /// 返回空结果
        /// </summary>
        /// <param name="controller"></param>
        /// <returns></returns>
        public async Task<IActionResult> EmptyAsync()
        {
            return await Task.FromResult(new EmptyResult());
        }

        /// <summary>
        /// 返回下载结果
        /// </summary>
        /// <param name="controller"></param>
        /// <param name="fileContent">下载时的文件名称</param>
        /// <param name="fileContent">内容字节数组</param>
        /// <param name="contentType">内容mime类型</param>
        /// <returns></returns>
        public async Task<IActionResult> DownloadAsync(string fileDownloadName,
            byte fileContent,
            string contentType)
        {
            return await Task.FromResult(new FileContentResult(fileContent, contentType) { FileDownloadName = fileDownloadName });
        }

        /// <summary>
        /// 返回下载结果
        /// </summary>
        /// <param name="controller"></param>
        /// <param name="fileName">内容文件地址</param>
        /// <param name="contentType">内容mime类型</param>
        /// <returns></returns>
        public async Task<IActionResult> DownloadAsync(string fileName,
            string contentType)
        {
            return await Task.FromResult(new VirtualFileResult(fileName, contentType)
            {
                EnableRangeProcessing = true,
                FileDownloadName = PathUtil.GetFileName(fileName)
            });
        }
        /// <summary>
        /// 返回流结果
        /// </summary>
        /// <param name="controller"></param>
        /// <param name="fileDownloadName"></param>
        /// <param name="fileStream"></param>
        /// <param name="contentType"></param>
        /// <returns></returns>
        public async Task<IActionResult> DownloadAsync(string fileDownloadName,
            Stream fileStream,
            string contentType
            )
        {
            return await Task.FromResult(new FileStreamResult(fileStream, contentType)
            {
                EnableRangeProcessing = true,
                FileDownloadName = fileDownloadName
            });
        }
        /// <summary>
        /// 返回跳转结果
        /// </summary>
        /// <param name="controller"></param>
        /// <param name="url"></param>
        /// <returns></returns>
        public async Task<IActionResult> RedirectAsync(string url)
        {
            return await Task.FromResult(new RedirectResult(url));
        }