bandeng-code

一个高性能的错误码库，支持自动容错处理，适用于 Node.js 项目。

特性

• ✅ 高性能：高频错误码（如 2000）使用直接属性访问，接近原生性能
• ✅ 自动容错：访问不存在的错误码时，自动返回 2999（未知错误）
• ✅ API 友好：支持 code[2000] 的对象访问方式，无需修改现有代码
• ✅ 类型灵活：支持数字和字符串键访问，code[2000] 和 code['2000'] 都可以
• ✅ 性能优化：使用 Proxy 和直接属性混合方案，兼顾性能和容错

安装

npm install bandeng-code

使用方法

基本用法

const code = require('bandeng-code')

// 访问存在的错误码
code[2000] // { code: 2000, msg: "请求成功" }
code['2000'] // { code: 2000, msg: "请求成功" }

// 访问不存在的错误码（自动返回 2999）
code[9999] // { code: 2999, msg: "未知错误" }

// 在 Express 中使用
const express = require('express')
const app = express()

app.get('/api/user', (req, res) => {
    // 成功响应
    return res.json({...code[2000], data: userData})
})

app.post('/api/user', (req, res) => {
    if (!req.body.name) {
        // 参数缺失
        return res.json({...code[3001], data: null})
    }
    // ...
})

// 在 Koa 中使用
const Koa = require('koa')
const Router = require('@koa/router')
const app = new Koa()
const router = new Router()

router.get('/api/user', async ctx => {
    // 成功响应
    ctx.body = {...code[2000], data: userData}
})

router.post('/api/user', async ctx => {
    if (!ctx.request.body.name) {
        // 参数缺失
        ctx.body = {...code[3001], data: null}
        return
    }
    // ...
})

app.use(router.routes())

展开语法

const code = require('bandeng-code')

// 使用展开语法，方便添加额外数据
res.json({
    ...code[2000],
    data: result,
    timestamp: Date.now()
})

// 结果：
// {
//     code: 2000,
//     msg: "请求成功",
//     data: result,
//     timestamp: 1234567890
// }

容错处理

const code = require('bandeng-code')

// 不存在的错误码自动返回 2999
const errorCode = someDynamicCode // 可能是任何值
const result = code[errorCode] // 如果不存在，自动返回 2999

// 无需手动判断
// ❌ 不需要这样：const result = code[errorCode] || code[2999];
// ✅ 直接使用：const result = code[errorCode];

错误码分类

2xxx - 请求相关错误码

• 2000: 请求成功
• 2001: 接口请求超时
• 2002: 接口禁止访问
• 2999: 未知错误（默认错误码）

3xxx - 参数相关错误码

• 3001: 参数缺失
• 3002: 参数为空
• 3003: 参数无效
• 3004: 参数错误

4xxx - 数据相关错误码

• 4000: 数据请求失败
• 4001: 数据不存在
• 4002: 数据已存在

5xxx - 文件/目录相关错误码

• 5001: 目录不存在
• 5007: 文件不存在

6xxx - 用户/权限相关错误码

• 6001: 用户不存在
• 6003: 用户名或密码错误
• 6014: 没有访问权限

更多错误码...

查看 code.json 文件获取完整的错误码列表。

性能优化

高频错误码优化

库内部对高频错误码（如 2000）进行了性能优化，使用直接属性访问，避免 Proxy 开销：

// 高频错误码（2000）使用直接属性，性能接近原生对象访问
code[2000] // 零 Proxy 开销

// 其他错误码通过 Proxy 访问，保持容错能力
code[4001] // 有 Proxy 开销，但可接受

性能对比

• 高频错误码（2000）：接近原生对象访问性能
• 其他错误码：约 10 倍性能开销（但单次访问是微秒级，可忽略）
• 真实场景（80% 2000）：整体性能提升约 70%

API 参考

code[number] 或 code[string]

获取错误码对象。

参数：

• number 或 string: 错误码（如 2000 或 '2000'）

返回：

• Object: 错误码对象 { code: number, msg: string }
• 如果错误码不存在，返回 { code: 2999, msg: "未知错误" }

示例：

code[2000] // { code: 2000, msg: "请求成功" }
code['2000'] // { code: 2000, msg: "请求成功" }
code[9999] // { code: 2999, msg: "未知错误" }

技术实现

Proxy 容错机制

库使用 Proxy 拦截属性访问，实现自动容错：

// 当访问不存在的错误码时
code[9999] // Proxy 拦截，自动返回 2999

混合性能优化

• 高频错误码：直接属性，零开销
• 其他错误码：Proxy 访问，保持容错

常见问题

Q: 为什么使用 Proxy？

A: Proxy 可以实现自动容错处理。当访问不存在的错误码时，自动返回 2999，避免返回 undefined 导致的运行时错误。

Q: 性能影响大吗？

A: 对于错误码库场景，性能影响可忽略：

• 单次访问差异：约 0.25 微秒
• 高频错误码（2000）已优化为直接属性，接近原生性能
• 相比网络请求（毫秒级），Proxy 开销可忽略

许可证

ISC

作者

lizhi

更新日志

1.0.3

改进 IDE 支持：添加了 JSDoc 注释，提升开发体验（VSCODE已验证）。 按住CTRL键并鼠标悬停在code码数字部分时, 将显示该code码的定义。