Java前后端阿里云HTTP请求核心规范_Java

一、阿里云 http 规范（补充代码示例 + 状态码场景区分）

1. 核心代码示例（java 后端 + 前端）

（1）统一响应体（resultdto）- 单 / 微服务通用

@data
public class resultdto<t> {
    // 业务状态码（映射http状态码，微服务网关层需对齐）
    private integer code;
    private string msg;
    private t data;

    // 成功响应
    public static <t> resultdto<t> success(t data) {
        resultdto<t> result = new resultdto<>();
        result.setcode(200);
        result.setmsg("操作成功");
        result.setdata(data);
        return result;
    }

    // 失败响应（对接http状态码）
    public static resultdto<void> fail(integer code, string msg) {
        resultdto<void> result = new resultdto<>();
        result.setcode(code);
        result.setmsg(msg);
        return result;
    }

    // 快捷方法（对齐阿里云状态码）
    public static resultdto<void> unauthorized() {
        return fail(401, "登录失效，请重新登录");
    }

    public static resultdto<void> forbidden() {
        return fail(403, "无操作权限");
    }

    public static resultdto<void> notfound() {
        return fail(404, "资源不存在");
    }

    public static resultdto<void> servererror() {
        return fail(500, "服务器内部错误");
    }
}

（2）全局异常处理器 - 单 / 微服务通用

@restcontrolleradvice
@slf4j
public class globalexceptionhandler {
    // 参数校验失败（400）
    @exceptionhandler(methodargumentnotvalidexception.class)
    public resultdto&lt;void&gt; handlevalidexception(methodargumentnotvalidexception e) {
        string msg = e.getbindingresult().getfielderror().getdefaultmessage();
        log.warn("参数校验失败：{}", msg);
        return resultdto.fail(400, msg);
    }

    // 自定义业务异常（映射401/403/404等）
    @exceptionhandler(businessexception.class)
    public resultdto&lt;void&gt; handlebusinessexception(businessexception e) {
        log.warn("业务异常：{}", e.getmessage());
        return resultdto.fail(e.getcode(), e.getmessage());
    }

    // 服务端未知异常（500）
    @exceptionhandler(exception.class)
    public resultdto&lt;void&gt; handleexception(exception e) {
        log.error("服务器异常", e);
        return resultdto.servererror();
    }
}

（3）前端 axios 统一拦截器（单 / 微服务通用）

// axios实例配置
const service = axios.create({
  baseurl: process.env.vue_app_base_api,
  timeout: 30000,
  headers: {
    'content-type': 'application/json;charset=utf-8'
  }
});

// 请求拦截器（添加token，对齐阿里云规范）
service.interceptors.request.use(
  config =&gt; {
    // token统一放authorization请求头
    const token = localstorage.getitem('token');
    if (token) {
      config.headers['authorization'] = `bearer ${token}`;
    }
    return config;
  },
  error =&gt; promise.reject(error)
);

// 响应拦截器（统一处理状态码）
service.interceptors.response.use(
  response =&gt; {
    const res = response.data;
    // 业务状态码处理（单服务/微服务核心）
    if (res.code !== 200) {
      // 401：未登录（单/微服务通用）
      if (res.code === 401) {
        elmessage.error('登录失效，请重新登录');
        localstorage.removeitem('token');
        window.location.href = '/login';
      }
      // 403：无权限（单/微服务通用）
      else if (res.code === 403) {
        elmessage.error('无操作权限');
      }
      // 404：资源不存在（单/微服务通用）
      else if (res.code === 404) {
        elmessage.error('资源不存在');
      }
      // 500：服务异常（单/微服务通用）
      else if (res.code === 500) {
        elmessage.error('服务器内部错误，请稍后重试');
      }
      // 微服务新增状态码（502/503/504）
      else if ([502, 503, 504].includes(res.code)) {
        elmessage.error('服务暂不可用，请稍后重试');
      }
      return promise.reject(res);
    }
    return res;
  },
  error =&gt; {
    // http状态码直接处理（微服务网关层返回）
    const status = error.response?.status;
    if (status === 429) {
      elmessage.error('请求频繁，请稍后重试');
    } else if (status === 408) {
      elmessage.error('请求超时，请重试');
    } else {
      elmessage.error('请求失败，请稍后重试');
    }
    return promise.reject(error);
  }
);

export default service;

（4）微服务网关过滤器（新增状态码处理）

@component
@slf4j
public class gatewayexceptionfilter implements globalerrorwebexceptionhandler {
    @override
    public mono&lt;void&gt; handle(serverwebexchange exchange, throwable ex) {
        serverhttpresponse response = exchange.getresponse();
        response.getheaders().setcontenttype(mediatype.application_json);
        resultdto&lt;void&gt; result = new resultdto&lt;&gt;();

        // 微服务新增状态码处理
        if (ex instanceof notfoundexception) {
            // 502：网关转发失败（服务不可达）
            result.setcode(502);
            result.setmsg("服务暂不可用");
        } else if (ex instanceof timeoutexception) {
            // 504：网关超时
            result.setcode(504);
            result.setmsg("网关请求超时");
        } else if (ex instanceof serviceunavailableexception) {
            // 503：服务下线/维护
            result.setcode(503);
            result.setmsg("服务维护中，请稍后重试");
        } else {
            // 500：网关内部异常
            result.setcode(500);
            result.setmsg("网关异常");
        }

        return response.writewith(mono.just(response.bufferfactory().wrap(json.tojsonbytes(result))));
    }
}

2. 单服务 vs 微服务 http 状态码使用差异表

状态码	官方含义	单服务使用场景（核心）	微服务新增使用场景（叠加单服务）	落地说明
200	ok	所有业务成功（查询 / 新增 / 修改 / 删除）	同单服务 + 微服务间调用成功	单 / 微服务核心，业务层优先返回
400	bad request	参数校验失败、get 传敏感数据	同单服务 + 网关参数校验失败	单 / 微服务通用
401	unauthorized	未登录、token 过期	同单服务 + 网关 token 校验失败	单 / 微服务通用
402	payment required	付费权限不足	同单服务 + 微服务多租户付费校验	单 / 微服务通用（仅付费场景）
403	forbidden	无操作权限	同单服务 + 微服务服务间调用权限不足	单 / 微服务通用
404	not found	资源不存在、接口不存在	同单服务 + 网关路由不存在、服务实例不存在	单 / 微服务通用
405	method not allowed	http 方法不允许	同单服务 + 网关层方法校验失败	单 / 微服务通用
408	request timeout	请求超时	同单服务 + 微服务服务间调用超时	单 / 微服务通用
413	payload too large	请求体过大	同单服务 + 网关层请求体校验	单 / 微服务通用
429	too many requests	接口限流（单服务本地限流）	同单服务 + 网关层全局限流、服务集群限流	微服务新增网关层使用场景
500	internal server error	服务端未知异常	同单服务 + 微服务单个业务服务异常	单 / 微服务通用
502	bad gateway	❌ 单服务不使用	网关转发请求失败（如服务实例崩溃）	微服务网关层专属
503	service unavailable	❌ 单服务不使用	服务下线、注册中心无可用实例、服务维护	微服务网关层专属
504	gateway timeout	❌ 单服务不使用	网关转发请求超时（如服务响应慢）	微服务网关层专属
其他	-	仅使用上述状态码，禁止自定义 http 状态码	仅使用上述状态码，新增状态码仅网关层使用	阿里云规范：状态码需标准化

3. 核心补充说明

（1）单服务 http 状态码使用范围

仅使用：200/400/401/402/403/404/405/408/413/429/500；
核心规则：所有业务异常通过resultdto的code字段映射（http 状态码仍为 200），仅框架层（如参数错误、请求方法错误）直接返回 4xx/5xx。

（2）微服务新增状态码核心场景

新增状态码	微服务专属场景	处理层	前端提示
502	网关转发到业务服务失败	网关层（gateway）	“服务暂不可用，请稍后重试”
503	业务服务下线 / 无可用实例	网关层 + 注册中心	“服务维护中，预计 xx 时间恢复”
504	网关等待业务服务响应超时	网关层	“请求超时，请检查服务是否正常”

（3）微服务状态码落地规则

业务服务：仅返回单服务的状态码（200/400/401 等），不处理 502/503/504；
网关层：
- 接收业务服务的响应，透传 200/400 等状态码；
- 自身处理转发失败 / 超时 / 服务下线，返回 502/503/504；
前端：
- 先判断网关返回的 http 状态码（如 502→通用提示）；
- 再判断业务响应体的code（如 401→跳转登录）。

二、总结

1. 代码核心

单 / 微服务统一用resultdto封装响应，对齐阿里云状态码；
全局异常处理器捕获所有异常，标准化返回；
微服务新增网关层过滤器，处理 502/503/504 等专属状态码。

2. 状态码核心差异

维度	单服务	微服务（叠加单服务）
使用范围	200/400/401/403/404/500 等基础码	基础码 + 网关层专属 502/503/504
处理层	业务服务自身	业务服务处理基础码，网关层处理新增码
核心规则	业务异常用 200 + 自定义 code	网关层返回 4xx/5xx，业务层仍用 200 + 自定义 code