2022年Web应用开发规范

1、密级 ：公开Web 应用开发规范制定日期： 2022 年 1 月中航国际金网公司Web应用开发规范版本历史日期版本简要描述信息作者2022-1-18 0.9.1 创建该规范文档高正2022-2-3 0.9.2 修改了目录结构规范部分高正2022-2-4 0.9.3 增加了 js 和 css 样式规范高正- 2 - Web应用开发规范目 录1. 文件编码格式 - 4 -2. 目录结构规范 - 4 -3. 编程规范 - 5 -资源、配置文件 - 5 -Doc 文档 - 6 -实体 - 7 -Dao - 8 -Service - 8 -Action - 9 -JSP - 10 -css - 11 -

2、js - 11 -4. 反常处理规范 - 11 -5. 数据校验 - 12 - 3 - Web应用开发规范前言本规范是在代码书写基础规范 .doc基础上,对 web 应用所制定的开发规范；要求所有 web 应用项目中的全部成员遵守；对于历史系统和小范畴调整的系统（2022 年前上线的系统）,开发爱护人员可以依据实际情形进行实施；该规范中未尽事项,各项目组依据实际情形进行；备注：本文档中“ 工程名 小 ” 表示工程名的全部小写字母；本文档中“ 模块名 小 ” 表示工程名的全部小写字母；1. 文件编码格式（1）、项目接受 UTF-8 作为默认编码；Eclipse 中的设置方式： Window-Pr

3、eferences-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下的 Java Source File,在 Default encoding 中输入 UTF-8 ,储存；2. 目录结构规范

4、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 - 4 - Web应用开发规范 common 存放该应用的通用jsp（403.jsp 、404.jsp 、

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

6、名称 _语种 _国家 .properties 例如：- 5 - Web应用开发规范globalMessages_en_US.properties；（英文）globalMessages_zh_CN.properties；（中文）（2）、资源文件内部条目的命名原就：全部是小写字母；用圆点分割的三个部分组成：功能模块名 . 类别 . 自定义部分, 针对每一个部分,如是由多个单词组成,就用下划线进行分割；其中“ 类别” 部分的内容如下：. 菜单相关： menu . 标题相关： title . 按钮显示文字相关：button . 提示文字相关：alert . 警告文字相关：warn . 确认文字相关：c

7、onfirm . 消息文字相关：message . 属性字段相关的定义：field . 验证相关的定义：validate . 其他很难归类的定义：label 示例： system.field.last_update_date = 最终更换时间；配置文件：指Spring 配置文件、 acegi 配置文件、 struts 件等；配置文件、数据库链接池配置文Spring 配置文件的命名为：applicationContext_ 自定义部分 .xml ； acegi 配置文件的命名为：applicationContext_security.xml；struts 配置文件的命名为：struts.xml；

8、数据库链接池配置文件的命名为：proxool.xml；Doc 文档存放本 web 应用相关的文档,依据项目情形,工作方案、数据库、需求等有变化时,要求做到文档同步更新；（1）、doc/db ：必需要有 db.changelog.txt 文档,其内容为：数据库创建 SQL,后期变更记录,依据时间正序排放,参考如下样例：- 6 - Web应用开发规范/* 创建数据库 SQL 人员： xxx 日期：2022-10-01 AS IDENTITY, */ createtable USERS ID integerprimarykeyGENERATED ALWAYS LOGIN_NAME varchar20

9、 notnullunique, PASSWORD varchar20, NAME varchar20, EMAIL varchar30 ; createtable ROLES keyGENERATED ALWAYS AS IDENTITY, ID integerprimaryNAME varchar20 notnullunique;；/* 实体： x.java 数据表名： x 操作：新增字段 对原有数据是否有影响：无 */ 人员： xxx 日期： 2022-10-01 altertable x addcolumn y varchar 1000 defaultnull; /* 实体： x.jav

10、a 数据表名： x 操作：修改记录 对原有数据是否有影响：是*/ 人员： xxx 日期： 2022-10-23 update x set y = 001whereid= 334323;update x set y = 002whereid= 355431;update x set y = 006whereid= 321114;update x set y = 008whereid= 543233;（2）doc/ 技术文档：存放开发规范及本应用所需技术帮忙参考等；（3）doc/ 开发方案：存放本 web应用的开发方案；（4）doc/ 需求文档：存放本 web应用的需求文档；实体映射数据库中的表,

11、并在各层之间传递数据；（1）、接受注解的方式来进行映射该实体和数据库表；（2）、必需继承自公司框架的cn.eavic.framework.entity.BaseEntity类；（3）、实体的命名要接近或等价于数据库表名,名称中具有面对对象的特点；（4）、类定义时,必需添加Entity 、SequenceGenerator、Table、Cache标签；（5）、各成员的排放次序为：成员属性；属性的 set 、get 方法；自定义方法；重载自 Object 的方法如 toString,hashCode,equals；- 7 - Web应用开发规范（6）、属性定义时,加/ 注释,其中包含其中文含义,字

12、段的类型及长度；如有必要的话也要描述其常量取值范畴；（7）、常用 annotation注解及其使用规范,参见annotation使用规范 .doc ；Dao 负责数据库操作,完成实体的储存、读取等；全部的数据库操作都在这层完成,不答应在其他层进行数据库操作（1）、类定义时,必需添加 Repository 标签；（2）、必需继承自公司框架中的 cn.eavic.framework.orm.hibernate.GenericDao 类；该基类中已定义了基本的增、删、改、查操作,能中意大部分需求；（3）、对于方法的命名：常用方法依据如下统一命名：参照GenericDao 中的方法命名；getPK i

13、d：读取指定 ID的实体；saveT entity：储存指定实体； delete ：删除实体； find 、findAll 、findPage ：查找；其余方法依据情形自定,但是必需中意 代码书写基础规范 .doc 中所定义的方法的命名规范；Service 业务处理层,负责业务处理过程,通过 Transactional 标签添加了事务处理才能,每个方法都是事务把握的,如子方法仍未开启事务,就 spring 自动开启事务,如父方法（调用方）已存在事务,就 spring 自动接管该事务；（1）、接口：必需继承自公司框架的cn.eavic.framework.service.GenericManag

14、er接口；接口的命名方式：实体名（2）、实现类：Manager,例如： UserManager；必需继承自公司框架的 cn.eavic.framework.service.impl.GenericManagerImpl 类；实现类的命名方式：实体名必需放于子包 impl 中；ManagerImpl ,例如： UserManagerImpl ；（3）、实现类定义时,必需添加 Service 和Transactional 标签；（4）、通过 Autowired 自动注入相应的 dao；（5）、优先使用基类供应的方法完成操作；（6）、对数据库的操作,要交给 dao 层完成；（7）、必需对传入的参数进

15、行合法性验证；（8）、对于具有事务特点的业务处理过程,必需放在一个方法中来执行；- 8 - Web应用开发规范Service1 Service2 Service3 图中红色表示已经处于同一个事务处理中；（9）、对于仅查询而不修改数据的方法（即不参与数据库的修改）,建议在方法定义上添加 TransactionalreadOnly = true 标签；（10）、是否接受接口开发,依据项目情形由项目架构师准备；（11）、方法的命名：常用方法依据如下统一命名：getXXX.：获得某实体；示例：getUserLong id；findXXX.：依据条件获得实体列表；deleteXXX.：删除某实体；sav

16、eXXX.：储存某实体；其余方法参照上面常规方法命名,并且要中意 代码书写基础规范 .doc 中定义的方法的命名规范；（12）、常用 annotation注解及其使用规范,参见annotation使用规范 .doc Action （1）、命名规范：实体名+Action ,例如 UserAction ；（2）、如 action 是“ 增、删、改、查” 型,就必需继承自公司基础框架的抽象类：cn.eavic.framework.web.BaseAction；并且必需实现BaseAction 的抽象方法： list、prepareModel 、input、delete、save ；（3）、命名空间

17、Namespace的定义：依据项目和模块实际情形进行定义；（4）、方法的命名：常用方法依据如下统一命名：list: 进入列表；prepareModel：进入 input 和save 方法之前,且 ongl 封装数据前进入的方法；可依据实际情形拆分成 preporeInput、preporeSave 方法分别表示进入 input和 save 前执行的方法；- 9 - Web应用开发规范input：进入编辑、查看页面；save ：新增、修改后的储存；delete：执行删除；batchDelete：批量删除；其余方法依据代码书写基础规范.doc 中定义的方法的命名规范来命名；（5）、接受 Conve

18、ntion 插件实现零配置文件；Convention 的使用方法,参见公司 wiki ：中文： 14/wiki/index.php/Convention_%E4%BB%8B%E7%BB%8D英文： 14/wiki/index.php/Convention_Plugin（6）、所用到的 service ,必需通过 Autowired 自动注入；（7）、如有分页,就 Page定义为默认 10行；（8）、关于反常处理,参见本文档第 JSP 4部分“ 反常处理规范” 部分；（1）、 WebRoot/common文件夹中存放的 jsp 为通用 jsp ,例如： 403.jsp 、 404.jsp 、50

19、0.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）、文件命名规章：全部是小写字母

20、,单词间加横杠分割；列表页面为action前缀名称；AccompanyApplyAction,就列表页名称为示例：如action的名称为accompany-apply.jsp 录入、编辑页面为 action 前缀名称 +横杠 +input ；示例：如 action 的名 称为 AccompanyApplyAction ,就录入、编辑页名称为 accompany-apply-input.jsp - 10 - Web应用开发规范其他页面跟action中所执行方法的return 字符串有关,只要保持一样即可；示例：如 action 的名称为 AccompanyApplyAction,部分内容为：public String view throws Exception return view-detail ; css 就程序执行完 view方法后所进入的 jsp页面为 accompany-apply-view-detail.jsp ；本应用所用样式统一放入css.css样式文件, jsp中不建议另写样式；可依据实际情形有多个css样式文件；js 不鼓励在 jsp页面中直接写 javascript 脚本,除非必要, 尽量将通用的脚本放入 js