From 01d9c848461b08d575190ed85f73b0854f38b3ef Mon Sep 17 00:00:00 2001
From: DCloud-yyl <yanyilin@dcloud.io>
Date: Fri, 11 Nov 2022 16:40:57 +0800
Subject: [PATCH] Update err-spec.md

---
 docs/tutorial/err-spec.md | 119 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)

diff --git a/docs/tutorial/err-spec.md b/docs/tutorial/err-spec.md
index 8b1378917..2047304f6 100644
--- a/docs/tutorial/err-spec.md
+++ b/docs/tutorial/err-spec.md
@@ -1 +1,120 @@
+## 规范  
+所有异步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名称  
+
 
-- 
GitLab