接口定义规范

Posted 2020-11-12 wanghaichao

　　良好的编码规范应该是程序员的一种职业素养，不仅仅是对自己的要求，也是对工作以及职业的尊重。代码不仅仅是给自己看的，也要供其他同事调用、调试，而且也要运行在jvm虚拟机上，健壮性、高效率、可读性强、标准化应该是大家都追求的目标。

　　不规范的代码和开发习惯使工作中的大部分时间都在定位问题 + 改代码，填堵遗留下来的坑，导致实际用于开发中的时间并不多，高质量、高效的代码，可以切实有效的提高工作效率，减少无谓的时间浪费，也让大家在工作中少踩坑，并且杜绝踩重复的坑。本文有参照知乎晓风轻和孤尽两位大神的文章，晓风轻文章链接：https://zhuanlan.zhihu.com/p/28705206，孤尽即阿里巴巴JAVA开发手册的作者。另外建议大家的开发工具都安装阿里巴巴Java规约扫描插件和findBug插件，最实用的两款插件。

　　无规矩不成方圆，技术很重要，但在团队开发中编码习惯比技术更加重要。个人的接口定义规范如下：

1、接口定义规范：

①返回格式要统一：同一个接口，有时候返回数组，有时候返回单个，有时候返回String，成功的时候返回对象，失败的时候返回错误信息字符串。工作中的系统如果集这样定义的接口，真是让人心累。在对应代码上，返回的类型是map，json，object，string都是不应该的。实际工作中，团队需要定义一个统一的格式。我们团队中开发用一个统一的Result工具类，附带状态码、返回数据以及返回描述。文章的最后附上代码。

②、输入参数要统一

一般情况下，不允许出现例如json字符串这样的参数，这种参数可读性极差。应该定义对应的JavaBean。例如现在很多都是springboot前后台分离的项目，一般都会使用swagger来做为restfulL接口的功能测试页面，如果你传递一个json，别人如何知道调用你的接口服务需要传递什么样的参数。正确示范，另外注意前面的红色剪头，会提示：Spring AOP marker at this line，表示已经被Spring的AOP标记并且拦截了：

错误示范，这种接口你让别人该怎么调用，可读性和质量极差：

③、返回类型要统一。供外围调用的restFul接口统一返回json，方便大家解析。又一次调用订单中心接口，结果那个同事给用map存储数据，并且给转成string字符串返回，结果就是：{CODE=0000, DATA={TRAIL_INFO=[{ACCEPT_ADDRESS=天津, ACCEPT_TIME=2018-05-21 19:28:56.0, OPCODE=20, REMARK=测试}]}, DESC=物流轨迹查询成功}，好好的数据格式给变成string了，按照字符串来解析返回数据，想想就很蛋疼。

④、Controller做参数格式的转换，以及页面的跳转，不允许把业务逻辑写到controller里面，也不允许把json，map这类对象传到services去，也不允许services返回json、map。map，json这种格式灵活，但是可读性差，如果放业务数据，每次阅读起来都比较困难。定义一个bean看着工作量多了，但代码清晰多了。

　　附上我的Result代码，见过不规范的代码多了，才知道这个Result用起来有多爽，不但可以返回一个统一的格式，而且可以应用spring的AOP，：

public class Result<T> {

/**
* @Fields code : 返回状态码
*/
private String code;

/**
* @Fields msg : 返回消息描述
*/
private String msg;

/**
* @Fields data : 返回实体数据
*/
private T data;


/**
* <p>Title: </p>
* <p>Description: 异常返回时的返回构造描述</p>
* @param code
* @param msg
*/
public Result(String code, String msg) {
this.code = code;
this.msg = msg;
}

public String getCode() {
return code;
}

public void setCode(String code) {
this.code = code;
}

public String getMsg() {
return msg;
}

public void setMsg(String msg) {
this.msg = msg;
}

public T getData() {
return data;
}

public void setData(T data) {
this.data = data;
}
}

 

public class ResultUtil {

/**
* @Title: success
* @Description: 成功有返回
* @param @param object
* @param @return 设定文件
* @return Result 返回类型
*/
public static Result success(Object object){
Result result = new Result(ResultEnum.SUCCESS.getCode(), ResultEnum.SUCCESS.getMessage());
result.setData(object);
return result;
}

/**
* @Title: success
* @Description: 成功无返回
* @param @return 设定文件
* @return Result 返回类型
*/
public static Result success(){
return ResultUtil.success(null);
}

/**
* @Title: error
* @Description: 失败方法返回
* @param @param code
* @param @param msg
* @param @return 设定文件
* @return Result 返回类型, 错误返回时状态码为 9999
*/
public static Result error(String code, String msg){
Result result = new Result(code, msg);
return result;
}
}

 

public enum ResultEnum {

UNKNOWN_ERROR("-1", "未知错误"),

SUCCESS("0000", "成功"),

PARAM_ERROR("2001", "参数不合法"),

DATABASE_ERROR("7001", "数据库异常");


private String code;
private String message;

ResultEnum(String code, String message) {
this.code = code;
this.message = message;
}

public String getCode() {
return code;
}
public void setCode(String code) {
this.code = code;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
}