tomevault-io API Design Skill
适用范围
- 设计或调整 Tauri 命令接口
- 设计 DTO/响应结构
- 统一命名与校验策略
关键规则（Critical Rules）
- 外层响应统一
ApiResponse<T> - DTO 使用
serde+specta::Type，字段 camelCase 与前端一致 - 校验在命令边界完成，业务层返回
anyhow::Result并补充上下文 - 错误信息面向用户，简洁明确
标准响应
#[derive(serde::Serialize, specta::Type)]
#[specta(inline)]
pub struct ApiResponse<T: specta::Type> {
pub success: bool,
pub data: Option<T>,
pub error: Option<String>,
}
DTO 规范（示例）
#[derive(Debug, Clone, Serialize, Deserialize, specta::Type)]
#[serde(rename_all = "camelCase")]
pub struct CreateFactoryDto {
pub factory_code: Code,
pub factory_name: Name,
pub description: Description,
pub address: Option<String>,
pub contact: Option<String>,
pub phone: Option<String>,
pub is_active: Boolean,
}
命名与契约
- 命令：动词 + 名词（
get/create/update/delete） - DTO：
CreateXDto/UpdateXDto/XDto - 前后端字段统一 camelCase，Rust 侧使用
#[serde(rename_all = "camelCase")]
分页与列表
- 优先复用现有类型：
crate::material::material_service::MaterialsPage/MaterialsPaginatedResult - 返回列表时保持字段可直接渲染，避免二次拼装
校验建议
- 对
String长度、Option必填进行检查 - SQLx 之前完成基本校验，避免 DB 错误直接暴露
检查清单
- 响应使用
ApiResponse<T> - DTO 实现
specta::Type且字段 camelCase - 校验在命令边界完成
- 命名与既有命令风格一致
Converted and distributed by TomeVault — claim your Tome and manage your conversions.