技术分享
SDK 错误码设计实践
00 分钟
2022-6-18
2025-1-16
type
status
date
slug
summary
tags
category
icon
password
在使用小程序 API 或组件时，可能会遇到异常（例如在 fail 回调或 Promise reject 中）。这些异常的 Error 对象除了包含 errMsg，还会带有通用错误码 errno。

代码示例

背景介绍

引入 errno 错误码的目的是为了解决以下问题：
  1. 部分 API 仅返回 errMsg，缺乏错误码。
  1. 有些 API 虽然有 errCode，但格式不统一。
  1. 不同 API 返回的 errCode 粒度不一致，信息不足。
  1. 相同错误在不同 API 中的 errCode 不一致，给开发者带来困扰。
因此，我们设计了一套统一规范的 errno 错误码，以帮助开发者更高效地调试和处理错误。

errno 错误码的优点

  • 统一的错误码格式。
  • 相同错误在不同 API 中对应相同的错误码。
  • 错误码包含 API 类别信息，便于快速定位问题。
  • 错误码粒度相对一致。
当 Error 对象中同时存在 errno 和 errCode 时，优先使用 errno。
未来，errno 错误码将逐步推广至所有 API 接口，取代现有的 errCode 参数。

错误码设计

errno 错误码由 7 位数字组成：

前两位：API 接口的一级类目

  • 00 - 通用错误码
  • 01 - 基础
  • 06 - 网络
  • 07 - 支付
  • 11 - 媒体
  • 13 - 文件
  • 14 - 开放接口
  • 15 - 设备
  • 20 - AI

第三、四位：API 接口的二级类目

例如，基础类目下的二级类目包括：
  • 00 - 通用基础错误
  • 03 - 更新
  • 09 - 加密

第五至七位：具体错误类型

例如，errno 为 1504003 时：
  • 15 表示设备类目
  • 04 表示 NFC
  • 003 表示具体错误类型

最佳实践

以 API 接口 openBluetoothAdapter 为例，蓝牙适配器不可用时，异常对象示例：
异常处理示例代码：

错误码列表

以下是 errno 值的一览表：
errno
errMsg
含义
0
ok
成功
1
cancel
撤销
3
system permission denied
系统权限未授予微信
4
internal error
小程序框架内部异常
5
time out
接口超时
...
...
...
上一篇
CSS 风格编写规范
下一篇
如何打造工程师文化？