竹简文档
响应处理

ErrorCode

ErrorCode 枚举定义 58 个预定义错误码,覆盖通用、客户端与服务端全场景

ErrorCode

ErrorCode 是筱工具(Java) 的错误码枚举类,位于 com.xlf.utility 包下。每个枚举值包含英文标识、5 位数字响应码与中文描述,用于标准化 API 响应状态。

枚举定义

ErrorCode.java
package com.xlf.utility;

public enum ErrorCode {
    NOT_EXIST("NotExist", 40000, "内容不存在"),
    EXISTED("Existed", 40001, "内容已存在"),
    PARAMETER_ERROR("ParameterError", 40002, "参数错误"),
    // ... 58 个预定义错误码

    private final String output;   // 英文标识
    private final Integer code;    // 5 位数字响应码
    private final String message;  // 中文描述
}

枚举字段

字段

类型

响应码规则

ErrorCode 的 5 位数字响应码遵循以下规则:

┌─────────────┬───────────────┐
│  前 3 位     │  后 2 位       │
│  HTTP 状态码  │  业务细分码    │
└─────────────┴───────────────┘

示例:40024 → HTTP 400 + 细分码 24
      50001 → HTTP 500 + 细分码 01

HTTP 状态码可通过 code / 100 计算得出。例如 40024 / 100 = 40050001 / 100 = 500

完整错误码列表

通用错误码(400xx)

枚举值outputcode说明
NOT_EXISTNotExist40000内容不存在
EXISTEDExisted40001内容已存在

400 请求错误

枚举值outputcode说明
BAD_REQUESTBadRequest40024错误请求
PARAMETER_ERRORParameterError40002参数错误
PARAMETER_MISSINGParameterMissing40003参数缺失
PARAMETER_INVALIDParameterInvalid40004参数无效
PARAMETER_ILLEGALParameterIllegal40005参数非法
PARAMETER_TYPE_ERRORParameterTypeError40006参数类型错误
BODY_ERRORBodyError40007请求体错误
BODY_MISSINGBodyMissing40008请求体缺失
BODY_INVALIDBodyInvalid40009请求体无效
BODY_ILLEGALBodyIllegal40010请求体非法
BODY_TYPE_ERRORBodyTypeError40011请求体类型错误
HEADER_ERRORHeaderError40012请求头错误
HEADER_MISSINGHeaderMissing40013请求头缺失
HEADER_INVALIDHeaderInvalid40014请求头无效
HEADER_ILLEGALHeaderIllegal40015请求头非法
HEADER_TYPE_ERRORHeaderTypeError40016请求头类型错误
OPERATION_ERROROperationError40017操作错误
OPERATION_FAILEDOperationFailed40018操作失败
OPERATION_INVALIDOperationInvalid40019操作无效
OPERATION_ILLEGALOperationIllegal40020操作非法
OPERATION_DENIEDOperationDenied40021操作被拒绝
OPERATION_NOT_ALLOWEDOperationNotAllowed40022操作不允许
OPERATION_NOT_SUPPORTEDOperationNotSupported40023操作不支持
OPERATION_TYPE_ERROROperationTypeError40025操作类型错误
EXPIREDExpired40026内容已过期
REQUEST_ERRORRequestError40027远程服务请求失败

401 未授权

枚举值outputcode说明
UNAUTHORIZEDUnauthorized40101未授权
LOGIN_FAILEDLoginFailed40102登录失败

403 禁止访问

枚举值outputcode说明
FORBIDDENForbidden40301禁止访问
PERMISSION_DENIEDPermissionDenied40302权限拒绝
ACCESS_LIMITEDAccessLimited40303访问受限

404 资源不存在

枚举值outputcode说明
PAGE_NOT_FOUNDPageNotFound40401页面未找到
NOT_FOUNDNotFound40402未找到
RESOURCE_NOT_FOUNDResourceNotFound40403资源未找到

405 方法不允许

枚举值outputcode说明
METHOD_NOT_ALLOWEDMethodNotAllowed40501方法不允许

406 不可接受

枚举值outputcode说明
NOT_ACCEPTABLENotAcceptable40601不可接受

408 请求超时

枚举值outputcode说明
TIMEOUTTimeout40801请求超时
CONNECTION_TIMEOUTConnectionTimeout40802连接超时
READ_TIMEOUTReadTimeout40803读取超时
WRITE_TIMEOUTWriteTimeout40804写入超时

429 请求过多

枚举值outputcode说明
TOO_MANY_REQUESTSTooManyRequests42901请求过多
REQUEST_RATE_TOO_HIGHRequestRateTooHigh42902请求频率过高

500 服务端错误

枚举值outputcode说明
SERVER_INTERNAL_ERRORServerInternalError50001服务器内部错误
DATABASE_ERRORDatabaseError50002数据库错误
CACHE_ERRORCacheError50003缓存错误
FILE_ERRORFileError50004文件错误
STORAGE_ERRORStorageError50005存储错误
REMOTE_CALL_ERRORRemoteCallError50006远程调用错误
CONFIGURATION_ERRORConfigurationError50007配置错误
RESOURCE_EXHAUSTEDResourceExhausted50008资源耗尽
NETWORK_ERRORNetworkError50009网络错误
NETWORK_NOT_SUCCESSNetworkNotSuccess50010网络请求不成功

502/503 网关与服务错误

枚举值outputcode说明
GATEWAY_ERRORGatewayError50201网关错误
SERVICE_UNAVAILABLEServiceUnavailable50301服务不可用
SYSTEM_MAINTENANCESystemMaintenance50302系统维护

特殊错误码

枚举值outputcode说明
UNKNOWN_ERRORUnknownError50999未知错误

使用方式

组合 BaseResponse

Example.java
import com.xlf.utility.BaseResponse;
import com.xlf.utility.ErrorCode;

// 使用 ErrorCode 字段构造标准错误响应
BaseResponse<Void> response = new BaseResponse<>(null, ErrorCode.PARAMETER_ERROR.getOutput(),
    ErrorCode.PARAMETER_ERROR.getCode(), ErrorCode.PARAMETER_ERROR.getMessage(), "用户名不能为空", null, null);

抛出业务异常

UserService.java
import com.xlf.utility.ErrorCode;
import com.xlf.utility.exception.library.BusinessException;

public UserDTO getUserById(Long id) {
    if (id == null) {
        // 抛出携带 ErrorCode 的业务异常,由全局异常处理器统一捕获
        throw new BusinessException("用户 ID 不能为空", ErrorCode.PARAMETER_MISSING);
    }
    // ...
}

条件判断

AuthService.java
public void validateToken(String token) {
    if (token == null || token.isEmpty()) {
        throw new BusinessException("令牌不能为空", ErrorCode.UNAUTHORIZED);
    }
    if (isTokenExpired(token)) {
        // 根据具体场景选择最精确的错误码
        throw new BusinessException("令牌已过期,请重新登录", ErrorCode.EXPIRED);
    }
}

下一步

On this page