ruweb::webclient模块提供统一的HTTP客户端接口支持同步基于ureq与异步基于reqwest双实现。通过WebClientTrait抽象出get2ret、post2ret等泛型方法自动处理状态码检查与JSON反序列化返回RuResultlt;Tgt;。同步版依赖注入单例注册异步版直接使用async fn并复用reqwest连接池。WebMsg结构体支持消息驱动请求灵活适配各类场景。整体设计兼顾易用性与性能适用于高并发或简单调用需求。# ruweb::webclient 模块讲解## 概述webclient 是 **ruweb 框架的 HTTP 客户端模块**负责向外部服务发起 RESTful 请求。该模块采用**双实现设计**——同步基于 ureq与异步基于 reqwest并存上层通过统一的 trait 抽象调用。---## 目录结构src/ruweb/webclient/├── mod.rs # 模块入口导出所有子模块├── web_client_trait.rs # 统一 HTTP 方法抽象 trait├── web_client.rs # 同步实现基于 ureq├── web_client_init.rs # 依赖注入自动注册单例 Bean├── web_client_test.rs # 同步客户端测试└── webasync/ # 异步子模块├── mod.rs├── web_client.rs # 异步实现基于 reqwest├── web_client_init.rs # 异步版本依赖注入└── web_client_test.rs # 异步客户端测试---## 一、统一接口层WebClientTrait trait文件[web_client_trait.rs](file:///E:/soft/gitee.com/ruwebframe/src/ruweb/webclient/web_client_trait.rs)这是整个 HTTP 客户端的**抽象契约**定义了所有支持的 HTTP 方法### 基础 HTTP 方法返回原始 ureq::Response| 方法 | 说明 ||------|------|| get(url) | GET 请求 || post(url, body) | POST 请求body 为 JSON 字符串 || delete(url) | DELETE 请求 || put(url, body) | PUT 请求 || patch(url, body) | PATCH 请求 || head(url) | HEAD 请求 |### 高级封装方法自动解析为 RuResultT| 方法 | 说明 ||------|------|| get2retT(url) | GET → 自动反序列化为 RuResultT || post2retT(url, body) | POST → 自动反序列化为 RuResultT || put2retT(url, body) | PUT → 自动反序列化为 RuResultT || delete2retT(url) | DELETE → 自动反序列化为 RuResultT || patch2retT(url, body) | PATCH → 自动反序列化为 RuResultT |### 分页专用方法| 方法 | 说明 ||------|------|| get2page_retT(url) | GET 分页数据 || post2page_retT(url, body) | POST 分页数据 |### 消息驱动方法| 方法 | 说明 ||------|------|| http2retT(WebMsg) | 通过 WebMsg 结构体发请求 || res2retT(Response) | 原始 Response → RuResultT || res2page_retT(Response) | 原始 Response → 分页 RuResultT |**设计亮点***2ret 泛型方法的核心价值在于——调用方无需关心 HTTP 状态码检查和 JSON 反序列化过程框架自动完成直接得到业务层所需的 RuResultT 结构。---## 二、同步实现WebClient基于 ureq文件[web_client.rs](file:///E:/soft/gitee.com/ruwebframe/src/ruweb/webclient/web_client.rs)### 结构体定义rustpub struct WebClient {pub client_dto: ClientDto, // 客户端配置testUrl、超时等}### 核心机制**1. URL 构建逻辑** (build_url)- 如果 URL 以 http:// 或 https:// 开头 → 直接当作完整 URL 处理- 否则 → 通过 build_server_url 判断是否启用测试地址模式testUrl如果启用了则自动拼接前缀rust// 例如testUrl http://localhost:6001// build_url(conf) → http://localhost:6001/conf// build_url(http://api.example.com) → http://api.example.com**2. HTTP 请求实现**以 get 为例rustfn get(self, url: str) - Response {let urls self.build_url(url.to_string());ureq::get(urls.as_str()).set(Content-Type, application/json).set(Authorization, Bearer token123).call().unwrap()}每个请求都会自动注入 Content-Type: application/json 和 Authorization: Bearer token123 请求头。**3. 响应解析** (res2ret)rustfn res2retT(self, res: Response) - ru_result::RuResultT {// 1. 检查 HTTP 状态码是否为 200// 2. 读取 body 字符串// 3. 使用 rutils::json2struct 反序列化为 RuResultT// 4. 若任何环节失败返回 code500 的错误结果}**4. 消息驱动请求** (http2ret)通过 WebMsg 结构体传递完整的请求信息method、url、headers、body内部根据 method 字段动态路由到对应的 HTTP 方法执行。这使得**调用方可以统一通过一个方法发送任意类型的请求**。---## 三、异步实现WebClient基于 reqwest文件[webasync/web_client.rs](file:///E:/soft/gitee.com/ruwebframe/src/ruweb/webclient/webasync/web_client.rs)### 与同步版本的关键差异| 特性 | 同步版本 | 异步版本 ||------|---------|---------|| HTTP 库 | ureq | reqwest || 方法签名 | fn get(self) - Response | async fn get(self) - ResultResponse, Error || 额外字段 | 无 | client: RwLockreqwest::Client || Trait 实现 | 实现了 WebClientTrait | **未实现 trait**直接是 struct 方法 |### 为什么异步版本不实现 trait由于 Rust 的 trait 中对 async fn 的支持尚有限制需要 async_trait 或 AFIT异步版本选择直接在 WebClient struct 上定义 async fn 方法调用方使用 .await 等待。### 异步版本的结构体rustpub struct WebClient {pub client_dto: ClientDto,pub client: RwLockreqwest::Client, // 复用 reqwest::Client 连接池}reqwest::Client 内部维护连接池支持 HTTP/2适合高并发场景。用 RwLock 包装确保线程安全。### 方法对比同步版fn get2retT(self, url: str) - RuResultT异步版pub async fn get2retT(self, url: str) - RuResultT调用方式差别rust// 同步let ret client.get2ret::ConfDto(conf);// 异步let ret client.get2ret::ConfDto(conf).await;---## 四、依赖注入与单例注册文件- [web_client_init.rs](file:///E:/soft/gitee.com/ruwebframe/src/ruweb/webclient/web_client_init.rs)同步版- [webasync/web_client_init.rs](file:///E:/soft/gitee.com/ruwebframe/src/ruweb/webclient/webasync/web_client_init.rs)异步版两者完全对称核心代码rustuse crate::rubase::{BaseEntitySingle, BeanSingle};use ctor::ctor;#[ctor(unsafe)]pub fn init() {WebClient::register_bean_singleton(); // 程序启动时自动注册}pub fn find_bean_web_client() - OptionArcWebClient {WebClient::find_bean() // 全局访问入口}impl BeanSingle for WebClient {fn new_bean() - Self {let mut bean WebClient::new();bean.init(); // 从全局配置加载 ClientDtobean}}**关键机制**1. #[ctor(unsafe)] —— 这是 Rust 的 ctor crate允许在程序 main() 执行之前自动运行初始化函数2. BeanSingle trait —— 框架的单例 Bean 注册机制确保 WebClient 全局只有一个实例3. find_bean_web_client() —— 全局获取 WebClient 实例的入口函数返回 OptionArcWebClient4. init() 方法 —— 从全局配置 RuConfig 中读取 web_client 相关配置如 testUrl---## 五、WebMsg —— 消息驱动的请求封装在 http2ret 方法中使用将 HTTP 请求封装为结构体rustpub struct WebMsg {pub method: String, // get | post | delete | put | patch | headpub url: String, // 请求 URLpub body: String, // 请求体 JSONpub headers: Vec(String, String), // 自定义请求头}支持添加 token、自定义 header并通过 set_header() 统一应用到 ureq::Request。---## 六、使用示例总结rust// 1. 获取全局单例let client find_bean_web_client().unwrap();// 2. 基础 GET 请求返回原始 Responselet resp client.get(http://localhost:6001/conf);// 3. 高级 GET自动解析为 ConfDtolet ret client.get2ret::ConfDto(conf);// ret 是 ru_result::RuResultConfDto// 4. POST 请求let ret client.post2ret::ConfDto(conf, json_body);// 5. 消息驱动let mut msg WebMsg::default();msg.init_get(String::from(conf));let ret client.http2ret::ConfDto(msg);// 6. 异步版本在 async 上下文中let ret async_client.get2ret::ConfDto(conf).await;---## 整体架构图┌──────────────────────────────────────────────────┐│ 调用方代码 ││ (通过 find_bean_web_client 获取) │└──────────────┬───────────────────────────┬────────┘│ │▼ ▼┌─────────────────┐ ┌────────────────────┐│ WebClientTrait │ │ WebClient(异步) ││ (trait) │ │ (直接定义 async fn) │└────────┬────────┘ └─────────┬──────────┘│ │┌────────▼────────┐ ┌─────────▼──────────┐│ WebClient(同步) │ │ reqwest::Client ││ 基于 ureq │ │ 连接池复用 │└────────┬────────┘ └────────────────────┘│┌────────▼────────┐│ build_url() │──→ 自动拼接 testUrl 前缀│ res2ret() │──→ HTTP→RuResultT 转换│ http2ret() │──→ WebMsg 消息路由└─────────────────┘总的来说webclient 模块的设计体现了以下原则1. **统一抽象**通过 WebClientTrait 定义契约同步/异步各有实现2. **开箱即用**依赖注入 #[ctor] 自动初始化调用方只需 find_bean_web_client()3. **灵活切换**同步适用于简单场景异步适用于高并发 IO 密集场景