完整word版Web应用开发规范.docx
《完整word版Web应用开发规范.docx》由会员分享，可在线阅读，更多相关《完整word版Web应用开发规范.docx（11页珍藏版）》请在冰豆网上搜索。
完整word版Web应用开发规范
密级：
公开
Web应用开发规范
制定日期：
2010年1月
中航国际金网公司
版本历史
日期
版本
简要描述信息
作者
2010-1-18
0.9.1
创建该规范文档
高正
2010-2-3
0.9.2
修改了目录结构规范部分
高正
2010-2-4
0.9.3
增加了js和css样式规范
高正
前言
本规范是在《代码书写基础规范.doc》基础上，对web应用所制定的开发规范。
要求所有web应用项目中的所有成员遵守。
对于历史系统和小范围调整的系统（2010年前上线的系统），开发维护人员可以根据实际情况进行实施。
该规范中未尽事项，各项目组根据实际情况进行。
备注：
本文档中“工程名[小]”表示工程名的全部小写字母。
本文档中“模块名[小]”表示工程名的全部小写字母。
1.文件编码格式
（1）、项目采用UTF-8作为默认编码。
Eclipse中的设置方式：
Window->Preferences->General->Workspace，右侧的Textfileencoding中从other中选择UTF-8。
（2）、资源文件采用ISO-8859-1编码。
（3）、.java、.jsp、.css、.js等文件采用UTF-8作为文件默认编码。
其他文件，【推荐】采用UTF-8作为文件默认编码。
Eclipse中的设置方式：
Window->Preferences->General->ContentTypes，点击右侧的Text下的JavaSourceFile，在Defaultencoding中输入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（403.jsp、404.jsp、500.jsp、meta.jsp、taglib.jsp）
│├─css——存放该应用的css样式文件
│├─js——存放该应用的js脚本文件
│├─images——存放该应用的图片文件
│└─WEB-INF
│├content——存放各个功能模块的jsp页面
│└web.xml——应用的web.xml
└─pom.xml
3.编程规范
Web应用主要分如下几层：
Action层
Service层
Dao层
url访问、JSP中form提交、ajax调用
数据库
entity实
体
层
资源、配置文件
src/main/resource中存放资源文件、配置文件等。
●资源文件：
（1）、资源文件的命名：
⏹资源文件命名如下：
自定义名称_语种_国家.properties
例如：
globalMessages_en_US.properties。
（英文）
globalMessages_zh_CN.properties。
（中文）
（2）、资源文件内部条目的命名原则：
⏹全部是小写字母。
⏹用圆点分割的三个部分组成：
功能模块名.类别.自定义部分，针对每一个部分，若是由多个单词组成，则用下划线进行分割。
其中“类别”部分的内容如下：
Ø菜单相关：
menu
Ø标题相关：
title
Ø按钮显示文字相关：
button
Ø提示文字相关：
alert
Ø警告文字相关：
warn
Ø确认文字相关：
confirm
Ø消息文字相关：
message
Ø属性字段相关的定义：
field
Ø验证相关的定义：
validate
Ø其他很难归类的定义：
label
示例：
system.field.last_update_date=最后更改时间。
●配置文件：
指Spring配置文件、acegi配置文件、struts配置文件、数据库链接池配置文件等。
Spring配置文件的命名为：
applicationContext[_自定义部分].xml。
acegi配置文件的命名为：
applicationContext_security.xml。
struts配置文件的命名为：
struts.xml。
数据库链接池配置文件的命名为：
proxool.xml。
Doc文档
存放本web应用相关的文档，根据项目情况，工作计划、数据库、需求等有变化时，要求做到文档同步更新。
（1）、doc/db：
必须要有db.changelog.txt文档，其内容为：
数据库创建SQL，后期变更记录，按照时间正序排放，参考如下样例：
/***************************************************************
创建数据库SQL人员：
xxx日期：
2009-10-01
****************************************************************/
createtableUSERS（
IDintegerprimarykeyGENERATEDALWAYSASIDENTITY,
LOGIN_NAMEvarchar（20）notnullunique,
PASSWORDvarchar（20）,
NAMEvarchar（20）,
EMAILvarchar（30）
）;
createtableROLES（
IDintegerprimarykeyGENERATEDALWAYSASIDENTITY,
NAMEvarchar（20）notnullunique
）;
。
。
。
。
。
。
。
/***************************************************************
实体：
x.java数据表名：
x人员：
xxx
操作：
新增字段对原有数据是否有影响：
无日期：
2009-10-01
****************************************************************/
altertablexaddcolumnyvarchar（1000）defaultnull;
/***************************************************************
实体：
x.java数据表名：
x人员：
xxx
操作：
修改记录对原有数据是否有影响：
是日期：
2009-10-23
****************************************************************/
updatexsety='001'whereid=334323;
updatexsety='002'whereid=355431;
updatexsety='006'whereid=321114;
updatexsety='008'whereid=543233;
（2）doc/技术文档：
存放开发规范及本应用所需技术帮助参考等。
（3）doc/开发计划：
存放本web应用的开发计划。
（4）doc/需求文档：
存放本web应用的需求文档。
实体
映射数据库中的表，并在各层之间传递数据。
（1）、采用注解的方式来进行映射该实体和数据库表。
（2）、必须继承自公司框架的cn.eavic.framework.entity.BaseEntity类。
（3）、实体的命名要接近或等价于数据库表名，名称中具有面向对象的特点。
（4）、类定义时，必须添加@Entity、@SequenceGenerator、@Table、@Cache标签。
（5）、各成员的排放顺序为：
●成员属性。
●属性的set、get方法。
●自定义方法。
●重载自Object的方法如toString（），hashCode（）,equals（）。
（6）、属性定义时，加//注释，其中包含其中文含义，字段的类型及长度；若有必要的话也要描述其常量取值范围。
（7）、常用annotation注解及其使用规范，参见《annotation使用规范.doc》。
Dao
负责数据库操作，完成实体的保存、读取等。
所有的数据库操作都在这层完成，不允许在其他层进行数据库操作
（1）、类定义时，必须添加@Repository标签。
（2）、必须继承自公司框架中的cn.eavic.framework.orm.hibernate.GenericDao类。
该基类中已定义了基本的增、删、改、查操作，能满足大部分需求。
（3）、对于方法的命名：
常用方法按照如下统一命名：
参照GenericDao中的方法命名。
get（PKid）：
读取指定ID的实体。
save（Tentity）：
保存指定实体。
delete（…）：
删除实体。
find（…）、findAll（…）、findPage（…）：
查找。
其余方法根据情况自定，但是必须满足《代码书写基础规范.doc》中所定义的方法的命名规范。
Service
业务处理层，负责业务处理过程，通过@Transactional标签添加了事务处理能力，每个方法都是事务控制的，若子方法还未开启事务，则spring自动开启事务，若父方法（调用方）已存在事务，则spring自动接管该事务。
（1）、接口：
●必须继承自公司框架的cn.eavic.framework.service.GenericManager接口。
●接口的命名方式：
实体名＋Manager，例如：
UserManager。
（2）、实现类：
●必须继承自公司框架的cn.eavic.framework.service.impl.GenericManagerImpl类。
●实现类的命名方式：
实体名＋ManagerImpl，例如：
UserManagerImpl。
●必须放于子包impl中。
（3）、实现类定义时，必须添加@Service和@Transactional标签。
（4）、通过@Autowired自动注入相应的dao。
（5）、优先使用基类提供的方法完成操作。
（6）、对数据库的操作，要交给dao层完成。
（7）、必须对传入的参数进行合法性验证。
（8）、对于具有事务特点的业务处理过程，必须放在一个方法中来执行。
Service1
Service2
Service3
图中红色表示已经处于同一个事务处理中。
（9）、对于仅查询而不修改数据的方法（即不参与数据库的修改），建议在方法定义上添加@Transactional（readOnly=true）标签。
（10）、是否采用接口开发，根据项目情况由项目架构师决定。
（11）、方法的命名：
常用方法按照如下统一命名：
getXXX（...）：
获得某实体。
示例：
getUser（Longid）。
findXXX（...）：
根据条件获得实体列表。
deleteXXX（...）：
删除某实体。
saveXXX（...）：
保存某实体。
其余方法参照上面常规方法命名，并且要满足《代码书写基础规范.doc》中定义的方法的命名规范。
（12）、常用annotation注解及其使用规范，参见《annotation使用规范.doc》
Action
（1）、命名规范：
实体名+Action，例如UserAction。
（2）、若action是“增、删、改、查”型，则必须继承自公司基础框架的抽象类：
cn.eavic.framework.web.BaseAction。
并且必须实现BaseAction的抽象方法：
list（）、prepareModel（）、input（）、delete（）、save（）。
（3）、命名空间@Namespace的定义：
根据项目和模块实际情况进行定义。
（4）、方法的命名：
常用方法按照如下统一命名：
●list（）:
进入列表。
●prepareModel（）：
进入input（）和save（）方法之前，且ongl封装数据前进入的方法。
可根据实际情况拆分成preporeInput（）、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.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）、异常页面应该设计成具有友好提示、隐藏异常细节的页面。
（5）、javascript脚本尽量不直接写在jsp文件中，而是写入相应的js文件，并引入它。
（6）、页面中尽量采用标签的方式，而不是使用<%…%>的方式。
（7）、jsp中的js和css文件和图片文件的引用路径、action路径等必须为绝对路径，而非相对路径，例如：
（8）、文件命名规则：
●全部是小写字母，单词间加横杠分割。
●列表页面为action前缀名称。
示例：
若action的名称为AccompanyApplyAction，则列表页名称为accompany-apply.jsp
●录入、编辑页面为action前缀名称+横杠+input。
示例：
若action的名称为AccompanyApplyAction，则录入、编辑页名称为accompany-apply-input.jsp
●其他页面跟action中所执行方法的return字符串有关，只要保持一致即可。
示例：
若action的名称为AccompanyApplyAction，部分内容为：
publicStringview（）throwsException{
......
return"view-detail";
}
则程序执行完view方法后所进入的jsp页面为accompany-apply-view-detail.jsp。
css
本应用所用样式统一放入css.css样式文件，jsp中不建议另写样式。
可根据实际情况有多个css样式文件。
js
不鼓励在jsp页面中直接写javascript脚本，除非必要，尽量将通用的脚本放入js.js文件中，不同模块所用的js文件可以独立成js文件。
4.异常处理规范
（1）、重新抛出的自定义异常必须保留原来的异常，即thrownewNewException（"message",e）；而不能写成thrownewNewException（"message"）。
（2）、在所有异常被捕获，且没有重新抛出的地方必须写日志。
（3）、在action、service、dao各层之间异常的抛出过程如下图所示：
Action层
Service层
Dao层
异常处理页面截获并提示。
抛出异常
捕获异常
抛出异常
抛出异常
注：
（1）、捕获action异常的jsp页面尽量设计成具有友好提示、隐藏异常细节的页面。
（2）、action在某些情况是需要捕获异常的，根据需要进行。
例如前台页面通过ajax方式提交、修改数据等操作，需要处理完毕后，返回给前台一个成功与否的提示。
（3）、dao、service层都不需要额外捕捉异常，如果确实需要捕获异常，则捕获后还要再次抛出该异常。
5.数据校验
前端校验：
通过javascript脚本进行数据合法性验证，【推荐】使用jquery的validate插件，该插件的优点是功能强大而且容易掌握；缺点是该插件要跟jquery的相应版本对应。
后端校验：
对于需要验证的表单数据，action层必须验证。
Service层的方法中，仅对其所负责的参数进行校验。
Struts2提供了两种方式来完成表单数据校验：
一种是采用编码校验，另一种是采用xml配置文件方式校验。
目前暂定为编码校验方式。
升级会员 