mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-14 06:34:30 +08:00
b4b3538b21
- 修复 GodotLog 配置源生命周期、Shutdown 释放与延迟 logger 并发发布问题 - 修复 Godot logger 配置归一化、无效数字级别校验和未知级别颜色回退 - 优化 Godot 日志模板缓存边界、内部文档和 update-namespaces 脚本失败传播 - 补充 Godot logging 回归测试、用户文档与 active ai-plan 恢复记录
85 lines
4.6 KiB
Markdown
85 lines
4.6 KiB
Markdown
# Godot Logging Compliance Polish 追踪
|
||
|
||
## 2026-05-02
|
||
|
||
### 阶段：GodotLogger 优点吸收与宿主层补齐（RP-001）
|
||
|
||
- 复核 `GodotLogger` 与 `GFramework.Godot.Logging` 后确认：
|
||
- 模板、颜色、Debug/Release 双模式、类别缩写和 Godot 输出路由已基本吸收
|
||
- 真正缺口主要在宿主接入与运行期配置层，而不是输出格式层
|
||
- 本轮新建 `godot-logging-compliance-polish` topic，并将当前分支
|
||
`feat/godot-logging-compliance-polish` 映射到该主题
|
||
- 为 `GFramework.Godot.Logging` 新增：
|
||
- `GodotLog`
|
||
- `DeferredLogger`
|
||
- `GodotLogConfigurationSource`
|
||
- `GodotLoggerSettings`
|
||
- `GodotLoggerSettingsLoader`
|
||
- 关键实现决策：
|
||
- 不把 `Microsoft.Extensions.Logging` 的 builder / provider 生态整套移植进来
|
||
- 保持 `LoggerFactoryResolver` 与 `ArchitectureConfiguration` 仍是主接线方式
|
||
- 只吸收 `GodotLogger` 里对 GFramework 现有模型真正有价值的部分：
|
||
- 配置自动发现
|
||
- 热重载
|
||
- 延迟 logger 初始化
|
||
- 配置命名兼容
|
||
- 为让热重载作用于已缓存 logger，调整 `AbstractLogger` 支持动态最小级别提供器，并让
|
||
`GodotLoggerFactoryProvider` / `GodotLogger` 在写入和级别判定时读取最新设置
|
||
- 为让结构化日志在 Godot 侧不再退化成纯字符串，扩展：
|
||
- `GodotLogRenderContext`
|
||
- `GodotLogTemplate`
|
||
- `GodotLoggerOptions`
|
||
- `GodotLogger`
|
||
使默认模板支持 `{properties}`，并将 `IStructuredLogger` / `LogContext` 属性渲染到输出中
|
||
- 为兼容 `GodotLogger` 原项目配置习惯，在 `GodotLoggerSettingsLoader` 中补充枚举解析兼容：
|
||
- `Info` / `Information`
|
||
- `Fatal` / `Critical`
|
||
- `Warn` / `Warning`
|
||
- 同步更新 `docs/zh-CN/godot/logging.md`，把文档结论从“只有薄适配层”刷新成“已具备宿主便利层和热重载语义”
|
||
- 已从 `ai-libs/GodotLogger` 复制 MIT 许可证到 `third-party-licenses/GodotLogger/LICENSE`
|
||
|
||
### 验证
|
||
|
||
- `dotnet test GFramework.Godot.Tests/GFramework.Godot.Tests.csproj -c Release --filter FullyQualifiedName~GodotLog -nologo`
|
||
- 结果：通过（11/11）
|
||
- `dotnet test GFramework.Godot.Tests/GFramework.Godot.Tests.csproj -c Release -nologo`
|
||
- 结果：通过（69/69）
|
||
- `dotnet test GFramework.Core.Tests/GFramework.Core.Tests.csproj -c Release --filter FullyQualifiedName~Logging -nologo`
|
||
- 结果：通过（214/214）
|
||
|
||
### 下一步
|
||
|
||
1. 若继续推进本主题，优先评估 Godot 输出是否应变成 Core 可组合 appender / sink
|
||
2. 若出现后续 review 反馈，直接在本 topic 追加 RP-002，而不是重新开临时 local-plan
|
||
3. 若本主题阶段性完成，再把详细实现 history 迁入 `archive/`，active 入口只保留恢复点与风险
|
||
|
||
### 阶段：PR review hardening（RP-002）
|
||
|
||
- 使用 `$gframework-pr-review` 抓取 PR #314 最新 review payload，确认当前 head 上仍有 CodeRabbit 与 Greptile
|
||
未解决线程
|
||
- 接受并处理仍适用的 review 结论：
|
||
- `GodotLog.ConfigurationPath` 不应提前创建全局配置源，`Configure(...)` 需要在 provider 或配置源已创建后 fail-fast
|
||
- 静态配置源需要可显式释放 watcher，因此新增 `GodotLog.Shutdown()`
|
||
- `DeferredLogger` 首次解析改为 `Interlocked.CompareExchange` 发布，避免 `_inner ??=` 并发竞态
|
||
- `GodotLogger` 结构化 `Log(...)` 覆写改为复用 `IsEnabled(level)`，删除重复的最小级别 provider 字段
|
||
- JSON 配置输入需要归一化模板和颜色字典，并拒绝未定义的数字 `LogLevel`
|
||
- `GodotLogTemplate` 模板缓存和分类缓存需要有界，避免热重载或动态 category 长期增长
|
||
- `refactor-scripts/update-namespaces.py` 不能依赖本机绝对路径，也不能把文件处理异常吞成 0 次替换
|
||
- 同步补充 Godot logging 内部类型和关键方法 XML 文档，说明热重载、快照发布、分类匹配和模板缓存语义
|
||
- 同步更新 `docs/zh-CN/godot/logging.md`，记录 `ConfigurationPath` 的诊断语义和 `Shutdown()` teardown 用法
|
||
|
||
### 验证
|
||
|
||
- `dotnet test GFramework.Godot.Tests/GFramework.Godot.Tests.csproj -c Release --filter FullyQualifiedName~GodotLog -nologo`
|
||
- 结果：通过（14/14）
|
||
- `dotnet test GFramework.Godot.Tests/GFramework.Godot.Tests.csproj -c Release -nologo`
|
||
- 结果：通过（72/72）
|
||
- `python3 -B refactor-scripts/update-namespaces.py --help`
|
||
- 结果：通过
|
||
|
||
### 下一步
|
||
|
||
1. 提交 RP-002 review hardening 改动
|
||
2. 刷新 PR review / CI，确认最新 head 是否关闭已处理线程
|
||
3. 若 CI 仍只有 MegaLinter `dotnet-format` restore 失败，优先定位 Actions restore 环境
|