※江西中烟工业有限责任公司广丰卷烟厂数据采集系统※

项目开发规范文档v1.3_2015.2.3 最后修改:leejean

最后修改内容请使用class='red'高亮显示


☆项目架构
  1. 本项目spring-webmvc4.0.6+spring4.0.6+Hibernate4.3.6.Final
    	生产管理软件采用(PMS) jQuery-1.11.0+easyui1.3.6(最新版)    访问http://127.0.0.1:8080/tzsc/pms
    	车间协同终端采用(WCT) html5+css3   访问http://127.0.0.1:8080/tzsc/wct
    	监控系统(ISP) matrix+html5+css3   访问http://127.0.0.1:8080/tzsc/isp
    	前端引入其他开源框架,使软件界面增彩
    	bootstrap-2.3.1   UI样式库
    	Highcharts-3.0.1   报表插件
    	kindeditor-4.1.7   文本编辑插件
    	My97DatePicker4.8b3   日期组件
    	myAlert2.1   WCT定制风格弹窗插件包
    	myKeyboard2.1   WCT虚拟键盘插件
    	edojs   js小框架,用于工厂日历
    	WCT 左侧菜单图标class 参考http://v2.bootcss.com/base-css.html#icons
    	ManhuaDate WCT日期采用本插件
    	
  2. 服务器采用tomcat7.0.54(暂定)
  3. 项目编码:UTF-8
  4. 整个项目主要包含jsp,controller,service,dao层;
    	jsp:数据展现层,提供给用户的界面
    	controller:只处理数据转换,或者页面跳转判断,不处理任何业务逻辑 继承controller基类
    	servcie:面向画面的业务处理
    	dao:数据库的存取,本项目对dao已做封装,无需个各个模块重写dao层
    	
☆项目结构说明
  1. src中的package定义一般格式如下:com.公司名.项目名.一级模块名.二级模块名(依次往下).层名:
  2. jsp中的目录结构:项目名.一级模块名.二级模块名(依次往下)
  3. 目录格式:
    |-src/main/java源码
      |-com
        |-sql  项目开发过程中测试sql代码,开发成员根据姓名简历子包 如com.sql.leejean,com.sql.tom 无需提交svn资源库
        |-test junit测试代码 ,开发成员根据姓名简历子包 如com.test.leejean,com.test.tom 无需提交svn资源库
        |-shlanbao.tzsc 项目名称
          |-base  项目基类包
            |-controller  controller基类
            |-dao     Dao基类
            |-filter  过滤器
            |-interceptor  拦截器
            |-listener  监听
            |-mapping Hibernate映射文件*.java,*.cfg.xml(内部文件通常情况下不做修改)
            |-model   自定义Model类
            |-service Service基类
          |-data   数据
            |-qm         质检仪数据
            |-runtime    生产实时数据
            |-webservice 与第三方系统接口数据
              |-server          接收消息
              |-client          发送消息
                |-proxyclass  存放由wsdl生成的文件
          |-init 存放系统启动实例化操作servlet
          |-plugin 公共插件包 如wct,pms常用的combobox数据源
          |-isp 实时监控模块(另起一个子系统)
          |-pms    生产管理软件
            |-sys      系统管理
              |-user
                |-beans 存放业务bean xxBean.java
                |-controller 存放controller类和配置文件  
                |-servie
                  |-impl  存放业务实现类
          |-wct    车间协同终端
            |-doc      文档管理
            |-isp      监控
            |-prod     生产管理
            |-qm       质量
            |-sys      系统管理
          |-utils  工具包
            |-extents  拓展   自定义标签等
            |-params  系统参数
            |-tools    常用类工具包   StringUtil.java,WebContextUtil.java,MD5Util.java,BeanConvertor.java,DateUtil.java等
    |-src/main/resource配置文件最新增加spring-task.xml
    |-src/test/java 测试
    |-build 项目打包成war后的存放目录
    |-项目文档 
    |-outersys   存放第三方系统wsdl生成的代理类文件 (打jar包)
    |-src/main
      |-webapp 项目前端文件 jsp,js,css...
        |-css   公共样式
        |-error   异常跳转静态页面
        |-img   公共图片
        |-jslib   外部库
        |-initlib  实例化库页面    
        |-pms     生产管理端
          |-sys   
            |-user  以用户模块为例
              |-css 用户模块涉及样式
              |-img 用户模块涉及图片
              |-js  用户模块涉及js
              user.jsp 功能界面
              ...        
            |-role
            |-...
            |-...
          |-qm
          |-doc
          |-...
        |-wct     车间协同端
          |-sys
          |-qm
          |-doc
          |-...
        |-isp     监控系统
      |-META-INF  证书,和校验数据
      |-xmlcfg  机台配置文件
      |-WEB-INF   WEB应用的安全目录
    |-pom.xml 马文配置文件
    
☆编码规范

  java编码规范
  1. 变量规范:本项目java编程采用驼峰命名法(Camel-Case)
  2. 变量规范:变量遵守定义最小域范围,即在括号内定义的就不要在括号外定义;
  3. 变量规范:变量命名应有意义,切忌aaa,bbb,ccc类似命名
  4. 变量规范:定义且未使用的变量(黄色警告线),应该移除
  5. 变量规范:变量定义如果不初始化,比如赋值null,如下
    		protected HttpServletRequest servletRequest;  
    		应该写成
    		protected HttpServletRequest servletRequest=null;
    	
  6. 变量规范:变量定义:controller层和Service层使用spring注入时,无需书写getter方法,命名切忌service,dao
    		private UserServiceI userService;  
    		应该写成
    		private UserServiceImpl userServiceImpl;
    	
    		private BaseDao<SysUser> dao;
    		应该写成
    		private BaseDao<SysUser> userDao;
    	
  7. 静态变量:全部大写,用'_'分隔 如:
            private final static Double MAX_DOUBLE_VALUE = 999999999999.99;
            private final static Double MIN_DOUBLE_VALUE = -999999999999.99;
    	
  8. 方法命名规范:
    		save*    C   建议格式saveXxx
    		query*   R   建议格式queryAll,queryXxxByXxx
    		edit*    U   建议格式editXxx,editXxxByXxx
    		delete*  D   建议格式deleteXxx,deleteXxxByXxx
    	
  9. 包package:一律小写,不能出现'_'等特殊字符
  10. 子模块包结构规范:以sys大模块下的user子模块为例
    		|-sys
    		  |-user
    		    |-controller  控制层
    		    |-beans   Vo层
    		    |-service 业务层
    		      |-impl   实现类
    	
    通常情况下不得违背这一结构
  11. 接口和实现类:
    		接口一律:  XxxYxxI.java
    		实现类一律:XxxYxxImpl.java
    	
  12. 日志规范:日志打印全部使用logger.info,logger.error,尽可能不使用System.out.println 测试完成务必移除调试形象
  13. 日志规范:通常情况下,采用A file one day,且日志保存30天后自动清除
  14. 日志规范:通常情况下,在if和else的入口需要打印日志,或者是代码比较长需要打印日志
  15. 日志规范:日志编写内容是以方便调试运维为目的,因此需要写清楚操作信息(主谓宾)和必要的业务信息(通常是带ID之类的信息),如下:
    	logger.info("用户某某,执行了某某操作,ID:10001");
    	
  16. 日志规范:如重要日志,应定义单独实例记录(如某个类里面业务日志单独记录在某一个日志文件中)
  17. mapping规范:由实体映射工具生成的model都必须是有abstract model的,该Model无需作修改
  18. 代码标签:template统一,记录代码作者,时间,描述等,以便生成格式规范的javadoc,<li>标签使文本列表显示
    		类:
    			/**
    			 * Bean转换器
    			 * <li>@author leejean
    			 * <li>@create 2014-6-24 下午11:48:40
    			 * <li>本转换器支持自定义日期转换 
    			 * <li>使用方法直接在成员变量加自定义注解即可
    			 * <li>例如:
    			 * <li>@DateFmtAnnotation(fmtPattern="yyyy-MM-dd HH:mm:ss")
    			 * <li>private String modifyDatetime;
    			 * <li>后期可拓展数字精度
    			 * <li>@NumberFmtAnnotation(scale=1)
    			 * <li>private Double num;
    			 */
    			 public class BeanConvertor {...}
    		方法:
    		   	/**
    			 * 将scr中的同名属性的值复制到desc的同名属性中
    			 * @author leejean
    			 * @create 2014-6-24 下午10:38:40
    			 * @param source 源
    			 * @param target 目标
    			 */
    			public static void copyProperties(Object source, Object target) throws Exception{
    				if(source == null) return;		
    				handle(source, target);		
    			}
    	
  Jsp编码规范
  1. js变量和方法命名采用驼峰命名法
  2. class,id等采用'版块-子版块'命名方式 如 'easyui-linkbutton','easyui-menu' (非强制,目的只为命名有意义,增强可读性)
  3. 定义且未使用的变量或方法应删除或注释
  4. 确保jsp页面标签结构正确即在IDE中不出现黄色警告
  5. 变量声明后务必接';' 部分浏览器无法解析此类语法
  6. jsp网页页面一律采用如下template
    		<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
    		<!DOCTYPE html>
    		<html>
    		<head>		
    		<title>用户管理</title>
    		<meta name="author" content="leejean">
    		<body>
    			...
    		</body>
    		</html>
    		title便签中务必要写明页面描述
    	
  7. jsp命名:一律使用Camel-Case命名法,如userEditPwd.jsp
  8. js命名:一律使用Camel-Case命名法,如果jsp和js是one to one,则js与jsp命名一致,且放置jsp页面于同级js目录中 如:
    			|-user
    			  |-js
    			    -login.js
    			  |-css
    			  |-img
    			  login.jsp
    		
  9. jsmin命名:js压缩后,在原名称后接min 如:
    		压缩前
    		login.js
    		压缩后
    		login.min.js
    	
  10. jasper报表文件:如有模块有报表导出,jasper文件存放于与css,js,img同级目录的jasper文件夹中,Camel-Case命名
  11. css命名:同js命名规则,放置jsp页面于同级css目录中
  12. image命名:不得使用中文命名(某种情况下将无法访问)
  13. 符号使用:系统提示信息推荐使用英文符号(括号,逗号,分号等) 如推荐使用'(',')' 不使用'(',')'
  14. 使用Easyui相关事宜:
    		组件变量声明与赋值:
    		var dataGrid=null;//声明全局变量接收组件对象,方便其他地方调用
    		$(function() {
    		   dataGrid = $('#dataGrid').datagrid({
    			properties...
    		   });
    		});
    	
    		表单内容序列化:
    		$.getFormData($('#searchForm'));
    	
    		日期组件初始化:
    		$.initDateBox($('#dateBox'));
    	
    		字符串分割
    		$.stringToList("1,2,4,5");
    		return "[1,2,3,4]"
    	
    		combobox数据源封装
    		原则:编写service时,添加一个空白格,index=0位置    id为0 text为' '
    		$.initShiftCombobox($("#comboBox"));
    	
    		String格式化功能
    		$.formatString($.formatString('字符串{0}字符串{1}字符串','第一个变量','第二个变量');
    		return "字符串第一个变量字符串第二个变量字符串"
    	
    		去字符串空格
    		str.trim();
    		str.ltrim();
    		str.rtrim();
    	
    		清除查询条件:
    		$.clearParams($("#form"));
    	
  代码封装部分
  1. 采用通用com.tz.base.dao.BaseDao<T> service层注入baseDao,调用内部封装方法,即可实现所有业务的CRUD操作
  2. service类通过继承com.tz.base.service.BaseService; 获取logger等父类定义成员变量等
  3. 拓展com.tz.utils.extents.DayRollingFileAppender 实现日志自动清除功能
  4. 拓展自定义注解@DateFmtAnnotation
    		@Retention(RetentionPolicy.RUNTIME)
    		/**
    		 * 日期格式化注解
    		 * <li>@author leejean
    		 * <li>@create 2014-6-24 下午11:38:40
    		 */
    		public @interface DateFmtAnnotation {
    			/**
    			 * 格式化模板
    			 * yyyy-MM-dd HH:mm:ss
    			 * <br>更多模板参考Data类相关API
    			 * @author leejean
    			 * @create 2014-7-3下午08:04:05
    			 * @return
    			 */
    			public String fmtPattern();
    		}
    
  5. 拓展自定义注解@NumberFmtAnnotation
    		@Retention(RetentionPolicy.RUNTIME)
    		/**
    		 * 数字精度注解
    		 * <li>@author leejean
    		 * <li>@create 2014-6-24 下午11:48:40
    		 */
    		public @interface NumberFmtAnnotation {
    			/**
    			 * 小数位数
    			 * <br>"0","1","2"
    			 * @author leejean
    			 * @create 2014-7-3 下午09:05:25
    			 * @return
    			 */
    			public int scale();
    		}
    
  6. 将常用类分类封装
    		BeanConvertor.java  vo-po转换器
    			使用此转换器配合自定义注解
    			@NumberFmtAnnotation(scale=2)
    			@DateFmtAnnotation(fmtPattern="yyyy-MM-dd")
    			可实现同名属性不同类型自由转换
    			目前支持Date<->String,以及高精度Double转自定义小数位Double类型		
    		ConfigUtil.java 配置文件类
    		DateUtil.java   日期处理类
    		FileOptionsUtil.java 文件操作类
    		MathUtil.java 数字处理类
    		MD5Util.java  MD5加密类
    		StringUtil.java 字符串处理类
    		WebContextUtil.java web上下文类
    	
  7. controller层分页重新封装
    		传统
    		super.outPrintBean(userService.querySysUser(userBean, this.getPage(), this.getRows(), this.getSort(), this.getOrder()));
    		现在
    		super.outPrintBean(userService.querySysUser(userBean, super.getPageParams()));
    	
☆用户界面基本操作及命名规范

为确保整个项目风格统一,命名一致,请项目开发成员遵循以下约定
  1. 查询 iconCls:'icon-standard-zoom'
  2. 清空条件 iconCls:'icon-standard-table-refresh'
  3. 新增xx
  4. 删除xx
  5. 批量删除xx
  1. toolbar一律使用/css/toptoolbar.css 以便统一管理
  2. form 一律使用 /css/formtab.css定义的样式以便统一管理
◇本文档涉及规范为项目开发过程提供指导作用,具体实施需要结合项目实际情况执行,如有特殊情形,应与项目经理协调,如公共模块须告知项目组其他人员,以确保项目开发过程中版本一致,风格统一