Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions .workbuddy/memory/2026-11-08.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# 2026-11-08

## 评审:JSON 配置驱动注册数据库(实验性,仅 Dameng)

变更范围:`AddLightOrm(..., IConfiguration?)`、`IExpressionContextSetup.RegisterDatabase`、
`ExpressionSqlOptions.RegisterCreator/LoadDatabases`、`src/LightORM/Options/DatabaseOptions.cs`、
手写 AOT binder `LightORM.Extensions.DependencyInjection/BindingExtensions.cs`、
`DamengProvider.CreateDmProvider`、`UseDameng()` 空重载、Avalonia `App.axaml.cs` + `db.json`。

### 实测(临时 MSTest + 内存/文件 JSON,跑完已删)
1. **启动时配置完全不生效** —— `Build()` 只 `OnChange` 订阅,从不读 `CurrentValue`;`DatabaseProviders` 为空。
2. 文件变更后 `OnChange` 正常触发,新 key 会注册(`KEYS_AFTER_RELOAD=cfgsqlite_b|cfgsqlite`)。
3. **改已有 key 的连接串不生效** —— `SetDatabase` 是 `TryAdd`:`CS_AFTER_FIRST=Data Source=a.db`,改成 b.db 后仍是 a.db。

### 其他确认
- `services.Configure<DatabaseList>(configuration.GetSection("LightOrmDatabases"))` 是空绑定(`DatabaseList` 属性名也是 `LightOrmDatabases`),唯一作用是隐式补 change token。
- `TestBase` 没把 configuration 传给 `AddLightOrm` ⇒ 新特性零覆盖,`test/LightORMTest/db.json` 是死文件。
- net462/netstandard2.0 下 `ArgumentNullException.ThrowIfNull` 能编译,靠 `MT.LightORM` 的 `internal ExceptionPolyfills`(`namespace System` + C# 14 extension block)+ `InternalsVisibleTo`,不是 BCL。

### 建议(未实施)
- P0:`Build()` 里补 `UpdateProviders(monitor.CurrentValue)`(幂等)+ `SetOrReplaceDatabase`(adapter/handler 按 type 一起换)+ 记录上一轮 key 做移除。
- P1:未知 `Type` 抛 `LightOrmException` 并列出已注册项;`RegisterCreator` key 用 OrdinalIgnoreCase;`SetDatabase` 用 `provider.DbBaseType`;`reloadToken` 从 static 改单例 `IDisposable`(现在只订阅第一个 ServiceProvider 且永不释放)。
- P2:`LoadDatabases(List<DatabaseOptions>)` 不该在核心(配置模型渗进内核);`Func<DatabaseOptions, IDatabaseProvider>` 建议换成 `IDatabaseCreator` 接口 + `Settings` 自由字典;`CreateDmProvider` 漏了 Slave/`UseIdentifierQuote`/`GenerateOption`/`NewFactory`;`DatabaseOptions` 与既有 `DataBaseOption<T>` 命名太近;`IExpressionContextSetup.RegisterDatabase` 是破坏性接口新增。

## 记忆维护
- `MEMORY.md` 已超限(24KB)被截断 → 重写为结论+铁律版(~11KB),细节链条保留在 09-XX 日志中。

## 实施上述改进(同日,全部落地)
- 核心:`ExpressionSqlBuilder.cs` 增 `RegisterCreator(DbBaseType,...)` / `ApplyDatabase` / `RemoveDatabase` / `TryGetCreator` / `CreatorNames`,三个字典改 `OrdinalIgnoreCase`,删 `LoadDatabases`;新增 `Interfaces/IDatabaseRegistry.cs`;重写 `Options/DatabaseOptions.cs`(补 Slave / IsUseIdentifierQuote / SpecificVersion / DetectVersion / DefaultStringLength / Settings,去掉误用的 `[NotNull]` 和无用 using);`IExpressionContextSetup.cs` 还原(不再加成员,改为可选接口 + 扩展方法)。
- DI:`IoCExtensions.cs` 重写(`TryAddSingleton<IConfiguration>`、显式 `ConfigurationChangeTokenSource`、单例 `DatabaseListReloader`、lambda 替代 method group);新增 `DatabaseListReloader.cs`(初始加载 + OnChange + diff 覆盖/移除 + 失败不崩监听线程);`BindingExtensions.cs` 改成强类型入口并补齐新属性绑定。
- Dameng:`CreateDmProvider` → `Create(DatabaseOptions)` 重载,"连接串为底 + 分散字段覆盖",补齐 Slave / Quote / SpecificVersion / DetectVersion / StringLength / Settings(TableSpace、GenerateUserId),缺 Server 抛可读异常。
- 测试:新增 `test/LightORMTest/DatabaseConfigurationTest.cs`(5 用例全过);删死文件 `test/LightORMTest/db.json`;`TestBase` 还原 `new ServiceCollection()` 并注明为何不接配置;csproj 换 `Microsoft.Extensions.Configuration.Json`。
- Avalonia:`Microsoft.Extensions.Hosting` → `Configuration.Json`;`db.json` 改 Dameng 示例(key=MainDb);`optional:false`。
- 移除 `EnableConfigurationBindingGenerator`(真实路径是手写 binder,留着会误导)。

验证:`DatabaseConfigurationTest` 5/5;Dameng 配置工厂临时用例 3/3(连接串与代码路径等价、覆盖生效、缺 Server 抛错 —— dm8 容器当时未启动,无法真连库);`LightORMTest` 全量 22 通过 3 失败(均为既有:`TestConfig` 用空连接串、`ConstantExpressionTest` 两个走纯 ExpressionResolver);`LightORM.slnx` 仅 BenchmarkTest 编译失败(固定旧 NuGet 包,`Ado` 不存在,既有)。

## 追加:接入 PostgreSQL 与 SqlServer
- 核心新增 `LightORM/Options/DatabaseOptionsExtensions.cs`(public,第三方 provider 可用):
- `DatabaseOptions.ToDbOption<T>(connectionString)`:统一搬运 `SalveConnectionStrings` / `IsUseIdentifierQuote` / `SpecificVersion` / `DetectVersion` / `DefaultStringLength`。
- `DatabaseDefinition.ApplyTo(TableOptions)`。
- `DatabaseConnectionString.Build(key, definition, hasSplitFields, factory, applyFields)`:连接串为底 + 字段覆盖;**无分散字段时原样返回**(不归一化);拼完为空抛可读异常。
- `PostgreSQLProvider.Create(DatabaseOptions)` + `UsePostgreSQL()`:`Host`/`Port`/`Username`/`Password`/`Database`;`Settings["TableSpace"]`。
- `SqlServerProvider.Create(DatabaseOptions)` + `UseSqlServer()`:`Data Source`/`Initial Catalog`/`User ID`/`Password`;**`SqlConnectionStringBuilder` 没有 Port**,端口拼进 `Data Source=host,port`,Server 已含 `,`/`\` 时再给 Port 直接报错。
- 达梦改用同一 helper,删掉自己那份 overlay 逻辑(行为不变:无 Server 时 Port 默认 5236)。
- 验证(临时用例,跑完已删):PG 3/3 —— 分散字段拼出 `Host=localhost;Port=5432;Username=postgres;Password=pwd;Database=testdb`、overlay 只改 Port/Database 且保留 Host=otherhost、`UsePostgreSQL()` 登记后 `TryGetCreator("PostgreSQL")` 命中(含小写);SqlServer 2/2 —— `Data Source=localhost,1433;Initial Catalog=testdb;User ID=sa`、`DetectVersion=false` 时 `Capabilities.IsResolved=True`(不连库落 Baseline)、命名实例 + Port 抛可读异常。
- 注:`LightORMTest.SqlServer` 项目没有 `InternalsVisibleTo`,端到端注册验证放不到那个项目里(PG 有)。

## 追加:接完 MySql / Sqlite / Oracle / KingbaseES
- 用户中途澄清口径:**"覆盖率"只指拼出可用连接串必需的字段,连接超时/命令超时/连接池/应用名这类调优项不要**。据此把已加的 6 个调优字段(ConnectionTimeout/CommandTimeout/Pooling/MaxPoolSize/MinPoolSize/ApplicationName)全部回滚,只保留 `DataSource` / `ServiceName` / `Sid`。
- `DatabaseConnectionString.Build` 由用户改成泛型(`where T : DbConnectionStringBuilder`),我进一步去掉 `hasSplitFields` 参数,改为内部调 `definition.HasSplitConnectionFields()`(字段清单只在一处维护)。
- 四个方言的 `Create(DatabaseOptions)` + 空参 `UseXxx()` 全部就位;字段映射:
- MySql:`Server`/`Port`(uint)/`UserID`/`Password`/`Database`;顺手把构造期那条"库名正则"换成 `MySqlConnectionStringBuilder(cs).Database`(原正则只认字母下划线,库名带数字会误判)。
- Sqlite:`DataSource` 优先,其次 `Database` 当库文件路径;都没有且无连接串 → 抛错说明 Server/Port/凭据无意义。
- Oracle:`DataSource`(TNS 别名/描述符/EZ Connect)→ `ServiceName`(`host:port/service`,默认 1521)→ `Sid`(完整 DESCRIPTION)→ 裸 `Server`(当别名,Port 有值才拼);ServiceName 与 Sid 同给、或给了却没 Server → 抛错。
- KingbaseES:同 PG(`Host`/`Username`)。
- 验证(临时用例,跑完已删):Sqlite 2/2(`data source=temp.db`、`Database` 字段也当路径);MySql 1/1(`Server=localhost;Port=3306;User ID=root;Password=pwd;Database=test_db`);Oracle 3/3(`localhost:1521/XE` / `SID=ORCL` 描述符 / TNS 别名 `MYTNS`);KingbaseES 2/2(`Host/Port/Username/Database` 正确、DataSource 优先于 Server)。全部七个 provider 多 TFM 编译通过。




## 追加:Oracle DataSource 语法核实(用户问 "ip:port/(serviceName 或 Sid) 就可以?")
- **结论:`ip:port/xxx` 的 xxx 在 Oracle 语法里是 service_name,不是 SID。** 官方 ODP.NET 文档的 EZ Connect 形式为 `[//]host[:port][/service_name]`;Easy Connect Plus 才多出 `[:server][/instance_name]` 两个后缀位,SID 依然不在第一段。
- 用户之所以觉得"都能用",是因为**单实例/默认安装下 service_name 通常与 SID 同名**(XE 的 SID 和 service 都是 XE);RAC 下 SID=`ORCL1`/`ORCL2` 而 service=`ORCL`,`/ORCL1` 直接 ORA-12514。所以当前 `Sid` 走完整描述符 `(DESCRIPTION=...(CONNECT_DATA=(SID=...)))` 是唯一始终正确的写法,保留。
- 顺手修掉一个隐患:原来 `Server` 有值但无 ServiceName/Sid 时会拼 `RACE:1521` —— 既不能精确匹配 TNS 别名,也不是合法 EZ Connect(缺 service_name)。改为**抛 LightOrmException**,提示"只连 TNS 别名请去掉 Port"。`Server` 单独给仍原样当别名返回。
- 本机 Oracle(localhost:1521)当前未启动,无法实测;结论来自 Oracle 官方文档 + 语法推导。
- 环境注意:本次沙箱下 `dotnet build` 会因 `C:/Users/Marvel/AppData/Roaming/NuGet` 无权限而 restore 失败,**加 `--no-restore` 可正常编译**。

## 追加:文档补齐 + 提交
- 分支 `json-config` 相对 `origin/master` 的改动已分 8 批落本地:内核 → DI → 7 provider → 测试 → Avalonia 示例 → 记忆 → 文档 → 警告修复。
- 文档三处:`README.md`「从配置文件注册数据库(可选)」+ 简单配置/关键 API 入口的指针 + `Options/` 目录行;`examples.md` 新增完整章节(字段表、各方言拼串规则、优先级与热重载、两个坑);`doc/版本日志.md` 补 v2026.11.08。
- `AddLightOrm` 的 XML summary 内嵌 `LightOrmDatabases` 的 JSON 结构(`<code>` 块逐字段注释),IDE 悬浮可查。
- **两个必须记住的坑**:① 配置键名**不做严格校验**(`ValidateConfigurationKeys` 里 `BinderOptions` 恒为 null,`ErrorOnUnknownConfiguration` 永远关着)→ 拼错的键静默忽略;② `DatabaseDefinition` 加字段必须同步 `BindingExtensions.s_configKeys_DatabaseDefinition` 与 `BindCore`,否则字段被静默丢弃。
- 方言名规范值:`Sqlite` / `MySql` / `SqlServer` / `PostgreSQL` / `Oracle` / `Dameng` / `KingbaseES`(对应 `DbBaseType.Name`,注册表大小写不敏感)。
- 顺手清掉 `BindingExtensions` 的 4 条 CS8604(net462/netstandard2.0 无 `[NotNullWhen]`,补 `!`)。DI 项目现 0 警告 0 错误,`DatabaseConfigurationTest` 5/5 通过。
- 沙箱跑测试也要 `--no-restore`,否则 restore 阶段因 `C:/Users/Marvel/AppData/Roaming/NuGet` 无权限直接失败。
Loading
Loading