Java初级程序员编码规范——接口

目录

1. 接口定义常见问题

1.1 返回个数不统一

1.2 没有考虑操作失败的情况

1.3 出现和业务无关的输入参数

1.4 出现复杂的输入参数

1.5 没有返回该返回的数据类型

2. 接口统一格式定义

---

在实际的项目开发中，接口定义是必须的。系统的集成需要定义接口，前后台调用也需要定义接口。通过接口的定义，能够在一定程度上看出程序员的编程功底。 接下来就列出在项目开发中经常出现的问题：

 

1. 接口定义常见问题

1.1 返回个数不统一

错误代码：

//返回map可读性不好，尽量不要
　＠PostMapping("/delete")
  public Map<String, Object> delete(long id, String lang) {

  }

  // 成功返回boolean，失败返回string，大忌
  ＠PostMapping("/delete")
  public Object delete(long id, String lang) {
    try {
      boolean result = configService.delete(id, local);
      return result;
    } catch (Exception e) {
      log.error(e);
      return e.toString();
    }
  }

通过上面的这段代码，我们可以看出一个最主要的问题：同一接口返回数据类型不统一。这样的话会造成：一、接口的调用者和接口的开发者对接困难（特别是前后端接口）。二、可读性太差——辣眼睛。

    在实际的项目开发中，我们需要同一接口的返回类型，制定合理的返回格式——ResultBean

1.2 没有考虑操作失败的情况

错误代码：

//不返回任何数据，没有考虑失败场景，容易返工
　＠PostMapping("/update")
  public void update(long id, xxx) {

  }

这段代码出现的问题：没有返回值。对于接口的调用者来说，不清楚此操作是否成功。因为接口开发者一开始只考虑了成功的场景，等后面测试发现有错误的情况， 怎么办？？？那就该接口呗，前后台都要改，劳民伤财无用功。

1.3 出现和业务无关的输入参数

错误代码：

// （当前用户删除数据）参数出现lang和userid，尤其是userid，大忌
　＠PostMapping("/delete")
  public Map<String, Object> delete(long id, String lang, String userId) {

  }

这段代码中出现的问题： 接口中的参数中出现了不应该出现的参数 用户信息lang和用户id。特别是用户userId，这是很严重的问题。 这些信息应该从当前会话里面获取。

1.4 出现复杂的输入参数

错误代码：

// 参数出现json格式，可读性不好，代码也难看
　＠PostMapping("/update")
  public Map<String, Object> update(long id, String jsonStr) {

  }

一般情况，不允许在接口参数中出现例如Json字符串这样的参数。一方面是因为可读性极差，另一方面在还要花费一定的篇幅去处理解析这个参数。

1.5 没有返回该返回的数据类型

错误代码：

// 约定俗成，新建应该返回新对象的信息，只返回boolean容易导致返工
　＠PostMapping("/add")
  public boolean add(xxx) {
    //xxx
    return configService.add();
  }

这段代码是“新增”功能的代码。 在我们的项目中，新增一个设备到设备云平台，需要返回新增设备的id。一般新手定义的时候因为前台没有使用就不反悔数据或者只返回true，这都是不允许的。

2. 接口统一格式定义

附上ResultBean，没有任何技术含量

＠Data
public class ResultBean<T> implements Serializable {

  private static final long serialVersionUID = 1L;

  public static final int SUCCESS = 0;

  public static final int FAIL = 1;

  public static final int NO_PERMISSION = 2;

  private String msg = "success";

  private int code = SUCCESS;

  private T data;

  public ResultBean() {
    super();
  }

  public ResultBean(T data) {
    super();
    this.data = data;
  }

  public ResultBean(Throwable e) {
    super();
    this.msg = e.toString();
    this.code = FAIL ;
  }
}

统一的接口规范，能够帮助开发人员规避很多无用的返工修改和可能出现的问题，能够使代码可读性更好。