# 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 中。