Java项目代码规范

目标

a. 统⼀业务系统技术语⾔，增强项⽬可继承性和可维护性。
b. 翻阅或接⼿他⼈代码时，只需关注业务逻辑。
c. 配合领域模型实现开发⼈员平滑切换。
d. 配合cogen(基于⾼质量模板的代码⽣成器)提⾼团队代码质量下限

模块划分

根据软件系统架构，划分如下模块：
模块说明：

• doc子模块：存放改动脚本，上线检测清单
• common子模块：被client、base依赖。通常为枚举类，常量，MQ数据载体类
• base⼦模块：被admin和service项⽬依赖，存放两个项⽬共⽤的mapper、mapper xml，service、util、vo等
• client⼦模块：dubbo rpc服务包
• web⼦模块：管理后台⻚⾯
• admin⼦模块：管理后台服务项⽬，为web⼦模块提供http服务
• service⼦模块：存放rpc实现和端上所需http服务
  包说明：
• common
  • config 存放项⽬配置相关代码
  • enums 存放项⽬级别的枚举类
  • utils 存放⼯具类相关代码
  • constants 存放常量相关代码
  • supports 存放项⽬级别的基类
• modules
  具体模块名称
  • service 存放service接⼝，内含impl⼦包
  • mapper 存放mapper接⼝
  • domain 存放模块持久化对象，与数据库相对应
  • vo 存放⻚⾯视图对象
  • constants 存放模块级别的常量
  • enums 存放模块级别的枚举
• mq
  • consumer 存放mq消费者
  • producer 存放mq⽣产者
• job
  • 存放定时任务，eg：xxxJobExecutor
• doc
  • checkList 存放项⽬上线checkList
  • sql 存放项⽬sql脚本
  • releasenote 存放api发版信息
• facade
  • 存放rpc接⼝,eg: ProductFacade

编码规范

编码规范分为异常、注释、版本和各层代码规范。

【推荐】局部变量使⽤基本数据类型
【强制】所有POJO类属性必须使⽤包装类型
【强制】RPC⽅法⼊参和返回值必须使⽤包装类型
【强制】异常⽇志，要打印关键上下⽂参数
【强制】⾮核⼼流程要做容错降级处理
【强制】复杂的业务流程，要包含流程主⼲处理和重要的业务规则，采⽤模板⽅法
【强制】复杂的业务流程，即使没有错误，也要分段打印中间结果，⽅便快速定位出错区间
【强制】rpc服务⽅法升级不要使⽤new后缀，使⽤版本号后缀。
【强制】POJO类中布尔类型变量，都不要以is开头，否则会引起序列化问题。
【强制】RPC服务接⼝以Facade结尾，实现以Impl结尾。
【强制】后台服务接⼝以Service结尾，实现以Impl结尾
【强制】类中⽅法名，要以类名为上下⽂，例如User类中获取⽤⼾名⽅法，getName()⽽不
是getUserName()。Message类中发送消息⽅法，send()⽽不是sendMessage()。
【强制】表中字段名，要以表名为上下⽂，例如Order中订单编号字段，使⽤no⽽不是
order_no。member表中⽤⼾名字段，使⽤name⽽不是member_name。

注释规范

在编写java代码时，必须写好注释，这对于日后代码的可读性、可维护性至关重要。
Java代码的注释，需要遵循以下要求。

1、每个类，必须写好类的文档注释，注释内容要能够讲清楚类的总体功能和设计思想。
每个接口，必须写好接口的文档注释，注释内容要能够讲清楚接口的总体功能和作用。
每一个方法，必须写好方法的文档注释，即使是私有方法，也该如此。如果方法中包含参数、返回值、显式异常抛出，必须在文档注释中写明。如果一个方法是对接口的实现，那么详细的方法文档注释应该写在接口类的方法中，实现类方法应该通过 @see 指引过去特殊引用代码加@code标识。
2、类的属性，必须写好文档注释，说明该属性的含义和用途。
方法的内部实现，需要写好实现注释。衡量标准是将方法中的逻辑实现步骤写清楚，每个逻辑块都必须写有注释。如果类的内部实现只有简单的一两行代码，内部的实现注释可以不写。
注释的语句行不宜过长，可通过换行或者加
标签换下行方式书写显示。

3、对于必须实现，而尚未实现的功能，使用 //TODO 标记注释。
对于需要修正的bug，使用 //FIXME 标记注释。
系统试运行后的代码修改，请在修改代码段的开始注明修改日期、修改人、修改原因，以便他人查看。（虽然配置管理的历史信息中可以比较，但建议这样做，这样更直观）
所有类和方法都必须有注释（接口和实现类同时存在的话，把接口的注释写清楚，service里面的业务逻辑需要加必要的注释。），注释一定要清晰易读。如果类或者方法是从旧框架中迁移过来，必须使用@引用原有旧代码。