错误处理

本文档说明 V2 协议的错误处理机制。

设计理念

V2 协议不定义全局错误码表，而是采用更灵活的错误处理方式：

方面	V1 做法	V2 做法
错误码	全局统一编号	各指令自行定义
错误信息	需查表	响应体直接携带
扩展性	新增需协调编号	各模块独立演进

响应结构

所有响应统一包含 code 和 message 字段：

message SomeResp {
  uint32 code = 1;     // 0=成功，非0=失败
  string message = 2;  // 人类可读的错误描述
  // ... 其他业务字段
}

错误码规则

code	含义
0	成功
> 0	失败，具体含义由各指令定义

错误处理示例

const resp = await sendCommand('AddFingerprint', req)

if (resp.code === 0) {
  console.log('指纹添加成功')
} else {
  // 直接使用 message 展示给用户
  alert(resp.message)
}

为什么不用全局错误码？

1. 避免编号冲突：不同模块独立开发，无需协调错误码分配
2. 语义更清晰：message 直接描述问题，无需查表
3. 便于国际化：message 可由设备端或服务端本地化
4. 减少耦合：新增指令无需修改全局错误码文档

常见错误场景

各指令可能返回的错误由具体指令文档定义，以下是一些通用场景：

场景	建议处理
权限不足	检查用户角色和凭证有效期
参数无效	检查请求参数格式和范围
资源不存在	确认 ID 是否正确
容量已满	删除无用数据后重试
设备忙	等待后重试