Java用 开发规范(1)

参考编写文章：https://zhuanlan.zhihu.com/p/413278453

本篇规范基于阿里巴巴、华为的开发手册，添加了我们团队的开发风格规范，补充了一些细节。感谢前人的经验和付出，让我们可以有机会站在巨人的肩膀上眺望星辰大海。

规范不是为了约束和禁锢大家的创造力，而是为了帮助大家能够在正确的道路上，尽可能的避免踩坑和跑偏。

规范可以让我们无论单枪匹马还是与众人同行的时候都能得心应手。

规范可以让我们在面对日益变态的需求和做代码接盘侠的时候，更优雅从容。

一、编程规范

1.底线原则

• 业务代码编写完成后，至少有且进行三次调用(接口、方法、插件…)，并测试通过
• 尽量减少重复代码，若存在排期结束时间将至，可酌情编写，后续可更新
• 每个函数体，至少有最基础的执行逻辑注释，可在每行代码都进行注释注明，注释不可冗余，本意为理解代码所表达的意义
• 代码的可阅读性，保证代码是容易阅读的，可拆分的进行拆分，不可拆分的可用上述注释协助表达

2.项目命名规范

项目工程包文件夹名：aw_prj_alice_server_public_house

• aw：知道安物
• prj：project 项目
• alice：架构代号
• server：项目属性，eg：service为提供远程调用接口，server提供web api或者其他的
• public_house：项目名称

项目工程包名：

1
2
3

<groupId>com.knowniot.alice</groupId>
<artifactId>aw-application-publichouse</artifactId>
<version>1.0-SNAPSHOT</version>

• groupId：固定为com.knowniot.代号
• artifactId：aw-除了主服务，都使用alice-项目名称，eg：aw-alice-deviceinfo

项目文件夹名称为使用下划线_，而包名是横杠-，注意。

3.注释、FIXME标识

• 大部分函数或方法需要头部注释（接口和接口实现是必须的）

  1 2 3 4 5 6 7 8 9

  由文字介绍，作者，参数，反参组成，格式为下列所示 /** * 这是一个接口、函数、方法的介绍 * * @author 友则 * @param ent 实体参数 * @return */

• 关于//FIXME 与 // 或 ///，//FIXME在idea作为高亮注释来使用，普通注释可用//或///
• 禁止/* */进行多行注释，可采用上述//FIXME 与 // 或 ///多行表达

4.方法参数规范

无论是controller，service，script，handler，mapper 亦或是其他的代码，超出2个参数的话，需要进行换行。

1
2
3
4
5
6
7

@Override
public PageUtility<AccountEventDto> visitorLogList(Long visitor_id,
                                                   Integer pageIndex,
                                                   Integer pageSize,
                                                   String direction,
                                                   String sortName) throws Exception {
}

二、项目规范

统一的application、service 服务类型工程目录结构的基础包结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

src
  |--main
        |--com
             |--knowniot
                       |--alice
                              |--server

这个是基础包，下述简写为 com.knowniot.alice.server

com.knowniot.alice.server
   |--aop                               切片函数
   |--cache                             缓存操作函数
   |--controller                        web api接口函数
   |--http                              http客户端
   |--mq                                消息队列配置
   |--persist                           交换类、dao
      |--dto
      |--entity
      |--mapper
      |--model
      |--repository
   |--script                            脚本函数操作
   |--service                           接口实现服务类
   |--reactor                           异步池函数
   |--task                              定时任务
   |-- Application.java