【开发规范】替API接口制定统一的报文返回格式

阳光穿透心脏的1/2处 2024-03-30 09:28 31阅读 0赞

实行前后端分离项目开发模式后，后端与前端之间的数据交互都变成了API接口的形式，这种项目模式将导致一个项目内拥有非常多的API接口。当然，即使采用 Spring Cloud 微服务开发模式，服务与服务之间的数据交互也是通过服务的对外API接口，API接口的数量也是非常可观的。

如果我们在项目开发初期不制定一份「统一的API接口的报文返回格式」，那么在一段时期的业务开发后项目内大概率会出现五花八门的API接口的报文返回格式，然后不仅会为跟前端同事联调增加不必要的工作量，还会对线上问题排查、项目更新迭代、项目重构等方面产生不可估量的负面影响。

因此，我们有必要在项目初期启动时就制定好一份合理的「统一的API接口的报文返回格式」，下面我将为大家提供了一份自己的实践示例，希望可以起到一个抛砖引玉的作用。

### （1）定义一个返回报文格式： ###

在上面代码中，time 字段表示当前精确到秒的时间，通过一个内部的公共方法获取。

### （2）定义API接口统一的返回状态码 ###

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 </td> 
 <td> package cn.webuser.common.resp; /** * API接口返回状态码 * */ public enum BaseResultCode { &nbsp;&nbsp;&nbsp;&nbsp;/* 成功状态码 */ &nbsp;&nbsp;&nbsp;&nbsp;SUCCESS("0000", "处理成功"), &nbsp;&nbsp;&nbsp;&nbsp;/* 参数错误：1001-1999 */ &nbsp;&nbsp;&nbsp;&nbsp;PARAM_IS_INVALID("1001", "参数无效"), &nbsp;&nbsp;&nbsp;&nbsp;PARAM_IS_BLANK("1002", "参数为空"), &nbsp;&nbsp;&nbsp;&nbsp;PARAM_TYPE_BIND_ERROR("1003", "参数类型错误"), &nbsp;&nbsp;&nbsp;&nbsp;PARAM_NOT_COMPLETE("1004", "参数缺失"), &nbsp;&nbsp;&nbsp;&nbsp;PARAM_VALIDATION_FAILS("1005", "验签失败"), &nbsp;&nbsp;&nbsp;&nbsp;REFRESH_TOKEN_IS_INVALID("1006", "Refresh Token不可用"), &nbsp;&nbsp;&nbsp;&nbsp;/* 用户错误：2001-2999 */ &nbsp;&nbsp;&nbsp;&nbsp;USER_NOT_LOGGED_IN("2001", "账号未登录"), &nbsp;&nbsp;&nbsp;&nbsp;USER_LOGIN_ERROR("2002", "账号名或密码错误"), &nbsp;&nbsp;&nbsp;&nbsp;USER_ACCOUNT_FORBIDDEN("2003", "账号已被禁用"), &nbsp;&nbsp;&nbsp;&nbsp;USER_ACCOUNT_IS_DEL("2004", "账号已注销"), &nbsp;&nbsp;&nbsp;&nbsp;USER_ACCOUNT_NOT_EXIST("2005", "账号不存在"), &nbsp;&nbsp;&nbsp;&nbsp;USER_ACCOUNT_HAS_EXISTED("2006", "账号已存在"), &nbsp;&nbsp;&nbsp;&nbsp;USER_ACCOUNT_NO_BALANCE("2007", "账户余额不足"), &nbsp;&nbsp;&nbsp;&nbsp;USER_ACCOUNT_IN_REVIEW("2008", "账号审核中"), &nbsp;&nbsp;&nbsp;&nbsp;USER_ACCOUNT_FALSE_REGISTER("2009", "账号审核未通过，请重新注册或联系管理员"), &nbsp;&nbsp;&nbsp;&nbsp;USER_PASSPORT_ERROR_TIMES_4("2010", "密码输入错误。如果输错次数超过4次，账户将被锁定"), &nbsp;&nbsp;&nbsp;&nbsp;USER_PASSPORT_ERROR_LOCK("2011", "密码输入错误次数过多，账户已被锁定"), &nbsp;&nbsp;&nbsp;&nbsp;//手机号 &nbsp;&nbsp;&nbsp;&nbsp;USER_PHONE_ERROR("2101", "手机号错误"), &nbsp;&nbsp;&nbsp;&nbsp;USER_PHONE_FORBIDDEN("2102", "手机号已被禁用"), &nbsp;&nbsp;&nbsp;&nbsp;USER_PHONE_NOT_EXIST("2103", "手机号未注册"), &nbsp;&nbsp;&nbsp;&nbsp;USER_PHONE_HAS_EXISTED("2104", "手机号已注册"), &nbsp;&nbsp;&nbsp;&nbsp;USER_PHONE_PWD_SIMPLE("2105", "密码应由6~20位字母、数字或符号两种或三种组成"), &nbsp;&nbsp;&nbsp;&nbsp;//验证码 &nbsp;&nbsp;&nbsp;&nbsp;USER_CODE_TIMEOUT("2201","验证码已失效，请重新获取"), &nbsp;&nbsp;&nbsp;&nbsp;USER_CODE_NULL("2202","还未获取验证码，请重新获取"), &nbsp;&nbsp;&nbsp;&nbsp;USER_CODE_ERROR_MORE("2203","验证码多次错误，请重新获取"), &nbsp;&nbsp;&nbsp;&nbsp;USER_CODE_COUNT_MORE("2204","验证码发送次数过多，请明天重试"), &nbsp;&nbsp;&nbsp;&nbsp;USER_CODE_SEND_ERROR("2205","验证码发送失败，请重新获取"), &nbsp;&nbsp;&nbsp;&nbsp;USER_CODE_VERIFY_ERROR("2206","验证码校验失败！"), &nbsp;&nbsp;&nbsp;&nbsp;//修改密码 &nbsp;&nbsp;&nbsp;&nbsp;USER_MODIFY_PWD_ERROR("2301","原始密码错误"), &nbsp;&nbsp;&nbsp;&nbsp;USER_MODIFY_PWD2_ERROR("2302","新密码不一致"), &nbsp;&nbsp;&nbsp;&nbsp;USER_MODIFY_PWD3_ERROR("2303","修改密码失败"), &nbsp;&nbsp;&nbsp;&nbsp;/* 业务错误：3001-3999 */ &nbsp;&nbsp;&nbsp;&nbsp;BUSINESS_INNER_ERROR("3001", "某业务出现问题"), &nbsp;&nbsp;&nbsp;&nbsp;/* 系统错误：4001-4999 */ &nbsp;&nbsp;&nbsp;&nbsp;SYSTEM_INNER_ERROR("4001", "系统错误"), &nbsp;&nbsp;&nbsp;&nbsp;SYSTEM_IS_BUSY("4002", "系统繁忙，请稍后重试"), &nbsp;&nbsp;&nbsp;&nbsp;/* 数据错误：5001-59999 */ &nbsp;&nbsp;&nbsp;&nbsp;DATA_NO_RESULTS("5001", "没有查询到结果"), &nbsp;&nbsp;&nbsp;&nbsp;DATA_IS_WRONG("5002", "数据有误"), &nbsp;&nbsp;&nbsp;&nbsp;DATA_ALREADY_EXISTED("5003", "数据已存在"), &nbsp;&nbsp;&nbsp;&nbsp;/* 接口错误：6001-6999 */ &nbsp;&nbsp;&nbsp;&nbsp;INTERFACE_INNER_INVOKE_ERROR("6001", "内部系统接口调用异常"), &nbsp;&nbsp;&nbsp;&nbsp;INTERFACE_OUTER_INVOKE_ERROR("6002", "外部系统接口调用异常"), &nbsp;&nbsp;&nbsp;&nbsp;INTERFACE_FORBID_VISIT("6003", "该接口禁止访问"), &nbsp;&nbsp;&nbsp;&nbsp;INTERFACE_ADDRESS_INVALID("6004", "接口地址无效"), &nbsp;&nbsp;&nbsp;&nbsp;INTERFACE_REQUEST_TIMEOUT("6005", "接口请求超时"), &nbsp;&nbsp;&nbsp;&nbsp;INTERFACE_EXCEED_LOAD("6006", "接口负载过高"), &nbsp;&nbsp;&nbsp;&nbsp;/* 权限错误：7001-7999 */ &nbsp;&nbsp;&nbsp;&nbsp;PERMISSION_NO_ACCESS("7001", "无访问权限"); &nbsp;&nbsp;&nbsp;&nbsp;private String code; &nbsp;&nbsp;&nbsp;&nbsp;private String msg; &nbsp;&nbsp;&nbsp;&nbsp;BaseResultCode(String code, String msg) { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.code = code; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.msg = msg; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;public String code() { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return this.code; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;public String msg() { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return this.msg; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;/** &nbsp;&nbsp;&nbsp;&nbsp; * 通过 code 获取对应枚举对象 &nbsp;&nbsp;&nbsp;&nbsp; */ &nbsp;&nbsp;&nbsp;&nbsp;public static BaseResultCode fromCode(String code) { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;for (BaseResultCode item : BaseResultCode.values()) { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (item.code.equals(code)) { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return item; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return null; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;/** &nbsp;&nbsp;&nbsp;&nbsp; * 通过 code 获取对应的状态码描述 &nbsp;&nbsp;&nbsp;&nbsp; */ &nbsp;&nbsp;&nbsp;&nbsp;public static String getMsgByCode(String code) { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;for (BaseResultCode item : BaseResultCode.values()) { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (item.code.equals(code)) { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return item.msg; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return null; &nbsp;&nbsp;&nbsp;&nbsp;} //&nbsp;&nbsp;&nbsp;&nbsp;/** //&nbsp;&nbsp;&nbsp;&nbsp; * 校验重复的code值 //&nbsp;&nbsp;&nbsp;&nbsp; */ //&nbsp;&nbsp;&nbsp;&nbsp;public static void main(String[] args) { //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;BaseResultCode[] resultCodes = BaseResultCode.values(); //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;List&lt;String&gt; codeList = new ArrayList&lt;&gt;(); // //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;for (BaseResultCode resultCode : resultCodes) { //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (codeList.contains(resultCode.code)) { //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;System.out.println(resultCode.code); //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} else { //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;codeList.add(resultCode.code()); //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} //&nbsp;&nbsp;&nbsp;&nbsp;} } </td> 
 </tr> 
 </tbody> 
</table>

### （3）配置生成统一的API接口返回格式 ###

### （4）配置并使用 ###

参数配置：

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 </td> 
 <td> #配置当前服务的tid生成工具类 tid: &nbsp;&nbsp;machine: &nbsp;&nbsp;&nbsp;&nbsp;id: 1 </td> 
 </tr> 
 </tbody> 
</table>

加载配置：

### （5）测试用例 ###

调用接口后返回数据如下：