java架构篇之请求参数格式的规范化（架构师入门 初学）

注意：我现在所讲的内容针对于rest风格的接口服务（请求值和返回值数据都为json）

首先声明一下架构观点：

规范性的公共类：必须封装，必须使用

便利性的公共类：谨慎封装，可用可不用

在讲述完此节内容后，会对以上观点进一步说明，相信有更深的感悟

参数规范化

首先说明下在开发中遇到的一些问题，在查询分页参数的时候，可能会看到这样的两份代码

张三写的代码：

  /**
   * 分页查询用户列表
   * @param pageIndex 页码
   * @param pageSize 每页显示数量
   * @return 分页后的数据（示例用）
   */
  public List<Data> queryPagedUserList(Integer pageIndex,Integer pageSize){
    //查询结果并返回
  }

李四写的代码：

 /**
   * 分页查询消息列表
   * @param currentPage 页码
   * @param count 每页显示数量
   * @return 分页后的数据（示例用）
   */
  public List<Data> getMessageList(Integer currentPage,Integer count){
    //查询结果并返回
  }

仔细对照一下，发现相同的参数含义，两个人写出不完全不同的参数名。

张三： 页码 pageIndex 分页大小pageSize

李四： 页码 currentPage 分页大小count

前端在调用这两个接口的时候，需要根据不同接口选择不同的参数名，如果不在这方面规范一下，会对前端造成很多困扰，不同的页面用不同参数名字，即使他们的含义一样。

怎么解决这种由于不同人开发造成的命名不规范的问题呢

现在有很多项目，以书面的方式，开会说明参数的命名规范。当后面有新人加入项目后，可能由于讲解不到位，又会出现自己命名的情况（我就遇到过这种情况）

下面讲的这种方式，叫强制规范化，也就是说你只能这样命名。

首先分析下前端提交的参数类型：

（1）接口私有查询参数：和接口业务相关的参数，比如查询用户列表有用户名，查询消息列表有消息日期

（2）数据列表参数：这种参数一般是用来批量保存数据的，比如说你想批量新增员工，这个参数就是一个list类型的数据

（3）接口私有查询参数 + 分页排序参数：这种参数在后台管理系统用的非常多，规定数据表格按照什么字段排序，怎么进行分页，以什么条件进行查询

以上面参数分析为参照，我们有了这样一种类图

下面解释我大量应用了泛型，对泛型不明白的小伙伴要补补泛型的知识了

BaseRequest定义

public class BaseRequest implements Serializable{
}

可以看到里面内容是空的，只是实现了Serializable接口，这个接口本身是个空接口，仅仅表明这个类可以通过序列化在网络上传输，在某些框架上必须要求传输的Bean实现Serializable接口。

另外：通过让所有参数继承BaseRequest的方式，可以全局添加请求参数

（1）第一种参数类型（只包含接口私有参数）

@Data
public class Request<T extends Serializable> extends BaseRequest{
    
    private T param;
}

注：@Data是Lombok注解，lombok主要用来给bean自动生成set/get方法。lombok的详尽用法请参照资料。

可以看到，我定义了一个泛型，并继承了BaseRequest，到这里你可能不太明白，这个到底怎么用，下面给出使用示例

  public List<Data> getMessageList(@RequestBody Request<String> request){
    String param = request.getParam();
    //查询结果并返回
  }

前端对应的参数为

注：@RequestBody作用是将前台传过来的json转为Bean，前提是框架配置好

这里可以看到我放了一个String类型的参数进去了，表明这个接口接受的参数类型是String，当前端传递了一个带param字段的json对象过来后，后台转换成Bean，赋值到Request的param字段上。

当需要传递多个参数的时候怎么办呢，这时候我们就需要一个bean了，比如这样

@Data
public class ClientLoginParam implements Serializable{
  private String username;
  private String password;
}

然后接口定义这么写

  public List<Data> getMessageList(@RequestBody RestRequest<ClientLoginParam> request){

  ClientLoginParam = request.getParam();

}

前端对应的参数

当然，接口私有参数可以定义一个全局的BaseParam参数

public class BaseParam implements Serializable{

}

public class ClientLoginParam extends BaseParam //后面省略

（2）第二种参数类型：数据列表参数

@Data
public class ListRequest<T extends Serializable> extends BaseRequest{
    private List<T> params;
}

本质上和是Request用法是一样的，只不过param类型变成了List<T>，用法上这么用

  public List<Data> getMessageList(@RequestBody ListRequest<ClientLoginParam> request){
    List<ClientLoginParam> param = request.getParams();
    //查询结果并返回
  }

（3）接口私有查询参数 + 分页排序参数（这个是重点）

@Data
public class PageRequest<T extends Serializable> extends BaseRequest{
    //分页参数
    private PageParam pageParam;
    //排序参数
    private List<SortParam> sortParams;
    //接口私有查询参数
    private T param;
}

@Data
public class PageParam extends BaseParam {
    //当前页
    private int currentPage;
    //每页显示大小
    private int pageSize;
    //是否分页
    private boolean paging;
}

@Data
public class SortParam extends BaseParam{
    //排序字段
    private String fieldName;
    //排序类型
    private String orderType;
}

然后对应的前端参数示例

后台对应的读参数方法示例

  public List<Data> getMessageList(@RequestBody PageRequest<ClientLoginParam> request){
    //获取接口自定义查询参数
    ClientLoginParam param = request.getParam();
    //获取分页参数
    PageParam pageParam = request.getPageParam();
    //获取排序参数
    List<SortParam> sortParamList = request.sortParams();
    //查询结果并返回
  }

这里可以看到，通过Bean定义的方式，确定了前台的参数格式和参数名称（配合swagger可以自动生成接口文档，后面的java架构篇会讲解）

这里有一个很重要的地方要注意，不能用Map接收参数

并不是这种方法不能实现功能，是因为这种方式给维护代码带来很大的不方便性，必须运行时才能确定有哪些参数传递过来了，并不能像Bean定义这种方式，通过浏览代码就知道接口主要接收哪些参数。

针对文章刚开始提到的架构观点

规范性的公共类：必须封装，必须使用

如果在写接口的时候，都使用了，基于以上说明的参数类。那么前端提交的参数格式会非常统一，可维护性大大提高，再也不会出现相同含义的公共参数名称不同的问题。提高了代码的整体质量。这就是规范性的东西一定要封装和使用的原因。