无Spring依赖的Java Azure Function如何返回人类可读错误响应

核心设计原则 #

• 状态码严格遵循HTTP标准语义，避免全错误场景统一返回500的粗放设计
• 响应结构保持前后一致，降低客户端解析成本
• 错误信息分层：对外返回用户可理解的提示，附带可关联日志的排查标识（日志落App Insights的逻辑不在本次讨论范围）
• 所有错误返回走统一构造逻辑，避免业务代码零散拼接响应

状态码映射规则（覆盖绝大多数业务场景） #

• 400 Bad Request：请求格式错误、参数校验不通过，比如JSON反序列化失败、必填字段缺失、字段类型不匹配
• 401 Unauthorized：鉴权失败，比如Function Key缺失、用户Token无效
• 403 Forbidden：身份合法但无对应操作权限，比如普通账号调用管理员接口
• 404 Not Found：请求的目标资源不存在，比如查询的业务ID对应数据不存在
• 409 Conflict：资源状态冲突，比如重复提交、数据已被其他操作修改
• 422 Unprocessable Entity：参数格式合法但不符合业务规则，比如用户名长度合规但包含违禁词
• 429 Too Many Requests：触发接口限流规则
• 500 Internal Server Error：服务端非预期异常，比如空指针、数据库连接失败等未被业务捕获的代码错误
• 503 Service Unavailable：依赖的下游服务不可用，比如第三方接口超时、存储服务连接中断

响应体结构设计 #

你当前正常场景返回Pojo1对象，两种兼容方案可按需选择：

方案A：外层统一包装（灵活性最高，推荐） #

所有请求无论成功失败，外层使用统一泛型结构，成功时将Pojo1放入data字段，错误时data置空、填充错误信息：

public class ApiResponse<T> {
    private boolean success;
    private T data;
    private ErrorDetail error;

    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> resp = new ApiResponse<>();
        resp.success = true;
        resp.data = data;
        return resp;
    }

    public static <T> ApiResponse<T> error(int bizCode, String message, String traceId) {
        ApiResponse<T> resp = new ApiResponse<>();
        resp.success = false;
        ErrorDetail detail = new ErrorDetail();
        detail.bizCode = bizCode;
        detail.message = message;
        detail.traceId = traceId;
        resp.error = detail;
        return resp;
    }

    // getter、setter省略
}

public class ErrorDetail {
    private int bizCode; // 自定义业务错误码，可与HTTP状态码独立
    private String message; // 面向调用方的人类可读错误提示
    private String traceId; // 单次请求唯一标识，可关联App Insights日志
    // getter、setter省略
}

这种方案下客户端仅需判断success字段即可区分请求结果，不需要额外根据HTTP状态码编写多套解析逻辑，适配前端、服务间调用等各类场景。

方案B：保留原有成功返回结构（改造成本低） #

如果不想调整已上线的成功返回逻辑，错误场景直接返回固定的ErrorDetail结构即可，客户端仅在HTTP状态码非2xx时解析错误结构，改造成本极低，适合存量接口快速迭代。

统一错误处理实现 #

不需要Spring生态组件，直接利用Azure Function原生API即可实现全局统一错误处理，不需要在业务代码中零散编写响应构造逻辑：

1. 自定义业务异常类，内置HTTP状态码、业务错误码、错误提示信息，业务逻辑中需要抛错的场景直接抛出该异常即可
2. 在每个函数入口的最外层包裹统一try-catch块，也可将该逻辑抽为通用工具方法，所有函数复用，示例代码：

@FunctionName("yourBizFunction")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
        final ExecutionContext context) {
    String traceId = context.getInvocationId(); // 直接使用Azure Function自带的调用ID作为traceId，自动与日志关联
    try {
        Pojo1 bizResult = doBizLogic(request);
        return request.createResponseBuilder(HttpStatus.OK)
                .header("Content-Type", "application/json")
                .body(ApiResponse.success(bizResult))
                .build();
    } catch (IllegalArgumentException e) {
        context.getLogger().warning("参数校验失败: " + e.getMessage());
        return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                .header("Content-Type", "application/json")
                .body(ApiResponse.error(40001, e.getMessage(), traceId))
                .build();
    } catch (ResourceNotFoundException e) {
        context.getLogger().warning("资源不存在: " + e.getMessage());
        return request.createResponseBuilder(HttpStatus.NOT_FOUND)
                .header("Content-Type", "application/json")
                .body(ApiResponse.error(40401, e.getMessage(), traceId))
                .build();
    } catch (BizException e) {
        context.getLogger().warning("业务异常: " + e.getMessage());
        return request.createResponseBuilder(e.getHttpStatus())
                .header("Content-Type", "application/json")
                .body(ApiResponse.error(e.getBizCode(), e.getMessage(), traceId))
                .build();
    } catch (Exception e) {
        context.getLogger().severe("服务内部错误: " + e);
        // 兜底异常不要返回原始错误栈，对外返回通用提示，排查靠traceId关联日志
        return request.createResponseBuilder(HttpStatus.INTERNAL_SERVER_ERROR)
                .header("Content-Type", "application/json")
                .body(ApiResponse.error(50000, "服务器内部错误，请稍后重试", traceId))
                .build();
    }
}

实践注意点 #

• 对外返回的错误提示不要直接输出Java异常类名、堆栈信息，要使用用户可理解的自然语言描述
• 所有错误响应必须携带traceId，排查问题时可通过该ID直接定位单次请求的全链路日志，效率提升明显
• 不要自定义非标准HTTP状态码，所有返回状态码需符合RFC标准语义，避免网关、代理、客户端出现识别异常
• 错误提示不要泄露服务内部实现细节，比如数据库地址、内部接口路径、依赖服务信息等

内容的提问来源于stack exchange，提问作者djangofan