WEB开发编程规范总体.doc

WEB开发编程规范(界面及编程)WEB开发编程规范1前言1术语解释1范围界定2相关开发环境(建议环境，不做强制要求)2开发工具：2数据库：3WEB服务器(仅做开发测试用)：3应用服务器：3界面开发规范3基本要求3其它注意事项6编程规范7基本要求7可读性要求7正确性与容错性要求8可重用性要求8变量命名8常量命名8函数命名8注释8程序10WEB开发编程规范前言J2EE是一种功能完备、稳定可靠、安全快速的企业级计算平台，它由多种基于JAVA的技术组成：Enterprise JavaBeans(EJB), JavaServer Pages(JSP), servlets, Java Naming and Directory Interface (JNDI), and the JDBC data access API等。 本规范针对从事资源管理开发中前端WEB站点开发设计人员。要求使用者对J2EE架构有所了解，具有一定的HTML、CSS基础知识，对交互式网页JSP及javabeans的开发有较深认识。本规范的目的是为了开发出通用的、易于维护的高效率的J2EE应用。术语解释表示层：即系统与系统使用者通过各终端进行交互时对数据内容的表现层，同时负责输入数据的格式合法性校验。该层次根据用户的需要完全个性化。应用表示逻辑层：根据个体应用系统的约束条件，实现表示层数据的组织和包装；根据应用逻辑对表示层输入的数据进行逻辑合法性检验。应用逻辑组件层：实现特定于个体系统的应用逻辑和算法(EJB)。持久存储层：可以实现所有实体数据的数据库集中存储。通过该层对持久存储的CRUD(create, read,update & delete) 操作，负责实体对象的创建、状态维护、删除等功能。范围界定根据J2EE技术框架的体系结构和WEB应用的特点，我们在项目的开发过程中将项目分成两个层次：与系统用户交互的网站页面系统（含静态页面结构和动态页面结构），以及实现用户业务逻辑的系统（含支持数据永久存储的数据库系统）。对于这两个层次，我们根据其特点采用不同的开发过程，而本规范只针对前一部分。在这一部分的开发中，需要如下开发人员：l Javabeans (包括无输出用户界面的servlet)开发人员l JSP 开发人员(包括客户端的JavaScript)l HTML 设计人员l 美工Javabeans开发人员建立表现层的逻辑，而其他人员建立表现的形式。因为这一层的开发可能会有几个人来承担不同的角色，也可能有些人需要兼顾到所有的方面，所以为了有针对性，下面我们分别就这几种角色在开发中应注意的事项提出要求：相关开发环境(建议环境，不做强制要求)开发工具：Javabeans的编写调试可用任何编辑器或JBuilder等，其它网站界面及管理部分用Dreamweaver MX，主要是做为一个大型的应用，网站管理是一个很重要的内容，采用DW MX可以通过内定的工作流程保证我们整个应用中模板、javascripts脚本、css样式表、JSP页面控件及XML、TLD等技术的实现保持一致，并无须设专人维护测试这些必须统一的公共部分。另一方面的优势是在JSP页面的开发上，不但提供JSP 标记库支持，而且提供完全 JavaBeans 自省功能，即除了在数据绑定面板中显示 JavaBeans 的 getProperty 和 setProperty 方式之外，Dreamweaver MX 还有一个能显示 JavaBean 所有方式和属性的服务器行为面板，可充分集成 Beans 和 JSP 应用程序，另外DW MX也支持Web Service的开发。(将在近期安排Dreamweaver MX针对JSP开发的相关培训)数据库：Oracle8i/9i(只安装客户端及相应JDBC驱动class12.zip)WEB服务器(仅做开发测试用)：Tomcat/Websphere/Resin等，建议用Tomcat4.0(这一层的开发做测试足够了，且占用系统资源少)，为了能测试包含访问EJB的代码，需安装j2ee.jar或其它包含有javax.ejb.*的包。应用服务器：可不安装，通过远程访问Websphere即可(指编写调用EJB的JAVABEANS部分)。界面开发规范基本要求网站目录命名规则 1所有目录名称使用小写英文字母的组合，绝对禁止包含汉字、空格和特殊字符及大写字母（WEB-INF目录除外），可以添加数字或下划线的组合，禁止输入全角字符。2在网站根目录中开设WEB-INF、images、common、temp、templete五个子目录，根据需要再开设其它子目录(如基础资源、管线资源等)，其中WEB-INF目录下设置classes、lib及tlds子目录， classes中放所有javabeans的class文件（凡package的请注意目录层次,在最终测试前将相应的java源文件与class文件放在一起），lib中放所有jar文件,tlds中放标签库文件。images目录中放网站所有页面都要用到的公共图片，例如公司的标志、banner 条、菜单、按钮等等；common 子目录中放Css、JavaScript、include 等公共文件，templete目录里是dreamweaver MX的公用模板文件。3在子目录中根据需要在每一个子目录中开设一个images的子目录用以放置此栏目专有的图片，如果这个栏目的内容特别多，又分出很多下级栏目，可以相应的再开设其他目录。4temp 目录中的文件往往会比较多，建议以时间为名称开设目录，将客户陆续提供的资料归类整理。 5在非网站目录里还得有三个目录：bakup、doc、src，其中bakup进行整个站点已开发内容的备份，doc 子目录，放客户提供的各种文字图片等等原始资料，src则放置所有class文件的源代码及页面设计师的PSD、Fla源文件。禁止将这三项内容放在dreamweaver MX的控制范围内。6网站中的路径全部采用相对路径。即一定要先建立站点然后在站内新建或修改文件，保证所有链接不会出现硬盘盘符的情况。以上是WEB站点目录结构的大致规划，实际使用时将先在规定的服务器上建好这个站点结构，大家通过DW MX的FTP功能下载并保持本地站点结构与服务器结构一致即可。文件命名原则1. 每一个目录中应该包含一个缺省的JSP文件，文件名统一用index.jsp。2. 文件名称统一用小写的英文字母、数字和下划线的组合。3. 命名原则的指导思想一是使得你自己和工作组的每一个成员能够方便的理解每一个文件的意义。CSS 层叠样式表文件 (建议直接采用DW MX的CSS 面板来定义，比较直观)样例： td font-family: 宋体; font-size: 12px; color: #000000; p text-indent: 2em; text-align: justify a:link color: #FFFFFF; text-decoration: none a:visited color: #99FFFF; text-decoration: none a:active color: #FF9900; text-decoration: underline a:hover color: #FF9900; text-decoration: underline 1. CSS定义的顺序为：重定义的最先，伪类其次，自定义最后，以便于他人阅读；对于伪类CSS定义，请严格按照以上顺序格式，即a:hover放在最后，以便使其不会被其他定义覆盖； 2. 为了保证不同浏览器上字号保持一致，字号用点数（pt）和像素（px）来定义，使用pt单位时一般使用中文宋体的9pt和10.5pt，使用px单位时一般使用中文宋体12px 和14.8px 。字体需要作为标题显示时，一般选用10.5pt或14.8px 的字号比较合适。所有的字号都应该用样式表来实现，禁止在页面中出现 标记。3. 排版中我们经常会遇到需要进行首行缩进的处理，不要使用   或者全角空格来达到效果，规范的做法是在样式表中定义 p text-indent: 2em; 然后给每一段加上 标记。脚本编写1 尽量直接采用DW MX提供的JavaScript 函数库，因为它提供了尖端的客户机方交互性，而不必学习冗长的教科书，这样也可以保证我们页面中JavaScript写法的一致性。所有javascrips的客户端脚本必须放在JSP页面的标签之前，便于使用模板进行站点统一管理时不致影响到脚本。2 网页中客户端代码只允许使用 JAVASCRIPS脚本、禁止用VBSCRIPTS。网站管理1 进入实际开发阶段将设置一测试用主服务器，上开设虚拟 WWW 目录。 2 主服务器包含站点完整结构，大家通过FTP功能及时上传最新的文件，保持共享最新的文件。3 实现服务器程序的互斥性修改 要求实现某一程序在同一时间只能一个开发人员修改。其具体实现方式是：需要修改程序的开发人员从源文件存放处提出（Chink-out）一个程序，这时其他开发人员就不可以再Chink-out同一个程序了，只有当第一个开发人员修改测试完成后，将更新版本的代码做放入（Chink-in）操作，其他开发人员才能Chink-out同一个程序。 JSP页面制作及编程技术要求界面风格需要一致： 在程序设计中需要注重模块化，而界面设计中对象化同样非常重要。将界面元素对象化，比如底部版权信息、导航条等，图片尽可能复用，比如站点标志、搜索按钮等等；下面提几点细节要求： 1网页适用的屏幕大小：制作网页时，显示器的分辨率设置可以为 800*600 或 1024768（或通过设置表格百分比方式尽量做成自适应的） 。2主要页面要写 。3 的alt 属性 , 使不能看图的用户也可以读懂页面。 4不使用过长的滚屏，采用分页。5在主页中尽量少使用滚动条，网页中尽量少出现横向滚动条。 6网页版权信息清晰明了。主页版权信息推荐使用下列格式： Best viewed with IE4.0, Resolution: 800600.Copyright2002 ，All right reserved.7如有特殊情况，必须在readme.txt文件中说明。8在查询显示结果过多时，除必须分页显示外，将上一页、下一页的翻页按钮同时放在列表的上面及最底下，并且设置直接跳转到某页的按钮。 其它注意事项控件的命名： 用小写前缀表示类别： frm 表单 cmd 按钮 txt 文本输入框 lab标签 img图象 pic lst 列表框 注释 用表格应用（仅针对JSP页面开发人员输出动态表格时） 表格不使用表格边框形式，即不得设置bordercolordark和bordercolorlight属性，也不准设置表格边框颜色，而是使用由页面设计师提供的CSS中设置的TD.content属性，此种方式可兼容IE5和NC6；并且只有这种方式，当浏览时有些单元格中无内容时仍可正常显示边框线；代码范例如下： 单元格内容界面友好系统提供灵活的输入方式以方便用户输入。容错能力强系统充分考虑到用户在操作时可能的错误，并提供相应的纠正措施。例如一份表单正常提交以后，假如用户利用历史记录后退，回到提交前的状态，这时候修改了提交内容，又再一次提交，那么结果是什么呢？编程规范基本要求 程序结构清析，简单易懂。 打算干什么，要简单，直接了当，代码精简，避免垃圾程序。 尽量使用标准库函数和公共函数。 可读性要求 保持注释与代码完全一致。 每个源程序文件，都有文件头说明。 每个函数，都有函数头说明。 主要变量（结构、联合、类或对象）定义或引用时，注释能反映其含义。 常量定义有相应说明。 处理过程的每个阶段都有相关注释说明。 在典型算法前都有注释。 利用缩进来显示程序的逻辑结构，缩进量一致并以Tab键为单位。 注释可以与语句在同一行，也可以在上行。 空行和空白字符也是一种特殊注释。 一目了然的语句不加注释。 注释的作用范围可以为：定义、引用、条件分支以及一段代码。 正确性与容错性要求 程序首先是正确，其次是优美 无法证明你的程序没有错误，因此在编写完一段程序后，应先回头检查。 改一个错误时可能产生新的错误，因此在修改前首先考虑对其它程序的影响。 所有变量在调用前必须被初始化。 对所有的用户输入，必须进行合法性检查（尽量采用客户端验证方式）。 不要比较浮点数的相等，如： 10.0 * 0.1 = 1.0 ， 不可靠。 单元测试也是编程的一部份，提交联调测试的程序必须通过单元测试。 可重用性要求 重复使用的完成相对独立功能的算法或代码应抽象为公共控件或类。 公共控件或类应考虑OO思想，减少外界联系，考虑独立性或封装性。 公共控件或类应建立使用模板。 变量命名 命名必须具有一定的实际意义,形式为xAbcFgh,x由变量类型确定,Abc、Fgh表示连续意义字符串,如果连续意义字符串仅两个,可都大写。常量命名常量定义必须具有一定的实际意义; 常量定义必须全部以大写字母来撰写,中间可根据意义的连续性用下划线连接,每一条定义的右侧必须有一简单的注释,说明其作用; 函数命名 函数原型说明包括引用外来函数及内部函数，外部引用必须在右侧注明函数来源： javabean的名称或include的文件名, 如是内部函数，只要注释其定义文件名; 第一个字母必须使用大写字母,要求用大小写字母组合规范函数命名,必要时可用下划线间隔 注释 原则上注释要求使用中文; 文件开始注释内容包括:公司名称、版权、作者名称、时间、模块用途、背景介绍等,复杂的算法需要加上流程说明; 函数注释包括:输入、输出、函数描述、流程处理、全局变量、调用样例等,复杂的函数 需要加上变量用途说明; 程序中注释包括:修改时间和作者、方便理解的注释等; 引用一: 文件开头的注释模板 /* * 文件名: * Copyright (c)2001.7-2001.9 * * 创建人: * 日 期: * 修改人: * 日 期: * 描 述: * * 版 本: *- */ 引用二: 函数开头的注释模板 /* * 函数名: * 输 入: a,b,c * a- * b- * c- * 输 出: x- * x 为 1, 表示. * x 为 0, 表示. * 功能描述: * 全局变量: * 调用模块: * 作 者: * 日 期: * 修 改: * 日 期: * 版本 */ 引用三: 程序中的注释模板 /*-*/ /* 注释内容 */ /*-*/ 程序 程序编码力求简洁，结构清晰，避免太多的分支结构及太过于技巧性的程序，尽量不采用递归模式。 编写程序时，亦必须想好测试的方法。如在javabean中包括方法时，在源程序中一般也应包括类似的代码（当然自行测试无误后必须用/* */ 封闭）：/*public static void main(String argv)MusicCollection m1 = new MusicCollection();System.out.println(m1.getAlbumsSize();System.exit(0);*/ 注释一定要与程序一致。 版本封存以后的修改一定要将老语句用/* */ 封闭，不能自行删除或修改,并要在文件及函数的修改记录中加以记录。 程序中每个block 的开头 ” 及 ” 必须对齐，嵌套的block 每进一套，缩进一个tab，TAB 为4个空格,block类型包括if、for、while、do等关键字引出的。 对于比较大的函数，每个block 和特殊的函数调用，都必须注明其功能 附录资料：Ehcache缓存配置 简介 Cache的配置很灵活，官方提供的Cache配置方式有好几种。你可以通过声明配置、在xml中配置、在程序里配置或者调用构造方法时传入不同的参数。 你可以将Cache的配置从代码中剥离出来，也可以在使用运行时配置，所谓的运行时配置无非也就是在代码中配置。以下是运行时配置的好处： 在同一个地方配置所有的Cache，这样很容易管理Cache的内存和磁盘消耗。 发布时可更改Cache配置。 可再安装阶段就检查出配置错误信息，而避免了运行时错误。 本文将会对ehcache.xml配置文件进行详细的阐述。在配置的时可以拷贝一个现有的ehcache.xml，如果没有请点击这里去下载。 ehcache-failsafe.xml 如果你调用了CacheManager默认构造方法去创建CacheManager的实例，此方法会到classpath中找ehcache.xml文件，否则它会到类路径下找ehcache-failsafe.xml文件。而ehcache-failsafe.xml被包含在jar包中，所有它肯定能找的到。 ehcache-failsafe.xml提供了一个非常简单的默认配置，这样可以使用户在没有创建ehcache.xml的情况下使用Ehcache。 不过这样做Ehcache会提醒用户创建一个正确的Ehcache配置。 ehcache.xml片段： ehcache.xml和其他配置文件 在Ehcache-1.6之前的版本，只支持ASCII编码的ehcache.xml配置文件。在Ehcach-1.6之后版本中，支持UTF8编码的ehcache.xml配置文件。因为向后兼容，所有采用ASCII编码的配置文件完全没有必要转换为UTF8。 一个CacheManager必须要有一个XML配置。由于磁盘路径或是监听端口，多个CacheManager使用同一个配置文件时会出现错误。 下面是ehcache.xml具体实例以及配置指南 ehcache xmlns:xsi=http:/www.w3.org/2001/XMLSchema-instance CacheManager配置 DmulticastGroupPort=4446，这样可以配置监听端口。 DiskStore配置 如果你使用的DiskStore（磁盘缓存），你必须要配置DiskStore配置项。如果不配置，Ehcache将会使用java.io.tmpdir。 diskStroe的“path”属性是用来配置磁盘缓存使用的物理路径的，Ehcache磁盘缓存使用的文件后缀名是.data和.index。 CacheManagerEventListener配置 我们通过CacheManagerEventListenerFactory可以实例化一个CacheManagerPeerProvider，当我们从CacheManager中added和removed Cache时，将通知CacheManagerPeerProvider，这样一来，我们就可以很方面的对CacheManager中的Cache做一些统计。 注册到CacheManager的事件监听类名有： adding a Cache和removing a Cache CacheManagerPeerProvider配置 在集群中CacheManager配置CacheManagerPeerProviderFactory创建CacheManagerPeerProvider。具体的实例如下： CacheManagerPeerListener配置 CacheManagerPeerListener配置是用来监听集群中缓存消息的分发的。 Cache配置 name：Cache的唯一标识 maxElementsInMemory：内存中最大缓存对象数。 maxElementsOnDisk：磁盘中最大缓存对象数，若是0表示无穷大。 eternal：Element是否永久有效，一但设置了，timeout将不起作用。 overflowToDisk：配置此属性，当内存中Element数量达到maxElementsInMemory时，Ehcache将会Element写到磁盘中。 timeToIdleSeconds：设置Element在失效前的允许闲置时间。仅当element不是永久有效时使用，可选属性，默认值是0，也就是可闲置时间无穷大。 timeToLiveSeconds：设置Element在失效前允许存活时间。最大时间介于创建时间和失效时间之间。仅当element不是永久有效时使用，默认是0.，也就是element存活时间无穷大。 diskPersistent：是否缓存虚拟机重启期数据。（这个虚拟机是指什么虚拟机一直没看明白是什么,有高人还希望能指点一二）。 diskExpiryThreadIntervalSeconds：磁盘失效线程运行时间间隔，默认是120秒。 diskSpoolBufferSizeMB：这个参数设置DiskStore（磁盘缓存）的缓存区大小。默认是30MB。每个Cache都应该有自己的一个缓冲区。 memoryStoreEvictionPolicy：当达到maxElementsInMemory限制时，Ehcache将会根据指定的策略去清理内存。默认策略是LRU（最近最少使用）。你可以设置为FIFO（先进先出）或是LFU（较少使用）。这里比较遗憾，Ehcache并没有提供一个用户定制策略的接口，仅仅支持三种指定策略，感觉做的不够理想。 Cache Exception Handling配置 总结 这里只对通用缓存的配置做了详细的阐述，至于RMI缓存和集群缓存可以参考这里。 下面给出几个配置示例： Ehcache默认Cache配置 SampleCache1配置 简单配置，在ehcache.xml文件中有此配置，在使用Ehcache前最好将其删除掉，自己配置。 缓存名sampleCache1，内存中最多可缓存10000个Element，其中的element会在闲置5分钟或是存活10分钟之后失效。 超过10000element时，element将会输出到磁盘中，输出路径是java.io.tmpdir。 SampleCache2配置 Cache名为SampleCache2，内存中最多可以缓存1000个element，超出1000不能输出到磁盘中。缓存是永久有效的。 SampleCache3配置 Cache名为SampleCache3。可缓存到磁盘。磁盘缓存将会缓存虚拟机重启期的数据。磁盘缓存失效线程运行间隔时间是10分钟。 sampleDistributedCache1配置 Cache名为sampleDistributedCache1。 sampleDistributedCache2配置 sampleDistributedCache3配置 /cac