crates_docs/tools/docs/
mod.rs

1//! 文档查询工具模块
2//!
3//! 提供用于查询 Rust crate 文档的工具和服务。
4//!
5//! # 子模块
6//!
7//! - `cache`: 文档缓存
8//! - `html`: HTML 处理
9//! - `lookup_crate`: Crate 文档查找
10//! - `lookup_item`: 项目文档查找
11//! - `search`: Crate 搜索
12//!
13//! # 示例
14//!
15//! ```rust,no_run
16//! use std::sync::Arc;
17//! use crates_docs::tools::docs::DocService;
18//! use crates_docs::cache::memory::MemoryCache;
19//!
20//! let cache = Arc::new(MemoryCache::new(1000));
21//! let service = DocService::new(cache).expect("Failed to create DocService");
22//! ```
23
24pub mod cache;
25pub mod html;
26pub mod lookup_crate;
27pub mod lookup_item;
28pub mod search;
29
30use crate::cache::{Cache, CacheConfig};
31use crate::config::PerformanceConfig;
32use std::sync::Arc;
33
34/// 文档服务
35///
36/// 提供 HTTP 客户端（带自动重试）、缓存和文档缓存的集中管理。
37///
38/// # 字段
39///
40/// - `client`: 带重试中间件的 HTTP 客户端（共享引用以实现连接池复用）
41/// - `cache`: 通用缓存实例
42/// - `doc_cache`: 文档专用缓存
43pub struct DocService {
44    client: Arc<reqwest_middleware::ClientWithMiddleware>,
45    cache: Arc<dyn Cache>,
46    doc_cache: cache::DocCache,
47}
48
49impl DocService {
50    /// 创建新的文档服务（使用默认 TTL）
51    ///
52    /// # 参数
53    ///
54    /// * `cache` - 缓存实例
55    ///
56    /// # 错误
57    ///
58    /// 如果 HTTP 客户端创建失败，返回错误
59    ///
60    /// # 示例
61    ///
62    /// ```rust,no_run
63    /// use std::sync::Arc;
64    /// use crates_docs::tools::docs::DocService;
65    /// use crates_docs::cache::memory::MemoryCache;
66    ///
67    /// let cache = Arc::new(MemoryCache::new(1000));
68    /// let service = DocService::new(cache).expect("Failed to create DocService");
69    /// ```
70    ///
71    /// # Note
72    ///
73    /// This method uses the global HTTP client singleton for connection pool reuse.
74    /// Make sure to call `init_global_http_client()` during server initialization
75    /// for optimal performance.
76    pub fn new(cache: Arc<dyn Cache>) -> crate::error::Result<Self> {
77        Self::with_config(cache, &CacheConfig::default())
78    }
79
80    /// 创建新的文档服务（使用自定义缓存配置）
81    ///
82    /// # 参数
83    ///
84    /// * `cache` - 缓存实例
85    /// * `cache_config` - 缓存配置
86    ///
87    /// # 错误
88    ///
89    /// 如果 HTTP 客户端创建失败，返回错误
90    ///
91    /// # Note
92    ///
93    /// This method uses the global HTTP client singleton for connection pool reuse.
94    /// If the global client is not initialized, it will be initialized with default config.
95    pub fn with_config(
96        cache: Arc<dyn Cache>,
97        cache_config: &CacheConfig,
98    ) -> crate::error::Result<Self> {
99        let ttl = cache::DocCacheTtl::from_cache_config(cache_config);
100        let doc_cache = cache::DocCache::with_ttl(cache.clone(), ttl);
101        // Use global HTTP client singleton for connection pool reuse
102        let client = crate::utils::get_or_init_global_http_client()?;
103        Ok(Self {
104            client,
105            cache,
106            doc_cache,
107        })
108    }
109
110    /// 创建新的文档服务（使用完整配置）
111    ///
112    /// # 参数
113    ///
114    /// * `cache` - 缓存实例
115    /// * `cache_config` - 缓存配置
116    /// * `perf_config` - 性能配置（仅用于初始化全局 HTTP 客户端，如果尚未初始化）
117    ///
118    /// # 错误
119    ///
120    /// 如果 HTTP 客户端创建失败，返回错误
121    ///
122    /// # Note
123    ///
124    /// This method uses the global HTTP client singleton for connection pool reuse.
125    /// The `perf_config` is used only if the global client hasn't been initialized yet.
126    /// For consistent configuration, call `init_global_http_client()` during server startup.
127    pub fn with_full_config(
128        cache: Arc<dyn Cache>,
129        cache_config: &CacheConfig,
130        _perf_config: &PerformanceConfig,
131    ) -> crate::error::Result<Self> {
132        let ttl = cache::DocCacheTtl::from_cache_config(cache_config);
133        let doc_cache = cache::DocCache::with_ttl(cache.clone(), ttl);
134        // Use global HTTP client singleton for connection pool reuse
135        let client = crate::utils::get_or_init_global_http_client()?;
136        Ok(Self {
137            client,
138            cache,
139            doc_cache,
140        })
141    }
142
143    /// 获取 HTTP 客户端（带重试中间件）
144    #[must_use]
145    pub fn client(&self) -> &reqwest_middleware::ClientWithMiddleware {
146        &self.client
147    }
148
149    /// 获取缓存实例
150    #[must_use]
151    pub fn cache(&self) -> &Arc<dyn Cache> {
152        &self.cache
153    }
154
155    /// 获取文档缓存
156    #[must_use]
157    pub fn doc_cache(&self) -> &cache::DocCache {
158        &self.doc_cache
159    }
160}
161
162impl Default for DocService {
163    fn default() -> Self {
164        let cache = Arc::new(crate::cache::memory::MemoryCache::new(1000));
165        Self::new(cache).expect("Failed to create default DocService")
166    }
167}
168
169/// 重新导出工具类型
170pub use lookup_crate::LookupCrateTool;
171pub use lookup_item::LookupItemTool;
172pub use search::SearchCratesTool;
173
174/// 重新导出缓存类型
175pub use cache::DocCacheTtl;
crates_docs/tools/docs/mod.rs

crates_docs/tools/docs/
mod.rs
