软件系统开发编码规范

城市超级大脑（数据大脑平台及部分智慧应用）项目城市超级大脑（数据大脑平台及部分智慧应用）项目城市超级大脑（数据大脑平台及部分智慧应用）项目城市超级大脑（数据大脑平台及部分智慧应用）项目智慧文旅编码规范

版本记录版本号提交人更新摘要提交时间审核人审核时间审核记录V1.0钟鸣新建2019-09-24孙培杰2019-09-26符合提纲要求审核通过 目录TOC\o"1-3"\h\u1文件类型 文件类型表STYLEREF1\s1-SEQ表\*ARABIC\s11文件命名表文件类型扩展名Java文件.javaJava字节文件.classJava库文件.jarXML文件.xmlJSP文件.jspHTML文件.htm/.htmlJavascript文件.jsActionScript文件.asMXML文件.mxmlMXML编译后文件.swf批处理文件.batcss文件.cssScss文件.scssVue文件.vue文件组织对文件的组织将采用以下形式：1、组成文件的段落用空行分开，并且对这些独立的段落用注释进行标注。2、单个文件确保不超过2000行，避免单个文件过于臃肿。3、适当的文件格式。详细的代码规范描述如下。开始注释所有的源文件都以注释开始，注释中列出类名，版本信息，日期和版权声明。例如：/**类名**版本信息**日期**版权声明*/包和导入声明JAVA源文件的第一个非注释行是package语句。之后，import语句出现。如：packagejava.awt；importjava.awt.peer.CanvasPeer；唯一包名的第一部分总是以全小写ASCII字符书写，并且是顶级域名，通常是com，edu，gov，mil，net，org或者两位由英文字母标识的国家代码。国家代码由ISOStandard3166，1981规范指定（译者注：如中国的国家代码为cn）。JavaScript文件时的默认行为是为每个QML组件实例提供唯一的隔离副本。类和接口定义下表描述了接口和类定义，如下：表STYLEREF2\s2.3-1类和接口定义描述表编号类和接口定义备注1类/接口文档注释(/**...*/)2Class或者interface声明接口类的实现要注意方法重写。3如果有必要，对类/接口编写实现注释(/*...*/)该注释应当包含任何接口/类信息，这些信息不适合在类/接口文档注释中出现。4类(静态)变量首先是公共类变量，其次是保护变量，其次是包级别变量(无访问修饰符)，最后是私有变量。5实例变量首先是公共实例变量，其次是保护变量，其次是包级别变量(无访问修饰符)，最后是私有变量。6构造器注意构造器的使用，自定义构造注意保留原始构造。7方法以功能对这些方法分组比以作用域或者可访问性分组更适当。例如，一个私有的类方法可以在公共的实例方法之间。其目的是使阅读和理解代码更容易。缩排代码格式使用tab缩进源代码。使用alt+shift+f（eclipse）来格式化代码,注：格式化代码后还需手动来调下。JavaScript：tab键用（必须）用四个空格代替。.vue文件：tab键用（必须）用四个空格代替。源文件编码源文件使用utf-8编码，结尾用unixn分格。行宽行宽度一般不要超过80,使用JDK1.8面向流的开发方式时，注意代码层次也不宜过长。包的导入删除不用的导入，尽量不要使用整个包的导入。在eclipse下经常使用快捷键ctrl+shift+o修正导入。域格式每行只能声明一个域。

域的声明用空行隔开。代码块格式缩进风格大括号的开始在代码块开始的行尾，闭合在和代码块同一缩进的行首，同一层次的代码要保持整齐。例如：packagecom.test;publicclassTestStyleextendsSomeClassimplementsAppleInter,BananaInter{

publicstaticfinalStringTHIS_IS_CONST="CONSTVALUE";

privatestaticvoidmain(String[]args){

intlocalVariable=0;

}

publicvoidcompute(Stringarg){

if(arg.length()>

0){

System.out.println(arg);

}

for(inti=0;i<10;i++){

System.out.println(arg);

}

while(condition){

}

do{

otherMethod();

}while(condition);

switch(i){

case0:

callFunction();

break;

case1:

callFunctionb();

break;

default:

break;

}

}}空格的使用表示分割时用一个空格不能这样：if(a>b){//dosomethinghere};运算符两边用一个空格隔开 不能这样：if

(

a>

b

)

{

//dosomethinghere};二元三元运算符两边用一个空格隔开如下：a+b=c;b-d=e;returna==b?1:0;不能如下：a+b=c;b-d=e;returna==b?1:0;空行的使用空行可以表达代码在语义上的分割，注释的作用范围，等等。将类似操作，或一组操作放在一起不用空行隔开，而用空行隔开不同组的代码。如图：order=orderDao.findOrderById(id);

//updatepropertiesorder.setUserName(userName);order.setPrice(456);order.setStatus(PAID);orderService.updateTotalAmount(order);session.saveOrUpdate(order);上例中的空行，使注释的作用域很明显.连续两行的空行代表更大的语义分割。方法之间用空行分割域之间用空行分割超过十行的代码如果还不用空行分割，就会增加阅读困难注释系统采用两种注释：实现注释和文档注释。实现注释以/*...*/，和//为分隔符。文档注释以/**...*/为分隔符。实现注释表示对代码块的注释或者对代码实现细节的注释。文档注释是对代码规格进行描述。文档注释与代码实现无关（注：不对过程内部进行注释，只注释过程规范，如过程描述、参数及返回）。注释用来提供代码的概要信息，以及提供代码本身没有提供的额外信息。注释仅仅应当包含与阅读、理解代码有关的信息。例如：怎么构建包或者目录信息不应当包含不注释中（注：这些信息应当包含在readme.txt中）。类、类属性、类方法的注释必须使用javadoc规范，使用/**内容*/格式，不得使用//xxx方式。在IDE编辑窗口中，javadoc方式会提示相关注释，生成javadoc可以正确输出相应注释；在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。注释不能被加上大量的*号（译者注：如/******************/这样的注释）。注释不能包含特殊字符如退格符。实现注释采用以下四种风格：块注释，单行注释，跟随注释，和行注释。能够准确反应设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。块注释块注释用于提供文件、方法、数据结构、算法的描述。块注释可以在每个文件开始处或者每个方法之前使用。也可以在其他地方，如方法内使用。方法内部的块注释应当为与代码排列整齐。块注释应当以一个空行开头，以使其与其他代码区分开来。/**Hereisablockcomment.*/以/*-开始的块注释不会被重新格式化。如：/*-*Hereisablockcommentwithsomeveryspecial*formattingthatIwantindent(1)toignore.**one*two*three*/单行注释方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/**/注释，注意与代码对齐反例：inti=this.getNum();//获取xxx正例://inti=this.getNum();短的注释可以用与代码并排的单行注释来实现。如果注释不能在一行中书写，则应当使用多行注释。单行注释应当以空行开始。以下是一个单行注释的例子：if(condition){/*Handlethecondition.*/...}跟随注释非常短的注释可以与代码同行，但是应当与代码隔得足够远。如果多个跟随注释与同一个代码块相关，它们应当排列整齐。这是一个跟随注释的例子：if(a==2){returnTRUE;/*specialcase*/}else{returnisPrime(a);/*worksonlyforodda*/}行注释//注释分隔符可以注释一个完整的行或者一行的某个部分。它不应当用来对多行代码进行代码注释。以下是三类型的注释例子:if(foo>1){//Doadouble-flip....}else{returnfalse;//Explainwhyhere.}//此种方式不被允许//if(bar>1){//////Doatriple-flip.//...//}//else{//returnfalse;//}文档注释文档注释描述Java类、接口、构造器、方法、和属性。每一个文档注释处于/**...*/里面，每个类、接口、或者方法都应当有文档注释。注释应当出现在定义之前：/***TheExampleclassprovides...*/publicclassExample{...注意：顶层类和接口是没有缩排的。注释的首行(/**)也是没有缩排的；随后的注释行都有一个空格的缩排(水平对齐*号)。成员（包含构造器）的注释，首行有四个空格，随后的行有五个空格。如果需要给出类、接口、变量或者方法的信息，在定义之后使用块注释或者单行注释。文档注释不能位于方法或者构造器内部。因为会将文档注释与其后的定义（注：即下一个方法定义）相关联。以下是文档注释的代码示例：/***ReturnsanImageobjectthatcanthenbepaintedonthescreen.*Theurlargumentmustspecifyanabsolute{@linkURL}.Thename*argumentisaspecifierthatisrelativetotheurlargument.*<p>*Thismethodalwaysreturnsimmediately,whetherornotthe*imageexists.Whenthisappletattemptstodrawtheimageon*thescreen,thedatawillbeloaded.Thegraphicsprimitives*thatdrawtheimagewillincrementallypaintonthescreen.**@paramurlanabsoluteURLgivingthebaselocationoftheimage*@paramnamethelocationoftheimage,relativetotheurlargument*@returntheimageatthespecifiedURL*@seeImage*/publicImagegetImage(URLurl,Stringname){ try{ returngetImage(newURL(url,name)); }catch(MalformedURLExceptione){ returnnull; }}方法注释所有的抽象方法（包括接口中的方法）必须要用javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。说明：如有实现和调用注意事项，请一并说明。/***根据事项编码查询表单结构**@paramtaskCode*@return*/类注释所有的类都必须添加创建者信息。/***表单信息控制器**@Author:lea*@Date:2019/2/2817:35*@Version1.0*/变更注释/**

*

<p>

*

*

</p>

*

*

@author

shiyun

*

@since

变更时间或版本

*/Swagger注释基于Swagger注释可以将项目的所有接口在一个UI界面上展示出来，同时表明了这个接口的用途，接口需要的参数是什么类型参数是否必须，输入了参数可以直接测试接口类似postman的功能，会显示接口请求的状态码和返回的数据结构，更好的注释用于在线接口测试的。表4.8-1swagger注释表作用范围API使用位置对象属性@ApiModelProperty用在出入参数对象的字段上协议集描述@Api用于controller类上协议描述@ApiOperation用在controller的方法上Response集@ApiResponses用在controller的方法上Response@ApiResponse用在@ApiResponses里边非对象参数集@ApiImplicitParams用在controller的方法上非对象参数描述@ApiImplicitParam用在@ApiImplicitParams的方法里边描述返回对象的意义@ApiModel用在返回对象类上定义每行的数量推荐每行只定义一个变量，这样便于书写注释。intlevel;//indentationlevelintsize;//sizeoftable上面的书写方面是首选的。intlevel,size;上面的书写虽然正确，但不被允许。不要在同一行书写不同类型的定义，如:intfoo,fooarray[];//错误的!初始化尽量在定义时对变量进行初始化。前端代码所有用到变量必须在data中初始化；变量用let声明，避免提升带来隐患常量用const，全局公共常量全大写位置仅仅在块开始的地方放置定义。（块是指由"{"和"}"围绕的代码。）不要在变量使用时才定义。voidmyMethod(){intint1=0;//在方法块的开头定义if(condition){intint2=0;//在"if"块的开头定义。...}}为了避免局部变量隐藏更高作用域的变量，不允许在块里面定义与外层块中同名的变量：intcount;...myMethod(){if(condition){intcount=0;//应当避免!...}...}类和接口语句在编写类和接口时，应当沿用以下的格式规则：1、在方法名和"("之间不要有空格。这个"("用于开始参数列表；2、"{"与定义语句在同一行，并在该行末尾，”}"单独处于一行，并与定义行左对齐。除非过程体为空，此时"}"应当紧跟在"{"后面，并与"{"处于同一行；classSampleextendsObject{intivar1;intivar2;Sample(inti,intj){ivar1=i;ivar2=j;}intemptyMethod(){}...}3、方法之间以空行分开；4、函数保持单一职责，避免函数代码过长；5、公共方法提前封装，区分工具函数库和功能函数库。语句简单语句每行最多包含一条语句。如：argv++;//正确argc--;//正确argv++;argc--;//应当避免!复合语句复合语句是指由"{statements}"包含的语句列表。“}”应当在块内的语句基础上向左缩排一个层次。“{”应当在复合语句开始行的末尾。“{”，“}”用于包围住块内所有代码，即使块内只有一个单行，也需要用“{”，“}”包围起来。这样可以更容易添加块内语句，避免因为在添加块内语句时忘记加上“{”，“}”而意外的引入BUG。返回语句有返回值的返回语句不要使用“（）”，除非一些显而易见的原因需要加上（）。如：return;returnmyDisk.size();return(size?size:defaultSize);if,if-else,ifelse-ifelse语句if-else语句应当如以下格式:if(condition){statements;}if(condition){statements;}else{statements;}if(condition){statements;}elseif(condition){statements;}else{statements;}注意:if语句总是应该使用{}。应当避免以下错误格式：if(condition)//错误，缺少{}!statement;for语句for应当以以下格式书写：for(initialization;condition;update){statements;}空的for语句（所有工作在for语句的初始，条件判断，修改部分完成）应当是以下格式：for(initialization;condition;update);在for语句中，如果在初始子句、修改子句中使用了“，”操作符,应当避免使用三个以上的变量。如果确实有必要，可以在FOR循环前或者循环体结束时使用多条语句。while语句while语句应当使用以下格式：while(condition){statements;}空while语句应当使用以下格式：while(condition);do-while语句do-while语句应当使用以下格式:do{statements;}while(condition);switch语句switch语句应当使用以下格式:switch(condition){caseABC:statements;/*fallsthrough*/caseDEF:statements;break;caseXYZ:statements;break;default:statements;break;}没有break语句时，会接着执行下一个case语句块，应当在没有break的case块中加入一个注释。每个switch应当包含一个default分支。虽然此时break语句是多余的，但是当以后增加一个case分支时，它可以防止执行新加的代码。try-catch语句try-catch语句应当使用以下格式：try{statements;}catch(ExceptionClasse){statements;}try-catch也可以跟随finally子句。try{statements;}catch(ExceptionClasse){statements;}finally{statements;}空白符空行通过空行，将逻辑相关的代码分块，可以改善程序的可读性。以下情况，需要用两个空行：一个源文件中的两个段落中。在两个类和接口定义之间。以下情况，需要用一个空行：（1）方法之间。（2）方法的局部变量和第一条语句之间。（3）开始一个代码块或者单行注释时。（4）在一个方法内改善可读性时（通过空行使逻辑相关的代码块组织在一起）。空格在以下情况中，需要使用空格:关键字与其后的“（”之间。如：while(true){...}注意：在方法名和其后的“（”之间不应该有空格。在参数列表的“，”后面应该有一个空格。所有的二元操作符，与其操作数据之间要有空格，所有一元操作符与其操作数之间不应当有空格符，如("++")，("--")。如：a+=c+d;a=(a+b)/(c*d);while(d++=s++){n++;}printSize("sizeis"+foo+"\n");For语句的表达式之间。如：for(expr1;expr2;expr3)类型转换时，应当在前面加一空格。如：myMethod((byte)aNum,(Object)x);myMethod((int)(cp+5),((int)(i+3))+1);命名规范方法命名及注释规范成员方法的命名成员方法的命名应该采用全英文单词且是大小写混合的方式来进行。方法名的第一个单词均小写，其它单词的首字母大写。而且方法名中第一个单词最好是一个动词形式的。如：openAccount(),printMailingLabel(),save(),delete()等。通过这样的命名规范，很容易看出这个方法是干什么用的，它的目的是什么。尽管有时方法名会比较长，但它能很容易让其他人理解本方法的意图。get方法，它一般返回一个属性值，一般应将get放在方法名中第一个单词的位置。而当它返回的是判断其结果是true或者false的时候，一般用”is”来取代”get”。例如：getFirstName(),getAccountNumber(),isPersistent(),isAtEnd()等等。通过这种命名规范，就可以很清楚的知道本方法是返回一个对象的属性或返回一个boolean值。同样，对于set方法，它一般是用于设置对象的属性值，同样也将set放在方法名中的第一个单词的位置。如：setFirstName(StringaName),setAtEnd(booleanisAtEnd),setPersistent(booleanisPersistent)等等。构造方法的命名构造方法一般是用来创建一个对象时要执行的初始化操作。构造方法必须具有与类名完全一致的名字，其大小写也必须完全一致。这种命名规范是由sun公司确定，且必须遵守。成员方法的头部注释文档规范每一个成员方法的前面必须要有相应的注释文档说明，它主要包括以下内容，但不仅限于以下内容：1、本成员方法的目的是什么。2、本成员方法要传递的参数是什么。它们是如何被使用的。3、本成员方法的返回值是什么。4、本成员方法有什么潜在的bugs，它们在被调用时要注意些什么。5、本成员方法会抛出什么样的异常。6、访问权限的控制说明。7、代码更改的一些历史信息，如什么时候被更改过，谁更改的，目的是什么等等一些信息。成员方法的内部注释文档规范为了更好的描述成员方法的目的，还会在成员方法的内部给予适当的注释，一般有两种格式：/*……..*/和//……….。一般而言，内部注释文档应该说明以下一些要素：控制结构，描述每一个控制结构是什么样的。在某些特殊的地方说明本代码为什么要这样编写。例如，在某些特殊的商业规范的处理代码中，给予说明。局部变量的说明，通常用单行的注释说明它们是如何使用的，意义是什么。对难以理解的，复杂的代码要有适当的说明，以便于其他开发人员理解。对一些必须按照特定的顺序被执行，否则出错的代码段，对其处理顺序进行适当的文档说明。成员方法的访问权限控制成员方法的访问权限控制的基本原则是尽量的限制对成员方法的访问权限。如果没有必要设置为public，则将其设置为protected，否则设置为默认方式或者private。getXxxx方法和setXxxx方法的使用getXxxx方法和setXxxx方法的名称一般是：get+属性名/set+属性名或is+属性名。例如：表8.1.6-1getXxxx方法和setXxxx方法的使用表属性名类型get方法set方法FirstNameStringgetFirstName()setFirstName(参数表)PersistentBooleanisPersistent()setPersistent(参数表)OrderItemsArrayofOrderItemsObjectsgetOrderItems()setOrderItems(参数表)getXxxx方法和setXxxx方法一般对其有如下的使用方式：设置对象属性的初始值。更新对象的属性值。得到属性值。控制对属性值的访问和修改，特别是修改。访问常量。访问数组，vector等多值数据变量。降低父、子类之间的耦合程度。例如：//Answerthebranchnumber,whichistheleftmostfourdigitsofthefullaccountnumberprotectedintgetBranchNumber(){if(branchNumber==0){//Thedefaultbranchnumberis1000,whichisthemainbranchindowntownBedrocksetBranchNumber(1000);}returnbranchNumber;}getXxxx方法和setXxxx方法的访问权限的控制：一般情况，将它们设置为“protected”，这样，只有同包类或子类的对象可以访问它们。但是通常将getXxxx方法设置为“public”方式，而setXxxx方法则是“protected”方式。只有在极少数情况下才将setXxxx方法设置为“public”方式。当然，有时也将setXxxx方法设置为“private”方式。属性变量的命名和注释规范属性变量的命名规范属性变量的命名采用全英文单词的混合命名方式，第一个单词全部小写，以后单词的第一个字母大写，其余小写。以便让它易于理解。而对于那些像数组或动态数组等一些多值的数据类型属性，则应该采用单词复数的方式命名（s加在最后一个单词上面），它的主要优点是可以方便的指明它们有多个值。例如：firstName,zipCode,orderItems等。前端命名属性变量命名方式采用⼩驼峰式命名⽅法并且在，命名规范：类型+对象描述的⽅式，如果没有明确的类型，就可以使前缀为名词。javascript变量命名类型变量命名前缀array数组aboolean布尔值bflfloat浮点数lfunction函数fnint整型iobject对象oregular正则rstring字符串s属性变量的访问权限控制为了是对象具有更好的封闭性，一般不把属性的访问权限设置为public，建议一般把所有的属性访问权限设置为private，以防止其它类的对象直接访问本类对象的属性。而对属性的访问可以用getXxxx方法和setXxxx方法进行。属性变量的注释每一个属性变量都要给予注释，以便其他开发人员更好的理解其含义。一般从以下几个方面给予注释：描述属性变量，以便其他开发人员知道如何使用它。访问权限的说明。如果你的属性变量的访问权限不是private修饰的，则必须给予说明其为什么是这样的。对于某些特殊取值（范围）的属性，其取值（范围）给予适当的说明，以便其他开发人员理解和使用。适当的例子说明。对与某些特殊情况相关的属性，可适当的加以例子说明，以便于别人更好的理解和使用。件变量的命名规范对于组件的命名，一般采用全英文单词的命名方式，但是采用将组件类型名后缀的方法。这样，就很容易识别这个组件变量的目的，从它的后缀类型就可以方便的看出。也很容易在列表中找到每一个组件（在很多可视化编程环境中，提供列表的方式来快速显示所有用到的组件变量）。如：okJButton,fileJMenu,newFileMenuItem等等。常量命名规范常量命名采用全英文单词的方式进行，且全是大写的字母，单词之间用下划线连接。如：MINIMUM_BALANCE，DEFAULT_START_DATE等等。它的主要优点是可以很容易的与变量区分开来。局部变量的命名和注释规范一般而言，局部变量的命名规范遵循属性变量的命名规范，即全用英文单词命名，且除第一个单词以外，其它单词的首字母均大写。但是，对于下面所列举的几种特殊类型的局部变量的命名有些特殊的规定：streams当一个单一的输入或输出流对象被定义和使用时，一般用in,inputStream表示输入流，而用out,outputStream表示输出流。而当一个流同时被使用为输入流和输出流的时候，则用inOut或者ioStream来命名。循环计数器的使用由于在成员方法中，我们经常会用一些循环结构，同时也就会使用循环计数器。在以前的C，C++中，已经习惯于使用像i,j,k等变量作为循环计数器，在JAVA编码中，也采用常用的，单一的小写字母来命名循环计数器。例如：for(i=0;i<10;i++)。例外对象的命名规范在JAVA中，经常会碰到一些例外情况的处理，一般用一个字母“e”来命名相应的例外对象。局部变量的文档注释一般涉及到以下几个方面：说明局部变量是如何被使用的。局部变量的声明与使用尽量靠近，也即等到要使用的时候才声明局部变量。一个局部变量尽量只用在一件事物上，而不要用在多件事物上，以便于理解。一般采用单行注释的方式。成员方法参数命名和注释规范成员方法参数的命名规范基本上与局部变量的命名规范相同。如：customer,inventoryItem,in,e等。成员方法参数的文档注释：成员方法参数的文档注释在成员方法的头部注释文档中，它应包括以下内容：该参数将被如何使用。该参数的一些约束或其它前提条件。如果仅凭以上的描述还不足以让人容易理解该参数是什么样的，可以举一个或多个例子加以说明。类的命名和注释规范类的命名也是采用全英文单词描述的方法，但它的第一个单词的首字母必须大写，其它单词的首字母也要大写。例如：publicclassCustomer{….}publicclassOrderItems{…}。类的注释文档一般位于类的定义之前，它将包含如下内容：本类的目的。其他开发人员常常需要知道一个类的通常目的，以便决定其是否是他所需要的。一些预知的bugs。一般情况，如果有bugs存在，最好是对其进行相应的处理。但有时，我们没有更多的时间，或在本类中没有必要对其进行处理，在目前而言不是太重要。在这种情况下，应文档给予说明。比如，类中的一个成员方法在传递一个负数的参数时不能正常工作，而正好应用程序有不会传递负的参数过来，在这种情况下，就有一个预知的bugs，但没有相应的处理，则应文档说明，以便其他开发人员清楚。对本类的一些开发/维护的历史信息的说明。比如日期、作者以及主要改变的内容等。如果是线程类的话，应对其使用的并发控制策略作适当的描述，以及为什么采用这种策略而不是其它策略等信息。接口的命名和注释规范接口的命名，其第一个字母必须是大写的“I”，以表明它是一个接口，与其它类进行区别。剩下的部分与类的命名规范一样，采用全英文单词描述的方法，第一个单词首字母大写，其它单词的首字母也大写。例如：publicinterfaceIOrderItems{……..}，publicinterfaceICustomer{…..}。接口的文档注释必须在接口被定义前给予说明，主要包括以下内容：本接口定义的目的。当其他开发人员使用一个接口的时候，他们常常需要了解本接口所封装的内容以及其目的。它将被怎样的使用或这不能被怎样的使用。其他开发人员想知道本接口能被如何使用以及它不能被如何使用。接口内的抽象成员方法的注释，参照类的成员方法的注释。包的命名和文档说明规范包的命名有以下几个规则：包与子包之间或包与类之间用“”加以区别。包名全部用小写字母来命名，如：persistence.mapping.relational等。如果一个包有可能在多个组织中使用，则使用本组织域名的逆转方式来命名包。如：.mcm.www.persistence.mapping.relational等。对于每一个包，应该有一个或多个外部文档来描述这个包。一般而言，文档中应描述如下内容：描述这个包是一个什么样的包，它有一些什么样的相关性等等。包中的类和接口的简单描述。应该有一个包中的类和接口的简单列表，并对每一个类和接口有相应的简单描述，以便其他开发人员都清楚的知道其包含的内容。惯例访问实例和类变量除非有充分的理由，不要使用公共的类变量、实例变量。通常，实例变量不需要显式的设置和读取。需要这样做的时候，使用方法调用。一个合适的使用公共实例变量的例子是：当类仅当成数据结构使用，而没有行为（注：没有方法调用）。类变量和方法避免通过类实例访问类方法和类变量。应该使用类名代替。如：classMethod();//OKAClass.classMethod();//OKanObject.classMethod();//避免!常量数字常量应该直接在代码中编写，除非象-1，0，和1这种可以在for循环中作为计数器使用的数字。变量赋值避免在同一行中将一个值赋给多个变量。这使代码阅读更困难，如：fooBar.fChar=barFoo.lchar='c';//应当避免!下面的写法不被接受：if(c++=d++){//应当避免!(Java不接受)...}应当写成：if((c++=d++)!=0){...}不要为了提高性能而使用内嵌的赋值语句。那是编译器的任务。如：d=(a=b+c)+r;//应当避免!应当写成：a=b+c;d=a+r;其他惯例括号使用括号来改变表达式中的运算次序是不错的主意。有时也可以强制加上（）以使代码更好理解，尽管在某些情况下不加（）的结果正确的。if(a==b&&c==d)//应当避免!if((a==b)&&(c==d))//正确返回值如：if(booleanExpression){returntrue;}else{returnfalse;}应当被写成：returnbooleanExpression;同样的，if(condition){returnx;}returny;应当被写成：return(condition?x:y);前的条件表达式如果条件表示式包含二元操作符，应当用（）包围起来。如：(x>=0)?x:-x;特殊注释在注释中使用XXX表示假的，但是可能会存在的事物。用FIXME假的并且被确定不存在的事物。SQL规范SQL基本规范SQL语句应正确、规范、高效和最优；同一项目的SQL书写格式应该统一；应避免写非常复杂的SQL语句；SQL语句不应在客户端组织，而应在服务器端组织；SQL语句的语法应与所使用的数据库相适应；应确保变量和参数的类型和大小与数据库中表数据列相匹配。使用SELECT语句时，应指出列名，不应使用列的序号或者用“*”替代所有列名；使用INSERT语句时，应指定插入的字段名，不应不指定字段名直接插入VALUES；如果SQL语句连接多表时，应使用表的别名来引用列；示例：//正确的示例SELECTlist.manifest_no, list.bill_no,stat.list_statFROMmft_listlist,list_statstatWHERElist.manifest_no=stat.manifest_noANDlist.bill_no=stat.list_no;SQL语句应避免对大表的全表扫描操作，对大表的操作应尽量使用索引；SQL语句应避免不必要的排序；SQL语句应避免删除全表的操作；应使用变量绑定实现SQL语句共享，避免使用硬编码；//红色字体表示书写错误；蓝色字体表示书写正确SELECTemp_nameFROMempWHEREemp_no=:B1;//Bindvalue:123SELECTemp_nameFROMempWHEREemp_no=:B1;//Bindvalue:987SELECTemp_nameFROMempWHEREemp_no=123;SELECTemp_nameFROMempWHEREemp_no=987;SQL书写规则SQL语句的大小写：SQL语句中出现的所有表名、表别名、字段名、序列等数据库对象都应小写。示例：//红色字体表示书写错误；蓝色字体表示书写正确SELECT list.manifest_no, list.bill_no,STAT.list_statFROMmft_listlist,list_statSTATWHERElist.manifest_no=STAT.manifest_noANDlist.BILL_NO=STAT.list_no;ALTERSEQUENCEMANIFEST_NOCACHE200;SELECTmanifest_no.nextvalFROMDUAL;SQL语句中出现的系统保留字、内置函数名、SQL保留字、绑定变量等都应大写。示例：//红色字体表示书写错误；蓝色字体表示书写正确SELECTlist.manifest_no,list.list_no,stat.list_statfrommft_listlist,list_statstatwherelist.manifest_no=stat.manifest_noANDlist.bill_no=stat.list_no;INSERTINTOemployees(employee_name,date,employee_age)VALUES(employees_seq.nextval,'John',to_date(SYSDATE)，30）；SQL语句的命名SQL语句中出现的变量参数应采用Camel语法命名，并反映变量的实际意义。SQL语句中的表别名应简短明了，宜反映表名的实际意义。示例：//红色字体表示书写错误；蓝色字体表示书写正确SELECTlist.manifest_no,list.list_no,s.list_statFROMmft_listlist,list_statsWHERElist.manifest_no=s.manifest_noANDlist.bill_no=s.list_no;SQL语句的缩进如果一行有多列并超过80个字符，基于列对齐原则，应采用下行缩进。缩进应为1个Tab或者4个字符。同层次的SQL语句缩进应保持一致（纵向对齐）。数据对接规范数据对接概述本系统的数据主要是通过数据交换的方式进行对接。数据交换平台是实现信息资源的适配、转换和传输，并对交换过程进行配置、监控和管理的信息软件，主要具有数据交换、交换节点管理、交换流程管理、系统管理等功能。数据交换平台系统支撑交换中心和交换节点的运行，交换节点具有信息资源适配、转换和传输等基本功能，交换中心具有交换节点的基本功能，并具有对交换节点和交换流程进行配置、监控和管理的功能。数据对接用途数据交换平台一般处理数据交换量大、全程监控和管理交换过程、支持异步传输和减少二次开发工作量等情况下的数据交换工作。前后端对接标准数据统一格式返回。采用ResultDTO封装返回结果。ResultDTO属性说明如下：属性名是否必填描述ret是0成功1失败msg否响应消息，一般成功是为空串或成功提示errorcode否错误码ret为1时可自定义data否根据业务需要返回业务数据全局异常处理异常分类api接口异常对外部应用调用系统接口时出现的异常。后台基础业务异常在处理系统业务是出现的异常。比如权限认证异常、系统出错异常等请求限制异常前端web发生重复点击请求时的异常。后台请求过滤异常对于必须前端携带请求参数校验未通过抛出的异常。异常胡处理一般对于不可预期的异常进行抛出处理。对于可预期的异常进行try{}catch(){}后，进行业务处理。全局日志输出全局日志输出采用log4j2工具，根据业务进行分包输出、按天压缩，方便查看业务日志。根据项目结构，将日志输出分为以下四个部分。平台业务操作的日志输出输出文件:log/platform.log小程序调用内部接口日志输出输出文件:log/internal-api.log外部应用调用系统对外接口的日志输出输出文件:log/api.log其余日志输出输出文件:log/common.log系统数据安全前端web的调用：需要用户登录授权(采用jwt和人机验证的方式实现安全登录)小程序内部接口调用：需要用户授权登录后方可进行主要业务操作。外部应用对外接口调用：由业务系统后台授权应用后，分配授权秘钥及ip白名单后才可进行业务调用。数据库安全：数据库不对外开放，仅可通过授权ip的业务系统进行调用；业务上需要做好数据库的事务处理，数据隔离级别采用性能较高的read-commit模式。数据库设计规范建表规约1.【强制】表达是与否概念的字段，必须使用is_xxx的方式命名，数据类型是unsignedtinyint（1表示是，0表示否），此规则同样适用于odps建表。说明：任何字段如果为非负数，必须是unsigned。2.【强制】表名、字段名必须使用小写字母或数字；禁止出现数字开头，禁止两个下划线中间只出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。正例：getter_admin，task_config，level3_name反例：GetterAdmin，taskConfig，level_3_name3.【强制】表名不使用复数名词。说明：表名应该仅仅表示表里面的实体内容，不应该表示实体数量，对应于DO类名也是单数形式，符合表达习惯。4.【强制】禁用保留字，如desc、range、match、delayed等，请参考MySQL官方保留字。5.【强制】唯一索引名为uk_字段名；普通索引名则为idx_字段名。说明：uk_即uniquekey；idx_即index的简称。6.【强制】小数类型为decimal，禁止使用float和double。说明：float和double在存储的时候，存在精度损失的问题，很可能在值的比较时，得到不正确的结果。如果存储的数据范围超过decimal的范围，建议将数据拆成整数和小数分开存储。7.【强制】如果存储的字符串长度几乎相等，使用char定长字符串类型。8.【强制】varchar是可变长字符串，不预先分配存储空间，长度不要超过5000，如果存储长度大于此值，定义字段类型为text，独立出来一张表，用主键来对应，避免影响其它字段索引效率。9.【强制】表必备三字段：id,gmt_create,gmt_modified。说明：其中id必为主键，类型为unsignedbigint、单表时自增、步长为1。gmt_create,gmt_modified的类型均为date_time类型。10.【推荐】表的命名最好是加上“业务名称_表的作用”。正例：tiger_task/tiger_reader/mpp_config11.【推荐】库名与应用名称尽量一致。12.【推荐】如果修改字段含义或对字段表示的状态追加时，需要及时更新字段注释。13.【推荐】字段允许适当冗余，以提高性能，但是必须考虑数据同步的情况。冗余字段应遵循：1）不是频繁修改的字段。2）不是varchar超长字段，更不能是text字段。正例：商品类目名称使用频率高，字段长度短，名称基本一成不变，可在相关联的表中冗余存储类目名称，避免关联查询。14.【推荐】单表行数超过500万行或者单表容量超过2GB，才推荐进行分库分表。说明：如果预计三年后的数据量根本达不到这个级别，请不要在创建表时就分库分表。15.【参考】合适的字符存储长度，不但节约数据库表空间、节约索引存储，更重要的是提升检索速度。正例：人的年龄用unsignedtinyint（表示范围0-255，人的寿命不会超过255岁）；海龟就必须是smallint，但如果是太阳的年龄，就必须是int；如果是所有恒星的年龄都加起来，那么就必须使用bigint。索引规约1.【强制】业务上具有唯一特性的字段，即使是组合字段，也必须建成唯一索引。说明：不要以为唯一索引影响了insert速度，这个速度损耗可以忽略，但提高查找速度是明显的；另外，即使在应用层做了非常完善的校验和控制，只要没有唯一索引，根据墨菲定律，必然有脏数据产生。2.【强制】超过三个表禁止join。需要join的字段，数据类型保持绝对一致；多表关联查询时，保证被关联的字段需要有索引。说明：即使双表join也要注意表索引、SQL性能。3.【强制】在varchar字段上建立索引时，必须指定索引长度，没必要对全字段建立索引，根据实际文本区分度决定索引长度。说明：索引的长度与区分度是一对矛盾体，一般对字符串类型数据，长度为20的索引，区分度会高达90%以上，可以使用count(distinctleft(列名,索引长度))/count(*)的区分度来确定。4.【强制】页面搜索严禁左模糊或者全模糊，如果需要请走搜索引擎来解决。说明：索引文件具有B-Tree的最左前缀匹配特性，如果左边的值未确定，那么无法使用此索引。5.【推荐】如果有orderby