JAVA开发手册强制精简版本.docx_javaapi中文手册下载资源-CSDN文库

需积分: 9 29 浏览量 2020-05-15 23:48:00 上传评论收藏 170KB DOCX 举报

JAVA 代码规范是Java开发中不可或缺的一部分，它旨在提高代码的可读性、可维护性和团队协作效率。本手册基于2020年的阿里开发手册进行了精简，重点关注强制性的编程规约、安全规约以及MySQL数据库的相关规定。在命名风格方面，遵循以下几个要点： 1. 代码中的命名不应以下划线或美元符号开始或结束，这是为了保持命名的一致性和清晰度。 2. 类名遵循UpperCamelCase风格，但有一些例外，如DO、BO、DTO、VO、AO、PO、UID等，这些通常用于特定的领域模型或数据传输对象，不需严格遵循此规则。 3. 方法名、参数名、成员变量和局部变量都应使用lowerCamelCase风格，这种风格使得代码在阅读时更加流畅。 4. 常量的命名应全大写，并用下划线分隔单词，确保其具有清晰的语义，即使这意味着名称可能较长。 5. 抽象类的命名一般以Abstract或Base开头，异常类以Exception结尾，而测试类的命名以待测试类的名字开始，以Test结尾。 6. 数组的表示方式是类型紧跟着中括号，例如`int[] array`，这样的表示方式直观且易于理解。 7. POJO类中的布尔变量不建议加is前缀，以免引起某些框架的序列化错误。 8. 包名使用小写字母，点分隔的每个部分都应有清晰的英文单词，包名通常是单数形式，但类名如有复数含义，可以使用复数形式。 9. 避免在子类、父类成员变量或不同代码块的局部变量间使用相同的命名，这会降低代码的可读性。 10. 避免使用不规范的缩写，确保代码的可理解性。在常量定义上，也有明确的规定： 1. 不允许直接在代码中出现未经定义的“魔法值”，这可能导致代码的不可预测性和维护困难。 2. 当使用long或Long类型的数值时，数值后应使用大写的L，如123L，以区分于数字123和小写字母l。此外，对于安全规约和MySQL数据库的部分，虽然这部分内容未在提供的文字中详细展开，但通常包括对SQL注入的防护、密码加密存储、数据访问控制、事务处理的正确性等方面。例如，使用预编译的SQL语句防止SQL注入，合理设置数据库权限，避免硬编码数据库连接信息，以及确保事务的ACID属性等。 Java开发手册强调了良好的编程习惯和一致性，这对于提升代码质量、减少bug、增强团队合作效率具有重要意义。开发者应遵循这些规约，以创建出更健壮、易读、易维护的Java应用。

资源推荐

资源详情

资源评论

JAVA 代码规范

Java 开发手册
1/57
目录
JAVA 代码规范....................................................................................................................................... 1
一、 编程规约....................................................................................................................................... 4
(一) 命名风格.................................................................................................................................. 4
1. 【强制】代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。............4
3. 【强制】类名使用 UpperCamelCase 风格，但以下情形例外：DO / BO / DTO / VO / AO / PO / UID 
等。............................................................................................................................................... 4
4. 【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格。.......................4
5. 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。.........4
6. 【强制】抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它
要测试的类的名称开始，以 Test 结尾。...........................................................................................4
7. 【强制】类型与中括号紧挨相连来表示数组。...............................................................................4
8. 【强制】POJO 类中的任何布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列化错误。
..................................................................................................................................................... 4
9. 【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形
式，但是类名如果有复数含义，类名可以使用复数形式。..................................................................5
10. 【强制】避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名， 使
可读性降低。................................................................................................................................. 5
11. 【强制】杜绝完全不规范的缩写，避免望文不知义。...................................................................5
(二) 常量定义.................................................................................................................................. 5
1. 【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。...................................5
2. 【强制】在 long 或者 Long 赋值时，数值后使用大写的 L，不能是小写的 l，小写容易跟数字混淆，造
成误解。........................................................................................................................................ 5
(三) 注释规约.................................................................................................................................. 5
1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/**内容*/格式，不得使用.........5
// xxx 方式。.................................................................................................................................. 5
2. 【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、异常说
明外，还必须指出该方法做什么事情，实现什么功能。.....................................................................6
3. 【强制】所有的类都必须添加创建者和创建日期。........................................................................6
4. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* *
/注释，注意与代码对齐。...............................................................................................................6
5. 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。..........................................6
(四) 其它........................................................................................................................................ 6
1. 【强制】在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。......................6
2. 【强制】避免用 Apache Beanutils 进行属性的 copy。...................................................................6
二、异常日志........................................................................................................................................ 7
(一) 错误码..................................................................................................................................... 7
1. 【强制】错误码的制定原则：快速溯源、简单易记、沟通标准化。.................................................7
(二) 异常处理.................................................................................................................................. 7
三、安全规约........................................................................................................................................ 7
1. 【强制】隶属于用户个人的页面或者功能必须进行权限控制校验。.................................................7
2. 【强制】用户敏感数据禁止直接展示，必须对展示数据进行脱敏。.................................................7
4. 【强制】用户请求传入的任何参数必须做有效性验证。.................................................................7
5. 【强制】禁止向 HTML 页面输出未经安全过滤或未正确转义的用户数据。......................................7
7. 【强制】URL 外部重定向传入的目标地址必须执行白名单过滤。....................................................7
8. 【强制】在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放的机制，如
数量限制、疲劳度控制、验证码校验，避免被滥刷而导致资损。........................................................8
四、MySQL 数据库................................................................................................................................ 9

Java 开发手册
2/57
(一) 建表规约.................................................................................................................................. 9
1. 【强制】表达是与否概念的字段，必须使用 is_xxx 的方式命名，数据类型是 unsigned tinyint...........9
（1 表示是，0 表示否）。..............................................................................................................9
3. 【强制】表名不使用复数名词。...................................................................................................9
4. 【强制】禁用保留字，如 desc、range、match、delayed 等，请参考 MySQL 官方保留字。.............9
5. 【强制】主键索引名为 pk_字段名；唯一索引名为 uk_字段名；普通索引名则为 idx_字段名。..........9
6. 【强制】小数类型为 decimal，禁止使用 float 和 double。.............................................................9
7. 【强制】如果存储的字符串长度几乎相等，使用 char 定长字符串类型。........................................9
8. 【强制】varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长度大于此
值，定义字段类型为 text，独立出来一张表，用主键来对应，避免影响其它字段索引效率。................9
9. 【强制】表必备三字段：id, gmt_create, gmt_modified。...............................................................9
(二) 索引规约................................................................................................................................ 10
1. 【强制】业务上具有唯一特性的字段，即使是组合字段，也必须建成唯一索引。...........................10
2. 【强制】超过三个表禁止 join。需要 join 的字段，数据类型保持绝对一致；多表关联查询时， 保证被
关联的字段需要有索引。...............................................................................................................10
3. 【强制】在 varchar 字段上建立索引时，必须指定索引长度，没必要对全字段建立索引，根据实际文
本区分度决定索引长度。...............................................................................................................10
4. 【强制】页面搜索严禁左模糊或者全模糊，如果需要请走搜索引擎来解决。.................................11
(三) SQL 语句...............................................................................................................................11
1. 【强制】不要使用 count(列名)或 count(常量)来替代 count(*)，count(*)是 SQL92 定义的标准统计行
数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。....................................................................11
2. 【强制】count(distinct col) 计算该列除 NULL 之外的不重复行数，注意 count(distinct col1, col2) 如果
其中一列全为 NULL，那么即使另一列有不同的值，也返回为 0。....................................................11
3. 【强制】当某一列的值全是 NULL 时，count(col)的返回结果为 0，但 sum(col)的返回结果为 NULL，
因此使用 sum()时需注意 NPE 问题。..............................................................................................11
5. 【强制】代码中写分页查询逻辑时，若 count 为 0 应直接返回，避免执行后面的分页语句。.........11
6. 【强制】不得使用外键与级联，一切外键概念必须在应用层解决。...............................................11
7. 【强制】禁止使用存储过程，存储过程难以调试和扩展，更没有移植性。.....................................11
8. 【强制】数据订正（特别是删除或修改记录操作）时，要先 select，避免出现误删除，确认无误才能
执行更新语句。............................................................................................................................ 11
9. 【强制】对于数据库中表记录的查询和变更，只要涉及多个表，都需要在列名前加表的别名（或表
名）进行限定。............................................................................................................................ 12
10. 【推荐】SQL 语句中表的别名前加 as，并且以 t1、t2、t3、...的顺序依次命名。.......................12
11. 【推荐】in 操作能避免则避免，若实在避免不了，需要仔细评估 in 后边的集合元素数量，控制在 1
000 个之内。............................................................................................................................... 12
12. 【参考】因国际化需要，所有的字符存储与表示，均采用 utf8 字符集，那么字符计数方法需要注意。
................................................................................................................................................... 12
无事务且不触发 trigger，有可能造成事故，故不建议在开发代码中使用此语句。...............................12
(四) ORM 映射.............................................................................................................................. 12
2. 【强制】POJO 类的布尔属性不能加 is，而数据库字段必须加 is_，要求在 resultMap 中进行字段与属
性之间的映射。............................................................................................................................ 12
3. 【强制】不要用 resultClass 当返回参数，即使所有类属性名与数据库字段一一对应，也需要定义<re
sultMap>；反过来，每一个表也必然有一个<resultMap>与之对应。................................................13
7. 【强制】更新数据表记录时，必须同时更新记录对应的 gmt_modified 字段值为当前时间。............13
五、工程结构...................................................................................................................................... 13
(一) 应用分层................................................................................................................................ 13
1. 【推荐】图中默认上层依赖于下层，箭头关系表示可直接依赖，如：开放接口层可以依赖于..........13
3. 【参考】分层领域模型规约：....................................................................................................15
(二) 二方库依赖............................................................................................................................ 15
2. 【强制】二方库版本号命名方式：主版本号.次版本号.修订号.......................................................15
3. 【强制】线上应用不要依赖 SNAPSHOT 版本（安全包除外）；正式发布的类库必须先去中央仓库进
行查证，使 RELEASE 版本号有延续性，且版本号不允许覆盖升级。.................................................15
4. 【强制】二方库的新增或升级，保持除功能点之外的其它 jar 包仲裁结果不变。如果有改变， 必须明

Java 开发手册
3/57
确评估和验证。............................................................................................................................ 15
5. 【强制】二方库里可以定义枚举类型，参数可以使用枚举类型，但是接口返回值不允许使用枚举类型
或者包含枚举类型的 POJO 对象。..................................................................................................15
6. 【强制】依赖于一个二方库群时，必须定义一个统一的版本变量，避免版本号不一致。.................16
六、设计规约...................................................................................................................................... 17
1. 【强制】存储方案和底层数据结构的设计获得评审一致通过，并沉淀成为文档。...........................17
2. 【强制】在需求分析阶段，如果与系统交互的 User 超过一类并且相关的 User Case 超过 5 个， 使用
用例图来表达更加清晰的结构化需求。...........................................................................................17
3. 【强制】如果某个业务对象的状态超过 3 个，使用状态图来表达并且明确状态变化的各个触发条件。
................................................................................................................................................... 17
4. 【强制】如果系统中某个功能的调用链路上的涉及对象超过 3 个，使用时序图来表达并且明确各调用
环节的输入与输出。..................................................................................................................... 17
5. 【强制】如果系统中模型类超过 5 个，并且存在复杂的依赖关系，使用类图来表达并且明确类之间的
关系。......................................................................................................................................... 17
6. 【强制】如果系统中超过 2 个对象之间存在协作关系，并且需要表示复杂的处理流程，使用活动图来
表示。......................................................................................................................................... 17
附 2：专有名词解释............................................................................................................................ 17
1. CAS（Compare And Swap）: 数据库表一一对应的 POJO 类。解决多线程并行情况下使用锁造成性能
损耗的一种机制，这是硬件实现的原子操作。CAS 操作包含三个操作数：内存位置、预期原值和新值。
如果内存位置的值与预期原值相匹配，那么处理器会自动将该位置值更新为新值。否则，处理器不做任
何操作。...................................................................................................................................... 17
5.  （AbstractQueuedSynchronizer）: 利用先进先出队列实现的底层同步工具类，它是很多上层同步实现
类的基础，比如：ReentrantLock、CountDownLatch、Semaphore 等，它们通过继承 AQS 实现其模版方
法，然后将 AQS 子类作为同步组件的内部类，通常命名为 Sync。...................................................18
10.  （Out Of Memory）: 源于 java.lang.OutOfMemoryError，当 JVM 没有足够的内存来为对象分配空间
并且垃圾回收器也无法回收空间时，系统出现的严重状况。.............................................................18
11. : 本工程内部子项目模块依赖的库（jar 包）。...........................................................................18
12. : 公司内部发布到中央仓库，可供公司内部其它应用依赖的库（jar 包）。...................................18
13. : 公司之外的开源库（jar 包）。...............................................................................................18
附 3：错误码列表............................................................................................................................... 19