JAVA开发规范文档.docx
业精于勤荒于嬉,行成于思毁于随！JAVA开发规范文档一千零一夜产品部系统开发规范V1.0一千零一夜途遇科技有限公司2015-11-03修改记录版本号V1.0修改人刘伟修改内容规范第一版目录1前言.42开发管理.43项目周期.44命名规范.54.1项目编号命名规范.54.2文档命名规范.54.3路径管理.54.4jsp/html命名规范.64.5数据库命名规范.84.5.1表名规范.84.5.2字段规范.85文档规范.86代码规范.96.1Java源代码规范.96.1.1命名.96.1.2代码格式.116.1.3注释.126.1.4其他.136.2jsp/html代码规范.136.3数据库开发规范.156.3.1主键.156.3.2日期类型.166.3.3固定字段.166.3.4取值规范.166.3.5数据库开发工具.166.3.6Sql书写规范.176.4其他规范.177实战代码规范.187.1Java源代码规范.187.1.1java代码命名与格式.187.2jsp/html代码规范.268FAQ.298.1Logic类中新增数据方法怎么写.298.2Logic类中修改数据方法怎么写.308.3Logic类中删除数据方法怎么写.318.4怎样创建一个没有底部按钮的窗口.328.5怎样设置弹出窗口的标题.328.6怎样重写提交数据的方法.338.7怎样创建单grid的页面.338.8怎样多个页签的grid的页面.348.9怎样创建左边树右边grid的页面.349代码检查规定.3410附录1：JPA使用指南javax.persistence的注解配置.341前言为了使软件开发过程有章可循，保证软件质量，加强开发管理。2开发管理3项目周期公司项目开发周期分为以下几个步骤：文档名称说明撰写人是否可选备注需求分析完成对用户系统的需求分析对项目工作量进行详细评估，配备相应的开发、测试、实施人员指定项目的开发计划，指定到人需求说明书需求分析人必选根据项目规模员和要求详细程度可以有所不同。Demo各个模块的详开发人员必选细页面Demo根据项目规模和要求详细程度可以有所不同。开发计划标记各个模块项目经理必选到周，到人的开发计划测试计划测试计划测试人员必选根据项目情况详细情况可以不同测试用例测试人员可选根据项目情况选用开发阶段各计划阶段时间点的执行情况每周进行总结项目执行情况说明项目经理必选项目经理填写标准格式的文每周个人总结项目组成员必选系统提交测试项目阶段性提项目经理可选报告交给项目测试报告测试人员实施阶段验收报告项目经理必选档初期在贵阳项目试行4命名规范4.1项目编号命名规范4.2文档命名规范4.3路径管理路径结构如下:项目名称|_database（数据库数据）|_docs（文档）|_参考文档（项目参考文件）|_需求&设计（需求文件及各种设计文档）|_开发计划|_软件测试|_部署&培训|_工作汇报|_trunk（主目录）|_WebRoot（应用文件）|_src（源代码）|_业务模块一(某一个功能分类，如工具类)|_com.navinfo.分类英文名(源代码目录)|_entity(数据模型)|_logic(逻辑实现类)|_services(逻辑接口层)|_action(Action层)|_utils(当前功能的工具类或常量定义)|_|_spring/(spring的配置文件)|_hibernate/(hibernate的配置文件)|_struts/(struts的配置文件)|_quartz/(quartz的配置文件)注，红色字体的部分和原有规范不同，主要是业务模块和配置文件放在同一个根目录下，为防止eclipse的配置顺序导致源代码和配置文件分离的很远。|_业务模块二|_.图：Src路径4.4jsp/html命名规范jsp与html文件名全部小写，并遵循如下的规范：数据/内容显示页名词，多个单词用下划线分隔，要求能说明显示内容的信息，为避免冲突，可加上"_list"。例如：new_message.html或my_file_list.jsp操作处理页命名格式：名词_下划线_动词，例如：file_delete.jsp。图：Jsp命名含frame页面<frameset>中<frame>的name属性命名的格式是xxx._xxx_xxxxxx部分用来标识当前页面隶属于整个系统中的哪一功能模块。如：属于ebwebmail则被表示为ebwebmail，其它情况依次类推。xxx部分标识当前页面所要完成的功能。如：完成用户登录的功能则被标识为login，其它情况依次类推。xxx部分用来用来表示页面在浏览器窗口所处的位置。处于浏览器窗口的顶部则标识为top，其它情况依次类推。例如：ebwebmail_inbox_top.jsp<frame>src属性相应的文件名根据情况建议在原命名规范上用下划线加上所处窗口的位置。javascript脚本方法脚本函数都以xxx_xxx的方式命名。xxx对应页面隶属的模块。xxx表示函数所要实现的功能(动宾结构)，多个单词用下划线连接。例如：ebwebmail_send_mail()模块通用的脚本函数必须集合于一个js文件中，在页面上通过<scriptlanguage="javascript"src="url"></script>形式导入。js文件名命名使用模块名，例如：ebwebmail.js。如果项目已经提供了公共js脚本，则优先使用公共js脚本中提供的函数。所有定义方法的<script>元素定义在<head></head>中或</body>后。javascript脚本内部变量与参数单词之间用下划线分隔且全部小写，例如：varfile_size。<form>表单name属性除系统模版生成的form外，统一以"form_"开头，其后加该表单所需收集的信息的作用或动作，例如：form_file_upload或form_send_mail。表单elements表单element的名称以element需收集的信息标示命名，单词之间使用下划线分隔且全部小写，例如：<inputtype="text"name="username"><inputtype="radio"name="file_type"><textareaname="content"rows="5"cols="40">cookie命名命名格式：模块名_存储信息名词(多个单词用下划线分隔)，全部大写，例如：EBWEBMAIL_SORT_TYPE。window.open中name参数的命名javascript的window.open方法中有一个name的参数，浏览器约定同样的名字的窗口只能打开一个，如果程序间名字重复将相互冲突。如果不限制打开窗口数，可以指定''或"（"不是null），否则需要加上模块名，例如ebwebmail_viewmail。4.5数据库命名规范4.5.1表名规范关于命名的规范，统一使用大写，单词之间用下滑写，采用三段式或者二段式。a)头一段标识数据库对象类型（T表,V视图，SP存储过程，TR触发器）b)二段标识业务的类型，详见四维产品体系.mmapc)三段和四段标识表的属性。（订单：ORDERS，计划：PLANS，路线：ROUTES）例如：系统用户表，系统用户状态字典表（T_CP_URERS_STATES）,订单表（T_BD_BLL_ORDERS）4.5.2字段规范所有表示boolean含义的字段，在前方需要加入IS_前缀5文档规范编写文档目前主要使用的工具是Word（项目计划文档例外，需要使用Project制作，项目计划文档为非技术的客户提供Excel版本），辅助使用的工具有Visio，PowerPoint等。所有Office文档均使用Office2003兼容格式文档。文档务必保持段落格式整齐，文字字体，颜色，大小统一。如果需要摘引html页面中的内容，不能直接从html中粘贴过来（会在word文档中留下html格式），而必须先去除格式，例如：先粘贴到notepad中。务必注意中英文标点符号，文档正文一概使用中文标点符号。如果需要在文档中插图，不要使用word自带的绘图工具。可以选择使用PowerPoint或visio。使用PowerPoint，选择"插入"->"对象"->"MicrosoftPowerPoint幻灯片"。使用visio，需要另外建立visio文档，绘制完以后粘贴到word中。Visio不得在word文档上的Visio对象上进行修改，要在源文件上修改后粘贴到word文档上。数据建模使用PowerDesigner工具。在项目进入开发阶段后，所有的的对PowerDesigner的修改需要同时提供相应修改的sql语句，并放到系统的文档目录下。对数据建模的文档修改，需要由项目经理统一进行，防止发生版本不统一的情况。修改他人文档务必使用修订模式，以便保留备修改的内容。使用修订模式，选择"工具"->"修订"->"突出显示修订"，勾上"编辑时标记修订"。6代码规范6.1Java源代码规范6.1.1命名6.1.1.1Package的命名Package的名字应该都是由一个小写单词组成，例如：com.navinfo.backplatform。此外，对于包名我们做如下约定：工具函数类包名前缀为.utilstestcase类包名前缀为.test图：工具类包结构6.1.1.2Class的命名Class的名字必须由大写字母开头而其他字母都小写的单词组成，例如：DataFile或InfoParser。Class变量的命名变量的名字必须用一个小写字母开头。后面的单词用大写字母开头，例如：debug或inputFileSize。StaticFinal变量的命名StaticFinal变量的名字应该都大写，并且指出完整含义，例如：MAX_UPLOAD_FILE_SIZE=1024。参数的命名参数的名字必须和变量的命名规范一致。数组的命名数组应该总是用下面的方式来命名：bytebuffer;而不是：bytebuffer;方法的参数使用有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字：SetCounter(intsize)this.size=size;6.1.2代码格式6.1.2.1文件头声明源文件的头部需要一个history段，对于每次对源文件的重大改动，都需要在history段中注明。该段定义在package和import之间，例如：*HISTORY*功能描述：*2002/01/29Biz创建文件*2002/02/19kevin增加新功能*/代码块书写格式可以选择以下任意一种代码块的书写方式：if(true)/bodyif(true)/body建议使用第一种书写方式。如果是修改他人的代码，必须使用代码原来的书写方式。对于代码块过长，超过1屏以上，后面要说明属于那个代码块，例如：if(i>100)/toomanylinesmorethanonescreen/if(i>100)6.1.2.2代码格式关于缩进缩进使用4个连续空格，不要在源文件中保存tab字符，请注意调整所用的IDE工具，打开将tab转换为空格功能。页宽页宽应该设置为80字符.源代码一般不会超过这个宽度,并导致无法完整显示,但这一设置也可以灵活调整.在任何情况下,超长的语句应该在一个逗号或者一个操作符后折行.一条语句折行后,应该比原来的语句再缩进4个空格。操作符操作符左右各用一个空格分隔。例如：inta=b;if(a>0);6.1.2.3类和方法定义类定义或方法定义过长需要换行书写，例如：publicclassCounterSetextendsObservableimplementsCloneableprivatePortletSetgetPortlets(Portletsportlets,RunDatarundata,booleanapplication,booleanapplicationsOnly)6.1.3注释Public和protected的方法成员变量和方法必须写javadoc注释。方法名属性名在Eclipse中输入/*加回车，自动生成代码描述区间，开发人员自行根据格式进行标注。如果属于重写的方法，需要/*加入回车，不需要加入其他说明。超过1句以上的注释使用中文书写。对于代码多于10行的private方法也要写javadoc注释。对于代码中的逻辑分支或循环条件需要书写注释，例如：if(somecondition)/符合某个条件，应该这样处理else/否则应该那样处理6.1.4其他关于属性类中的属性不能定义为public变量直接存取，而是定义成protect变量并编写get/set方法，例如：protectStringmyName;publicStringgetMyName()returnmyName;publicvoidsetMyName(StringmyName)this.myName=myName;6.2jsp/html代码规范jsp/html描述注释jsp/html页面顶部必须存在一个基本描述注释，包含功能描述、参数列表和历史修改信息，例如：<%-/*NAME:file_download.jsp*PURPOSE:下载文件提示*PARAMETERS:*file_id-文件ID号*force?C是否强制下载*HISTORY*2002/04/05Hafele创建文件*2002/06/07tmp增加强制下在功能*/-%>jsp头格式jsp头部一般需要遵循以下格式：<%pagecontentType="text/html;charset=UTF-8"%><%pageimport="java.io.*"%>/jdk标准包<%pageimport="javax.mail.*"%>/java扩展包<%pageimport="org.apache.xml.*"%>/使用的外部库的包<%pageimport="com.sunrise.*"%>/使用的项目的公共包<%pageimport="com.sunrise.applications.*"%>/使用的模块的其他包<%includefile="some.jsp"%>/include其他的jsp<%response.setHeader("Pragma","No-cache");response.setHeader("Cache-Control","no-cache");response.setHeader("Expires","0");%>/一般jsp都需要防止缓存html格式html头一般需要遵循以下格式：<head><metahttp-equiv="Content-Type"content="text/html;charset=UTF-8"><title>sometitle</title><linkrel="stylesheet"href="some.css"type="text/css"><scriptlanguage="javascript">/somejavascript</script></head>注意：必须指定一个有意义的<title>，严禁出现"Untitled"或"未命名"之类的<title>。2.所有html标签使用小写3.html页面一般需要设置一个背景色（一般是#FFFFFF）。html语法校验所有的jsp/html页面需要能够使用DreamWeaver正确打开（即html语法正确，没有错误的标记）。注释一般不使用html注释，除非是有必要让最终用户看到的内容。对于包含JSP代码的html块，必须使用JSP注释。对于没有必要的注释，在发行版本中必须移除。form属于域的maxlength对于text类型的输入域，必须根据数据库字段的长度设置相应的maxlength，例如数据库类型是VARCHAR(64)，那么maxlength是32（因为中文浏览器对于中文也认为是一个字符）。6.3数据库开发规范6.3.1主键每个表都有一个自动增长键作为主键ID。同时，业务逻辑上，采用唯一主键做索引，我们可以采用UUID，或者订单号，作为逻辑主键。以订单表为例：BLL_ORDERSIDLONGORDER_NUMVARCHAR(30)AMOUNTNUMBER(8)CREATE_TIMELONGUPDATE_TIMELONG.ID为自动增长列作表的主键，ORDER_NUM或者UUID实际订单的编号，设置为唯一键（或者不设也可以）。这样做的好处是：加快JOIN查询的速度，因为，如果采用订单编号这一类型键值作为主键，它的类型多为字符型，如果多表JOIN会比，数值型慢很多。而且一般ORDER_NUM这类型的键值一般是通过逻辑生成，很难保证是绝对唯一的。建立自增主键的方法：http:/www.oracle-为什么需要同时具有UUID和ID？UUID具备防篡改的能力，但是过长同时不易读，在大数据量的存储的时候会导致空间的浪费。即在关联表或者外键中，都使用id进行关联。ID和UUID都是能找到唯一一条记录的。因此，在数据存储层（dataaccesslayer）里，使用ID和UUID进行更新或删除操作，都可以，对数据安全没影响。而在代码里，更新数据或删除数据的操作，采用自增ID，而数据显式传递是（如，通过URL传递参数时）采用UUID根据UUID，在数据库里把整个对象装载入实体类。所以，Hibernate里的实体类，必要要有自增键的映射，而联合查询必须是通过自增键进行。注：不是所有的表都需要具备UUID的，主要取决于被仿冒的程度，如用户、门店、商品等是需要UUID的，但是订单表只保留ID即可。6.3.2日期类型日期类型，统一采用文本格式的字符串，中间不加入任何连接符，在显示的时候再进行格式化转换。6.3.3固定字段每个表添加两个时间字段，CREATE_TIME，保存的是该条记录创建的时间，UPDATE_TIME，保存的是该条记录最后一次更新的时间。这个方便我做数据抽取。每个表加入ISVALID字段，用来表示该条记录是否的有效性。既是，我们业务系统的所用删除操作，都不是实际删除，只是一个标识。假如数据量增大很多后，才统一由DBA执行物理删除，而删除前可作一个备份，这样可以极大得减少因人为操作不当，而对系统数据造成的不必要损失。6.3.4取值规范当使用字符代表某个业务含义为bool型的字段时，使用1代表true的含义，使用10代表false的含义。即：isvalid标识有效性，为1代表有效，为10代表无效。6.3.5数据库开发工具数据库设计工具采用SysBase的PowerDesigner15.1建的数据库设计图。由于此PD的版本在小版本上存在格式不兼容的可能。必须限定使用工具的大小版本均一致。6.3.6Sql书写规范select*使用时要注意，不能滥用用like语句要精确，尽量使用等着查询过滤重复少用in语句（1.多用等值查询2.多用exists语句）减少SQL查询嵌套Java程序中尽量不要查一个结果集然后循环拼SQL再执行查询较少SQL语句中的SQL子嵌套）多用exists少用in表查询建索引但不要滥用建索引磁盘占用率大，建索引的规则是通过对实际业务查询要求分析而来的，而不是所有的表都需要加入。即查询条件中同时使用的等值查询部分作为索引的规则。查询要尽量使用分页查询预编译可适当使用别滥用，用多会导致游标数被占用完，同时不要for循环中间使用预编译对象的声明（可以使用对象的创建）6.4其他规范对于IDE的使用目前J2EE系统的开发使用Eclipse，但是最后提交的代码必须不依赖任何IDE，而需要可以使用ant完成所有的编译工作。一般提交的代码目录格式参照4.3限制session的使用在代码中使用session需要听取项目经理的意见，项目经理需要在设计文档中登记项目中所有使用到的session的名字和作用。限制外部包的使用开发员如果需要使用一个外部包需要听取项目经理的意见。在项目经理批准以前，严禁擅自使用一个外部的包。项目经理需要将依赖的外部包在文档中进行描述。7实战代码规范7.1Java源代码规范7.1.1java代码命名与格式7.1.1.1Package的命名Package的名字应该都是由一个小写单词组成，例如：com.navinfo.backplatform。此外，对于包名我们做如下约定：图：organization包结构7.1.1.2Entity类的命名与规范实体类定义示例代码如下：说明：1：实体类命名，表名+Entity。2：实体类注解定义EntityTable(name=”实际表名”)Cache(usage=CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)3：实体类必须继承BaseForm4：id字段的定义必须定义成id。5：Transient表示非数据库字段。7.1.1.3Logic类的命名与规范Logic类的示例代码：1：所有logic的命名都是以Logic结尾。都要继承HibernateDao这个类。2：在logic中都必须覆盖listPage这个类。3：增，删，改已经在HibernateDao这个类实现了，如下：新增，修改或删除数据操作，如果setSuccess(true)表示操作成功，如果setSuccess(false)表示操作失败，操作成功默认在jsp/js中显示的是infoSuccess的信息，操作失败默认在jsp/js中显示的是info的信息，如下图：7.1.1.4Action的命名与规范示例如下代码：说明：1：所有的action命名都是模块名+Action，都要继承com.navinfo.backplatform.core.utils.web包的CrudActionSupport类。图：CrudActionSupport的定义2：CrudActionSupport的泛型中第一个参数是实体类，第二个参数是业务逻辑类。图：action的定义3：业务逻辑类的定义，需要用到Autowired注解标签。图：逻辑类的申明4：实体类的申明，实体类与页面上的form类合成了一个，减少了一个页面form的定义。5：实现getModel()方法。在getModel()方法中需要赋值，把实体类赋值给父类的entityClass变量。把业务逻辑类赋值给baseServices变量。6：必须覆盖prepareModel()方法。7：覆盖list()方法，默认已经在父类实现了list()方法，这个方法主要是取分页数据。要实现自己的查询数据，只要在logic类中覆盖父类的listPage方法。list()方法默认是json输出，struts中的配置如下：Struts中result的type是json。但是这个action的url配置要注意，package的extends必须是json-default。Jsp中extjs中reader的配置如下：Root是page.data,totalProperty是page.totalCount。8：默认beforeAdd(),add(),beforeUpdate(),update(),delete()都已经在父类实现，可以直接调用父类的方法，如super.beforeAdd()等等。7.2jsp/html代码规范7.2.1.1jsp的命名与规范jsp示例，文件名managerexamplemoduleexample_list.jsp：1：jsp的命名是模块名+”_list.jsp”表示列表页。jsp的命名是模块名+”_add.jsp”表示新增页。jsp的命名是模块名+”_edit.jsp”表示修改页。width和height是设置第一个弹出窗口的高与宽。Widt2h和height2是设置第二个弹出窗口的高与宽。2：before_add_data_list_url:弹出第一个新增窗口的url。data_add_url:弹出第一个新增窗口的提交数据url。data_list_url:列表页的grid的store的url。before_update_
