Rust WASM 异常处理规范（精简版）

核心原则：业务异常封闭

JavaScript只是渲染套壳，所有业务异常在Rust-WASM内部处理完毕，不向JavaScript传递。

必须遵守的规则

1. #[wasm_bindgen]函数签名

• **严禁**返回`Result<..., JsValue>`
• **必须**无返回值或只返回`JsValue`（纯数据）
• **必须**内部处理所有错误

// ✅ 正确
#[wasm_bindgen]
pub fn handle_click() {
    match business_logic() {
        Ok(result) => { let _ = JS_FNS.set_data_obj("result", Some(&result)); }
        Err(e) => { let _ = JS_FNS.alert(&format!("失败: {}", e)); }
    }
}

// ❌ 错误
#[wasm_bindgen]
pub fn handle_click() -> Result<(), JsValue> {
    business_logic()?;  // 错误会传到JavaScript
    Ok(())
}

2. 错误类型统一

• **必须**所有错误统一为`CatError`
• **必须**第三方库错误立即转换
• **必须**JavaScript异常通过`JS_FNS`自动转换

// 第三方错误转换
external_lib::call()
    .map_err(|e| CatError::new_with(format!("外部错误: {}", e), -5000))?;

// JS_FNS已处理JavaScript异常
JS_FNS.set_data_str("key", "value")?;  // 内部已转CatError

3. 用户反馈

• **必须**所有错误提供用户可感知的反馈
• **必须**使用`JS_FNS.alert()`或`JS_FNS.set_data_*()`

match api_call().await {
    Ok(data) => { let _ = JS_FNS.set_data_obj("data", Some(&data)); }
    Err(e) => { 
        let _ = JS_FNS.alert(&format!("操作失败: {}", e));
        let _ = JS_FNS.set_data_str("error", &e.to_string());
    }
}

4. Panic安全

• **应该**避免`unwrap()`、`expect()`
• **严禁**使用`panic::catch_unwind`包装`JS_FNS`调用
• **必须**使用安全访问模式

// ✅ 安全访问
let value = vec.get(index).ok_or(CatError::new("索引越界"))?;

// ❌ 风险代码
let value = vec[index];  // 可能panic

重构检查点

1. **搜索并修复**所有`#[wasm_bindgen].*->.*Result.*JsValue`函数
2. **搜索并移除**所有`map_err(|e| JsValue::from_str(&e))`
3. **搜索并移除**所有`panic::catch_unwind`包装的JavaScript调用
4. **检查**所有错误分支是否有用户反馈

---

制定：林栖(cat07)

日期：2026-02-23

参考：《Rust (Actix-web) 编码规范 V2.0》

返回