编程规范定义

任何事情都是有规律可循,同时也有其对应的守则(可理解为规范)。各行各业如此,联系到计算机行业里面的软件开发,也是如此。

参考了《程序员为什么那么累》这篇文章,该文章链接为:https://www.imooc.com/article/27569

针对这篇文章,我再详细的归纳总结,同时也联系到我的实际开发上面。

下面进入正题,谈谈我对编程规范定义的想法和实践。

今天主要就如下几个方面详细说并讲解实践方式和思路。

用思维导图可划分为如下几个方面?
编程规范定义

一、接口定义常见问题

常见问题为如下几个方面?
编程规范定义

1.返回格式统一

目前安卓开发与后台交互方式通常为JSON,微信支付比较特殊使用XML方式。

这个格式不仅仅包含返回数据类型一致,同时也包含对应的格式,示例如下:
编程规范定义

像返回这种格式的数据,如果按照传统的方式的话,可能是这样,用代码表示:

Map returnMap = new HashMap();
returnMap.put("msg":"success"):
......
......

这样一来的话 controller的代码行会增加,同时的话,这是一个非常差的体验

最好的方式是变相一个通用ResultBean

这里我觉得renren-security的可以借鉴:

package io.renren.common.utils;

import java.util.HashMap;
import java.util.Map;

public class R extends HashMap {

private static final long serialVersionUID = 1L;

public R() {
    put("code", 0);
    put("msg", "success");
}

public static R error() {
    return error(500, "未知异常,请联系管理员");
}

public static R error(String msg) {
    return error(500, msg);
}

public static R error(int code, String msg) {
    R r = new R();
    r.put("code", code);
    r.put("msg", msg);
    return r;
}

public static R ok(String msg) {
    R r = new R();
    r.put("msg", msg);
    return r;
}

public static R ok(Map<String, Object> map) {
    R r = new R();
    r.putAll(map);
    return r;
}

public static R ok() {
    return new R();
}

@Override
public R put(String key, Object value) {
    super.put(key, value);
    return this;
}

}

这是通用的ResultBean

放到Controller中,如下所示:
编程规范定义

2.考虑失败情况

在安卓与后台接口交互的时候,总会出现这个或者是那个的突发意外,有些意外处理不好不仅仅会影响系统的运行,同时也会影响用户体验。

例如:

我之前开发的一个智能酒店后台系统,主要是以MVC模式为主的web应用开发,当视图有问题时,总不可能直接给用户报个500吧或者是404那种很不友好的错误界面吧

最好的办法是异常处理,如果是以jsp作为视图层,可以考虑在web.xml配置个全局500或者404。

像安卓对后台接口,如果是服务器端有问题,可以给用户弹出个友好的提示,比如未知异常,请联系管理员等。

还是以renren-security为例

它的异常处理代码如下:

@RestControllerAdvice
public class RRExceptionHandler {

private Logger logger = LoggerFactory.getLogger(getClass());

/**
 * 处理自定义异常
 */
@ExceptionHandler(RRException.class)
public R handleRRException(RRException e){
    R r = new R();
    r.put("code", e.getCode());
    r.put("msg", e.getMessage());

    return r;
}

@ExceptionHandler(DuplicateKeyException.class)
public R handleDuplicateKeyException(DuplicateKeyException e){
    logger.error(e.getMessage(), e);
    return R.error("数据库中已存在该记录");
}

@ExceptionHandler(Exception.class)
public R handleException(Exception e){
    logger.error(e.getMessage(), e);
    return R.error();
}

}

加上数据校验类

public class ValidatorUtils {

private static Validator validator;

static {
    validator = Validation.buildDefaultValidatorFactory().getValidator();
}

/**
 * 校验对象
 * @param object        待校验对象
 * @param groups        待校验的组
 * @throws RRException  校验不通过,则报RRException异常
 */
public static void validateEntity(Object object, Class<?>... groups)
        throws RRException {
    Set<ConstraintViolation<Object>> constraintViolations = validator.validate(object, groups);
    if (!constraintViolations.isEmpty()) {
        ConstraintViolation<Object> constraint = (ConstraintViolation<Object>)constraintViolations.iterator().next();
        throw new RRException(constraint.getMessage());
    }
}

}

/**

  • 数据校验
  • @author chenshun
  • @email sunlightcs@gmail.com
  • @date 2017-03-23 15:50
    */

public abstract class Assert {

public static void isBlank(String str, String message) {
    if (StringUtils.isBlank(str)) {
        throw new RRException(message);
    }
}

public static void isNull(Object object, String message) {
    if (object == null) {
        throw new RRException(message);
    }
}

}

完成上述后,当用户输入不合法时,返回的数据格式和数据类型应该是这样
编程规范定义

这样也充分表明对数据的异常处理

关于Spring的异常处理,可以参考我的这篇文章:https://www.cnblogs.com/youcong/p/9462715.html

3.不要出现与业务无关的输入参数

问题代码如图:
编程规范定义

Hotel是一个实体,一个实体是由很多属性组成的,不说远了,这段代码完成的这个功能仅仅只是需要该实体的五到六个字段,而这个实体有十多个字段,这就显得有些冗余了。

像这段代码就做的比较好:
编程规范定义

它的LoginForm代码也仅仅只是包含所需要的属性,你可以理解LoginForm仅仅只是的dto,负责参数传递,过滤掉无用的参数。

4.不要出现复杂的参数

你可以这样理解?最理想的情况下,是参数列表中的参数一般保持在三个作用,且参数类型相同,如果是参数五个以上(通常,参数列表如果超过三个以上的参数,强烈建议使用对象表示)且参数类型不一致,不仅仅会使得前端方面传递数据和取数据出现异常,而且也会增加复杂性。

一般情况下,参数三个或者三个以下,可以像如下这段代码:
编程规范定义

高于三个以上,直接用dto,即方便有快捷,同时易于维护。

5.返回应该返回的数据

针对这个,确实也没有什么好说的,不过既然说了,还是要说的,特别是安卓与后台这边,最好的情况是根据接口文档上面的安卓那边需要的数据,返回对应的数据,不要多一个或者是少一个,多一个意味着增加数据的传输量,有些时候看似没多大影响,一旦项目用户多了,数据量大了,带宽也大了,你就懂了。当然了,返回应该返回的数据,也是为了规范起见。

二、Controller规范

思维导图归纳如下:
编程规范定义

1.统一返回ResultBean

这个我想在接口规范中已经说了,这里不再赘述,不过有一点要说的是,这个统一返回ResultBean对象,我的确没有做好,以至于目前的代码像前面一样:

编程规范定义

即便可以将返回值改为Object,但是有一点不得不承认的是,还有需要编写JSONObject,最好的办法还是像前面那样R作为返回值,有对应R作为ResultBean统一返回对应的对象。

2.ResultBean不允许往后传

就好像之前我们常用Map接收参数和返回结果集那样,同时兼任两个。看似没问题,实际很大的问题,问题就是职能不明确,可理解为分工不明确,你插手我的,我插手你的。

最好的做法就是你好好做你的,他好好做他的。

3.Controller只做参数传递

同时这里也提到一个要特别注意的问题:

不允许把json,map这类对象传到services去,也不允许services返回json、map

问题代码一(service返回json):
编程规范定义

问题代码二(map居然作为service的接收参数):
编程规范定义

3.参数不允许出现Request,Response 这些对象

问题代码:

编程规范定义

这样看,用request接收参数,导致的可能是可读性差。

怎么解决呢?

还是那句话,三个以下或者等于三个在参数列表中指定,大于三个使用对象作为dto,负责参数传递。

4.关于打印日志

日志在AOP里面会打印,而且我的建议是大部分日志在Services这层打印。

因为业务逻辑也就是service代码,基本上是可以复用的,日志还是在这里打好些。

controller是不能复用的,所以controller那边应该要有其单独的日志打印。

三、AOP实现

思维导图如下:
编程规范定义

1.ResultBean定义

通用的定义无非是响应码、返回信息、实体数据或者集合数据就没有了。

2.区分异常,返回码定义

这个定义不能太细,最好还是200或者500,不然像我现在定义000000、111111、222222等,感觉有太累,这也是因为service当初没有搞好,以及controller嵌套太多导致的。

这个问题,我将在后续解决。

四、日志打印
编程规范定义

思维导图如下:

1.日志要求

(1)能找到机器

如果不知道那台机器,出现问题请问怎么排查?如果是一台两台服务器还好,要是想腾讯阿里那样成千上万台,就算累死都很难排查问题

(2)知道用户在做什么

最好的是当用户操作某些功能时,服务器上面的控制台会打印对应的日志,说明其正在操作某某,比如他正在登陆或者是他正在新增菜单等等

2.开发人员日志

很多时候开发人员在遇到问题时,想办法解决的过程中,浪费了很多时间,包括我自己也一样,就是因为不打印日志或者日志打印一些无关紧要的东西

五、异常处理

思维导图如下:

编程规范定义

异常类型要分清,这里可以借鉴重要且紧急、重要且不紧急、不重要不紧急的这种套路来划分。

特别是对于运维人员来说,对服务器监控是十分必要的,当出现一些问题的苗头时,可以将其扼杀在摇篮中。

六、参数校验和国际化

思维导图如下:
编程规范定义

1.参数校验通用工具类封装调用,可以引用第三库

这里我建议可以使用开源项目hutool

地址为:http://hutool.mydoc.io/

这个地址有关于如何引用和使用的,十分详细。

我个人建议,通用的工具类(特别是开源的,尽量使用一种,而不是你引用这个,我引用那个,如果真的这么做,你会很痛苦的,我联想到开发前端的时候,极不规范的做法,引用这个插件,那个框架,到最后,面临的很严重问题,是该如何维护它。简直是太混乱糟糕透顶了。

所以建议朋友们,工具类统一。

当然了,自己编写也得统一,最好是看引用的第三库能不能实现,如果不能实现再考虑自己写。

2.参数校验不应该放在controller中,应该由service处理

正面示例:
编程规范定义

controller代码如此简洁:
编程规范定义

如此简洁的controller,让人十分喜爱,再看service,换做其他业务代码,我就会很轻松的复用。

再来看反面示例:

service代码(和dao没区别,被称做很low的写法)
编程规范定义

controller代码(全部放在controller处理,代码不简洁,也不利于复用,随着业务的扩展,代码只会越来越多,如果controller如此杂乱,以后新招人来维护,估计人家要么硬着头皮忍着,要么第二天不来了):

编程规范定义

七、函数编写建议

思维导图如下:
编程规范定义

引用我的哥哥对我说的那两句话:

1.一个函数只办一件事;

2.某段代码块需要多处引用,可考虑将其封装调用;

这两句话可以回答上面的部分问题

不过需要补充的是,正如小时候看武打片那样,特别是用剑的高手,真正的高手是不需要剑的,正如软件开发工程师,代码的可读性并不是靠注释,而是本身代码就已经告诉人家它是做什么的。

尽管目前我还不能做到这些,但是我一直也在努力的做。

编写能测试的函数,在此我之前在一篇关于单元测试的重要性重已经说明了,但是今天看来还不够全面。最全面的就是,编写的测试函数,短而精悍,可单独测试。

八、应对需求变更

思维导图如下:
编程规范定义

1.把代码写到最简单

其实往往复杂的东西就是最简单的

像前面说的那样,其实controller里面的好几个,其实不必冗长,短而精即可。

2.把可能变化的封装成函数

这个需要思考,每次在编写代码的时候,要想,这段代码是否会在其他地方引用,如果引用的话,复制过来复制过去,影响可读性,同时也很冗余,这就需要考虑封装成一个函数调用。

3.解耦

解耦是编程里面重要的思想,解耦的关键在于:多引入“第三者”,不要直接发生关系

“高内聚,低耦合”的程序,是每个程序员的追求,如何写一手优雅的代码,关键在于此。

如何解耦呢?

观察者模式可以借鉴

或者可以联系到模块设计方面

如何隔离app应用和后台应用

如何确保改这段代码不会影响那段代码

看看人人开源的这个
编程规范定义

admin和api是独立的

common作为工具类是可以复用的

generator作为代码生成器也是隔离的

4.数据结构要考虑扩展

关于数据结构方面,后期我会专门讲的,同时也包含算法

九、配置规范
编程规范定义

上一篇:tomcat 加载 war包


下一篇:4000 字面试心经,教你如何打动支付宝面试官