Genarrative/docs/technical/RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md

Rust shared-logging crate 设计

日期：2026-04-21

1. 文档目的

这份文档用于明确 server-rs/ 下统一日志模块的落地方式。

目标是把当前仅存在于 crates/api-server/src/logging.rs 的日志初始化逻辑，上提为一个可被多 crate 复用的独立 shared-logging crate，并固定：

1. 统一日志模块的职责边界
2. api-server、后续 spacetime-module、测试支撑与脚本入口的复用方式
3. 日志过滤、subscriber 初始化、输出风格的统一口径
4. 不允许继续把日志初始化散落到各主工程 crate 中

2. 当前基线

当前 Rust 工作区里的日志实现现状：

1. api-server 内部已有 src/logging.rs
2. 该文件负责创建 EnvFilter 并初始化 tracing subscriber
3. main.rs 直接调用 init_tracing(&config)
4. 其它 crate 尚未复用同一套日志初始化逻辑

当前问题：

1. 日志初始化逻辑被绑定在 api-server 内部，无法作为工作区级共享能力复用
2. 后续 spacetime-module、测试支撑、独立 worker、脚本入口若需要日志，会继续复制粘贴
3. 当前没有独立 crate 作为“统一日志模块”承接输出风格、默认过滤器与 subscriber 初始化边界

3. crate 职责边界

3.1 shared-logging 负责

1. 提供工作区统一的 tracing subscriber 初始化入口
2. 提供统一的日志过滤器解析逻辑
3. 固定当前阶段的输出风格，例如 compact、with_target(true)
4. 为 api-server、后续 spacetime-module、测试支撑与独立入口提供可复用初始化函数

3.2 它不负责

1. 保存业务日志事件结构体
2. 直接耦合 Axum 中间件或 TraceLayer
3. 处理业务 request id、response headers、error body
4. 承担供应商日志上报、链路追踪采样、远端日志聚合

3.3 与其他 crate 的边界

1. shared-logging 只提供“日志基础设施初始化”
2. api-server 继续负责 HTTP 访问日志的 TraceLayer 挂载
3. request_context、错误中间件、响应头模块继续负责 request id 与响应元信息串联
4. 若未来需要结构化埋点或审计事件，应进入对应业务 crate，不进入 shared-logging

4. 目录与命名

统一落位：

1. server-rs/crates/shared-logging

当前阶段建议最小文件结构：

server-rs/crates/shared-logging/
├─ Cargo.toml
├─ README.md
└─ src/
   └─ lib.rs

说明：

1. 当前阶段只做库 crate，不做独立二进制入口
2. api-server 从 src/logging.rs 迁出后，直接依赖 shared-logging

5. API 设计

当前阶段建议提供以下最小 API：

1. init_tracing(log_filter: &str) -> Result<(), io::Error>
2. resolve_env_filter(default_filter: &str) -> EnvFilter

设计原因：

1. api-server 当前只需要一个初始化入口
2. 后续如 spacetime-module 需要不同默认过滤器，也可以复用 resolve_env_filter(...)
3. 避免在第一版就过度设计成复杂 builder

6. 配置约定

当前阶段仍保留现有配置来源：

1. api-server 默认读取 GENARRATIVE_API_LOG
2. 若环境变量未提供，则回落到配置对象中的 log_filter
3. shared-logging 不直接读取业务配置结构，只消费最终传入的默认 filter 字符串

这样做的原因：

1. 保持 shared-logging 对上层业务配置解耦
2. 避免把 AppConfig 类型反向沉到共享基础设施 crate

7. 输出风格约定

当前阶段固定沿用现有输出口径：

1. compact
2. with_target(true)
3. 基于 EnvFilter 做过滤

说明：

1. 先保证工作区统一
2. 后续若要引入 JSON 输出、环境区分或远端采集，再在 shared-logging 中集中演进

8. 落地规则

8.1 api-server

必须调整为：

1. 删除本地 src/logging.rs
2. 在 Cargo.toml 中引用 shared-logging
3. main.rs 改为调用 shared_logging::init_tracing(...)

8.2 其它 crate

后续若需要日志初始化，统一按以下规则：

1. 优先依赖 shared-logging
2. 不再在各自 crate 内重复实现一份 init_tracing

9. 不允许的设计漂移

后续实现时禁止出现以下情况：

1. 再为 api-server、spacetime-module 各自复制一份 subscriber 初始化逻辑
2. 把 Axum 的 TraceLayer 直接塞进 shared-logging
3. 把 request id、响应头、错误 envelope 这些 HTTP 语义放进 shared-logging
4. 为了抽象而把业务配置类型强耦合进共享日志 crate

10. 本任务完成定义

当以下条件满足时，统一日志模块任务视为完成：

1. shared-logging crate 已创建并加入 workspace
2. api-server 已改为依赖 shared-logging
3. 原 api-server/src/logging.rs 已被移除
4. 工作区文档与任务清单已同步到“统一日志模块”口径

11. 依据文件

1. server-rs/crates/api-server/src/logging.rs
2. server-rs/crates/api-server/src/main.rs
3. server-rs/crates/api-server/src/config.rs
4. server-rs/crates/api-server/README.md
5. backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md