qiming/qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/HTTP API架构/路由配置.md

路由配置

**本文档引用的文件** - [router.rs](file://crates/agent_runner/src/router.rs) - [main.rs](file://crates/agent_runner/src/main.rs) - [handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs) - [middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs) - [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs) - [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs) - [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs) - [proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs) - [router.rs](file://crates/rcoder/src/router.rs)

目录

1. 项目结构
2. 核心路由注册机制
3. 模块化路由组织结构
4. 全局中间件应用
5. 路由层级划分逻辑
6. 动态路由参数处理
7. 错误传播模式
8. API端点详细说明
9. OpenAPI文档集成

项目结构

本项目采用模块化设计，HTTP API路由配置主要分布在crates/agent_runner和crates/rcoder两个核心模块中。路由配置的核心文件位于src/router.rs，通过Axum框架实现路由注册。处理器函数分布在src/handler目录下，按功能模块组织。中间件定义在src/middleware目录中，用于处理全局请求拦截和日志追踪。

graph TD
A[HTTP API路由系统] --> B[路由注册]
A --> C[处理器模块]
A --> D[中间件]
A --> E[应用状态]
B --> F[router.rs]
C --> G[handler/mod.rs]
D --> H[middleware/tracing_middleware.rs]
E --> I[AppState结构]
F --> J[create_router函数]
G --> K[health_handler]
G --> L[chat_handler]
G --> M[agent_session_notification]
G --> N[proxy_api]
H --> O[tracing_middleware_handler]
I --> P[sessions]
I --> Q[config]
I --> R[local_task_sender]
I --> S[pingora_service]

图源

• router.rs
• handler/mod.rs
• middleware/tracing_middleware.rs

节源

• router.rs
• main.rs

核心路由注册机制

基于Axum框架的路由注册机制通过create_router函数实现，该函数接收应用状态并返回配置好的Router实例。路由注册采用链式调用方式，将不同功能的路由分组后合并到主路由中。

路由注册的核心流程如下：

1. 创建API路由组，包含健康检查、聊天、代理会话通知等核心接口
2. 创建代理API路由组，提供Pingora反向代理相关的状态查询接口
3. 将各路由组合并到主路由中
4. 集成Swagger UI路由，提供API文档界面

sequenceDiagram
participant App as 应用启动
participant Router as 路由创建
participant API as API路由组
participant Proxy as 代理API路由组
participant Swagger as Swagger UI
App->>Router : create_router(state)
Router->>API : 创建API路由组
API->>API : route("/health", get(health_check))
API->>API : route("/chat", post(handle_chat))
API->>API : route("/agent/progress/{session_id}", get(agent_session_notification))
API->>Router : 返回API路由组
Router->>Proxy : 创建代理API路由组
Proxy->>Proxy : route("/proxy/status", get(proxy_status))
Proxy->>Proxy : route("/proxy/stats", get(proxy_stats))
Proxy->>Router : 返回代理API路由组
Router->>Swagger : 创建Swagger UI路由
Swagger->>Router : 返回Swagger路由
Router->>App : 合并所有路由并返回

图源

• router.rs

节源

• router.rs

模块化路由组织结构

路由处理器采用模块化组织结构，通过handler/mod.rs文件统一导出所有处理器模块。这种设计实现了关注点分离，使代码结构更加清晰和易于维护。

graph TD
A[handler/mod.rs] --> B[agent_cancel_handler]
A --> C[agent_session_notification]
A --> D[chat_handler]
A --> E[agent_status_handler]
A --> F[health_handler]
A --> G[proxy_api]
A --> H[proxy_handler_api]
B --> I[agent_session_cancel]
C --> J[agent_session_notification]
D --> K[handle_chat]
E --> L[agent_status]
F --> M[health_check]
G --> N[proxy_status]
G --> O[proxy_stats]
G --> P[proxy_config]
G --> Q[proxy_to_port]
G --> R[proxy_to_port_with_path]
G --> S[proxy_with_query_params]

图源

• handler/mod.rs

节源

• handler/mod.rs

全局中间件应用

通过Layer堆叠机制应用全局中间件，实现请求的统一处理。主要中间件包括追踪中间件，用于记录请求日志和生成trace_id。

graph TD
A[HTTP请求] --> B[Tracing中间件]
B --> C[提取或生成trace_id]
C --> D[创建日志span]
D --> E[记录请求开始]
E --> F[执行后续处理器]
F --> G[记录响应完成]
G --> H[返回响应]
subgraph 中间件处理流程
C
D
E
F
G
end

图源

• middleware/tracing_middleware.rs

节源

• middleware/tracing_middleware.rs

路由层级划分逻辑

路由系统采用清晰的层级划分逻辑，将公共接口与代理专用接口分离。这种设计提高了系统的可维护性和安全性。

graph TD
A[主路由] --> B[API路由组]
A --> C[代理API路由组]
A --> D[Swagger UI路由]
B --> E[公共接口]
E --> F[/health]
E --> G[/chat]
E --> H[/agent/progress/{session_id}]
E --> I[/agent/session/cancel]
E --> J[/agent/status/{project_id}]
C --> K[代理专用接口]
K --> L[/proxy/status]
K --> M[/proxy/stats]
K --> N[/proxy/config]
K --> O[/proxy/{port}]
K --> P[/proxy/{port}/{*path}]

图源

• router.rs

节源

• router.rs

动态路由参数处理

动态路由参数通过Axum的路径参数机制处理，支持路径参数和通配符参数。系统能够正确解析和验证动态路由参数。

flowchart TD
A[接收到请求] --> B{路径匹配}
B --> |/agent/progress/{session_id}| C[提取session_id]
B --> |/proxy/{port}| D[提取port]
B --> |/proxy/{port}/{*path}| E[提取port和path]
B --> |其他路径| F[返回404]
C --> G[验证session_id]
G --> H[调用agent_session_notification]
D --> I[验证port]
I --> J[调用proxy_to_port]
E --> K[验证port和path]
K --> L[调用proxy_to_port_with_path]

图源

• router.rs
• router.rs

节源

• router.rs

错误传播模式

系统采用统一的错误传播模式，通过Result类型传递错误信息。错误处理遵循以下原则：

1. 处理器函数返回Result类型，包含成功值或错误
2. 使用AppError类型封装各种错误情况
3. 错误信息包含错误代码和描述
4. 通过HttpResult包装器提供一致的响应格式

stateDiagram-v2
[*] --> 请求处理
请求处理 --> 验证输入
验证输入 --> |有效| 业务逻辑
验证输入 --> |无效| 返回验证错误
业务逻辑 --> |成功| 构建成功响应
业务逻辑 --> |失败| 构建错误响应
构建成功响应 --> 返回响应
构建错误响应 --> 返回响应
返回响应 --> [*]

图源

• chat_handler.rs
• model.rs

节源

• chat_handler.rs

API端点详细说明

健康检查端点

• 路径: /health
• 方法: GET
• 功能: 检查服务的健康状态
• 响应: 返回服务状态、时间戳和服务名称

聊天端点

• 路径: /chat
• 方法: POST
• 功能: 发送聊天消息并获取AI响应
• 请求体: 包含prompt、project_id、session_id等信息
• 响应: 返回项目ID和会话ID

代理会话通知端点

• 路径: /agent/progress/{session_id}
• 方法: GET
• 功能: 通过SSE协议实时推送AI代理执行进度
• 参数: session_id
• 响应: SSE流，包含各种类型的消息事件

代理API端点

• 路径: /proxy/status, /proxy/stats, /proxy/config等
• 方法: GET
• 功能: 提供Pingora反向代理的状态、统计和配置信息
• 参数: port, path等动态参数

节源

• health_handler.rs
• chat_handler.rs
• agent_session_notification.rs
• proxy_api.rs

OpenAPI文档集成

系统集成了OpenAPI文档功能，通过utoipa和utoipa_swagger_ui crate提供API文档界面。文档包含所有API端点的详细描述、请求参数、响应格式和示例。

graph TD
A[OpenAPI文档] --> B[API端点]
A --> C[组件定义]
A --> D[标签]
A --> E[信息]
B --> F[health_check]
B --> G[handle_chat]
B --> H[agent_session_notification]
B --> I[proxy_status]
B --> J[proxy_stats]
B --> K[proxy_config]
C --> L[请求体]
C --> M[响应体]
C --> N[参数]
D --> O[system]
D --> P[chat]
D --> Q[agent]
D --> R[proxy]
E --> S[描述]
E --> T[标题]
E --> U[版本]
E --> V[许可证]
E --> W[联系人]

图源

• router.rs

节源

• router.rs