Java软件开发规范

　Java 软件开发规范 版本说明 版本 作者 日期 备注 征求版

　 提出初始版本，分发各相关人员

　JAVA 软件开发规范 1

　1

　绪论 4

　1.1

　概述 4

　1.2

　优良代码的特点 4

　1.3

　适用范围 4

　2

　总体架构 4

　2.1

　框架概述 4

　2.2

　框架规范 4

　2.2.1

　Service 规范 5

　2.2.2

　Model 规范 5

　2.2.3

　DAO 规范 5

　2.2.4

　Servlet 规范 5

　2.2.5

　Action 规范 5

　2.2.6

　消息规范 错误! 未定义书签。

　3

　J AVA 开发规范 5

　3.1

　风格规范 5

　3.1.1

　风格概述 5

　3.1.2

　类(包)导入规范 6

　3.1.3

　缩进规范 6

　3.1.4

　表达式和语句规范 6

　3.1.5

　括号规范 6

　3.1.6

　空格规范 7

　3.1.7

　空行规范 7

　3.1.8

　注释规范 7

　3.2

　模块划分 8

　3.3

　包存放规范 9

　3.4

　命名规范 10

　3.4.1

　包命名规范 10

　3.4.2

　类(接口) 命名规范 10

　3.4.3

　字段命名规范 11

　3.4.4

　方法命名规范 11

　3.5

　方法编写规范 11

　3.5.1

　基本原则 11

　3.5.2

　参数规范 12

　3.5.3

　出口规范 12

　3.5.4

　注意事项 12

　3.6

　语句选择规范 13

　3.6.1

　分支语句 13

　3.6.2

　循环语句 13

　3.7

　异常处理与资源回收 15

　3.7.1

　异常处理 15

　3.7.2

　资源回收 15

　3.8

　性能与安全 16

　3.8.1

　基本原则 16

　3.8.2

　减少重复计算 16

　3.8.3

　可变字符串 17

　3.8.4

　集合实现 17

　3.8.5

　对象创建与释放 18

　3.8.6

　代码同步 18

　4

　WEB 开发规范 18

　4.1

　目录规范 18

　4.1.1

　一般原则 18

　4.1.2

　根目录 18

　4.1.3

　公用资源目录 18

　4.1.4

　业务模块目录 19

　4.1.5

　文件引用规范 19

　4.1.6

　配置文件目录 19

　4.1.7

　配置文件命名 22

　Spring 配置文件命名 22

　Spring 配置文件中 Bean 的命名 22

　Struts 配置文件命名 22

　其他配置文件命名 22

　4.2

　HTML 规范 22

　4.2.1

　页面规范 22

　4.2.2

　元素 name 命名规范 23

　4.2.3

　元素 id 命名规范 23

　JSP 规范 23

　4.3.1

　JSP 页面规范 23

　4.3.2

　JSP 编码规范 23

　4.3.3

　单记录页面布局规范 24

　4.3.4

　列表记录页面规范 25

　4.3.5

　数据有效性验证 26

　4.3.6

　特别规定 26

　4.3

　安全验证 29

　5

　附录 29

　第三方组件的使用 29

　引入新的第三方组件 29

　5.1

　特殊要求 30

　5.5.1

　页面传值要求 30

　5.5.2

　常用操作类型定义 30

　5.5.3

　维护页面个数 30

　5.5.4

　数据保持 30

　5.2

　其它 30

　5.3

　错误收集 31

　 1 绪论 1.1 概述 本规范的目的是使本公司能以标准的、规范的方式设计和编码。通过建立开发规范，使每个开发人员养成良好的开发风格和习惯；提高程序的可靠性、可读性、可维护性和一致性等，提高程序员的开发水平，增进团队间的交流，并保证软件产品的质量。

　代码虽然是给机器运行的，但却是给人读的。

　最基本的原则是运用常识。当找不到任何规则或指导方针或者规则明显不适用时，运用常识并核实本规范的基本原则。这条规则比其它所有规则都重要，记住一点，常识必不可少。当出现该情况时，应当及时收集并提交，以便完善本规范。

　1.2 优良 代码的特点 任何的软件设计中，都离不开编程实现。在软件实现中，除了程序架构设计、数据结构设计、算法的设计以外，还有具体的代码的编写规范问题。

　好的代码应该具有以下的特征：

　 准确性：保证程序运行稳定、正确，不容易出错；  简单性：程序代码容易管理；  清晰性：程序容易理解，无论对人还是计算机；  普遍性：在很广泛的情况下都能工作的很好，也容易做修改以适应新出现的情况； 1.3 适用 范围 本规范适用于XXX 经营分析系统下所有有软件项目、产品等的设计、开发以及维护、升级等。

　本公司所有从事 经营分析系统产品开发的软件开发人员在整个软件开发过程中必须遵循此规范。

　2 总体架构 2.1 框架 概述 2.2 框架 规范 XXX 经营分析系统下所有的模块和子系统都应该使用 SSH(Struts1.2.* + Spring1.2/2.* +

　Hibernate 2.1.*/3.*) 或 Seam(Seam2.1.* 或 以 上 ) 框 架 进 行 开 发 （ 具 体 使 用 的Sturts,Spring,Hibernate 版本在 Maven 的 Master 项目中定义）。

　XXX 经营分析系统下所有的模块和子系统的开发都应该使用 JDK1.5.*版本，不能使用JDK1.6.*版本。

　2.2.1 Service 规范 只完成业务逻辑操作，数据库事务在此层进行控制。

　Struts Form 类不能作为参数传入 Service 类中。

　2.2.2 Model 规范 只有属性及属性的 Getter 和 Setter 方法，以及必要的 euqals 和 hashcode 方法。

　2.2.3 DAO 规范 只做存取、更新、删除数据的操作，SQL 语句应该出现在此层的类中。

　2.2.4 Servlet 规范 只做请求转发、结果返回的工作，逻辑及数据操作放到 Service 及 DAO 层。

　2.2.5 Action 规范 同 Servlet，只做请求参数接收、请求转发、结果转换、结果返回的工作。

　3 Java 开 发 规范 本部分着重 B/S 结构中 Server 端 Java 代码的规范。

　3.1 风格规范 3.1.1 风格概述 在实际的开发中，由于项目期限等原因，尽管已经有初步的开发规范，但在项目后期常常失控，为了赶进度，开发人员逐渐养成了一些不良的习惯。命名随意(汉语拼音英文混合、词不达意、动名词不分)、注释不清晰、导入不使用的类、定义不使用的变量、方法存在不需要的参数、方法命名与方法实现功能不一致、程序缩进不一致等。这些都是需要规范的地方。

　好的程序书写规范比随意的书写规范更清晰、错误更少、更易修改。所以，一开始就要注意使用好的编写风格。好的程序设计风格就如同好的文章，不仅要求语句顺畅，而且段落分明，结构紧凑。不仅排版要清晰，标点符号正确使用，而且重点要突出，中心明确。

　让我们从这些基本的编程技术基础上入手，改正以前的不良习惯，逐步提高应用交付的质量。

　3.1.2 类( 包) 导入规范 在 import 需要用到的类时，尽量少用 import *；而应当具体指明需要导入的类，利于代码阅读，知道用到了具体的什么类。同时，由于我司目前开发的应用为打包，所以还不存在较大问题，今后开发的应用进一步规范化之后，打包时会将*所涉及到的类全部导入。

　导入需要用到的类应当按照一定的顺序导入，不能随便写，此处规定，导入顺序如下，且前后类别之间以空行隔开：

　 Java 标准包类  Java 扩展包类  第三方组件包类  公司基础库包类  业务系统自身基础包类 3.1.3 缩进 规范 源码缩进不仅仅使程序更美观，而且也使程序结构更清晰、易读。采用统一的 Tab 缩进方式。各集成开发工具应当将 Tab 键设为 4 个空格。在类的定义、方法体的开始以及 if、for、do、while、switch、case 语句中的程序都要采用如上的缩进方式。

　3.1.4 表达式和语句规范 表达示和语句是程序中使用最多的基本语法，也是构成程序逻辑的基本要素，它们的不合理使用很大地影响了程序的清晰性、简洁性。

　3.1.5 括号 规范 在表达示中，因为算术运算符，关系运算符和逻辑运算符的优先级别一般很难记清，因此规定采用括号“（）”显式划分计算的优先级，排除二义性。

　在条件判断中，无论执行语有几条，都应当以大括号“{}”括起来，否则容易引入 Bug。

　在复杂的条件判断中必须要使用括号把各个条件分隔开来。

　3.1.6 空格规范 关键词和操作符之间加空格； 方法名之后不要留空格，紧跟左括号“（”，以与关键字区别； 方法中参数之间夹空格； 赋值操作符、比较操作符、算术操作符、逻辑操作符、位与操作符，如“=”、“+=” “>=”、“<=”、“+”、“%”、“&&”、“||”、“<<”,“^”等二元操作符的前后应当加空格； 一元操作符如“!”、“~”、“++”、“--”、“&”（地址运算符）等前后不加空格； 对于表达式比较长的 for 语句和 if 语句，为了紧凑起见可以适当地去掉一些空格，如 for (i=0; i<10; i++)和 if ((a<=b) && (c<=d))。

　3.1.7 空行规范 包命名的行和后续导入的类(包)之间加一个空行； 按 3.1.2 规范导入的类(包)之间加空行； 在导入类和类注释之间加空行； 方法和方法之间加空行； 相对独立的程序块与块之间加空行； 较长的语句、表达式等要分成多行书写（是否需要换行可以以是否要拖到左右滚动条才能看到整行代码为准，即需要拖到滚动条才能看见整行代码的需要进行换行处理）；

　划分出的新行要进行适当缩进，使排版整齐，语句可读。

　长表达式要在低优先级操作符处划分新行，操作符放在新行之首； 循环、判断等语句中若有较长的表达式或语句，则要进行适当划分； 方法参数较长，进行适当的划分；

　不允许把多个短语句写在一行中，即一行只写一条语句； 方法或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格。

　程序的分界符“{”和“}”应独占一行并且位于同一列，同时与引用它们的语句左对齐； 3.1.8 注释规范 为便于维护，对程序应当给出适当的注释。没有注释也就意味着很快就会被抛弃，因为可能没人能懂。注释应当符合 JavaDOC 的标准，这样编译器不会给出警告，否则有的编译器可能会给出警告。

　 类(接口)注释 对类和接口应当加以注释，对该类作一个简单功能描述，同时还可以标注其他内容：如公司名称，开始编写日期等，但作者必须标注上，方便在出现问题时由原作者负责解释。注

　释示例如图 3.1 所示。

　图 3.1：类注释示例  方法注释 应当对方法进行注释。注释必须含“功能”描述，参数描述，返回值描述。如果参数较为复杂，或者怕遗忘，则详细说明每个参数的作用、取值范围及相互间的关系。方法注释示例如图 3.2 所示。

　图 3.2：方法注释示例  代码注释 对于较长或逻辑较负责的代码段，都应该添加注释，注释主要说明为什么要这样做以及都做了些什么工作。代码注释示例见图 3.3 所示：

　图 3.3：代码注释示例 3.2 模块划分 合理的模块划分能提高我司按模块提交项目的能力。在一个项目开始之前，应当进行合理的模块划分，各个包之间不能有循环引用的关系。划分之后任一模块的业务代码应当仅依赖于下述包(或类)：

　 Java 标准包  Java 扩展包  第三方组件包  公司基础库包  业务系统基础包 除此之外，不应该再导入其他类(包)，如有导入，则说明模块划分可能不够合理。设计人员在设计之初应当对此进行全局考虑。

　3.3 包存放规范 尽管 Java 支持未命名包，但为让程序显得美观、清晰直观，程序应当放到相应的包下。我公司开发的程序应当放到 com.XXX 包或其子目录下。

　此处规定，禁止写未命名包的程序，希望大家遵守。

　Java 包命名规范如下：

　包名 使用描述 com.XXX.biframe AIOmniVison-tech 部门使用的根包，Tech 部门所有的类都放在此包下 com.XXX.biapp AIOmniVison-app 部门使用的根包，App 部门所有的类都放在此包下 com.XXX.bistudio 存放构建在 Eclipse 基础上的经分开发工具的代码 com.XXX.util 存放在 biframe 及 biapp 中都需要使用的工具类 com.XXX.biframe[biapp].<模块名> 相应的模块应该在根包下都有一个子包，每个模块在根包下有且只能有一个子包 com.XXX.biframe[biapp].<模块名>.action 存放模块的 action 类，如果模块中的子模块较多，可以在此目录下再建子模块包 com.XXX.biframe[biapp].<模块名>.dao 存放模块的 dao 接口类，如果模块中的子模块较多，可以在此目录下再建子模块包 com.XXX.biframe[biapp].<模块名>.dao.impl 存放模块的 dao 实现类，如果模块中的子模块较多，可以在此目录下再建子模块包 com.XXX.biframe[biapp].<模块名>.model 存放模块中 Hibernate 使用的数据对象映射类及.hbm.xml 配置文件 com.XXX.biframe[biapp].<模块名>.service 存放模块的 Service 接口类，如果模块中的子模块较多，可以在此目录下再建子模块包

　com.XXX.biframe[biapp].<模块名>.service.impl 存放模块的 Service 实现类，如果模块中的子模块较多，可以在此目录下再建子模块包 com.XXX.biframe[biapp].<模块名>.util 存放模块中使用的工具类 com.XXX.biframe[biapp].<模块名>.servlet 存放模块中使用的Servlet类（不推荐使用Servlet来实现控制转发或逻辑处理）

　3.4 命名规范 命名采用英文命名，禁止采用中文汉语拼音命名，命名采用大小写混合，提高可读性。命名应当能顾名思义，能够正确表达出想要表达的意思。

　3.4.1 包命名规范 包表示一对类的共同含义，可以对应应用开发的模块，必须以名词(或动名词)命名，必须全部采取小写字母形式，并具备规定的层次。

　如 com.XXX.report 包表示出现在该包内的类都是为报表服务的。

　3.4.2 类( 接口) 命名规范 类和接口表示一类对象，必须以名词命名。类名的第一个字母必须大写，类名如由多个单词(或缩写)构成，则每个单词(缩写)的头一个字母必须大写。如消息管理器命名为MessageManager。

　为统一起见，对我司的框架中出现的五种类做出进一步规定，如下：

　 Action 类 Action 类必须以“Action”结尾，如 AmsAssetsCheckHeaderAction；  Dao 类 Dao 接口类必须以“I”大写字母开头，以“Dao”字母结尾，如 IAmsAssetsCheckHeaderDao； Dao 实现类必须以“Impl”字母结尾，如 AmsAssetsCheckHeaderDaoImpl；  Service 类 Service 接 口 类 必 须 以 “ I ” 大 写 字 母 开 头 ， 以 “ Service ” 字 母 结 尾 ， 如IAmsAssetsCheckHeaderService； Service 实现类必须以“Impl”字母结尾，如 AmsAssetsCheckHeaderServiceImpl；  Servlet 类 Servlet 类必须以“Servlet”结尾，如 AmsAssetsCheckHeaderServlet；  Model 类 Model 类以表名为准，如 AmsAssetsCheckHeader。

　 上述五个示例类对应的表 AMS_ASSETS_CHECK_HEADER，类(接口)名和表名的对应关系为：表名第一个字母大写不变，后续字母变为小写，直到遇到下划线“_”，下划线“_”不出现在类名中，下划线“_”紧跟的字母保持大写不变，后续字母又变为小写，以此类推。

　对于不需要单独维护或查询表，不需要写对应的 Servlet 类，但其他三类应当提供，由其他的 DAO 类调用。

　3.4.3 字段命名规范 类中的字段表示类的一个属性或标志，同样也必须以名词命名。字段名的第一个字母必须 为 小 写 ， 其 余 字 母 和 表 字 段 映 射 关 系 同 类 名 和 表 名 的 映 射 关 系 。

　如 表AMS_ASSETS_CHECK_HEADER 的字段盘点工单号“TRANS_NO”则在上述四类中都必须以“transNo”出现。

　特别规定：Web 页面表单域名与 Model 对象属性名相同。

　对应关系 定义如表 3.1 ：

　所示：

　表 3.1：命名示例 表单域名 Model 属性名 数据库字段名 transNo transNo TRANS_NO 3.4.4 方法命名规范 方法表示一次操作，因此必须以动词形式命名。方法名第一个字母采取小写形式，其余字母同类(接口)的命名规则。

　Model 类中方法名和字段名的对应关系为 JavaBean 中的规则，此处不再赘述。

　3.4.5 变量命名规范 变量命名规范参加《XXX-JAVA 编码规范.doc》中“3.变量属性规范”及“4.局部变量规范”。

　3.5 方法 编写 规范 3.5.1 基本原则 方法是 Java 的基本功能单元，设计的细微缺点很容易导致该方法被错用，所以仅方法功能正确是不够的。

　一个方法应当只完成一项功能。

　对于公用接口外的方法，应当尽可能缩小其可见性，避免用一个类实例去访问其静态变量和方法。当一个方法被调用之后，方法所在类应当反馈出本次调用是成功还是失败，如果被调用方法不能反馈结果，则同一类中其他方法应当提供。

　3.5.2 参数规范 禁止方法提供超过四个的参数。如果确实需要更多参数，则用参数建立新的值对象，以此对象做参数。

　参数类型和返回值尽量接口化，以屏蔽具体的实现细节，提高程序的可扩展性。

　在方法的入口处对参数进行有效性检查。

　很多程序错误是由非法参数引起的。良好的编程典范规定：当编写一个方法时，必须验证所有传递进来的参数，如果任何一个参数不合乎要求，就应当明确地引发一个异常。boolean 参数不应当检查。

　3.5.3 出口规范 对于有返回值的方法，建议最多只提供 2 个出口（一个是判断参数有效性后可以直接返回，另一个是只能在方法体最后有返回），不好的代码如图 3.3 所示，好的代码如图 3.4 所示。

　图 3.3：方法出口错误示例(多出口)

　图 3.4：方法出口正确示例(单出口) 3.5.4 注意事项  方法的规模尽量限制在 200 行以内。超过 200 行则多半存在可以独立的逻辑单元，

　则可以将其抽取出去另写方法；  一个方法仅完成一件功能；  为简单功能编写方法；  方法的功能应该是可预测的，也就是只要输入数据相同就应产生同样的输出；  尽量不要编写依赖于其他方法内部实现的方法；  避免设计多参数方法，不使用的参数从接口中去掉；参数多时将之作为新对象的字段，以对象形式传入；  用注释详细说明每个参数的作用、取值范围及相互间的关系；  检查所有参数输入的有效性；  检查所有非参数输入的有效性，如数据文件、公共变量等。

　 方法名应准确描述方法的功能；  方法的返回值要清楚、明了，让使用者不容易忽视错误情况。

　 减少方法本身或方法间的递归调用； 3.6 语句选择规范 3.6.1 分支语句 分支语句有 if，switch 两种。if 语句多用于分支较少的情况，switch 语句正好相反。当分支较多时，采用 if 语句显得冗长，建议采用 switch 语句。

　3.6.2 循环语句 Java 循环语句中，for 语句使用频率最高，while 语句其次，do 语句很少用，可根据自己熟悉程度选用，但应当考虑效率问题。在循坏次数不太多时，三种语句循环效率无明显差别；当循环次数较大时，效率最高的是 do 循坏，其次是 for 循坏，最后是 while 循坏。

　 多重循环效率问题 在多重循环中，如果有可能，应当将最长的循环放在最内层，最短的循环放在最外层，以减少 CPU 跨切循环层的次数。示例 3-5 的效率比示例 3-6 的高。

　图 3.5：效率高的多重循环

　图 3.6：效率低的多重循环  循环内逻辑判断问题 如果循环体内存在逻辑判断，并且循环次数很大，宜将逻辑判断移到循环体外面。示例3-7 的程序比示例 3-8 多执行了 N-1 次逻辑判断。并且由于前者老要进行逻辑判断，打断了循环“流水线”作业，使得编译器不能对循环进行优化处理，降低了效率。如果 N 非常大，应当采用示例 3-8 的写法；如果 N 非常小，两者效率差别并不明显，采用示例 3-7 的写法可使程序更加简洁。

　图 3-7：低效率逻辑判断

　图 3-8：高效率逻辑判断  特殊规定

　如无必要，不应该在 for 循环体内修改循环变量，防止 for 循环失去控制。

　3.7 异常 处理与资源回收 3.7.1 异常处理 异常处理的基本思想是只对错误进行处理，如数据库操作、文件操作中的错误以及有限性资源耗尽等。

　捕捉异常是为了处理它，不要捕捉后却不做任何处理。如果不想处理，则应当申明方法抛出相应异常，由调用者处理。

　如果对不同的异常有不同的处理方式，则应该使用多个 catch 语句捕获异常，并分别进行处理。

　一个方法申明抛出的异常个数应当最小化，最好只抛出一个异常。

　在 SSH 架构开发中，异常处理流程应该是这样的：

　 Dao 层不处理错误，直接把错误抛出给调用它的 Service 层，Dao 类的方法必须要申明会抛出异常；  Service 层负责捕获及处理异常，把技术异常信息转换为用户能理解逻辑异常信息，并抛出包含此异常信息的业务逻辑异常类；  Action 层负责捕获 Service 层抛出的业务逻辑异常类，并取出业务逻辑异常信息存储在 Request 或 Session 对象中；  展现层（JSP）负责展示存储在 Request 或 Session 对象中的业务逻辑异常信息，可以通过弹出窗体显示、在错误页面上显示或在当前页面上显示； 在 com.XXX.biframe.exception 包下定义了各种常用的异常基类，经营分析系统中各模块或子系统中定义的业务逻辑异常类应该从ServiceException类或BaseRuntimeExcepton类处继承。

　3.7.2 资源回收 有限性资源使用完毕后，应当立即释放。如数据库连接，I/O 操作等。无论程序是否发生异常，资源都应当得到回收。

　回收资源的代码应当位于 finally 子句内，以保证资源得到释放，禁止与正常的业务处理代码混在一块。

　如果类中有限性资源是全局性共享资源，则类还应当提供 finalize 方法，由 JVM 在资源回收的时候调用 finalize 方法，做最后释放。

　异常处理与资源回收代码示例如图 3.9 所示。

　 图 3.9：异常与资源释放示例 3.8 性能与安全 3.8.1 基本原则 程序在满足功能的情况下，应当尽量提高运行性能。

　3.8.2 减少重复计算 如果一个代价昂贵的计算或查询多次出现，那么就只在一个地方实现，并记录结果。这

　样会避免无谓的重复计算与查询工作。示例 3.10 枚循环一次都会计算一次 size()，而 3.11 只计算一次，计算越复杂性能牺牲就越大。

　图 3.11：重复计算示例

　图 3.12：一次计算示例 3.8.3 可变字符串 处理可变字符串时，尽量使用 StringBuffer 类而非 String 类。由 StringBuffer 对象完成大部分工作，完成后将之转换为需要的 String 对象。在 1.5 及以上的 JDK 版本中可以选中使用StringBuilder 类，其效率比 StringBuffer 更高，但是线程不安全的。

　3.8.4 集合 实现 禁止使用 Vector 和 HashTable 等旧集合实现，在新的系统设计中应当分别使用 ArrayList

　和 HashMap 代替。

　数组的性能比 Vector 和 ArrayList 高，如果元素个数不变，尽量使用数组。

　在使用集合类时，变量的定义以及参数的接收应当使用接口，而非具体实现类。

　3.8.5 对象 创建与 释放 禁止在循环中频繁构建和释放对象；不再使用的对象应当及时销毁；如无必要，不要序列化对象。对于频繁使用的对象，可将其缓存起来，下次使用时直接从缓存中获取对象。

　3.8.6 代码 同步 在不需要同步操作时禁止使用同步操作；尽量少用同步方法，避免使用太多的 synchronized 关键字。

　确需使用同步时，尽量将同步代码的范围最小化。

　4 WEB 开发 规范 本部分着重 B/S 系统开发中的 JSP 编写规范。

　4.1 目录 规范 4.1.1 一般原则 Web 程序要按照一定的目录存放。公司建立积累 Web 基础库，目前主要指 Javascript和 CSS，今后随发展积累进一步提取，以促进公司开发应用的成熟度。

　从 Web 应当用的根目录算起，应当用目录不应超过三层。

　目录名称建议也采用 Java 命名规范。

　4.1.2 根目录 J2EE 平台上，包含“/WEB-INF”目录的目录称作根目录。

　应用本身的基础性文件必须位于 Web 根目录下。

　与具体业务相关的页面不能直接位于根目录下，必须位于根目录下相应模块的子目录下。

　4.1.3 公用资源目录 Web 基础库作为公用资源，供每套应用使用。在 Web 根目录下建立/jscript 目录和/ css

　目录，分别存放 Javascript 函数库和样式表文件。

　除此之外，图片文件也作公用资源看待。在根目录下建立/images 目录，其下直接存放整套应用需要使用的图片资源文件。在/images 目录下以模块名建立子目录，用于存放每个模块需要用到的图片文件。其他目录不应当再存在图片文件。（每个模块目录下也可再建images 目录用于存放模块相关的图片文件）

　4.1.4 业务模块目录 根目录下以业务模块名称建立子目录，用于存放各自的文件。如一个模块过大或有部分独立功能，可在其下再建立一层子目录。

　4.1.5 文件引用 规范 由于常采用 servlet 的 forward 的形式进行请求的转发，文件之间以“相对目录”的形式引用常常出错。为此规定，在 Web 应用中，任何文件的应用都应当采用绝对目录(此处决对目录指相对于 Web 根目录而言)。

　我司开发的应用，目前文件间的引用都是采用的绝对目录。

　但目前我司开发的应用还存在一个缺陷，当 Web 应用配置的虚拟目录不为空时，文件间的应用会出错，即找不到引用的资源。此处规定，在今后的 Web 开发中，在根目录“/”前加上虚拟目录，在 JSP 中以 request.getContextPath()获取。示例如下：

　<img src="<%=request.getContextPath()%>/images/news/Styleb1_1.gif”> 4.1.6 配置文件目录 配置文件可以提高灵活性，以适应相应的变化。位于/WEB-INF/目录下的 web.xml 是符合 J2EE 规范的标准配置文件，任何符合 J2EE 规范的应用服务器必须能正确解析该文件。其他配置文件也应当由该配置文件引导加载。

　最好的应用是在 web.xml 文件中只指定一个加载入口，而不应当加入其他的具体配置。

　经营分析系统中各子系统或模块使用的配置文件应该是独立分开的，即每个子系统或模块都有自己的配置文件(如：spring,Struts 配置文件)。在和 BIPlatform 集成时，通过在 web.xml中增加各子系统或模块的配置文件把子系统或模块和 BIPlatform 集成在一起。

　例如，  spring 配置文件的集成：

　<context-param>

　<param-name>contextConfigLocation</param-name>

　 <param-value>

　classpath:/config/common/application-common-configure.xml

　classpath:/config/<模块英文名>/application-<模块英文

　名>-configure.xml

　 </param-value> </context-param>  Struts 配置文件的集成：

　<servlet> <servlet-name>aiaction</servlet-name>

　 <servlet-class>org.apache.struts.action.ActionServlet</servlet-class>

　 <init-param>

　<param-name>config/<模块英文名></param-name> <param-value>/WEB-INF/classes/config/<模块英文名>/struts-<模块英文名>-config.xml</param-value>

　 </init-param>

　 <init-param>

　<param-name>config/common</param-name>

　<param-value>/WEB-INF/ classes/config/common/struts- common-config.xml</param-value>

　</init-param>

　<load-on-startup>2</load-on-startup> </servlet>

　 各子系统或模块中基于第三方组件/引擎的配置文件（如 Struts,Spring 配置文件）、自己读取使用的配置文件发布后都统一存放在 WEB-INF/classes/config/<modulename>/目录下； 公 用 的 配 置 文 件 （ 如 ：

　log4j ， ehcache 等 ）

　的 配 置 文 件 存 放 在WEB-INF/classes/config/common/目录下；

　表 4.1：Web 应用目录结构示例 目录名称 用途 备注 /css/ 存放所有 CSS 文件 存放公共的 css 文件 /jscript/ 存放所有公用 JS 文件 存放公共的 js 文件 /images/ 存放公用图片文件

　/images/<moduleName>/ 存放特定模块使用到的专用图片文件 如果特定模块没有专用图片文件，则不需创建对应目录。

　/<moduleName>/ 存放各模块 JSP 文件 每个应用建立单独的目录，如果应用模块较大，可在下建立各种资源子目录（css,js,images 等）

　/WEB-INF/conf/ 存放遗留配置文件 如

　XXX.properties, holiday.properties, mm7config.xml, smgpc.ini /WEB-INF/tlds 存放经营分析系统各模块/子系统自建的页面标签文件 Struts 或 JSF 的页面标签文 件 可 以 仍 然 存 放 在/WEB-INF 目录下 以下目录从/WEB-INF/classes/开始计算 /com/XXX/moduleName/servlet/ 存放 servlet 的目录 servlet 都应当位于相应模块之下，即必须有相应的包名。

　/com/XXX/moduleName/action/ 存放特定模块 Action 类目录

　/com/XXX/moduleName/dao/ 存放特定模块数据访问组件 DAO 目录

　/com/XXX/moduleName/model/ 存放特定模块 Hibernate映射文件目录

　/com/XXX/moduleName/service/ 存放特定模块业务逻辑服务类目录

　/config/<modulename> 存放各模块在运行时使用的配置文件，每个模块或子系统一个目录，存放各自要使用的配置文件 如 Spring,Struts,JSF 等的配置文件 /config/common 存放各模块或子系统公用的配置文件 如 Log4j,Ehcache 等的配置文件

　4.1.7 配置文件命名 Spring 配置文件命名

　子系统或模块的 Spring 配置文件命名规则如下：application-< 模块英文名>-configure.xml

　注：BIPlatform 中 中 spring 配置文件命名为：application-common-configure.xml Spring 配置文件中 Bean 的命名

　Spring 配置文件中 Bean 的命名规则如下：< 模块英文名>-<Bean 类名> Struts 配置文件命名

　子系统或模块的 Struts 配置文件命名规则如下：struts-< 模块英文名> -config.xml

　注：BIPlatform 中 中 Struts 配置文件命名为：struts-common-config.xml 其他配置文件命名

　子系统或模块中如果使用其他配置文件，并且这些配置文件只供本子系统/模块使用，则这些配置文件命名规则如下：< 模块英文名>-< 配置文件名>.< 配置文件后缀> 4.2 HTML 规范 通常由于浏览器的容错功能太强，即使编写不规范的页面浏览器也能解析。但我们写的程序不仅需要浏览器能识别，更大程度上需要人能识别，符合一定的规范代码更以维护。为此规定以下相关事项。

　4.2.1 页面规范  所有标记均为小写；  标记属性均为小写，属性值必须以双引号括起来；  编辑页面的文本输入框必须指定“maxlength”属性值，以免插入数据库中长度越界；  HTML 代码必须以<HTML>开头，</HTML>结尾；  所有的 Script 及其外部引用、CSS 及其外部引用均放入<HEAD></HEAD>中；  <HEAD></HEAD>之间应当设置页面所使用的语言，如 <META http-equiv="Content-Type" content="text/html; charset=GBK"/>  所有 HTML 页面必须在<TITLE></TITLE>中设置标题，禁止出现“UnTitled”或“未命名”标题的页面；  从菜单栏目链接打开的页面标题必须与菜单栏目描述一致；

　4.2.2 元素 name 命名规范 表单域元素必须命名，且必须与 Model 中属性名一致。

　4.2.3 元素 id 命名规范 尽管元素的 id 属性不是后台 servlet 所必需的，但为了页面 Javascript 操作的方便，id属性也应当命名，名称必须以双引号引起来。

　JSP 规范 4.3.1 JSP 页面规范  JSP 页面必须指定页面的编码，且放在第一行的位置，编码全部采用“UTF-8”；  JSP 页面引用类的导入规范同 3.1.2 部分的 Java 导入规范；  禁止在页面导入 Java.sql 包中的任何类；  JSP 页面不需要对会话进行判断，由基础库提供的 filter 统一完成；  JSP 页面不需要写缓存清除代码，由基础库提供的 filter 统一完成；  禁止 JSP 页面直接提交给 JSP 页面，必须提交给控制器 Servlet 转发处理； 4.3.2 JSP 编码规范  禁止 JSP 出现过多 Java 代码；  禁止在 JSP 页面出现数据库连接 Connection、；  禁止在 JSP 页面写公共方法；  JSP 页面中的 Java 脚本代码必须位于“<%”和“%>”之间，且“<%”和“%>”必须各自占一行，“<%”和“%>”必须位于一行的开头；示例代码如图 4.1 和图 4.2所示；

　图 4.1：JSP 代码示例 2

　图 4.2：JSP 代码示例 2  JSP 页面连续的 Java 代码不能之间有多余的“<%”和“%>”，图 4.3 为正确的写法，图 4.4 位错误的写法；

　图 4.3：正确的 JSP 代码示例

　图 4.4：错误的 JSP 代码示例 4.3.3 单记录页面 布局 规范  现存问题 单记录指录入数据、编辑修改数据、记录详细信息等页面。

　目前我司开发的各套应用中，对此没有统一的处理风格，界面比较杂乱。主要表现在：

　 “文字描述标签”不对齐；  同一逻辑信息其“文字描述标签”不一致；如《资产实物管理系统》中，对“资产名称”同一信息存在“资产名称”、“资产描述”、“设备名称”、“名称”等各

　种描述；  “文字描述标签”后有跟中文冒号“：”的，也有跟英文冒号“:”的，也有什么也不跟的；  文本框占据表格列的宽度长短不一；  文本框不对齐；  文本框中内容对齐方式太随意；  页面布局规范 此处做如下规定：

　 “文字描述标签”应当靠右对齐，且以中文冒号“：”结束，“标签描述”字符长度应当尽量一致；  文本框应当对齐；  文本框内容根据内容特性其布局特性不同，大致原则如下：文本字符靠左对齐，如果同一应用中该内容长度一致，则应当居中，如《资产实物管理系统》中的“资产标签”；日期及其他等长度代码居中对齐；数字靠右齐。

　单记录页面布局示例如图 4.5 所示。

　图 4.5：单记录页面布局示例 4.3.4 列表记录页面规范  现存问题 我司的查询页面都是以列表的形式显示数据记录，这也是绝大部分应用系统展示数据的方式。目前我司开发的各套应用中，对此没有统一的处理风格，界面比较杂乱。主要表现在：

　 查询按钮、导出按钮、新增、删除按钮等布局太乱；  数据列出现的先后顺序太随意，查询相同的数据，不同的页面不一样；  上下行数据没有按照统一的方式对齐；  数据折行，同一页中数据行的高度不一致；  如果同一页数据行过多，则在向下滚动后，表头部分消失，导致用户不知各列数据的具体含义(目前该问题较少)；  宽屏电脑页面出现空白；  页面布局规范 此处做如下规定：

　 按钮应当在查询条件的左边出现。按从左至右的顺序，“只读类”按钮应当先

　出现，“编辑类”按钮紧跟其后。如“查 询”、“导 出”、“新 增”、“删 除”、“失 效”；  列表显示数据的页面均采用个表格：一个用于表头部分，一个用于数据展示部分，表头部分代码如图 4.6 所示，数据展示部分代码如图 4.7 所示；  文本字符左对齐，如果确定本列文本长度一致，则应当居中对齐；  日期字符、以及其他等长文本字符居中对齐；  数字靠右对齐；

　图 4.6：表头代码示例

　图 4.7：数据表代码示例 4.3.5 数据有效性验证 数据编辑页面(含新增，修改，删除数据)提交的数据，必须进行有效性验证。有效性验证分为两类：字面格式的验证和业务逻辑的验证。除了必须有后台数据参与才能完成验证的以外，字面格式的验证以及简单的业务逻辑验证，应当在 JSP 页面完成，减轻服务器负载。

　有效性验证由公司的 Javascript 基础库完成，不能完成的，如果该验证功能是通用性需求，则扩充基础库功能，否则由该模块开发人员自行开发 javascript 方法完成。

　4.3.6 特别规定  页面加载规定

　在任何一个页面被打开后，用户可能将其最小化，而当用户再次点击相应连接时，该页面总是不弹出。其解决办法是，在每个页面的<body>标签中都加入一个初始化函数，如do_initPage()，该函数至少执行获取焦点的方法 window.focus()，可根据需要加入其他功能。

　 防止表格撑开的方法 图 4.7 的代码不能防止表格被撑开。在确认显示数据长度不大的情况下，可以采取上述方式。但当显示数据长度较大时，建议在表格列中增加一个没有名称、不带边框的只读文本框，将要显示的值显示在该文本框中。代码示例如图 4.8 所示。同时为使表格宽度可自适应调整，应当在上面的 do_initPage()方法中加入 do_SetPageWidth()方法。该方法由 Web 基础库提供，可根据屏幕分辨率自适应调整表格宽度。

　图 4.8：文本框展示数据防止表格被撑开示例  LookUp 规范 为方便用户操作和数据的规范性，应用需尽量提供选择的方式录入数据。在我司开发的应用中，常以 Select 下拉框和 LookUp 查询方式提供。

　当展示的数据条数不多，如 100 条以内，且用户关心的数据项为 1 时，可以 Select 的下拉框形式提供，没必要处处提供 LookUp 操作；反之则应当提供 LookUp 查询方式。

　公司基础库提供了较为方便的 LookUp 查询方式，但对页面提出了一定的要求，在此以特别规定的形式描述如下。

　 多数据选择 多数据选择用于选择多条数据的时候。如《资产实物管理系统》中，创建“资产调拨单”时选择资产；创建“资产盘点工单”时选择地点。LookUp 会自动创添加的表格行，并将选择的数据自动添加到相应的位置。要完成该功能，JSP 页面的数据表格需要满足一些特殊条件，如果是新增数据，则需要具备一个隐藏的空行。数据表格行要求如下：

　每个需要显示的列必须具备“name”属性和“id”属性值，“id”属性值以“name”属性值连接数字构成。比如<td name=”userName” id=”userName0”></td>； 如果表格列不具备上述特点，则表格列应当具有表单域，表单域应当具有“name”属性和“id”属性值，“id”属性值以“name”属性值连接数字构成。比如<td width="10%"><input

　type="text" name="transNo" id="transNo0"></td>； 不能同时具备上述情况； 一个表格列最多只能有一个显示表单域； 如果从 LookUp 返回的值除了需要显示的以外，还需要其他的值，则均以隐藏域的形式存在于最后一列，且最后一列需要隐藏； 表格具备上述特征后，配合相应的 Javascript 函数，则可以完成相应的功能了。

　列示例代码如图 4.9 所示，Javascript 函数示例如图 4.10 所示。

　图 4.9：LookUp 数据表空行示例

　图 4.10：LookUp Javascript 示例 1

　 单数据选择 单数据选择用于仅选择一条数据的情况。LookUp 会自动将选择的数据赋值到相应表单域。这时没有对表格的要求，但执行 LookUp 的 Servlet 设置的返回字段必须和页面表单域存在前面描述的命名规范中的对应关系。其 Javascript 函数示例如图 4.11 所示。

　 图 4.11：LookUp Javascript 示例 2 4.3 安 安 全验证 Web 应当 中，除个别 jsp 页面或 servlet ， 外， 其它 Web 页面或 或 servlet 都 应当 是受保护的资源 ，对 Web 页面的访问必须由安全验证程序进行验证。验证通过后方可访问。

　安全验证包含会话有效性验证和权限验证。

　禁止会话验证代码散布在 JSP 页面或 Servlet 中，会话验证程序由基础库统一提供。

　权限验证程序由基础库统一提供。如个别模块有特殊权限需求，则相应当模块的应当用程序自行验证相应权限。

　5 附录 第三方组件 的使用 引入新的第三方组件 在开发经营分析组件或应用的过程中，如果需要引入新的第三方组件，需要向部门经理提请“第三方组件引入使用”申请，由部门经理组织各开发小组相应的人员进行会议评审，主要审核如下几个方面：

　• 是否有必要引入此组件？ • 经分中是否已经存在相关的组件能满足需求？ • 当前引入组件是否是最优的？ • 引入组件是否和当前使用的应用服务器(Tomcat/Weblogic/Websphere)冲突？ • 引入组件是否和经分中已存在组件相冲突？ • 引 入 组 件 依 赖 的 相 关 类 库 是 否 和 当 前 使 用 的 应 用 服 务 器(Tomcat/Weblogic/Websphere)冲突？ • 引入组件依赖的相关类库是否和经分中已存在的组件相冲突？ • 引入组件依赖的相关类库是否和经分中已存在类库相冲突？ 在评审会议上，申请人应该已经根据审批标准进行相关测试并提交相关兼容性资料文档，评审人根据自己的经验做出最后是否引入新组件的决定。

　5.1 特殊要求 5.5.1 页面传值要求 Form 传值必须使用“post”方法；Form 应当含有隐藏表单域，统一命名为 cmd，代表本次操作类型；常用操作类型必须使用基础库 com.XXX.biframe.WebConstant 常量接口定义的参数，具体应用需要使用的值如果该接口没有，则从该接口扩展。

　5.5.2 常用操作类型定义 常用操作类型有特定的含义，不可更改，描述如下：

　 QUERY_ACTION：进入查询页面，且显示数据  NEW_ACTION：进入新增页面  DETAIL_ACTION：进入详细信息页面  CREATE_ACTION：新增数据  UPDATE_ACTION：更新数据  DELETE_ACTION：删除数据  EXPORT_ACTION：导出数据  SUBMIT_ACTION：提交单据，流程使用  REJECT_ ACTION：单据审批退回，流程使用  APPROVE_ACTION：单据审批通过，流程使用  CLEAR_ACTION：清除数据  TREE_ACTION：树状菜单请求 5.5.3 维护页面个数 页面个数一般根据具体情况确定。但对于维护类页面，一般只需要两张页面即可：翻页查询页面和详细信息页面。新增页面与详细信息页面使用同一页面。

　5.5.4 数据保持 在任何一步操作失败时，必须保留用户输入的数据，返回到原页面，并回显数据。

　5.2 其它 本规范中未尽事宜请参考《XXX-JAVA 编码规范.doc》

　5.3 错误收集 如果发现基础库错误，请及时与相关作者联系，以便更正。如果发现本规范语意不清或存在错别字等问题，请与 吴卫淋（wuwl@XXX.com ）联系 。