refactor: add shared logging crate
This commit is contained in:
@@ -4,6 +4,7 @@
|
||||
|
||||
## 文档列表
|
||||
|
||||
- [RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md](./RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md)：Rust 工作区统一日志模块 `shared-logging` 的职责边界、API、输出风格与 `api-server` 迁移规则。
|
||||
- [SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md)：`M2` 第七张微信 OAuth 状态表 `wechat_auth_state` 的字段、过期/消费语义、`wechat/start` 与 `wechat/callback` 的单次消费规则，以及多实例下的清理策略。
|
||||
- [SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md)：`M2` 第六张短信鉴权统计表 `sms_auth_event` 的事件范围、统计口径、索引与和风控/审计表的协作边界。
|
||||
- [SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md)：`M2` 第五张风控状态表 `auth_risk_block` 的作用域、活跃态、刷新/解除规则与读取派生约束。
|
||||
|
||||
155
docs/technical/RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md
Normal file
155
docs/technical/RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 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`
|
||||
|
||||
当前阶段建议最小文件结构：
|
||||
|
||||
```text
|
||||
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`
|
||||
@@ -258,6 +258,7 @@ server-rs/
|
||||
│ ├─ module-ai/ # AI 编排模块 crate
|
||||
│ ├─ shared-contracts/ # HTTP DTO / SSE event / 前后端兼容 contract
|
||||
│ ├─ shared-kernel/ # 跨模块共享领域类型、ID、枚举、值对象
|
||||
│ ├─ shared-logging/ # 工作区统一日志初始化与 tracing subscriber 基础设施
|
||||
│ ├─ platform-auth/ # JWT、cookie、provider adapter
|
||||
│ ├─ platform-oss/ # OSS 直传、签名、对象管理
|
||||
│ ├─ platform-llm/ # DashScope / Ark / 其他模型适配
|
||||
@@ -277,7 +278,8 @@ server-rs/
|
||||
3. `crates/module-*` 保持与当前业务模块边界一一对应，已明确退出本轮的 `editor` 遗留模块除外；必要时可在 crate 内部再拆 `application`、`domain`、`spacetime` 子层次。
|
||||
4. `crates/shared-contracts/` 负责与当前前端兼容的 JSON / SSE 协议。
|
||||
5. `crates/shared-kernel/` 只放跨模块复用的数据结构和规则，不碰框架。
|
||||
6. `crates/platform-*` 统一承接三方供应商与平台适配。
|
||||
6. `crates/shared-logging/` 负责统一日志初始化、过滤器解析与 subscriber 基础设施，不承接 HTTP 业务语义。
|
||||
7. `crates/platform-*` 统一承接三方供应商与平台适配。
|
||||
|
||||
命名补充说明：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user