Java教程

java开发手册 - 码出规范 - 要点整理

本文主要是介绍java开发手册 - 码出规范 - 要点整理,对大家解决编程问题具有一定的参考价值,需要的程序猿们随着小编来一起学习吧!

文章目录

    • 编程规约
        • 命名风格
        • 常量定义
        • 代码格式
        • OOP规约
        • 集合处理
        • 并发处理
        • 控制语句
        • 注释规约
        • 其他
    • 异常日志
        • 异常处理
        • 日志规约
    • 单元测试
    • 安全规约
    • Mysql数据库规范
        • 索引规约
        • SQL语句
        • ORM映射
    • 工程结构
        • 应用分层
        • 二方库依赖
        • 服务器
    • 设计规约

编程规约

命名风格

  1. 代码的命名不能以下划线或美元符号,也不能以下划线或美元符号结束

  2. 代码的命名禁止使用中文拼音和英文混用的形式,更不允许直接使用中文的方式,纯中文拼音的方式尽量避免采用,使用英文命名。注:国际通用拼音可以使用,如renminbi,alibaba

  3. 类名应当使用UpperCamelCase的形式,也就是首字母大写驼峰命名的形式。

  4. 方法名、参数名、成员变量、局部变量同意使用lowerCamelCase风格,必须遵循驼峰的形式

  5. 常量命名全部大写,单词之间用下划线隔开,力求语意表达请求,不要嫌名字长。正例:MAX_STOCK_COUNT 反例:MAX_COUNT

  6. 抽象类命名使用Abstract或Base开头;异常类命名使用Exception结尾;测试类命名以他要测试的类的名称开始,以Test结尾

  7. 类型与中括号紧挨相连表示数组;如 int[] array, 反例: String args[]

  8. POJO类中的布尔类型变量都不要加is前缀,否则部分框架解析会引起序列化错误。在Mysql规约中的建表约定第一条,表达与是否的值采用is_xxx的命名方式,所以需要在设置is_xxx到xxx的映射关系

  9. 包名统一使用小写,点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式。如工具类包名为com.alibaba.ai.util、类名为MessageUtils

  10. 避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名,使可读性降低。

    public class ConfusingName { public int age;
    // 非 setter/getter 的参数名称,不允许与本类成员变量同名
    public void getData(String alibaba) { if(condition) {
    final int money = 531;
    // ...
    }
    for (int i = 0; i < 10; i++) {
    // 在同一方法体中,不允许与其它代码块中的 money 命名相同 final int money = 615;
    // ...
    } }
    }
    class Son extends ConfusingName {
    // 不允许与父类的成员变量名称相同 public int age;
    }
    
  11. 杜绝完全不规范的缩写,避免望文不知意。

  12. 为了达到代码自解释的目标,任何自定义编程元素在命名时,尽量使用完整的单词组合来表达其意。

  13. 在常量与变量的命名时,表示类型的名称放在词尾,以提升辨识度。

    正例:startTime / workQueue / nameList / TERMINATED_THREAD_COUNT

    反例:startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD

  14. 如果模块、接口、类、方法使用了设计模式,在命名时需要体现出具体的模式。比如OrderFactory,LoginProxy等。

  15. 接口类中的方法和属性不要加任何修饰符号(public也不要加),保持代码的简洁性,并加上有效的javadoc注释。尽量不要在接口里定义变量,如果一定要定义变量,肯定是与接口方法相关,并且是整个应用的基础常量

  16. 接口和实现类的命名有两套规则:

    1. 对于Service和DAO类,基于SOA的理念,暴露出来的服务一定是接口,内部的实现类用Impl的后缀与接口区别。
    2. 如果是形容能力的接口名称,取对应的形容词为接口名(通常为-able)。如AbstractTranslator实现Translatable。
  17. 枚举类名带上Enum后缀,枚举成员名称需要全大写,单词见用下划线隔开。

  18. 各层命名规约

    1. Service/DAO层方法命名规范

      1. 获取单个对象的方法用get做前缀。
      2. 获取多个对象的方法用list做前缀,复数形式结尾如:listObjects
      3. 获取统计值的方法用count做前缀
      4. 插入的方法用save/insert做前缀
      5. 删除的方法用remove/delete做前缀
      6. 修改的方法用update做前缀

      (个人定义:以最基本的mvc为基础,Controller引用Service,Service调用Repository,Repository调用DAO,Service中定义的应该是对某个业务服务实体的各种调用操作,如ActorService,对主播的各种操作,可能涉及多个Repository的操作,毕竟主播不可能只有一个关联表。Repository与DAO相对应,DAO与表sql相对应,Repository的作用就是对允许进出DAO查询的BO实体与DO实体进行转换,不要将数据库的表结构暴露到Service层中,仅转换成需要的数据返回即可。DAO层定义db的查询方式。进入查询的BO实体需要注意表查询的索引,尽量走索引,再转成DO进入查询。)

    2. 领域模型命名规约

      1. 数据对象:xxxDO,xxx为数据表名。(个人感觉这个用PO指代也可以)
      2. 数据传输对象:xxxDTO,xxx为业务领域相关的名称。
      3. 展示对象:xxxVO,xxx一般为网页名称
      4. 业务对象:xxxBO,xxx一般为业务对象名称
      5. POJO是DO/DTO/BO/VO的统称,禁止命名成xxxPOJO

常量定义

  1. 不允许任何**魔法值(即未经预先定义的常量)**直接出现在代码中。

    String key = "Id#taobao_" + tradeId;
    cache.put(key, value);
    // 缓存 get 时,由于在代码复制时,漏掉下划线,导致缓存击穿而出现问题
    
  2. 在long或者Long赋值时,数值后使用大写的L,不能是小写的l,小写容易跟数字1混淆,造成误解。

  3. 不要使用一个常量类群维护所有常量, 要按常量功能进行归类,分开维护。如缓存相关的常量放在CacheConsts中,系统配置相关常量放在ConfigConsts中。

  4. 常量的复用层次有5层:跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。

    1. 跨应用共享常量:放置在二方库中,通常是client.jar中的constant目录下。
    2. 应用内共享常量:放置在一方库中,通常是子模块中的constant目录下。
    3. 子工程内部共享常量:即在当前子工程的constant目录下。
    4. 包内共享常量:即在当前包下单独的constant目录下。
    5. 类内共享常量:直接在类内部 private static final 定义
  5. 如果一个变量值仅在一个固定范围内变化用enum类型来定义

    public enum SeasonEnum {
    SPRING(1), SUMMER(2), AUTUMN(3), WINTER(4);
    private int seq; SeasonEnum(int seq) {
    this.seq = seq; }
    public int getSeq() { return seq;
    } }
    

代码格式

  1. 如果是大括号内为空,则写成{}即可,大括号中间无需换行和空格;如果是非空则左大括号前不换行,左大括号后换行,右大括号前换行,右大括号后还有else等代码则不换行,如果表示终止则必须换行。
  2. 左小括号和字符之间不出现空格;同样,右小括号和字符之间也不出现空格;而左 大括号前需要空格。详见第 5 条下方正例提示。
    正例:if空格 (a == b)空格
  3. if/for/while/switch/do等保留字与括号之间都必须加空格
  4. 任何二目、三目运算符的左右两边都需要加一个空格。
  5. 采用四个空格缩进,如果使用tab字符缩进,那必须设置4个空格。
  6. 注释的双斜线与注释内容之间有且仅有一个空格
  7. 在进行类型强制转换时,左括号与强制转换值之间不需要有任何空格隔开
  8. 单行字符数限制不超过120个,超出需要换行,换行时遵循如下原则:
    1. 第二行相对第一行缩进4个空格,从第三行开始,不需要继续缩进
    2. 运算符与下文一起换行
    3. 方法调用的点符号与下文一起换行
    4. 方法调用中的多个参数需要换行时,在逗号后进行
    5. 在括号前不要换行
  9. 方法参数在定义和传入时,多个参数逗号后面必须加空格
  10. IDE的text file encoding 设置为UTF-8;IDE中文件的换行符使用Unix格式,不要使用windows格式
  11. 单个方法的总行数不要超过80行。分清个性与共性
  12. 没有必要增加若干空格来使得变量的赋值等号与上一行对应位置的等号对齐。
  13. 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。

OOP规约

  1. 避免通过一个类的对象引用访问此类的静态变量或静态方法,无谓增加编译器解析成本,直接用类名来访问即可。

  2. 所有覆盖的方法,必须加@Override注解

  3. 相同参数类型,相同业务含义,才可以使用java的可变参数,避免使用Object,在业务上尽量避免使用Object可变参数

  4. 外部正在调用或者二方库依赖的接口,不被允许修改方法签名,避免对接口调用方产生影响。接口过时必须加@Deprecated注解,并清晰地说明采用的新接口或者新服务是什么。

  5. 不能使用过时的类或方法(过时的方法如果标注最好经过大家的一致同意,不要个人进行标注)

  6. Object的equals方法容易抛空指针异常,应使用常量或者确定有值的对象来调用equals。

  7. 所有整型包装类对象之间的值比较,全部使用equals方法比较。

  8. 浮点数之间的等值判断,基本数据类型不能用==来比较,包装类型不能用equals来判断。

  9. 定义数据对象DO类时,属性类型要与数据库字段类型相匹配。

  10. 为了防止精度损失,禁止使用构造方法BigDecimal(double)的方式把double值转为BigDecimal对象。

  11. 关于基本数据类型与包装数据类型的使用标准如下:

    1. 所有的POJO类都必须使用包装数据类型
    2. RPC方法的返回值和参数必须使用包装数据类型
    3. 所有的局部变量使用基本数据类型
  12. 定义DO/DTO/VO等POJO类时,不要设定任何初始值。

  13. 序列化类新增属性时,不要修改serialVersionUID字段,避免反序列化失败;如果 完全不兼容升级,避免反序列化混乱,那么请修改 serialVersionUID 值。

  14. 构造方法里面禁止加入任何业务逻辑,如果有初始化逻辑,请放在 init 方法中。

  15. POJO 类必须写 toString 方法。使用 IDE 中的工具:source> generate toString 时,如果继承了另一个 POJO 类,注意在前面加一下 super.toString。

  16. 禁止在POJO类中,同时存在对应属性xxx的isXxx()和getXxx()方法。

  17. 使用索引访问用 String 的 split 方法得到的数组时,需做最后一个分隔符后有无内容的检查,否则会有抛 IndexOutOfBoundsException 的风险。

  18. 当一个类有多个构造方法,或者多个同名方法,这些方法应该按顺序放置在一起, 便于阅读,此条规则优先于下一条

  19. 类内方法定义的顺序依次是:公有方法或保护方法 > 私有方法 > getter / setter 方法。

  20. setter 方法中,参数名称与类成员变量名称一致,this.成员名 = 参数名。在

    getter/setter 方法中,不要增加业务逻辑,增加排查问题的难度。

  21. 循环体内,字符串的连接方式,使用 StringBuilder 的 append 方法进行扩展。

  22. final 可以声明类、成员变量、方法、以及本地变量,下列情况使用 final 关键字:

    1. 不允许被继承的类,如:String 类。
    2. 不允许修改引用的域对象。
    3. 不允许被覆写的方法,如:POJO 类的 setter 方法。
    4. 不允许运行过程中重新赋值的局部变量。
    5. 避免上下文重复使用一个变量,使用 final 可以强制重新定义一个变量,方便更好地进行重构。
  23. 慎用 Object 的 clone 方法来拷贝对象。

  24. 类成员与方法访问控制从严:

    1. 如果不允许外部直接通过 new 来创建对象,那么构造方法必须是 private。
    2. 工具类不允许有 public 或 default 构造方法。
    3. 类非 static 成员变量并且与子类共享,必须是 protected。
    4. 类非 static 成员变量并且仅在本类使用,必须是 private。
    5. 类 static 成员变量如果仅在本类使用,必须是 private。
    6. 若是 static 成员变量,考虑是否为 final。
    7. 类成员方法只供类内部调用,必须是 private。
    8. 类成员方法只对继承类公开,那么限制为 protected。

集合处理

  1. 关于hashCode和equals的处理,遵循如下规则:

    1. 只要覆盖equals,就必须覆盖hashCode
    2. 因为Set存储的是不重复的对象,依据hashCode和equals进行判断,所以Set存储的对象必须覆写这两个方法
    3. 如果自定义对象作为Map的键,那么必须覆写hashCode和equals
  2. ArrayList的subList结果不可强转成ArrayList,否则会抛出ClassCast Exception

  3. 是哟哦给Map的方法keySet()/values()/entrySet()返回集合对象时,不可以对其进行添加元素操作,否则会抛出UnsupportedOperationException异常。

  4. Collections类返回的对象,如:emptyList()/singletonList()等都是immutablelist,不可对其进行添加或者删除元素的操作

  5. 在subList场景中,高度注意对原集合元素的增加或删除,均会导致子列表的遍 历、增加、删除产生 ConcurrentModificationException 异常。

  6. 使用集合转数组的方法,必须使用集合的toArray(T[] array),传入的是类型完全一样,长度为0的空数组

    List<String> list = new ArrayList<>(2); list.add("guan");
    list.add("bao");
    String[] array = list.toArray(new String[0]);
    
  7. 在使用Colletion接口任何实现类的addAll()方法时,都要对输入的集合参数进行NPE判断。不然会抛出空指针异常。

  8. 使用工具类Arrays.asList()把数组转换成集合时,不能使用其修改集合相关的方 法,它的 add/remove/clear 方法会抛出 UnsupportedOperationException 异常。

    1. asList 的返回对象是一个 Arrays 内部类,并没有实现集合的修改方法。Arrays.asList 体现的是适 配器模式,只是转换接口,后台的数据仍是数组。
  9. 泛型通配符<? extends T>来接收返回的数据,此写法的泛型集合不能使用add方 法,而<? super T>不能使用 get 方法,作为接口调用赋值时易出错。
    说明:扩展说一下 PECS(Producer Extends Consumer Super)原则:第一、频繁往外读取内容的,适合 用<? extends T>。第二、经常往里插入的,适合用<? super T>

  10. 在无泛型限制定义的集合赋值给泛型限制的集合时,在使用集合元素时, 需要进行instanceof判断,避免出现classCastException异常。

  11. 不要在foreach循环里进行元素的remove/add操作。remove元素请使用Iterator的方式,如果并发操作,需要对Iterator对象加锁

  12. 在 JDK7 版本及以上,Comparator 实现类要满足如下三个条件,不然 Arrays.sort, Collections.sort 会抛 IllegalArgumentException 异常。

    1. x,y 的比较结果和 y,x 的比较结果相反。
    2. x>y,y>z,则 x>z。
    3. x=y,则 x,z 比较结果和 y,z 比较结果相同。
  13. 集合泛型定义时,在 JDK7 及以上,使用 diamond 语法或全省略。菱形泛型,即diamond,直接使用<>来指代前边已经指定的类型

  14. 集合初始化时,指定集合初始值大小

  15. 使用entrySet遍历Map类集合KV,而不是keySet方式进行遍历。说明:keySet其实遍历了2次,一次是转为Iterator对象,另一次是从hashMap中取出key所对应的value。而entrySet知识遍历了一次就把key和value都放在了entry中,效率更高。如果是jdk8,使用Map.forEach方法

  16. 高度注意Map类集合K/V能不能存储null值的情况。

  17. 合理利用好集合的有序性(sort)和稳定性(order),避免集合的无序性(unsort)和不稳定性(unorder)带来的负面影响。

  18. 利用Set元素唯一的特性,可以快速对一个集合进行去重操作,避免使用List的contains方法进行遍历、对比、去重操作。

并发处理

  1. 获取单例对象需要保证线程安全,其中的方法也要保证线程安全

  2. 创建线程或线程池时请指定有意义的线程名称,方便出错时回溯

  3. 线程资源必须必须通过线程池提供,不允许在应用中自行显式创建线程

  4. 线程池不允许使用Executors去创建,而是通过ThreadPoolExecutor的方式,这样的处理方式让写的同学能够更加明确线程池的运行规则,规避资源耗尽的风险。

    1. FixedThreadPool和SingleThreadPool允许的请求队列的长度为MAX,可能会堆积大量的请求,从而导致OOM
    2. CacheThreadPool允许创建的线程数为MAX,可能会创建大量的线程,从而导致OOM
  5. SimpleDateFormat 是线程不安全的类,一般不要定义为static变量,如果定义为static,必须加锁,或者使用DateUtils工具类。

    注意线程安全,使用 DateUtils。亦推荐如下处理:
    private static final ThreadLocal<DateFormat> df = new ThreadLocal<DateFormat>() { @Override
    protected DateFormat initialValue() {
    return new SimpleDateFormat("yyyy-MM-dd");
    } };
    说明:如果是 JDK8 的应用,可以使用 Instant 代替 Date,LocalDateTime 代替 Calendar, DateTimeFormatter 代替 SimpleDateFormat,官方给出的解释:simple beautiful strong immutable thread-safe。
    
  6. 必须回收自定义的ThreadLocal变量,尤其在线程池场景下,线程经常会被复用,如果不清理自定义的ThreadLocal变量,可能会影响后续业务逻辑和造成内存泄漏等问题。尽量在代理中使用try-finally块进行回收。

    //一般在多方法间传输局部变量时可以用线程的ThreadLocal进行保存,但是使用完毕后要进行删除
    objectThreadLocal.set(userInfo); try {
    // ...
    } finally { 
      objectThreadLocal.remove();
    }
    
  7. 高并发时,同步调用应该去考量锁的性能损耗。能用无锁数据结构,就不要用锁;能锁住区块,就不要锁住整个方法体;能用对象锁,就不要用类锁。

  8. 对多个资源、数据库表、对象同时加锁时,需要保持一致的加锁顺序,否则可能会造成死锁。说明:线程一需要对三个资源ABC依次加锁后才可以进行更新操作,那么线程二的加锁顺序也必须是ABC,否则可能会出现死锁

  9. 在使用阻塞等待获取锁的方式中,必须在try代码块之外,并且在加锁方法与try代 码块之间没有任何可能抛出异常的方法调用,避免加锁成功后,在 finally 中无法解锁。 lock在try之中,如果异常,那么finally解锁时会调用AQS的tryRelease出现异常

  10. 在使用尝试机制来获取锁的方式中,进入业务代码块之前,必须先判断当前线程是否持有锁。锁的释放规则与锁的阻塞等待方式相同。在进行使用前先判断是否已经加锁tryLock(),不然在释放锁的时候会出现异常

  11. 并发修改同一记录时,避免更新丢失,需要加锁。要么在应用层加锁,要么在缓存加锁,要么在数据库层使用乐观锁,使用version作为更新依据。mysql的乐观锁:通过version记录版本号,在修改记录前先select version,通过update的where条件进行判断version,修改后使version + 1,由于update执行阶段的语句是不可分割的,以此保证了乐观锁。如果是for update 则是悲观锁了。一般的事务都是按公司级定义隔离级别,对应查询时的隔离等级,对修改的情况一般需要自己加锁

  12. (暂不知)多线程并行处理定时任务时,Timer运行多个TimeTask时,只要其中之一没有捕获抛出的异常,其他任务便会自动终止运行,如果在处理定时任务时使用ScheduledExecutorService则没有这个问题

  13. 资金相关的金融敏感信息,使用悲观锁策略;

    乐观锁在获得锁的同时已经完成了更新操作,校验逻辑容易出现漏洞,另外,乐观锁对冲突的解决策略有较复杂的要求,处理不当容易造成系统压力或数据异常,所以资金相关的金融敏感信息不建议使用乐观锁更新
    
  14. 使用CountDownLatch进行异步转同步操作,每个线程退出前必须调用countDown方法,线程执行代码注意catch异常,确保countDown方法被执行到,避免主线程无法执行至await方法,直到超时才返回结果。

  15. 避免Random实例被多线程使用,虽然共享该实例是线程安全的,但会因竞争同一seed导致的性能下降。Random实例包括java.util.Random 的实例或者Math.random()的方式,在 JDK7 之后,可以直接使用 API ThreadLocalRandom,而在 JDK7 之前,需要编码保证每个线 程持有一个实例

  16. 在并发场景下,通过双重检查锁(double-checked locking)实现延迟初始化的优化 问题隐患(可参考 The “Double-Checked Locking is Broken” Declaration),推荐解决方案中较为 简单一种(适用于 JDK5 及以上版本),将目标属性声明为 volatile 型。

  17. volatile 解决多线程内存不可见问题。对于一写多读,是可以解决变量同步问题,但 是如果多写,同样无法解决线程安全问题。

  18. HashMap在容量不够时进行resize时由于高并发可能出现死链,导致CPU飙升,在开发过程中可以使用其他数据结构或加锁来规避此风险。

  19. ThreadLocal 对象使用 static 修饰,ThreadLocal 无法解决共享对象的更新问题。

控制语句

  1. 在一个switch块内,每个case要么通过continue/break/return等来终止,要么注释说明程序将继续执行到哪个case为止;在一个switch块内,都必须包含一个default语句并且放在最后,即使他什么也没有

  2. 当switch括号内的变量类型为String并且此变量为外部参数时,必须先进行null判断。

  3. 在if/else/for/while/do语句中必须使用大括号

  4. 在并发场景中,避免使用等于判断作为中断或退出的条件如果并发控制没有处理好,容易产生击穿的情况,使用大于或小于的区间判断来代替;你如奖品剩余为0的时候终止,并发错误瞬间变成负数则无法终止

  5. 表达异常的分支时,少用if-else,避免超过3层if else if,可以改写成if(condition) return obj;

    1. 超过三层的if-else的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现,其中卫语句即代码逻辑先考虑失败、异常、中断、退出等直接返回的情况,以方法多个出口的方式,解决代码中判断分支嵌套的问题。

      public void findBoyfriend(Man man) {
      if (man.isUgly()) { System.out.println("本姑娘是外貌协会的资深会员");
      return; }
      if (man.isPoor()) { System.out.println("贫贱夫妻百事哀");
      return; }
      if (man.isBadTemper()) { System.out.println("银河有多远,你就给我滚多远");
      return; }
      System.out.println("可以先交往一段时间看看"); }
      
  6. 除常用方法(如getXxx/isXxx)等外,不要在条件判断中执行其他复杂的语句,将复杂逻辑判断的结果赋值给一个有意义的布尔变量名,以提高可读性。

  7. 不要在**其他表达式(尤其是条件表达式)**中,插入赋值语句。赋值点类似于人体的穴位,对于代码的理解至关重要,所以赋值语句需要清晰的单独成为一行。

public Lock getLock(boolean fair) {
// 算术表达式中出现赋值操作,容易忽略 count 值已经被改变
threshold = (count = Integer.MAX_VALUE) - 1;
// 条件表达式中出现赋值操作,容易误认为是 sync==fair
return (sync = fair) ? new FairSync() : new NonfairSync(); }
  1. 循环体中的语句要考量性能,以下操作尽量移至循环体外处理,如定义对象、变 量、获取数据库连接,进行不必要的 try-catch 操作(这个 try-catch 是否可以移至循环体 外)。
  2. 避免采用取反逻辑运算符
  3. 接口入参保护,这种场景常见的是用作批量操作的接口
  4. 下列情形,需要进行参数校验:
    1. 调用频次低的方法。
    2. 执行时间开销很大,此情形中,参数校验时间几乎可以忽略不计,但如果因为参数错误导致中间执行回退,或者错误,那得不偿失
    3. 需要极高稳定性和可用性的方法
    4. 对外提供的开放接口,不管是RPC/API/HTTP接口。
    5. 敏感权限入口
  5. 下列情形,不需要进行参数校验
    1. 极有可能被循环调用的方法。但在方法说明里必须注明外部参数检查要求。
    2. 底层调用频度比较高的方法。毕竟是像纯净水过滤的最后一道,参数错误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中,部署在同一台服务器中,所以 DAO 的参数校验,可 以省略。
    3. 被声明成private只会被自己代码调用的方法,如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题,此时可以不校验参数。

注释规约

  1. 类、类属性、类方法的注释必须使用javadoc规范,使用/*内容/格式,不得使用// xxx方式。
  2. 所有的抽象方法(包括接口中的方法)必须要用javadoc注释、除了返回值、参数、异常说明外,还必须指出该方法做了什么事,实现什么功能。对子类的实现要求,或者调用注意事项,请一并说明
  3. 所有的类都必须添加创建者和创建日期
  4. 方法内部使用单行注释,在被注释语句上另起一行,使用//注释。方法内部多行注释使用/* */注释,注意与代码对齐
  5. 所有的枚举类型字段必须要有注释,说明每个数据项的用途。
  6. 与其半吊子的英文注释,不如用中文注释把问题说清楚。专有名词与关键词保持英文原文即可。
  7. 代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑的修改
  8. 谨慎注释掉代码。在上方详细说明,而不是简单地注释掉,如果不用,则删除
  9. 对于注释的要求:第一、能够准确反映设计思想和代码逻辑;第二、能够描述业务 含义,使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者 形同天书,注释是给自己看的,即使隔很长时间,也能清晰理解当时的思路;注释也是给继 任者看的,使其能够快速接替自己的工作。
  10. 好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的 一个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释是相当大的负担
  11. 特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫 描,经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

其他

  1. 在使用正则表达式时,利用好其预编译功能,可以有效加快正则匹配速度。说明:不要在方法体内定义:Pattern pattern = Pattern.compile(“规则”)
  2. velocity调用POJO类的属性时,直接使用属性名取值即可,模板引擎会自动按规范 调用 POJO 的 getXxx(),如果是 boolean 基本数据类型变量(boolean 命名不需要加 is 前 缀),会自动调用 isXxx()方法。
  3. 后台输送给页面的变量必须加 ! v a r — — 中 间 的 感 叹 号 。 ∗ ∗ 如 果 v a r 等 于 n u l l 或 者 不 存 在 , 那 么 !{var} —— 中间的感叹号。**如果var等于null或者不存在,那么 !var——中间的感叹号。∗∗如果var等于null或者不存在,那么{var}会直接显示在页面上。**
  4. 注意 Math.random() 这个方法返回是 double 类型,注意取值的范围 0≤x<1(能够 取到零值,注意除零异常),如果想获取整数类型的随机数,不要将 x 放大 10 的若干倍然后 取整,直接使用 Random 对象的 nextInt 或者 nextLong 方法。
  5. 获取当前毫秒数 System.currentTimeMillis(); 而不是 new Date().getTime(); 说明:如果想获取更加精确的纳秒级时间值,使用 System.nanoTime()的方式。在 JDK8 中,针对统计时 间等场景,推荐使用 Instant 类
  6. 日期格式化时,传入pattern中表示年份统一使用小写的y。new SimpleDateFormat(“yyyy-MM-dd HH:mm:ss”);
  7. 在MVC的理论中,不要在视图模版中加入任何复杂的逻辑
  8. 任何数据结构的构造或初始化,都应该指定其大小,避免数据结构无限增长吃光内存
  9. 即使清理不再使用的代码段或配置信息

异常日志

异常处理

  1. Java类库中定义的可以通过预检方式规避的RuntimeException异常不应该通过catch的方式来处理。比如:NullPointerException,IndexOutOfBoundException等。
  2. 异常不要用来做条件控制,流程控制。
  3. catch时请分清稳定代码和非稳定代码,稳定代码指的是无论如何不会出错的代码。 对于非稳定代码的 catch 尽可能进行区分异常类型,再做对应的异常处理。
  4. 捕获异常时为了处理它,不要捕获了却什么都不处理而抛弃它,如果不想处理它,请将该异常抛给它的调用者。最外层的业务使用者,如果必须处理异常,将其转化为用户里可以理解的内容
  5. 有try块放到了事务代码中,catch异常后,如果需要回滚事务,一定要注意手动回滚事务。
  6. finally块必须对资源对象、流对象进行关闭,有异常也要做try-catch。**如果是jdk7以上,可以使用try-with-resource方式。
  7. 不要再finally块中使用return。try 块中的 return 语句执行成功后,并不马上返回,而是继续执行 finally 块中的语句,如果此处存在 return 语句,则在此直接返回,无情丢弃掉 try 块中的返回点。
  8. 捕获异常与抛异常,必须是完全匹配,或者捕获异常是抛异常的父类。
  9. 在调用RPC、二方包、或动态生成类的相关方法时,捕获异常必须使用Throwable类进行拦截。说明:通过反射机制来调用方法,如果找不到方法,抛出 NoSuchMethodException。什么情况会抛出NoSuchMethodError 呢?二方包在类冲突时,仲裁机制可能导致引入非预期的版本使类的方法签名不匹配,或者在字节码修改框架(比如:ASM)动态创建或修改类时,修改了相应的方法签名。这些情况,即使代码编译期是正确的,但在代码运行期时,会抛出 NoSuchMethodError
  10. 方法的返回值可以为null,不强制返回空集合,或者空对象等,但必须添加注释充分说明什么时候会返回null值。
  11. 防止NPE,是程序员的基本修养,注意NPE产生的场景
    1. 返回类型为基本数据类型,return 包装数据类型的对象时,自动拆箱可能产生NPE。
    2. 数据库的查询结果可能为null
    3. 集合里的元素即使isNotEmpty,取出的元素依然可能是null
    4. 远程调用返回对象时,一律要求进行空指针判断。防止NPE
    5. 对于Session中获取的数据,建议进行NPE检查,避免NPE。
    6. 级联调用obj.getA().getB().getC();一连串调用,容易产生NPE(使用JDK8的Optional类来防止NPE问题。)
  12. 定义时区分 unchecked / checked 异常,避免直接抛出 new RuntimeException(), 更不允许抛出 Exception 或者 Throwable,应使用有业务含义的自定义异常。推荐业界已定 义过的自定义异常,如:DAOException / ServiceException 等。
  13. 对于公司外的http/api开放接口必须使用"错误码";而应用内部推荐异常抛出;跨应用间RPC调用优先考虑使用Result方式,封装isSuccess()方法、错误码、错误间断信息
  14. 避免出现重复的代码,即DRY原则。随意复制和粘贴代码,必然会导致代码的重复,在以后需要修改时,需要修改所有的副本,容易遗 漏。必要时抽取共性方法,或者抽象公共类,甚至是组件化。

日志规约

  1. 日志中不可直接使用日志系统(Log4j、Logback)中的API,而应依赖使用日志框架SLF4J中的API,使用门面模式的日志框架,有利于维护和各个类的日志处理方式统一。

    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    private static final Logger logger = LoggerFactory.getLogger(Test.class);
    
  2. 所有日志文件至少保存15天,因为有些异常具备以"周"为频次发生的特点。网络运行状态、安全相关信息、系统检测、管理后台操作、用户敏感操作需要留存相关的网络日志不少于6个月。

  3. 应用中的扩展日志(如打点、临时监控、访问日志等)命名方式:appName_logType_logName.log。logType:日志类型,如stats/monitor/access等;logName:日志描述。这种命名的好处:通过文件名就可以知道日志文件属于什么应用,什么类型,什么目的。也有利于归类查找

  4. 在日志输出时,字符串变量之间的拼接使用占位符的方式。说明:因为String字符串的拼接会使用StringBuilder的append()方式,有一定的性能损耗。使用占位符仅是替换动作,可以有效提高性能

    例子:logger.debug(“process trade id: {}”, id);

  5. 对于trace/debug/info级别的日志输出,必须进行日志级别的开关判断。

    // 如果判断为真,那么可以输出 trace 和 debug 级别的日志 if (logger.isDebugEnabled()) {
    logger.debug("Current ID is: {} and name is: {}", id, getName());
    }
    
  6. 避免重复打印日志,浪费磁盘空间,务必在log4j.xml中设置additivity=false。正例:

  7. 异常信息应该包括两类信息:案发现场信息和异常堆栈信息。如果不处理,那么通过关键字throws往上抛出。正例:logger.error(各类参数或者对象 toString() + “_” + e.getMessage(), e);

  8. 谨慎地记录日志。生产环境禁止输出debug日志;有选择地输出info日志;如果使用warn来记录刚上线时的业务行为信息,一定要注意日志输出量的问题,避免把服务器磁盘撑爆,并记得及时删除这些观察日志。

  9. 可以使用warn日志级别来记录用户输入参数错误的情况,避免用户投诉时,无所适从。如非必要,请不要在此场景打出error级别,避免频繁报警。

  10. 尽量使用英文来描述日志错误信息,如果日志信息中的错误信息用英文描述不清楚的话使用中文描述即可,否则容易产生歧义。

  11. 国际化团队或海外部署的服务器由于字符集的问题,使用全英文来注释和描述日志错误信息。

单元测试

  1. 好的单元测试必须遵守AIR原则。单元测试在线上运行时,感觉像空气一样并不存在,但在质量测试的保障上,确实非常关键的。好的单元测试宏观上来说,具有自动化、独立性、可重复执行的特点。
  2. 单元测试应该是全自动执行的,并且非交互式的。测试用例通常是被定期执行的,执行过程必须完全自动化才有意义。输出结果需要人工检查的测试不是一个好的单元测试。单元测试中不准使用System.out来进行人肉严重,必须使用assert来验证
  3. 保存单元测试的独立性。为了保证单元测试稳定可靠且便于维护,单元测试用例之间决不能互相调用,也不能依赖执行的先后顺序
  4. 单元测试是可以重复执行的,不能收到外界环境的影响。(单元测试通常会被放到持续集成中,每次有代码 check in 时单元测试都会被执行。如果单测对外部 环境(网络、服务、中间件等)有依赖,容易导致持续集成机制的不可用。)正例:为了不受外界环境影响,要求设计代码时就把SUT的依赖改成注入,在测试时用Spring这样的DI框架注入一个本地(内存)实现或者Mock实现
  5. 对于单元测试,要保证测试粒度足够小,有助于精确定位问题。单测粒度至多时类级别,一般是方法级别。
  6. 核心业务、核心应用、核心模块的增量代码确保单元测试通过。
  7. 单元测试代码必须写在如下工程目录:src/test/java,不允许写在业务代码目录下。说明:源码编译时会跳过此目录,而单元测试框架默认是扫描此目录
  8. 单元测试的基本目标:语句覆盖率达到70%;核心模块的语句覆盖率和分支覆盖率都要达到100%。
  9. 编写单元测试代码遵守BCDE原则,以保证被测试模块的交付质量
    1. B:Border,边界值测试,包括循环边界、特殊取值、特殊时间点、数据顺序等。
    2. C:Correct,正确的输入,并得到预期的结果。
    3. D:Design,与设计文档相结合,来编写单元测试。
    4. E:Error,强制错误信息输入(如:非法数据、异常流程、业务允许外等),并得到预期的结果。
  10. 对于数据库相关的查询、更新和删除等操作,不能假设数据库里的数据是存在的,或者直接操作数据库把数据插入进去,请使用程序插入或者导入数据的方式来准备数据。
  11. 和数据库相关的单元测试,可以设定自动回滚机制,不给数据库造成脏数据。或者对单元测试产生的数据有明确的前后缀标识。在企业智能事业部的内部单元测试中,使用ENTERPRISE_INTELLIGENCE_UNIT_TEST_的前缀来标识单元测试相关代码
  12. 对于不可测的代码在适当的时机做必要的重构,使代码变得可测,避免为了达到测试要求而书写不规范测试代码。
  13. 在设计评审阶段,开发人员需要和测试人员一起确定单元测试范围,单元测试最好 覆盖所有测试用例。
  14. 单元测试作为一种质量保障手段,在项目提测前完成单元测试,不建议项目发布后补充单元测试用例。
  15. 为了更方便地进行单元测试,业务代码应避免以下情况:
    1. 构造方法中做的事情过多。
    2. 存在过多的全局变量和静态方法。
    3. 存在过多的外部依赖。
    4. 存在过多的条件语句。
  16. 不要对单元测试存在如下误解:
    1. 那是测试同学干的事情。本文是开发手册,凡是本文内容都是与开发同学强相关的。
    2. 单元测试代码是多余的。系统的整体功能与各单元部件的测试正常与否是强相关的。
    3. 单元测试代码不需要维护。一年半载后,那么单元测试几乎处于废弃状态。
    4. 单元测试与线上故障没有辩证关系。好的单元测试能够最大限度地规避线上故障。

安全规约

  1. 隶属于用户个人的页面或者功能必须进行权限控制校验。防止没有做水平权限校验就可以随意访问、修改、删除别人的数据,比如查看他人私信内容,修改订单
  2. 用户敏感数据禁止直接展示,必须对展示数据进行脱敏
  3. 用户输入的SQL参数严格使用参数绑定或者METADATA字段值限定,防止SQL注入,禁止字符串拼接SQL访问数据库。
  4. 用户请求传入的任何参数必须做有效性验证
  5. 禁止向html页面输出未经安全过滤或未正确转义的用户数据
  6. 表单、AJAX提交必须执行CSRF安全验证。
  7. 在使用平台资源,譬如短信、邮件、电话、下单、支付,必须实现正确的防重放的机制,如数量限制、疲劳度控制,验证码校验,避免被滥刷而导致资损。
  8. 发帖、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过滤等风控策略。

Mysql数据库规范

  1. 表达是与否概念的字段,必须使用is_xxx的方式命名,数据类型是unsigned tinyint (1 表示是,0表示否)。任何字段如果是非负数,必须是unsigned
  2. 表名、字段名必须使用小写字母或数字,禁止出现数字开头,禁止两个下划线中间只出现数字。数据库字段名的修改代价很大,因为无法进行预发布,所以字段名需要慎重考虑。
  3. 表名不使用复数名词。
  4. 禁用保留字,如desc、range、match、delayed等,请参考MYSQL官方保留字。
  5. 主键索引名为pk字段名;唯一索引名为uk字段名,普通索引名则为idx字段名。
  6. 小数类型为decimal,禁止使用float和double
  7. 如果存储等字符串长度几乎相等,使用char定长字符串
  8. varchar是可变长字符串,不预先分配存储空间,长度不要超过5000,如果存储长度大于此值,定义字段类型为text,独立出来一张表,用主键来对应,避免影响其他字段索引效率。
  9. 表必备三字段:id,create_time,update_time.**其中id必为主键,类型为bigint unsigned、单表时自增、步长为1。create_time,update_time的类型均为datetime类型。
  10. 表的命名最好遵循"业务名称_表的作用"。alipay_task / force_project / trade_config
  11. 库名与应用名称尽量一致
  12. 如果需要修改字段含义或对字段表示对状态追加时,需要及时更新字段注释。
  13. 字段允许适当冗余,以提高查询性能,但必须考虑数据一致。冗余字段应遵循:
    1. 不是频繁修改的字段
    2. 不是varchar超长字段,更不能时text字段
    3. 不是唯一索引的字段。
  14. 单表行数超过500万行或者单表容量超过2GB,才推荐进行分库分表。如果预计三年后的数据量根本达不到这个级别,不要在创建表时就分库分表
  15. 合适的字符存储长度,不但节约数据库表空间,节约索引存储,更重要的是提升检索速度。如人的年龄使用tinyint unsigned, 龟的寿命使用smallint unsigned, 恐龙的寿命使用 int unsigned, 太阳的寿命使用bigint unsigned。

索引规约

  1. 业务上具有唯一特性的字段,即使是多个字段的组合,也必须建成唯一索引。不要以为唯一索引影响了insert速度,这个速度损耗可以忽略,但提高查找速度是明显的;另外即使在应用层做了非常完善的校验控制,只要没有唯一索引,根据墨菲定律,不然有脏数据产生。
  2. 超过三个表禁止join。需要join的字段,数据类型必须一致;多表关联查询时,保证被关联的字段需要有索引。即使双表join也要注意表索引、sql性能
  3. 在varchar字段上建立索引时,必须指定索引长度,没必要对全字段建议索引,根据实际文本区分度决定索引长度即可。索引的长度与缺分毒是一对矛盾体,一般对字符串类型数据,长度为20的索引,区分度会高达90%以上,可以用count(distinct left(列名, 索引长度))/count(*)的区分度来确定
  4. 页面搜索严禁左模糊或者全模糊,如果需要请走搜索引擎来解决。如果左值未确定,那么无法走索引
  5. 如果有order by 的场景,请注意利用索引的有序性。order by 最后的字段是组合索引的一部分,并且放在索引组合顺序的最后,避免出现file_sort的情况,影响查询性能。
  6. 利用覆盖索引来查询操作,避免回表。能够建立索引的种类分为主键索引、唯一索引、普通索引三种,而覆盖索引知识一种查询的一种效果,用explain的结果,extra列会出现:using index
  7. 利用延迟关联或者子查询优化超多分页场景。*比如取特定段id的数据,原本是SELECT * FROM a where 条件 LIMIT 100000,20,在mysql中,会先取到100020行,然后放弃前100000行,这样效率会非常低。所以可以使用子查询方式优化效率:SELECT a. FROM 表 1 a, (select id from 表 1 where 条件 limit 100000, 20) b where a.id = b.id。 先查出对应的id,再通过id去获取数据结果,效率会高很多 **
  8. SQL性能优化的目标:至少要达到range级别,要求是ref级别,如果可以是consts最好。
    1. consts 单表中最多只有一个匹配行(主键或唯一索引),在优化阶段即可读取到数据
    2. ref指的是使用普通的索引
    3. range对索引进行范围检索
  9. 建组合索引时,区分度最高的在左边
  10. 防止因字段类型不同造成的隐式转换,导致索引失效
  11. 创建索引时避免有如下极端误解:
    1. 宁滥勿缺,认为一个查询就需要建一个索引
    2. 宁缺毋滥。认为索引会消耗空间、严重拖慢记录的更新以及行的新增速度
    3. 抵制唯一索引。认为业务的唯一性一律需要在应用层通过先查后插的方式解决。

SQL语句

  1. 不要使用count(列名)或count(常量)来替代count(),count()是SQL92定义的标准统计行数的语法,跟数据库无关,跟NULL和非NULL无关。count(*)会统计值未NULL的行,而count(列名)不会统计此列为NULL的行
  2. count(distinct col) 计算该列除NULL之外的不重复行数,注意 count(distinct col1, col2) 如果其中一列全为NULL,那么即使另一列有不同的值,也返回0。
  3. 当某一列的值全是NULL时,count(col)的返回结果为0,但sum(col)的返回个结果为NULL,因此使用sum()时需要注意NPE问题。通过如下方式来避免sum的NPE问题:select IFNULL(SUM(column), 0) from table;
  4. 使用ISNULL()来判断是否为NULL值。NULL与任何值的直接比较都为NULL
    1. NULL <> NULL的结果返回是NULL, 而不能是false。
    2. NULL = NULL 的返回结果是NULL,而不是true。
    3. NULL <> 1的范围结果是NULL,而不是true。
  5. 代码中写分页查询逻辑时,若count为0应直接返回,避免执行后面所有的分页语句。
  6. 不得使用外键与级联,一切外键概念必须在应用层解决。
  7. 禁止使用存储过程,存储过程难以调试和扩展,更没有移植性。
  8. 数据订正(特别是删除、修改记录操作)时,要先select,避免出现误删除,确认无误才能执行更新语句。
  9. in 操作能避免则避免,若实在避免不了,需要仔细评估in后面的集合元素数量,控制在1000个以内。
  10. 如果有国际化需要,所有的字符存储与表示,均以utf-8编码,注意字符统计函数的区别。
  11. TRUNCATE TABLE 比 DELETE 速度快,且使用的系统和事务资源少,但TRUNCATE无事务且不处罚trigger,可能造成事故,故不建议在开发中使用此语句。

ORM映射

  1. 在表查询中,一律不要使用 * 作为查询的字段列表,需要哪些字段必须明确写明。1. 增加查询解析器解析成本 2.增减字段容易与resultMap配置不一致 3.无用字段增加网络消耗,尤其是text类型的字段
  2. POJO类的布尔属性不能加is,而数据库字段必须加is_,要求在resultMap中进行字段与属性之间的映射。
  3. 不要使用resultClass当返回参数,即使所有类属性名与数据库字段一一对应,也需要定义;反过来,每一个表也必然有一个POJO类与之对应。
  4. sql.xml配置参数使用:#{}, #param#,不要使用${} 这种方式容易出现SQL注入
  5. iBATIS 自带的 queryForList(String statementName,int start,int size)不推荐使用。
  6. 不允许直接拿HashMap与HashTable作为查询结果集的输出**resultClass = "HashTable"会置入字段名和属性名,但是值的类型不可控。
  7. 更新数据表记录时,必须同时更新记录对应gmt_modified字段值为当前时间
  8. 不要写一个大而全的数据更新接口,传入为POJO类,不管是不是自己的更新目标字段,多进行update table set c1=value1,c2=value2,c3=value3这是不对的。执行sql时,不要更新无改动的字段,一是容易出错,二是效率低,三是增加binlog存储。
  9. @Transactional事务不要滥用。事务会影响数据库的QPS,另外使用事务的地方需要考虑各方面的回滚方案,包括缓存回滚,搜索回滚,消息补偿,统计修正等
  10. 中的 compareValue 是与属性值对比的常量,一般是数字,表示相等时 带上此条件;表示不为空且不为 null 时执行;表示不为 null 值 时执行。

工程结构

应用分层

  1. 开放接口层:可直接封装Service方法暴露成RPC接口;通过Web封装成http接口;进行网关安全控制、流量控制等。
  2. 终端显示层:各个端端模版渲染并执行显示的层。当前主要是velocity渲染,js渲染,jsp渲染,移动端展示等。
  3. Web层:主要是对访问控制进行转发,各类基本参数校验,或者不复用的业务简单处理等。
  4. Service层:相对具体的业务逻辑服务层。
  5. Manager层:通用业务处理层,它有如下特征
    1. 对第三方平台封装的层,预处理返回结果及转化异常信息
    2. 对Service层通用能力的下沉,如缓存方案,中间件通用处理
    3. 与DAO层交互,对多个DAO组合复用
  6. DAO层:数据访问层,与底层MySQL、Hbase等进行数据交互
  7. 外部接口与第三方平台:包括其他部门RPC开放接口,基础平台,其他公司的Http接口
  8. (分层异常处理规约)在DAO层,产生的异常类型有很多,无法用细粒度的异常进行catch,使用catch(Exception e)方式,并throw new DAOException,不需要打印日志,因为日志在Manager/Service层一定需要捕获并打印到日志文件中去,如果同台服务器再打日志,浪费性能和存储。在Service层出现异常时,必须记录出错日志到磁盘,尽可能带上参数信息,相当于保护案发现场。如果Manager与Service同机部署,日志方式与DAO层处理一致,如果是单独部署,则采用与Service一致的处理方式。Web层绝不应该继续往上抛异常,因为已经处于顶层,如果意识到这个异常将导致页面无法正常渲染,那么就应该直接跳转到友好错误页面,加上用户容易理解的错误提示信息。开放接口层要将异常处理成错误码和错误信息方式返回。
  9. 分层领域模型规约
    1. DO(Data Object):此对象与数据库表结构一一对应,通过DAO层向上传输数据源对象。
    2. DTO(Data Transfer Object):数据传输对象,Service或Manager向外传输的对象
    3. BO(Business Object):业务对象,由Service层输出的封装业务逻辑的对象
    4. AO(Application Object):应用对象,在Web层与Service层之间抽象的复用对象模型,即为贴近展示层,复用度不高。
    5. VO(View Object):显示层对象,通常是Web向模版渲染引擎层传输的对象
    6. Query:数据查询对象,各层接收上层的查询请求。注意超过两个参数的查询封装,禁止使用Map类来传输

二方库依赖

  1. 定义GAV遵从以下规则:

    1. GroupID格式:com.{公司/BU}.业务线[.子业务线],最多4级。

      {公司/BU} 例如:alibaba/taobao/tmall/aliexpress 等 BU 一级;子业务线可选。如com.taobao.jstorm, com.alibaba.dubbo.register

    2. ArtifactID格式:产品线名-模块名。语义不重复不遗漏,先到中央仓库全查证一下。如dubbo-client / fastjson-api

    3. Version:详细规定参考下方

  2. 二方库版本号命名方式:主版本号.次版本号.修订号

    1. 主版本号:产品方向改变,或者大规模API不兼容,或者架构不兼容升级
    2. 次版本号:保持相对兼容性,增加主要功能特性,影响范围极小的API不兼容修改
    3. 修订号:保持完全兼容性,修复BUG、新增次要功能特性等

    注意起始版本号必须为:1.0.0,而不是0.0.1,正式发布的类库必须先去中央仓库进行查证,使版本号有延续性,正式版本号不允许覆盖升级。如当前版本为1.3.3,那么下一个合理的版本号为1.3.4或1.4.0或2.0.0

  3. 线上应用不要依赖SNAPSHOT版本(安全包除外)。不依赖SNAPSHOT版本是保证应用发布的幂等性。另外,也可以加快编译时的打包构建

  4. 二方库的新增或升级,保持除功能点之外的其他jar包仲裁结果不变。如果有改变,必须明确评估和验证。说明:在升级时,进行 dependency:resolve 前后信息比对,如果仲裁结果完全不一致,那么通过dependency:tree 命令,找出差异点,进行排除 jar 包

  5. 二方库里可以定义枚举类型,参数可以使用枚举类型,但是接口返回值不允许使用枚举类型或包含枚举类型的POJO对象。

  6. 依赖一个二方库群时,必须定义一个统一的版本变量,避免版本号不一致。依赖springframework-core, -context, -beans,他们都是同一个版本,可以定义一个变量来保存版本:${spring.version},定义依赖的时候,引用该版本

  7. 禁止在子项目的pom依赖中出现相同的GroupId,相同的ArtifactId,但是不同的Version。在本地调试时会使用各子项目指定的版本号,但是合并成一个war,只能有一个版本号出现在最后的lib目录中。可能出现线下调试是正确的,发布到线上却出现故障的问题

  8. 底层基础技术框架、核心数据管理平台、或近硬件端系统谨慎引入第三方实现。

  9. 所有pom文件中的依赖声明放在语句块中,所有版本仲裁放在语句块中。里只是声明版本,并不实现引入,因此子项目需要显式的声明依赖,version和scope都读取自父pom。而所有声明在主pom的里的依赖都会自动引入,并默认被所有的子项目继承

  10. 二方库不要有配置项,最低限度不要再增加配置项。

  11. 为避免应用二方库的依赖冲突问题,二方库发布者应当遵循以下原则:

    1. 精简可控原则。移除一切不必要的 API 和依赖,只包含 Service API、必要的领域模型对象、Utils 类、常量、枚举等。如果依赖其它二方库,尽量是 provided 引入,让二方库使用者去依赖具体版本号; 无 log 具体实现,只依赖日志框架。
    2. 稳定可追溯原则。每个版本的变化应该被记录,二方库由谁维护,源码在哪里,都需要能方便查到。 除非用户主动升级版本,否则公共二方库的行为不应该发生变化。

服务器

  1. 高并发服务器建议调小time_wait超时时间。操作系统默认240s后,才会关闭处于time_wait状态的连接,在高并发访问下,服务器端会因为处于time_wait的连接数太多,可能无法建立新的连接,所以需要在服务器上调小此等待值。如在 linux 服务器上请通过变更/etc/sysctl.conf 文件去修改该缺省值(秒):net.ipv4.tcp_fin_timeout = 30
  2. 调大服务器所支持的最大文件句柄数(File Descriptor,简称fd)。主流操作系统的设计是将TCP/UDP连接采用与文件一样的方式去管理,即一个连接对应于一个fd。主流的linux服务器默认所支持最大fd为1024,当并发连接数很大时很容易因为 fd 不足而出现 “open too many files”错误,导致新的连接无法建立。建议将 linux 服务器所支持的最大句柄数调高数 倍(与服务器的内存数量相关)
  3. 给JVM环境参数设置-XX:+HeapDumpOutOfMemoryError参数,让JVM碰到OOM场景时输出dump信息。OOM的发生时有概率的,甚至相隔数月才出现一例,出错时的堆内信息对解决问题非常有帮助
  4. 在线上生产环境,JVM的Xms和Xmx设置一样大小的内存容量,避免在GC后调整堆大小带来的压力。
  5. 服务器内部重定向使用forward;外部重定向抵制使用URL拼接工具类来生成,否则会带来URL维护不一致的问题和潜在的安全风险

设计规约

  1. 存储方案和底层数据结构的设计获得评审的一致通过,并沉淀成为文档。有缺陷的底层数据结构容易导致系统风险上升,可扩展性下降。重构成本也会因历史数据迁移和系统平滑过渡而陡然增加,所以,存储方案和数据结构需要认真的进行设计和评审,生产环境提交执行后,需要进行double check
  2. 在需求分析阶段,如果与系统交互的User超过一类并且相关的User Case超过5个,使用用例图来表达更加清晰的结构化需求。
  3. 如果某个业务对象的状态超过3个,使用状态图来表达并且明确状态变化的各个触发条件。状态图的核心是对象状态,首先明确对象有多少种状态,然后明确两两状态之间是否存在直接转换的关系,再明确触发状态转换的条件是什么。如淘宝订单状态有已下单、待付款、已付款、待发货、已发货、已收货等。比如已下单与已收货这两种状态之间是不可能有直接转换关系的
  4. 如果系统中某个功能的调用链路上设计对象超过3个,使用时序图来表达并且明确各调用环节的输入和输出
  5. 如果系统中模型类超过5个,并且存在复杂的依赖关系,使用类图来表达并且明确 类之间的关系。类图像建筑领域的施工图,如果搭平房,可能不需要,但如果建造蚂蚁 Z 空间大楼,肯定需要详细 的施工图
  6. 如果系统中超过2个对象之间存在协作关系,并且需要表示复杂的处理流程,使用活动图来表示。活动图是流程图的扩展,增加了能够体现协作关系的对象泳道,支持表示并发等
  7. 需求分析与系统设计在考虑主干功能的同时,需要充分评估异常流程与业务边界
  8. 类在设计与实现时要符合单一原则。单一原则最易理解却是最难实现的一条规则,随着系统演进,很多时候,忘记了类设计的初衷
  9. 谨慎使用继承的方式来进行扩展,优先使用聚合/组合的方式来实现。不得已使用继承的话,必须符合里氏代换原则,此原则说父类能够出现的地方子类一定能够出现, 比如,“把钱交出来”,钱的子类美元、欧元、人民币等都可以出现
  10. 系统设计时,根据依赖倒置原则,尽量依赖抽象类与接口,有利于扩展与维护。低层次模块依赖于高层次模块的抽象,方便系统间的解耦
  11. 系统设计时,注意对扩展开放,对修改闭合。极端情况下,交付线上生产环境的代码都是不可修改的,同一业务域内的需求变化,通过模块或类 的扩展来实现
  12. 系统设计阶段,共性业务或公共行为抽取出来公共模块、公共配置、公共类、公共 方法等,避免出现重复代码或重复配置的情况。随着代码的重复次数不断增加,维护成本指数级上升
  13. 避免如下误解:敏捷开发 = 讲故事 + 编码 + 发布。敏捷开发是快速交付迭代可用的系统,省略多余的设计方案,摒弃传统的审批流程,但核心关键点上的必要设计和文档沉淀是需要的
  14. 系统设计主要目的是明确需求、理顺逻辑、后期维护,次要目的用于指导编码。避免为了设计而设计,系统设计文档有助于后期的系统维护和重构,所以设计结果需要进行分类归档保存
  15. 设计的本质就是识别和表达系统难点,找到系统的变化点,并隔离变化点。世间众多设计模式目的是相同的,即隔离系统变化点
  16. 系统架构设计的目的
    1. 确定系统边界。确定系统在技术层面上的做与不做
    2. 确定系统内模块之间的关系。确定模块之间的依赖关系及模块的宏观输入与输出
    3. 确定指导后续设计与演化的原则。使后续的子系统或模块设计在规定的框架内继续演化
    4. 确定非功能性需求。非功能性需求是指安全性、可用性、可扩展性等
  17. 在做无障碍产品设计时,需要考虑到
    1. 所有可交互的控件元素必须能被 tab 键聚焦,并且焦点顺序需符合自然操作逻辑
    2. 用于登陆校验和请求拦截的验证码均需提供图形验证以外的其它方式
    3. 自定义的控件类型需明确交互方式
这篇关于java开发手册 - 码出规范 - 要点整理的文章就介绍到这儿,希望我们推荐的文章对大家有所帮助,也希望大家多多支持为之网!