Genarrative/server-rs/apps/api-server/README.md

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. 接入统一日志与 tracing
2. 接入 request_id
3. 接入统一错误处理中间件
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，保证调用方、日志链路和后续 envelope meta.requestId 可对齐。

当前错误处理中间件约定：

1. 对 Axum 默认产生的空 4xx / 5xx 响应，统一归一化为 legacy 兼容 JSON 错误体：{ error: { code, message, details? } }。
2. 已经带 content-type 的业务错误响应不会被覆盖，避免抢走后续 response envelope 的职责。
3. 统一错误日志会复用当前请求的 request_id，便于后续和响应头、envelope 元信息串联。

当前 response envelope 约定：

1. RequestContext 已记录 request_id、请求开始时间、默认 operation 与 envelope 协商结果。
2. json_success_body(...) / json_error_body(...) 会根据 x-genarrative-response-envelope 自动在“裸数据 / 标准 envelope / legacy error + meta”之间切换。
3. meta.apiVersion、meta.requestId、meta.routeVersion、meta.operation、meta.latencyMs、meta.timestamp 已按当前前端契约生成，响应头回写仍留给后续独立任务。

3. 边界约束

1. api-server 负责 HTTP、SSE、Cookie、Header、路由与协议装配。
2. 业务逻辑优先通过独立模块 package 暴露能力，再由主工程组合。
3. 外部副作用通过 platform-auth、platform-oss、platform-llm 与各模块 package 的应用层完成。
4. 不把领域规则直接堆在 handler 中。