pd_log 0.3.1

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

0.1.0 — 首个公开测试版本

发布日期：2025-10-10

新增

• 提供跨平台统一日志 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-10

修复

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

0.1.2 — 文档与元数据更新

发布日期：2025-10-10

改进

• 更新 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-10

改进

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

兼容性

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

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

发布日期：2025-10-10

变更摘要

• 统一日志着色到样式系统：新增 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-11

修复

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

改进

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

兼容性

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

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

发布日期：2025-10-11

修复

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

改进

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

兼容性

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

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

发布日期：2025-10-11

新增/改进

• 新增 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-11

改进

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

工程

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

兼容性

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