门户系统开发规范.docx

门户系统开发规范.docx

《门户系统开发规范.docx》由会员分享，可在线阅读，更多相关《门户系统开发规范.docx（12页珍藏版）》请在冰豆网上搜索。

门户系统开发规范

门户产品开发规范

开发规范

（提交稿）

北京XXXX软件股份有限公司

2009年4月

文档说明

本文档所涉及到的文字、图表等，仅限于北京XXXX软件股份有限公司内部使用，未经双方书面许可，请勿扩散到第三方。

文档属性

属性

内容

客户名称：

XXXX软件股份有限公司

项目名称：

XXXX软件股份有限公司门户产品

文档主题：

门户产品开发规范

文档编号：

文档版本：

0.1

版本日期：

2009-04-27

文档状态：

提交稿

作者：

XXXX

文档变更

版本

修订日期

修订人

描述

1.0

2009-04-27

姜涛

创建文档结构

文档送呈

单位

姓名

目的

XXXX

审阅

XXXX

参阅

1概述

本文提供一整套编写高效可靠的Java代码的标准、约定和指南。

它们以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强。

而且，通过遵循这些程序设计标准，你作为一个Java软件开发者的生产效率会有显著提高。

经验证明，若从一开始就花时间编写高质量的代码，则在软件开发阶段，对代码的修改要容易很多。

最后，遵循一套通用的程序设计标准将带来更大的一致性，使软件开发团队的效率明显提高。

1.1最根本原则

❒运用常识

当找不到任何规则或指导方针，当规则明显不能适用，当所有的方法都失效的时侯：

运用常识并核实这些基本原则。

这条规则比其它所有规则都重要。

常识是必不可少的。

2程序设计标准

Java的程序设计标准很重要，原因在于它将提高开发团队各成员的代码的一致性。

一致性的提高会使代码更易理解，这意味着它更易开发和维护。

从而降低了应用程序的总开发成本。

你必须牢记的是：

你的Java代码在你已离开并开始另一个项目之后，会保留相当长的一段时间。

因此开发过程中一个很重要的目标就是要确保在开发成员或开发团队之间的工作可以顺利交接，不必花很大的力气便能理解已编写的代码，以便继续维护和改进以前的工作。

如果代码难以理解，很有可能被废弃和重写。

2.1命名约定

我们将在整个标准中讨论命名约定，以下是几个基本点：

❒使用可以准确说明变量/字段/类的完整的英文描述符

例如，采用类似firstName，grandTotal或CorporateCustomer这样的名字。

虽然象x1，y1或fn这样的名字很简短，输入起来容易，但是我们难以知道它们代表什么、结果是什么含义，因而使代码难以理解、维护和改进。

❒采用该领域的术语

如果用户称他们的“客户”（clients）为“顾客”（customers），那么就采用术语Customer来命名这个类，而不用Client。

许多程序开发者会犯的一个错误是，不去使用工业或领域里已经存在着很完美的术语时，却生造出一些普通词汇。

❒采用大小写混合，提高名字的可读性

一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。

❒尽量少用缩写，但如果一定要使用，就要谨慎地使用

这意味着应该保留一个标准缩写的列表，明智地从中选取，并且在使用时保持一致。

例如，想对单词“number”采用缩写，那么可从nbr，no或者num中选取一个，说明一下采用了哪一个（具体是哪个倒无所谓），并且只使用这一种形式。

❒避免使用长名字（不超过15个字母）

虽然PhysicalOrVirtualProductOrService看起来似乎是个不错的类名，但是这个名字太长了，应该考虑重新给它起个短一点的名字，比如象Offering。

❒避免使用相似或者仅在大小写上有区别的名字

例如，不应同时使用变量名persistentObject和persistentObjects及anSqlDatabase和anSQLDatabase这样的名称

❒避免使用下划线作为名字的首末字母

以下划线为首末字母的名字通常为系统保留，除预处理定义之外，一般不用作用户命名。

更重要的是，下划线经常造成麻烦而且难输入，所以尽量避免使用。

2.2注释约定

本文还会对注释进行约定，以下是几个基本点：

❒注释应该增加代码的清晰度

代码注释的目的是要使代码更易于被同时参与程序设计的开发人员以及其他后继开发人员理解。

❒如果你的程序不值得注释，那么它也很可能也不值得运行。

❒保持注释的简洁

最好的注释应该是简单明了的注释。

注释不必洋洋洒洒，只需提供足够的信息，使别人能够理解你的代码。

❒先写注释，后写代码

写代码注释的最好方法是在写代码之前就写注释。

这使你在写代码之前可以想想代码的功能和运行。

而且这样确保不会遗漏注释。

另一种方法是边写代码边写注释。

因为注释可以使代码更易理解，所以在程序开发的过程中，也可以利用这一点。

如果打算花些时间写注释，那么至少你应从这个过程中获得些什么。

❒注释信息不仅要包括代码的功能，还应给出原因

例如，下面例1中的代码显示金额在$1,000以上（包括$1,000）的定单可给予5%的折扣。

为什么要这样做呢？

难道有一个商业法则规定大额定单可以得到折扣吗？

这种给大额定单的特殊是有时限的呢，还是一直都这样？

最初的程序设计者是否只是由于慷慨大度才这样做呢？

除非它们在某个地方（或者是在源代码本身，或者是在一个外部文档里）被注释出来，否则你不可能知道这些。

2.3快速浏览JavaDoc

Sun公司的JavaDevelopmentKit（JDK）中有一个名为javadoc的程序。

它可以处理Java的源代码文件，并且为Java程序产生HTML文件形式的外部注释文档。

Javadoc支持一定数目的标记，标识注释文档中各段起始位置的保留字。

详情请参考JDKjavadoc文档。

标记

用于

目的

@authorname

类、接口

说明特定某一段程序代码的作者。

每一个作者各有一个标记。

@deprecated

类、成员函数。

说明该类的应用程序编程接口（API）已被废弃，因此应不再使用。

@exceptionnamedescription

成员函数

说明由成员函数发出的异常。

一个异常采用一个标记，并要给出异常的完整类名。

@paramnamedescription

成员函数

用来说明传递给一个成员函数的参数，其中包括参数的类型/类和用法。

每个参数各有一个标记。

@returndescription

成员函数

若成员函数有返回值，对该返回值进行说明。

应说明返回值的类型/类和可能的用途。

@since

类、成员函数

说明自从有JDK1.1以来，该项已存在了多长时间。

@seeClassName

类、接口、成员函数、字段

在文档中生成指向特定类的超文本链接。

可以并且应该采用完全合法的类名。

@seeClassName#memberfunctionName

类、接口、成员函数、字段

在文档中生成指向特定成员函数的超文本链接。

可以并且应该采用完全合法的类名。

@versiontext

类、接口

说明特定一段代码的版本信息。

你注释代码的方式很大地影响着你的工作效率以及所有维护改进代码的后继开发者的工作效率。

在软件开发过程中及早注释代码，会促使你在开始撰写代码之前仔细考虑这些代码，从而带来更高的工作效率。

而且，当你重新阅读数天前或者数星期前所写的代码时，你可以很容易地判断出当时你是怎么想的，因为这一切都有记录。

3门户系统开发规范

3.1整体包结构说明

目前UIP的大包结构如下：

附图1.包结构

主要分5个包：

1.askbar：

问吧，说明：

存放了所有关于问吧的类包括持久层，业务层，控制层和相应的模型。

2.common：

UIP平台的所有底层类和公共类。

3.forum：

论坛。

4.framework：

UIP平台基本功能。

说明：

存放了所有关于UIP基本功能的类包括持久层，业务层，控制层和相应的模型。

5.im：

即时消息。

以上是UIP整体功能包结构的说明。

注意：

UIP是可扩展的平台，如果在新的功能增加将会与这5个包并其来命名。

子包结构说明：

公共包说明：

附图2.公共包结构

以上是存放的是UIP整个平台的核心类，基本不做任何改动。

主要分缓存，控制层基类，异常基类，过滤器，ldap，模型基类，wiki和常使用的类。

各个模块功能包基本都一样就以问吧为例：

附图3.各个模块包结构

所有功能的大模块都会按照这种层次结构来做，业务层，控制层，异常，模型，持久层，常用类。

这里的常用类和公共里的不一样如果各大模块在公共类里没有找到，可以在自己的模块中自行扩展。

达到遵循“开—闭”原则。

3.1.1常用包结构

◆cache包

说明：

所有的缓存结构。

例如UIP所使用的OSCACHE。

◆config包

说明：

该包存放所有关于配置信息的类

◆util包

说明：

存放基本常用的类。

例如文件类，字符串类等。

◆web包

说明：

存放在控制层下面的一些用于前端公用的类。

例如登陆，登出，角色切换等。

◆constant包

说明:

存放常量类，比如全局类。

◆common包

说明:

存放所有公共的基本类，例如：

控制层的公共类，持久层的公共类。

◆core包

说明:

存放关于平台里的核心类。

例如平台的底层类。

3.1.2功能包结构

按照各个层次结构包分完：

功能包基本分为2个包：

1.各个层次的接口包。

2.对于接口的实现包。

3.2命名规则

3.2.1共用类

◆公共用类要求以“功能英文名称（首字母大写）”+Util命名。

例如：

日期的英文名为date，按照规则要求，命名为：

DateUtil；

◆

3.2.2业务层

◆业务层接口要求以I+“模块英文名称（首字母大写）”+Manager命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

INavigatorManager；

◆接口的实现类要求以“模块英文名称（首字母大写）”+ManagerImpl命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

NavigatorManagerImpl；

3.2.3展现层

◆基类要求以“模块英文名称（首字母大写）”+ActionBase命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

NavigatorActionBase；

◆查询模块列表类要求以List+“模块英文名称（首字母大写）”+s+Action命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

ListNavigatorsAction；

◆创建模块对象类要求以Create+“模块英文名称（首字母大写）”+Action命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

CreateNavigatorAction；

◆修改模块对象类要求以Modify+“模块英文名称（首字母大写）”+Action命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

ModifyNavigatorAction；

◆删除模块对象类要求以Remove+“模块英文名称（首字母大写）”+Action命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

RemoveNavigatorAction；

◆对模块对象的操作类要求以“模块英文名称（首字母大写）”+Operator+Action命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

NavigatorOperatorAction。

3.2.4模型层

◆模型层存放的是实体类，要求以“模块英文名称（首字母大写）”命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

Navigator；

◆根据注解配置实体类与Hibernate之间的关系，表名以tb_+“模块英文名称（首字母小写）”命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

tb_navigator；

◆属性字段根据具体含义用英文名称（首字母小写）命名，多词组要求合并，并且从第二个词开始首字母大写。

例如：

应用系统的URL地址的英文名为applicationURLr，按照规则要求，命名为：

applicationURL。

3.2.5持久层

◆dao接口要求以I+“模块英文名称（首字母大写）”+DAO命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

INavigatorDAO；

◆接口的实现类要求以“模块英文名称（首字母大写）”+DAOHibernateImpl命名。

例如：

导航菜单的英文名为navigator，按照规则要求，命名为：

NavigatorDAOHibernateImpl；

3.2.6XML配置

◆actionContext.xml用于配置需要向spring注入管理的action层bean的配置文件。

命名格式我们需要注意：

比如用户模块会先按照门户产品开发规范新建一个UserActionBase，id命名为userBase,修改用户的就会创建类为ModifyUserAction，id命名为modifyUser，并相应设置其parent属性为userBase。

然后这些子类就必须继承base类，但却可以减少配置相关引用springbean的繁琐配置。

◆daoContext.xml用于配置需要向spring注入管理的DAO层和DAO层client端bean的配置文件。

命名规范与定义java变量同样的规范。

但却需要注意spring事务管理的定义规则，详细说明在事务命名约束部分。

◆managerContext.xml用于配置需要向spring注入管理的Manager层和Manager层client端bean的配置文件。

命名规范与定义java变量同样的规范。

◆utilContext.xml用于配置需要向spring注入管理的portal产品在服务运行时工具bean的配置文件。

命名规范与定义java变量同样的规范。

◆applicationContext.xml用于配置spring常用设置，以及需要的元数据的配置文件。

当我们新建一个model的时候我们需要在这个文件配置其相应元数据bean。

◆ehcache.xml为门户产品配置缓存相应参数的配置文件。

◆forum.xml门户产品论坛系统管理配置参数的配置文件。

◆forumcore.xml门户产品论坛系统系统配置参数的配置文件。

◆ISMG-Config门户产片短信组件配置文件。

◆Jamwiki-configuration.xml门户产品wiki系统数据处理、内容分析、全文检索、命名空间等参数配置文件。

◆Rights.xml门户产品权限管理配置文件。

涉及门户产品权限管理的文件都在此文件进行相关配置，首先我们是功能模块我们要建一个相关module，然后配置相关模块的功能fuction，然后配置相对于每个功能实现的方法method。

配置过程中我们要考虑权限的连贯性，默认入口。

拿用户管理举例说明：

Module

✧需要新建一个用户管理模块managerUserModule，设置其父节点是后台管理树的根节点，也就是设置ParentModeulId为#号，然后它的子节点可以设置相应的父节点为managerUserModule,。

✧AtionURL指用来访问这个相关模块的命名空间。

✧查看类型viewType是指要说明此模块节点是要在前台显示还是后台管理的。

✧ImgURL指当我们把这些模块展示在相关树上显示的图标链接。

Fuction

✧然后确定包含的功能比如增加用户：

addUser。

Method

✧增加用户的入口方法：

saveAddUser。

✧ActionURL指这个入口方法在当前模块命名空间下的访问地址createUser.加一个点是用来判断最后的后缀，如果是点结尾程序会自动补齐门户产品访问链接的后缀，如果是其他后缀直接访问这个链接。

✧IsDefault是否默认入口：

一个模块功能只能有一个方法作为默认入口。

◆Struts.xml门户架构当中struts组件相关配置，开发相关模块的时候注意相关规范，试举例：

✧Strust.xml文件包含所有模块struts详细配置。

✧Package：

我们可以在模块中定义包以避免命名空间重复，命名规则：

struts-xxx（模块名层）。

✧Namespace相关模块的命名空间。

这里涉及几个需要注意的地方：

这个链接会和权限关联由过滤器判断命名空间管理权限功能。

凡是命名空间在/public/common这个路径下的系统定义为前台没有权限管理的访问链接，凡是命名空间在/manage/common这个路径下的系统定义为后台没有权限管理的访问链接。

在这个两个路径下面访问的地址，过滤器不作权限判断。

其它访问地址会根据rights中配置定义的权限进行过滤。

✧Extends:

在struts配置中需要考虑各种拦截器和错误处理跳转，配置在struts-interceptor.xml这个文件。

Action

✧Name：

定义action被访问的id命名规范与定义java变量同样的规范。

✧Class:

就是我们在actionContext.xml文件已经配置了注入springbean的id。

✧Result：

struts处理跳转，两种跳转方式dispatcher转向和redrict重定向。

✧interceptor-ref:

所使用的拦截器。

在struts-interceptor.xml这个文件有相关注释。

systemConfig.xml:

定义平台描述参数、外围NMS等系统、Mail服务器、ldap、IM、全文检索等相关配置，相关参数的配置含义查看该文件注解。

◆初始化数据right.xml写法

appLog

/manage/system/log/applog

systemManage,#

应用日志

backType

/images/common/module/sys.gif

viewAppLogInfo

viewAppLogInfo

appLogOperator!

viewAppLog.

0

searchAppLogs

searchAppLogs

searchAppLogs.

0

listAppLogs

listAppLogs

listAppLogs.

1

3.2.7资源文件

◆Commons-logging.properties公共日志配置文件。

◆Init.properties门户产品数据连接配置文件。

◆Interwiki.properties门户产品维客系统互联网资源配置文件。

◆Log4j.properties门户产品日志输出保存等相关设置的配置文件。

◆Oscache门户产品缓存组件系统配置文件。

◆Quartz.properties门户产品调度组件相关设置的配置文件。

◆Struts.properties门户产品struts组件相关系统配置文件（国际化、上传等）。

◆Jamwiki.properties门户产品维客系统使用的参数配置文件（ldap、db、pattern、rss）。

国际化资源文件的读取不再从web.xml加载到上下文，而是利用jstl标签绑定。

实例

bundlebasename="ApplictionResource">,通过不同的local读取不同的语言相关资源。

国际化资源文件中key的定义规则：

portal.子系统.模块名称.功能名称.key描述，但此全部小写，多个单词之间用下划线分割。

试举例:

门户产品问吧系统分类模块编辑条目分类的key定义为：

portal.askbar.category_group.edit_category_group=编辑条目分类。

◆message开头的资源文件包含门户产品相关的国际化资源内容。

◆exceptionMessage开头的资源文件包含门户产品异常处理描述的国际化资源内容。

◆mvncore_java_i18n开头的资源文件包含门户产品论坛系统相关核心的国际化资源内容。

◆mvnforum_i18n开头的资源文件包含门户产品论坛系统相关的国际化资源内容。

◆wiki_message开头的资源文件包含门户产品维客系统相关的国际化资源内容。

3.2.8事务命名约束

◆在门户产品中，所有关于事务处理的，必须遵循以下命名规则：

保存/增加：

以save开头。

修改：

以update开头。

删除：

以delete开头。

读取：

以get开头。

查询：

以search开头。

3.2.9JS命名约束（待完善）

◆常用工具类

◆

附图目录