提交 01d9c848 编写于 作者: DCloud-yyl's avatar DCloud-yyl

Update err-spec.md

上级 b0e57c62
## 规范
所有异步API,都应通过callback回调返回错误,在回调函数参数中包含错误信息,回调函数参数为JSON类型
完整定义如下:
```ts
//源错误信息
interface SourceError {
subject?: string,
code?: number,
message?: string,
cause?: SourceError | AggregateError
}
//聚合源错误信息
interface AggregateError extends SourceError {
errors: Array<SourceError|AggregateError>
}
//uni错误信息
interface UniError {
errSubject: string,
errCode: number,
errMsg: string,
data?: Object,
cause?: SourceError | AggregateError
}
//回调函数
function CallBack(err:UniError){
//console.log(JSON.stringify(res));
}
```
### SourceError
用于保存引起错误的源错误,如App端三方SDK的错误信息
- module
源错误(如App端三方SDK)模块名称,如uni-AD中的穿山甲广告SDK的模块名称为"csj"
- code
源错误(如App端三方SDK)的原始错误码
- message
源错误(如App端三方SDK)的原始错误描述信息
- cause
上级源错误,只有一个源错误时是SourceError,包含多个源错误时封装成AggregateError
**注意**
源错误可以根据业务情况扩展其它属性,如uni-AD中,可以添加slotId来表示聚合的三方广告位标识
### UniError
Uni统一错误信息,用于统一各平台(端)错误信息
- errSubject
统一错误主题(模块)名称,字符串类型,存在多级模块时使用"::"分割,即"模块名称::二级模块名称"
- errCode
统一错误码,数字类型
对于已经实现的API,继续保留现有errCode规范(保留向下兼容)
**新开发模块按以下规则**
错误码可以是正数,也可以是负数,推荐采用4或5位数字,模块内错误数字码唯一
数字范围划分:
+ 50000以下是端的错误码
+ 50000以上是云的错误码
errCode的错误数字码实现原则:
+ 微信小程序规范中有定义的按其规范进行统一
+ 微信小程序规范没有定义,由DCloud定义errCode发布到uni-app网站
+ 产生冲突时,以先定义发布的规范为准
- errMsg
统一错误描述信息,字符串类型,应准确描述引起的错误原因
- data
可选,错误时返回的数据,比如获取设备信息时,如部分数据获取成功,部分数据获取失败,此时触发错误回调,需将获取成功的数据放到data属性中
- cause
可选,源错误信息,可以包含多个错误,详见SourceError
### AggregateError
W3C规范:[](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError)
当源错误存在多个时,需要将SourceError封装到AggregateError对象中,按以下方式获取SourceError数组:
```ts
function CallBack(err:UniError){
var cerrs:SourceError[] = err.cause.errors;
}
```
## 平台兼容原则
- 保留原平台(端)的错误回调函数参数的属性
+ 如app端原来错误信息的属性是code和message,则继续保留,统一实现时增加UniError中定义的属性
+ 如微信小程序端错误错误信息的属性是errCode和errMsg,则继续保留,统一实现时增加UniError中定义的属性
- app端兼容处理
+ 已经实现的API如果不是通过回调返回错误,暂不调整,后续重新实现新API时按此规范处理
+ 已经实现的API如果是通过回调返回错误,则保留原有属性,后续按此规范补充errCode、errMsg、cause
+ 新开发的API,按此规范实现errCode、errMsg、cause
## 主题(模块)名称
|模块名称|描述|
|----|----|
| uni-runtime | SDK错误,如没有配置模块 |
| uni-secure-network | 安全网络 |
| uni-ad | uni-AD |
| uni-push | UniPush |
| uni-login | OAuth(登录鉴权) |
| uni-verify | 一键登录 |
**注意**
- 内置模块(不开源)
uni-前缀加模块名称
+ 模块名称由多个完整单词组成应该加-分割
- API模块(开源)
+ uni.XX API 时:uni-前缀加API名称,如uni.getSystemInfo(),errSubject名称uni-getSystemInfo
+ Object.XX API 时:uni-Object名称-前缀加API名称,如SocketTask.onMessage(),errSubject名称为uni-SocketTask-onMessage
- 公共模块或方法
封装API调用时需要重写errSubject
- 插件
使用插件id作为errSubject名称
对于API较多的插件建议使用插件id-API名称作为errSubject名称
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册