1.代码规范概要

主要参考博客加上自己的简介，纯属个人简介。

 

在我们平常的开发中良好的代码规范，对项目的进展会起到事半功倍的效果。所以项目的开发必须设计好的代码规范，其主要会设计到以下：

（1）接口定义规范（2）controller规范（3）日志规范（4）异常处理规范（5）国际化规范（6）参数校验规范（7）工具类规范（8）函数编写建议（9）配置建议

1.接口定义规范

工作中，少不了要定义各种接口，系统集成要定义接口，前后台掉调用也要定义接口。接口定义一定程度上能反应程序员的编程功底。列举一下工作中我发现大家容易出现的问题：
（1）. 返回格式不统一
同一个接口，有时候返回数组，有时候返回单个；成功的时候返回对象，失败的时候返回错误信息字符串。工作中有的系统集成就是这样定义的接口，真是辣眼睛。这个对应代码上，返回的类型是map，json，object，都是不应该的。实际工作中，我应该定义一个统一的格式，就是ResultBean，分页的有另外一个PageResultBean

错误范例：

//返回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();
    }

 

  }

（2）. 没有考虑失败情况
 一开始只考虑成功场景，等后面测试发现有错误情况，怎么办，改接口，前后台都改，劳民伤财无用功。
 错误范例：
 //不返回任何数据，没有考虑失败场景，容易返工
 ＠PostMapping("/update")

  public void update(long id, xxx) {

  }

（3）. 出现和业务无关的输入参数
如lang语言，当前用户信息 都不应该出现参数里面，应该从当前会话里面获取。后面讲ThreadLocal会说到怎么样去掉。除了代码可读性不好问题外，尤其是参数出现当前用户信息的，这是个严重问题。
错误范例：
 // （当前用户删除数据）参数出现lang和userid，尤其是userid，大忌
＠PostMapping("/delete")
  public Map<String, Object> delete(long id, String lang, String userId) {

 }

（4）. 出现复杂的输入参数

一般情况下，不允许出现例如json字符串这样的参数，这种参数可读性极差。应该定义对应的bean。
错误范例：
 // 参数出现json格式，可读性不好，代码也难看
 ＠PostMapping("/update")

 public Map<String, Object> update(long id, String jsonStr) {

  }

（5）. 没有返回应该返回的数据
例如，新增接口一般情况下应该返回新对象的id标识，这需要编程经验。新手定义的时候因为前台没有用就不返回数据或者只返回true，这都是不恰当的。别人要不要是别人的事情，你该返回的还是应该返回。
错误范例：
// 约定俗成，新建应该返回新对象的信息，只返回boolean容易导致返工
＠PostMapping("/add")
  public boolean add(xxx) {
   //xxx
  return configService.add();

  }

2.controller规范

主要的内容就是接口定义里面的内容，你只要遵循里面的规范，controller就问题不大，除了这些，还有另外的几点：
首先思考controller无非就是两个作用 （1）返回请求的页面 （2）返回请求后处理的数据
（1）.对于所有的异步查询，函数返回统一的ResultBean/PageResultBean格式。没有统一格式，AOP无法玩。
  example：
   @RequestMapping("list");
  @ResponseBody
  public  PageResultBean<User>  toList(ModelMap map){ 
   //查询后台
   PageResultBean<User> result=userService.findAll();
   return result;   

  }

2.对于返回返回String类型的页面类请求
example:

/**返回数据渲染 list页面

*/

 

 @RequestMapping("list");
   public  String  toList(ModelMap map){
   //查询后台
  PageResultBean<User> map=userService.findAll();
  map.put("pageResultBean",map);
  return list;  

 

 }

(3).ResultBean/PageResultBean是controller专用的，不允许往后传,如果需要传递查询参数重新定义查询对象，这里可以定义查询对象继承实体对象，
然后添加没有的查询字段,如pageSize,mysql分页查询的starRows从多少行开始查询！
(4).Controller做参数格式的转换，不允许把json，map这类对象传到services去，也不允许services返回json、map。
一般情况下！写过代码都知道，map，json这种格式灵活，但是可读性差，如果放业务数据，每次阅读起来都比较困难。
同3解决办法，定义一个bean看着工作量多了，但代码清晰多了。
(5).参数中一般情况不允许出现Request，Response这些对象主要是可读性问题。一般情况下。
(6).不需要打印日志日志在AOP里面会打印，而且我的建议是大部分日志在Services这层打印。

(7).使用 AOP 统一处理异常，并根据不同异常返回不同返回码。尤其关注非用户自己抛出的异常

3.日志规范

(1). 修改（包括新增）操作必须打印日志

 大部分问题都是修改导致的。数据修改必须有据可查。

(2). 条件分支必须打印条件值，重要参数必须打印
尤其是分支条件的参数，打印后就不用分析和猜测走那个分支了，很重要！如下面代码里面的userType，一定要打印值，因为他决定了代码走那个分支。

 

(3).数据量大的时候需要打印数据量，查询时间

前后打印日志和最后的数据量，主要用于分析性能，能从日志中知道查询了多少数据用了多久。这点是建议。自己视情况而决定是否打印。

这个可以使用aop的环绕通知。

4.工具类概要

隐藏实现
就是要定义自己的工具类，尽量不要在业务代码里面直接调用第三方的工具类。这也是解耦的一种体现。如果我们不定义自己的工具类而是直接使用第三方的工具类有2个不好的地方：
 a. 不同的人会使用不同的第三方工具库，会比较乱。

 b.将来万一要修改工具类的实现逻辑会很痛苦。

explame:

以最简单的字符串判空为例，很多工具库都有 StringUtils工具类，如果我们使用commons的工具类，一开始我们直接使用 StringUtils.isEmpty ，字符串为空或者空串的时候会返回为true，后面业务改动，需要改成如果全部是空格的时候也会返回true，怎么办？我们可以改成使用 StringUtils.isBlank 。看上去很简单，对吧？ 如果你有几十个文件都调用了，那我们要改几十个文件，是不是有点恶心？再后面发现，不只是英文空格，如果是全角的空格，也要返回为true，怎么办？StringUtils上的方法已经不能满足我们的需求了，真不好改了。。。
所以我的建议是，一开始就自己定义一个自己项目的StringUtil，里面如果不想自己写实现，可以直接调用commons的方法，如下：
public static boolean isEmpty(String str) {
  return org.apache.commons.lang3.StringUtils.isEmpty(str);
}

后面全部空格也返回true的时候，我们只需要把isEmpty改成isBlank；再后面全部全角空格的时候也返回true的话，我们增加自己的逻辑即可。我们只需要改动和测试一个地方。

explame:

如复制对象的属性方法。一开始，如果我们自己不定义工具类方法，那么我们可以使用 org.springframework.beans.BeanUtils.copyProperties(source, dest) 这个工具类来实现，就一行代码，和调用自己的工具类没有什么区别。看上去很OK，对吧？

随着业务发展，我们发现这个方式的性能或者某些特性不符合我们要求，我们需要修改改成 commons-beanutils包里面的方法，org.apache.commons.beanutils.BeanUtils.copyProperties(dest, source)，这个时候问题来了，第一个问题，它的方法的参数顺序和之前spring的工具类是相反的，改起来非常容易出错！第二个问题，这个方法有异常抛出，必须声明，这个改起来可要命了！结果你发现，一个看上去很小的改动，改了几十个文件，每个改动还得测试一次，风险不是那么得小。有一点小奔溃了，是不是？

 

等你改完之后测试完了，突然有一天需要改成，复制参数的时候，有些特殊字段需要保留（如对象id）或者需要过滤掉（如密码）不复制，怎么办？这个时候我估计你要崩溃了吧？不要觉得我是凭空想象，编程活久见，你总会遇到的一天！

所以，我们需要定义自己的工具类函数，一开始我定义成这样子。

public void copyAttribute(Object source, Object dest) {
  org.springframework.beans.BeanUtils.copyProperties(source, dest);
}
后面需要修改为commons-beanutis的时候，我们改成这样即可，把参数顺序掉过来，然后处理了一下异常，我使用的是Lombok的SneakyThrows来处理异常，你也可以捕获掉抛出运行时异常，个人喜好。
@SneakyThrows
public void copyAttribute(Object source, Object dest) {
  org.apache.commons.beanutils.BeanUtils.copyProperties(dest, source);
}
再后面，复制属性的时候需要保留某些字段或者过滤掉某些字段，我们自己参考其他库实现一次即可，只改动价格和测试一个文件一个方法，风险非常可控。

未完

                                                                       微信公众号： 

                                               

                                                                             JAVA程序猿成长之路

                          分享资源，记录程序猿成长点滴。专注于Java,Spring,SpringBoot,SpringCloud，分布式，微服务。