60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
# api-server 主工程 package 占位说明
|
||
|
||
日期：`2026-04-20`
|
||
|
||
## 1. package 职责
|
||
|
||
`api-server` 是新后端的 Axum 主工程 package，后续负责：
|
||
|
||
1. `main.rs` 启动入口
|
||
2. `Router` 装配
|
||
3. `with_state` 共享状态注入
|
||
4. 中间件挂载
|
||
5. `/healthz`、`/api/*`、SSE 与静态资源兼容层装配
|
||
|
||
## 2. 当前阶段说明
|
||
|
||
当前目录已经完成以下基础骨架：
|
||
|
||
1. 目录占位
|
||
2. `Cargo.toml`
|
||
3. `src/main.rs`
|
||
4. `src/app.rs`
|
||
5. `src/state.rs`
|
||
6. `src/config.rs`
|
||
7. `src/logging.rs`
|
||
8. 基础 `TraceLayer` 挂载与 `tracing subscriber` 初始化
|
||
|
||
后续与本 package 直接相关的任务包括：
|
||
|
||
1. [x] 接入统一日志与 tracing
|
||
2. [x] 接入 `request_id`
|
||
3. [x] 接入统一错误处理中间件
|
||
4. [ ] 接入 response envelope
|
||
5. [ ] 接入 `/healthz`
|
||
|
||
当前 tracing 约定：
|
||
|
||
1. 进程启动时统一初始化 `tracing subscriber`。
|
||
2. 默认日志过滤器来自 `GENARRATIVE_API_LOG`，未提供时回落到 `info,tower_http=info`。
|
||
3. HTTP 访问日志统一通过 Axum 路由层的 `TraceLayer` 输出，后续 `request_id`、响应头与错误中间件继续在同一层扩展。
|
||
|
||
当前 request context 约定：
|
||
|
||
1. 中间件优先读取来访 `x-request-id`，未提供时生成新的 UUID。
|
||
2. `request_id` 会统一写入请求 `extensions` 与请求头，供 tracing、错误处理中间件和响应头层复用。
|
||
3. 响应头回写 `x-request-id` 仍属于后续独立任务，本阶段只完成请求上下文准备。
|
||
|
||
当前错误处理中间件约定：
|
||
|
||
1. 对 Axum 默认产生的空 `4xx / 5xx` 响应，统一归一化为 legacy 兼容 JSON 错误体：`{ error: { code, message, details? } }`。
|
||
2. 已经带 `content-type` 的业务错误响应不会被覆盖，避免抢走后续 response envelope 的职责。
|
||
3. 统一错误日志会复用当前请求的 `request_id`，便于后续和响应头、envelope 元信息串联。
|
||
|
||
## 3. 边界约束
|
||
|
||
1. `api-server` 负责 HTTP、SSE、Cookie、Header、路由与协议装配。
|
||
2. 业务逻辑优先通过独立模块 package 暴露能力，再由主工程组合。
|
||
3. 外部副作用通过 `platform-auth`、`platform-oss`、`platform-llm` 与各模块 package 的应用层完成。
|
||
4. 不把领域规则直接堆在 handler 中。
|