java编码规范

编码规范

编制日期：2017年11月

1. 目录

绪论 .......................................................................................................................................................3 1.1. 目的 ...................................................................................................................................................3 1.2. 概述 ...................................................................................................................................................3 1.3. 优良代码的特点 ............................................................................................................................3 1.4. 适用范围 ..........................................................................................................................................4 总体架构 ..............................................................................................................................................4 2.1. 框架概述 ..........................................................................................................................................4 2.2. 框架规范 ..........................................................................................................................................5 2.2.1. DAO规范 ...................................................................................................................................5 2.2.2. Service规范 ...............................................................................................................................7 2.2.3. Controller层规范 .....................................................................................................................7 代码规范 ..............................................................................................................................................9 3.1. Java相关命名 ................................................................................................................................9 3.1.1. 包命名 ..........................................................................................................................................9 3.1.2. 类命名规范 ................................................................................................................................9 3.1.3. 方法命名 .................................................................................................................................. 10 3.1.4. 字段命名 .................................................................................................................................. 11 3.1.5. 变量 ........................................................................................................................................... 11 3.1.6. 常量命名 .................................................................................................................................. 11 3.1.7. 属性文件.properties定义变量命名 ................................................................................ 11 3.1.8. JSP文件命名 .......................................................................................................................... 12 3.1.9. JS文件命名 ............................................................................................................................. 12 3.1.10. 资源文件命名 ......................................................................................................................... 12 3.2. 有关注释 ....................................................................................................................................... 12 3.3.1. 程序文件头注释 .................................................................................................................... 12 3.3.2. 方法头注释 ............................................................................................................................. 13 3.3.3. 关键点注释 ............................................................................................................................. 13 格式规范 ........................................................................................................................................... 14 4.1. 缩进 ................................................................................................................................................ 14 4.2. 换行 ................................................................................................................................................ 14 写在后面 ........................................................................................................................................... 14

版本说明 版本 初始版 作者 秦绪海 日期 2017-11-30 备注 提出初始版本，分发各相关人员 绪论

1.1. 目的

为了使软件开发过程顺畅，保证软件质量，于是有了这份开发规范文档。

1.2. 概述

 项目以功能模块来划分分工

 数据库不能随意修改，本地数据库须统一  有标准的Java代码风格，有良好习惯  时刻考虑代码的可复用性  每个人需要有每周项目进度报告

1.3. 优良代码的特点

任何的软件设计中，都离不开编程实现。在软件实现中，除了程序架构设计、数据结构设计、算法的设计以外，还有具体的代码的编写规范问题。

好的代码应该具有以下的特征：

 准确性：保证程序运行稳定、正确，不容易出错  简单性：程序代码容易管理

 清晰性：程序容易理解，无论对人还是计算机

 普遍性：在很广泛的情况下都能工作的很好，也容易做修改以适应新出现的情况

1.4. 适用范围

本规范适用于本公司(上海奇搜网络科技)所有软件项目、产品等的设计、开发以及维护、升级等。

本公司所有软件开发人员在整个软件开发过程中必须遵循此规范。

总体架构

2.1. 框架概述

本公司开发的软件产品多为B/S结构，涉及多个层面的开发，为便于逻辑分离及项目分工，本公司开发的软件产品应当符合MVC设计模式。新框架由相互协作的三层组件(DAO、Service、Controller)构成。DAO、Service如图2.1所示，Controller如2.2所示

图2.1

图2.2

2.2. 框架规范

2.2.1. DAO规范

DAO为持久层，用于访问持久性数据，例如为关系型数据库。规定要求必须每一个实体对象建立一套DAO入口类。如图2.3所示

DAO层类：

 model：object 持久对象,可以看成是与数据库中的表相映射的java对象，属性

和表结构对应。

 mapper：MyBatis接口类，与mapper.xml配置到一起。

 mapper.xml：MyBatis的SQL Map配置文件。我们将在这里编写SQL语句，

并将这些SQL语句与对象的方法配置到一起。

图2.3

每个Mapper要求实现5个Base方法如图2.4所示

图2.4

2.2.2. Service规范

Service为服务层，主要负责业务逻辑开发，要求每一个Bean建立一套Service入口类。禁止service层依赖于request等Web对象，便于servcie层可以脱离于Web应用。如图2.5所示

Service层类：

 service类：服务层接口类。  serviceImpl类：服务层实现类。

 DTO类：数据传输对象，用于展示层与服务层之间的数据传输对象。

图2.5

2.2.3. Controller层规范

Controller为展示层，负责具体的业务模块流程的控制，在此层里面要调用Service层的接口来控制业务流程。控制的配置通过SpringMvc注解的方式进行。Controller类

都必须直接继承类BaseController，对request、session、response的操作必须使用BaseController中封装的的方法进行操作。控制权限通过权限注解方式进行。如图2.6所示

Controller层类：

 Controller类：展示层类。  VO类：视图对象，用于展示层。 权限注解：

 @HasAllPermissions：判断当前用户是否拥有其中所有的权限（逗号分隔，表

示“与”的关系）

 @HasAnyPermissions：判断当前用户是否拥有其中某一种权限（逗号分隔，表

示“或”的关系）

 @HasPermissions：判断当前用户是否拥有某种权限  @HasRoles：判断当前用户是否拥有某种角色  @Authenticated：判断当前用户是否已认证

 @Guest：判断当前用户是否未登录（包括：未认证 或 未记住，即“访客”身

份）

 @User：判断当前用户是否已登录（包括：已认证 与 已记住）

图2.6

代码规范

3.1. Java相关命名

尽量保证能够通过变量名得知变量的含义

3.1.1. 包命名

 包命名采用全小写命名

 通过唯一域名+项目名+模块名+组件来命名 比如：

com.pz.call.outbound.controller 3.1.2. 类命名规范

类和接口表示一类对象，必须以名词命名。类名的第一个字母必须大写，类名如由多个单词(或缩写)构成，则每个单词(缩写)的头一个字母必须大写。 为统一起见，对我司的框架中出现的七种类做出进一步规定，如下：

 DAO类：以“DAO”三个大写字母结尾，如SystemUserDAO；  Service类：以“Service”结尾，如SystemUserService；

 ServiceImpl类：以“ServiceImpl”结尾，如SystemUserServiceImpl；  model类：首字母大写，如SystemUser；  VO类：以“VO”结尾，如SystemUserVO；  DTO类：以“DTO”结尾，如SystemUserDTO；

 Controller类：以“Controller”结尾，如SystemUserController；

上述七个示例类对应表system_user，类(接口)名和表名的对应关系为：表名第一个字母为大写，后续字母为小写，直到遇到下划线“_”，下划线“_”不出现在类名中，下划线“_”紧跟的字母为大写，后续字母为小写，以此类推。

对于不需要单独维护或查询的表，可以不需要写对应的Controller、Service、VO、DTO类，但其他俩类应当提供，由其他的service类调用。

3.1.3. 方法命名

方法表示一种行为，它代表一种动作，最好是一个动词或者动词词组或者第一个单词为一个动词。

 方法命名采用Camel命名法  小写字母开头，各个单词首字母大写

 属性的getter和setter方法尽量使用自动生成，并放在程序的后面。  Boolean类型返回值的方法应形如isProperty()

DAO层方法，只能以insert（插入）,delete（删除）,update（更新）,select（查找）开头，其他层方法避免以这个5个单词开头，以免造成误解。

Service方法，根据方法的行为命名，只描述方法的意义，而不采用方法的目的命名。比如系统的添加新用户，用户可以前台注册，也可以管理员后台添加，方法会被重用，所以最好不要用使用register，采用create会更好写。避免使用与web层相关的方法。

Controller层方法最好是贴近web的语言，如register，login，logout等方法。

3.1.4. 字段命名

类中的字段表示类的一个属性或标志，同样也必须以名词命名。字段名的第一个字母必须为小写，其余字母和表字段映射关系同类名和表名的映射关系。如表system_user的字段“register_date”则在VO、DTO、Model上述三类中都必须以“registerDate”出现。对应关系定义如表3.1所示：

VO属性名 registerDate DTO属性名 registerDate Model属性名 registerDate 表3.1

数据库字段名 register_date 3.1.5. 变量

变量属于名称，避免用采用其他词性。 采用名称要能代表在方法中的意义。如果员工列表： 最好是使用List employees或则employeeList而不是去使用List list或则更糟糕的List l，如果应用了List employees和Map employees可以分别使用employeeList和employeeMap。

自定义类型的变量可以采用本身的名称，把首字母改为小写。  采用Camel命名法

 小写字母开头，各个单词首字母大写  特有大写缩写词汇保持大写如：SQL

3.1.6. 常量命名

 采用全大写命名法 ，所有字母均大写

比如：

String SYSTEM_USER_TYPE; 3.1.7. 属性文件.properties定义变量命名

 pz.call.import.urlPath格式，全部小写，其中pz.call.import是宿主，urlPath多

个单词小写字母开头，各个单词首字母大写。

比如：

pz.call.import.urlPath=/asset/template/wx pz.call.upload.urlPath=/asset pz.call.call.phoneKey=sdf#ttj 3.1.8. JSP文件命名

 采用全小写命名法

 所有的字母均小写，单词之间以下划线’_’分隔  展示页面，按照名词+描述，如：news_list.jsp  操作页面，按照名词+动词命名，如：news_add.jsp  按照模块从大到小命名，如：news_order_add.jsp

3.1.9. JS文件命名

 与对应的JSP页面名字相同，多个字母首字母大写

 如：JSP页面为news_order_add.jsp，相对应JS文件newsOrderAdd.js

3.1.10. 资源文件命名

 采用全小写命名法

 按照前缀+模块+描述+状态命名，如：btn_main_login_pressed.png  (不一定完全包含如上4个部分，但是要依照顺序命名)

3.2. 有关注释

团队成员都应该形成良好的写注释的习惯，方便以后阅读，以及为了后期生成可读性良好的Java Doc

3.3.1. 程序文件头注释

提前设置好文件的模板Template

如以下模板：

/** * @Description: ${类描述}

* @ProjectName: ${PROJECT_NAME} * @ClassName: ${TYPE_NAME} * @Author: ${user} * @CreateDate: ${DATE} ${TIME} * @UpdateUser: ${user} →→→ 每次进行代码修改根据实际情况进行更新 * @UpdateDate: ${DATE} ${TIME} →→→ 每次进行代码修改根据实际情况进行更新 * @Version: 1.0 →→→每次进行代码修改根据项目版本号进行升级 */ 3.3.2. 方法头注释

一般在写完一个方法后使用快捷键生成一个块注释，IDE会自动帮我们写入一些信息。 如以下模板：

/** * @Description: $params$ * @Author: 作者名 * @CreateDate: $DATE$ $TIME$ * @UpdateUser: 更新者名 * @UpdateDate: $DATE$ $TIME$ * @Note: */ 注意：方法里面不要使用块注释 3.3.3. 关键点注释

应该包含如下信息： * 一些程序关键的地方 * 一些程序不易读的地方 * 编写代码过程中遇到问题的地方 * 需要提示读者的地方

注释应该写得少而易懂

格式规范

4.1. 缩进

应注意使用format来格式化代码，使用Tab键来缩进代码，相当于4个空格。

4.2. 换行

 {}花括号应该另起一行，左花括号与方法名、类名在同一行。(除了数组初始化时的

花括号)

 if、while等语句，假如体内只有一句代码也不要省略{}，为了方便以后的增删  字符串过长考虑拆分成多行

写在后面

希望各位成员遵守这份开发规范文档，养成良好的开发习惯