CRM-PRD-技术开发规范-软件规范

技术开发规范

编写编写时间

审批审批时间

文档版本

文档修订摘要

审阅

日期修订号描述著者日期

者

20xx-xx-xx1建V.XX

根据XX的反馈意见补充了分层技术架构、

20xx-xx-xx2数据库架构、安全审计需求章节，同时对XX

错误码、常.量部分进行了修订

根据XX的意见补充了架构组和平台组需

20xx-xx-xx3XX

要提供的公共程序章节

根据XX方要求把涉及到设计的相关章节

20xx-xx-xx4XX

从文档中剔除，单独形成文档

目录

第1章弓I言................................................................-.........5

1.1文档用途.......................................................................5

1.2阅读对象.......................................................................5

1.3参考文档.......................................................................5

第2章工程目录规划...................................................................6

2.1“c目录规划及说明................................................................6

2.2html目录规划及说明..............................................................7

2.3config目录规划及说明.............................................................8

2.4lib目录说明......................................................................9

第3章分层开发规范.................................................................10

3.1页面展现层.......................................................................10

3.1.ICSS样式开发规范..........................................................10

3.1.2JSP开发规范...............................................................11

3.1.3JS开发规范................................................................12

3.3.3Action开发规范............................................................14

3.1.4其他注意事项..............................................

3.1业务逻辑层....................................................................15

3.2.1业务服务对象获取规则......................................................15

3.2.2与其它层的交互规则........................................................16

3.2.3其它注意事项..............................................................16

3.3数据存取层.......................................................................18

3.3.1数据存取对象获取规则......................................................18

332与其它层的交互规则.........................................................18

3.3.3其它注意事项..............................................................20

第4章基础命名规范..................................................................23

4.1类命名规范......................................................................23

4.2成员函数命名规范...............................................................25

4.3变量属性命名规范................................................................26

4.4局部变量命名规范...............................................................27

第5章数据库开发规范................................................................27

5.1Cache加载及使用.................................................

5.2SQL变量绑定.....................................................................21

5.3批量数据保存.....................................................................21

5.4SEQUENCE使用..................................................................22

5.5其它注意事项....................................................

第6章日志处理......................................................................30

第7章错误码........................................................

第8章常量..........................................................................32

第1章引言

1.1文档用途

本文档侧重于对基于XX研发中心Appframe、Comframe开发平台编程的规则和范例进行

说明，主要内容包括：工程目录规划；文件命名规则；页面层、逻辑层、数据层开发规范等。

本文档主要面向开发/测试人员，为以后的程序编码/测试工作提供依据，最终达到以下

目的：

<增加开发过程代码的强壮性、可读性、易维护性；减少有经验和无经验开发人员编

程所需的脑力工作；

令在产品研发或项目实施时统一代码风格；

◊通过人为以及自动的方式对最终软件应用质量标准；

<使新的开发人员快速适应项目的氛围；

令支持资源的复用：允许开发人员从一个研发或项FI团队移动到另一个，而不需要重

新适应新的团队的开发氛围。

1.2阅读对象

本规范适用F：

令开发工程师：通过本文了解产品研发或项目实施时的技术开发规范

<测试工程师：通过本文了解产品研发或项目实施的的技术开发规范

<其它相关人员：如使用产品的电信运营商，或者从事基础技术研究的工程师

1.3参考文档

《JAVA编码规范.doc》

《APPFrame5.2前台界面规范汇总.doc》

《南方基地（西藏）项目开发规范.doc》

第2章工程目录规划

XX研发中心项FI所有的JAVA代码统一建立一个工程，工程下创建四个目录：htmksrc.

lib、config,以下对4个目录的规划逐一进行说明。

2.1src目录规划及说明

Src目录存放工程中所有的java文件，src目录的划分原则如下：

a）先针对业务域做目录划分，一致划分到颗粒度最小的业务模块，划分如下:

/src/com/asiainfo/boss/common公共子模块，用于存放一些公用的代

吗。主要包括：操作日志记录、公共

的静态数据类、公共的web方法等。

cache公共缓存实现

center中心路由方法

sn公共序列管理

tab分表规则实现

.....

/com/asiainfo/boss/so营业模块

/soframe营业受理框架

/order订单子模块

/instance实例子模块

......其它

/com/asiainfo/boss/ams般务管理模块

/balance资金管理子模块

/bill喉单管理子模块

/owe欠费管理子模块

其它

Zcom/asiainfo/boss/channel渠道管理模块

/channelinfo渠道信息管理

/staff人员信息管理

/reward渠道佣金

其它

/com/asiainfo/boss/rcs资源管理模块

/phone号码管理

/simSIM卡管理

/equip终端管理

其它

/com/asiainfo/boss/markct集团客户模块

/custmgr客户经理管理

/salesmgr营销活动管理

其它

/com/asiainfo/boss/intcr接口模块

/zw哝务接口子模块

/open开通接口子模块

/cbossCBOSS接口子模块

其它

/com/asiainfb/boss/cusi客户管理模块

/com/asiainfo/boss/sec权限模块

/com/asiainfo/boss/report报表模块

/com/asiainfo/boss/product产品管理模块

/com/asiainfo/boss/query综合查询模块

/com/asiainfb/boss/ulil公共的工具类，比如时间类、文件类、

资源类等等

b)在具体的模块下面，再按照文件的用途进行目录划分，如下:

/bo存放数据库表操作引擎类

/dao数据访问层

/interfaces数据访问层的接口类

/imp!数据访问层的实现类

/ivalues表信息描述类

/web存放接收和处理web请求的

action类

/service服务层

/interfaces服务的接口类

/impl服务的实现类

2.2html目录规划及说明

Html目录存放工程中所有的html、jsp、js文件，html目录划分原则如下:

a)Himi下建立boss目录，工程中所有的html、jsp、js文件必须放在boss目录下，不

允许在和boss目录平级创建项目相关的目录。

b)Boss目录下的划分原则和src类似，以业务模块为目录划分的依据，如下：

/him/boss/common公共子模块

/css样式表

/image图片

/js系统级公用js

/so营业模块

/soframe营业受理框架

/css模块公用css

模块公用js

/image模块公用图片

/rboss个人业务

/bboss集团业务

.......其它

/ams帐务管理模块

/balance资金管理

/bill帐单管理

/owe欠费管理

其它

/channel渠道管理模块

/channelinfo渠道信息管理

/staff人员信息管理

/reward渠道佣金

其它

/res资源管理模块

/phone号码管理

/simSIM卡管理

/equip终端管理

其它

/market集团客户模块

/custmgr客户经理管理

/salesmgr营销活动管理

其它

/cust客户管理模块

/product产品模块

/report报表模块

/query综合查询模块

2.3config目录规划及说明

Config目录中存放系统配置文件及针对数据库表操作的配置文件，针对数据库表操作

的配置文件由Appframe配置工具ConfigTools自动生成，包括b。文件（数据操作引擎资源

文件）、set文件（DBGRID、DBFORU使用资源文件）、ds文件（下拉框资源文件），config目录

划分原则如下：

a）先针对业务域做目录划分，划分如下:

config/com/asiainfb/boss/common公共子模块，用于存放一些公用

表操作的配置文件。

/CaskTask框架

/tfTf框架

/socketSocket框架

其它

/com/asiainfb/boss/so营业模块

/soframc营业受理框架

/order订单子模块

/instance实例子模块

其它

/com/asiainfb/boss/channel渠道管理模块

/channelintb渠道信息管理

/staff人员信息管理

/reward渠道佣金

.......其它

/com/asiainfb/boss/res资源管理模块

/phone号码管理

ZsimSIM卡管理

/equip终端管理

其它

/com/asiainfo/boss/market集团客户模块

/custmgr客户经理管理

/salesmgr营销活动管理

......其它

/com/asiainfb/boss/cust客户管理模块

/coin/asiainfo/boss/scc权限模块

/com/asiainfb/boss/report报表模块

/coin/asiainfo/boss/product产品管理模块

/com/asiainfo/boss/query综合查询模块

.......系统配置文件

a）在具体的模块下面，再按照文件的用途进行目录划分，如下:

/bo存放数据操作引擎资源文件

/web存放DBGRID.DBFORM、

下拉框使用的资源文件

注意：系统配置文件需要由架构组统一规划，开发人员需要新增系统配置文件时必须向架

构组提交申请，申请通过后才可增加到项目工程中。

2.4lib目录说明

lib目录下包含Appframe.Comframe平台的JAR包以及引入的第三方JAR包。

注意：lib包由技术架构组统一进行管理，新增、变更、删除lib包需经过技术架构组的

审批统一，任何人不得不经审批直接上传或变更lib目录下的文件。

第3章分层开发规范

3.1页面展现层

页面展示层作为与用户的交换界面，在设计开发的过程中需要特别关注用户的体验。

3.1.1CSS样式开发规范

1、平台标准组件样式统一使用htinl文件夹下jsv2公用样式AppFrameCss.jsp,另有

AIFramcDBCSS_css.jsp（路径：/webframe/common/）常用样式搭配；自定义组件样式则统

一使用htinl文件夹下theme主题中相应的4种样式（蓝classicalblue>黑classicalvista绿

softgreen、橙asiainfoorange）,另有main.css（路径：/webframe/common/）常用样式搭配；

两种在前台jsp页面口的统一调用公用方法为：

<%@includefile=,7webframe/common/comnionhead.jsp',%>

开发时务必使用conwonhead.jsp文件中引用的几个标准css及js样式，如有特殊要求

无法满足，需要向平台UI设计人员申请增加，不得在任何单一页面中另建文件夹存储css

及js样式或图片。

2、整体大框架间距由body执行，无需另外设置：

BODY（

font-family:Arial,"宋体";〃英文版本请修改为Arial

margin:Opx;padding:Opx;〃框架的上下限以此为准

background-color:#FFFFFF;〃避免客户端有其他背景颜色扰乱主色调

overflow:auto;〃滚动条设置为自动显示，请勿在单个jsp页面中再设置滚动条样式

）

3、所有文字如无特殊要求，一律系统默认

Tr,Td{

font-family:ArialJ宋体"J/英文版本请修改为Arial

3.1.2JSP开发规范

1、JSP开发时必须把所有对CSS文件的引用放在〈head/＞标签中，以提升页面洎染效

率以及客户体验。

2、JSP开发时对卜JS文件的引用必须放在JSP文件的最后，以提高贝曲的加载速度（对

JS文件的加载在通常情况下是排它的，也就是说在加载JS文件的同时不可以加载其他页面

元素）。

3、JSP文件中实现JS与HTML的分离，尽量把JS代码写在单独的文件中（分离后的JS

文件名与原来的JS文件名相同，后缀不同，如x.jsp对应的JS文件为x.js）,达到分离后

JSP页面变小、加载速度加快，并且能够对单独定义JS文件gzip、mini后进行客户端缓存

处理（JSP页面不能进行客户端缓存）。

4、内部使用的JSP文件命名以下划线开头如（.inner.jsp）o

5、尽量使用分页等减少数据集的数据，避免大数据量对web、app.数据库的压力，

也能提高客户的体验度。

6、不使用session保存业务数据，以免清除不即时和不彻底，导致web服务器内存溢出。

7、URL使用带ContextPath方式的相对地址，能提高部署的灵活性。

8、减少页面的复杂度，不要•次性的把所有的功能点罗列在•个页面上，往往使用的

只是20%的页面功能，能减少网络1O和应用服务器的压力。

9、平台提供的lag,尽量不要使用直接初始化的方式，避免每次打开这个页面都需要调

用服务层，增大了页面响应的时间，增大了web和app服务器的压力。

10、对于DS下拉数据源，所有静态的下拉数据源，全部采用静态方式，直接cache在

web端，减少页面响应时间。

11、对于Set显示，尽量罗列需要显示的列，而不要把所有的列直接放置在tag里通过

隙藏的方式。

12、静态类型文件，比如:图片、js、css、htmRvbs等等，缩小每个文件的大小,减

少第一次访问页面的时候等待大量的时间，减少了web容器并发的响应能力。

13、web端禁止直接调用数据存取层，或在web端直接操作数据库，为后期的维护提

供方便,

14、使用粗粒度的服务调用，减少每次web响应到叩p层次的网络10和对象序列化。

15、对于操作数据量较大的前台操作，通过前台发起作业，由后台调度进行作业执行

的方式进行处理，避免页面响应时间过长。

16、对于Label信息，如Fonn或者Grid中字段的名称，菜单、按钮的名称，采用统一

格式编码，如下：

a）编码共9位，3位字母+6位数字；

b）头两位标识产品或模块代码，包括以下定义：

AP-Appframe

CO-Comframe

SE-Secframe

OM-营业

CS-客服

AM-帐务管理

SF-PBOSS

PD-产品

CA-渠道管理

BA-公共

MK-集团客户

RS-资源

IN-接口

c）第三位字母标识资源的类型，定义为L

d）后6位数字由各产品或模块自定义。

3.1.3JS开发规范

1、公用JS方法必须统一定义在/common/js/common.js中，模块使用的JS文件定义在

相应模块的js/common.js文件中,如营业模块为/so/js/common.js。

2、JS开发时尽可能的避免使用全局变量，以降低代码的耦合度；

3、使用if或者switch的时候，尽量把匹配最多的情况写在最前面。

如对http相应的判断

Switch(status){

Case200:〃因为200是匹配最多的情况，把它写在前面

Case307：

Case404：

break：

Default：

Break：

)

4、对于提示信息，通过平台提供的公共函数进行统一提示，提示信息采用统一格式编

码进行定义，如下：

a)编码共9位，3位字母+6位数字；

b)头两位标识产品或模块代码，包括以下定义：

AP-Appframe

CO-Comframe

SE-Sccframc

OM-营业

CS-客服

AM-帐务管理

SF-PBOSS

PD-产品

CA-渠道管理

BA-公共

MK-集团客户

RS-资源

IN-接口

0第三位字母标识资源的类型，定义为I

d)后6位数字由各产品或模块自定义。

5、JS方法需要进行注释，注释示例如"

/★★

*@Function:函数名

*@Description:该函数的功能描述

★

*©param:参数描述

*Qreturn：返回结果描述

*Aversion:版本

*@author:创建人

*@date:创建时间yyyy-mm-ddhh24:mi:ss

★

*ModificationHistory:

*DateAuthorVersionDescription

*_____________________________________________________________________*

*修改时间修改人版本修改原因

*/

3.1.4Action开发规范

1、Action中禁止使用同步变量或同步方法。

2、Action中的缓存数据由架构组统一规划，开发人员需要在web端缓存数据时需要向

架构组提交申请，以避免患法和做法的疏忽导致web容器的性能明显下降。

3、web端向Action提交数据区分少量数据和大批量数据，少量数据提交采用PostInfo

方法(如缴费模块在缴费申请后向后台传递号码、金额等信息)，大批量数据提交采用

saveRowSet方法(如DBFoim、DBGrid中的数据保存)，示例如下：

/少量数据提交：

varstaff_id="0001”;

varpsw=“1234”;

varoldPsw=“2345”；

varagentNum=；

varmsg=

PostInfo(H<%=request.getContextPath()%>/business/com.asiainfo.boss.sp

ecialarea.business.web.SpBusinessAction?action=ChangeAgentPassword&ST

AFF_ID=,,+staff_id+"iNEW_PWD=,,+psw+"&OLD_PWD=,,+oldPsw+,,&AGENT_NUM="+ag

entNum);

/大批量数据保存

vardcalAction=

"<%=request.getContextPath()%>

/business/com.asiainfo.boss.channeLchannelinfo.web.ActionChannelBusiRegion";

varform=getDBForms()[0];

varlist=newArray();

list.push(form);

varret=

saveRowSet(dealAction+"?action=addChannelBusiRegionn,list,

false,false);

4、Action在接收到web端请求数据后，处理后必须对web端进行响应，响应结果的示

例如下:

CustoinPropenycp=CustomProperty.getins(ance();

cp.set("retVal",Y);

cp.set("retMsg”,“adktjakdtjaktja”)

用retVal表示数据提交有没有成功(Y或者y表示成功，其他表示失败)

用retMsg表示返回的信息，不可以将底层的异常未经处理直接返回给前端。

3.1.5与其它层的交互规则

页面展现层只允许jsp页面通过Aclion类调用业务逻辑层的服务实现对相关数据的操作

Osp->action->sv),禁止jsp页面直接调用业务逻辑层服务(jsp->sv)或数据存取层服务

(jsp->dao),或者直接通过平台提供的数据操作引擎(jsp->engine)或SQL语句(jsp->sql)对数据

资源层数据进行操作。

3.2业务逻辑层

业务逻辑层开发时.，需定义服务接口类和服务实现类，服务接口类和服务实现类必须采

川指定的命名规则进行命名(详参见：4.1类命名规范).

321业务服务对象获取规则

1、业务服务对象的获取可以采用gctScrvicc和gctCrossCcntcrScrvicc两种方式：普通服

务对象获取采用gctScrvicc方法，对于涉及到跨中心数据操作访问的服务对象获取，必须

使用平台提供的getCrossCenterService方法，示例如下：

ICommonSVcommonSV=

(ICommonSV)ServiceFactory.getService(ICommonSV.class);

commonSV.saveOrdSoLogDatalnfo(......);

2、getCrossCenterServ.ee方法在服务内部禁止使用，必须在接口、web段或进程主程序

中调用，使用方式如下：

booleanflag=CrossCenterStoreHelper.isSameCenter。;//判断是否同一个中心

if(nag){

gctScrvicc();

else{

getCrossCenterService();

}

调用getCrossCenterService方法后，必须采用平台提供的BO*Engine.save方法保存数

据，直接使用Jdbc无效，并且在保存的BOBean中需要主动设置RegionkL

getCrossCenterService必须在确认进行跨地市数据访问或操作的时候才可使用，因调用

getCrossCenterService方法后，会在特定的场合引起数据库的rac的gc事件，使用时需谨慎。

RAC,全称realapplicationdusters,译为“实时应用集群”

gc等待事件

3、服务对象获取时，避免使用静态化方式，错误实例如下：

privatestaticfinalIHNSmsSendOpcratorSVhnSmsScndOpcratorSV=

(IHNSmsScndOpcratorSV)ScrviceFactory.gctScn'icc(IHNSmsScndOpcratorSV.class);

3.2.2与其它层的交互规则

1、业务服务对外提供时，只能供其它业务服务(sv->sv),或者页面展现层通过Action

类进行调用(jsp->aclion->sv),严禁直接在jsp页面、数据存取层调用业务逻辑层的相关服务;

2、业务逻辑层开发时，业务服务不能直接与数据资源层进行交互，必须通过数据存取

层①A0层)与数据资源层进行交互(sv->dao),平台会在服务调用层设置事务上下文环境，示

例如下：

publicHashMapcreatePaylnvoice(Stringpaymentld,LongoptSeq,

StringoptCode,longacctld.StringacctNaxe,StringkeyNum,

longpayAmounc,TimestamppayDatezlongbillingCycleld)

throwsException,RemoteException{

稳镂㈱鳍㈱黯•崎谶嵋i簪歌温®

acctld,acctName,keyNuro,payAmount,payDatezbillingCycleld);

3、业务逻辑层禁止直接调用其它模块(package)下的数据存取层(DAO)服务，必须通过

调用其它模块卜的业务服务(SV)实现相关功能；

4、业务逻辑层在服务间相互调用时，禁止粗粒度服务在调用细粒度服务(原子服务)

的同时又进行了数据存取层(DAO层)的服务调用。

3.2.3其它注意事项

1、业务逻辑层JT发时，所有的服务接口类必须抛出javu.iini.RciiiulcExwpliuu,因为在

发布后，sv会发布成EJB服务，根据EJB规范要求，必须抛出RemoteException异常＜

importjava.rmi.RemoteException:

publicinterfacelUserlnfoFSV{

publicIlnsProdValucgetInsProdByBillId(StringBillld)

throwsException,RemoteException;

)

2、自定义的valuebean,需要供服务层使用时,必须要可序列化，例如:

importjava.io.serializable;

publicclassBillingBeanimplementsSerializable{

publicBillingBcan(){}

)

3、业务逻辑层的注程必须在服务接口类进行定义,注释包括：类及方法说明、输入参

数说明、返回结果说明、作者、修改日期等，注释采用统一的标准格式，格式如下：

⑴、接口类注释:

/**

*Copyright:Copyright(c)${year}Asiainfo-Linkage

★

*@ClassName:${file_name}

*0Description:该类的功能描述

金

*@version:vl.0.0

*0author:${user)

*@date:${date}${time)

*

*ModificationHistory:

*DateAuthorVersionDescription

★★

*${date)${user}vl.0.0修改原因

*/

(2)、接口函数注释：

/★★

*0Function:${file_name}

*©Description:该函数的功能描述

*

*@param:参数描述

*^return：返回结果描述

*Gthrows：异常描述

*©version:vl.0.0

*@author:${user)

*@date:${date}${time}

★

*ModificationHistory:

*DateAuthorVersionDescription

**

*${date1${user}vl.0.0修改原因

*/

在进行代码开发前，建议先在开发工具(如Eclipse)中设置注释模板，代码开发时直

接使用开发工具中配置好的注释模板。

3.3数据存取层

数据存取层开发时，需定义数据接口类和数据实现类，数据接口类和数据实现类必须采

用指定的命名规则进行命名(详参见：4.1类命名规范)。

331数据存取对象获取规则

1、数据存取对象的获取采用gctScrvicc方式，获取到数据存取对象进行方法调用，示

例如下：

IAcc(BalanceDAObalanceDAO=(IAcccBalanceDao)ServiceFac(ory.getService

(lAcc(BalanceDAO.cIass);

balanceDAO.saveAcctBalance(...);

2、数据存取对象获取时，避免使用静态化方式，错误实例如下：

privatestaticfinalIHNSmsSendOperatorDAOhnSmsSendOperatorDAO=

(IHNSmsScndOpcratorDAO)ScrviccFactory.gctScrvicc(IHNSmsScndOpcratorDAO.class);

3.3.2与其它层的交互规则

1、数据存取对象只能供业务服务(sv->da。)或者其它数据实现类(dao->da。)进行调用，严

禁在页面展现层直接调用。

2、Appframe平台提供对数据库数据源和事务的统一管理，数据存取层不能直接连接数

据库与数据库进行数据交互，必须通过平台提供的方式迸行，数据存取层对数据库的操作可

以采用以下两种方式：

(1)、数据处理引擎，使用方法如下：

publicvoidsavePageRu1eRe1ace(SoPageRulesetRuleRelateBean[]beans)

throwsException(

SoPageRulesetRuleRelateBeanbean;

if(beans[OJ.getRelaceld()>0)(

bean=SoPageRulesecPuleRelateEngme

.getBean(beans(0].getRelateId());

bean.secEvencCond(beans[0].gecEvencCond());

bean,setEvencName(beans[0].getEventNaire());

bean,setEventObjId(be©ns[0].getEventObjId());

bean.secEventParaon(beans[0].getEventParam());

bean.setEvnetCtojType(beans[0].gecEvnetObjType());

bean.setRuleId(beans[0].getRuleldO);

}else(

bean=beans[0];

bean.setRelaceId(SoPageRulesetRuleRelateEngine.getNewId()

・longValue());

bean.secScate(lI);

)

(2)、获取数据库连接，使用方法如下：

publicvoidqueryPaywentlnroByScarxid(String3cafrid.Stringreaionld/longbilllngCycleld,Stringdate)throwsException<

Connectionconn■nuJLl;

PreparedStatetnentptnc-nuXl;

StringBuf£ersql-newStringBuffer();

try(

sql.append|-insertinto(PIYHINT^PROVISICWALI...”)；

〃进行分我播作处理

ToblcVorsobjToblcVora•newToblcVars();

MW

objTableVars.addC-PAYHENT^ROVISICWJLL*,REGK»I_IDrregionld);

N

objTablevar8.add(-PAYniNT",-REGICN_IDZreglonldj;