Skip to content

支持从 JSON 配置注册数据库 - #45

Merged
MarvelTiter merged 10 commits into
masterfrom
json-config
Nov 8, 2026
Merged

MarvelTiter merged 10 commits into
masterfrom
json-config

Conversation

@MarvelTiter

Copy link
Copy Markdown
Owner

概述

让 LightORM 支持从 JSON 配置注册数据库:配置里写一条 { Key, Option { Type, Server, ... } },
框架按 Type 找到对应方言的创建器并生成 provider,不再需要用代码逐个 UseXxx(connStr)。
支持配置文件热重载(改连接串、加库、删库即时生效)。

使用方式

var configuration = new ConfigurationBuilder()
    .AddJsonFile("db.json", optional: false, reloadOnChange: true)
    .Build();

services.AddLightOrm(option =>
{
    option.SetTableContext<MyDbContext>();
    option.UseDameng();          // 只登记"从配置创建"的工厂,不注册实例
}, configuration);
{
  "LightOrmDatabases": [
    {
      "Key": "MainDb",
      "Option": {
        "Type": "Dameng",
        "Server": "localhost", "Port": 5236,
        "UserId": "SYSDBA", "Password": "SYSDBA001"
      }
    }
  ]
}

Type 大小写不敏感;也可直接给 ConnectionString,再用分散字段覆盖其中部分键。

变更内容

内核(LightORM)​

  • DbBaseType 作为方言身份;新增可选能力接口 IDatabaseRegistry,
    RegisterDatabase 以扩展方法挂在 IExpressionContextSetup 上 —— 不改接口成员,第三方实现不受影响。
  • 注册表 customDatabases / databaseHandlers / databaseCreators 统一改为大小写不敏感;
    新增 RegisterCreator / TryGetCreator / ApplyDatabase(replace) / RemoveDatabase,
    支持同名键覆盖(原 TryAdd 会让重载静默失效)与删除。
  • 新增配置模型 DatabaseOptions / DatabaseDefinition / DatabaseList,
    以及 DatabaseConnectionString.Build<T>:以已有连接串为底、分散字段覆盖,
    无分散字段时原样返回(不重新归一化,避免改写用户手写串)。
  • ExpressionSqlOptions 拆为平台无关(Shared)与实例两部分。

依赖注入扩展

  • AddLightOrm 增加可选 IConfiguration 参数,配置节 LightOrmDatabases 经
    手写 AOT 友好绑定(BindingExtensions)映射为 DatabaseList,
    不用反射绑定(并为将来 AOT 留路)。
  • 新增 DatabaseListReloader:构造期同步一次 CurrentValue
    (修复"初始配置永不生效"),随后订阅 OnChange;重载包在 try/catch + 日志里,
    不让文件监听线程被异常打断;按 key 差集清理配置中已删除的库。
  • Type 找不到创建器时抛可读异常并列出已支持方言名。
  • 移除 AddLightOrm 内的静态 reloadToken / initialLoaded,订阅生命周期交给容器。

方言接线(7 个)​

  • 每个 provider 新增 Create(DatabaseOptions) 与无参 UseXxx() 重载。
  • 字段映射只覆盖拼出可用连接串必需的字段(超时、连接池、应用名等调优项不纳入):
    Datasource / Server / Port / UserId / Password / Database / ServiceName / Sid 等。
  • 修掉一个既有 bug:MySQL 构造期用正则 (?<=Database=)([A-Z|a-z|_]+) 提取库名,
    库名带数字或非 ASCII 会被误判为"需要切库",改用 MySqlConnectionStringBuilder(cs).Database。

Oracle 专项

  • DataSource 原样透传(TNS 别名 / 完整描述符 / EZ Connect 均可);
    ServiceName 拼 host:port/service;Sid 拼完整描述符;
    裸 Server 当 TNS 别名。
  • 不用 host:port/SID:Oracle 语法里该位置是 service_name,
    仅在 service 与 SID 同名(单实例默认安装)时"看起来能用",RAC 下(SID=ORCL1 / service=ORCL)必失败。
  • 禁止 Server + Port 却不给 ServiceName/Sid:拼出的 host:port
    既不能精确匹配 TNS 别名,也不是合法 EZ Connect,改为抛可读异常。

示例 / 测试 / 版本

  • DatabaseUtils.Avalonia 改为从 db.json 注册(optional: false,缺文件直接启动失败),
    依赖由 Microsoft.Extensions.Hosting 换成 Microsoft.Extensions.Configuration.Json。
  • 新增 DatabaseConfigurationTest:初始加载、同名键覆盖、条目删除、未知 Type 报错、大小写不敏感,5/5 通过。
  • 版本号统一提到 2026.11.08.1;移除已不需要的 Microsoft.Extensions.Configuration.Binder 引用。

兼容性

  • 源码兼容:AddLightOrm 的新参数是可选参数,现有调用无需修改
    (二进制层面签名变化,需同版本重编译)。
  • 未改 IExpressionContextSetup 成员,第三方实现不会编译失败。
  • 无配置时行为与之前完全一致(configuration = null 直接跳过整条链路)。

验证

  • src/LightORM.Extensions.DependencyInjection、7 个 provider、test/LightORMTest 全部编译通过(net462;netstandard2.0;net8.0;net10.0)。
  • dotnet test --filter DatabaseConfigurationTest:5/5 通过(net10.0)。

待办 / 已知项

  • DatabaseOptions(配置模型)与既有 DataBaseOption<T>(选项对象)命名易混,后续可考虑重命名。
  • 各 provider 项目的端到端注册用例此前是临时验证后删除,仓库里暂时只有 LightORMTest 的通用用例。

- `DbBaseType` 作为方言身份,新增 `IDatabaseRegistry` 可选能力接口,
  `RegisterDatabase` 以扩展方法挂在 `IExpressionContextSetup` 上,
  不破坏第三方实现。
- `ExpressionSqlOptions` 拆为平台无关(Shared)与实例两部分,
  便于后续按 TFM 差异化实现。
- 注册表(customDatabases / databaseHandlers / databaseCreators)
  统一改为大小写不敏感;新增 `RegisterCreator` / `TryGetCreator` /
  `ApplyDatabase` / `RemoveDatabase`,支持同名键覆盖与删除。
- 新增 `DatabaseOptions` / `DatabaseDefinition` 配置模型与
  `DatabaseConnectionString.Build<T>` 通用连接串拼装:
  已有连接串为底、分散字段覆盖,无分散字段时原样返回不归一化。
- `AddLightOrm` 增加可选 `IConfiguration` 参数:配置节 `LightOrmDatabases`
  经 AOT 友好的手写绑定(`BindingExtensions`)映射为 `DatabaseList`。
- 新增 `DatabaseListReloader`:构造期同步一次 `CurrentValue`(修复此前
  "初始配置永不生效"),随后订阅 `OnChange`;重载在 try/catch 内执行并
  记录日志,避免文件监听线程被异常打断。
- 重载支持覆盖同名键、以及删除配置中已消失的库(按 key 差集调用
  `RemoveDatabase`);`Type` 找不到登记过的创建器时抛出可读异常并列出
  已支持方言名。
- 移除 `AddLightOrm` 内的静态 `reloadToken` / `initialLoaded`,订阅生命周期
  交给容器,随 provider 释放。
每个 provider 新增 `Create(DatabaseOptions)` 与无参 `UseXxx()` 重载,
后者只需登记 `RegisterDatabase(DbBaseType.Xxx, d => XxxProvider.Create(d))`。

字段映射(只覆盖"拼出可用连接串必需"的字段,超时/连接池等调优项不收):
- Dameng:`DataSource` 优先,否则 `Server`+`Port`(默认 5236)+`UserId`/`Password`。
- PostgreSQL / KingbaseES:`DataSource`→`Host`(回退 `Server`)、`Port`、
  `UserId`→`Username`;`Settings["TableSpace"]`。
- SqlServer:`Server`→`Data Source`;`SqlConnectionStringBuilder` 无 Port,
  端口折进 `Data Source=host,port`,Server 已含 `,`/`\` 时再给 Port 直接报错。
- MySql:`Port` 转 `uint`;顺手把构造期用正则提取库名的写法换成
  `MySqlConnectionStringBuilder(cs).Database`(原正则只认字母下划线,
  库名带数字会误判为需要换库)。
- Sqlite:`DataSource` 优先,其次 `Database` 当库文件路径。
- Oracle:`DataSource`(TNS 别名 / 描述符 / EZ Connect)原样透传 →
  `ServiceName` 拼 `host:port/service` → `Sid` 拼完整描述符 →
  裸 `Server` 当 TNS 别名。`Sid` 不用 `host:port/SID`:Oracle 语法里该位置
  是 service_name,只在 service 与 SID 同名时"看起来能用",RAC 下必失败;
  同时禁止 `Server`+`Port` 却无 ServiceName/Sid(拼出的 `host:port`
  既不匹配别名也不是合法 EZ Connect)。
覆盖初始加载、同名键覆盖、删除条目、未知 Type 的可读报错、
Type 大小写不敏感五种场景;用临时目录 + `reloadOnChange: true`
真实走一遍文件监听,`[DoNotParallelize]` 避免静态注册表互相污染,
用完按 key 调 `RemoveDatabase` 清理。

`TestBase` 保持不消费 configuration:多注册几个库会让
`DatabaseProviders.First()` 类断言失效。
`db.json` 随输出复制(PreserveNewest),启动时
`AddJsonFile(optional: false, reloadOnChange: true)`,
缺文件直接启动失败而不是运行期抛 `KeyNotFoundException`;
`UseDameng()` 只登记创建器,实际库由配置提供。
示例配置用 `Key = "MainDb"`,否则 `DefaultDbKey` 找不到默认库。

依赖由 `Microsoft.Extensions.Hosting` 换成
`Microsoft.Extensions.Configuration.Json`,不再引入整套 Host。
记录配置驱动注册的落地范围、字段取舍口径(只覆盖拼串必需字段)、
Oracle DataSource 语法结论(`host:port/xxx` 是 service_name,
SID 必须完整描述符),以及沙箱下 `dotnet build` 需 `--no-restore`。
- README:新增「从配置文件注册数据库(可选)」小节,给出 db.json 与
  `AddLightOrm(..., configuration)` 的最小示例、Key/Type/覆盖规则说明;
  「简单配置」与「关键 API 入口」补指针,「核心库内部结构」补 `Options/` 目录。
- examples.md:新增「从配置文件注册数据库」章节,含完整字段表、
  各方言拼串规则、优先级与热重载、以及两条易踩的坑
  (Type 未登记会报错并列出可选值;键名拼错会被静默忽略)。
- 版本日志:补 v2026.11.08 条目。
- `AddLightOrm` 的 XML summary 内嵌 LightOrmDatabases 的 JSON 结构,
  逐字段标注含义与默认值,IDE 悬浮即可查,不必翻文档。
net462 / netstandard2.0 的 BCL 不带 `[NotNullWhen]` 注解,
`string.IsNullOrEmpty` 之后编译器仍认为值可能为 null,
`ParseInt` / `ParseBool` 的调用补 `!` 断言。仅消除警告,行为不变。
@gitguardian

gitguardian Bot commented Nov 8, 2026

Copy link
Copy Markdown

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secret in your pull request
GitGuardian id GitGuardian status Secret Commit Filename
39820933 Triggered Generic Password 16e6163 DatabaseUtils.Avalonia/db.json View secret
🛠 Guidelines to remediate hardcoded secrets
  1. Understand the implications of revoking this secret by investigating where it is used in your code.
  2. Replace and store your secret safely. Learn here the best practices.
  3. Revoke and rotate this secret.
  4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider


🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.

@MarvelTiter
MarvelTiter merged commit b24223b into master Nov 8, 2026
0 of 2 checks passed
@MarvelTiter
MarvelTiter deleted the json-config branch November 8, 2026 09:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant