📝 Document 0.2 examples and usage patterns

README.md

@@ -16,9 +16,15 @@ BitLogger 是一个基于 MoonBit 编写的结构化日志库。
 
 ## ❇️ 特点
 
-- 🧩 核心能力清晰：先把 logging core 做稳，再继续扩展 `FileSink`、buffered/async 等能力。
+- 🧩 核心能力清晰：先把 logging core 做稳，再继续扩展 rotation/async 等能力。
 - 🏗️ 结构明确：按 `level / record / formatter / sinks / logger / global` 拆文件，便于继续维护。
 - 🔌 可扩展：支持 `fanout_sink(...)` 和 `callback_sink(...)`，方便后续桥接文件、指标或外部系统。
+- 🧱 可组合：支持 `buffered_sink(...)` 和 `filter_sink(...)`，可以在不引入复杂 runtime 的前提下组合输出策略。
+- 🔎 可复用过滤：提供 `target_has_prefix(...)`、`message_contains(...)`、`level_at_least(...)`、`field_equals(...)` 等过滤辅助函数。
+- 🩹 可变换 Record：支持 `with_patch(...)`、`patch_sink(...)` 与脱敏/补字段/message 变换 helper。
+- 📮 显式队列：支持 `queued_sink(...)` / `with_queue(...)`、有界积压与溢出策略，作为后续 async sink 的 runtime-safe 基础。
+- 🧾 可配置文本格式：支持 `text_formatter(...)`、`format_text(...)`、`text_console_sink(...)` 和 `formatted_callback_sink(...)`。
+- 💾 Native 文件输出：支持 `file_sink(...)`，但当前仅保证 `native/llvm` backend 可用。
 - 📦 面向 MoonBit：API 和工程结构围绕 MoonBit 的 package / visibility / toolchain 现实约束设计。
 
 ## 🚀 快速开始
@@ -31,14 +37,15 @@ let logger = Logger::new(console_sink(), min_level=Level::Info, target="demo")
 logger.info("starting", fields=[field("port", "8080")])
 ```
 
-层级 target 示例：
+<details><summary>层级 target 示例</summary>
 
 ```moonbit
 let worker = Logger::new(console_sink(), target="app").child("worker")
 worker.info("job ready")
 ```
+</details>
 
-自定义 callback sink 示例：
+<details><summary>自定义 callback sink 示例</summary>
 
 ```moonbit
 let hook = Logger::new(
@@ -50,6 +57,98 @@ let hook = Logger::new(
 
 hook.info("hello")
 ```
+</details>
+
+<details><summary>基础 buffered sink 示例</summary>
+
+```moonbit
+let sink = buffered_sink(console_sink(), flush_limit=2)
+let logger = Logger::new(sink, target="buffered")
+
+logger.info("one")
+logger.info("two")
+sink.flush()
+```
+</details>
+
+<details><summary>基础 filter sink 示例</summary>
+
+```moonbit
+let sink = filter_sink(console_sink(), fn(rec) {
+  rec.target == "kept"
+})
+
+let kept = Logger::new(sink, target="kept")
+let dropped = Logger::new(sink, target="dropped")
+
+kept.info("visible")
+dropped.info("hidden")
+```
+</details>
+
+<details><summary>Logger 链式 filter 示例</summary>
+
+```moonbit
+let logger = Logger::new(console_sink(), target="service")
+  .with_filter(all_of([
+    target_has_prefix("service"),
+    message_contains("visible"),
+  ]))
+
+logger.info("hidden")
+logger.child("api").info("visible")
+```
+</details>
+
+<details><summary>Record patch 示例</summary>
+
+```moonbit
+let logger = Logger::new(console_sink(), target="auth")
+  .with_patch(compose_patches([
+    prefix_message("[safe] "),
+    redact_fields(["token"]),
+    append_fields([field("service", "bitlogger")]),
+  ]))
+
+logger.info("login", fields=[field("user", "alice"), field("token", "secret")])
+```
+</details>
+
+<details><summary>显式 queue sink 示例</summary>
+
+```moonbit
+let logger = Logger::new(console_sink(), target="queue")
+  .with_queue(max_pending=2, overflow=QueueOverflowPolicy::DropOldest)
+
+logger.info("one")
+logger.info("two")
+logger.info("three")
+ignore(logger.sink.flush())
+```
+</details>
+
+<details><summary>自定义文本 formatter 示例</summary>
+
+```moonbit
+let formatter = text_formatter(show_timestamp=false, separator=" | ")
+let logger = Logger::new(text_console_sink(formatter), target="pretty")
+
+logger.info("hello", fields=[field("mode", "pretty")])
+```
+
+</details>
+
+<details><summary>native 文件 sink 示例</summary>
+
+```moonbit
+if native_files_supported() {
+  let logger = Logger::new(file_sink("bitlogger.log"), target="file")
+  logger.info("hello", fields=[field("kind", "file")])
+  ignore(logger.sink.flush())
+  ignore(logger.sink.close())
+}
+```
+</details>
 
 ## 📂 仓库结构
 
@@ -60,4 +159,3 @@ hook.info("hello")
 
 - [Mooncake 文档页](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
 - [English README](./docs/README-en.md)
-