CADmium序列化技术：Serde实现JSON序列化

【免费下载链接】CADmium A CAD program that runs in the browser 项目地址: https://gitcode.com/GitHub_Trending/cad/CADmium

引言：CAD数据的持久化挑战

在现代CAD（计算机辅助设计）系统中，数据持久化是一个核心需求。CADmium作为一个基于Rust和WebAssembly的浏览器端CAD程序，面临着如何高效、可靠地序列化复杂三维几何数据的挑战。通过Serde框架实现的JSON序列化方案，CADmium成功解决了这一难题。

本文将深入解析CADmium如何利用Serde实现完整的JSON序列化体系，涵盖从基础数据结构到复杂几何实体的序列化实现。

Serde框架概述

Serde是Rust生态中最流行的序列化框架，提供了一套统一的API来处理各种数据格式的序列化和反序列化。在CADmium中，Serde与serde_json配合使用，实现了完整的JSON序列化能力。

// Cargo.toml依赖配置
[dependencies]
serde = "1.0.202"
serde_json = "1.0.117"
tsify = "0.4.5"  // 用于WebAssembly互操作

核心数据结构的序列化实现

1. Project结构体的序列化

Project是CADmium的核心数据结构，代表整个CAD项目：

#[derive(Tsify, Debug, Serialize, Deserialize)]
#[tsify(into_wasm_abi, from_wasm_abi)]
pub struct Project {
    pub name: String,
    pub assemblies: Vec<Assembly>,
    pub workbenches: Vec<Workbench>,
}

impl Project {
    pub fn json(&self) -> String {
        match serde_json::to_string(self) {
            Ok(json) => json,
            Err(e) => format!("Error: {}", e),
        }
    }

    pub fn from_json(json: &str) -> Self {
        match serde_json::from_str(json) {
            Ok(p) => p,
            Err(e) => {
                println!("Error: {}", e);
                Project::new("Error")
            }
        }
    }
}

2. 几何实体的序列化

CADmium定义了多种几何实体，都实现了Serde的序列化：

// 三维点
#[derive(Tsify, Debug, Clone, Serialize, Deserialize)]
pub struct Point3 {
    pub x: f64,
    pub y: f64,
    pub z: f64,
    pub hidden: bool,
}

// 三维线段
#[derive(Tsify, Debug, Clone, Serialize, Deserialize)]
pub struct Line3 {
    pub start: u64,
    pub end: u64,
}

// 三维圆
#[derive(Tsify, Debug, Clone, Serialize, Deserialize)]
pub struct Circle3 {
    pub center: u64,
    pub radius: f64,
    pub top: u64,
}

序列化架构设计

层次化数据结构

CADmium采用层次化的数据结构设计，确保序列化的完整性和一致性：

序列化流程

实战：完整的序列化示例

创建并序列化项目

// 创建测试项目
fn create_test_project() -> Project {
    let mut p = Project::new("Test Project");
    let wb = p.workbenches.get_mut(0).unwrap();
    
    // 添加草图到平面
    wb.add_sketch_to_plane("Sketch 1", "Plane-0");
    let s = wb.get_sketch_mut("Sketch 1").unwrap();
    
    // 添加几何元素
    let ll = s.add_point(0.0, 0.0);
    let lr = s.add_point(40.0, 0.0);
    let ul = s.add_point(0.0, 40.0);
    let ur = s.add_point(40.0, 40.0);
    
    s.add_segment(ll, lr);
    s.add_segment(lr, ur);
    s.add_segment(ur, ul);
    s.add_segment(ul, ll);
    
    p
}

// 序列化到JSON
let project = create_test_project();
let json_string = project.json();
println!("Serialized JSON: {}", json_string);

// 从JSON反序列化
let deserialized_project = Project::from_json(&json_string);

序列化结果示例

{
  "name": "Test Project",
  "assemblies": [],
  "workbenches": [
    {
      "name": "Workbench 1",
      "history": [
        {
          "name": "Plane-0",
          "data": {
            "Plane": {
              "plane": {
                "origin": { "x": 0.0, "y": 0.0, "z": 0.0, "hidden": false },
                "primary": { "x": 1.0, "y": 0.0, "z": 0.0, "hidden": false },
                "secondary": { "x": 0.0, "y": 1.0, "z": 0.0, "hidden": false }
              },
              "name": "Plane-0",
              "width": 100.0,
              "height": 100.0
            }
          }
        },
        {
          "name": "Sketch 1",
          "data": {
            "Sketch": {
              "sketch": {
                "points": {
                  "1": { "x": 0.0, "y": 0.0, "hidden": false },
                  "2": { "x": 40.0, "y": 0.0, "hidden": false },
                  "3": { "x": 0.0, "y": 40.0, "hidden": false },
                  "4": { "x": 40.0, "y": 40.0, "hidden": false }
                },
                "line_segments": {
                  "1": { "start": 1, "end": 2 },
                  "2": { "start": 2, "end": 4 },
                  "3": { "start": 4, "end": 3 },
                  "4": { "start": 3, "end": 1 }
                }
              },
              "plane_description": { "PlaneId": "Plane-0" }
            }
          }
        }
      ]
    }
  ]
}

高级序列化特性

1. 枚举类型的序列化

CADmium使用枚举来表示不同的操作类型：

#[derive(Tsify, Debug, Serialize, Deserialize)]
#[tsify(into_wasm_abi, from_wasm_abi)]
pub enum Message {
    RenameWorkbench {
        workbench_id: u64,
        new_name: String,
    },
    NewPointOnSketch {
        workbench_id: u64,
        sketch_id: String,
        x: f64,
        y: f64,
        hidden: bool,
    },
    NewExtrusion {
        workbench_id: u64,
        extrusion_name: String,
        sketch_id: String,
        face_ids: Vec<u64>,
        length: f64,
        offset: f64,
        direction: Direction,
    }
}

2. 自定义序列化逻辑

对于需要特殊处理的类型，可以实现自定义的序列化逻辑：

impl Message {
    pub fn as_json(&self) -> String {
        match serde_json::to_string(self) {
            Ok(json) => json,
            Err(e) => format!("Error: {}", e),
        }
    }

    pub fn from_json(json: &str) -> Result<Message, anyhow::Error> {
        Ok(serde_json::from_str(json)?)
    }
}

性能优化策略

1. 避免不必要的克隆

在序列化过程中，CADmium尽量避免不必要的数据克隆：

#[wasm_bindgen(getter)]
pub fn json(&self) -> String {
    self.native.json()  // 直接调用底层实现
}

2. 错误处理优化

采用友好的错误处理机制，确保序列化失败时仍能提供有用的信息：

pub fn json(&self) -> String {
    let result = serde_json::to_string(self);
    match result {
        Ok(json) => json,
        Err(e) => format!("Error: {}", e),  // 提供详细的错误信息
    }
}

应用场景与最佳实践

1. 项目保存与加载

// 保存项目到文件
fn save_project(project: &Project, filename: &str) -> std::io::Result<()> {
    let json = project.json();
    std::fs::write(filename, json)
}

// 从文件加载项目
fn load_project(filename: &str) -> std::io::Result<Project> {
    let contents = std::fs::read_to_string(filename)?;
    Ok(Project::from_json(&contents))
}

2. 网络传输

CADmium的JSON序列化格式非常适合网络传输：

// 前端JavaScript代码示例
async function saveProjectToServer(project) {
    const response = await fetch('/api/projects', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: project.json()  // 直接使用序列化的JSON
    });
    return response.json();
}

3. 版本控制友好

由于使用纯文本JSON格式，CADmium项目文件非常适合版本控制系统：

# 查看项目文件变更
git diff project.cadmium

# 合并冲突时更容易解决

技术对比：JSON vs 二进制格式

特性	JSON格式	二进制格式
可读性	✅ 人类可读	❌ 需要特殊工具
兼容性	✅ 广泛支持	⚠️ 格式特定
文件大小	❌ 较大	✅ 较小
解析速度	⚠️ 较慢	✅ 较快
调试便利	✅ 容易调试	❌ 困难
版本控制	✅ 友好	❌ 不友好

总结与展望

CADmium通过Serde实现的JSON序列化方案提供了一个强大而灵活的数据持久化机制。这种方案具有以下优势：

1. 跨平台兼容性：JSON是Web标准，确保在各种环境中的兼容性
2. 调试友好性：人类可读的格式大大简化了调试过程
3. 扩展性：易于添加新的数据类型和功能
4. 生态系统：充分利用Rust和JavaScript生态系统的工具链

未来可能的改进方向包括：

• 支持增量序列化，减少大型项目的序列化开销
• 添加压缩支持，减小文件体积
• 实现更高效的二进制序列化格式作为可选方案

通过Serde框架，CADmium成功构建了一个既强大又易用的序列化系统，为浏览器端CAD应用的发展奠定了坚实的基础。

【免费下载链接】CADmium A CAD program that runs in the browser 项目地址: https://gitcode.com/GitHub_Trending/cad/CADmium