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

Update err-spec.md

上级 a9754a4e
## 规范
所有异步API,都应通过callback回调返回错误,在回调函数参数中包含错误信息,回调函数参数为JSON类型
## 错误信息规范
所有异步API,都应通过callback回调返回错误,在回调函数参数中包含错误信息,回调函数参数为UniError类型
完整定义如下:
完整错误类型定义如下:
```ts
//源错误信息
interface SourceError {
......@@ -32,35 +32,32 @@ function CallBack(err:UniError){
```
### SourceError
用于保存引起错误的源错误,如App端三方SDK的错误信息
- module
源错误(如App端三方SDK)模块名称,如uni-AD中的穿山甲广告SDK的模块名称为"csj"
用于保存引起错误的源错误,如app端三方SDK的错误信息,包括以下属性:
- subject
源错误(如app端三方SDK)模块名称,如uni-AD中的穿山甲广告SDK的模块名称为"csj"
- code
源错误(如App端三方SDK)的原始错误码
源错误(如app端三方SDK)的原始错误码
- message
源错误(如App端三方SDK)的原始错误描述信息
源错误(如app端三方SDK)的原始错误描述信息
- cause
上级源错误,只有一个源错误时是SourceError,包含多个源错误时封装成AggregateError
**注意**
源错误可以根据业务情况扩展其它属性,如uni-AD中,可以添加slotId来表示聚合的三方广告位标识
### AggregateError
用于保存多个源错误,如app端某个错误可能是由多个三方SDK的错误引起,这是会将多个源错误组成AggregateError对象。
包括以下属性:
- errors
数组,可包含SourceError或AggregateError对象
### UniError
Uni统一错误信息,用于统一各平台(端)错误信息
- errSubject
统一错误主题(模块)名称,字符串类型,存在多级模块时使用"::"分割,即"模块名称::二级模块名称"
统一错误主题(模块)名称,字符串类型,存在多级模块时使用"::"分割,即"模块名称::二级模块名称",详情参考[主题(模块)名称](#主题(模块)名称)
- errCode
统一错误码,数字类型
统一错误码,数字类型,通常0表示成功,其它为错误码
对于已经实现的API,继续保留现有errCode规范(保留向下兼容)
**新开发模块按以下规则**
错误码可以是正数,也可以是负数,推荐采用4或5位数字,模块内错误数字码唯一
数字范围划分:
+ 50000以下是端的错误码
+ 50000以上是云的错误码
errCode的错误数字码实现原则:
+ 微信小程序规范中有定义的按其规范进行统一
+ 微信小程序规范没有定义,由DCloud定义errCode发布到uni-app网站
+ 产生冲突时,以先定义发布的规范为准
- errMsg
统一错误描述信息,字符串类型,应准确描述引起的错误原因
- data
......@@ -68,8 +65,6 @@ Uni统一错误信息,用于统一各平台(端)错误信息
- cause
可选,源错误信息,可以包含多个错误,详见SourceError
### AggregateError
W3C规范:[](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError)
当源错误存在多个时,需要将SourceError封装到AggregateError对象中,按以下方式获取SourceError数组:
```ts
......@@ -79,19 +74,6 @@ function CallBack(err:UniError){
```
## 平台兼容原则
- 保留原平台(端)的错误回调函数参数的属性
+ 如app端原来错误信息的属性是code和message,则继续保留,统一实现时增加UniError中定义的属性
+ 如微信小程序端错误错误信息的属性是errCode和errMsg,则继续保留,统一实现时增加UniError中定义的属性
- app端兼容处理
+ 已经实现的API如果不是通过回调返回错误,暂不调整,后续重新实现新API时按此规范处理
+ 已经实现的API如果是通过回调返回错误,则保留原有属性,后续按此规范补充errCode、errMsg、cause
+ 新开发的API,按此规范实现errCode、errMsg、cause
## 主题(模块)名称
|模块名称|描述|
......@@ -104,17 +86,7 @@ function CallBack(err:UniError){
| uni-verify | 一键登录 |
**注意**
插件中返回错误时建议将“插件id”作为errSubject属性值,如果插件的API较多时可将每个API单独定义errSubject,建议使用errSubject属性值格式为“插件id-API名称”。
- 内置模块(不开源)
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.
先完成此消息的编辑!
想要评论请 注册