knife-util

一个为 knife 项目提供通用工具和功能的 Rust 库，专注于 JSON 数据处理、路径管理和配置转换。

功能特性

🔧 错误处理

• 统一错误类型：提供 AppError 统一错误处理机制
• 错误链追踪：支持错误源追踪和堆栈信息
• 上下文信息：可添加自定义错误上下文
• 自动转换：支持与 std::io::Error 等标准错误类型互转

🔄 JSON 合并

• 深度合并：支持嵌套对象的递归合并
• 类型转换：自动处理字符串、数字、布尔值之间的转换
• 覆盖机制：支持 _override_ 字段强制覆盖
• 数组拼接：智能合并数组内容
• Trait 支持：为基本类型和集合类型提供合并 trait

📁 路径工具

• 智能检测：自动识别开发/生产环境
• 工作目录：根据环境自动获取正确的工作目录
• 路径构建：基于工作目录构建相对路径

⚙️ TOML 工具

• 双向转换：TOML 与 JSON 之间的无缝转换
• 文件支持：直接读取 TOML 文件并转换为 JSON
• 类型保持：保持数据类型的完整性

快速开始

安装

在 Cargo.toml 中添加依赖：

[dependencies]
knife-util = "0.2.0"

使用示例

JSON 合并

use knife_util::{AppError, merge_json};
use serde_json::json;

fn main() -> Result<(), AppError> {
    let target = json!({
        "user": {"name": "Alice", "age": 30},
        "settings": {"theme": "light"}
    });
    
    let source = json!({
        "user": {"email": "alice@example.com"},
        "settings": {"language": "en"}
    });
    
    let merged = merge_json(&target, &source)?;
    println!("合并结果: {}", serde_json::to_string_pretty(&merged).unwrap());
    Ok(())
}

使用覆盖机制

use knife_util::merge_json;
use serde_json::json;

let target = json!({"age": 25});
let source = json!({
    "age": 30,
    "age._override_": 35  // 强制覆盖为 35
});

let result = merge_json(&target, &source).unwrap();
assert_eq!(result["age"], 35);

路径工具

use knife_util::{AppError, get_work_dir, build_work_path, is_dev_mode};

fn main() -> Result<(), AppError> {
    // 获取工作目录
    let work_dir = get_work_dir()?;
    println!("工作目录: {:?}", work_dir);
    
    // 检查环境
    if is_dev_mode() {
        println!("当前在开发模式");
    }
    
    // 构建配置文件路径
    let config_path = build_work_path("config/app.toml")?;
    println!("配置文件路径: {:?}", config_path);
    
    Ok(())
}

TOML 转换

use knife_util::{AppError, toml_to_json, json_to_toml};
use serde_json::json;

fn main() -> Result<(), AppError> {
    // TOML 到 JSON
    let toml_str = r#"
        title = "My App"
        [database]
        host = "localhost"
        port = 5432
    "#;
    
    let json_value = toml_to_json(toml_str)?;
    println!("JSON: {}", serde_json::to_string_pretty(&json_value).unwrap());
    
    // JSON 到 TOML
    let json_data = json!({
        "app": {"name": "MyApp", "version": "1.0.0"},
        "database": {"host": "localhost", "port": 5432}
    });
    
    let toml_str = json_to_toml(&json_data)?;
    println!("TOML:\n{}", toml_str);
    
    Ok(())
}

错误处理

use knife_util::AppError;
use std::fs;

fn read_config() -> Result<String, AppError> {
    let content = fs::read_to_string("config.toml")?; // 自动转换为 AppError
    Ok(content)
}

fn main() -> Result<(), AppError> {
    match read_config() {
        Ok(content) => println!("配置内容: {}", content),
        Err(e) => {
            println!("错误: {}", e);
            if let Some(detail) = e.message_detail() {
                println!("详细信息: {}", detail);
            }
        }
    }
    Ok(())
}

API 文档

核心 Trait

• MergeJsonTrait: JSON 数据合并 trait
• MergeFromTrait: 同类型对象合并 trait

主要函数

JSON 合并

• merge_json(target, source): 深度合并两个 JSON 值

路径工具

• get_work_dir(): 获取工作目录
• is_dev_mode(): 检查是否为开发模式
• build_work_path(path): 构建工作路径

TOML 工具

• toml_to_json(toml_str): TOML 字符串转 JSON
• toml_file_to_json(file_path): TOML 文件转 JSON
• json_to_toml(json_value): JSON 转 TOML 字符串

错误处理

• AppError::new(code, message): 创建新错误
• AppError::from_error(code, message, err): 从其他错误创建
• AppError::with_attribute(key, value): 添加上下文信息

开发环境

环境要求

• Rust 1.70+
• Cargo

运行测试

cargo test

生成文档

cargo doc --open

许可证

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

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

详见 CHANGELOG.md