完整word版Web应用开发规范.docx

1、完整word版Web应用开发规范密级：公开Web应用开发规范制定日期：2010年1月中航国际金网公司版本历史日期版本简要描述信息作者2010-1-180.9.1创建该规范文档高正2010-2-30.9.2修改了目录结构规范部分高正2010-2-40.9.3增加了js和css样式规范高正前言本规范是在代码书写基础规范.doc基础上，对web应用所制定的开发规范。要求所有web应用项目中的所有成员遵守。对于历史系统和小范围调整的系统（2010年前上线的系统），开发维护人员可以根据实际情况进行实施。该规范中未尽事项，各项目组根据实际情况进行。备注：本文档中 “工程名小”表示工程名的全部小写字母。本文

2、档中 “模块名小”表示工程名的全部小写字母。1.文件编码格式（1）、项目采用UTF-8作为默认编码。Eclipse中的设置方式：Window-Preferences-General-Workspace，右侧的Text file encoding中从other中选择 UTF-8。 （2）、资源文件采用ISO-8859-1编码。（3）、.java 、.jsp、.css、.js等文件采用UTF-8作为文件默认编码。其他文件，【推荐】采用UTF-8作为文件默认编码。Eclipse中的设置方式：Window-Preferences-General-Content Types，点击右侧的Text下的Jav

3、a Source File，在Default encoding中输入UTF-8，保存。2.目录结构规范Web应用 src/main/java cn.eavic.工程名小 模块名小 action 存放action类 dao 存放dao类 entity 存放实体类 service 存放Service接口 impl 存放Service实现 src/main/resource 存放该web应用所需的资源文件和配置文件src/main/test 存放service类的单元测试类doc 存放该web应用相关的一些文件 db 工作计划 技术文档 需求文档WebRoot common 存放该应用的通用jsp（

4、403.jsp、404.jsp、500.jsp、meta.jsp、taglib.jsp） css 存放该应用的css样式文件 js 存放该应用的js脚本文件 images 存放该应用的图片文件 WEB-INF content 存放各个功能模块的jsp页面 web.xml 应用的web.xml pom.xml3.编程规范Web应用主要分如下几层：Action层Service层Dao层url访问、JSP中form提交、ajax调用数据库entity实体层资源、配置文件src/main/resource中存放资源文件、配置文件等。资源文件：（1）、资源文件的命名：资源文件命名如下：自定义名称_语种_

5、国家.properties例如：globalMessages_en_US.properties。（英文）globalMessages_zh_CN.properties。（中文）（2）、资源文件内部条目的命名原则：全部是小写字母。用圆点分割的三个部分组成：功能模块名.类别.自定义部分，针对每一个部分，若是由多个单词组成，则用下划线进行分割。其中“类别”部分的内容如下：菜单相关： menu标题相关： title按钮显示文字相关：button提示文字相关：alert警告文字相关：warn确认文字相关：confirm消息文字相关：message属性字段相关的定义：field验证相关的定义：valida

6、te其他很难归类的定义：label示例：system.field.last_update_date = 最后更改时间。配置文件：指Spring配置文件、acegi配置文件、struts配置文件、数据库链接池配置文件等。Spring配置文件的命名为：applicationContext_自定义部分.xml。 acegi配置文件的命名为：applicationContext_security.xml。struts配置文件的命名为：struts.xml。数据库链接池配置文件的命名为：proxool.xml。Doc文档存放本web应用相关的文档，根据项目情况，工作计划、数据库、需求等有变化时，要求做到

7、文档同步更新。（1）、doc/db：必须要有db.changelog.txt文档，其内容为：数据库创建SQL，后期变更记录，按照时间正序排放，参考如下样例：/* 创建数据库SQL 人员：xxx 日期：2009-10-01*/create table USERS (ID integer primary key GENERATED ALWAYS AS IDENTITY,LOGIN_NAME varchar(20) not null unique,PASSWORD varchar(20),NAME varchar(20),EMAIL varchar(30);create table ROLES (I

8、D integer primary key GENERATED ALWAYS AS IDENTITY,NAME varchar(20) not null unique);。/* 实体：x.java 数据表名：x 人员：xxx 操作：新增字段 对原有数据是否有影响：无 日期：2009-10-01*/alter table x add column y varchar(1000) default null;/* 实体：x.java 数据表名：x 人员：xxx 操作：修改记录 对原有数据是否有影响：是 日期：2009-10-23*/update x set y = 001 where id = 33

9、4323;update x set y = 002 where id = 355431;update x set y = 006 where id = 321114;update x set y = 008 where id = 543233;（2）doc/技术文档：存放开发规范及本应用所需技术帮助参考等。（3）doc/开发计划：存放本web应用的开发计划。（4）doc/需求文档：存放本web应用的需求文档。实体映射数据库中的表，并在各层之间传递数据。（1）、采用注解的方式来进行映射该实体和数据库表。（2）、必须继承自公司框架的cn.eavic.framework.entity.BaseEnt

10、ity类。（3）、实体的命名要接近或等价于数据库表名，名称中具有面向对象的特点。（4）、类定义时，必须添加Entity、SequenceGenerator、Table、Cache标签。（5）、各成员的排放顺序为：成员属性。属性的set、get方法。自定义方法。重载自Object的方法如toString()，hashCode(),equals()。（6）、属性定义时，加/注释，其中包含其中文含义，字段的类型及长度；若有必要的话也要描述其常量取值范围。（7）、常用annotation注解及其使用规范，参见annotation使用规范.doc。Dao负责数据库操作，完成实体的保存、读取等。所有的数据

11、库操作都在这层完成，不允许在其他层进行数据库操作（1）、类定义时，必须添加Repository标签。（2）、必须继承自公司框架中的cn.eavic.framework.orm.hibernate.GenericDao类。该基类中已定义了基本的增、删、改、查操作，能满足大部分需求。（3）、对于方法的命名： 常用方法按照如下统一命名：参照GenericDao中的方法命名。 get(PK id)：读取指定ID的实体。 save(T entity)：保存指定实体。 delete()：删除实体。 find()、findAll()、findPage()：查找。其余方法根据情况自定，但是必须满足代码书写基础

12、规范.doc中所定义的方法的命名规范。Service业务处理层，负责业务处理过程，通过Transactional标签添加了事务处理能力，每个方法都是事务控制的，若子方法还未开启事务，则spring自动开启事务，若父方法（调用方）已存在事务，则spring自动接管该事务。（1）、接口：必须继承自公司框架的cn.eavic.framework.service.GenericManager接口。接口的命名方式：实体名Manager，例如：UserManager。（2）、实现类：必须继承自公司框架的cn.eavic.framework.service.impl.GenericManagerImpl类。

13、实现类的命名方式：实体名ManagerImpl，例如：UserManagerImpl。必须放于子包impl中。（3）、实现类定义时，必须添加Service和Transactional标签。（4）、通过Autowired自动注入相应的dao。（5）、优先使用基类提供的方法完成操作。（6）、对数据库的操作，要交给dao层完成。（7）、必须对传入的参数进行合法性验证。（8）、对于具有事务特点的业务处理过程，必须放在一个方法中来执行。 Service1Service2Service3图中红色表示已经处于同一个事务处理中。（9）、对于仅查询而不修改数据的方法（即不参与数据库的修改），建议在方法定义上添加

14、Transactional(readOnly = true)标签。（10）、是否采用接口开发，根据项目情况由项目架构师决定。（11）、方法的命名：常用方法按照如下统一命名：getXXX(.)：获得某实体。示例：getUser(Long id)。findXXX(.)：根据条件获得实体列表。deleteXXX(.)：删除某实体。saveXXX(.)：保存某实体。其余方法参照上面常规方法命名，并且要满足代码书写基础规范.doc中定义的方法的命名规范。（12）、常用annotation注解及其使用规范，参见annotation使用规范.docAction（1）、命名规范：实体名+Action，例如Us

15、erAction。（2）、若action是“增、删、改、查”型，则必须继承自公司基础框架的抽象类：cn.eavic.framework.web.BaseAction。并且必须实现BaseAction的抽象方法：list()、prepareModel() 、input()、delete()、save()。（3）、命名空间Namespace的定义：根据项目和模块实际情况进行定义。（4）、方法的命名： 常用方法按照如下统一命名：list():进入列表。prepareModel()：进入input()和save()方法之前，且ongl封装数据前进入的方法。可根据实际情况拆分成preporeInput(

16、)、preporeSave()方法分别表示进入input()和save()前执行的方法。input()：进入编辑、查看页面。save()：新增、修改后的保存。delete()：执行删除。batchDelete()：批量删除。其余方法根据代码书写基础规范.doc中定义的方法的命名规范来命名。（5）、采用Convention插件实现零配置文件。Convention的使用方法，参见公司wiki：中文：http:/192.168.102.114/wiki/index.php/Convention_%E4%BB%8B%E7%BB%8D英文：http:/192.168.102.114/wiki/index

17、.php/Convention_Plugin（6）、所用到的service，必须通过Autowired自动注入。（7）、若有分页，则Page定义为默认10行。（8）、关于异常处理，参见本文档第4部分“异常处理规范”部分。JSP（1）、WebRoot/common文件夹中存放的jsp为通用jsp，例如：403.jsp、404.jsp、500.jsp、meta.jsp、taglibs.jsp等。（2）、jsp页面中的meta部分，通过引入meta.jsp完成。（3）、jsp页面中的标签（s、c、e等标签），统一放入taglibs.jsp。（4）、异常页面应该设计成具有友好提示、隐藏异常细节的页面。

18、（5）、javascript脚本尽量不直接写在jsp文件中，而是写入相应的js文件，并引入它。（6）、页面中尽量采用标签的方式，而不是使用的方式。（7）、jsp中的js和css文件和图片文件的引用路径、action路径等必须为绝对路径，而非相对路径，例如：（8）、文件命名规则：全部是小写字母，单词间加横杠分割。列表页面为action前缀名称。示例：若action的名称为AccompanyApplyAction，则列表页名称为accompany-apply.jsp录入、编辑页面为action前缀名称+横杠+input。示例：若action的名称为AccompanyApplyAction，则录入、

19、编辑页名称为accompany-apply-input.jsp其他页面跟action中所执行方法的return 字符串有关，只要保持一致即可。示例：若action的名称为AccompanyApplyAction，部分内容为：public String view() throws Exception . return view-detail;则程序执行完view方法后所进入的jsp页面为accompany-apply-view-detail.jsp。css本应用所用样式统一放入css.css样式文件，jsp中不建议另写样式。可根据实际情况有多个css样式文件。js不鼓励在jsp页面中直接写jav

20、ascript脚本，除非必要，尽量将通用的脚本放入js.js文件中，不同模块所用的js文件可以独立成js文件。4.异常处理规范（1）、重新抛出的自定义异常必须保留原来的异常，即throw new NewException(message, e)； 而不能写成throw new NewException(message)。（2）、在所有异常被捕获，且没有重新抛出的地方必须写日志。（3）、在action、service、dao各层之间异常的抛出过程如下图所示：Action层Service层Dao层异常处理页面截获并提示。抛出异常捕获异常抛出异常抛出异常注：（1）、捕获action异常的jsp页面尽

21、量设计成具有友好提示、隐藏异常细节的页面。（2）、action在某些情况是需要捕获异常的，根据需要进行。例如前台页面通过ajax方式提交、修改数据等操作，需要处理完毕后，返回给前台一个成功与否的提示。（3）、dao、service层都不需要额外捕捉异常，如果确实需要捕获异常，则捕获后还要再次抛出该异常。 5.数据校验前端校验：通过javascript脚本进行数据合法性验证，【推荐】使用jquery的validate插件，该插件的优点是功能强大而且容易掌握；缺点是该插件要跟jquery的相应版本对应。后端校验：对于需要验证的表单数据，action层必须验证。Service层的方法中，仅对其所负责的参数进行校验。Struts2提供了两种方式来完成表单数据校验：一种是采用编码校验，另一种是采用xml配置文件方式校验。目前暂定为编码校验方式。