# uni错误规范

# background

Most of the error messages of the MiniApp platform are returned in the format of errCode and errMsg. However, different MiniApp platforms may return different errCode.

In actual development, the uni-app engine, third-party plug-ins, and the developer's own business code will all return errors, but errCode may also conflict with each other.

In unified error interception and uni statistics, confusing errCode will cause many problems.

Many errors are caused by lower-level errors, but only the outermost errors are exposed, which is difficult to troubleshoot, and lower-level errors need to be exposed.

In order to further standardize the error message format, uni-app defines a more complete error specification:

Added errSubject, which is used to distinguish between different platforms or different modules with the same errCode
Added cause, which is used to feed back the source of the error. For example, on the app platform, when the uni.login API returns an error, it may be that the underlying third-party social login sdk reported an error, and the error of the third-party sdk will be added to the cause.

From 2022-11-11, all new APIs added by DCloud will use this set of uni error specifications. At the same time, we recommend that all plugin authors also use this specification and declare their own plugin id in errSubject.

# define

All asynchronous APIs should return errors through the callback callback, and the error information should be included in the callback function parameters, and the callback function parameters should be of type UniError

完整错误类型定义如下：

// source error message
interface SourceError {
    message: string,
    subject?: string,
    code?: number,
    cause?: SourceError | UniAggregateError
}

//Uni聚合源错误信息
interface UniAggregateError extends SourceError {
	errors: Array<SourceError|UniAggregateError>
}

//uni error message
interface UniError {
	errSubject: string,
	errCode: number,
	errMsg: string,
	data?: Object,
	cause?: SourceError | UniAggregateError
}

//Callback
function CallBack(err:UniError){
	//console.log(JSON.stringify(res));
}

# SourceError

用于保存引起错误的源错误，如app端三方SDK的错误信息，包括以下属性：

subject 源错误（如app端三方SDK）模块名称，如uni-ad中的穿山甲广告SDK的模块名称为"csj"
code 源错误（如app端三方SDK）的原始错误码
message 源错误（如app端三方SDK）的原始错误描述信息
cause 上级源错误，只有一个源错误时是SourceError，包含多个源错误时封装成AggregateError

注意源错误可以根据业务情况扩展其它属性，如uni-ad中，可以添加slotId来表示聚合的三方广告位标识

# UniAggregateError

用于保存多个源错误，如app端某个错误可能是由多个三方SDK的错误引起，可将多个源错误组成UniAggregateError对象。包括以下属性：

errors 数组，可包含SourceError或UniAggregateError对象

# UniError

Uni统一错误信息，用于统一各平台（端）错误信息

errSubject 统一错误主题（模块）名称，字符串类型，存在多级模块时使用"::"分割，即"模块名称::二级模块名称"，参考errSubject（模块/主题）名称
errCode 统一错误码，数字类型，通常0表示成功，其它为错误码。
对于已经实现的API，继续保留现有errCode规范（保留向下兼容）。
错误码长度及规范参考微信小程序的Errno错误码，使用 7 位数错误码，第 1 - 2 位标识 API 接口的一级类目，第 3 - 4 位标识 API 接口的二级类目，第 5 - 7 位表示具体的错误类型。
其他平台，与微信小程序相同的错误，错误码应尽量保持一致。
定义平台专有错误码时，为了避免冲突，错误码的第 5 - 7 位按以下规则：
- 跨端（App/Web）：使用6xx
- App-Android端：使用7xx
- App-iOS端：使用8xx
- Web端：使用9xx
- harmony next端：使用5xx
errMsg 统一错误描述信息，字符串类型，应准确描述引起的错误原因
data 可选，错误时返回的数据，比如获取设备信息时，如部分数据获取成功，部分数据获取失败，此时触发错误回调，需将获取成功的数据放到data属性中
cause 可选，源错误信息，可以包含多个错误，详见SourceError

When there are multiple source errors, SourceError needs to be encapsulated into an AggregateError object, and the SourceError array can be obtained as follows:

function CallBack(err:UniError){
	var cerrs:SourceError[] = err.cause.errors;
}

# errSubject（模块/主题）名称

The errSubject attribute value indicates the name of the calling module that returned the error.

Module Name	Description
uni-runtime	App side SDK runtime environment error
uni-ad	uni-ad
uni-push	UniPush
uni-login	OAuth (login authentication)
uni-verify	One-key login

注意

The errSubject attribute value of the uni built-in module is "uni-module English name". If the English name consists of multiple words, the word key should be separated by -
uni API的errSubject属性值
- uni.XXX API时 errSubject属性值为“uni-API名称”，如uni.getSystemInfo()，错误回调中errSubject属性值为“uni-getSystemInfo”
- Object.XX API时 errSubject属性值为“uni-Object名称-API名称”，如SocketTask.onMessage()，错误回调中errSubject属性值为“uni-SocketTask-onMessage”
uni插件中返回错误时建议将“插件id”作为errSubject属性值，如果插件的API较多时可将每个API单独定义errSubject，建议使用errSubject属性值格式为“插件id-API名称”。

# uts插件或uvue页面中使用UniError

在uni-app、uni-app x中的错误信息建议统一使用UniError对象，以便在发生错误时统一捕获处理，特别是以下情况：

在uts插件中封装API给uni-app使用时，返回的错误信息要求使用UniError对象。
在uni-app x项目的uvue页面中，抛出错误要求使用UniError对象。

在App端，UniError和SourceError都是从uts的Error继承。

# 构造UniError对象

UniError对象必须通过 new 操作符构造

语法

new UniError()
new UniError(errSubject:string, errCode:number, errMsg:string)

参数

errSubject 统一错误主题（模块）名称，字符串类型，存在多级模块时使用"::"分割，即"模块名称::二级模块名称"，参考errSubject（模块/主题）名称
errCode 统一错误码，数字类型，通常0表示成功，其它为错误码
errMsg 统一错误描述信息，字符串类型，应准确描述引起的错误原因

示例

//创建一个UniError
let error = new UniError("uni-apidName", 60000, "Custom uni error");
//设置data数据（可选）
error.data = {
	"dataName": "custom data value"
};

# 构造SourceError对象

当错误信息是有三方SDK或其它模块引起时，可以将三方SDK或其它模块的错误信息封装在SourceError中作为UniError的源错误

语法

new SourceError()
new SourceError(message:string)

参数

message 源错误描述信息，字符串类型

示例

//创建一个SourceError
let sourceError = new SourceError("Third SDK error message");
//创建一个UniError
let error = new UniError("uni-apidName", 60000, "Custom uni error");
//设置源错误
error.cause = sourceError;

# 构造UniAggregateError对象

当错误是由多个SourceError源错误引起时，可以将多个源错误放到一个UniAggregateError对象中

语法

new UniAggregateError(errors:Array<SourceError>)

参数

errors 源错误数组，Array类型

示例

//创建UniAggregateError
let aggregateError = new UniAggregateError([new SourceError("First 3rd SDK error message"), new SourceError("Second 3rd SDK error message")]);
//创建一个UniError
let error = new UniError("uni-apidName", 60000, "Custom uni error");
//设置源错误
error.cause = aggregateError;