H2010编码规范——JavaScript分册.doc

H2010编程规范JavaScript开发分册文档修改记录版本更新摘要 NO. H2010-DEV -2010-0000002版本号日期修改人更新摘要0.1.02010-03-20王翔创建0.1.12010-03-22王翔补充异常事件处理目录概要4背景介绍5命名规范7主要的命名样式7命名空间7顶层命名空间7平台框架类7工具类8业务应用类8培训和教程示例类8单元测试类8变量9基本编码规范10性能要求11事件处理16异常处理19参考资料21概要本文档是H2010工程信息系统设计和开发标准中的JavaScript开发分册，用于指导H2010工程实施组浏览器端JavaScript开发部分。本文读者适用于H2010工程开发人员和代码复查人员，对于中国海关自建、合建信息系统中使用JavaScript设计应用的设计、开发人员也有一定的借鉴作用。本系列文档有如下其他分册，读者可以根据开发需要进行参阅：l 编程规范和开发指南.Net开发l 编程规范和开发指南Java 分册l 编程规范和开发指南JavaScript 分册l 编程规范和开发指南T-SQL 分册l 编程规范和开发指南PL/SQL 分册l 编程规范和开发指南.Net安全编码指南背景介绍随着海关基于浏览器平台项目的普及，如何在浏览器端提供更好的交互机制及用户体验，适应海关应用“服务化”特点，成为海关应用开发人员需要面临的主要问题。为了实现浏览器客户端运行平台的无关性，项目普遍采用JavaScript语言完成UI及UIP部分逻辑，并且配合AJAX技术实现浏览器客户端与海关后台“服务”Endpoint的有效衔接。如图1是一个典型Web应用的分层结构。本文所介绍的JavaScript开发规范主要面对UI和UIP（UIP：位于UI层，协调调度UI组件的客户端控制机制）部分的JavaScript开发，对于采用JavaScript作为服务端代码的应用，可以主要参考“命名规范”、“基本编码规范”、“性能要求”、“事件处理”、“异常处理”的适用部分。图1：典型Web应用的分层结构 为了便于海关对外技术合作和系统集成，本文介绍的JavaSript内容基于ECMA 262 language标准，同时适于中国海关.NET、Java & Java EE、REST平台项目。 为了便于项目协作，中国海关涉及JavaScript的开发、调试、库代码共享统一基于下列工具平台。平台开发工具WindowsVisual Studio 2008、Visual Studio 2010Visual Studio 2008 Web Developer ExpressVisual Studio 2010 Web Developer ExpressMacintoshBBEdit表1：推荐的开发工具l 为了帮助读者了解本文对于不同内容的约束性强度，采用下列标志区分：o 强制要求o 虽然不强制，但强烈建议o 建议本文读者适于中国海关各类信息系统的设计、开发人员。对于系统管理、运行维护人员也有一定的借鉴意义。命名规范主要的命名样式Pascal标示命名的每个单词都是首字母大写。例如：BackColor、EntryHeadCamel标示命名的首单词首字母小写，其余的每个单词均首字母大写。例如：backColor、entryHeadUpper标示的每个字母均大写。例如：IO、ENTRYHEADLower标示的每个字母均小写。例如：io、entryhead命名空间命名空间参考编程规范和开发指南.Net开发分册，所有命名空间的根为chinaCustoms.，命名方式采用首字母小写的骆驼型命名方式。顶层命名空间按照开发的主要类型，顶层命名空间分别为l chinaCustoms.frameworkl chinaCustoms.utilityl chinaCustoms.applicationl chinaCustoms.tutorial平台框架类chinaCustoms.framework代表所有海关平台类项目的父节点例如：风险平台命名为chinaCustoms.framework.riskDSS命名为chinaCustoms.framework.dss安全运维平台命名为chinaCustoms.framework.securityOperation工具类chinaCustoms.utility代表所有海关应用工具类的代码的处理部分，工具自身的界面处理保存在扩展的.design命名空间下：例如：数据访问管理工具chinaCustoms.utility.db数据访问管理工具界面chinaCustoms.utility.db.design业务应用类chinaCustoms.application代表所有海关应用项目的父节点例如：H2010系统chinaCustoms.application.h2010HB2008chinaCustoms.application.hb2008选择查验chinaCustoms.application.ccts培训和教程示例类chinaCustoms.tutorial代表所有海关官方开发教程的父节点例如：数据访问块示例chinaCustoms.tutorial.utility.dbH2010开发示例chinaCustoms.tutorial.applicaion.h2010单元测试类UnitTest的命名空间规则如下：目标类型的命名空间：chinaCustoms.utility.dbUnitTest的命名空间：chinaCustoms.utility.db.test示例：JavaScript var chinaCustoms; if (typeof (chinaCustoms) = undefined) | (chinaCustoms = null) chinaCustoms = new Object(); if (typeof (chinaCustoms.framework) = undefined) | (chinaCustoms.framework = null) chinaCustoms.framework = new Object(); if (typeof (chinaCustoms.framework.deluxeWorks) = undefined) | (chinaCustoms.framework.deluxeWorks = null) chinaCustoms.framework.deluxeWorks = new Object(); if (typeof (chinaCustoms.framework.deluxeWorks.data) = undefined) | (chinaCustoms.framework.deluxeWorks.data = null) chinaCustoms.framework.deluxeWorks.data = new Object(); chinaCustoms.framework.deluxeWorks.data.database = function(dbName) this.isConnected = false; this.dbName = dbName; chinaCustoms.framework.deluxeWtotype.connect = function() alert(connected); var db = new chinaCustoms.framework.deluxeWorks.data.database(H2010); alert(db.dbName); db.connect(); alert(ok);变量强制采用匈牙利命名法约束性：适于范围：浏览器端、服务端前缀解释示例bBooleanbIsRegisteredc统计的数量（Count）cElementsobjObject类型objTargetn数值nTagsarr数组arrNamessStringsFirstNamei用于迭代中的索引对象arrNamesiNamer / c数据中的行（row）/列（col）cAddressg_全局变量g_sApplicationNamem_成员变量m_nAgefn委托fnHandler表：命名法约定基本编码规范除全局变量外，使用前明确声明每个变量 约束性：适于范围：浏览器端、服务端显式在每行代码最后用“;”结束约束性：适于范围：浏览器端、服务端示例：JavaScript错误的代码function sort(a, b) col1 = a.getElementsByTagName(TD)Col col1 = b.getElementsByTagName(TD)Col text1 = col1.firstChild.data text1 = col2.firstChild.data if (text1 text2) return Ascending ? -1 : 1 else return Ascending ? 1 : -1 else return 0正确的代码var g_bAscending = true;var g_iCol = 0;function sort(a, b) / get each column by its index var col1 = a.getElementsByTagName(TD)g_iCol; var col2 = b.getElementsByTagName(TD)g_iCol; / get content var text1 = col1.firstChild.data; var text1 = col2.firstChild.data; / compare and switch if (text1 text2) return g_bAscending ? -1 : 1 else return g_bAscending ? 1 : -1 else return 0尽量避免使用全局变量，涉及全局参数传递尽量封装在命名空间中约束性：适于范围：浏览器端、服务端避免采用eval()方式的构造过程主要为了减少对象引用和使用过程中的性能损失。约束性：适于范围：浏览器端、服务端除非项目明确约定目标浏览器类型，对于采用JavaScript开发海关应用的团队，需要在JavaScript公共库部分封装并解决浏览器兼容性问题。约束性：适于范围：浏览器端、服务端严禁在功能页面中增加浏览器类型判断逻辑及不同分支的兼容性处理逻辑，兼容性逻辑统一置于单独封装的JavaScript库中。约束性：适于范围：浏览器端性能要求尽可能采用JavaScript的内置函数采用内置函数的优势如下： 因为JavaScript编译器本身采用的是执行效率更好的语言完成（C+、Java、C#等），使用这些函数绝大部分情况下会获得比用JavaScript自己封装函数更好的性能。 减少自定义函数出现bug的可能 减少代码总量，提高浏览器加载速度示例：为了实现验证输入的文本中是否仅英文字母和数字，采用JavaScript内置正则表达式，只需要两行代码即可实现，对应的单元测试如下：JavaScriptvar reAlphaNum = /a-zA-Z0-9+$/;return reAlphaNum.test(s);Unit Testvar sItem;var bMatched;function assertIsTrue(b) if (!b) throw new Failed;function assertIsFalse(b) assertIsTrue(!b);function bIsAlphaNumeric(s) var reAlphaNum = /a-zA-Z0-9+$/; return reAlphaNum.test(s);sItem = 1;bMatched = bIsAlphaNumeric(sItem);assertIsTrue(bMatched);sItem = aadfasdfaVasdf234asdfa;bMatched = bIsAlphaNumeric(sItem);assertIsTrue(bMatched);sItem = FF;bMatched = bIsAlphaNumeric(sItem);assertIsFalse(bMatched);对于涉及数组排序的内容，尽量采用Array.Sort由于该方法由JavaScript解释器内部提供，因此绝大部分情况下，效率相对用JavaScript完成的自定义函数要好。 其中无参的Array.Sort()采用按字典排序， 因为JavaScript内部会将其转换为string； 有参数的Array.Sort()用于高级排序;约束性：适于范围：浏览器端、服务端向变量赋值常量须在循环体外部约束性：适于范围：浏览器端、服务端基于上下文确定值引用型变量属性（或确定返回结果函数）作为循环结束条件须在循环体外部定义约束性：适于范围：浏览器端、服务端JavaScript错误的写法for (var i = 0; i document.getElementsByTagName(a).length; i+) var sPrefix = Found element:; var arrElements = document.getElementsByTagName(a); var sElementStr = sPrefix + arrElementsi.tagName; alert(sElementStr);正确的写法var arrElements = document.getElementsByTagName(a);var sPrefix = Found element:;var nLen = arrElements.length;for (var i = 0; i nLen; i+) alert(sPrefix + arrElementsi.tarName);避免使用With语句尽管JavaScript为了简化编码，提供了with语句，但由于引用型对象使用with语句会在执行时带来性能损失。因此，统一要求避免使用with语句。约束性：适于范围：浏览器端、服务端JavaScript错误的写法with (rmation.settings.files) primary = Names; secondary = roles; applyTo = All;正确的写法var objFiles = rmation.settings.files；objFiles.primary = Names;objFiles.secondary = roles;objFiles.applyTo = All;对象方法赋值尽量采用匿名方法而非new Function()方式主要出于执行效率考虑，减少JavaScript解释器运行时再次分析委托方法约束性：适于范围：浏览器端、服务端JavaScript错误的写法function addMethodToObj(objTarget, oProperty, sFunctionName) objTargetoProperty = new Function(sFunctionName);addMethodToObj(objMyObj, rotate90, this.angle = (this.angle + 90) % 360);addMethodToObj(objMyObj, rotate60, this.angle = (this.angle + 60) % 360);正确的写法function addMethodToObj(objTarget, oProperty, objFunc) objTargetoProperty = objFunc;addMethodToObj(objMyObj, rotate90, function()this.angle = (this.angle + 90) % 360;);addMethodToObj(objMyObj, rotate60, function()this.angle = (this.angle + 60) % 360;);避免在调用setTimeout和setInterval()时传递string型名称指定委托处理内容因为这样会导致JavaScript每次执行该方法时，再次解析对应的委托方法。约束性：适于范围：浏览器端、服务端JavaScript错误的写法 setInterval(displayData(), 1000); setTimeout(moveElementBy(x); x += 5;, 1000);正确的写法 function displayData() / some process setInterval(displayData, 1000); setTimeout(function() moveElementBy(x); x += 5; );尽量避免使用“+”连接字符串，采用string连接函数的重载操作符“+=”由于JavaScript每次“+”运算后都会产生新的字符串实例，为了提高效率建议采用“+=”。约束性：适于范围：浏览器端、服务端JavaScript错误的写法 var sNew = ; sNew += str x + str y + str z; 正确的写法 var sNew = ; sNew += str x; sNew += str y; sNew += str z;如果要处理大量HTML信息，采用innerHTML而非DOM方式约束性：适于范围：浏览器端对于涉及多次操作更新UI信息的界面DOM元素，为了避免界面滚动，尽量采用一次性赋值的方式实现上，建议先在内存中定制对象，然后一次性将其赋值到界面元素上。约束性：适于范围：浏览器端事件处理尽量采用事件方式而非轮循方式响应采用JavaScript提供的事件机制往往可以提高应用的执行效率，对于绝大多数海关Web前端应用而言，除个别监控类项目外，要尽量避免采用轮循方式动态监测对象状态。即便对于监控项目，Web前端架构也要尽可能向异步事件方式靠拢，降低前端因轮循带来的性能损失。约束性：适于范围：浏览器端、服务端以window.loaded为例，JavaScript应用为了确定在加载完成这个点执行相关操作，轮循和事件方式两者执行模式差异如下图2和图3：图2：轮循方式判断加载完成图3：事件方式判断加载完成注意DOM对象层次关系对于事件抛出和捕获的影响考虑到JavaScript提供根据DOM对象层次关系的“抛出”、“捕获”机制（如图4），因此应用设计上需要在恰当的位置对于事件进行处理和封装。约束性：适于范围：浏览器端、服务端图4：JavaScript根据DOM层次进行事件“抛出”、“捕获”的示意为了有效提供多个DOM对象的事件出版预定机制，建议采用DOM level 2规范的新事件模型但考虑到IE与DOM标准间的兼容性问题，考虑到跨浏览器的问题，还需要封装统一的事件预定模型。同上，兼容性逻辑须在独立的JavaScript库封装，严禁置于具体功能页面内部。约束性：适于范围：浏览器端JavaScript IE标准与COM标准间的差异DOM 事件element.addEventListener(evt, fn, capture);element.removeEventListener(evt, fn, capture);IEx事件element.attachEvent(evt, fn);element.detachEvent(evt, fn);JavaScript传统写法 init = function() alert(initialized); window.onload = init();或者 init = function() alert(initialized); 增加了兼容性的新写法（这里仅为了示例写在页面逻辑中） function addEventHandler(objNode, sEventName, fnHandler) if (objNode = undefined) | (objNode = null) return; if (typeof (window.event) != undefined) / IE x的处理 objNode.attachEvent(on + sEventName, fnHa