软件框架以及编码规范说明文档

时间:2022-06-30 05:41:55

1 文档简介

   此文档主要是描述软件架构和编码的技术规范。详细地说明所确定的整个框架所涉及到的技术的外部行为,以及表现形式。另外,涉及到具体编写代码时,类、方法的命名规范。

 

2 软件框架

2.1 框架介绍

本框架主要是基于Hibernate 3.0 + Struts 1.2.x + Servlet 2.4 + Jsp 2.0 + JSTL 1.2 ( Spring 1.2)构建而成。推荐使用eclipse 3.x作为软件开发工具,tomcat 5.x作为web容器。对于软件的测试,推荐使用eclipse集成的JUnit作为测试工具。项目的版本控制器,使用的是VSS,不要整个项目check out,而应该check out你自己修改的部分,修改完毕后,记得及时check in,尤其是属于公共文件,例如Struts的配置文件。

 

2.2 框架目录结构

   2.2.1 源文件目录

         框架的java类文件目录是:src。Package目录:cn.rhui.framework.*, 建议模块包的包名不能太长,尽量使用英文单词,常用词汇。下面列出的包的名称当中,action包、domain包、dao包,service包属于某个模块的包(一个模块可能包括很多功能,功能相似的组成一个模块)。Filter包、Listener包,其它Servlet类属于整个项目,而不应该在某个模块中出现。

      action包:struts的action以及actionForm.

      Domain包:hibernate映射文件以及普通java bean类。

      Dao包:包括接口以及接口实现。

      Service包:service层 ,包括接口以及接口实现。另外,在该目录下,可以放一些辅助类,也就是一些普通的java类。这些类仅限于该模块使用。

      Filter包:过滤器。

      Listener包:监听器。

      其它的servlet类。

        

   2.2.2 配置文件目录

         框架的配置文件目录是:config。该目录主要存放的是资源配置文件,log4j文件以及其它不是框架必须的配置文件。

   2.2.3 测试类目录

         框架的测试类目录是:test。Package目录是:test.cn.rhui.framework.*, 测试类也是分模块的,便于管理。

   2.2.4 web发布目录

         框架的web目录是:web。Web目录包含了jsp文件,classes文件,lib类库文件以及框架所必须的配置文件。

2.3 开源框架

    2.3.1 Struts

          框架的web层我们采用的是Struts 1.2.x.在主流的MVC实现框架中,Struts不是最好的,但是由于其版本比较稳定,使用人群广泛,大家都有Struts开发经历。

      据业务的需要,应该建立不同的基类(baseClass),分别继承不同的Action.

      我们还需要在服务器端,对用户提交的表单进行数据验证,建议使用validator框架,它已经集成在struts框架中。

      struts的配置文件应该分模块,同一模块下的配置放在同一个配置文件,而struts-config.xml文件主要配置属于整个框架的action mapping。

      Struts 的配置文件我们使用Struts console统一管理。

      2.3.2 hibernate

           框架的业务层我们采用的是hibernate 3.0。hibernate最新的eclipse插件hibernate_tools可以根据数据库表的结构,生成映射文件和普通的java bean文件。我们只需要对配置文件稍加修改就可以使用。

      2.3.3 spring

           主要应用spring的事务管理和容器管理。目前spring+hibernate结合是比较不错的选择,因为spring对事务管理和session管理非常出色,而且spring的其它功能我们可以不使用,而不会对整个项目有影响。

 

3 注释规范

  eclipse控制台,选择“窗口首选项java--代码样式代码模板”,编辑类的注释。

  3.1 类的注释

 3.2 方法注释

        

4 字符集

   java中,由于其编码是utf-8,因此建议在整个系统中,在数据交换过程中采用utf-8编码。目前已经测试了oracle,mysql,sql server,可以很好的保存中文,繁体,以及一些生僻字。页面依然使用GBK。

  

5 编码规范

  5.1 Struts命名规范

       5.1.1 Action命名

             Action的命名:XxxAction与XxxFormAction.例如:UserAction 与 UserFormAction.另外,我们可能会用到dispatchAction.其mapping 中的parameter 设置为:method,便于理解。

      XxxAction:此Action中的方法,主要是不包括保存数据的其它方法。

Add:此方法主要是用来显示新增表单页面。

Edit:此方法主要是用来显示修改表单页面。

List:此方法用来显示列表页面。

View:此方法用来显示查看页面。

Remove:此方法用来执行删除操作。

      XxxFormAction:此Action是用来把表单数据保存或者更新到数据库中,所以

在服务器端需要验证。一般来说这个Action中只含有一个方法:save。同时处理新增和更新数据操作。

          5.1.2 Jsp命名

                这里主要是针对jsp页面命名。Jsp页面我们是分模块进行管理,不同模块的jsp页面放在不同的文件夹里,考虑到jsp页面的安全性,建议把jsp根目录放到WEB-INF下。Jsp页面的命名应该是与Action中的方法命名对应,方便管理。

      Action中的add,edit方法对应的页面命名为:xxxForm.jsp,例如:userForm.jsp.

      Action中的list方法对应的页面命名为:xxxList.jsp.例如:userList.jsp.

      Action中的view方法对应的页面命名为:xxxView.jsp,例如:userView.jsp.

     5.2 DAO命名规范

         5.2.1 接口命名

             接口命名:XxxDao.例如:UserDao.

接口对应的方法命名可以对照Action命名规则。

             saveXxx:此方法用来新增和修改记录,例如:saveUser(User user);

             removeXxx:此方法用来删除某条或者多条记录,例如removeUserById(int id);

             findXxx:此方法用来显示某条记录,例如:findUserById(int id);

             selectXxx:此方法用来列表符合条件的列表,例如:selectUserByDepartID(int departID);

         5.2.2 接口实现命名

             接口实现命名:XxxDaoImpl.例如:UserDaoImpl.

     5.3 Service命名规范

        5.3.1 接口命名

            一个模块,对应一个service类。例如:User模块,其service就可能是:UserService。其方法命名与DAO命名一样。

      5.3.2 接口实现命名

           接口实现命名:XxxServiceImpl.例如:UserServiceImpl.