Nacos HTTP API 响应与错误规范Result 包装、异常映射与 ExceptionHandler 收敛指南【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos本文档面向 Nacos 服务端开发者与 API 集成方系统讲解 Nacos v3 HTTP API 的响应契约统一 JSON 包装结构、有意的响应形态例外、NacosApiExceptionHandler的异常到 HTTP 状态与业务错误码的映射规则以及NacosApiNacosApiExceptionHandler收敛策略。读完本文你将掌握如何让 v3 API 返回结构一致、错误码可预期的响应并理解 Config、Naming 等模块当前待收敛的历史遗留问题。本文是 HTTP API 规范 中响应契约的细化鉴权相关失败由 HTTP 鉴权规范 定义当前端点覆盖范围记录在 V3 API 范围 中。1. JSON 响应包装ResultT 统一信封Nacos v3 JSON 响应默认使用com.alibaba.nacos.api.model.v2.ResultT作为统一响应信封序列化后的结构固定为三个字段{ code: 0, message: success, data: {} }各字段语义如下字段类型说明codeInteger业务错误码0表示成功非 0 表示具体错误类别详见第 3 节与 ErrorCode 枚举messageString面向调用方的人类可读提示成功时为successdataT泛型业务数据负载成功时承载实际返回对象在源码层面ResultT位于 api/src/main/java/com/alibaba/nacos/api/model/v2/Result.java是一个实现了Serializable的不可变风格容器code/message/data均为 final 字段并提供了丰富的静态工厂方法Result.success()/Result.success(T data)成功响应默认 code 为ErrorCode.SUCCESS.getCode()即0message 为successResult.failure(String message)失败响应code 固定为ErrorCode.SERVER_ERROR.getCode()即30000Result.failure(ErrorCode errorCode)/Result.failure(ErrorCode errorCode, T data)按枚举错误码构造失败响应Result.failure(Integer code, String msg, T data)完全自定义的失败响应。端点在编写文档时必须明确说明data的具体类型以及任何非默认的 HTTP 状态码确保调用方无需猜测响应结构。2. 响应形态例外有意保留的非常规响应并非所有端点都遵循ResultT信封当前规范明确列出以下有意设计的响应形态例外集成方在对接这些端点时需要特殊处理文件下载端点可以返回ResponseEntitybyte[]直接以二进制流下发文件内容而非 JSON 信封Copilot 流式端点返回 Server-Sent EventsSSE以text/event-stream方式逐条推送增量数据健康检查 readiness在服务尚未就绪时可以返回 HTTP 500并携带ResultString响应体注意此时是String类型的 data而非空对象默认鉴权Default Authv1 与 v3 登录登录成功时返回遗留的平铺 token 对象即直接把 token 字段平铺在响应顶层而非包在Result.data内凭据错误时返回 HTTP 403 和通用纯文本响应体遗留或运维端点部分旧端点可以返回纯文本但只有在确认属于兼容行为时才应保留新代码不应再引入纯文本响应。这些例外属于兼容性约束下的存量行为并非新 API 的设计模板。开发者新增端点时默认仍应使用ResultT信封。3. 错误处理NacosApiExceptionHandler 的统一映射标注了NacosApi注解的 Controller该注解定义于 api/src/main/java/com/alibaba/nacos/api/annotation/NacosApi.java作用于类级别、运行时保留用于标记 Nacos API v2 Controller其抛出的异常统一由NacosApiExceptionHandler处理。该 Handler 位于 core/src/main/java/com/alibaba/nacos/core/exception/NacosApiExceptionHandler.java通过ControllerAdvice(annotations {NacosApi.class})精确绑定到 v3 API 控制器并带有Order(-1)保证优先级。3.1 异常类型 → HTTP 状态 → Result code 映射表异常类型HTTP 状态Result code 来源NacosApiException异常错误码由异常的 statusCode 决定详细 API 错误码detailErrCodeNacosException异常错误码SERVER_ERROR缺少请求参数400PARAMETER_MISSING非法参数或数字格式错误400PARAMETER_VALIDATE_ERRORMedia type 错误400MEDIA_TYPE_ERRORAccessException403ACCESS_DENIED数据访问、Servlet 或 IO 失败500DATA_ACCESS_ERROR未处理异常500通用失败3.2 源码级映射实现剖析对照 NacosApiExceptionHandler.java 的实现可进一步看到每个分支的细节NacosApiExceptionhandleNacosApiException返回ResponseEntityResultStringHTTP 状态取自异常的getErrCode()即业务代码显式声明的 HTTP 状态码响应体为new Result(e.getDetailErrCode(), e.getErrAbstract(), e.getErrMsg())。NacosApiException定义于 api/src/main/java/com/alibaba/nacos/api/exception/api/NacosApiException.java在NacosException基础上额外携带两个 v2 API 字段detailErrCodev2 业务错误码与errAbstractv2 摘要错误描述其构造方法通常以(statusCode, ErrorCode, message)形式传入由ErrorCode.getCode()/getMsg()自动填充NacosException/NacosRuntimeException同样按异常自身错误码设置 HTTP 状态但 Result code 统一收敛为SERVER_ERRORmessage 取异常的原始消息400 系列HttpMessageNotReadableException请求体不可读→PARAMETER_MISSINGHttpMessageConversionException、NumberFormatException、IllegalArgumentException参数非法或数字格式错误→PARAMETER_VALIDATE_ERRORMissingServletRequestParameterException缺少请求参数→PARAMETER_MISSINGHttpMediaTypeExceptionContent-Type 错误→MEDIA_TYPE_ERROR。这些分支均通过ResponseStatus(HttpStatus.BAD_REQUEST)固定返回 HTTP 400AccessException返回 HTTP 403Result code 为ACCESS_DENIED数据访问/Servlet/IO 失败DataAccessException、ServletException、IOException合并处理返回 HTTP 500 与DATA_ACCESS_ERROR兜底其余未处理异常统一返回 HTTP 500code 为SERVER_ERROR即Result.failure(e.getMessage())的默认行为。3.3 ErrorCode 枚举业务错误码的取值空间Result code 的实际取值来自com.alibaba.nacos.api.model.v2.ErrorCode枚举api/src/main/java/com/alibaba/nacos/api/model/v2/ErrorCode.java其取值空间按功能域分段组织方便调用方按码段快速定位问题类别码段含义典型错误码示例0成功SUCCESS(0)10000 ~ 10002通用错误PARAMETER_MISSING(10000)、ACCESS_DENIED(10001)、DATA_ACCESS_ERROR(10002)20001 ~ 20013参数与资源校验TENANT_PARAM_ERROR(20001)、PARAMETER_VALIDATE_ERROR(20002)、MEDIA_TYPE_ERROR(20003)、RESOURCE_NOT_FOUND(20004)、RESOURCE_CONFLICT(20005)、CONFIG_LISTENER_IS_NULL(20006)、CONFIG_LISTENER_ERROR(20007)、INVALID_DATA_ID(20008)、PARAMETER_MISMATCH(20009)及灰度相关 20010~200135031 ~ 5034容量配额OVER_CLUSTER_QUOTA(5031)、OVER_GROUP_QUOTA(5032)、OVER_TENANT_QUOTA(5033)、OVER_MAX_SIZE(5034)21000 ~ 21011Naming 服务域SERVICE_NAME_ERROR(21000)、WEIGHT_ERROR(21001)、INSTANCE_NOT_FOUND(21003)、SERVICE_ALREADY_EXIST(21007)、SERVICE_NOT_EXIST(21008)等22000 ~ 22002命名空间域ILLEGAL_NAMESPACE(22000)、NAMESPACE_NOT_EXIST(22001)、NAMESPACE_ALREADY_EXIST(22002)23000 ~ 23002集群节点域ILLEGAL_STATE(23000)、NODE_INFO_ERROR(23001)、NODE_DOWN_FAILURE(23002)30000服务器内部错误SERVER_ERROR(30000)40000 ~ 40001API 生命周期API_DEPRECATED(40000)、API_FUNCTION_DISABLED(40001)50000 ~ 50404MCP / Agent 域MCP_SERVER_NOT_FOUND(50000)、AGENT_NOT_FOUND(50100)、HTTP_CLIENT_NOT_FOUND(50404)等100002 ~ 100006配置导入域METADATA_ILLEGAL(100002)、DATA_VALIDATION_FAILED(100003)等50310 ~ 50311模糊监听限制FUZZY_WATCH_PATTERN_OVER_LIMIT(50310)等3.4 废弃 v3 API 的兼容门禁HTTP 410 Gone接入共享兼容门禁的废弃 v3 API在配置nacos.core.api.compatibility.enabledfalse默认值时会返回HTTP 410 Gone响应中的 Result code 为API_DEPRECATED40000。该行为由 core/src/main/java/com/alibaba/nacos/core/controller/compatibility/CompatibilityHelper.java 实现check(String alternatives)方法通过EnvUtil.getProperty(nacos.core.api.compatibility.enabled, Boolean.class, false)读取开关默认关闭当开关为 false 时抛出NacosApiException其 HTTP 状态为HttpStatus.GONE.value()410错误码为ErrorCode.API_DEPRECATEDmessage 提示调用方改用替代 API或迁移期间在application.properties中设置nacos.core.api.compatibility.enabledtrue。该配置项同样存在于 distribution/conf/application.properties 中运维可通过修改配置文件控制废弃接口的可用性。4. ExceptionHandler 收敛统一 v3 API 的异常处理边界4.1 收敛原则Nacos 自有的 v3 HTTP API 应统一收敛到NacosApiNacosApiExceptionHandler组合以获得一致的异常处理与响应形态。对于早于 v3 API 模型就已存在的模块级 ExceptionHandler不应为 v3 API 定义不同的响应形态——也就是说v3 端点不能因为历史 Handler 的存在而返回不同于ResultT的错误结构。4.2 插件式模块的例外插件性质的模块如果有意维护独立的 API 面可以保留自己的 ExceptionHandler。通用扩展边界由 Nacos 插件化规范 定义。PrometheusApiExceptionHandler就是这类插件式 ExceptionHandler 的典型例子其存在不破坏整体收敛原则因为插件拥有独立的 API 契约。4.3 已知待处理项Convergence Items当前仓库中存在以下已知的收敛遗留问题这些项应作为待处理事项逐步迁移使 Config 和 Naming 的 v3 API 使用与其他 Nacos v3 API 一致的ResultT错误契约config/server/exception/GlobalExceptionHandler仍作用于com.alibaba.nacos.config.server包并可能返回纯文本ResponseEntityString与ResultT契约不一致naming/exception/ResponseExceptionHandler仍作用于com.alibaba.nacos.naming包同样可能返回纯文本ResponseEntityStringConfigOpenApiController引入了NacosApiimport 了相关类但当前没有标注NacosApi注解因此尚未接入NacosApiExceptionHandler的统一处理。对于新编写的 v3 API规范要求直接采用NacosApiNacosApiExceptionHandler避免产生新的不一致响应形态。5. 实践建议与集成要点判断端点响应形态调用 v3 API 时先查看端点文档声明的data类型与 HTTP 状态若端点属于第 2 节的例外清单文件下载、SSE、登录、readiness按对应形态解析否则统一按ResultT解析。错误码处理以code字段作为业务判定依据先判断code 0再取data非 0 时结合第 3.3 节的码段表定位错误域message仅作展示参考。服务端开发新 v3 Controller 必须标注NacosApi业务异常优先抛出NacosApiException以同时携带精确的 HTTP 状态、v2 业务错误码与摘要描述。迁移存量模块参考第 4.3 节清单逐步将 Config、Naming 的 v3 端点迁移到NacosApi体系消除纯文本错误响应。兼容性开关迁移期间如依赖废弃 v3 API可在application.properties中设置nacos.core.api.compatibility.enabledtrue临时启用避免 410 Gone长期应切换到替代 API。相关规范文档可继续参阅 HTTP API 规范、HTTP 鉴权规范 与 V3 API 范围异常处理实现细节可阅读 NacosApiExceptionHandler.java 及其单元测试 NacosApiExceptionHandlerTest.java。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考