码迷,mamicode.com
首页 > 其他好文 > 详细

接口定义规范

时间:2018-06-07 21:57:17      阅读:2617      评论:0      收藏:0      [点我收藏+]

标签:其他   add   accept   @param   图片   stat   逻辑   异常   作者   

  良好的编码规范应该是程序员的一种职业素养,不仅仅是对自己的要求,也是对工作以及职业的尊重。代码不仅仅是给自己看的,也要供其他同事调用、调试,而且也要运行在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;
}
}

 

接口定义规范

标签:其他   add   accept   @param   图片   stat   逻辑   异常   作者   

原文地址:https://www.cnblogs.com/wanghaichao/p/9152707.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!