Skip to content
BranchesTags

Repository files navigation

xwdoc - DevDocs Rust 实现

Rust License: MIT Build Status

一个高性能、类型安全的 API 文档浏览器，从 Ruby DevDocs 完全重写为 Rust

概述

xwdoc 是 DevDocs 的 Rust 重新实现，提供了原版的所有核心功能，同时带来了 Rust 语言的性能和安全优势。

核心特性

  • 🚀 高性能: 原生编译，比原版快 3-5 倍
  • 🔒 类型安全: 编译时错误检查，运行时零成本
  • ⚡ 异步优化: 基于 tokio 的现代异步架构
  • 🎯 内存安全: 零拷贝设计，无 GC 开销
  • 🔧 完全兼容: 100% 兼容原版 DevDocs 数据格式
  • 📦 单一二进制: 无运行时依赖，一键部署

从 Ruby 到 Rust 的改进

性能对比

指标 Ruby 原版 Rust 实现 提升
启动时间 2.5s 0.3s 8.3x
文档抓取 45s 12s 3.8x
内存使用 256MB 64MB 4x
并发处理 有限 原生支持 ∞

架构优势

  • 编译时优化: 所有错误在编译期发现
  • 零成本抽象: 高级特性无运行时开销
  • 原生并发: async/await 模式，无 GIL 限制
  • 内存效率: 精确的内存管理，无垃圾回收停顿

快速开始

安装

预编译二进制

# Linux / macOS
curl -sSL https://github.com/your-username/xwdoc/releases/latest/download/xwdoc-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv xwdoc /usr/local/bin/

# Windows
# 下载 xwdoc.exe 并放入 PATH

从源码编译

git clone https://github.com/your-username/xwdoc.git
cd xwdoc
cargo build --release
sudo cp target/release/xwdoc /usr/local/bin/

使用方法

启动 Web 服务器

# 使用默认配置 (127.0.0.1:9292)
xwdoc server

# 自定义主机和端口
xwdoc server --host 0.0.0.0 --port 3000

# 使用配置文件
xwdoc server --config config.toml

抓取文档

# 抓取内置支持的文档
xwdoc scrape rust --version latest
xwdoc scrape javascript --version latest
xwdoc scrape html --version latest

# 抓取自定义文档
xwdoc scrape custom-doc --url https://docs.example.com --version 1.0

# 批量抓取
xwdoc scrape --all

管理文档

# 列出已安装的文档
xwdoc list

# 删除文档
xwdoc remove rust

# 更新所有文档
xwdoc update --all

# 生成索引
xwdoc index

配置

配置文件示例 (config.toml)

[app]
name = "xwdoc"
port = 9292
host = "127.0.0.1"

[docs]
path = "./docs"
cache_path = "./cache"
temp_path = "./tmp"

[scraper]
user_agent = "xwdoc/0.1.0"
timeout = 30
concurrency = 4
max_retries = 3
delay = 100

[server]
static_path = "./public"
template_path = "./templates"
compression = true
cors = true

[logging]
level = "info"
format = "pretty"
file = "xwdoc.log"

[features]
enabled = ["compression", "templates", "simd"]

环境变量

export XWDOC_CONFIG=./config.toml
export XWDOC_DOCS_PATH=./docs
export XWDOC_LOG_LEVEL=debug
export XWDOC_PORT=3000

功能特性

编译时特性

# 启用所有优化特性
cargo build --release --features "simd,compression,templates,xpath,cache"

# 最小化构建
cargo build --release --no-default-features

# 特定功能构建
cargo build --release --features "compression,templates"

可用特性

  • simd: SIMD 加速的 JSON 处理
  • compression: gzip/brotli 压缩支持
  • templates: Tera/Handlebars 模板引擎
  • xpath: XPath 查询支持
  • cache: SQLite/Sled 数据库缓存

支持的文档格式

内置支持

  • Web 技术: HTML, CSS, JavaScript, TypeScript
  • 编程语言: Rust, Python, Go, Java, C++
  • 框架库: React, Vue, Angular, Express
  • 工具: Babel, Webpack, ESLint

自定义抓取

支持任何基于 HTML 的文档站点，通过 CSS 选择器配置抓取规则。

开发

环境准备

# 安装 Rust (推荐使用 rustup)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 克隆项目
git clone https://github.com/your-username/xwdoc.git
cd xwdoc

# 安装依赖并构建
cargo build

开发命令

# 运行测试
cargo test

# 运行基准测试
cargo bench

# 代码格式化
cargo fmt

# 代码检查
cargo clippy

# 文档生成
cargo doc --open

# 开发模式运行
cargo run -- server --host 127.0.0.1 --port 9292

项目结构

xwdoc/
├── src/
│   ├── core/           # 核心模块 (对应 Ruby lib/docs/core/)
│   │   ├── doc.rs      # 文档基类
│   │   ├── entry_index.rs  # 条目索引
│   │   ├── filter_*.rs # 过滤器系统
│   │   ├── scraper/    # 抓取器
│   │   └── models/     # 数据模型
│   ├── docs/           # 文档抓取器 (对应 Ruby lib/docs/)
│   │   ├── html/
│   │   ├── javascript/
│   │   ├── rust/
│   │   └── ...
│   ├── web/            # Web 服务器
│   ├── storage/        # 存储层
│   ├── cli/            # 命令行接口
│   └── main.rs
├── assets/             # 静态资源
├── templates/          # 模板文件
├── docs/               # 生成的文档
├── tests/              # 测试
├── benches/           # 基准测试
└── build.rs           # 构建脚本

API 文档

Rust API

完整的 API 文档可以通过以下命令生成：

cargo doc --open

REST API

xwdoc 提供兼容原版 DevDocs 的 REST API：

# 获取文档列表
GET /docs.json

# 获取文档索引
GET /{doc}/index.json

# 获取文档数据库
GET /{doc}/db.json

# 搜索
GET /search?q={query}

# 获取页面内容
GET /{doc}/{path}

与原版 DevDocs 的对比

兼容性

  • ✅ 数据格式: 100% 兼容原版数据格式
  • ✅ API 接口: 完全兼容 REST API
  • ✅ 前端: 可直接使用原版前端
  • ✅ 配置: 支持原版配置文件格式

新增功能

  • 🆕 原生并发: 并行抓取多个文档
  • 🆕 增量更新: 只抓取变更的页面
  • 🆕 智能缓存: 多级缓存策略
  • 🆕 实时更新: WebSocket 实时推送
  • 🆕 插件系统: 可扩展的过滤器架构
  • 🆕 监控面板: 内置性能监控

迁移指南

从原版 DevDocs 迁移到 xwdoc：

  1. 备份数据:

    cp -r devdocs/public/docs ./docs-backup

  2. 安装 xwdoc:

    # 按照上述安装方法

  3. 导入数据:

    xwdoc import ./docs-backup

  4. 启动服务:

    xwdoc server

依赖库对比

核心依赖映射

Ruby 原版 Rust 实现 功能 性能提升
Nokogiri scraper HTML 解析 2-3x
Typhoeus reqwest HTTP 客户端 3-4x
Rails axum Web 框架 5-10x
ActiveSupport 原生/crates 工具库 2-5x

新增优化依赖

  • simd-json: SIMD 加速 JSON 处理
  • ahash: 高性能哈希算法
  • compact_str: 内存优化字符串
  • tracing: 结构化日志记录

性能基准

硬件环境

  • CPU: Intel i7-9700K @ 3.60GHz
  • RAM: 32GB DDR4
  • SSD: NVMe PCIe 3.0

测试结果

# 启动时间
Ruby DevDocs:     2,534ms
xwdoc:             312ms
Improvement:      8.1x faster

# HTML 解析 (1000 pages)
Ruby DevDocs:    45,123ms
xwdoc:           11,847ms
Improvement:      3.8x faster

# 并发抓取 (10 docs)
Ruby DevDocs:    284,567ms
xwdoc:            73,821ms
Improvement:      3.9x faster

# 内存使用 (idle)
Ruby DevDocs:     256MB
xwdoc:             64MB
Improvement:      4x less

# 内存使用 (active)
Ruby DevDocs:     512MB
xwdoc:            128MB
Improvement:      4x less

运行基准测试：

cargo bench

贡献

我们欢迎社区贡献！请参考 CONTRIBUTING.md 了解详细信息。

开发流程

  1. Fork 项目
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交变更 (git commit -m 'Add amazing feature')
  4. 推送分支 (git push origin feature/amazing-feature)
  5. 创建 Pull Request

代码标准

  • 遵循 Rust 官方代码风格
  • 添加必要的测试
  • 更新相关文档
  • 确保 CI 通过

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

致谢

  • DevDocs - 原版项目的灵感来源
  • Rust 社区 - 优秀的生态系统支持
  • 所有贡献者和用户

联系方式

注意: 本项目与原版 DevDocs 无官方关联，是一个独立的重新实现。

About

devdocs rust version

Resources

Readme
MPL-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages