2 设计规范

2.1 系统设计规范

当有需求变化的时候，开发经理必须遵守一个顺序，第一先修改概要设计、设计设计，数据库设计等接着再修改代码的原则；

对于每一次修改，都必须编写 changelog ；

系统的设计文件需要放到版本控制文件当中，以便对不同的版本进行控制；

2.2 数据库设计规范

数据库的设计必须放到 PowerDesinger 的 Repository 当中；

每一个项目只有系统架构师，开发经理有权限去修改物理数据模型，其他人只有只读取权；

按数据库脚本的命名规范编写数据库脚本与初始化数据脚本；

数据库的设计只能由系统架构师，开发经理或由开发经理指定的高级工程师进行修改；

需求变更需要修改到数据库的时候，必须先修改物理数据模型，再到数据库修改；

任何人没有经过系统架构师或开发经理的授权，不得私自修改数据库；

对修改内容需要修改 changelog ，并编写修改数据库的脚本；

修改数据库的脚本需要在测试机上做过测试，并提供项目部经理；

3 文件命名规范

3.1 页面文件命名规范

页面文件的命名是由小写英文字码，下划线，数字组成； user_list.html ； index.jsp ； index_cn.jsp ； 503.jsp 等；

页面文件最好以英文单词组成，以便提高文件的可读性；例如： permission_list.jsp

对于一个模块的操作页面，以模块名 + 下划线 + 动词组成，例如： permission_list.jsp

对于有些模块使用英文单词命名比较麻烦的，在不得已的情况下，可以使用拼音的简写来进行命名，但是，必须在页面文件的最前面加上注释，注释以下所示：

<%--

用户列表， yflb 是用户列表的简写 .

@version $ Date 2005-7-19 $

@author gsh XXXXXXXX 公司 / 信息化应用中心 / 平台产品部

--%>

其中 <%-- 的下一行或多行为页面作用描述，

@version 后跟日期，以日期作为版本

@author 公司帐号 XXXXXXX 公司 / 信息化应用中心 / 所在部门

3.2 Java 文件命名规范

Java 类文件的命名不要超过 32 个字字符；

Java 文件的命名规范按照 Sun 公司的标准进行命名；

取消 Java 文件以下划线进行分隔的命名方式；

取消命名当中出现的 Map 这些命名方式；

3.2.1 Action 类的命名规范

Action 类是以英文单词组成；由模块名 + [ 其它标试 ] + Action 构成；

同一个模块的 Action 类 CRUD 操作放在同一个 Action 类当中；比如 UserAction ； GroupAction ；

对于一个模块的非 CRUD 操作，由系统架构师或开发经理根据命名规范决定重新定义一个有意义的 Action ；比如： UserSearchAction ；

不要在类文件当中加上下划线；

一个 Action 类文件不要超过 500 行代码；

3.2.2 Service 层的命名规范

Service 层命名规范将由接口与实现构成；

Service 层接口的命名由 I + 模块名 + Service 构成，例如： IUserService.java ；

Service 层实现的命名由模块名 + ServiceImpl 构成，例如： UserServiceImpl.java

DAO 层方法的命名：以操作动词 + ValueObject 名

创建前缀： create ，比如： createUser(User user) ；

修改前缀： update ，比如： updateUser(User user);

删除前缀： delete ，比如： deleteUser(User user);

列出前缀： list ，比如： listUsers();

通过 UUID 查找实体前缀： find + 实体名 + ById ，比如： findUserById(String userId);

查询： search ，比如： searchUsers(Map searchKey);

统计： count ，比如： countUsers();

3.2.3 DAO 层的命名规范

DAO 层命名规范将由接口与实现构成；

DAO 层接口的命名由 I + 模块名 + DAO 构成，例如： IUserDAO ；

DAO 层实现的命名方式需要结构持久层的实现方式，比如， Hibernate 的应用的话其命名由：模块名 + DAO + Hibernate 构成，例如： UserDAOHibernate ；如实持久实现是由 JDO 方式实现，则命名由：模块名 + DAO + JDO 构成，例如： UserDAOJDO ；

所有 CRUD 在接口当中都必须定义，方法体调用父对象的操作实现；

DAO 层方法的命名：以操作动词 + ValueObject 名

创建前缀： create ，比如： createUser(User user) ；

修改前缀： update ，比如： updateUser(User user);

删除前缀： delete ，比如： updateUser(User user);

列出前缀： list ，比如： deleteUsers();

通过 UUID 查找实体前缀： find + 实体名 + ById ，比如： findUserById(String userId);

查询： search ，比如： searchUsers(Map searchKey);

统计： count ，比如： countUsers();

3.2.4 Pojo 类的命名规范

Pojo 类的类名必须与 html 文件的文件名对应，比如， Pojo 的类名为 User ，则 hbm 映射文件的命名为 User.hbm.xml ；

Pojo 类的类名需要与命名规范相对应，比如，表名为 ITSM_ CONFIGURATION_ITEM （ itsm 项目的配置项表），相对应的 Pojo 类名应该为 ConfigurationItem.java ， hbm 映射文件的命名为： ConfigurationItem.hbm.xml ；

3.2.5 Helper 类的命名规范

帮助类的命名是由名词 + [ 名词 ] + Helper 构成；如 Spring 的帮助类命名为 SpringHelper.java ；

所有帮助类的每一个 public 方法，都必须加上简单的使用 sample ；

3.2.6 Servlet 类的命名规范

Servlet 的命名由名词 + [ 动词 ] + [ 名词 ] + Servlet 构成；比如 Struts 的 ActionServlet.java

Listener 的命名由名词 + [ 动词 ] + [ 名词 ] + Listener 构成；比如： CommonSessionListener.java

Filter 的命名由名词 + [ 动词 ] + [ 名词 ] + Filter 构成；比如 Spring 的 CharacterEncodingFilter.java ；

3.2.7 EJB 类的命名规范

Ejb 的命名最终是以 Bean 结尾；

Ejb 的接口文件存放在 Ejb 同级目录的 interface 当中；

使用 Ejb 必须提供相应的 Xdolect 脚本；

布署描述符存放在 src 下面；

3.2.8 基础类的命名规范

基础类的命名以 Base + 名词 + [ 动词 ] + [ 名词 ] 构成；例如： BaseAction.java ； BaseService ；

基础数只能为 abstract ；或 interface ；

3.3 Java Package 的命名及层次结构规范

包的命名必须有意义；包名必须以 com.gdcn 开头；

com.gdcn.common 包存放着所有各个项目所共用的文件；项目组开发人员不得修改；

项目组开发出更加通用的组件，通知部门经理或系统架构师，经开发讨论后，将新的构件加入到 common 包当中；

包名的命名大致如下：

com.gdcn.projectname.common 存放着项目级别的通用类；

com.gdcn.projectname.web 存放着与 web 相关的类文件；

com.gdcn.projectname.web.action 存放着 struts 的 action 文件；

com.gdcn.projectname.web.taglib 存放着所有的标签文件；

com.gdcn.projectname.web.servlet 存放着所有的 servlet ；

com.gdcn.projectname.valueobject 存放着所有 pojo ；

com.gdcn.projectname.service 存放着项目所有 service 层的接口；

com.gdcn.projectname.service.impl 存放着项目 service 层的所有实现；

com.gdcn.projectname.dao 存放着项目 dao 层的所有接口；

com.gdcn.projectname.dao.impl 存放着项目 dao 层的所有接口；

com.gdcn.projectname.webservice 下面存放着 webservice 的实现与接口；

对于大项目，允许将 com.gdcn.projectname.web.action 下面再进行模块的区分；

对于大项目，允许将 com.gdcn.projectname.service 下面再按模块进行区分；

对于大项目，允许将 com.gdcn.projectname.dao 下面再按模块进行区分；

3.4 导入包的顺序

在应用程序当中导入的包的顺序是做如下定义：

java

javax

org

net

com

可以使用格式化工具进行代码的格式化；

3.5 自定义标签命名规范

标签的名名以前缀 + 下划线 + 后缀的方式进行命名；比如，通用标签的前缀以 gdcn 命名，后缀以 tree 命名；

项目级别的标签以项目名称 + 下划线 + 标签名称进行命名：

标签称只允许由小写英文字母 + 下线划 + 数字组成；

3.6 属性配置文件的命名规范

属性配置的命名只允许小写英文字母和下划线组成；

属性配置文件只允许是 property 文件或者是 xml 文件；

属性文件存放在工程目录的 etc 下面

3.7 数据库脚本的命名规范

建表文件以项目名称 + 下划线 + setup 构成，例如： itsm_setup.sql ；

初始化脚本文件以项目名称 + 下划线 + init 构成，例如： itsm_init.sql ；

修改数据脚本文件以项目名称 + 下划线 + modify + 修改时间构成，例如： itsm_modify_2006-8-19.sql 构成；

数据库脚本文件必须存放到 cvs 或 SVN 当中做版本控制；

4 编码规范

4.1 Java 类的注释规范

每一个类都必须有较为详细的注释；

注释内容包括：类文件说明、创建者、创建时间、修改者、修改时间、其它信息：比如：

/**

* <code>CommonServletContextListener</code> ，该监听器的作用是在 web app 启动的时候

* 将 ServletContext 绑定到 SpringHelper 当中，以更加方便地获取到上下文信息 .

* @author XXX ，信息化产品部 - 研发中心 -XXXXXXX 有限公司 . Create-Time 2006-8-1 11:42.

* @see ServletContextListener

* @see SpringHelper

4.2 Java 方法的注释规范

每一个方法都需要有注释，对于通用类提供的方法，除了有详细的注释除外，还必须有一些简单的 sample ；

每一个参数都必须做一下说明；

每一个返回值都必须做一下说明；

每一个异常都必须做一下说明；

/**

* parse Web Security Settings

* @param ele Element

* @return WebSecuritySettings

* @throws ConfigException

static WebSecuritySettings parseWebSecuritySettings(Element ele) throws ConfigException {

……

}

方法体里面重要的算法需要加上详细注释；

4.3 Java 类属性的注释规范

对于类属性必须加上注释；

通用的 POJO 类的属性注释必须有详细的注释；

项目级别的 POJO 类的属性注释由开发经理根据项目的紧急程度自己做控制；

4.4 Java 层次结构的规范

Jsp 页面只负责页面的展现，理论上不允许任何业务逻辑代码存放在 jsp 文件当中；

Action 层负责处理页面的请求信息，并将 ActionForm 转换为 pojo ，或将 pojo 转换为 ActionForm ；

ActionForm 不能达到 Service 层；

Pojo 不能达到 Jsp 层；列表对象必须在 Action 当中做封装；

不允许在 Action 层抛出 ServiceException ； Action 层只允许抛出 ParameterException 异常；

业务层负责业务信息的处理，并调用业务层的对象；

业务层抛出 ServiceException ；

不允许在业务层操作 Hibernate Session ；

不允许在业务层传递 SQL 或 HQL 到 DAO 层；

DAO 层负责数据库的操作；

DAO 层抛出 DAOException ；

4.5 WEB 目录存储规范

在 WEB 目录下面：

images 存放着所有的图片文件，该目录可以按照模块，按照组件名进行细化；

stylesheet 存放着所有的样式文件；

javascript 存放着所有的脚本文件

自定义Java开发规范