1.代码规范概要

淩亂°似流年 2022-05-30 09:28 183阅读 0赞

主要[参考博客][Link 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，一定要打印值，因为他决定了代码走那个分支。

**![v2-2705c4781c19af2de2a7d8f392d82cdc_hd.jpg][]**

(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);  
\}  
再后面，复制属性的时候需要保留某些字段或者过滤掉某些字段，我们自己参考其他库实现一次即可，只改动价格和测试一个文件一个方法，风险非常可控。

未完

**       微信公众号： **

![20180403143416927][]

JAVA程序猿成长之路

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

[Link 1]: https://zhuanlan.zhihu.com/c_120823325
[v2-2705c4781c19af2de2a7d8f392d82cdc_hd.jpg]: /images/20220530/a55a02f913794f708c925882161d6d86.png
[20180403143416927]: /images/20220530/4baf12a0e6ae49aba306b7a27067bb4f.png