游塔极光团队 Rust 全栈开发代码规范总结报告

游塔极光团队 Rust 全栈开发代码规范总结报告

📋 文档概览

| 文档名称 | 版本 | 大小 | 制定日期 | 制定人 |

|----------|------|------|----------|--------|

| Rust (Actix-web) 编码规范 V2.0 | V2.0 | 63.7KB | - | 团队 |

| 团队Rust WASM编码规范 V1.0 | V1.0 | 16.6KB | 2026-02-28 | 林栖(cat07) |

| Rust WASM 异常处理规范（精简版） | V1.0 | 2.3KB | 2026-02-23 | 林栖(cat07) |

🎯 核心设计理念

1.1 架构定位

1.2 核心原则

  1. 业务异常封闭原则: JavaScript只是渲染套壳，所有业务异常在Rust-WASM内部处理完毕，不向JavaScript传递

  2. 统一错误处理原则: 所有错误统一转换为CatError类型，错误处理模式一致

  3. 用户感知反馈原则: 所有错误必须提供用户可感知的反馈，错误信息对用户友好

  4. 安全可靠原则: 避免运行时panic，确保WASM模块稳定性，防御性编程

1.3 AI友好性指南

📝 命名规范 (Rust Actix-web 规范 V2.0)

2.1 通用命名规则

2.2 多语言团队协作约束

严禁使用其他编程语言的关键字或常用标识符作为Rust变量、函数或类型名：

| 语言 | 严重程度 | 示例标识符 |

|------|----------|------------|

| SQL | 严格禁止 | desc, limit, date, where, match, set, map, string等关键字 |

| Java | 严格禁止 | class, interface, public, static, String, Object等 |

| Python | 严格禁止 | async, await, def, list, dict, tuple, print等 |

| PHP | 建议避免 | echo, print_r, array, date, time等内置函数 |

| Dart | 严格禁止 | var, final, async, String, List, Map等 |

| JavaScript | 严格禁止 | function, console, window, Promise, async, await等 |

| Rust | 严格禁止 | fn, struct, trait, impl, mut, Option, Result等 |

替代策略:

2.3 desc 术语使用规范

  1. 允许使用场景: 与数据库字段和数据库表直接相关的方法名、字段名

- 示例: getuserdesc(), productdescription, orderdesc

  1. 不鼓励使用场景: 通用业务逻辑中的变量名、函数名

  2. 固定用法: 跨语言传输的DTO中，若已有Java端定义的StdDataResponse包含desc字段，Rust端应保持对应字段名一致

🔧 Rust WASM 异常处理规范

3.1 #[wasm_bindgen]函数签名规则

规则1: 严禁返回 Result<..., JsValue>



// ❌ 错误：业务异常泄漏到JavaScript


#[wasm_bindgen]


pub fn handle_click() -> Result<(), JsValue> {


    business_logic()?;  // 错误会传到JavaScript


    Ok(())


}


// ✅ 正确：内部处理所有错误


#[wasm_bindgen]


pub fn handle_click() {


    match business_logic() {


        Ok(result) => { let  = JSFNS.setdataobj("result", Some(&result)); }


        Err(e) => { let  = JSFNS.alert(&format!("失败: {}", e)); }


    }


}

规则2: 必须无返回值或只返回JsValue（纯数据）

规则3: 异步函数必须内部处理错误

3.2 错误类型统一规则

规则4: 所有错误统一为CatError



// 第三方错误立即转换


external_lib::call()


    .maperr(|e| CatError::newwith(format!("外部错误: {}", e), -5000))?;

规则5: JavaScript异常通过JS_FNS自动转换



// JS_FNS调用内部已处理JavaScript异常


JSFNS.setdata_str("key", "value")?;  // 内部已转CatError


JS_FNS.alert("消息")?;

3.3 用户反馈规则

规则6: 所有错误必须提供用户可感知的反馈

规则7: 使用适当的反馈方式

3.4 Panic安全规则

规则8: 避免unwrap()和expect()



// ❌ 错误：可能导致panic


let value = serdewasmbindgen::to_value(&data).unwrap();


let value = vec[index];  // 直接索引可能panic


self.quit_login().expect("Quit Login Fail");


// ✅ 正确：安全访问模式


let value = vec.get(index).ok_or(CatError::new("索引越界"))?;

规则9: 严禁使用panic::catchunwind包装JSFNS调用

规则10: 必须使用安全访问模式

🏗️ 团队特有编码约定

4.1 JS_FNS抽象层约定

约定1: 所有JavaScript交互必须通过JS_FNS



// ✅ 正确：通过JS_FNS抽象层


let  = JSFNS.setdatastr("key", "value");


let  = JSFNS.alert("消息");


let  = JSFNS.setdataobj("data", Some(&data));


// ❌ 错误：直接调用JavaScript


#[wasm_bindgen]


extern "C" {


    fn alert(message: &str);


}


alert("消息");

约定2: JSFNS调用忽略返回值使用let =

4.2 数据传递约定

约定3: 复杂数据使用serdewasmbindgen序列化

约定4: 简单数据使用字符串传递

4.3 异步处理约定

约定5: 长时间操作提供进度反馈

约定6: 网络请求处理连接状态

🎨 代码结构与组织 (Rust Actix-web 规范)

5.1 模块组织结构

5.2 错误处理模式



// 统一错误类型定义


pub type CatResult = Result;


// 错误转换实现


impl From for CatError {


    fn from(err: sqlx::Error) -> Self {


        match err {


            sqlx::Error::RowNotFound => CatError::new("数据不存在"),


             => CatError::newwith(format!("数据库错误: {}", err), -1000),


        }


    }


}

5.3 接口响应格式



// 统一响应结构


#[derive(Serialize)]


pub struct StdDataResponse {


    pub code: i32,


    pub data: Option,


    pub desc: String,  // 支持多语言的业务描述


    pub timestamp: i64,


}

🚨 关键约束与禁令

6.1 绝对禁止项

  1. WASM函数返回Result<..., JsValue> - 业务异常不得泄漏到JavaScript

  2. 使用其他语言关键字作为Rust标识符 - 避免跨语言混淆

  3. 直接调用JavaScript API - 必须通过JS_FNS抽象层

  4. unwrap()和expect()不加处理 - 避免运行时panic

  5. panic::catchunwind包装JSFNS调用 - JS_FNS内部已处理异常

6.2 强烈建议项

  1. 所有错误转换为CatError - 统一错误处理

  2. 提供用户可感知的错误反馈 - 增强用户体验

  3. 使用安全访问模式 - 避免索引越界等错误

  4. 异步函数内部处理所有错误 - 避免未处理Promise

6.3 团队特殊约定

  1. desc字段使用 - 仅限数据库相关和跨语言DTO

  2. JS_FNS抽象层 - 所有JavaScript交互的统一入口

  3. serdewasmbindgen序列化 - 复杂数据传递标准

🤖 AI辅助开发指导

7.1 代码生成规则

  1. 严格遵守关键词强度标识

- 必须(MUST): 绝对要求，无例外

- 严禁(MUST NOT): 绝对禁止，无例外

- 应该(SHOULD): 强烈建议，除非有充分理由

  1. 参考结构化规则格式

```

[规则ID] [强度] [规则描述]

适用范围: [模块/类型]

示例:

正例: [代码示例]

反例: [代码示例]

理由: [解释原因]

```

  1. 优先使用正例模式

7.2 代码审查要点

  1. WASM函数签名检查: 确保不返回Result<..., JsValue>

  2. 错误处理检查: 所有错误分支是否转换为CatError并提供用户反馈

  3. 命名规范检查: 避免使用其他语言关键字，符合命名规则

  4. 安全访问检查: 避免unwrap()、expect()和不安全索引

  5. JS_FNS使用检查: 所有JavaScript交互是否通过抽象层

7.3 团队协作注意事项

  1. 多语言标识符冲突: 特别检查SQL、Java、Python等关键字使用

  2. 跨语言DTO一致性: 保持与Java端StdDataResponse的结构一致

  3. 异常处理一致性: 所有错误统一使用CatError模式

  4. 用户反馈一致性: 错误信息格式和反馈方式统一

📊 实施与检查清单

8.1 Rust Actix-web 项目检查清单

8.2 Rust WASM 项目检查清单

8.3 代码审查检查清单

  1. 搜索模式:

- #[wasm_bindgen].->.Result.*JsValue

- maperr\(\\|e\\| JsValue::fromstr

- panic::catch_unwind

- \\.unwrap\( 和 \\.expect\(

  1. 命名检查:

- SQL关键字: desc, limit, date, where等

- Java关键字: class, interface, public等

- Python关键字: async, def, print等

  1. 错误处理检查:

- 所有错误是否转换为CatError

- 错误分支是否有用户反馈

- 第三方库错误是否转换

🔗 相关资源与参考

9.1 文档链接

9.2 工具支持

  1. clippy配置: 集成规范检查到Rust工具链

  2. 预提交钩子: 自动检查规范合规性

  3. CI/CD流水线: 集成自动化代码检查

  4. IDE插件: 实时规范提示和检查

9.3 团队培训

  1. 新成员培训: 规范解读和示例讲解

  2. 代码审查培训: 规范检查要点和方法

  3. AI工具培训: 如何利用AI辅助遵守规范

  4. 定期回顾: 规范更新和最佳实践分享

📈 规范演进与维护

10.1 版本管理

10.2 反馈机制

10.3 更新流程

  1. 提案: 团队成员提出规范变更建议

  2. 讨论: 团队讨论变更的必要性和影响

  3. 评审: 技术负责人评审和批准

  4. 发布: 更新文档并通知团队

  5. 培训: 针对重要变更进行培训

🎯 总结与建议

11.1 规范特点总结

  1. 全面性: 覆盖Rust Actix-web和WASM全栈开发

  2. 实践性: 基于团队实际项目经验总结

  3. 协作性: 考虑多语言团队协作需求

  4. AI友好: 结构化表述便于AI理解和遵守

  5. 用户导向: 强调用户体验和错误反馈

11.2 AI辅助开发建议

  1. 规则优先级: 优先遵守"必须"和"严禁"规则

  2. 示例参考: 代码生成时参考规范中的正例模式

  3. 检查集成: 在代码审查环节集成规范检查

  4. 持续学习: 根据团队反馈优化AI生成质量

11.3 团队实施建议

  1. 分阶段实施: 优先实施关键约束和禁令

  2. 工具支持: 开发自动化检查工具和插件

  3. 培训支持: 定期开展规范培训和分享

  4. 持续优化: 根据实践反馈不断完善规范

总结生成: 虾酱一号（游塔极光开发团队AI助手成员）

生成时间: 2026年3月18日

数据来源: 团队Rust全栈开发代码规范三份文档

返回

返回