📝 add Chinese examples and extension docs

2026-07-30 15:04:48 +00:00 · 2026-07-17 16:31:25 +08:00
parent 4e2ef69b11
commit b32de63d57
12 changed files with 496 additions and 26 deletions
@@ -0,0 +1,47 @@
+# 异步日志生命周期
+
+当 native 异步应用需要通过异步队列处理日志写入时，使用异步包。库声明的可用目标比可执行 `async fn main` 示例更广，仓库示例仍以 native 为主。
+
+## 导入两个包
+
+```moonbit
+import {
+  "Nanaloveyuki/BitLogger/src" @log,
+  "Nanaloveyuki/BitLogger/src-async" @async_log,
+  "moonbitlang/async",
+}
+```
+
+## 构建、运行、关闭
+
+```moonbit
+async fn main {
+  let raw = "{\"logger\":{\"min_level\":\"info\",\"target\":\"service.async\",\"sink\":{\"kind\":\"text_console\"}},\"async_config\":{\"max_pending\":64,\"overflow\":\"DropOldest\",\"max_batch\":16,\"linger_ms\":5,\"flush\":\"Batch\"}}"
+  let config = @async_log.parse_async_logger_build_config_text(raw) catch {
+    err => {
+      ignore(err)
+      return
+    }
+  }
+  let logger = @async_log.build_async_logger(config)
+
+  @async.with_task_group(group => {
+    group.spawn_bg(allow_failure=true, () => logger.run())
+    logger.info("worker started", fields=[@log.field("mode", "async")])
+    logger.shutdown()
+  })
+}
+```
+
+`run()` 持有 worker 循环。先启动它再记录日志，并调用 `shutdown()`，使待处理记录按配置的 flush 策略结束。
+
+## 运行仓库示例
+
+```bash
+moon run examples/async_basic --target native
+```
+
+## 下一步
+
+- 查看[队列](../extend/queue.md)中的溢出与 flush 选择。
+- 英文 API：[`parse_async_logger_build_config_text(...)`](../../api/parse-async-logger-build-config-text.md)、[`build_async_logger(...)`](../../api/build-async-logger.md)、[`run()`](../../api/async-logger-run.md)、[`shutdown()`](../../api/async-logger-shutdown.md)。
@@ -0,0 +1,35 @@
+# 配置驱动构建
+
+当 level、目标名、输出方式或队列策略应由部署配置决定时，使用这一流程。
+
+## 解析、构建、记录
+
+```moonbit
+let raw = "{\"min_level\":\"info\",\"target\":\"service\",\"sink\":{\"kind\":\"text_console\",\"text_formatter\":{\"show_timestamp\":false,\"separator\":\" | \"}},\"queue\":{\"max_pending\":64,\"overflow\":\"DropOldest\"}}"
+
+let config = @log.parse_logger_config_text(raw) catch {
+  err => {
+    ignore(err)
+    println("invalid logger configuration")
+    return
+  }
+}
+
+let logger = @log.build_logger(config)
+logger.info("configured logger ready")
+ignore(logger.flush())
+```
+
+解析先验证数据，再构造运行时 Logger。真实部署应将原始配置放在应用代码之外，并在配置进入进程的边界处理错误。
+
+## 运行仓库示例
+
+```bash
+moon run examples/config_build
+```
+
+## 下一步
+
+- 需要明确选择满队列时的行为，阅读[队列](../extend/queue.md)。
+- 需要后台 worker 生命周期时，阅读[异步日志生命周期](./async.md)。
+- 英文 API：[`parse_logger_config_text(...)`](../../api/parse-logger-config-text.md)、[`build_logger(...)`](../../api/build-logger.md)、[`with_queue(...)`](../../api/with-queue.md)。
@@ -0,0 +1,55 @@
+# 控制台与结构化字段
+
+命令行工具和服务都可以从这一流程开始。一条记录由 level、target、message 与可选 fields 构成。
+
+## 安装与导入
+
+```bash
+moon new log-demo
+cd log-demo
+moon add Nanaloveyuki/BitLogger@0.7.0
+```
+
+在应用的 `moon.pkg` 中加入：
+
+```moonbit
+import {
+  "Nanaloveyuki/BitLogger/src" @log,
+}
+```
+
+## 构建控制台 Logger
+
+```moonbit
+fn main {
+  let logger = @log.build_logger(
+    @log.console(min_level=@log.Level::Info, target="service.http"),
+  )
+
+  logger.info("listening", fields=[
+    @log.field("port", "8080"),
+    @log.field("environment", "development"),
+  ])
+  logger.warn("slow request", fields=[@log.field("path", "/health")])
+}
+```
+
+`min_level` 在记录到达 sink 前过滤日志；`target` 用于识别子系统；fields 用于携带可查询上下文，而不是拼接到 message 中。
+
+## 切换为 JSON
+
+保持日志调用不变，只替换配置：
+
+```moonbit
+let logger = @log.build_logger(
+  @log.json_console(min_level=@log.Level::Info, target="service.http"),
+)
+```
+
+当日志采集器按行处理结构化记录时，JSON 输出更合适。
+
+## 下一步
+
+- 需要自定义终端输出时，阅读[文本格式](../extend/formatting.md)。
+- 需要由 JSON 配置构建时，阅读[配置构建](./config.md)。
+- 英文 API：[`console(...)`](../../api/console.md)、[`json_console(...)`](../../api/json-console.md)、[`field(...)`](../../api/field.md)、[`build_logger(...)`](../../api/build-logger.md)。
@@ -0,0 +1,51 @@
+# 文件输出与轮转
+
+文件输出面向需要本地持久化的 native 应用。跨端代码应先判断能力，并保留控制台回退方案。
+
+## 检查能力
+
+```moonbit
+if !@log.native_files_supported() {
+  println("file logging is unavailable on this target")
+  return
+}
+```
+
+## 构建可轮转文件 Logger
+
+```moonbit
+let config = @log.with_file_rotation(
+  @log.file(
+    "service.log",
+    min_level=@log.Level::Info,
+    target="service.file",
+    auto_flush=true,
+  ) catch {
+    err => {
+      ignore(err)
+      return
+    }
+  },
+  1024 * 1024,
+  max_backups=3,
+)
+
+let logger = @log.build_logger(config)
+logger.info("file logger ready")
+ignore(logger.flush())
+ignore(logger.file_close())
+```
+
+轮转阈值是活动文件的字节数，`max_backups=3` 保留备份链。应用有序退出时必须关闭文件 Logger。
+
+## 运行仓库示例
+
+```bash
+moon run examples/file_rotation --target native
+```
+
+## 下一步
+
+- 写入突发较多时，加入[队列](../extend/queue.md)。
+- 与 web 目标共享代码前，阅读[目标平台边界](../extend/targets.md)。
+- 英文 API：[`file(...)`](../../api/file.md)、[`with_file_rotation(...)`](../../api/with-file-rotation.md)、[`file_close(...)`](../../api/configured-logger-file-close.md)。
@@ -0,0 +1,24 @@
+# 示例
+
+示例是 BitLogger 的主学习路径。每页从一个应用需求开始，给出完整最小代码，再链接到英文 API 参考查看精确契约。
+
+## 选择流程
+
+| 需求 | 从这里开始 | 后续扩展 |
+| --- | --- | --- |
+| 在终端输出结构化日志 | [控制台与字段](./console.md) | [文本格式](../extend/formatting.md) |
+| 保存本地日志并限制磁盘占用 | [文件轮转](./file-rotation.md) | [目标平台边界](../extend/targets.md) |
+| 由应用配置决定日志行为 | [配置构建](./config.md) | [队列](../extend/queue.md) |
+| 在 native 异步应用中处理日志写入 | [异步生命周期](./async.md) | [Sink 组合](../extend/composition.md) |
+
+## 可运行源码
+
+仓库中的 `examples/` 是可执行参考；本目录说明何时选择它们、如何运行，以及下一步应该扩展什么：
+
+- `examples/console_basic`
+- `examples/config_build`
+- `examples/file_rotation`
+- `examples/async_basic`
+- `examples/presets`、`examples/text_formatter`、`examples/style_tags`
+
+遇到函数签名、错误语义或边界条件时，请查询[英文 API 参考](../../api/index.md)。