开发规范

开发规范
一、编程规约

1. 命名规范
   1）通用：

		1. A. 命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束
		2. B. 代码中的命名，尽量避免使用拼音与英文混合的方式，更不允许直接使用中文的方式
		3. C. 杜绝完全不规范的缩写，避免望文不知义。如：condition“缩写”命名成 condi

1）类,接口:
1. XXXController, XXXBussiness，XXXBussinessImpl，XXXDao，XXXDaoImpl
2）方法:

3. 增：save/insertObject(Object)
4. 删：delete/removeXXXByIdByNameByTime(id, name, time)
5. 改：updateXXXByIdByNameByTime(id, name, time)
6. 查：get/searchXXXByIdByNameByTime(id, name, time)

3. 变量：
   A. lowerCamelCase风格
   B. 见名知意，不要怕长
   4）常量：
   A. 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长
   B. 如果变量值仅在一个固定范围内变化用enum类型来定义
   5）枚举：
   1. 枚举类名建议带上Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开
   2. 代码风格引入统一模版(https://gitee.com/yiyiTeam/mayijixiao/docs/目录下，两个xml文件，直接导入到"Winidow -> Preferences -> Java -> Code Style”下的Code Template 和 Formatter )

OOP规约1）接口过时必须加@Deprecated注解，并清晰地说明采用的新接口或者新服务是什么2）不能使用过时的类或方法3）Object的equals方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals；正例：”test”.equals(object); 反例：object.equals(“test”);4）所有的相同类型的包装类对象之间值的比较，全部使用equals方法比较5）构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在init方法中6）使用索引访问用String的split方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛IndexOutOfBoundsException的风险7）慎用Object的clone方法来拷贝对象。 说明：对象的clone方法默认是浅拷贝，若想实现深拷贝需要重写clone方法实现域对象的深度遍历式拷贝
4.
集合处理1）关于hashCode和equals的处理，遵循如下规则：

	1. 1） 只要重写equals，就必须重写hashCode。
	2. 2） 因为Set存储的是不重复的对象，依据hashCode和equals进行判断，所以Set存储的对象必须重写这两个方法。
	3. 3） 如果自定义对象作为Map的键，那么必须重写hashCode和equals。

2）ArrayList的subList结果不可强转成ArrayList，否则会抛出ClassCastException异常3）使用集合转数组的方法，必须使用集合的toArray(T[] array)，传入的是类型完全一样的数组，大小就是list.size()。4）使用工具类Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的add/remove/clear方法会抛出UnsupportedOperationException异常5）不要在foreach循环里进行元素的remove/add操作。remove元素请使用Iterator方式，如果并发操作，需要对Iterator对象加锁6）使用entrySet遍历Map类集合KV，而不是keySet方式进行遍历 5.
并发处理1）获取单例对象需要保证线程安全，其中的方法也要保证线程安全。2）创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。

	1. public class TimerTaskThread extends Thread {
	2. public TimerTaskThread() {
	3. super.setName("TimerTaskThread");
	4. ...
	5. }
	6. }

3）线程资源必须通过线程池提供，不允许在应用中自行显式创建线程4）线程池不允许使用 Executors ExecutorsExecutors去创建，规避资源耗尽风险5）SimpleDateFormat 是线程不安全的类，一般不要定义为static变量，如果定义为static，必须加锁，或者使用DateUtils工具类
1. 说明：如果是JDK8的应用，可以使用Instant代替Date，LocalDateTime代替Calendar，DateTimeFormatter代替SimpleDateFormat，官方给出的解释：simple beautiful strong immutable thread-safe。
6）高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁；能锁区块，就不要锁整个方法体；能用对象锁，就不要用类锁。7）对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁8）多线程并行处理定时任务时，使用ScheduledExecutorService，不用Timer9）HashMap在容量不够进行resize时由于高并发可能出现死链，导致CPU飙升，在开发过程中可以使用其它数据结构或加锁来规避此风险 6.
控制语句1）在if/else/for/while/do语句中必须使用大括号。即使只有一行代码，避免采用单行的编码方式：if (condition) statements;2）并发环境中，避免使用==作为退出标志，如果并发控制没有处理好，容易产生等值判断被 “击穿 ”的情况，使用大于或小区间的情况判断条件来代替。3) 循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的try-catch操作（这个try-catch是否可以移至循环体外）
7.
注释规约1) 类、类属性、类方法的注释必须使用Javadoc规范，使用/**内容/格式，不得使用// xxx方式。2) 所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能3) 所有的类都必须添加创建者和创建日期。4) 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/ /注释，注意与代码对齐5) 代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改6) 重要变量，重要分支逻辑要加注释，进行解释说明
8.
其他1) 获取当前毫秒数System.currentTimeMillis(); 而不是new Date().getTime();在JDK8中，针对统计时间等场景，推荐使用Instant类。2) controller 里只做参数检查，和异常处理，不做任何业务逻辑的处理3）及时清理不再使用的代码段或配置信息。对于垃圾代码或过时配置，坚决清理干净，避免程序过度臃肿，代码冗余

二、异常日志
1.
异常处理1）dao、business层的异常抛到controller层统一处理2）捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。3）finally块必须对资源对象、流对象进行关闭，有异常也要做try-catch4）避免直接抛出new RuntimeException()，更不允许抛出Exception或者Throwable，应使用有业务含义的自定义异常。推荐业界已定义过的自定义异常，如：DAOException / ServiceException等。如无已有异常，可在exception包内，自定义异常
2.
日志规约1）生产环境禁止使用system.out2) 应用中不可直接使用日志系统（Log4j、Logback）中的API，而应依赖使用日志框架SLF4J中的API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一3) 避免重复打印日志，浪费磁盘空间，务必在log4j.xml中设置additivity=false4) 异常信息应该包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么通过关键字throws往上抛出。

	1. 正例：logger.error(各类参数或者对象toString() + "_" + e.getMessage(), e);

三、数据库
1.
建表规约1）表达是与否概念的字段，必须使用 is_xxx的方式命名，数据类型是 的方式命名，数据类型是 的方式命名，数据类型是 unsigned tinyint（1表示是， 0表示否）。2）表名、字段名必须使用小写字母或数字，禁止出现数字开头3）表名不使用复数名词4）禁用保留字，如desc、range、match、delayed等，请参考MySQL官方保留字5）主键索引名为pk字段名；唯一索引名为uk字段名；普通索引名则为idx_字段名6）小数类型为decimal，禁止使用float和double7）库名与应用名称尽量一致8）如果修改字段含义或对字段表示的状态追加时，需要及时更新字段注释9）字段允许适当冗余，以提高查询性能，但必须考虑数据一致。冗余字段应遵循：

	1. A. 不是频繁修改的字段
	2. B.不是varchar超长字段，更不能是text字段。

10. 单表行数超过500万行或者单表容量超过2GB，才推荐进行分库分表。
    1. 说明：如果预计三年后的数据量根本达不到这个级别，请不要在创建表时就分库分表

索引规约1) 业务上具有唯一特性的字段，即使是多个字段的组合，也必须建成唯一索引2) 超过三个表禁止join。需要join的字段，数据类型必须绝对一致；多表关联查询时，保证被关联的字段需要有索引3) 在varchar字段上建立索引时，必须指定索引长度，没必要对全字段建立索引，根据实际文本区分度决定索引长度即可4) 页面搜索严禁左模糊或者全模糊，如果需要请走搜索引擎来解决5) 如果有order by的场景，请注意利用索引的有序性。order by 最后的字段是组合索引的一部分，并且放在索引组合顺序的最后，避免出现file_sort的情况，影响查询性能。

	1. 正例：where a=? and b=? order by c; 索引：a_b_c

6. 建组合索引的时候，区分度最高的在最左边7) 创建索引时避免有如下极端误解：
   1. A. 宁滥勿缺。认为一个查询就需要建一个索引。
   2. B. 宁缺勿滥。认为索引会消耗空间、严重拖慢更新和新增速度。
   3. C. 抵制惟一索引。认为业务的惟一性一律需要在应用层通过“先查后插”方式解决。

SQL语句1) 不要使用count(列名)或count(常量)来替代count()，count()是SQL92定义的标准统计行数的语法，跟数据库无关，跟NULL和非NULL无关。

	1. 说明：count(*)会统计值为NULL的行，而count(列名)不会统计此列为NULL值的行。

2. 不得使用外键与级联，一切外键概念必须在应用层解决3) 禁止使用存储过程，存储过程难以调试和扩展，更没有移植性4) 数据订正（特别是删除、修改记录操作）时，要先select，避免出现误删除，确认无误才能执行更新语句。5) in操作能避免则避免，若实在避免不了，需要仔细评估in后边的集合元素数量，控制在1000个之内。