pd_log 0.6.0

Cross-platform logging plugin for Flutter with buffered native file logging.

0.1.0 — 首个公开测试版本

发布日期：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。

0.1.1 — Android 构建修复

发布日期：2025-10-02

修复

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

0.1.2 — 文档与元数据更新

发布日期：2025-10-03

改进

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

0.1.3 — 文档注释完善与内部重构

发布日期：2025-10-04

改进

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

兼容性

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

0.2.0 — 样式系统统一与 API 迁移（破坏性变更）

发布日期：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）可跳转。

0.2.1 — 调用者信息修复与稳定性改进（补丁）

发布日期：2025-10-06

修复

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

改进

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

兼容性

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

0.2.2 — 多行样式修复与发布流程完善（补丁）

发布日期：2025-10-07

修复

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

改进

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

兼容性

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

0.3.0 — JSON 美化与输出可读性优化（次版本）

发布日期：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 可读性与日志整洁度。如存在依赖旧输出格式的解析器，请验证并调整以适配新的空格拼接与美化输出。

0.3.1 — 文档全面完善与发布流程校验（补丁）

发布日期：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 获取更完整的文档与更稳健的发布流程校验。

0.4.0 — 日志滚动策略（次版本功能新增）

发布日期：2025-10-10

新增

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

文档

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

兼容性

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

0.5.0 — 日志路径结构升级（次版本）

发布日期：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 可读性与一致性。

0.5.1 — 文档完善与发布（补丁版本）

发布日期：2025-10-11

改进

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

发布

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

0.6.0 — 查询 API 增强与文件元信息派生（次版本）

发布日期：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 .）。
• 单元测试通过（新增解析与排序/分页测试）。