对于相对规范的服务API应如何实现

请求与响应

请求与响应参数是前后端开发人员对接的重要关注点，如果后端 API 不能向前端（甚至是自己）清晰的传达我接收什么，我返回什么的问题，那么对于双方来说，这都是一种灾难。

通用的 ApiResult

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ApiResult<T> implements Serializable {
    private static final long serialVersionUID = 2747440445733983051L;
 
    /**
     * 状态
     */
    private Integer status;
 
    /**
     * 信息
     */
    private String msg;
 
    /**
     * 响应数据
     */
    private T payload;
 
    /**
     * 程序异常信息
     */
    private String exception;
}
 

这是一个简单的ApiResult示例，你所开发的每一个接口响应参数都应该是它，它是处于顶层的响应参数结构，通过指定不同的泛型适应各个接口的需求。各个参数作用如下:

• status 状态码，用不同的数字表示当前接口处理完成后的结果状态。请不要与 Http 的状态混为一谈，我们不希望直接使用 Http 的状态来表示。 Http 的状态每次请求都应该是 200 的，处理的结果应由响应参数来体现。
• msg 信息，后端服务提示用户消息的主要途径，因为许多的提示信息（正确或错误）都是在后端程序执行过程中才会出现。一般这个信息前端需要使用弹窗、横幅或其他手段去传达给用户的。
• payload 响应数据，这个参数可以是任何数据类型，它是接口响应的具体业务数据。
• exception 程序异常信息，结合自己的开发经验，觉得需要这样一个参数来帮助开发者更快的定位问题。例如发生某个异常，这个参数可以是该异常的具体信息e.getMessage()，所以开发人员只需通过浏览器开发者工具就能找到发生异常的原因。注意这个信息是不能传达给用户的！

可以根据自己的习惯去命名这些参数，也可以为ApiResult扩展一些常用的方法，使得接口在构建响应参数时更加方便。

状态码枚举

@Getter
@AllArgsConstructor
public enum ApiStatusEnum {
 
    /**
     * 成功
     */
    SUCCESS(200, "处理成功"),
 
    /**
     * 未授权（登录信息有误，需要重新登录）
     */
    UNAUTHORIZED(401, "未授权（登录信息有误 需要重新登录）"),
 
    /**
     * 无操作权限
     */
    NO_PERMISSIONS(403, "无操作权限"),
 
    /**
     * 失败
     */
    FAIL(500, "处理失败");
 
    /**
     * 状态码
     */
    private final Integer status;
 
    /**
     * 提示消息
     */
    private final String msg;
}
 

这是一个状态码枚举示例，它的status最终会体现在ApiResult的status中，前端得以根据不同的状态码进行逻辑处理，可以根据业务需要进行添加。可以参考 http 标准的状态码列举，但是一般与业务相近的 http 状态码少之又少，所以按照数字顺序不断自增列举的方式也是可取的。

使用实体类声明请求与响应参数

一个优秀的 API 接口，是不需要翻阅具体代码就能知道它的请求与响应参数的。

不知道有多少人喜欢使用Map或者类似于Map的类去接收和响应数据，甚至是使用String搭配一些 Json 工具去处理。这是非常愚蠢的操作。当然，爽是真的爽，但是这样的爽非常自私。对于调用者1来说，这样的的接口就像是一个黑盒子&#