2. 程式人生 > 程式設計 >最佳實踐 - API 錯誤處理

最佳實踐 - API 錯誤處理

阿新 • • 發佈：2020-06-24

API 中的錯誤如何定義，請求過程中出錯或請求處理中出錯。API 無法解析傳遞的資料，API 本身有很多問題，甚至格式正確的請求也會進行失敗。在這兩種情況下，都需要進行分析查詢原因。

無論是程式碼形式的錯誤還是簡單的錯誤響應，錯誤程式碼可能是 API 領域中最有用的診斷元素，錯誤程式碼非常有用。API 響應階段中的錯誤程式碼是開發人員可以將故障傳達給使用者的基本方式。

編寫良好的錯誤程式碼

好的錯誤程式碼必須通過三個基本標準，才能真正發揮作用。好的錯誤程式碼應包括：

  • 業務域標識，因此可以輕鬆確定問題的根源和領域；
  • 內部參考 ID，用於特定於檔案的錯誤符號。在某些情況下，只要內部參考表中包含 HTTP 狀態碼方案或類似的參考資料，就可以替換 HTTP 狀態碼。
  • 人工可讀的訊息，概述了當前錯誤的上下文，原因和一般解決方案。

業界主流的處理方式

  • facebook
curl https://graph.facebook.com/v2.9/me?fields=id%2Cname%2Cpicture%2C%20picture&access_token=xxxxxxxxxxx
複製程式碼
{
  - error: {
        message: "An active access token must be used to query information about the current user.",type: "OAuthException"
 
,code: 2500,fbtrace_id: "ABdaipBGDyGFOyVCgrBfL56"
    }
}
複製程式碼
  • Twitter
curl https://api.twitter.com/1.1/statuses/mentions_timeline.json
複製程式碼
{
  - errors: [
      - {
            code: 215,message: "Bad Authentication data."
        }
    ]
}
複製程式碼

錯誤程式碼的定義

  • 請求過程中出錯，未進入處理邏輯。
{
    "domain":"pay","code"
 
:10501002,"message":"引數錯誤","errors":[
      - {
            "name":"bankNo","message":"銀行卡號不符合規範"
        }
    ]
}
複製程式碼
  • 請求處理中出錯
{
    "domain":"order","code":111501002,"message":"支付通道網路異常"
}
複製程式碼
{
    "domain":"user","code":100501001,"message":"對應的使用者不存在！"
}
複製程式碼

錯誤程式碼詳細說明：

  • domain 定義了領域，方便定位錯誤的根源。
  • code 定義了內部錯誤的編碼
  • message 描述了錯誤的原因
  • error 對部分具體性錯誤進行了詳細的說明

code 補充說明：異常碼說明是由 8位 數字組成，前三位系統標識（從100開始），中間兩位是模組標識（業務劃分），後三位是異常標識（特定異常） error 補充說明：當 message 不能準確描述錯誤產生的原因，需要細化每項錯誤說明時，可考慮使用 error 欄位，來補充說明錯誤項。 domain 補充說明：底層框架裡面封裝了部分異常處理，比如引數校驗錯誤這種 code 應該是全系統共用的，而不會有系統標識。導致就不能根據 code 識別出來是哪個系統發生錯誤了，鏈路一長就很難排查到底是哪的問題了，所以錯誤處理中動態去拿當前應用的業務域標識。

錯誤處理 - Spring Boot

定義 Response 模型

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;
/**
 * Result
 *
 * @author Weichao Li ([email protected])
 * @since 2019-08-11
 */
@Data
@AllArgsConstructor
@ApiModel("統一 Response 返回值")
public class Result<T> implements Serializable {
    private static final long serialVersionUID = 1L;
    public static final long SUCCESS_CODE = 200L;
    public static final String DEFAULT_SUCCESS_MESSAGE = "success";
    @ApiModelProperty(name = "業務域或應用標識",notes = "僅當產生錯誤時會賦值該欄位")
    private String domain;
    @ApiModelProperty(name = "結果碼",notes = "正確響應時該值為 Result#SUCCESS_CODE，錯誤響應時為錯誤程式碼")
    private long code;
    @ApiModelProperty(name = "人工可讀的訊息",notes = "正確響應時該值為 Result#DEFAULT_SUCCESS_MESSAGE，錯誤響應時為錯誤資訊")
    private String msg;
    @ApiModelProperty(name = "響應體",notes = "正確響應時該值會被使用")
    private T data;
    /**
     * 當驗證錯誤時，各項具體的錯誤資訊
     */
    @ApiModelProperty("錯誤資訊")
    private List<Error> errors;
    public Result(T data) {
        this.setData(data);
        this.setCode(SUCCESS_CODE);
        this.setMsg(DEFAULT_SUCCESS_MESSAGE);
    }
    public Result() {
        this.setCode(SUCCESS_CODE);
        this.setMsg(DEFAULT_SUCCESS_MESSAGE);
    }
    public void addError(String name,String message) {
        if (this.errors == null) {
            this.errors = new ArrayList<>();
        }
        this.errors.add(new Error(name,message));
    }
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    @ApiModel("統一 Response 返回值中錯誤資訊的模型")
    public class Error {
        @ApiModelProperty(name = "錯誤項",notes = "錯誤的具體項")
        private String name;
        @ApiModelProperty(name = "錯誤項說明",notes = "錯誤的具體項說明")
        private String message;
    }
}
複製程式碼

異常攔截器處理

Spring Boot 的專案已經對有一定的異常處理了，但是比較泛化不夠精細化，因此需要基礎框架對這些異常進行統一的捕獲並處理。Spring Boot 中有一個 @RestControllerAdvice 的註解，使用該註解表示開啟了全域性異常的捕獲，我們只需在自定義一個方法使用 ExceptionHandler 註解然後定義捕獲異常的型別即可對這些捕獲的異常進行統一的處理。 定義異常基礎類

import com.github.hicolors.best.practices.pojo.Result;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;

/**
 * 擴充套件異常
 *
 * @author Weichao Li ([email protected])
 * @since 2019-08-11
 */
@Getter
@NoArgsConstructor
@AllArgsConstructor
public class ExtensionException extends RuntimeException {

    /**
     * 業務域
     */
    private String domain;

    /**
     * 業務異常碼 ( 詳情參加檔案說明 )
     */
    private Long code;

    /**
     * 業務異常資訊
     */
    private String message;

    /**
     * 額外資料，可支援擴充套件
     */
    private Object data;

    /**
     * cause
     */
    private Throwable cause;

    /**
     * 業務域標識自動取當前服務
     *
     * @param code    code
     * @param message message
     */
    public ExtensionException(Long code,String message) {
        this.code = code;
        this.message = message;
    }

    /**
     * 指定業務域標識
     *
     * @param domain  domain
     * @param code    code
     * @param message message
     */
    public ExtensionException(String domain,Long code,String message) {
        this.domain = domain;
        this.code = code;
        this.message = message;
    }

    public ExtensionException(Result result) {
        this.domain = result.getDomain();
        this.code = result.getCode();
        this.message = result.getMsg();
        this.data = result.getData();
    }
複製程式碼

}

全域性異常處理器 - 資訊列舉

import lombok.Getter;
/**
 * WebMvc 模組異常碼定義
 * <p>
 * 系統標識：100
 * 模組標識：02
 *
 * @author Weichao Li ([email protected])
 * @since 2019-08-11
 */
@Getter
public enum EnumExceptionMessageWebMvc {
    // 非預期異常
    UNEXPECTED_ERROR(10002000L,"服務發生非預期異常，請聯絡管理員！"),PARAM_VALIDATED_UN_PASS(10002001L,"引數校驗(JSR303)不通過，請檢查引數或聯絡管理員！"),NO_HANDLER_FOUND_ERROR(10002002L,"未找到對應的處理器，請檢查 API 或聯絡管理員！"),HTTP_REQUEST_METHOD_NOT_SUPPORTED_ERROR(10002003L,"不支援的請求方法，請檢查 API 或聯絡管理員！"),HTTP_MEDIA_TYPE_NOT_SUPPORTED_ERROR(10002004L,"不支援的網際網路媒體型別，請檢查 API 或聯絡管理員"),;
    private final Long code;
    private final String message;
    EnumExceptionMessageWebMvc(Long code,String message) {
        this.code = code;
        this.message = message;
    }
}
複製程式碼

全域性異常處理器

import com.github.hicolors.best.practices.exception.ExtensionException;
import com.github.hicolors.best.practices.pojo.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.util.StringUtils;
import org.springframework.validation.BindException;
import org.springframework.validation.FieldError;
import org.springframework.web.HttpMediaTypeNotSupportedException;
import org.springframework.web.HttpRequestMethodNotSupportedException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.NoHandlerFoundException;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.validation.ConstraintViolation;
import javax.validation.ConstraintViolationException;
import java.text.MessageFormat;
import java.util.List;
import java.util.Objects;
/**
 * ExceptionHandlerAdvice
 *
 * @author Weichao Li ([email protected])
 * @since 2019/11/25
 */
@RestControllerAdvice
@Slf4j
public class ExceptionHandlerAdvice {

    @Value("${spring.application.domain:${spring.application.name:unknown-spring-boot}}")
    private String domain;

    /**
     * 針對業務異常的處理
     *
     * @param exception 業務異常
     * @param request   http request
     * @param response  http response
     * @return 異常處理結果
     */
    @ExceptionHandler(value = ExtensionException.class)
    @SuppressWarnings("unchecked")
    public Result extensionException(ExtensionException exception,HttpServletRequest request,HttpServletResponse response) {
        log.warn("請求發生了預期異常，出錯的 url [{}]，出錯的描述為 [{}]",request.getRequestURL().toString(),exception.getMessage());
        Result result = new Result();
        result.setDomain(StringUtils.isEmpty(exception.getDomain()) ? domain : exception.getDomain());
        result.setCode(exception.getCode());
        result.setMsg(exception.getMessage());
        Object data = exception.getData();
        if (Objects.nonNull(data) && data instanceof List) {
            if (((List) data).size() > 0 && (((List) data).get(0) instanceof Result.Error)) {
                result.setErrors((List<Result.Error>) data);
            }
        }
        return result;
    }

    /**
     * 針對引數校驗失敗異常的處理
     *
     * @param exception 引數校驗異常
     * @param request   http request
     * @param response  http response
     * @return 異常處理結果
     */
    @ExceptionHandler(value = {BindException.class,MethodArgumentNotValidException.class,ConstraintViolationException.class})
    public Result databindException(Exception exception,HttpServletResponse response) {
        log.error(MessageFormat.format("請求發生了非預期異常，出錯的 url [{0}]，出錯的描述為 [{1}]",exception.getMessage()),exception);
        Result result = new Result();
        result.setDomain(domain);
        result.setCode(EnumExceptionMessageWebMvc.PARAM_VALIDATED_UN_PASS.getCode());
        result.setMsg(EnumExceptionMessageWebMvc.PARAM_VALIDATED_UN_PASS.getMessage());

        if (exception instanceof BindException) {
            for (FieldError fieldError : ((BindException) exception).getBindingResult().getFieldErrors()) {
                result.addError(fieldError.getField(),fieldError.getDefaultMessage());
            }
        } else if (exception instanceof MethodArgumentNotValidException) {
            for (FieldError fieldError : ((MethodArgumentNotValidException) exception).getBindingResult().getFieldErrors()) {
                result.addError(fieldError.getField(),fieldError.getDefaultMessage());
            }
        } else if (exception instanceof ConstraintViolationException) {
            for (ConstraintViolation cv : ((ConstraintViolationException) exception).getConstraintViolations()) {
                result.addError(cv.getPropertyPath().toString(),cv.getMessage());
            }
        }
        return result;
    }

    /**
     * 針對spring web 中的異常的處理
     *
     * @param exception Spring Web 異常
     * @param request   http request
     * @param response  http response
     * @return 異常處理結果
     */
    @ExceptionHandler(value = {
            NoHandlerFoundException.class,HttpRequestMethodNotSupportedException.class,HttpMediaTypeNotSupportedException.class
    })
    public Result springWebExceptionHandler(Exception exception,exception);
        Result result = new Result();
        result.setDomain(domain);
        if (exception instanceof NoHandlerFoundException) {
            result.setCode(EnumExceptionMessageWebMvc.NO_HANDLER_FOUND_ERROR.getCode());
            result.setMsg(EnumExceptionMessageWebMvc.NO_HANDLER_FOUND_ERROR.getMessage());
        } else if (exception instanceof HttpRequestMethodNotSupportedException) {
            result.setCode(EnumExceptionMessageWebMvc.HTTP_REQUEST_METHOD_NOT_SUPPORTED_ERROR.getCode());
            result.setMsg(EnumExceptionMessageWebMvc.HTTP_REQUEST_METHOD_NOT_SUPPORTED_ERROR.getMessage());
        } else if (exception instanceof HttpMediaTypeNotSupportedException) {
            result.setCode(EnumExceptionMessageWebMvc.HTTP_MEDIA_TYPE_NOT_SUPPORTED_ERROR.getCode());
            result.setMsg(EnumExceptionMessageWebMvc.HTTP_MEDIA_TYPE_NOT_SUPPORTED_ERROR.getMessage());
        } else {
            result.setCode(EnumExceptionMessageWebMvc.UNEXPECTED_ERROR.getCode());
            result.setMsg(EnumExceptionMessageWebMvc.UNEXPECTED_ERROR.getMessage());
        }
        return result;
    }

    /**
     * 針對全域性異常的處理
     *
     * @param exception 全域性異常
     * @param request   http request
     * @param response  http response
     * @return 異常處理結果
     */
    @ExceptionHandler(value = Throwable.class)
    public Result throwableHandler(Exception exception,exception);
        Result result = new Result();
        result.setDomain(domain);
        result.setCode(EnumExceptionMessageWebMvc.UNEXPECTED_ERROR.getCode());
        result.setMsg(EnumExceptionMessageWebMvc.UNEXPECTED_ERROR.getMessage());
        return result;
    }

}
複製程式碼

使用

  • 業務開發異常使用
    // 此處只是簡單演示，邏輯處理應該抽象在 mvc 分層中，業務開發過程中只需要拋異常即可。
    @GetMapping
    public String get() {
        throw new ExtensionException(105001001L,"simple 資源不存在");
    }
複製程式碼

圖片

  • 基礎框架異常使用

model

@Data
public class ValidatedModel {
    @NotNull(message = "id 不能為空")
    @Min(value = 10,message = "id 不能小於 10")
    private Long id;
    
    @NotBlank(message = "name 不能為空")
    @Length(max = 5,message = "name 長度不能超過 5")
    private String name;
}
複製程式碼

controller

	// 此處只是簡單演示
    @PostMapping("/test/validated")
    public String getx(@Validated @RequestBody ValidatedModel model) {
        return model.getName();
    }
複製程式碼

圖片

程式碼連結

示例中所有程式碼

招聘

潮流電商平臺行業獨角獸（毒APP）基礎架構團隊誠招 Java / Golang / Kubernetes 研發工程師/架構師，Base 上海楊浦互聯寶地，歡迎有興趣的同學投遞簡歷到 [email protected] 。

相關推薦

最佳實踐 - API 錯誤處理

API 中的錯誤如何定義，請求過程中出錯或請求處理中出錯。API 無法解析傳遞的資料，API 本身有很多問題，甚至格式正確的請求也會進行失敗。在這兩種情況下，都需要進行分析查詢原因。

Rust錯誤處理最佳實踐

錯誤處理是Rust編碼過程中重要的一環; ) 序言 現實世界處處凶險,充滿了未知和異常,錯誤處理是保持程式碼健壯性必不可少的環節,處理錯誤的方式各有千秋,本文是對筆者在學習與實踐過程中摸索得來的錯誤處理之道的梳理

RESTful API 最佳實踐

RESTful API 最佳實踐 RESTful是目前最流行的 API 規範，適用於 Web 介面規範的設計。讓介面易讀，且含義清晰。本文將介紹如何設計易於理解和使用的 API，並且藉助 Docker api 的實踐說明。

Spring Boot提供RESTful介面時的錯誤處理實踐

使用Spring Boot開發微服務的過程中，我們會使用別人提供的介面，也會設計介面給別人使用，這時候微服務應用之間的協作就需要有一定的規範。

API 設計最佳實踐的思考

API 設計最佳實踐的思考 谷樸 釋出於：2019 年 5 月 21 日 08:00 導讀：API 是模組或者子系統之間互動的介面定義。好的系統架構離不開好的 API 設計，而一個設計不夠完善的 API 則註定會導致系統的後續發展和維護

Elasticsearch 常見的 8 種錯誤及最佳實踐

題記 Elasticsearch 社群有大量關於 Elasticsearch 錯誤和異常的問題。 深挖這些錯誤背後的原因，把常見的錯誤積累為自己的實戰經驗甚至是工具，不僅可以節省我們的開發和運維時間，而且可以幫助確保 Elasticsearch

圖片載入失敗後CSS樣式處理最佳實踐

1、傳統的圖片異常處理 <img>如果因為網路或者跨域限制等原因無法正常載入，在預設情況下會顯示瀏覽器預設的“裂開”的圖片效果，如果設定了 alt 屬性值，則 alt 屬性對應的內容也會一併顯示。例如：

XAML: 自定義控制元件中事件處理的最佳實踐

技術標籤：C#c#xaml 在開發 XAML(WPF/UWP) 應用程式中，有時候，我們需要建立自定義控制元件 (Custom Control) 來滿足實際需求。而在自定義控制元件中，我們一般會用到一些原生的控制元件（如 Button、TextBox 等

日期處理-最佳實踐

技術標籤：java基礎java 文章目錄 一、舊API轉新API二、新API轉舊API三、與資料庫對映四、新API結構

c#程式設計最佳實踐1：異常處理

技術標籤：C#資料結構與演算法 — 你是否在使用者輸入驗證中使用異常處理機制?

Spark 大資料處理最佳實踐

開源大資料社群 & 阿里雲 EMR 系列直播 第十一期 主題：Spark 大資料處理最佳實踐

最佳實踐_C#Api對接實體校驗

工作之後，做過不少的api對接，有提供api介面，也有呼叫對方api介面。api對接中，實體校驗一定是必不可少的一個通用模組。

JAVA 中異常處理的最佳實踐

前言 異常處理的問題之一是知道何時以及如何去使用它。我會討論一些異常處理的最佳實踐，也會總結最近在異常處理上的一些爭論。

Java 異常處理的 9 個最佳實踐

在 Java 中，異常處理是個很麻煩的事情。初學者覺得它很難理解，甚至是經驗豐富的開發者也要花費很長時間決定異常是要處理掉和丟擲。

RESTful API的十個最佳實踐1. 使用名詞而不是動詞 2. Get方法和查詢引數不應該改變資源狀態3. 使用名詞的複數形式 4. 為關係使用子資源 5. 使用HTTP頭決定序列化格式 6. 使

WebAPI在過去幾年裡非常的盛行，我們很多以往的技術手段都慢慢的轉換為使用WebAPI來開發，因為它的語法簡單規範化，以及輕量級等特點，這種方式收到了廣泛的推崇。

3種方式！Go Error處理最佳實踐

https://mp.weixin.qq.com/s/rn51V4VwXYb46h8_ugafeg 3種方式！Go Error處理最佳實踐 原創 李森林 雲加社群 2022-05-09 18:39

k8s 最佳實踐：處理記憶體碎片化

k8s 最佳實踐：處理記憶體碎片化 記憶體碎片化造成的危害 節點的記憶體碎片化嚴重，導致docker執行容器時，無法分到大的記憶體塊，導致start docker失敗。最終導致服務更新時，狀態一直都是啟動中

限流-最佳實踐

對比基於時間視窗的限流演演算法，令牌桶和漏桶演演算法對流量整形效果比時間視窗演演算法要好很多，但是並不是整形效果越好就越合適，對於沒有提前預熱的令牌桶，如果做否決式限流，會導致誤殺很多請求。上述演演算

ScrollView巢狀tableView聯動滾動最佳實踐

前言 隨著業務的發展，頁面的複雜度越來越高，巢狀滾動檢視的方式也越來越受設計師們的青睞，在各大電商App十分常見。如下Demo圖：

[譯] Go 1.13 errors 包錯誤處理

原文地址：peter.bourgon.org/blog/2019/0… 原文作者：Peter 譯文地址：github.com/watermelo/d…