Arch4系统开发指南-开发规范篇
技术平台组
目录
1前言 (4)
1.1文档编写目的 (4)
1.2文档适用范围 (4)
1.3修订历史 (4)
2开发规范目标 (5)
3命名规范 (5)
3.1总命名规则 (5)
3.1.1概述 (5)
3.1.2典型环境名 (5)
3.1.3典型对象名 (5)
3.1.4典型操作名 (6)
3.1.5举例 (6)
3.2目录命名规范 (7)
3.2.1页面目录命名规则 (7)
3.2.2Java程序目录结构 (8)
5.1文件命名规范 (9)
5.1.1页面文件（表单）命名规则 (9)
5.1.2页面片段文件（表单）命名规则 (9)
5.1.3Java文件命名规则 (9)
5.2Java程序命名规范 (9)
5.2.1Java包命名规则 (9)
5.2.2Java类命名规则 (10)
5.2.3Java属性命名规则 (10)
5.2.4Java方法命名规则 (10)
5.3词根表 (11)
6开发规范 (12)
6.1子系统/模块规范 (12)
6.1.1子系统命名规范 (12)
6.1.2模块命名规范 (12)
6.1.3特殊模块 (12)
6.2WEB层规范 (12)
6.2.1命名规范 (12)
6.2.2类编程规范 (13)
6.2.3方法编程规范 (13)
6.3业务层规范 (13)
6.3.1命名规范 (13)
6.3.2方法命名规范 (13)
6.3.3类编程规范 (14)
6.3.4方法编程规范 (14)
6.4实体类(PO)规范 (14)
7实现高效Java编程的基础规则 (15)
7.1避免使用new关键字来创建String对象 (15)
7.2避免使用不必要的嵌套 (15)
7.3避免在同一行声明多个变量 (15)
7.4避免使用不推荐的API (15)
7.5避免把方法本地变量和参数定义成和类变量相同的名字 (16)
7.6为所有序列化的类创建serialVersionUID (16)
7.7常量的定义加上final关键字 (16)
7.8数组的声明习惯 (17)
7.9一行只写一条语句 (17)
7.10正确释放JDBC连接 (17)
7.11表示长整数时用L来代替l（小写L） (18)
7.12Java注释 (18)
8JavaScript开发规范 (19)
8.1JavaScript原则 (19)
8.2命名规范 (19)
8.3JavaScript注释 (20)
1前言
本文档是《《Arch4系统开发指南-开发规范篇》，文档讲述的内容要求所有开发人员必须遵守。
参与项目开发的任何开发人员如果对本文档讲述的内容有疑问，在开发前请询问项目经理，不允许任何开发人员以任何理由违反本文档讲述的规范要求。
1.1文档编写目的
规范开发思想，约束开发行为，明确开发纪律。
特别约定：
1.本章规范中，我们用“subsystems”代表“各个子系统”。例如“subsystems的Action类”表述为
“各个子系统的Action类”。
2.本章规范中，我们用“module”代表“模块”。例如“module的POJO类”表述为“模块的POJO
类”。
3.本章规范中所有的英文单词都是严格遵守大小写的。
1.2文档适用范围
本文档适用于使用Arch4架构开发系统的项目组成员。下表是本文档对于项目组成员的最低要求程度：项目组成员是否必读要求程度
项目经理■是□否□了解文档结构■明白文档内容□透彻理解
系统分析师（业务）■是□否■了解文档结构□明白文档内容□透彻理解
系统分析师（技术）■是□否□了解文档结构□明白文档内容■透彻理解
高级程序员■是□否□了解文档结构■明白文档内容□透彻理解
开发工程师■是□否□了解文档结构■明白文档内容□透彻理解
质量保证工程师□是■否□了解文档结构□明白文档内容□透彻理解
对于项目经理、系统分析师、高级程序员和开发工程师，还需要阅读《Arch4系统架构设计说明书》。
1.3修订历史
修订章节类型日期作者说明
全部重整2012-02-01 周咸立新建文档
2开发规范目标
开发规范的目标是规范开发思想，约束开发行为，明确开发纪律。
开发规范要掌握的主要内容如下表所示：
内容说明备注
命名规范掌握文件、方法如何命名理解总命名规范，它是一起命名
的基础
子系统/模块规范掌握子系统/模块规范，学会如何创建新
的子系统/模块
WEB层规范明确Action的位置和写法
业务层规范明确Service的位置、分类和写法
PO类规范明确POJO是如何生成的
高效Java编程规范理解高效Java编程规范
JSP/HTML编码规范理解JSP/HTML编码规范
JavaScript开发规范理解JavaScript开发规范
3命名规范
3.1总命名规则
3.1.1概述
总命名规则：环境＋对象＋操作
环境分为分层与外挂，对象通常为表名（或逻辑表名）和布局名，表名以“维度”来做一个名字概念空间进行命名，布局名以其包含的功能对象进行命名。操作名对应相应的操作。
3.1.2典型环境名
环境名适用文件类型含义
Action Java Struts2Action对象
Service Java Service的接口
ServiceSpringImpl Java Service的Spring方式实现
3.1.3典型对象名
对象名适用对象类型含义
Proposal 逻辑表名投保单
Policy 逻辑表名保单
PrpDuser 物理表名员工
Claim 业务对象立案
User 业务对象员工
Main 表名主表
Head 布局名头部
Middle 布局名中部
Tail 布局名尾部
3.1.4典型操作名
操作名适用文件类型含义
Edit JSP 编辑
View JSP 显示
Query JSP 查询
deleteByPK Java 按主键删除
deleteXXX Java 按对象删除本身
findXXX Java 查询
findByXXX Java 按XXX查询，请勿使用getXXX
addXXX Java 添加
updateXXX Java 更新
initXXX Java 初始化
注意：getXXX易和getter方法混淆，所以不建议使用，用findByXXX方法代替3.1.5举例
3.1.5.1JSP文件举例1
表单EngageEdit.jsp，分解如下：
3.1.5.2JSP文件举例2
表单MainHeadEdit.jsp，表示基本信息头部编辑，分解如下：
3.1.5.3Java文件举例
类UserServiceSpringImpl.java，表示用户服务的Spring实现，分解如下：
在Java文件中，操作不体现在文件名中，而体现在该Java类的方法中3.2目录命名规范
除特别用途外，目录名必须全部为小写。
3.2.1页面目录命名规则
webapp为应用的目录。
目录说明
pages 应用的页面文件目录
pages/user 应用的User模块的页面文件目录
WEB-INF Web应用系统部分，包括配置文件、库文件、类文件等
WEB-INF/classes 类文件目录
WEB-INF/lib Jar文件目录
widgets WEB组件目录（所有的外部公共组件都放在这里）
widgets/sui SUI组件目录
widgets/yui2 YUI2组件目录(YUI2的目录，供SUI使用)
3.2.1.1举例
以新增报案模块功能为例说明如何确定目录名
1．确定根目录名
pages
2．确定模块目录名
模块为报案，对应关键字为regist
所以报案模块的目录名为pages/regist
3.2.2Java程序目录结构
4
5
包名说明
ins.helloworld 演示系统
https://www.doczj.com/doc/f618133514.html,er 模块根目录
https://www.doczj.com/doc/f618133514.html,er.model 模块对应的POJO对象目录
https://www.doczj.com/doc/f618133514.html,er.service 服务目录
https://www.doczj.com/doc/f618133514.html,er.service.facade 服务接口目录
https://www.doczj.com/doc/f618133514.html,er.service.spring Spring方式的服务实现目录
https://www.doczj.com/doc/f618133514.html,er.web Struts2方式的Action目录
5.1文件命名规范
除特别用途外，文件名区分大小写，每个单词的首字母大写。
5.1.1页面文件（表单）命名规则
环境为:.jsp
操作名为：
操作名适用文件类型含义
Edit JSP 编辑
View JSP 显示
Query JSP 查询
规则为：对象＋操作＋环境
以对象User为例，其文件名称如下所示：
文件名含义
UserEdit.jsp 用户编辑表单
UserQuery.jsp 用户查询表单
5.1.2页面片段文件（表单）命名规则
环境为:.jspf
规则为：对象＋操作＋环境
示例如下所示：
文件名含义
RegistMainEdit.jspf 报案主信息编辑表单片段
RegistThirdCarEdit.jspf 报案三者车信息编辑表单片段
5.1.3Java文件命名规则
规则为：对象＋操作＋环境
以对象User为例，其文件名称如下所示：
包名文件名
ins.claim.schema.model PrpDuser.java
https://www.doczj.com/doc/f618133514.html,er.service.facade UserService.java
https://www.doczj.com/doc/f618133514.html,er.service.spring UserServiceSpringImpl.java
https://www.doczj.com/doc/f618133514.html,er.web UserAction.java
5.2Java程序命名规范
5.2.1Java包命名规则
包名中所有字母均为小写。如：
ins.claim
https://www.doczj.com/doc/f618133514.html,er
ins.claim.defloss
5.2.2Java类命名规则
按Java规则，首字母大写，之后的每个单词的首字母也大写。
注意：当表名为PrpLXXX（或PrpCXXX、PrpTxxx）时，Prp作为一个单词，LXXX作为一个单词如表名为prpduser时类名为PrpDuser
典型类名如下：
对象名（表名）类名
prpduser PrpDuser
prplregist PrpLregist
prpldeflossmain PrpLdeflossMain
Policy Policy
5.2.3Java属性命名规则
规则1：首字母小写，之后的每个单词的首字母也大写。
如policyNo,itemNo
规则2：如果首字母之后的字母按规则1应该为大写时，改为小写。
如ID应该为id
如ISBN应该为isbn
如usercname应该为userCName
注：这是因为JavaBean规范中对于iD的访问是按ID的方式进行的，如果页面上写iD则无法访问到。为了避免混淆，用规则2处理，直接从最底层避免这种问题。
5.2.4Java方法命名规则
方法名为动词＋名词，如新增报案方法名为addRegist，更新报案为updateRegist
下表为标准的几种方法前缀。
方法前缀说明示例
prepareAdd 准备增加prepareAddUser、prepareAddRole
add 增加addUser、addRole
prepareUpdate 准备更新prepareUpdateUser、prepareUpdateRole
update 更新updateUser、updateRole
prepareFind 准备查询prepareFindUser、prepareFindRole
find 查询findUser、findRole
delete 删除deleteUser、deleteRole
view 查看viewUser、viewRole
findByXXX 按XXX查询findByUserCode
5.3词根表
在命名的时候，参照部门定义的词根表进行。里面包含词根的英文名、缩写及对应的中文意思。
部门词根表的文件名为“FI-WordRoot.xml”。
6开发规范
6.1子系统/模块规范
6.1.1子系统命名规范
规则为应用名＋子系统名
如保险系统包名为ins
则中科软理赔子系统包名为ins.claim
6.1.2模块命名规范
按照业务划分，如理赔包括报案、立案、结案等环节，可以按照环节划分模块。即报案模块、立案模块、结案模块等。
中科软第二代理赔子系统报案模块包名为对应的包名为ins.claim.regist
中科软第二代理赔子系统立案模块包名为对应的包名为ins.claim.claim
每个模块下都有相同的包结构,参“3.2.2Java程序目录结构”：
6.1.3特殊模块
除了对应业务的模块外，还包括接口模块。负责与外部系统的交互，如中科软第二代理赔子系统接口模块包名为对应的包名为ins.claim.interf
包名说明
ins.claim.interf 公共模块根目录
ins.claim.interf.servlet 与外部系统通过Servlet交互的目录
ins.claim.interf.webservice 与外部系统通过WebService方式交互的目录
ins.claim.interf.XXX 与外部系统通过XXX方式交互的目录
6.2WEB层规范
6.2.1命名规范
1.Action类必须存放在ins.subsystems.module.web包下。
2.ins.subsystems.module.web包下的类全部都要以“Action”结尾。
3.Action类必须继承https://www.doczj.com/doc/f618133514.html,ponents.web.Struts2Action n类。
4.类名为：模块名+后缀，如报案模块的Web层Java类名为RegistAction
6.2.2类编程规范
1.在WEB层类不允许用“new”关键字创建业务层和持久层类对象。
2.在WEB层类不允许出现与SQL语句相关的代码，不允许调用任何类拼写SQL语句。
6.2.3方法编程规范
1.调用业务层的Service必须通过接口注入。
2.在查询和翻页查询的方法中，必须把从业务层Service返回的结果集存放到Page对象中。
3.WEB层的类之间不允许互相调用。
4.WEB层仅可以抛出DataVerifyException和PermissionException。
5.方法名为：动词＋名词，如新增报案方法名为addRegist，更新报案为updateRegist。
6.3业务层规范
6.3.1命名规范
1.ins.subsystems.module.service包下不能有文件。
2.ins.subsystems.module.service.facade包下的接口名必须以Service结尾。
3.ins.subsystems.module.service.spring包下的类名必须以ServiceSpringImpl结尾。
4.类名为：模块名+后缀，如报案模块的业务层Java类的facade名为RegistService，其Spring的
实现类的名字为RegistSeviceSpringImpl
6.3.2方法命名规范
Service方法命名规范如下：
方法前缀说明示例
add 增加addUser、addRole
update 更新updateUser、updateRole
find 查询、获取等(单条或多条记录）findUser、findRole、findUserById、
findUserByUserCode
check 检查
delete 删除deleteUser、deleteRole
注意：由于和getter方法混淆，这里不采用get作为业务方法的前缀，而改用find。
6.3.3类编程规范
1.所有的ServiceSpringImpl类必须实现对应的Service接口，类和接口的名称仅相差“SpringImpl”。
2.ServiceSpringImpl类必须配置在/src/resources/spring/serviceContext.xml文件中，
值必须是首字母小写的Service接口名。
3.ServiceSpringImpl类的类变量只能用于定义Service引用，且只可用private修饰，对于这些Service
引用，只需要在ServiceSpringImpl类中生成set方法。
4.ServiceSpringImpl类的Service引用的变量名必须与serviceContext.xml文件中定义的
的id属性值相同。
6.3.4方法编程规范
1.在ServiceSpringImpl类中不允许使用“new”关键字创建持久层对象和WEB层对象。
2.在业务层仅可以抛出BusinessException。
6.4实体类(PO)规范
1.PO类由HibernateTools（Sinosoft版本）生成，不允许做任何修改的，也不允许在这个包下新增
类。
2.PO类中的属性区分大小写，在编写hibernate.reveng.xml文件时指定将自动生成。
3.PO类统一生成到ins.subsystems.schema.model包下（不分模块）。
4.类名为：对象名。通常按照表名命名，区分大小写。
如：表prplregist对应的PO类为PrpLregist
7实现高效Java编程的基础规则
7.1避免使用new关键字来创建String对象
把一个String常量copy到String 对象中通常是多余、浪费时间的。
public class test{
public void method(){
System.out.print (str);
}
private String str = new String ("1"); //这里新建对象是完全没有必要的
private String str2=”2” //正确的应该如此
}
7.2避免使用不必要的嵌套
过多的嵌套会使你的代码复杂化，减弱可读性。
public class test {
string add (){
int c=(a=a+b)+b; //过于复杂
return c
}
}
7.3避免在同一行声明多个变量
避免在同一行声明多个变量，这样可以使程序更加清晰，提高可读性。
错误的方法：
private int index, index1[];
正确的方法：
private int index;
private int index1[];
7.4避免使用不推荐的API
避免使用不推荐的API。有一些方法加了"deprecated"标记，表示不推荐使用（通常在JavaDoc中还提供了替代方法）。如List类中add方法加了"deprecated"标记，参考JavaDoc发现其建议用add()来代替addItem()。
错误的方法：
List dataList = new ArrayList ();
dataList.addItem (str);
正确的方法：
List dataList = new ArrayList ();
dataList.add (str);
7.5避免把方法本地变量和参数定义成和类变量相同的名字
把任何的变量都定义成唯一的，避免引起混淆。
错误的方法：
public void method (int j) {
final int i = 5; // VIOLATION
}
private int j = 2;
正确的方法：
public void method (int j1) {
final int i = 5; // VIOLATION
}
private int j = 2;
7.6为所有序列化的类创建serialVersionUID
为所有序列化的类创建一个serialVersionUID，可以避免破坏序列的兼容性。如果不特别制订一个UID的话，系统会自动计算UID（根据类的内容）。如果类被改变了，即时它是兼容的，你也不能反序列化老的版本了。在类中加如一个UID，编码控制类的兼容性。
错误的方法：
public class DUID implements java.io.Serializable {
public void method () {}
}
正确的方法：
public class DUIDFixed implements java.io.Serializable {
private static final long serialVersionUID = 1L;
public void method () {}
}
7.7常量的定义加上final关键字
常量的定义应该加上final标记，保证常量值从自始至终都不会改变。
错误的方法：
private int SIZE = 5;
正确的方法：
private final int SIZE = 5;
7.8数组的声明习惯
数组应该总是用Java的方式来声明，及中括号放在类型后面。
错误的方法：
byte buffer[];
正确的方法：
byte[] buffer;
7.9一行只写一条语句
一行里只写一条语句，不要挑战人的习惯用法。
错误的方法：
public class OSPL {
int method (int a, int b) {
int i = a + b; return i; // 可读性不强
}
正确的方法：
public class OSPLFixed {
int method (int a, int b) {
int i = a + b;
return i;
}
}
7.10正确释放JDBC连接
如果有JDBC连接没有关掉的话，需要在"finally"方法中关掉。如果数据库连接失败或者是没有释放连接，看上去无关紧要。但是其他的用户就需要用更长的时间等待连接，这样数据库利用效率就会下降。
确保你的代码在任何情况下，包括出错或者程序异常终止的情况下都释放数据库连接。在"finally"方法中关掉连接，就可以确保这一点。
错误的方法：
try {
Statement stmt = con.createStatement();
} catch(SQLException e) {
e.printStackTrace();
}
正确的方法：
try {
Statement stmt = con.createStatement();
} finally {
if (con != null && !con.isClosed()) {
con.close();
}
}
7.11表示长整数时用L来代替l（小写L）
表示长整数时用L来代替l（小写L），因为l（小写L）很难和1（数字1）区分。
错误的方法：
long temp = 23434l;
正确的方法：
long temp = 23434L;
7.12Java注释
单行注释以前缀//开头，样例如下所示：
// Java中的单行注释
多行注释以/*开头，以*/结尾，样例如下所示：
/*
Java中的多行注释
不能嵌套使用
*/
JavaDoc注释以/**开头，以*/结尾，可以工具生成JavaDoc文档。样例如下所示：/**
JavaDoc注释
能多行
不能嵌套使用
可用工具生成JavaDoc文档
*/
8JavaScript开发规范
8.1JavaScript原则
所有的JavaScript脚本都应该是标准的，要求支持IE6+、Safari、FileForx3.6+, Google Chrome等主流浏览器。
8.2命名规范
3．JavaScript文件
JavaScript程序应独立保存在后缀名为.js的文件中。
JavaScript 代码不应该被包含在HTML 文件中，除非这是段特定只属于此部分的代码。在HTML 中的JavaScript代码会明显增加文件大小，而且也不能对其进行缓存和压缩。
filename.js 应尽量放到body 的后面。这样可以减少因为载入脚本而造成其他页面内容载入也被延迟的问题。
4．变量名命名规范
* 常量及全局变量采用全部大写的形式。
* 变量名采用大小写混合形式，除首单词的字母全部小写外其余单词的首字母都大写。
* 变量名过长的可以采用单词缩写，除广泛使用的缩写外，采用单词缩写的变量名必须添加注释。
5．变量使用规范
* 变量名使用之前必须定义，未定义的变量名禁止使用。
* 变量的使用要尽量的减小作用域。例如：
for(var I = 0;I ...... } 6．函数及名称的命名规范 * 函数名尽量采用“动词+名词”的命名方式。 * 函数名称中的动词前缀必须是和函数功能相关的完整动词。 * 函数名称的第一个单词全部小写，后面的单词首字母大写。例如： function getUserName(){ .........//此处要开始缩进。 } 7．缩进 缩进的单位为两个空格。避免使用Tab 键来缩进。因为始终没有个统一的Tab 长短标准。 虽然使用空格会增加文件的大小，但在局域网中几乎可以忽略，且在最小化过程中也可被消除掉。 8．函数声明 所有的函数在使用前进行声明。内函数的声明跟在var语句的后面。这样可以帮助判断哪些变量是在函数范围内的。函数名与“(”（左括号）之间不应该有空格。“)”（右括号）与开始程序体的“{” （左大括号）之间应插入一个空格。函数程序体应缩进四个空格。“}”（右大括号）与声明函数的那一行代码头部对齐。 function outer(c，d) { var e = c * d; function inner(a，b) { return (e * a) + b; } return inner(0，1); } 8.3JavaScript注释 1．单行注释 插入单行注释的符号是“//”，示例如下所示： 2．多行注释 多行注释以"/*"开始，以"*/"结束，示例如下所示：
相关主题
文本预览