[Aprendizaje Java] Especificación de datos de la interfaz API

En el desarrollo diario, una API elegante debe proporcionar valores de respuesta simples y claros, y luego puede conocer aproximadamente el problema según el código de estado. Aquí organizamos principalmente códigos de estado HTTP y códigos de estado personalizados.

1. Código de estado HTTP

Cuando un navegador visita una página web, el navegador del navegador envía una solicitud al servidor donde se encuentra la página web. Antes de que el navegador reciba y muestre la página web, el servidor donde se encuentra la página web devolverá un encabezado de servidor que contiene el código de estado HTTP en respuesta a la solicitud del navegador.

Los códigos de estado HTTP comunes son:

200 - La solicitud fue exitosa.

301 - El recurso (página web, etc.) se mueve permanentemente a otra URL.

403 - Acceso denegado por el servidor. Se pasó la autenticación, pero el recurso no tiene permiso para operar.

404 - El recurso solicitado (página web, etc.) no existe.

Error interno de servidor 500.

504 - Se agotó el tiempo de espera de la puerta de enlace. El servidor actúa como puerta de enlace o proxy, pero no recibe una solicitud del servidor ascendente de manera oportuna.

2. Clasificación del código de estado HTTP

Los códigos de estado HTTP se pueden dividir en 5 categorías: respuesta de mensaje, respuesta exitosa, redirección, error del cliente, error del servidor.

3. Especificación de código de estado de respuesta personalizada

El back-end regresa al front-end generalmente en formato json, que se define de la siguiente manera:

{
    #返回状态码
    Code:integer,
    #返回信息描述
    message:string,
    #返回值
  	data:object
}
复制代码

3.1, interfaz de retorno

public interface IResultStatus {
    /**
     * 状态码
     * @return
     */
    Integer errorCode();
    /**
     * 异常信息
     * @return
     */
    String errorMsg();
}
复制代码

3.2 Enumeración de códigos de estado:

public enum ResultStatus implements IResultStatus {
    /**
     * 状态码及对应信息
     */
    //成功状态码
    SUCCESS(0, "执行成功"),
    //参数错误：1001~1999
    PARAM_IS_INVALID(1001, "参数无效"),
    PARAM_IS_BLANK(1002, "参数为空"),
    PARAM_TYPE_BIND_ERROR(1003, "参数类型错误"),
    //用户错误：2001~2999
    USER_LOGIN_ERROR(2001, "账号不存在或密码错误"),
    USER_ACCOUNT_FORBIDDEN(2002, "账户已被禁用"),
    USER_NOT_EXIST(2003, "用户不存在");
    private int errorCode;
    private String errorMsg;
    ResultStatus(int errorCode, String errorMsg) {
        this.errorCode = errorCode;
        this.errorMsg = errorMsg;
    }
    @Override
    public Integer errorCode() {
        return errorCode;
    }
    @Override
    public String errorMsg() {
        return errorMsg;
    }
}
复制代码

El código de estado y la información se corresponderán uno por uno, lo que es más fácil de mantener. De esta manera, después de que los colegas de front-end obtengan el valor de retorno, pueden saber cuál es probablemente el error según el código de estado y luego pueden ubicarlo rápidamente de acuerdo con la descripción de la información relacionada con el mensaje.

3.3, devolver cuerpo de datos

formato json, hay diferentes cuerpos json según diferentes negocios, puede diseñar un resultado de clase de cuerpo de retorno

@Data
public class Result<T> {
    private Integer code;
    private String message;
    private Object data;
    public Result(ResultStatus restStatus, Object data) {
        this.code = restStatus.errorCode();
        this.message = restStatus.errorMsg();
        this.data = data;
    }
    /**
     * 业务成功返回业务代码和描述信息
     */
    public static Result<Void> success() {
        return new Result<Void>(ResultStatus.SUCCESS, null);
    }
    /**
     * 业务成功返回业务代码,描述和返回的参数
     */
    public static <T> Result<T> success(T data) {
        return new Result<T>(ResultStatus.SUCCESS, data);
    }
    /**
     * 业务成功返回业务代码,描述和返回的参数
     */
    public static <T> Result<T> success(ResultStatus resultStatus, T data) {
        if (resultStatus == null) {
            return success(data);
        }
        return new Result<T>(resultStatus, data);
    }
    /**
     * 业务异常返回业务代码和描述信息
     */
    public static <T> Result<T> failure() {
        return new Result<T>(ResultStatus.PARAM_TYPE_BIND_ERROR, null);
    }
    /**
     * 业务异常返回业务代码,描述和返回的参数
     */
    public static <T> Result<T> failure(ResultStatus resultStatus) {
        return failure(resultStatus, null);
    }
    /**
     * 业务异常返回业务代码,描述和返回的参数
     */
    public static <T> Result<T> failure(ResultStatus resultStatus, T data) {
        if (resultStatus == null) {
            return new Result<T>(ResultStatus.PARAM_IS_INVALID, null);
        }
        return new Result<T>(resultStatus, data);
    }
}
复制代码

3.4 Prueba del cuerpo de retorno

@RestController
@RequestMapping("/api/demo2")
public class Demo2Controller {
    private static final HashMap<String, Object> INFO;
    static {
        INFO = new HashMap<>();
        INFO.put("name", "张三");
        INFO.put("age", "25");
    }
    @GetMapping("/getInfo")
    public Map<String, Object> getInfo() {
        return INFO;
    }
    @GetMapping("/getInfoResult")
    public Result<Map<String, Object>> getInfoResult() {
        return Result.success(INFO);
    }
}
复制代码

Referencia del resultado: