RuoVea.OmiApi.Config 10.0.0.7

RuoVea.OmiApi.Config

系统配置管理 —— 高性能、可缓存的参数配置 API NuGet 包。

目录

• 概览
• 安装
• 30 秒快速开始
• 核心场景
• 配置选项详解
• API 接口速览
• 错误处理与日志
• 版本迁移指南
• 常见问题

概览

RuoVea.OmiApi.Config 是一个即装即用的 NuGet 包，为 .NET 应用提供系统级参数配置的完整管理能力。它封装了从数据库自动建表、种子数据填充、RESTful API 暴露到缓存加速的全流程，开发者仅需一行注册即可获得生产级的配置中心。

核心特性一览

架构概览

+-----------------------------------------------------------+
|                      Swagger UI                           |
|               GroupName = "system"                        |
+-----------+-----------+-----------+-----------+-----------+
            |           |           |           |
     GET /api/SysConfig/GetPagesAsync      分页查询
     GET /api/SysConfig/GetDataAsync       单条查询
    POST /api/SysConfig/AddDataAsync       添加
     PUT /api/SysConfig/UpdateDataAsync    修改
  DELETE /api/SysConfig/DeleteDataAsync    删除
    POST /api/SysConfig/BatchDelete        批量删除
     GET /api/SysConfig/GetConfigCache     缓存读取
     GET /api/SysConfig/GetConfigCaches    批量缓存读取
     GET /api/SysConfig/GetConfig          数据库直读
     GET /api/SysConfig/GetConfigs         批量数据库直读
     GET /api/SysConfig/GetDemoEnvFlag     演示环境开关 [AllowAnonymous]
     GET /api/SysConfig/GetGroupList       分组列表
            |           |           |           |
+-----------+-----------+-----------+-----------+-----------+
|                    SysConfigService                       |
|         (IApplicationService via DynamicWebApi)           |
+-----------+------------------------------+---------------+
            |                              |
+-----------v-----------+       +----------v-----------+
|    CacheFactery.Cache |       |  SugarRepository     |
|  (Redis / Memory)     |       |  <SysConfig>         |
|  Key: sys_config:{code} |     |  (SqlSugar ORM)      |
+-----------------------+       +----------+-----------+
                                           |
                              +------------v-----------+
                              |     SysConfig 表       |
                              |  MySql/SqlServer/      |
                              |  SQLite/Pg/Oracle ...  |
                              +------------------------+

数据模型

SysConfig (参数配置表)  ──继承──>  EntityBase (基础字段)
                     │               ├── Id, CreateTime, UpdateTime
                     │               ├── IsDelete (软删除)
                     │               └── CreateUserId, UpdateUserId, ...
                     │
                     └──实现──>  ITenantEntity
                                   └── TenantId (多租户隔离)

安装

.NET 8.0

dotnet add package RuoVea.OmiApi.Config --version 8.0.0.22

Install-Package RuoVea.OmiApi.Config -Version 8.0.0.22

.NET 10.0

dotnet add package RuoVea.OmiApi.Config --version 10.0.0.4

Install-Package RuoVea.OmiApi.Config -Version 10.0.0.4

依赖项：RuoVea.DynamicWebApi, RuoVea.ExSugar, RuoVea.ExConfig, RuoVea.ExUtil, RuoVea.ExDto, RuoVea.ExEnum, RuoVea.ExCache, SqlSugar, Mapster

30 秒快速开始

1. 数据库配置（appsettings.json）

{
  "ConnectionConfigs": [
    {
      "DbType": "Sqlite",
      "ConnectionString": "DataSource=./ruovea.db"
    }
  ],
  "DbInitConfig": {
    "InitTable": true,
    "InitSeedData": true
  },
  "Swagger": {
    "ApiVersions": [
      {
        "Title": "系统应用",
        "Version": "system"
      }
    ]
  }
}

2. Program.cs 注册

// <summary>
// 注册 DynamicWebApi 动态 API 组件（生产环境添加 /openapi/api 前缀）
// </summary>
if (builder.Environment.IsProduction())
{
    builder.Services.AddDynamicWebApi(options =>
    {
        options.DefaultApiPrefix = "/openapi/api";
        options.RemoveControllerPostfixes = new List<string> { "AppService", "Service" };
        options.RemovePrefix = new List<string> { "get", "post" };
    });
}
else
{
    builder.Services.AddDynamicWebApi(options =>
    {
        options.RemoveControllerPostfixes = new List<string> { "AppService", "Service" };
        options.RemovePrefix = new List<string> { "get", "post" };
    });
}

// <summary>
// 注册 ORM（SqlSugar），需配合 RuoVea.ExSugar 或自行注册 ISqlSugarClient
// </summary>
builder.Services.AddSqlSugarSetup();

// <summary>
// 注册系统配置服务，默认 Scoped 生命周期
// </summary>
builder.Services.AddOmiConfigSetup();

// <summary>
// 初始化数据库表结构与种子数据（异步后台执行）
// </summary>
builder.Services.AddConfigInitSetup();

3. 启动并访问 Swagger

启动项目后，访问 Swagger UI（默认 /swagger），在下拉列表中选择 "系统应用" 分组即可看到所有配置管理 API。

核心场景

场景一：参数配置 CRUD 管理

完整的增删改查 + 批量删除 + 分页查询能力，所有接口自动暴露为 RESTful API。

+--------+       +-------------------+       +-------------+
| Client | ----> | SysConfigService  | ----> |   数据库     |
+--------+  REST +-------------------+  ORM  +-------------+
                  |  AddDataAsync      |       | INSERT      |
                  |  UpdateDataAsync   |       | UPDATE      |
                  |  DeleteDataAsync   |       | SOFT DELETE |
                  |  BatchDelete       |       | BULK DELETE |
                  |  GetPagesAsync     |       | SELECT PAGE |
                  |  GetDataAsync      |       | SELECT ONE  |
                  +-------------------+       +-------------+

// <summary>
// 分页查询参数配置
// </summary>
public async Task<PageResult<SysConfigDto>> QueryConfigsAsync()
{
    var param = new SysConfigParam
    {
        PageNo = 1,
        PageSize = 20,
        GroupCode = "Default"
    };
    // 异步方式
    return await _sysConfigService.GetPagesAsync(param);

    // 同步方式
    // return _sysConfigService.GetPagesAsync(param).GetAwaiter().GetResult();
}

// <summary>
// 添加一条配置记录
// </summary>
public async Task<bool> AddConfigAsync()
{
    var input = new SysConfigInputDto
    {
        Name = "日志保留天数",
        Code = "log_retention_days",
        Value = "30",
        SysFlag = YesOrNot.N,
        GroupCode = "Log",
        Sort = 10
    };
    // 异步方式
    return await _sysConfigService.AddDataAsync(input);

    // 同步方式
    // return _sysConfigService.AddDataAsync(input).GetAwaiter().GetResult();
}

// <summary>
// 批量删除配置（自动过滤系统参数）
// </summary>
public async Task BatchDeleteConfigsAsync(List<long> ids)
{
    // ⚠️ 系统参数 (SysFlag=Y) 会被自动排除，不会被删除
    await _sysConfigService.BatchDelete(ids);
}

场景二：缓存优先的配置读取（Cache-Aside）

高并发场景下推荐使用带缓存的读取方法，避免频繁访问数据库。内置 Cache-Aside 模式：缓存命中直接返回，未命中则查库并回填缓存。

+--------+     +-------------------+     +-------------+     +-------------+
| Client | --> | GetConfigCache()  | --> |  缓存层      | --> |   数据库     |
+--------+     +-------------------+     +-------------+     +-------------+
                      |                     |   命中?               ^
                      |                     +---YES---> 返回        |
                      |                     |                       |
                      |                     +---NO----> 查库 ------+
                      |                                回填缓存
                      |                                    |
                      +<---- 返回 value -------------------+

// <summary>
// 从缓存读取单个配置值
// </summary>
public async Task<string> ReadConfigWithCacheAsync()
{
    // 异步方式
    var demoFlag = await _sysConfigService.GetConfigCache("dilon_demo_env_flag");
    return demoFlag;

    // 同步方式
    // var demoFlag = _sysConfigService.GetConfigCache("dilon_demo_env_flag").GetAwaiter().GetResult();
    // return demoFlag;
}

// <summary>
// 批量从缓存读取多个配置（减少 IO 次数）
// </summary>
public async Task<Dictionary<string, string>> ReadConfigsWithCacheBatchAsync()
{
    var codes = new[] { "dilon_demo_env_flag", "dilon_captcha_open", "sys_oplog" };

    // 异步方式
    var dict = await _sysConfigService.GetConfigCaches(codes);
    // 返回: { "dilon_demo_env_flag": "false", "dilon_captcha_open": "false", ... }
    return dict;

    // 同步方式
    // return _sysConfigService.GetConfigCaches(codes).GetAwaiter().GetResult();
}

// <summary>
// 泛型类型转换：直接从缓存获取并转为目标类型
// </summary>
public async Task<bool> ReadConfigAsBoolAsync()
{
    // 异步方式
    var isDemoEnv = await _sysConfigService.GetConfigValueCache<bool>("dilon_demo_env_flag");
    return isDemoEnv;

    // 同步方式
    // return _sysConfigService.GetConfigValueCache<bool>("dilon_demo_env_flag").GetAwaiter().GetResult();
}

// <summary>
// ⚠️ 缓存一致性：修改/删除配置时会自动失效对应缓存键
// </summary>
public async Task UpdateConfigWithCacheInvalidationAsync()
{
    var input = new SysConfigInputDto
    {
        Id = 142307070902374,
        Code = "dilon_demo_env_flag",
        Value = "true"
    };
    // UpdateDataAsync 内部会自动执行:
    // 1. 更新数据库
    // 2. await CacheFactery.Cache.WriteAsync("sys_config:dilon_demo_env_flag", "true")
    await _sysConfigService.UpdateDataAsync(input);
}

场景三：系统参数保护与租户隔离

内置的"系统参数不可删除"保护机制，配合多租户隔离，确保 SAAS 场景下各租户的配置数据互不影响。

+--------+       DELETE /api/SysConfig/DeleteDataAsync?id=123
| Client |  ------------------------------------------------>
+--------+                                                  |
                                                             v
                                              +-----------------------------+
                                              |      DeleteDataAsync()      |
                                              +-----------------------------+
                                                         |
                                          +--------------v--------------+
                                          |  1. 查询 config 是否存在     |
                                          |     └── 不存在? 抛出 D1002   |
                                          |                             |
                                          |  2. 检查 SysFlag == Y?       |
                                          |     └── 是? 抛出 D9001       |
                                          |        ("禁止删除系统参数")    |
                                          |                             |
                                          |  3. 执行软删除               |
                                          |  4. 删除对应缓存键            |
                                          +----------------------------+

// <summary>
// 尝试删除系统参数 —— 会被拒绝
// </summary>
public async Task AttemptDeleteSysConfigAsync()
{
    // 假设 ID 142307070902374 是 SysFlag=Y 的系统参数
    var data = new EntityBaseIdDto { Id = 142307070902374 };

    try
    {
        await _sysConfigService.DeleteDataAsync(data);
    }
    catch (ArgumentException ex)
    {
        // 捕获: "禁止删除系统参数" (D9001)
        Console.WriteLine($"删除被阻止: {ex.Message}");
    }
}

// <summary>
// 安全删除：先判断 SysFlag 再决定
// </summary>
public async Task SafeDeleteConfigAsync(long id)
{
    // 同步方式获取配置详情
    var dto = _sysConfigService.GetDataAsync(new EntityBaseIdDto { Id = id })
        .GetAwaiter().GetResult();

    if (dto.SysFlag == YesOrNot.Y)
    {
        Console.WriteLine($"配置 [{dto.Name}] 为系统参数，不可删除");
        return;
    }

    await _sysConfigService.DeleteDataAsync(new EntityBaseIdDto { Id = id });
}

场景四：分组列表查询

按 GroupCode 去重获取所有分组编码列表，适用于前端下拉选择或配置分类导航。

// <summary>
// 查询所有分组编码（去重）
// </summary>
public async Task<List<string>> GetAllGroupsAsync()
{
    // 异步方式：不传 groupCode 时返回所有去重后的 GroupCode
    var allGroups = await _sysConfigService.GetGroupList(null);
    return allGroups;

    // 同步方式
    // return _sysConfigService.GetGroupList(null).GetAwaiter().GetResult();
}

// <summary>
// 查询指定分组下的配置列表
// </summary>
public async Task<List<string>> GetSpecificGroupsAsync()
{
    // 异步方式：传入具体分组编码进行精确匹配
    var groups = await _sysConfigService.GetGroupList("Default");
    return groups;

    // 同步方式
    // return _sysConfigService.GetGroupList("Default").GetAwaiter().GetResult();
}

场景五：内置辅助方法调用

SysConfigService 内部提供了多个 [NonAction] 辅助方法，供业务模块直接注入调用：

// <summary>
// 注入 SysConfigService 后直接调用内置辅助方法
// </summary>
public class MyBusinessService
{
    private readonly SysConfigService _configService;

    /// <summary>
    /// 通过 DI 注入 SysConfigService
    /// </summary>
    public MyBusinessService(SysConfigService configService)
    {
        _configService = configService;
    }

    /// <summary>
    /// Demo：在业务逻辑中使用配置辅助方法
    /// </summary>
    public async Task DemoBusinessWithConfigAsync()
    {
        // <summary>检查演示环境开关</summary>
        bool isDemo = await _configService.GetDemoEnvFlag();

        // <summary>检查验证码开关</summary>
        bool captchaOpen = await _configService.GetCaptchaOpenFlag();

        // <summary>获取系统默认密码</summary>
        string defaultPwd = await _configService.GetDefault_Password();

        // <summary>是否开放注册</summary>
        bool enableRegister = await _configService.GetEnableRegister();

        // <summary>是否开放找回密码</summary>
        bool enableForgotPwd = await _configService.GetEnableForgotPassword();

        // <summary>是否记录操作日志</summary>
        bool sysOplog = await _configService.GetSysOplog();

        // <summary>更新配置值（内部会失效缓存）</summary>
        await _configService.UpdateConfigValue("sys_oplog", "false");
    }
}

配置选项详解

DbInitConfig 数据库初始化配置

Swagger API 版本分组

DI 注册参数

ServiceLifetime 可选值

缓存键规范

API 接口速览

所有接口归属 Swagger 分组 system，基路径由 AddDynamicWebApi 配置决定。

内置种子数据一览

错误处理与日志

错误码

异常处理示例

// <summary>
// 捕获并处理配置操作的业务异常
// </summary>
public async Task<string> HandleConfigErrorsAsync()
{
    try
    {
        var input = new SysConfigInputDto
        {
            Name = "演示环境",
            Code = "dilon_demo_env_flag", // D9000: 编码已存在
            Value = "false"
        };
        return await _sysConfigService.AddDataAsync(input) ? "添加成功" : "添加失败";
    }
    catch (ArgumentException ex)
    {
        // <summary>业务异常：唯一性冲突 (D9000)、数据不存在 (D1002)、系统参数保护 (D9001)</summary>
        Console.WriteLine($"操作被拒绝: {ex.Message}");
        return ex.Message;
    }
    catch (Exception ex)
    {
        // <summary>未预期的系统异常</summary>
        Console.WriteLine($"系统异常: {ex.Message}");
        throw;
    }
}

// <summary>
// 安全添加：预先检查是否存在同名或同编码配置（同步方式）
// </summary>
public bool SafeAddConfig(SysConfigInputDto input)
{
    // 同步方式：先查询再决定
    var existing = _sysConfigService.GetPagesAsync(new SysConfigParam
    {
        Name = input.Name,
        Code = input.Code,
        PageNo = 1,
        PageSize = 1
    }).GetAwaiter().GetResult();

    if (existing.TotalCount > 0)
    {
        Console.WriteLine($"配置 [{input.Name}] 已存在，跳过添加");
        return false;
    }

    return _sysConfigService.AddDataAsync(input).GetAwaiter().GetResult();
}

版本迁移指南

v8.0.x 升级至 v10.0.x

迁移步骤：更新目标框架至 net10.0，将 NuGet 包引用版本改为 10.0.0.4，API 接口签名与行为完全向后兼容，无需修改业务代码。

常见问题

Q: 为什么调用 GetConfigCache 返回空字符串？

A: 可能原因：配置编码不存在于数据库，或编码拼写不一致。该包使用大小写不敏感的编码查询（内部统一转小写），但仍需确保编码完全匹配种子数据或手动添加的配置记录。

Q: ⚠️ AddConfigInitSetup 使用 Task.Run 异步初始化，是否会阻塞服务启动？

A: AddConfigInitSetup 内部通过 Task.Run 在后台线程执行建表和种子数据插入，不会阻塞 WebApplication.Run()。但在极端情况下（如表结构初始化耗时过长），首次请求到达时表可能尚未就绪。建议在应用部署后确认初始化完成。

Q: ❗ 使用 Singleton 生命周期注册会有什么风险？

A: SysConfigService 内部依赖 SugarRepository<SysConfig>，该仓储通常是 Scoped 生命周期。将服务注册为 Singleton 会捕获作用域内的依赖，可能导致 DbContext 生命周期错乱或内存泄漏。强烈建议保持默认的 Scoped 注册。

Q: 修改或删除配置后缓存会自动更新吗？

A: 自动更新。UpdateDataAsync 会在更新数据库后立即写入缓存；DeleteDataAsync 会在软删除后立即删除对应缓存键。缓存键格式为 sys_config:{code_lower}。无需手动管理缓存。

Q: ⚠️ GetConfig 和 GetConfigCache 有什么区别？

A:

• GetConfig：直接查询数据库，每次调用都访问数据库。适合低频访问或需要强一致性的场景。
• GetConfigCache：Cache-Aside 模式，优先从缓存读取，缓存未命中时查库并回填。适合高并发、高频访问场景，可显著降低数据库压力。

Q: 如何添加自定义种子数据？

A: 在 appsettings.json 中设置 DbInitConfig.InitSeedData=true，然后引用 RuoVea.OmiApi.Config.SeedData 命名空间，继承 SeedDataEntity<SysConfig> 实现自定义 HasData() 方法即可。首次启动时包会自动发现并插入。

Q: 支持哪些数据库？

A: 通过 SqlSugar 支持的数据库均可用，包括：MySql, SqlServer, PostgreSQL, SQLite, Oracle, Dm, Kdbndp, OpenGauss, ClickHouse, GBase, QuestDB, Access, Odbc 等。在 ConnectionConfigs[].DbType 中配置即可。

Q: ❗ 批量删除 (BatchDelete) 会删除系统参数吗？

A: 不会。BatchDelete 内部通过 u.SysFlag != YesOrNot.Y 条件自动过滤系统参数，传入的 ID 列表中即使包含 SysFlag=Y 的记录也不会被删除。

Q: 如何确保配置编码不重复？

A: 添加和修改接口均内置了大小写不敏感的唯一性校验（Code.ToLower() 比较）。如果尝试添加已存在的名称或编码，将抛出 D9000 错误。建议在业务代码中捕获该异常并给出友好提示。