阿里巴巴Java开发手册(终极版).pdf
《阿里巴巴Java开发手册(终极版).pdf》由会员分享,可在线阅读,更多相关《阿里巴巴Java开发手册(终极版).pdf(39页珍藏版)》请在咨信网上搜索。
1、 前言 阿里巴巴 Java 开发手册是阿里巴巴集团技术团队的集体智慧结晶和经验总结,经历了多次大规模一线实战的检验及不断的完善,系统化地整理成册,反馈给广大开发者。现代软件行业的高速发展对开发者的综合素质要求越来越高,因为不仅是编程知识点,其它维度的知识点也会影响到软件的最终交付质量。比如:数据库的表结构和索引设计缺陷可能带来软件上的架构缺陷或性能风险;工程结构混乱导致后续维护艰难;没有鉴权的漏洞代码易被黑客攻击等等。所以本手册以 Java 开发者为中心视角,划分为编程规约、异常日志、单元测试、安全规约、工程结构、MySQL 数据库六个维度,再根据内容特征,细分成若干二级子目录。根据约束力强弱
2、及故障敏感性,规约依次分为强制、推荐、参考三大类。对于规约条目的延伸信息中,“说明”对内容做了适当扩展和解释;“正例”提倡什么样的编码和实现方式;“反例”说明需要提防的雷区,以及真实的错误案例。本手册的愿景是码出高效码出高效,码出质量码出质量。现代软件架构都需要协同开发完成,高效协作即降低协同成本,提升沟通效率,所谓无规矩不成方圆,无规范不能协作。众所周知,制订交通法规表面上是要限制行车权,实际上是保障公众的人身安全。试想如果没有限速,没有红绿灯,谁还敢上路行驶。对软件来说,适当的规范和标准绝不是消灭代码内容的创造性、优雅性,而是限制过度个性化,以一种普遍认可的统一方式一起做事,提升协作效率。
3、代码的字里行间流淌的是软件生命中的血液,质量的提升是尽可能少踩坑,杜绝踩重复的坑,切实提升质量意识。考虑到可以零距离地与众多开发同学进行互动,决定在线维护手册内容,此版本号为1.3.0的PDF版本,是对外释放的终极版;其次,我们会在 2017 年 10 月 14日杭州云栖大会上,进行阿里巴巴 Java 开发规约插件全球首发,插件点此下载,阿里巴巴云效(一站式企业协同研发云)也会集成代码规约扫描引擎。最后,码出高效码出高效阿里巴巴 Java 开发手册详解即将出版,敬请关注。目录 前言 一、编程规约.1(一)命名风格.1(二)常量定义.3(三)代码格式.4(四)OOP 规约.6(五)集合处理.9(
4、六)并发处理.12(七)控制语句.14(八)注释规约.16(九)其它.17 二、异常日志.18(一)异常处理.18(二)日志规约.19 三、单元测试.21 四、安全规约.23 五、MySQL 数据库.24(一)建表规约.24(二)索引规约.25(三)SQL 语句.27(四)ORM 映射.28 六、工程结构.30(一)应用分层.30(二)二方库依赖.31(三)服务器.32 附 1:版本历史.34 附 2:本手册专有名词.35 (注:浏览时请使用PDF左侧导航栏)阿里巴巴 Java 开发手册 禁止用于商业用途,违者必究 1/35 JavaJava 开发开发手册手册 版本号版本号 制定团队制定团队
5、更新日期更新日期 备注备注 1.3.0 阿里巴巴集团技术团队 2017.2017.9 9.2525 增加单元测试规约(PDF 终极版)一一、编程规约编程规约 (一一)命名命名风格风格 1.【强制】代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。反例:_name/_name/$Object/name_/name$/Object$2.【强制】代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。说明:正确的英文拼写和语法可以让阅读者易于理解,避免歧义。注意,即使纯拼音命名方式也要避免采用。正例:alibaba/taobao/youku/hangzhou 等国
6、际通用的名称,可视同英文。反例:DaZhePromotion 打折/getPingfenByName()评分/int 某变量=3 3.【强制】类名使用UpperCamelCase风格,必须遵从驼峰形式,但以下情形例外:DO/BO/DTO/VO/AO 正例:MarcoPolo/UserDO/XmlService/TcpUdpDeal/TaPromotion 反例:macroPolo/UserDo/XMLService/TCPUDPDeal/TAPromotion 4.【强制】方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格,必须遵从驼峰形式。正例:localValue
7、/getHttpMessage()/inputUserId 5.【强制】常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚,不要嫌名字长。正例:MAX_STOCK_COUNT 反例:MAX_COUNT 6.【强制】抽象类命名使用Abstract或Base开头;异常类命名使用Exception结尾;测试类命名以它要测试的类的名称开始,以Test结尾。7.【强制】中括号是数组类型的一部分,数组定义如下:String args;反例:使用String args的方式来定义。8.【强制】POJO类中布尔类型的变量,都不要加is,否则部分框架解析会引起序列化错误。反例:定义为基本数据类型Bool
8、ean isDeleted;的属性,它的方法也是isDeleted(),RPC阿里巴巴 Java 开发手册 禁止用于商业用途,违者必究 2/35 框架在反向解析的时候,“以为”对应的属性名称是deleted,导致属性获取不到,进而抛出异常。9.【强制】包名统一使用小写,点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式,但是类名如果有复数含义,类名可以使用复数形式。正例:应用工具类包名为com.alibaba.open.util、类名为MessageUtils(此规则参考spring的框架结构)10.【强制】杜绝完全不规范的缩写,避免望文不知义。反例:AbstractClass“
9、缩写”命名成AbsClass;condition“缩写”命名成 condi,此类随意缩写严重降低了代码的可阅读性。11.【推荐】为了达到代码自解释的目标,任何自定义编程元素在命名时,使用尽量完整的单词组合来表达其意。正例:从远程仓库拉取代码的类命名为 PullCodeFromRemoteRepository。反例:变量 int a;的随意命名方式。12.【推荐】如果模块、接口、类、方法使用了设计模式,在命名时体现出具体模式。说明:将设计模式体现在名字中,有利于阅读者快速理解架构设计理念。正例:public class OrderFactory;public class LoginProxy;p
10、ublic class ResourceObserver;13.【推荐】接口类中的方法和属性不要加任何修饰符号(public 也不要加),保持代码的简洁性,并加上有效的Javadoc注释。尽量不要在接口里定义变量,如果一定要定义变量,肯定是与接口方法相关,并且是整个应用的基础常量。正例:接口方法签名:void f();接口基础常量表示:String COMPANY=alibaba;反例:接口方法定义:public abstract void f();说明:JDK8 中接口允许有默认实现,那么这个default方法,是对所有实现类都有价值的默认实现。14.接口和实现类的命名有两套规则:1)【强制
11、】对于Service和DAO类,基于SOA的理念,暴露出来的服务一定是接口,内部的实现类用Impl的后缀与接口区别。正例:CacheServiceImpl实现CacheService接口。2)【推荐】如果是形容能力的接口名称,取对应的形容词做接口名(通常是able的形式)。正例:AbstractTranslator实现 Translatable。阿里巴巴 Java 开发手册 禁止用于商业用途,违者必究 3/35 15.【参考】枚举类名建议带上Enum后缀,枚举成员名称需要全大写,单词间用下划线隔开。说明:枚举其实就是特殊的常量类,且构造方法被默认强制是私有。正例:枚举名字为ProcessSta
12、tusEnum 的成员名称:SUCCESS/UNKOWN_REASON。16.【参考】各层命名规约:A)Service/DAO层方法命名规约 1)获取单个对象的方法用get做前缀。2)获取多个对象的方法用list做前缀。3)获取统计值的方法用count做前缀。4)插入的方法用save/insert做前缀。5)删除的方法用remove/delete做前缀。6)修改的方法用update做前缀。B)领域模型命名规约 1)数据对象:xxxDO,xxx即为数据表名。2)数据传输对象:xxxDTO,xxx为业务领域相关的名称。3)展示对象:xxxVO,xxx一般为网页名称。4)POJO是DO/DTO/BO
13、/VO的统称,禁止命名成xxxPOJO。(二二)常量定义常量定义 1.【强制】不允许任何魔法值(即未经定义的常量)直接出现在代码中。反例:String key=Id#taobao_+tradeId;cache.put(key,value);2.【强制】long或者Long初始赋值时,使用大写的L,不能是小写的l,小写容易跟数字 1 混淆,造成误解。说明:Long a=2l;写的是数字的 21,还是Long型的 2?3.【推荐】不要使用一个常量类维护所有常量,按常量功能进行归类,分开维护。说明:大而全的常量类,非得使用查找功能才能定位到修改的常量,不利于理解和维护。正例:缓存相关常量放在类Cac
14、heConsts下;系统配置相关常量放在类ConfigConsts下。4.【推荐】常量的复用层次有五层:跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。1)跨应用共享常量:放置在二方库中,通常是client.jar中的constant目录下。2)应用内共享常量:放置在一方库中,通常是modules中的constant目录下。反例:易懂变量也要统一定义成应用内共享常量,两位攻城师在两个类中分别定义了表示“是”的变量:阿里巴巴 Java 开发手册 禁止用于商业用途,违者必究 4/35 类A中:public static final String YES=yes;类B中
15、:public static final String YES=y;A.YES.equals(B.YES),预期是true,但实际返回为false,导致线上问题。3)子工程内部共享常量:即在当前子工程的constant目录下。4)包内共享常量:即在当前包下单独的constant目录下。5)类内共享常量:直接在类内部private static final定义。5.【推荐】如果变量值仅在一个范围内变化,且带有名称之外的延伸属性,定义为枚举类。下面正例中的数字就是延伸信息,表示星期几。正例:public Enum MONDAY(1),TUESDAY(2),WEDNESDAY(3),THURSDAY
16、(4),FRIDAY(5),SATURDAY(6),SUNDAY(7);(三三)代码代码格式格式 1.【强制】大括号的使用约定。如果是大括号内为空,则简洁地写成即可,不需要换行;如果是非空代码块则:1)左大括号前不换行。2)左大括号后换行。3)右大括号前换行。4)右大括号后还有else等代码则不换行;表示终止的右大括号后必须换行。2.【强制】左小括号和字符之间不出现空格;同样,右小括号和字符之间也不出现空格。详见第 5 条下方正例提示。反例:if(空格 a=b 空格)3.【强制】if/for/while/switch/do等保留字与括号之间都必须加空格。4.【强制】任何二目、三目运算符的左右两
17、边都需要加一个空格。说明:运算符包括赋值运算符=、逻辑运算符&、加减乘除符号等。5.【强制】采用 4 个空格缩进,禁止使用tab字符。说明:如果使用 tab 缩进,必须设置 1 个 tab 为 4 个空格。IDEA 设置 tab 为 4 个空格时,请勿勾选Use tab character;而在 eclipse 中,必须勾选insert spaces for tabs。正例:(涉及 1-5 点)public static void main(String args)/缩进 4 个空格 String say=hello;/运算符的左右必须有一个空格 int flag=0;阿里巴巴 Java 开发
18、手册 禁止用于商业用途,违者必究 5/35 /关键词 if 与括号之间必须有一个空格,括号内的 f 与左括号,0 与右括号不需要空格 if(flag=0)System.out.println(say);/左大括号前加空格且不换行;左大括号后换行 if(flag=1)System.out.println(world);/右大括号前换行,右大括号后有 else,不用换行 else System.out.println(ok);/在右大括号后直接结束,则必须换行 6.【强制】注释的双斜线与注释内容之间有且仅有一个空格。正例:/注释内容,注意在/和注释内容之间有一个空格。7.【强制】单行字符数限制不超
19、过 120 个,超出需要换行,换行时遵循如下原则:1)第二行相对第一行缩进 4 个空格,从第三行开始,不再继续缩进,参考示例。2)运算符与下文一起换行。3)方法调用的点符号与下文一起换行。4)方法调用时,多个参数,需要换行时,在逗号后进行。5)在括号前不要换行,见反例。正例:StringBuffer sb=new StringBuffer();/超过 120 个字符的情况下,换行缩进 4 个空格,点号和方法名称一起换行 sb.append(zi).append(xin).append(huang).append(huang).append(huang);反例:StringBuffer sb=n
20、ew StringBuffer();/超过 120 个字符的情况下,不要在括号前换行 sb.append(zi).append(xin).append (huang);/参数很多的方法调用可能超过 120 个字符,不要在逗号前换行 method(args1,args2,args3,.,argsX);8.【强制】方法参数在定义和传入时,多个参数逗号后边必须加空格。正例:下例中实参的a,后边必须要有一个空格。method(a,b,c);9.【强制】IDE的text file encoding设置为UTF-8;IDE中文件的换行符使用Unix格式,不要使用Windows格式。阿里巴巴 Java 开发
21、手册 禁止用于商业用途,违者必究 6/35 10.【推荐】没有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐。正例:int a=3;long b=4L;float c=5F;StringBuffer sb=new StringBuffer();说明:增加sb这个变量,如果需要对齐,则给a、b、c都要增加几个空格,在变量比较多的情况下,是一种累赘的事情。11.【推荐】方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。说明:没有必要插入多个空行进行隔开。(四四)OOPOOP 规约规约 1.【强制】避免通过一个
22、类的对象引用访问此类的静态变量或静态方法,无谓增加编译器解析成本,直接用类名来访问即可。2.【强制】所有的覆写方法,必须加Override注解。说明:getObject()与get0bject()的问题。一个是字母的O,一个是数字的 0,加Override可以准确判断是否覆盖成功。另外,如果在抽象类中对方法签名进行修改,其实现类会马上编译报错。3.【强制】相同参数类型,相同业务含义,才可以使用Java的可变参数,避免使用Object。说明:可变参数必须放置在参数列表的最后。(提倡同学们尽量不用可变参数编程)正例:public User getUsers(String type,Integer.
23、ids).4.【强制】外部正在调用或者二方库依赖的接口,不允许修改方法签名,避免对接口调用方产生影响。接口过时必须加Deprecated注解,并清晰地说明采用的新接口或者新服务是什么。5.【强制】不能使用过时的类或方法。说明:.URLDecoder 中的方法decode(String encodeStr)这个方法已经过时,应该使用双参数decode(String source,String encode)。接口提供方既然明确是过时接口,那么有义务同时提供新的接口;作为调用方来说,有义务去考证过时方法的新实现是什么。6.【强制】Object的equals方法容易抛空指针异常,应使用常量或确定有值
24、的对象来调用equals。正例:test.equals(object);反例:object.equals(test);说明:推荐使用java.util.Objects#equals(JDK7 引入的工具类)7.【强制】所有的相同类型的包装类对象之间值的比较,全部使用equals方法比较。说明:对于Integer var=?在-128 至 127 范围内的赋值,Integer对象是在阿里巴巴 Java 开发手册 禁止用于商业用途,违者必究 7/35 IntegerCache.cache产生,会复用已有对象,这个区间内的Integer值可以直接使用=进行判断,但是这个区间之外的所有数据,都会在堆上
25、产生,并不会复用已有对象,这是一个大坑,推荐使用equals方法进行判断。8.关于基本数据类型与包装数据类型的使用标准如下:1)【强制】所有的POJO类属性必须使用包装数据类型。2)【强制】RPC方法的返回值和参数必须使用包装数据类型。3)【推荐】所有的局部变量使用基本数据类型。说明:POJO类属性没有初值是提醒使用者在需要使用时,必须自己显式地进行赋值,任何NPE问题,或者入库检查,都由使用者来保证。正例:数据库的查询结果可能是null,因为自动拆箱,用基本数据类型接收有NPE风险。反例:比如显示成交总额涨跌情况,即正负x%,x为基本数据类型,调用的RPC服务,调用不成功时,返回的是默认值,
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 阿里巴巴 Java 开发 手册 终极
1、咨信平台为文档C2C交易模式,即用户上传的文档直接被用户下载,收益归上传人(含作者)所有;本站仅是提供信息存储空间和展示预览,仅对用户上传内容的表现方式做保护处理,对上载内容不做任何修改或编辑。所展示的作品文档包括内容和图片全部来源于网络用户和作者上传投稿,我们不确定上传用户享有完全著作权,根据《信息网络传播权保护条例》,如果侵犯了您的版权、权益或隐私,请联系我们,核实后会尽快下架及时删除,并可随时和客服了解处理情况,尊重保护知识产权我们共同努力。
2、文档的总页数、文档格式和文档大小以系统显示为准(内容中显示的页数不一定正确),网站客服只以系统显示的页数、文件格式、文档大小作为仲裁依据,平台无法对文档的真实性、完整性、权威性、准确性、专业性及其观点立场做任何保证或承诺,下载前须认真查看,确认无误后再购买,务必慎重购买;若有违法违纪将进行移交司法处理,若涉侵权平台将进行基本处罚并下架。
3、本站所有内容均由用户上传,付费前请自行鉴别,如您付费,意味着您已接受本站规则且自行承担风险,本站不进行额外附加服务,虚拟产品一经售出概不退款(未进行购买下载可退充值款),文档一经付费(服务费)、不意味着购买了该文档的版权,仅供个人/单位学习、研究之用,不得用于商业用途,未经授权,严禁复制、发行、汇编、翻译或者网络传播等,侵权必究。
4、如你看到网页展示的文档有www.zixin.com.cn水印,是因预览和防盗链等技术需要对页面进行转换压缩成图而已,我们并不对上传的文档进行任何编辑或修改,文档下载后都不会有水印标识(原文档上传前个别存留的除外),下载后原文更清晰;试题试卷类文档,如果标题没有明确说明有答案则都视为没有答案,请知晓;PPT和DOC文档可被视为“模板”,允许上传人保留章节、目录结构的情况下删减部份的内容;PDF文档不管是原文档转换或图片扫描而得,本站不作要求视为允许,下载前自行私信或留言给上传者【Stan****Shan】。
5、本文档所展示的图片、画像、字体、音乐的版权可能需版权方额外授权,请谨慎使用;网站提供的党政主题相关内容(国旗、国徽、党徽--等)目的在于配合国家政策宣传,仅限个人学习分享使用,禁止用于任何广告和商用目的。
6、文档遇到问题,请及时私信或留言给本站上传会员【Stan****Shan】,需本站解决可联系【 微信客服】、【 QQ客服】,若有其他问题请点击或扫码反馈【 服务填表】;文档侵犯商业秘密、侵犯著作权、侵犯人身权等,请点击“【 版权申诉】”(推荐),意见反馈和侵权处理邮箱:1219186828@qq.com;也可以拔打客服电话:4008-655-100;投诉/维权电话:4009-655-100。