JAVA 开发规范

JAVA 开发规范

JAVA编程遵循的通用原则：

• 清晰第一、易于维护、易于重构。
• 简洁为美、易于理解、易于实现。
• 选择合适的风格，团队保持一致。

一、全局命名

基本常识

定义合法标识符的规则

• 由26个英文字母大小写，0-9，_或$组成
• 数字不可以开头
• 不可以使用关键字和保留字，但是能包括关键字和保留字
• Java中严格区分大小写，长度无限制
• 标识符不能包括空格
• 取名尽量做到"见名知意"
• 坚决不允许出现中文

驼峰命名法（Camel-Case）:

当变量名或函式名是由一个或多个单字连结在一起，而构成的唯一识别字时，首字母以小写开头，每个单词首字母大写（第一个单词除外）。

命名规则

1. 包名 xxxyyyzzz

**要求: 全部小写 **

命名应该都是名词或名词性词组，全部小写，单词之间用"."分开;一般使用本公司／组织网站域名的逆序后跟具体的软件内部模块名

   正例:
   com.gongzhi.user.controller
   com.gongzhi.user.service
   com.gongzhi.user.service.impl
   com.gongzhi.user.dao
   com.gongzhi.user.model
   com.gongzhi.util
   com.gongzhi.vo
   com.gongzhi.dto
   com.zlb
   com.zlb.activity
   com.zhaolaobao.activity
   com.zlb.attr
   com.zlb.userrule
   反例:
   com.zlb.userRule
   com.zlb.user_rule

2. 类(接口)名 XxxYyyZzz

要求: 首字母大写，如果类名由多个单词组成，每个单词的首字母都要大写。

类名使用 UpperCamelCase 风格，必须遵从驼峰形式，但以下情形例外：（领域模型的相关命名）DO / BO / DTO / VO / AO

正例:
public class MyFirstClass{
   }
public interface MessageService{
   }
反例:
public class userService{
   }


正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

接口的实现类,在类的后面加上"Impl"

Exception类用"Exception"做为类命名的结尾,例如：DataNotFoundException；

抽象类用"Abstract"做为类命名的开头,例如：AbstractBeanDefinition,AbstractBeanFactory；

Test类用"Test"做为类命名的结尾。例如：ContainerTest;

3. **变量名、方法名 ** xxxYyyZzz

要求: 首字母小写，如果名称由多个单词组成，每个单词的首字母都要大写。(驼峰式)

除非是在循环中，否则一般不推荐使用单个字母作为变量名，i、j、k等只作为小型循环的循环索引变量。

方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从 驼峰形式。

Model 类中布尔类型的变量，都不要加 is，否则部分框架解析会引起序列化错误。

反例：定义为基本数据类型 Boolean isDeleted；的属性，它的方法也是 isDeleted()，RPC框架在反向解析的时候，“以为”对应的属性名称是 deleted，导致属性获取不到，进而抛出异常。

request response 变量名尽量与数据库一致(驼峰式)**

代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。

代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。(尽量避免使用纯拼音命名方式)

变量:
//普通变量
int index = 0;
String localValue = null;
//魔法数字
Product product1 = new Product();
Product product2 = new Product();
//根据对象生成变量名称
List<Order> orderList = new ArrayList<>();
List<Order> order = new ArrayList<>();
//变量名对应数据库列名 (不同模块代码不是同一个后端编写,但是传给前端的变量名称一致)
Date createTime;  //变量名
timestamp NOTNULL create_time //数据库列名
//代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束    
反例： _name / __name / $Object / name_ / name$ / Object$    

方法:
public void toString(){
   }
public void setName(String name){
   }
public void getHttpMessage(){
   } 
public void inputUserId(){
   }

Service/DAO 层方法命名规约，统一前缀。

1. 获取单个对象的方法用 get,find 做前缀。
2. 获取多个对象的方法用 list 做前缀/后缀。
3. 获取统计值的方法用 count 做前缀。
4. 插入的方法用 save（推荐）或 insert ,add、create做前缀。
5. 删除的方法用 remove（推荐）或 delete 做前缀。
6. 修改的方法用 update 做前缀。
7. 搜索性查询方法前缀：query、search。
8. 批量插入方法用 insertBatch做前缀.

声明数组

//建议使用
int[] arrays = new int[1024];
//不建议使用
int arrays[] = new int[1024];

4.常量名 全部大写 XXX_YYY_ZZZ

**常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。 **

public static final String GAME_COLOR=”RED”;

常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包
内共享常量、类内共享常量。
跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。
应用内共享常量：放置在一方库的 modules 中的 constant 目录下。
反例：易懂变量也要统一定义成应用内共享常量，两位攻城师在两个类中分别定义 了
表示“是”的变量：
类 A 中：public static final String YES = “yes”;
类 B 中：public static final String YES = “y”;
A.YES.equals(B.YES)，预期是 true，但实际返回为 false，导致产生线上问题。
子工程内部共享常量：即在当前子工程的 constant 目录下。
包内共享常量：即在当前包下单独的 constant 目录下。
类内共享常量：直接在类内部 private static final 定义。

二、代码格式

基本常识

类中不要出现无用import，可以采用IDE工具进行优化，类提交前进行代码的格式化；
代码格式以开发工具默认为准,提交SVN代码前,先 ctrl + alt + L 格式化代码;
IDE 的 text file encoding 设置为 UTF-8; IDE 中文件的换行符使用 Unix 格式，
不要使用 windows 格式
一个程序(java)文件最好不要超过２０００行;

一个方法所完成的功能要单一(单一职责原则),不同的功能封装为不同的方法;

三、注释

基本常识

类、类属性、类方法的注释必须使用 Javadoc 规范，使用/内容/格式，不得使用
//xxx 方式。
说明：在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注
释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高
阅读效率
方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释
使用/ */注释，注意与代码对齐。
所有的类都必须添加创建者信息
与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持
英文原文即可。
反例：“TCP 连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。
代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑
等的修改。
说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，
就失去了导航的意义。
特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，
经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
1 待办事宜（TODO）:（ 标记人，标记时间，[预计处理时间]）
表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc
还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc 标签）。
2 错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]）
在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。

注释三种方式

• 单选注释：符号是：//

• 块注释： 符号是： /* */ 可以跨多行

• javadoc注释： 符号是： /** */ 可以跨多行，

  生成javadoc时，这样的注释会被生成标准的javaapi注释。

使用场景

类注释

/**
 * @author 毛海涛
 * @create 2017-11-14 10:42
 * @DESCRIPTION 后台用户登录
 **/
@Api(tags = "登陆模块", description = "登陆模块API文档")
@RestController
@RequestMapping(value