【编程规约】

命名规约

• 所有命名不能以美元符和下划线开始和结尾
• 禁止拼音加英文
• 类用UserDao..方法，变量，参数用userDao
• 常量名全部大写，下划线隔开
• 抽象类使用Abstract或者Base开头，异常类使用Exception结尾
• boolean属性命名不能使用is开头
• 如果使用到了设计模式，建议在类名中体现出具体模式。LoginProxy
• 接口类中方法不加权限修饰符
• 接口和实现类 实现类以Impl结尾
• MVC各层命名规约
  
  • Service/Dao层
    
    • 获取单个对象 get 前缀
    • 获取多个对象 list 前缀
    • 获取统计值的方法 count 前缀
    • 插入 save 前缀
    • 删除 remove
    • 修改 update
  • 领域模型
    
    • 数据对象 DO 是数据表名
    • 数据传输对象 DTO 是业务领域相关的名称
    • 展示对象 VO 是网页名称 使用了模板框架
    • POJO是 DO DTO BO VO 统称

常量定义

• 不允许出现魔法值，未经定义的常量突然出现
• Long类型使用大写L结尾
• 常量类存放常量要分门别类放置
• 常量的复用层次的安排
  
  • 跨应用共享常量 ：二方库中 通常是client.jar中的constant目录下
  • 应用内共享常量 ：一方库的modules中的constant
  • 子工程内共享常量 ：当前子工程的constant目录下
  • 包内共享常量：当前包下单独的constant目录下
  • 类内共享常量：直接定义 private static final

格式规约

• 小括号，左右括号前后之间没有空格
• if/for/while/switch/do 后加空格: 例如 ：if ()
• 任何运算符前后都必须加空格
• 缩进采用4个空格，而不是tab字符，IDE要调整一下
• 单行字符不超过120个，超出需换行 第二行比第一行缩进4个空格，第三行以后就和第二行平齐就可以了
  
  • 运算符与下文一起换行
  • 方法调用的点符号与下文一起换行
  • 调用方法 多个参数，超长，需逗号后进行换行
  • 括号之前不要换行
• 方法参数在定义和传入时，多个参数逗号后边必须加空格
• 编码统一采用UTF-8 IDE中换行符采用unix格式
• 方法体内执行语句组，变量的定义语句组，不同的业务逻辑之间或者不同的语义之间插入一个空行，相同业务逻辑和语义之间不需要插入空行

OOP规约

• 避免使用对象来引用类的静态变量或方法
• 所有的覆写方法，必须加注解 @Override
• 相同参数类型，相同业务含义，才可以使用Java的可变参数避免使用Object
• 对外暴露的接口签名，原则上不允许修改方法签名，避免对接口调用方法产生影响，接口过时必须加@Deprecated注解，并说明采用的新接口或新服务是什么
• 不能使用过时的类或方法
• 使用 “t”.equals(test)方式，推荐使用java.util.Object#equals (jdk7引入的工具类)
• 所有的相同类型的包装类对象之间的值比较，全部使用equals方法，
  
  • 注意： Integer对象 使用==也可以，但是会产生很多内存浪费
• 所有的POJO类属性必须使用包装数据类型
  
  • RPC方法的返回值和参数必须使用包装数据类型
  • 所有的局部变量 推荐使用基本数据类型
• 定义 DO/DTO/VO等POJO类时，不要设定任何属性的默认值
• 序列化类新增属性时，不要修改serialVersionUID字段，避免反序列化失败，如果完全不兼容升级，避免反序列化混乱，可以修改serialVersionUID的值
• 构造方法不能有任何的业务逻辑，只是用来初始化对象的
• POJO类每一个都必须重写 toString方法，方便之后debug
• 使用索引访问用String 的split 方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有下标超出的异常
• 当一个类有多个构造方法，或者多个重名方法，这些方法应该按顺序放置在一起
• 类内方法的定义顺序依次是 共有方法或保护方法 -> 私有方法 -> setter/getter方法
• setter/getter方法中也不要加入业务逻辑
• 循环体中的字符串的连接方式，使用StringBuffer的append方法进行扩展
• final可提高程序响应效率，声明成final的情况：
  
  • 不需要重新赋值的变量，包括类属性，局部变量
  • 对象参数前加final，表示不允许修改引用的指向
  • 类方法确定不允许被重写
• 慎用Object的clone方法来拷贝对象，最好重写该方法，实现属性的拷贝
• 类成员与方法访问控制从严：
  
  • 如果不允许外部直接通过new来创建对象，那么构造方法显式声明并private
  • 工具类不允许有public或default构造方法
  • 类非static成员变量并且与子类共享，必须是protexted
  • 类非static成员变量并且仅在本类中使用，必须是private
  • 若是static成员变量，必须考虑是否final
  • 类成员方法只供类内部调用，必须是private
  • 类成员方法只对继承类公开，那么限制为protected
  • 注意 访问范围的严格控制利于对模块解耦，如果删除一个private方法，删除就删除，但是如果是public方法就得手心冒汗的删除了

集合处理

• 关于HashCode 和equals的处理
  
  • 只要重写equals，就必须重写HashCode
  • 因为Set存储的是不重复的对象，依据HashCode和equals进行判断，所以Set存储的方法必须重写这两个方法
  • 如果自定义对象作为Map的键，那么必须重写HashCode和equals
• ArrayList的subList结果不可强转成ArrayList，否则会抛出类型强转的错误
  
  • subList返回的是ArrayList的内部类，是ArrayList的一个视图，对于subList的所有操作最终都会反映到原列表上
• 在 subList 场景中，高度注意对原集合元素个数的修改，会导致子列表的遍历、增加、删除均产生 ConcurrentModificationException 异常。
• 使用集合转数组的方法，必须使用集合的 toArray(T[] array) ，传入的是类型完全一样的数组，大小就是 list . size()
  
  • String[] array = new String[list.size()];
  • array = list.toArray(array);
• 把数组转换成集合：使用工具类 Arrays . asList()时 ，不能使用其修改集合相关的方法，它的 add / remove / clear 方法会抛出 UnsupportedOperationException 异常。
  
  • asList 的返回对象是一个 Arrays 内部类，并没有实现集合的修改方法。 Arrays . asList体现的是适配器模式，只是转换接口，后台的数据仍是数组。
  • String[] str = new String[] { “a”, “b” };
  • List list = Arrays.asList(str);
  • 第一种情况： list.add(“c”); 运行时异常。
  • 第二种情况： str[0]= “gujin”; 那么 list.get(0) 也会随之修改。
• 泛型通配符

   List<String> a = new ArrayList<String>();
      a.add("1");
      a.add("2");
      for (String temp : a) {
         if("1".equals(temp)){
            a.remove(temp);
         }
   }

• 在 JDK 7 版本以上， 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 比较结果相同。
• 集合初始化时，尽量指定集合初始值大小。
• 使用 entrySet 遍历 Map 类集合 KV ，而不是 keySet 方式进行遍历
  
  • keySet 其实是遍历了 2 次，一次是转为 Iterator 对象，另一次是从 hashMap 中取出key 所对应的 value 。
  • 而 entrySet 只是遍历了一次就把 key 和 value 都放到了 entry 中，效率更高。
  • 如果是 JDK 8，使用 Map . foreach 方法。
  • values() 返回的是 V 值集合，是一个 list 集合对象 ；keySet() 返回的是 K 值集合，是一个 Set 集合对象 ；entrySet() 返回的是 K - V 值组合集合。
• 高度注意 Map 类集合 K / V 能不能存储 null 值的情况，如下表格:

- 合理利用好集合的有序性 (sort) 和稳定性 (order) ，避免集合的无序性 (unsort) 和不稳定性 (unorder) 带来的负面影响。
- 稳定性指集合每次遍历的元素次序是一定的。
- 有序性是指遍历的结果是按某种比较规则依次排列的。
- 如： ArrayList 是 order / unsort；HashMap 是 unorder / unsort；TreeSet 是order / sort 。
- 利用 Set 元素唯一的特性，可以快速对一个集合进行去重操作，避免使用 List 的contains 方法进行遍历、对比、去重操作。

并发处理

• 获取单例对象需要保证线程安全，其中的方法也要保证线程安全。
  
  • 资源驱动类、工具类、单例工厂类都需要注意。
• 创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
• 线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。
• 线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。
  
  • 1） FixedThreadPool 和 SingleThreadPool :
  • 允许的请求队列长度为 Integer.MAX_VALUE ，可能会堆积大量的请求，从而导致 OOM 。
  • 2） CachedThreadPool 和 ScheduledThreadPool :
  • 允许的创建线程数量为 Integer.MAX_VALUE ，可能会创建大量的线程，从而导致 OOM 。
• SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为static ，必须加锁，或者使用 DateUtils 工具类。
  
  • 如果是 JDK 8 的应用，可以使用 Instant 代替 Date ， LocalDateTime 代替 Calendar ，DateTimeFormatter 代替 Simpledateformatter ，
  • 官方给出的解释： simple beautiful strongimmutable thread - safe 。
• 高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁 ； 能锁区块，就不要锁整个方法体 ； 能用对象锁，就不要用类锁。
• 对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。
  
  • 线程一需要对表 A 、 B 、 C 依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是 A 、 B 、 C ，否则可能出现死锁。
• 并发修改同一记录时，避免更新丢失，要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用 version 作为更新依据。
  
  • 如果每次访问冲突概率小于 20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于 3 次。
• 多线程并行处理定时任务时， Timer 运行多个 TimeTask 时，只要其中之一没有捕获抛出的异常，其它任务便会自动终止运行，使用 ScheduledExecutorService 则没有这个问题。
• 使用 CountDownLatch 进行异步转同步操作，每个线程退出前必须调用 countDown方法，线程执行代码注意 catch 异常，确保 countDown 方法可以执行，避免主线程无法执行至 countDown 方法，直到超时才返回结果。
  
  • 注意，子线程抛出异常堆栈，不能在主线程 try - catch 到。
• 避免 Random 实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一seed 导致的性能下降。
  
  • Random 实例包括 java . util . Random 的实例或者 Math . random() 实例。
• 通过双重检查锁 （double - checked locking）（ 在并发场景 ） 实现延迟初始化的优化问题隐患
  
  • ( 可参考 The ” Double - Checked Locking is Broken ” Declaration) ,推荐问题解决方案中较为简单一种 （ 适用于 JDK 5 及以上版本 ） ，将目标属性声明为 volatile 型 。
• volatile 解决多线程内存不可见问题。对于一写多读，是可以解决变量同步问题，但是如果多写，同样无法解决线程安全问题。如果是 count ++操作，使用如下类实现：
  
  • AtomicInteger count = new AtomicInteger(); count . addAndGet( 1 );
  • 如果是 JDK 8，推荐使用 LongAdder 对象，比 AtomicLong 性能更好 （ 减少乐观锁的重试次数 ） 。
• HashMap 在容量不够进行 resize 时由于高并发可能出现死链，导致 CPU 飙升，在开发过程中注意规避此风险。
• ThreadLocal 无法解决共享对象的更新问题， ThreadLocal 对象建议使用 static修饰。这个变量是针对一个线程内所有操作共有的，所以设置为静态变量，
  
  • 所有此类实例共享此静态变量 ，也就是说在类第一次被使用时装载，只分配一块存储空间，所有此类的对象 ( 只要是这个线程内定义的 ) 都可以操控这个变量。

控制语句

• 在一个 switch 块内，每个 case 要么通过 break / return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止 ；
  
  • 在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使它什么代码也没有。
• 在 if / else / for / while / do 语句中必须使用大括号，即使只有一行代码
• 推荐尽量少用 else ， if - else 的方式可以改写成：
  
  • 逻辑上超过 3 层的 if-else 代码可以使用卫语句，或者状态模式来实现
• 除常用方法（如 getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。
  
  • boolean existed = (file.open(fileName, "w") != null) && (...) || (...);if (existed) {}
• 循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的 try - catch 操作 （ 这个 try - catch 是否可以移至循环体外） 。
• 接口入参保护，这种场景常见的是用于做批量操作的接口。
• 方法中需要进行参数校验的场景：
  
  • 1 ） 调用频次低的方法。
  • 2 ） 执行时间开销很大的方法，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
  • 3 ） 需要极高稳定性和可用性的方法。
  • 4 ） 对外提供的开放接口，不管是 RPC / API / HTTP 接口。
  • 5） 敏感权限入口。
• 方法中不需要参数校验的场景：
  
  • 1 ） 极有可能被循环调用的方法，不建议对参数进行校验。但在方法说明里必须注明外部参数检查。
  • 2 ） 底层的方法调用频度都比较高，一般不校验。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。
    
    • 一般 DAO 层与 Service层都在同一个应用中，部署在同一台服务器中，所以 DAO 的参数校验，可以省略。
  • 3 ） 被声明成 private 只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。

注释规约

• 类、类属性、类方法的注释必须使用 Javadoc 规范，使用/* 内容 /格式，不得使用 // xxx 方式。
• 所有的抽象方法 （ 包括接口中的方法 ） 必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
• 所有的类都必须添加创建者信息。
• 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
• 所有的枚举类型字段必须要有注释，说明每个数据项的用途。
• 与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。
• 代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
  
  • 代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。
• 注释掉的代码尽量要配合说明，而不是简单的注释掉。
  
  • 代码被注释掉有两种可能性：
    
    • 1 ） 后续会恢复此段代码逻辑。
    • 2 ） 永久不用。
  • 情况（1）如果没有备注信息，难以知晓注释动机。（2）建议直接删掉 （ 代码仓库保存了历史代码 ） 。
• 对于注释的要求：
  
  • 第一、能够准确反应设计思想和代码逻辑 ；
  • 第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。
  • 完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路 ；
  • 注释也是给继任者看的，使其能够快速接替自己的工作。
• 好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。
• 特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。 线上故障有时候就是来源于这些标记处的代码。
  
  • 1 ） 待办事宜 （TODO） : （ 标记人，标记时间， [ 预计处理时间 ]）
    
    • 表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法 （ 因为它是一个 Javadoc 标签 ） 。
  • 2 ） 错误，不能工作 （FIXME） : （ 标记人，标记时间， [ 预计处理时间 ]）
    
    • 在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。

其他

• 在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。
  
  • 不要在方法体内定义： Pattern pattern = Pattern . compile( 规则 );
• velocity 调用 POJO 类的属性时，建议直接使用属性名取值即可，模板引擎会自动按规范调用 POJO 的 getXxx() ，
  
  • 如果是 boolean 基本数据类型变量 （boolean 命名不需要加 is前缀 ） ，会自动调用 isXxx() 方法。
  • 注意如果是 Boolean 包装类对象，优先调用 getXxx() 的方法。
• 后台输送给页面的变量必须加 $!{var} ——中间的感叹号。
  
  • 如果 var = null 或者不存在，那么 ${var} 会直接显示在页面上。
• 注意 Math . random() 这个方法返回是 double 类型，注意取值的范围 0≤ x <1 （ 能够取到零值，注意除零异常 ） ，
  
  • 如果想获取整数类型的随机数，不要将 x 放大 10 的若干倍然后取整，直接使用 Random 对象的 nextInt 或者 nextLong 方法。
• 获取当前毫秒数 System . currentTimeMillis(); 而不是 new Date() . getTime();
  
  • 如果想获取更加精确的纳秒级时间值，用 System . nanoTime() 。在 JDK 8 中，针对统计时间等场景，推荐使用 Instant 类。
• 尽量不要在 vm 中加入变量声明、逻辑运算符，更不要在 vm 模板中加入任何复杂的逻辑。
• 任何数据结构的构造或初始化，都应指定大小，避免数据结构无限增长吃光内存。
• 对于“明确停止使用的代码和配置”，如方法、变量、类、配置文件、动态配置属性等要坚决从程序中清理出去，避免造成过多垃圾。

【异常日志】

异常处理

• 不要捕获 Java 类库中定义的继承自 RuntimeException 的运行时异常类
  
  • 如：IndexOutOfBoundsException / NullPointerException，这类异常由程序员预检查来规避，保证程序健壮性。
  • if(obj != null) {String name = obj.getName();}
• 异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低。
• 对大段代码进行 try - catch ，这是不负责任的表现。 catch 时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的 catch 尽可能进行区分异常类型，再做对应的异常处理。
• 捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。
• 有 try 块放到了事务代码中， catch 异常后，如果需要回滚事务，一定要注意手动回滚事务。
• finally 块必须对资源对象、流对象进行关闭，有异常也要做 try - catch 。
  
  • 如果 JDK 7，可以使用 try - with - resources 方式。
• 不能在 finally 块中使用 return ， finally 块中的 return 返回后方法结束执行，不会再执行 try 块中的 return 语句。
• 捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。说明：如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。
• 方法的返回值可以为 null ，不强制返回空集合，或者空对象等，必须添加注释充分说明什么情况下会返回 null 值。调用方需要进行 null 判断防止 NPE 问题。
  
  • 本规约明确防止 NPE 是调用者的责任。即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失败，运行时异常等场景返回 null 的情况。
• 防止 NPE ，是程序员的基本修养，注意 NPE 产生的场景：
  
  • 1 ） 返回类型为包装数据类型，有可能是 null ，返回 int 值时注意判空。
  • 反例： public int f() { return Integer 对象}; 如果为 null ，自动解箱抛 NPE 。
  • 2 ） 数据库的查询结果可能为 null 。
  • 3 ） 集合里的元素即使 isNotEmpty ，取出的数据元素也可能为 null 。
  • 4 ） 远程调用返回对象，一律要求进行 NPE 判断。
  • 5 ） 对于 Session 中获取的数据，建议 NPE 检查，避免空指针。
  • 6 ） 级联调用 obj . getA() . getB() . getC()； 一连串调用，易产生 NPE 。
• 在代码中使用“抛异常”还是“返回错误码”，对于公司外的 http / api 开放接口必须使用“错误码” ； 而应用内部推荐异常抛出 ； 跨应用间 RPC 调用优先考虑使用 Result 方式，封装 isSuccess 、“错误码”、“错误简短信息”。
  
  • 关于 RPC 方法返回方式使用 Result 方式的理由：
    
    • 1 ） 使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。
    • 2 ） 如果不加栈信息，只是 new 自定义异常，加入自己的理解的 error message ，对于调用端解决问题的帮助不会太多。
    • 如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输的性能损耗也是问题。
• 定义时区分 unchecked / checked 异常，避免直接使用 RuntimeException 抛出，更不允许抛出 Exception 或者 Throwable ，应使用有业务含义的自定义异常。
  
  • 推荐业界已定义过的自定义异常，如： DAOException / ServiceException 等。
• 避免出现重复的代码 （Don ’ t Repeat Yourself） ，即 DRY 原则。
  
  • 随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。必要时抽取共性方法，或者抽象公共类，甚至是共用模块。

日志规约

• 应用中不可直接使用日志系统 （Log 4 j 、 Logback） 中的 API ，而应依赖使用日志框架SLF4J中的API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。
• 日志文件推荐至少保存 15 天，因为有些异常具备以“周”为频次发生的特点。
• 应用中的扩展日志 （ 如打点、临时监控、访问日志等 ） 命名方式：appName _ logType _ logName . log 。 logType :
  
  • 日志类型，推荐分类有stats / desc / monitor / visit 等 ；logName :日志描述。
  • 这种命名的好处：通过文件名就可知道日志文件属于什么应用，什么类型，什么目的，也有利于归类查找。
  • 推荐对日志进行分类，错误日志和业务日志尽量分开存放，便于开发人员查看，也便于通过日志对系统进行及时监控。
• 对 trace / debug / info 级别的日志输出，必须使用条件输出形式或者使用占位符的方式。
  
  • logger . debug( ” Processing trade with id : ” + id + ” symbol : ” + symbol);如果日志级别是 warn ，上述日志不会打印，但是会执行字符串拼接操作，如果 symbol 是对象，会执行 toString() 方法，浪费了系统资源，执行了上述操作，最终日志却没有打印。
• 避免重复打印日志，浪费磁盘空间，务必在 log 4 j . xml 中设置 additivity = false 。
• 异常信息应该包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么往上抛。
• 可以使用 warn 日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所适从。注意日志输出的级别， error 级别只记录系统逻辑出错、异常等重要的错误信息。如非必要，请不要在此场景打出 error 级别。
• 谨慎地记录日志。生产环境禁止输出 debug 日志 ； 有选择地输出 info 日志 ； 如果使用 warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑爆，并记得及时删除这些观察日志。
  
  • 大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。
  • 记录日志时请思考：
    
    • 这些日志真的有人看吗？
    • 看到这条日志你能做什么？
    • 能不能给问题排查带来好处？

MySQL规约

建表规约

• 表达是与否概念的字段，必须使用 is _ xxx 的方式命名，数据类型是 unsigned tinyint（ 1 表示是，0 表示否 ） ，此规则同样适用于 odps 建表。
  
  • 任何字段如果为非负数，必须是 unsigned 。
• 表名、字段名必须使用小写字母或数字 ； 禁止出现数字开头，禁止两个下划线中间只出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。
• 表名不使用复数名词。
  
  • 表名应该仅仅表示表里面的实体内容，不应该表示实体数量，对应于 DO 类名也是单数形式，符合表达习惯。
• 禁用保留字，如 desc 、 range 、 match 、 delayed 等，请参考 MySQL 官方保留字。
• 唯一索引名为 uk 字段名 ； 普通索引名则为 idx 字段名。
  
  • uk _ 即 unique key；idx _ 即 index 的简称。
• 小数类型为 decimal ，禁止使用 float 和 double 。
  
  • float 和 double 在存储的时候，存在精度损失的问题，很可能在值的比较时，得到不正确的结果。如果存储的数据范围超过 decimal 的范围，建议将数据拆成整数和小数分开存储。
• 如果存储的字符串长度几乎相等，使用 char 定长字符串类型。
• varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长度大于此值，定义字段类型为 text ，独立出来一张表，用主键来对应，避免影响其它字段索引效率。
• 表必备三字段： id , gmt _ create , gmt _ modified 。
  
  • 其中 id 必为主键，类型为 unsigned bigint 、单表时自增、步长为 1。 gmt _ create ,gmt _ modified 的类型均为 date _ time 类型。
  • GMT 是指格林尼治时间，这样的话，就是会让表的数据和时间关联上，具有一定数据分析价值
• 表的命名最好是加上“业务名称_表的作用”。
  
  • 例如 ：tiger _ task / tiger _ reader / mpp _ config
• 库名与应用名称尽量一致。
• 如果修改字段含义或对字段表示的状态追加时，需要及时更新字段注释。
• 字段允许适当冗余，以提高性能，但是必须考虑数据同步的情况。冗余字段应遵循：
  
  • 1 ） 不是频繁修改的字段。
  • 2 ） 不是 varchar 超长字段，更不能是 text 字段。
  • 商品类目名称使用频率高，字段长度短，名称基本一成不变，可在相关联的表中冗余存储类目名称，避免关联查询。
• 单表行数超过 500 万行或者单表容量超过 2 GB ，才推荐进行分库分表。
  
  • 如果预计三年后的数据量根本达不到这个级别，请不要在创建表时就分库分表。
• 合适的字符存储长度，不但节约数据库表空间、节约索引存储，更重要的是提升检索速度。
  
  • 人的年龄用 unsigned tinyint（ 表示范围 0-255，人的寿命不会超过 255 岁 ）；
  • 海龟就必须是 smallint ，但如果是太阳的年龄，就必须是 int；
  • 如果是所有恒星的年龄都加起来，那么就必须使用 bigint 。

索引规约

• 业务上具有唯一特性的字段，即使是组合字段，也必须建成唯一索引。
  
  • 不要以为唯一索引影响了 insert 速度，这个速度损耗可以忽略，但提高查找速度是明显的 ；
  • 另外，即使在应用层做了非常完善的校验和控制，只要没有唯一索引，根据墨菲定律，必然有脏数据产生。
• 超过三个表禁止 join 。需要 join 的字段，数据类型保持绝对一致 ； 多表关联查询时，保证被关联的字段需要有索引。
  
  • 即使双表 join 也要注意表索引、 SQL 性能。
• 在 varchar 字段上建立索引时，必须指定索引长度，没必要对全字段建立索引，根据实际文本区分度决定索引长度。
  
  • 索引的长度与区分度是一对矛盾体，一般对字符串类型数据，长度为 20 的索引，区分度会高达 90%以上，
  • 可以使用 count(distinct left( 列名, 索引长度 )) / count( * ) 的区分度来确定。
• 页面搜索严禁左模糊或者全模糊，如果需要请走搜索引擎来解决。
  
  • 索引文件具有 B - Tree 的最左前缀匹配特性，如果左边的值未确定，那么无法使用此索引。
• 如果有 order by 的场景，请注意利用索引的有序性。 order by 最后的字段是组合索引的一部分，
  
  • 并且放在索引组合顺序的最后，避免出现 file _ sort 的情况，影响查询性能。
  • where a =? and b =? order by c; 索引： a_b_c
• 利用覆盖索引来进行查询操作，来避免回表操作。
  
  • 能够建立索引的种类：主键索引、唯一索引、普通索引，而覆盖索引是一种查询的一种效果，用 explain 的结果， extra 列会出现： using index 。
  • 覆盖索引是select的数据列只用从索引中就能够取得，不必读取数据行，换句话说查询列要被所建的索引覆盖。
  • 理解方式一：索引是高效找到行的一个方法，但是一般数据库也能使用索引找到一个列的数据，因此它不必读取整个行。毕竟索引叶子节点存储了它们索引的数据；当能通过读取索引就可以得到想要的数据，那就不需要读取行了。一个索引包含了（或覆盖了）满足查询结果的数据就叫做覆盖索引
  • 理解方式二：是非聚集复合索引的一种形式，它包括在查询里的Select、Join和Where子句用到的所有列（即建索引的字段正好是覆盖查询条件中所涉及的字段，也即，索引包含了查询正在查找的数据）。
  • 如果一本书需要知道第 11 章是什么标题，会翻开第 11 章对应的那一页吗？目录浏览一下就好，这个目录就是起到覆盖索引的作用。
• 利用延迟关联或者子查询优化超多分页场景。
• MySQL 并不是跳过 offset 行，而是取 offset + N 行，然后返回放弃前 offset 行，返回N 行，
  
  • 那当 offset 特别大的时候，效率就非常的低下，要么控制返回的总页数，要么对超过特定阈值的页数进行 SQL 改写。
  • 先快速定位需要获取的 id 段，然后再关联：
• SQL 性能优化的目标：至少要达到 range 级别，要求是 ref 级别，如果可以是 consts最好。
  
  • 1 ）consts 单表中最多只有一个匹配行 （ 主键或者唯一索引 ） ，在优化阶段即可读取到数据。
  • 2 ）ref 指的是使用普通的索引 （normal index） 。
  • 3 ）range 对索引进行范围检索。
  • explain 表的结果， type = index ，索引物理文件全扫描，速度非常慢，这个 index 级别比较 range 还低，与全表扫描是小巫见大巫。
• 建组合索引的时候，区分度最高的在最左边。
  
  • 如果 where a =? and b =? ， a 列的几乎接近于唯一值，那么只需要单建 idx _ a 索引即可。
  • 存在非等号和等号混合判断条件时，在建索引时，请把等号条件的列前置。如： where a >?and b =? 那么即使 a 的区分度更高，也必须把 b 放在索引的最前列。
• 创建索引时避免有如下极端误解：
  
  • 1 ） 误认为一个查询就需要建一个索引。
  • 2 ） 误认为索引会消耗空间、严重拖慢更新和新增速度。
  • 3 ） 误认为唯一索引一律需要在应用层通过“先查后插”方式解决。

SQL规约

• 不要使用 count( 列名 ) 或 count( 常量 ) 来替代 count( * ) ， count( * ) 就是 SQL 92 定义的标准统计行数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。
  
  • count( * ) 会统计值为 NULL 的行，而 count( 列名 ) 不会统计此列为 NULL 值的行。
• count(distinct col) 计算该列除 NULL 之外的不重复数量。注意 count(distinct col 1, col 2 ) 如果其中一列全为 NULL ，那么即使另一列有不同的值，也返回为 0。
• 当某一列的值全是 NULL 时， count(col) 的返回结果为 0，但 sum(col) 的返回结果为NULL ，因此使用 sum() 时需注意 NPE 问题。
  
  • 可以使用如下方式来避免 sum 的 NPE 问题： SELECT IF(ISNULL(SUM(g)) ,0, SUM(g))FROM table;
• 使用 ISNULL() 来判断是否为 NULL 值。注意： NULL 与任何值的直接比较都为 NULL。
  
  • 1 ） NULL<>NULL 的返回结果是 NULL ，而不是 false 。
  • 2 ） NULL=NULL 的返回结果是 NULL ，而不是 true 。
  • 3 ） NULL<>1 的返回结果是 NULL ，而不是 true 。
• 在代码中写分页查询逻辑时，若 count 为 0 应直接返回，避免执行后面的分页语句。
• 不得使用外键与级联，一切外键概念必须在应用层解决。
  
  • （ 概念解释 ） 学生表中的 student _ id 是主键，那么成绩表中的 student _ id 则为外键。如果更新学生表中的 student _ id ，同时触发成绩表中的 student _ id 更新，
  • 则为级联更新。外键与级联更新适用于单机低并发，不适合分布式、高并发集群 ； 级联更新是强阻塞，存在数据库更新风暴的风险 ； 外键影响数据库的插入速度。
• 禁止使用存储过程，存储过程难以调试和扩展，更没有移植性。
• 数据订正时，删除和修改记录时，要先 select ，避免出现误删除，确认无误才能执行更新语句。
• in 操作能避免则避免，若实在避免不了，需要仔细评估 in 后边的集合元素数量，控制在 1000 个之内。
• 如果有全球化需要，所有的字符存储与表示，均以 utf -8 编码，那么字符计数方法
  
  • 注意：
  • SELECT LENGTH( “轻松工作” )； 返回为 12
  • SELECT CHARACTER _ LENGTH( “轻松工作” )； 返回为 4
  • 如果要使用表情，那么使用 utfmb 4 来进行存储，注意它与 utf -8 编码的区别。
• TRUNCATE TABLE 比 DELETE 速度快，且使用的系统和事务日志资源少，但 TRUNCATE无事务且不触发 trigger ，有可能造成事故，故不建议在开发代码中使用此语句。
  
  • TRUNCATE TABLE 在功能上与不带 WHERE 子句的 DELETE 语句相同。

ORM规约

• 在表查询中，一律不要使用 * 作为查询的字段列表，需要哪些字段必须明确写明。
  
  • 1 ） 增加查询分析器解析成本。
  • 2 ） 增减字段容易与 resultMap 配置不一致。
• POJO 类的 boolean 属性不能加 is ，而数据库字段必须加 is _，要求在 resultMap 中进行字段与属性之间的映射。
• 不要用 resultClass 当返回参数，即使所有类属性名与数据库字段一一对应，也需要定义 ； 反过来，每一个表也必然有一个与之对应。
• 配置映射关系，使字段与 DO 类解耦，方便维护。
• xml 配置中参数注意使用：#{}，# param # 不要使用${} 此种方式容易出现 SQL 注入。
• iBATIS 自带的 queryForList(String statementName , int start , int size) 不推荐使用。
• 其实现方式是在数据库取到 statementName 对应的 SQL 语句的所有记录，再通过 subList取 start , size 的子集合，线上因为这个原因曾经出现过 OOM 。
  
  • 在 sqlmap . xml 中引入 #start#, #size#
  • Map

工程规约

应用分层

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

二方库规约

• 定义 GAV 遵从以下规则：
  
  • GroupID 格式： com .{公司/ BU }.业务线. [ 子业务线 ] ，最多 4 级。
    
    • {公司/ BU } 例如： alibaba / taobao / tmall / aliexpress 等 BU 一级 ； 子业务线可选。
    • com . taobao . jstorm 或 com.alibaba.dubbo.register
  • ArtifactID 格式：产品线名-模块名。语义不重复不遗漏，先到仓库中心去查证一下。
    
    • dubbo - client / fastjson - api / jstorm - tool
  • Version ：详细规定参考下方。
• 二方库版本号命名方式：主版本号.次版本号.修订号
  
  • 1 ） 主版本号 主版本号：当做了不兼容的 API 修改，或者增加了能改变产品方向的新功能。
  • 2 ） 次版本号 次版本号：当做了向下兼容的功能性新增 （ 新增类、接口等 ） 。
  • 3 ） 修订号 修订号：修复 bug ，没有修改方法签名的功能加强，保持 API 兼容性。
  • 起始版本号必须为： 1.0.0 ，而不是 0.0.1
• 线上应用不要依赖 SNAPSHOT 版本 （ 安全包除外 ）； 正式发布的类库必须使用 RELEASE版本号升级+1 的方式，且版本号不允许覆盖升级，必须去中央仓库进行查证。
  
  • 不依赖 SNAPSHOT 版本是保证应用发布的幂等性。另外，也可以加快编译时的打包构建。
• 二方库的新增或升级，保持除功能点之外的其它 jar 包仲裁结果不变。如果有改变，必须明确评估和验证，
  
  • 建议进行 dependency : resolve 前后信息比对，如果仲裁结果完全不一致，那么通过 dependency : tree 命令，找出差异点，进行< excludes >排除 jar 包。
• 二方库里可以定义枚举类型，参数可以使用枚举类型，但是接口返回值不允许使用枚举类型或者包含枚举类型的 POJO 对象。
• 依赖于一个二方库群时，必须定义一个统一版本变量，避免版本号不一致。
  
  • 依赖 springframework - core ,- context ,- beans ，它们都是同一个版本，可以定义一个变量来保存版本：
  • ${ spring . version }，定义依赖的时候，引用该版本。
• 禁止在子项目的 pom 依赖中出现相同的 GroupId ，相同的 ArtifactId ，但是不同的Version 。
• 在本地调试时会使用各子项目指定的版本号，但是合并成一个 war ，只能有一个版本号出现在最后的 lib 目录中。
  
  • 曾经出现过线下调试是正确的，发布到线上出故障的先例。
• 所有 pom 文件中的依赖声明放在< dependencies >语句块中，所有版本仲裁放在< dependencyManagement >语句块中。
  
  • < dependencyManagement >里只是声明版本，并不实现引入，因此子项目需要显式的声明依赖， version 和 scope 都读取自父 pom 。
  • 而< dependencies >所有声明在主 pom 的< dependencies >里的依赖都会自动引入，并默认被所有的子项目继承。
• 二方库尽量不要有配置项，最低限度不要再增加配置项。
• 为避免应用二方库的依赖冲突问题，二方库发布者应当遵循以下原则：
  
  • 1 ） 精简可控原则。移除一切不必要的 API 和依赖，只包含 Service API 、必要的领域模型对象、 Utils 类、常量、枚举等。
    
    • 如果依赖其它二方库，尽量是 provided 引入，让二方库使用者去依赖具体版本号 ； 无 log 具体实现，只依赖日志框架。
  • 2 ） 稳定可追溯原则。每个版本的变化应该被记录，二方库由谁维护，源码在哪里，都需要能方便查到。除非用户主动升级版本，否则公共二方库的行为不应该发生变化。

服务器规约

• 高并发服务器建议调小 TCP 协议的 time _ wait 超时时间。
  
  • 操作系统默认 240 秒后，才会关闭处于 time _ wait 状态的连接，
  • 在高并发访问下，服务器端会因为处于 time _ wait 的连接数太多，可能无法建立新的连接，所以需要在服务器上调小此等待值。
    
    • 在 linux 服务器上请通过变更/ etc / sysctl . conf 文件去修改该缺省值 （ 秒 ） ：net . ipv 4. tcp _ fin _ timeout = 30
• 调大服务器所支持的最大文件句柄数 （File Descriptor ，简写为 fd） 。
  
  • 主流操作系统的设计是将 TCP / UDP 连接采用与文件一样的方式去管理，即一个连接对应于一个 fd 。
  • 主流的 linux 服务器默认所支持最大 fd 数量为 1024，当并发连接数很大时很容易因为 fd 不足而出现“ open too many files ”错误，导致新的连接无法建立。
  • 建议将 linux服务器所支持的最大句柄数调高数倍 （ 与服务器的内存数量相关 ）
• 给 JVM 设置- XX :+ HeapDumpOnOutOfMemoryError 参数，让 JVM 碰到 OOM 场景时输出dump 信息。
  
  • OOM 的发生是有概率的，甚至有规律地相隔数月才出现一例，出现时的现场信息对查错非常有价值。
• 服务器内部重定向使用 forward； 外部重定向地址使用 URL 拼装工具类来生成，否则会带来 URL 维护不一致的问题和潜在的安全风险。

安全规约

• 隶属于用户个人的页面或者功能必须进行权限控制校验。
  
  • 防止没有做水平权限校验就可随意访问、操作别人的数据，比如查看、修改别人的订单。
• 用户敏感数据禁止直接展示，必须对展示数据脱敏。
  
  • 查看个人手机号码会显示成:158****9119，隐藏中间 4 位，防止隐私泄露。
• 用户输入的 SQL 参数严格使用参数绑定或者 METADATA 字段值限定，防止 SQL 注入，禁止字符串拼接 SQL 访问数据库。
• 用户请求传入的任何参数必须做有效性验证。
  
  • 忽略参数校验可能导致：
    
    • page size 过大导致内存溢出
    • 恶意 order by 导致数据库慢查询
    • 任意重定向
    • SQL 注入
    • 反序列化注入
    • 正则输入源串拒绝服务 ReDoS
  • Java 代码用正则来验证客户端的输入，有些正则写法验证普通用户输入没有问题，但是如果攻击人员使用的是特殊构造的字符串来验证，有可能导致死循环的效果。
• 禁止向 HTML 页面输出未经安全过滤或未正确转义的用户数据。
• 表单、 AJAX 提交必须执行 CSRF 安全过滤。
  
  • CSRF(Cross - site request forgery) 跨站请求伪造是一类常见编程漏洞。对于存在CSRF 漏洞的应用/网站，
  • 攻击者可以事先构造好 URL ，只要受害者用户一访问，后台便在用户不知情情况下对数据库中用户参数进行相应修改。
  • 个人理解 就是使用的ajax可以在别的网站得到使用，而且构造好了改你的密码，又伪装成别的，就等着获取你的用户名，然后就能立即更改你的密码，所以进行Session校验应该就能防范，还有好多种情况吧，这只是其中一种
• 在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放限制，如数量限制、疲劳度控制、验证码校验，避免被滥刷、资损。
  
  • 如注册时发送验证码到手机，如果没有限制次数和频率，那么可以利用此功能骚扰到其它用户，并造成短信平台资源浪费。
• 发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过滤等风控策略。

注意

• 安全意识很重要，不然毫无实际意义
• NPE是空指针异常
• OOM是内存溢出