pd_log 0.8.0

pd_log: ^0.8.0 copied to clipboard

发布日期：2025-12-16

新增

• 新增 LogUtils.formatJsonAsync（隔离执行），为复杂 Map/对象的 JSON 美化提供异步通道，避免主隔离卡顿。
• 新增 PDLog.formatJsonAsync 与 PDLog.formatedAsync，在插件 API 层暴露异步格式化与打印能力（Web 自动回退为同步）。

改进

• 为 PDLog.formated 补充文档注释，提示在大对象/高频场景优先使用异步版本；为异步 API 补充完整行为说明。
• 代码质量：dart analyze、dart format 与 flutter test 全部通过。
• 生成最新 API 文档：dart doc。
• 更新 README 当前版本与安装片段：^0.8.0。

兼容性

• 无破坏性变更；为新增能力的次版本升级，建议升级至 0.8.0 获取更流畅的美化打印与完善文档。

发布日期：2025-10-24

改进

• 统一文档术语为“纯 Dart”并完成网站文档修订（缓冲刷新与事件监听、文件存储与滚动、元数据与历史记录等）。
• 代码质量：dart analyze 零问题；dart format . 统一风格；flutter test 全部通过。
• 生成 API 文档（dart doc），本地预览。

兼容性

• 无破坏性变更；建议升级至 0.7.3 以获得最新文档与发布流程校验。

发布日期：2025-10-20

改进

• 源码文档注释增强，覆盖：log_ledger_io.dart/log_ledger_web.dart、dart_file_logger.dart、file_watchers_web.dart、platform_service_io.dart/platform_service_web.dart、list_options.dart、log_query.dart。
• 文档模块同步：
  • doc/query_and_pagination.md 移除不存在的 SortBy.size，补充 SortBy.time 的回退语义（优先 modifiedMs，其次解析 year/month/day）。
  • doc/web_platform.md 明确 Web 端文件监听为 no-op（FileWatchManager）、平台服务版本与路径行为（userAgent / logRootPath == null / 空事件流）。
  • doc/metadata_and_history.md 强化快照原子写策略说明（临时文件+重命名），补充即时创建事件与 listSummary 的过滤/排序/分页能力示例。
• 工程质量：flutter analyze 零问题。

兼容性

• 无破坏性变更；建议升级至 0.7.2 获取更完整的文档与源码注释。

改进

• 更新 Dart SDK 版本约束至 >=2.19.6 <4.0.0，支持 Dart 3.x
• 升级依赖项：plugin_platform_interface 至 2.1.8
• 升级 lints 开发依赖至 2.1.1
• 修复测试代码中的废弃 API 使用，替换 setMockMethodCallHandler 为 TestDefaultBinaryMessengerBinding

发布日期：2025-10-16

新增

• 新增全局配置项：PDLogConfig.ansiEnabled（默认 false）。用于控制控制台/平台输出是否包裹 ANSI 颜色；文件写入始终为纯文本。

改进

• 分离控制台与文件输出的着色行为：
  • 控制台输出（Dart/平台）在 ansiEnabled: false 时保留 ANSI 转义码；
  • 文件写入始终不包含 ANSI 转义码（纯文本），便于后续分析与归档。
• 文档同步：更新 README.md、doc/configuration.md、doc/styling_and_formatting.md 说明与示例；纠正默认值为 true。
• 工程质量：flutter analyze 零问题、统一格式（dart format .）、单元测试全部通过（11 项）。

兼容性

• 无破坏性变更；建议升级至 0.7.0 以获得更灵活的控制台着色与一致的文件纯文本输出。

发布日期：2025-10-16

改进

• 静态分析与格式化：修复/清理提示，统一代码风格（dart format .），flutter analyze 零问题。
• 单元测试：全部通过（11 项）。
• 版本升级：pubspec.yaml 提升至 0.6.2，README 依赖片段同步为 ^0.6.2。
• 文档对齐：补充 README 开关说明与 Web 限制，统一“平台侧/本地文件写入（Dart 管理）”术语。

兼容性

• 无破坏性变更；建议升级以获得更完善的文档与发布校验。

发布日期：2025-10-15

改进

• 统一代码质量：flutter analyze 零问题、flutter test 全部通过。
• 升级版本至 0.6.1 并更新 README 与入门文档安装片段为 ^0.6.1。
• 顶层文档目录对齐 pub 布局约定：使用 doc/（保留文档网站结构不变）。
• 新增 .pubignore 排除示例的文件读取辅助源文件，消除发布警告。
• 术语与注释统一：将“原生写入/原生侧”统一为“平台侧/本地文件写入（Dart 管理）”，覆盖 lib/ 源码与 API 文档注释。
• 明确刷盘职责：PDLog.flushNativeLogs() 为 Dart 写入器刷盘；平台侧方法保留为占位以保证接口一致。
• README 调整：移除 useNative 参数说明，统一由 useConsole 控制控制台输出；保留 nativeFileLoggingEnabled 说明；标注 Web 不执行本地文件写入。
• pubspec.yaml 描述更新为 Dart 管理的缓冲文件写入与平台控制台打印。

兼容性

• 无破坏性变更；推荐升级以获得更规范的包布局与文档。

发布日期：2025-10-13

新增

• 引入统一的查询选项 ListOptions，支持：
  • 排序：SortBy.time（优先使用 modifiedMs，缺失时回退到 year/month/day 解析出的日期）、SortBy.name；
  • 方向：SortDirection.asc | desc；
  • 分页：pageSize 与 page。
• 将 ListOptions 集成到公共查询 API：
  • PDLog.listLogFiles({ListOptions? options})
  • PDLog.listLogFilesByYear(int year, {ListOptions? options})
  • PDLog.listLogFilesByYearMonth(int year, int month, {ListOptions? options})
• 为 PDLogFile 增加派生只读字段：year/month/day，基于规范化路径 .../<yyyy>/<MM>/<dd>.log 解析；当末段非 dd.log 时返回 null。

改进

• 新增 LogQuery.applyOptions，统一排序与分页逻辑；修复降序实现以兼容 Dart List API（使用 list.reversed.toList()）。
• 完善文档注释与 README 示例，提升 API 可发现性与开发体验。

工程

• 静态分析通过（flutter analyze）。
• 统一格式（dart format .）。
• 单元测试通过（新增解析与排序/分页测试）。

发布日期：2025-10-11

改进

• 补充与完善 Dart 源码文档注释（pd_log.dart、src/log_query.dart、src/log_utils.dart）。
• README 新增“API 文档注释”一节，说明可通过 IDE/Dartdoc 查看文档。

发布

• 提升 pubspec.yaml 版本至 0.5.1，用于发布上述文档更新。

发布日期：2025-10-11

变更摘要

• 统一调整原生日志文件路径结构为 /<year>/<month>/<day>.log，最终示例：pd_log/2025/01/19.log。
• 涉及平台：Android（Kotlin）、iOS/macOS（Swift）、Windows（C++）、Linux（C++/glib）。

兼容性与影响

• 外部 Dart API 保持不变：listLogFiles() 仍递归枚举、listYearFolders() 仅列出首层年份目录。
• 现有日志滚动策略（基于 modifiedMs）不受影响。
• 历史 /<year>/<yyyy-MM-dd>.log 结构的文件仍可通过递归枚举与删除接口进行管理；如需统一结构，可按需迁移。

文档

• 更新 README 的“文件组织结构”与 FAQ，说明新的月份子目录与日文件命名。
• 安装版本更新为 ^0.5.0。

升级建议

• 建议升级至 0.5.0 以获得更清晰的目录组织结构（年/月/日）。如存在依赖旧路径模式的外部脚本，请同步调整解析规则。

新增 Dart API

• 新增按日期/年份/月查询辅助方法，便于在 Dart 层快速定位日志文件：
  • PDLog.logFilePathIfExists(DateTime date)：检查指定日期是否存在 .log 文件；存在返回绝对路径，否则返回空字符串。
  • PDLog.listLogFilesByYear(int year)：列出指定年份目录下的所有日志文件。
  • PDLog.listLogFilesByYearMonth(int year, int month)：列出指定年份与月份目录下的所有日志文件。

内部重构

• 抽取通用路径与筛选逻辑到 lib/src/log_query.dart（LogQuery 工具类），统一处理路径分隔符、根路径规整与前缀过滤，降低 PDLog 类的实现复杂度。

文档

• 更新 README 的“常用 API”与“查询示例（按日期/年份/月）”章节，补充上述新增查询能力的说明与示例代码。
• 完善源码的 Dart 文档注释（pd_log.dart、src/log_query.dart、src/log_utils.dart 等），提升 API 可读性与一致性。

发布日期：2025-10-10

新增

• 新增日志文件滚动策略（完全在 Dart 层实现，避免多平台重复逻辑）：
  • 支持按天/月/年保留最近 N 个周期，其余自动删除；
  • 新增配置项：PDLogConfig.logRetentionStrategy 与 PDLogConfig.logRetentionCount；
  • PDLog.updateConfigure 支持上述配置并在更新后自动执行一次清理；
  • 新增公共 API：PDLog.enforceRotation() 可随时手动触发清理。

文档

• README 增加滚动策略章节与示例。

兼容性

• 次版本更新（功能新增），无破坏性外部 API 变更；建议升级至 0.4.0 以获得自动清理与统一的配置能力。

发布日期：2025-10-09

改进

• 补充并统一跨平台实现的文档注释（Dart 层、iOS/macOS、Windows、Linux、Web），涵盖缓冲策略、文件路径约定、MethodChannel 交互与日志级别过滤规则。
• 为 LogLevel 枚举补充最小级别过滤说明，明确枚举顺序与 fileLoggingMinLevel 的协作关系。
• 增强 PDLog 与 PDLogConfig 字段文档，说明文件日志行为与平台限制（Web 不支持文件写入）。

工程

• 通过 dart analyze 全面静态分析，无问题。
• 统一代码格式（dart format .）。
• 单元测试全部通过（flutter test）。
• 生成本地 API 文档（dart doc）。

兼容性

• 无破坏性变更，建议升级至 0.3.1 获取更完整的文档与更稳健的发布流程校验。

发布日期：2025-10-08

新增/改进

• 新增 JSON 美化打印：PDLog.formated(Object? message) 使用 JsonEncoder.withIndent 与自定义递归归一化逻辑，支持换行缩进与双引号合法输出；兼容 Map 非字符串键（转为字符串）、Iterable、DateTime（ISO8601）、以及带 toJson() 的对象。
• 优化日志拼接可读性：在 log_utils.dart 中引入中间变量 wantCaller 并通过片段过滤+空格拼接（[tsPart, callerPart, msgText].where(...).join(' ')），避免在未显示时间戳/调用者信息时出现多余空格。
• 每行 ANSI 样式保持：在包含多行的消息中逐行应用样式，确保颜色/样式不会在换行后丢失。

兼容性

• 无破坏性外部 API 变更；PDLog.formated 的输出更易读且为合法 JSON。当 Map 的键为非字符串类型时，按照 JSON 规范统一转为字符串（如 1 → "1"）。如需保留键类型语义，可在业务侧采用自定义非 JSON 格式或以 [{key, keyType, value}] 结构记录。

升级建议

• 建议升级至 0.3.0 以获得更好的 JSON 可读性与日志整洁度。如存在依赖旧输出格式的解析器，请验证并调整以适配新的空格拼接与美化输出。

发布日期：2025-10-07

修复

• 修复当日志消息包含换行符时，后续行不继承 ANSI 样式的问题；改为逐行包裹样式序列，保证每行颜色/样式一致（lib/src/log_utils.dart）。

改进

• 统一代码格式并通过静态分析与单元测试；更新 README 安装版本至 ^0.2.2。

兼容性

• 无破坏性变更，建议升级至 0.2.2 以获得更好的日志可读性。

发布日期：2025-10-06

修复

• 使用 package:stack_trace 统一解析调用栈（Trace/Frame），在多平台下稳定获取调用者的函数名、文件与行号。
• 修正过滤规则，避免误将示例业务包（如 pd_log_example）当作内部包而跳过，导致不显示调用者信息。

改进

• 增加依赖：stack_trace，提升跨平台栈解析的兼容性与可维护性。
• 持续保持原有日志输出格式与样式系统，避免破坏外部 API；本次为行为修复。

兼容性

• 无破坏性 API 变更，建议升级至 0.2.1 以获得更准确的调用者信息显示。

发布日期：2025-10-05

变更摘要

• 统一日志着色到样式系统：新增 LogStyleConfig（前景色/背景色/文本样式），默认映射 kDefaultLogStyles。
• 移除 PDLog.out 的 colorCode 参数；删除 LogLevelExt.ansiColorCode 映射。
• 着色逻辑改为优先使用：调用级 style → 全局 PDLogConfig.logStyles[level] → 无色。

迁移指引（Breaking Changes）

• 旧代码：PDLog.out('msg', colorCode: 34) → 新写法：

  PDLog.out('msg', level: LogLevel.info, style: LogStyleConfig(foreground: 34));
  

• 旧引用：LogLevel.info.ansiColorCode → 使用 PDLogConfig.logStyles[LogLevel.info] 或直接构造 LogStyleConfig。
• 如需背景与文本样式（粗体/斜体/下划线等），使用 LogStyleConfig(background: 47, styles: [1, 3, 4])。

文档

• 更新 README 示例为 style 用法；补充 ANSI 颜色、背景与样式参考。
• 重新生成 API 文档，确保 Dartdoc 链接（如 LogStyleConfig.ansiStartSequence）可跳转。

发布日期：2025-10-04

改进

• 提升 Dart 端文档注释质量：为 PDLog、平台接口与实现、配置与级别枚举、文件元信息等补充全面注释，优化阅读体验与 API 可发现性。
• 抽取核心日志逻辑到 lib/src/log_utils.dart，提升可维护性；将 ANSI 颜色映射迁移到 LogLevel 扩展以复用。
• 清理不合理内联注释与未使用导入，统一风格。

兼容性

• 无破坏性变更，保持外部 API 稳定；建议升级到 0.1.3 以获得更好的文档与内部实现。

发布日期：2025-10-03

改进

• 更新 README.md 安装示例版本到 ^0.1.2，同步最新发布信息。
• 更新 iOS/macOS Podspec 的作者与主页为真实信息（Pedro Pei / 270055988@qq.com / Gitee 仓库）。
• 统一 Android 包 ID 与命名空间为 me.pedro.pei.pd_log（延续 0.1.1 修复，在示例与文档中明确）。

发布日期：2025-10-02

修复

• 为 Android 模块添加 namespace "com.example.pd_log"，解决在 AGP 8+ 环境中构建报错（Namespace not specified）。
• 版本号提升至 0.1.1，语义化补丁发布。

发布日期：2025-10-01

新增

• 提供跨平台统一日志 API：PDLog.v/d/i/w/e、标签与时间戳支持、可选调用者信息。
• 原生文件日志缓冲：支持按时间与缓冲阈值触发刷新，减少频繁磁盘写入。
• 日志文件管理：枚举日志文件、统计总大小、删除单个或全部日志。
• 平台支持：Android / iOS / macOS / Windows / Linux / Web。

改进

• Dart 端字符串拼接优化，提升可读性与微小性能（lib/pd_log.dart）。
• iOS/macOS 原生并发修复：移除同队列同步阻塞风险，失败回填与重试逻辑更稳健。
• Linux 原生调度修复：避免在持锁情况下重复调用导致潜在死锁。

文档

• 新增 README，完善功能说明、安装指南、使用方法与示例代码。
• 新增 MIT LICENSE。