其他分享
首页 > 其他分享> > 代码规范V1.0

代码规范V1.0

作者:互联网

目录

配置

禁用

强制

接口和实现类

各层命名规约

空格、换行、注释

OOP规约

注释规约

安全规约

MYSQL

索引规约

应用分层

设计规约


配置

文件格式全部设置为utf-8

禁用

代码中拼音命名

完全不规范的缩写

无意义命名

任何魔法值 (请定义常量或者Enum)

1)java.sql.Date 2)java.sql.Time 3) java.sql.Timestamp

在foreach循环里进行元素的remove/add

强制

类名使用UpperCamelCase(但以下情形例外:DO / BO / DTO / VO / AO / PO / UID)

方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase

常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚,不要嫌名字长。

抽象类命名使用Abstract或Base开头

异常类命名使用Exception 结尾

测试类 命名以它要测试的类的名称开始,以Test结尾

定义整形数组 int[] arrayDemo

POJO类中的任何布尔类型的变量,都不要加is前缀,否则部分框架解析会引起序列 化错误

包名统一使用小写,点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用 单数形式,但是类名如果有复数含义,类名可以使用复数形式

接口和实现类

public interface ICustomService {

}
public class CustomServiceImpl implements ICustomService {
  // 类内方法定义的顺序依次是:公有方法或保护方法 > 私有方法 > getter / setter 方法。 
}
public interface ICustomDao {

}
public class CustomDaoImpl implements ICustomDao {

}

各层命名规约

A) Service/DAO 层方法命名规约

1) 获取单个对象的方法用 get 做前缀

 2) 获取多个对象的方法用 list 做前缀,复数结尾,如:listObjects

 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/VO的统称,禁止命名成 xxxPOJO

Long类型用L结尾:

Long id = 1L;

缓存相关常量放在类

public final class CacheConsts {

}

系统配置相关常量放在类 ConfigConsts

空格、换行、注释

// 这是示例注释,请注意在双斜线之后有一个空格 
if (xxx == "xxx") {

  // 代码

} else if (bbb=="xxxxx") {

  // 代码

} else {

  // 代码

}

for (DevTableColumnEntity devTableColumnEntity : newList) {
            
}
int state = xxx ? xx : xxxx;
public void method(String args1, int args2, boolean args3) {

}

OOP规约

所有的覆写方法,必须加@Override注解

相同参数类型,相同业务含义,才可以使用 Java的可变参数,避免使用 Object

接口过时必须加@Deprecated注解,并清晰地说明采用的新接口或者新服务

所有整型包装类对象之间值的比较,全部使用equals方法比较

所有的 POJO类属性必须使用包装数据类型。 不要设定任何属性默认值

RPC 方法的返回值和参数必须使用包装数据类型

构造方法里面禁止加入任何业务逻辑,如果有初始化逻辑,请放在 init方法

POJO类必须写toString方法

类成员与方法访问控制从严:

1) 如果不允许外部直接通过 new来创建对象,那么构造方法必须是 private。  

2) 工具类不允许有 public或default 构造方法。  

3) 类非static 成员变量并且与子类共享,必须是 protected。  

4) 类非static 成员变量并且仅在本类使用,必须是private。  

5) 类static 成员变量如果仅在本类使用,必须是 private。  

6) 若是static 成员变量,考虑是否为final。  

7) 类成员方法只供类内部调用,必须是 private。  

8) 类成员方法只对继承类公开,那么限制为 protected

注释规约

类、类属性、类方法的注释必须使用Javadoc规范,使用/**内容*/格式,不得使用 // xxx方式

所有的抽象方法(包括接口中的方法)必须要用 Javadoc注释、除了返回值、参数、 异常说明外,还必须指出该方法做什么事情,实现什么功能

所有的类都必须添加创建者和创建日期

所有的枚举类型字段必须要有注释,说明每个数据项的用途。 

代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑 等的修改

谨慎注释掉代码。在上方详细说明,而不是简单地注释掉。如果无用,则删除。 说明:代码被注释掉有两种可能性:1)后续会恢复此段代码逻辑。2)永久不用。前者如果没有备注信息, 难以知晓注释动机。后者建议直接删掉即可,假如需要查阅历史代码,登录代码仓库即可。 

安全规约

隶属于用户个人的页面或者功能必须进行权限控制校验

用户敏感数据禁止直接展示,必须对展示数据进行脱敏

用户输入的 SQL参数严格使用参数绑定或者 METADATA字段值限定,防止 SQL注入, 禁止字符串拼接 SQL访问数据库

用户请求传入的任何参数必须做有效性验证

⚫ page size 过大导致内存溢出 ⚫ 恶意order by导致数据库慢查询 ⚫ 缓存击穿 ⚫ SSRF ⚫ 任意重定向 ⚫ SQL 注入,Shell注入,反序列化注入 ⚫ 正则输入源串拒绝服务 ReDoS

URL外部重定向传入的目标地址必须执行白名单过滤

在使用平台资源,譬如短信、邮件、电话、下单、支付,必须实现正确的防重放的机 制,如数量限制、疲劳度控制、验证码校验,避免被滥刷而导致资损

发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过 滤等风控策略

MYSQL

数据库名、表名、 字段名,都不允许出现任何大写字母

表名不使用复数名

禁用保留字,如desc、range、match、delayed等,请参考MySQL官方保留字

主键索引名为 pk_字段名;唯一索引名为 uk_字段名;普通索引名则为 idx_字段名

小数类型为decimal,禁止使用float和double

varchar是可变长字符串,不预先分配存储空间,长度不要超过5000,如果存储长度 大于此值,定义字段类型为 text,独立出来一张表,用主键来对应,避免影响其它字段索引效 率

表必备三字段:id ( bigint unsigned), gmt_create(datetime ), gmt_modified(datetime )

表的命名最好是遵循“业务名称_表的作用”。 正例:alipay_task / force_project / trade_config 

库名与应用名称尽量一致

字段允许适当冗余,以提高查询性能,但必须考虑数据一致。冗余字段应遵循:  1) 不是频繁修改的字段。  2) 不是唯一索引的字段。     3) 不是varchar 超长字段,更不能是text 字段。     正例:各业务线经常冗余存储商品名称

单表行数超过500万行或者单表容量超过2GB,才推荐进行分库分表。 说明:如果预计三年后的数据量根本达不到这个级别,请不要在创建表时就分库分

索引规约

业务上具有唯一特性的字段,即使是组合字段,也必须建成唯一索引

超过三个表禁止 join。需要 join的字段,数据类型保持绝对一致;多表关联查询时, 保证被关联的字段需要有索引

在 varchar字段上建立索引时,必须指定索引长度,没必要对全字段建立索引,根据 实际文本区分度决定索引长度, 索引的长度与区分度是一对矛盾体,一般对字符串类型数据,长度为 20 的索引,区分度会高达 90% 以上,可以使用 count(distinct left(列名, 索引长度))/count(*)的区分度来确定

 如果有order by的场景,请注意利用索引的有序性。order by 最后的字段是组合索 引的一部分,并且放在索引组合顺序的最后,避免出现file_sort的情况,影响查询性能。 正例:where a=? and b=? order by c; 索引:a_b_c 

不要使用count(列名)或count(常量)来替代count(*)

不得使用外键与级联,一切外键概念必须在应用层解决

in操作能避免则避免,若实在避免不了,需要仔细评估 in后边的集合元素数量,控 制在1000个之内

因国际化需要,所有的字符存储与表示,均采用 utf8字符集,那么字符计数方法需 要注意。 说明:       SELECT LENGTH("轻松工作"); 返回为 12       SELECT CHARACTER_LENGTH("轻松工作"); 返回为4       如果需要存储表情,那么选择utf8mb4 来进行存储,注意它与 utf8 编码的区

应用分层

设计规约

  1. 存储方案和底层数据结构的设计获得评审一致通过,并沉淀成为文档
  2. 在需求分析阶段,如果与系统交互的User超过一类并且相关的User Case超过5个, 使用用例图来表达更加清晰的结构化需求
  3. 如果某个业务对象的状态超过3个,使用状态图来表达并且明确状态变化的各个触发 条件
  4. 如果系统中某个功能的调用链路上的涉及对象超过3个,使用时序图来表达并且明确 各调用环节的输入与输出。 
  5. 如果系统中模型类超过5个,并且存在复杂的依赖关系,使用类图来表达并且明确类 之间的关系
  6. 如果系统中超过2个对象之间存在协作关系,并且需要表示复杂的处理流程,使用活 动图来表示
  7. 【推荐】系统架构设计时明确以下目标: 
    ⚫ 确定系统边界。确定系统在技术层面上的做与不做。 
    ⚫ 确定系统内模块之间的关系。确定模块之间的依赖关系及模块的宏观输入与输出。 
    ⚫ 确定指导后续设计与演化的原则。使后续的子系统或模块设计在一个既定的框架内和技术方向上继 续演化。 
  8. 推荐】需求分析与系统设计在考虑主干功能的同时,需要充分评估异常流程与业务边界。 反例:用户在淘宝付款过程中,银行扣款成功,发送给用户扣款成功短信,但是支付宝入款时由于断网演 练产生异常,淘宝订单页面依然显示未付款,导致用户投诉。 
  9. 推荐】类在设计与实现时要符合单一原则。 说明:单一原则最易理解却是最难实现的一条规则,随着系统演进,很多时候,忘记了类设计的初衷。 
  10. 推荐】谨慎使用继承的方式来进行扩展,优先使用聚合/组合的方式来实现。 说明:不得已使用继承的话,必须符合里氏代换原则,此原则说父类能够出现的地方子类一定能够出现, 比如,“把钱交出来”,钱的子类美元、欧元、人民币等都可以出现。 
  11. 推荐】系统设计阶段,根据依赖倒置原则,尽量依赖抽象类与接口,有利于扩展与维护。 说明:低层次模块依赖于高层次模块的抽象,方便系统间的解耦。 
  12. 推荐】系统设计阶段,注意对扩展开放,对修改闭合。 说明:极端情况下,交付的代码是不可修改的,同一业务域内的需求变化,通过模块或类的扩展来实现。 
  13. 推荐】系统设计阶段,共性业务或公共行为抽取出来公共模块、公共配置、公共类、公共方 法等,在系统中不出现重复代码的情况。 说明:随着代码的重复次数不断增加,维护成本指数级上升。 
  14. 推荐】避免如下误解:敏捷开发 = 讲故事 + 编码 + 发布。 说明:敏捷开发是快速交付迭代可用的系统,省略多余的设计方案,摒弃传统的审批流程,但核心关键点上 的必要设计和文档沉淀是需要的。  反例:某团队为了业务快速发展,敏捷成了产品经理催进度的借口,系统中均是勉强能运行但像面条一样 的代码,可维护性和可扩展性极差,一年之后,不得不进行大规模重构,得不偿失。 
  15. 参考】设计文档的作用是明确需求、理顺逻辑、后期维护,次要目的用于指导编码。 说明:避免为了设计而设计,系统设计文档有助于后期的系统维护和重构,所以设计结果需要进行分类归 档保存。 
  16. 参考】可扩展性的本质是找到系统的变化点,并隔离变化点。 说明:世间众多设计模式其实就是一种设计模式即隔离变化点的模式。 正例:极致扩展性的标志,就是需求的新增,不会在原有代码交付物上进行任何形式的修改。 
  17. 参考】设计的本质就是识别和表达系统难点。 说明:识别和表达完全是两回事,很多人错误地认为识别到系统难点在哪里,表达只是自然而然的事情, 但是大家在设计评审中经常出现语焉不详,甚至是词不达意的情况。准确地表达系统难点需要具备如下能力: 表达规则和表达工具的熟练性。抽象思维和总结能力的局限性。基础知识体系的完备性。深入浅出的 生动表达力。 
  18. 参考】代码即文档的观点是错误的,清晰的代码只是文档的某个片断,而不是全部。 说明:代码的深度调用,模块层面上的依赖关系网,业务场景逻辑,非功能性需求等问题是需要相应的文 档来完整地呈现的。 
  19. 参考】在做无障碍产品设计时,需要考虑到: 

⚫ 所有可交互的控件元素必须能被 tab 键聚焦,并且焦点顺序需符合自然操作逻辑。 
⚫ 用于登陆校验和请求拦截的验证码均需提供图形验证以外的其它方式。 ⚫ 自定义的控件类型需明确交互方式。 
正例:用户登陆场景中,输入框的按钮都需要考虑 tab键聚焦,符合自然逻辑的操作顺序如下,“输入用 户名,输入密码,输入验证码,点击登录”,其中验证码实现语音验证方式。如果有自定义标签实现的控 件设置控件类型可使用 role 属性。   
 
 

标签:索引,规约,代码,规范,V1.0,必须,使用,方法
来源: https://blog.csdn.net/a8590455/article/details/122700008