# Java开发规范

版本：v1.0

时间：2019-01-30

[TOC]

## 概述

开发流程的规范化有利于保障开发过程的顺利进行，以及减少后期代码维护的成本和风险 。

此规范的目的是指导java开发人员以正确的姿势完成代码开发的全过程，内容包括：开发工具&插件使用，代码编写，数据库脚本维护，单元测试，文档化，代码版本管理和持续集成多个方面。

## 开发规范

### 工具&插件规范

工具&插件的规范定义了集成开发工具和必要的辅助开发插件

- 对于集成开发工具的使用不同开发人员可能存在不同的偏好，而且不同的集成开发工具在功能上可能也差不多，看起来好像没有统一的必要，但是集成开发工具的统一，能够提供一致的编程环境和交流语境，在一定程度上可以减少开发人员之间的沟通成本，避免辅助开发插件功能的不一致性，也有利于后期不同开发人员的维护

- 对于辅助开发插件可分为必要和非必要两种类型，必要辅助开发插件每个开发人员必须安装，并且必须按照指南正确使用，他们是确保代码质量和高维护性的技术手段。而非必要辅助开发插件一般是从某些方面提高开发效率的工具，在不违反开发规范和对团队开发造成不利影响的前提下，开发人员可个性化使用，也鼓励将优秀者向团队推荐，编写指南放置resources目录。本规范只涉及必要辅助开发插件的内容



**集成开发环境**

<u><强制></u> 集成开发环境（IDE）统一使用Intellij IDEA，版本2016及以上

2016及以上版本已完全集成Spring boot Initializer，Maven，Git等众多的辅助开发工具



**代码质量检查**

代码质量检查能够很大程度上保证开发人员写出满足规范要求的代码（优雅，高效，bug少）

由于此规范的代码开发规范是基于阿里巴巴Java开发规约，因此必须安装 “ali代码规约插件”，安装后可手动或实时启动代码规约检查。建议对遵守规约不太自信的朋友，开启实时检查，自信的朋友也请在完成代码编写后手动执行一次。

<u><强制></u> 所有开发人员必须安装 “ali代码规约插件”，并且在commit代码之前必须执行一次代码规约检查，以确保提交到仓库的代码满足规约要求

ali代码规约插件具体安装和使用请参考 《开发工具和插件使用指南》



**代码风格检查**

代码风格检查主要是保证开发人员编写的代码在格式上满足模板的要求，从而保证代码在可读性上语义一致，减少开发人员之间的沟通成本和后续的代码维护成本。

为了与代码规约保持统一，直接使用阿里java代码格式化模板，在Intellij中通过安装CheckStyle插件可以快速导入格式化模板文件。

<u><强制></u> 所有开发人员必须安装checkStyle插件以及阿里格式化模板文件，并且在commit代码之前必须执行一次代码格式化检查，以确保提交到仓库的代码满足格式要求，建议养成良好的习惯，在编码过程中以快捷键方式经常对代码进行format。

CheckStyle插件以及格式化模板具体安装和使用请参考 《开发工具和插件使用指南》



**代码bug检查**

安装Intellij中的Java静态分析工具FindBugs插件，帮助进一步的发现一些隐藏的bug。需要说明的是，FindBugs插件发现的bug有时请仅作为参考，因为它可能会产生误告警。

<u><强制></u> 所有开发人员必须安装FindBugs插件，并且在commit代码之前必须执行一次检查。

FindBugs插件具体安装和使用请参考 《开发工具和插件使用指南》



**代码安全性检查**

代码安全性对于开发人员来说可能是比较容易忽视的问题，在国际项目中，代码的安全性审计比较严格。

FindSecurityBugs是FindBugs的插件，通过一系列的规则发现代码中的Java安全漏洞。

<u><强制></u> 所有开发人员在安装FindBugs后，请确保FindSecurityBugs开启。

FindSecurityBugs插件具体安装和使用请参考 《开发工具和插件使用指南》



**文档化**

Java代码的文档化，采用javaDoc的标准进行编写，最终将由持续集成工具在项目和产品的doc目录生成完整的javaDoc文档

区分为RESTful接口文档（controler层）和一般Java代码文档

- Java代码文档

  <u><强制></u> Intellij集成javaDoc工具，导入文档模板后，根据模板编写即可，具体安装和使用请参考 《开发工具和插件使用指南》

- RESTful接口文档

  Swagger是一个比较不错的文档插件，但Swagger对代码的侵入性较强，且有单独的语法，存在一定学习过程，因此选择Apiggs插件，Apiggs插件直接使用javaDoc的语法，不存在任何多余的学习。

  <u><强制></u> Intellij集成Apiggs插件工具，具体安装和使用请参考 《开发工具和插件使用指南》



**版本管理**

使用git进行版本管理

<u><强制></u> 安装git，在Intellij集成git插件中完成配置，具体安装和使用请参考 《开发工具和插件使用指南》

git的图形化管理工具，建议直接使用Intellij自带git插件工具，或者使用Tortoisegit



### 代码开发规范

<强制> Java代码开发规范具体细则参考《阿里巴巴Java开发手册》，并认真学习，重点关注以下章节：

```
编程规约
 - 命名风格
 - 常量定义
 - 代码格式
 - OOP规约
 - 集合处理
 - 控制语句
 - 注释规约
 异常日志
 安全规约
```

### 数据库脚本规范

此项针对开发经理和设计师，数据库脚本必须纳入版本管理，并在项目或者产品script目录进行维护

具体参考《数据库脚本管理规范》

### 测试规范

对于Java开发人员 **当前阶段** 只关注单元测试，并编写自动化测试案例，测试工具采用testNg + mockito

<u><强制></u> 测试规范具体要求请参考《java单元测试规范》文档

建议先学习resources里面的《有效的单元测试》一文，对测试能够有更好的理解

### 文档规范

<u><强制></u> 如何编写有效的Java代码文档请参考《阿里巴巴Java开发手册》的注释规约部分

补充说明几点：

- 必须在集成工具中导入标准文档模板，并按照模板编写javaDoc
- 复杂的业务代码的关键流程分支处，详细描述处理原因和方法
- 核心业务代码，交互接口，公共模块必须写javaDoc
- 文档描述要准确，清晰，杜绝胡说八道

### 版本管理规范

使用git进行版本管理（包括代码和文档），并采用gitlab flow模式实现分支管理

<u><强制></u> git和gitlab flow具体使用和要求，请参考《git开发流程规范》



