Arch4系统开发指南-开发规范篇

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

Arch4系统开发指南-开发规范篇

技术平台组

第 1 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

目 录

1

前言 ................................................................................................................................................................... 4 1.1 文档编写目的 ................................................................................................................................... 4 1.2 文档适用范围 ................................................................................................................................... 4 1.3 修订历史 ........................................................................................................................................... 4 开发规范目标 ................................................................................................................................................... 5 命名规范 ........................................................................................................................................................... 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.2 Java程序目录结构 ................................................................................................................... 8 5.1 文件命名规范 ................................................................................................................................... 9

5.1.1 页面文件（表单）命名规则 ................................................................................................... 9 5.1.2 页面片段文件（表单）命名规则............................................................................................ 9 5.1.3 Java文件命名规则 ................................................................................................................... 9 5.2 Java程序命名规范 ........................................................................................................................... 9

5.2.1 Java包命名规则 ....................................................................................................................... 9 5.2.2 Java类命名规则 ..................................................................................................................... 10 5.2.3 Java属性命名规则 ................................................................................................................. 10 5.2.4 Java方法命名规则 ................................................................................................................. 10 5.3 词根表 ..............................................................................................................................................11 开发规范 ......................................................................................................................................................... 12 6.1 子系统/模块规范 ............................................................................................................................ 12

6.1.1 子系统命名规范 ..................................................................................................................... 12 6.1.2 模块命名规范 ......................................................................................................................... 12 6.1.3 特殊模块 ................................................................................................................................. 12 6.2 WEB层规范 ................................................................................................................................... 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 实现高效Java编程的基础规则 .................................................................................................................... 15 7.1 避免使用new关键字来创建String对象 ..................................................................................... 15 7.2 避免使用不必要的嵌套 ................................................................................................................. 15 7.3 避免在同一行声明多个变量 ......................................................................................................... 15

2 3

6

7

第 2 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

8

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.12 Java注释 ......................................................................................................................................... 18 JavaScript开发规范 ........................................................................................................................................ 19 8.1 JavaScript原则 ................................................................................................................................ 19 8.2 命名规范 ......................................................................................................................................... 19 8.3 JavaScript注释 ................................................................................................................................ 20

第 3 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

1 前言

本文档是《《Arch4系统开发指南-开发规范篇》，文档讲述的内容要求所有开发人员必须遵守。 参与项目开发的任何开发人员如果对本文档讲述的内容有疑问，在开发前请询问项目经理，不允许任何开发人员以任何理由违反本文档讲述的规范要求。

1.1 文档编写目的

规范开发思想，约束开发行为，明确开发纪律。

特别约定：

1. 本章规范中，我们用“subsystems”代表“各个子系统”。例如“subsystems的Action类”表述为

“各个子系统的Action类”。

2. 本章规范中，我们用“module”代表“模块”。例如“module的POJO类”表述为“模块的POJO

类”。

3. 本章规范中所有的英文单词都是严格遵守大小写的。

1.2 文档适用范围

本文档适用于使用Arch4架构开发系统的项目组成员。下表是本文档对于项目组成员的最低要求程度：

项目组成员 项目经理 系统分析师（业务） 系统分析师（技术） 高级程序员 开发工程师 质量保证工程师 是否必读 ■是 □否 ■是 □否 ■是 □否 ■是 □否 ■是 □否 □是 ■否 要求程度 □了解文档结构 ■明白文档内容 □透彻理解 ■了解文档结构 □明白文档内容 □透彻理解 □了解文档结构 □明白文档内容 ■透彻理解 □了解文档结构 ■明白文档内容 □透彻理解 □了解文档结构 ■明白文档内容 □透彻理解 □了解文档结构 □明白文档内容 □透彻理解 对于项目经理、系统分析师、高级程序员和开发工程师，还需要阅读《Arch4系统架构设计说明书》。

1.3 修订历史

修订章节 全部 类型 重整 日期 2012-02-01 作者 周咸立 新建文档 说明 第 4 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

2 开发规范目标

开发规范的目标是规范开发思想，约束开发行为，明确开发纪律。 开发规范要掌握的主要内容如下表所示： 内容 命名规范 子系统/模块规范 WEB层规范 业务层规范 PO类规范 高效Java编程规范 JSP/HTML编码规范 JavaScript开发规范 说明 掌握文件、方法如何命名 备注 理解总命名规范，它是一起命名的基础 掌握子系统/模块规范，学会如何创建新 的子系统/模块 明确Action的位置和写法 明确Service的位置、分类和写法 明确POJO是如何生成的 理解高效Java编程规范 理解JSP/HTML编码规范 理解JavaScript开发规范 3 命名规范

3.1 总命名规则

3.1.1 概述

总命名规则：环境＋对象＋操作

环境分为分层与外挂，对象通常为表名（或逻辑表名）和布局名，表名以“维度”来做一个名字概念空间进行命名，布局名以其包含的功能对象进行命名。操作名对应相应的操作。

3.1.2 典型环境名

环境名 Action Service

适用文件类型 含义 Java Java Struts2Action对象 Service的接口 Service的Spring方式实现 ServiceSpringImpl Java 3.1.3 典型对象名

对象名 Proposal Policy PrpDuser Claim 适用对象类型 逻辑表名 逻辑表名 物理表名 业务对象 含义 投保单 保单 员工 立案 第 5 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

User Main Head Middle Tail 业务对象 表名 布局名 布局名 布局名 员工 主表 头部 中部 尾部 3.1.4 典型操作名

操作名 Edit View Query deleteByPK deleteXXX findXXX findByXXX addXXX updateXXX initXXX

适用文件类型 JSP JSP JSP Java Java Java Java Java Java Java 含义 编辑 显示 查询 按主键删除 按对象删除本身 查询 按XXX查询，请勿使用getXXX 添加 更新 初始化 注意：getXXX易和getter方法混淆，所以不建议使用，用findByXXX方法代替 3.1.5 举例

3.1.5.1 JSP文件举例1

表单EngageEdit.jsp，分解如下：

3.1.5.2 JSP文件举例2

表单MainHeadEdit.jsp，表示基本信息头部编辑，分解如下：

第 6 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

3.1.5.3 Java文件举例

类UserServiceSpringImpl.java，表示用户服务的Spring实现，分解如下：

在Java文件中，操作不体现在文件名中，而体现在该Java类的方法中

3.2 目录命名规范

除特别用途外，目录名必须全部为小写。

3.2.1 页面目录命名规则

webapp为应用的目录。

第 7 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

目录 pages pages/user WEB-INF WEB-INF/classes WEB-INF/lib widgets widgets/sui widgets/yui2

说明 应用的页面文件目录 应用的User模块的页面文件目录 Web应用系统部分，包括配置文件、库文件、类文件等 类文件目录 Jar文件目录 WEB组件目录（所有的外部公共组件都放在这里） SUI组件目录 YUI2组件目录(YUI2的目录，供SUI使用) 3.2.1.1 举例

以新增报案模块功能为例说明如何确定目录名 1． 确定根目录名

pages

2． 确定模块目录名

模块为报案，对应关键字为regist

所以报案模块的目录名为 pages/regist

3.2.2 Java程序目录结构

4

5

包名 ins.helloworld ins.helloworld.user ins.helloworld.user.model ins.helloworld.user.service ins.helloworld.user.service.facade ins.helloworld.user.service.spring ins.helloworld.user.web

说明 演示系统 模块根目录 模块对应的POJO对象目录 服务目录 服务接口目录 Spring方式的服务实现目录 Struts2方式的Action目录 第 8 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

5.1 文件命名规范

除特别用途外，文件名区分大小写，每个单词的首字母大写。

5.1.1 页面文件（表单）命名规则

环境为:.jsp 操作名为：

操作名 Edit View Query 适用文件类型 JSP JSP JSP 含义 编辑 显示 查询 规则为：对象＋操作＋环境

以对象User为例，其文件名称如下所示：

文件名 UserEdit.jsp UserQuery.jsp 含义 用户编辑表单 用户查询表单 5.1.2 页面片段文件（表单）命名规则

环境为:.jspf

规则为：对象＋操作＋环境 示例如下所示：

文件名 RegistMainEdit.jspf

含义 报案主信息编辑表单片段 RegistThirdCarEdit.jspf 报案三者车信息编辑表单片段 5.1.3 Java文件命名规则

规则为：对象＋操作＋环境

以对象User为例，其文件名称如下所示： 包名 ins.claim.schema.model ins.claim.user.service.facade ins.claim.user.service.spring ins.claim.user.web 文件名 PrpDuser.java UserService.java UserServiceSpringImpl.java UserAction.java 5.2 Java程序命名规范

5.2.1 Java包命名规则

包名中所有字母均为小写。如： ins.claim ins.claim.user

第 9 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

ins.claim.defloss

5.2.2 Java类命名规则

按Java规则，首字母大写，之后的每个单词的首字母也大写。

注意：当表名为PrpLXXX（或PrpCXXX、PrpTxxx）时， Prp作为一个单词，LXXX作为一个单词 如表名为prpduser时类名为PrpDuser 典型类名如下：

对象名（表名） prpduser prplregist prpldeflossmain Policy

类名 PrpDuser PrpLregist PrpLdeflossMain Policy 5.2.3 Java属性命名规则

规则1：首字母小写，之后的每个单词的首字母也大写。 如policyNo,itemNo

规则2：如果首字母之后的字母按规则1应该为大写时，改为小写。 如ID应该为id 如ISBN应该为isbn

如usercname应该为userCName

注：这是因为JavaBean规范中对于iD的访问是按ID的方式进行的，如果页面上写iD则无法访问到。为了避免混淆，用规则2处理，直接从最底层避免这种问题。

5.2.4 Java方法命名规则

方法名为 动词＋名词，如新增报案方法名为 addRegist，更新报案为updateRegist 下表为标准的几种方法前缀。 方法前缀 prepareAdd add prepareUpdate update prepareFind find delete view findByXXX 说明 准备增加 增加 准备更新 更新 准备查询 查询 删除 查看 示例 prepareAddUser、prepareAddRole addUser、addRole prepareUpdateUser、prepareUpdateRole updateUser、updateRole prepareFindUser、prepareFindRole findUser、findRole deleteUser、deleteRole viewUser、viewRole 按XXX查询 findByUserCode 第 10 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

5.3 词根表

在命名的时候，参照部门定义的词根表进行。里面包含词根的英文名、缩写及对应的中文意思。 部门词根表的文件名为“FI-WordRoot.xml”。

第 11 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

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 ins.claim.interf.webservice ins.claim.interf.XXX

说明 公共模块根目录 与外部系统通过Servlet交互的目录 与外部系统通过WebService方式交互的目录 与外部系统通过XXX方式交互的目录 6.2 WEB层规范

6.2.1 命名规范

1. Action类必须存放在ins.subsystems.module.web包下。

第 12 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

2. ins.subsystems.module.web包下的类全部都要以“Action”结尾。 3. Action类必须继承ins.components.web.Struts2Actionn类。 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 update find check delete 说明 增加 更新 查询、获取等(单条或多条记录） 检查 删除 示例 addUser、addRole updateUser、updateRole findUser、findRole、findUserById、findUserByUserCode deleteUser、deleteRole 注意：由于和getter方法混淆，这里不采用get作为业务方法的前缀，而改用find。

第 13 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

6.3.3 类编程规范

1. 所有的ServiceSpringImpl类必须实现对应的Service接口，类和接口的名称仅相差“SpringImpl”。 2. ServiceSpringImpl类必须配置在/src/resources/spring/serviceContext.xml文件中，的id属性

值必须是首字母小写的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

第 14 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

7 实现高效Java编程的基础规则

7.1 避免使用new关键字来创建String对象

把一个String常量copy到String 对象中通常是多余、浪费时间的。

public class test{ public void method(){ System.out.print (str); } private String str = new String (\这里新建对象是完全没有必要的 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。有一些方法加了\标记，表示不推荐使用（通常在JavaDoc中还提供了替代方法）。如List类中add方法加了\标记，参考JavaDoc发现其建议用add()来代替addItem()。

错误的方法：

第 15 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

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; 正确的方法：

第 16 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

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连接没有关掉的话，需要在\方法中关掉 。如果数据库连接失败或者是没有释放连接，看上去无关紧要。但是其他的用户就需要用更长的时间等待连接，这样数据库利用效率就会下降。确保你的代码在任何情况下，包括出错或者程序异常终止的情况下都释放数据库连接。在\方法中关掉连接，就可以确保这一点。 错误的方法：

try { Statement stmt = con.createStatement(); } catch(SQLException e) { e.printStackTrace(); } 正确的方法：

try { Statement stmt = con.createStatement(); } finally { 第 17 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

} 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.12 Java注释

单行注释以前缀//开头，样例如下所示： // Java中的单行注释 多行注释以/*开头，以*/结尾，样例如下所示： /* Java中的多行注释 不能嵌套使用 */

JavaDoc注释以/**开头，以*/结尾，可以工具生成JavaDoc文档。样例如下所示： /** JavaDoc注释 能多行 不能嵌套使用 可用工具生成JavaDoc文档 */ 第 18 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

8 JavaScript开发规范

8.1 JavaScript原则

所有的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

* 函数名尽量采用 “动词+名词”的命名方式。

* 函数名称中的动词前缀必须是和函数功能相关的完整动词。 * 函数名称的第一个单词全部小写，后面的单词首字母大写。例如： function getUserName(){ .........//此处要开始缩进。 } 7． 缩进

第 19 页 共 20 页

Arch4系统开发指南-开发规范篇 中科软科技股份有限公司

缩进的单位为两个空格。避免使用 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.3 JavaScript注释

1．单行注释

插入单行注释的符号是“//”，示例如下所示：

2．多行注释

多行注释以\/*\开始，以\*/\结束，示例如下所示：

第 20 页 共 20 页

本文来源：https://www.bwwdw.com/article/9xbg.html