一、约定规范

1.1、git 提交约定规范

  • 约定的 type ```shell

    定义的提交类型

    提交：主要 type

    feat: 增加新功能 fix: 修复bug

提交：特殊 type

docs: 只改动了文档相关的内容 style: 不影响代码含义的改动，例如去掉空格、改变缩进、增删分号 build: 构造工具的或者外部依赖的改动，例如webpack，npm refactor: 代码重构时使用 revert: 执行git revert打印的message

提交：暂不使用type

test: 添加测试或者修改现有测试 perf: 提高性能的改动 ci: 与CI（持续集成服务）有关的改动 chore: 不修改src或者test的其余修改，例如构建过程或辅助工具的变动

  2. - 提交的格式

(): // 空一行

// 空一行

scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。

subject是 commit 目的的简短描述，不超过50个字符。

  3. <a name="tQ6u0"></a>
  4. #### 1.2、代码注释
  6. - 类注释

/**

  • @description:
  • @author: ${USER}
  • @date: ${DATE} */ ```

1.3、接口标准

  • 统一响应格式

二、Java 编写规范

  1. Java 文件格式
    文件格式必须是 UTF-8，无 BOM 格式
    文件回车换行符必须是 Unix 风格
    每个文件结尾必须有一个空白行
    行尾空白内容应该被 trim 掉
    每个文件开头必须写上项目的标准 LICENSE 注释，如下：
  1. /**
  2.  * Copyright 2013-2014 Guoqiang Chen, Shanghai, China. All rights reserved.
  3.  *
  4.  *   Author: Guoqiang Chen
  5.  *    Email: subchen@gmail.com
  6.  *   WebURL: https://github.com/subchen
  7.  *
  8.  * Licensed under the Apache License, Version 2.0 (the "License");
  9.  * you may not use this file except in compliance with the License.
  10.  * You may obtain a copy of the License at
  11.  *
  12.  *   http://www.apache.org/licenses/LICENSE-2.0
  13.  *
  14.  * Unless required by applicable law or agreed to in writing, software
  15.  * distributed under the License is distributed on an "AS IS" BASIS,
  16.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17.  * See the License for the specific language governing permissions and
  18.  * limitations under the License.
  19.  */


代码必须是格式化的，请使用统一的 Eclipse 的代码格式文件：jetbrick-eclipse-formatter.xml

不想被自动格式化的代码请用 @formatter 包裹，如下： 

  1. //@formatter:off
  2. private static final String[] DATE_PATTERNS = new String[] {
  3.     "yyyy-MM-dd HH:mm:ss.SSS",
  4.     "yyyy-MM-dd HH:mm:ss",
  5.     "yyyy-MM-dd",
  6.     "HH:mm:ss"
  7. };
  8. //@formatter:on


Java 文件必须是可编译的，不应该有任何的 warning 存在

  1. 包名
    包名必须是全部小写的，最好用一个单词表示，尽量不要以复数结尾
    包名必须以 jetbrick. 开头
    接口或者抽象类的多种实现，推荐以 support, spi 等命名
  2. 类名
    类名必须首字母大写，驼峰命名法： 如 UserInfo，ClassUtils
    类名尽量不要缩写，如果缩写，必须为特别常用的缩写
    接口的命名不要以 I 开头
    抽象类推荐以 Abstract 开头
    接口的默认实现推荐以 Default 开头或者 Impl 结尾
    每个 Class 都需要标注 @auther, @since
    每个 Class 都应该有简短的注释
  3. Imports
    Imports 间不要有空行
    超过 3 个相同包下面的 Class 需要使用 .* 代替
    不要使用 import static, 除了 JUnit / TestNG 的 assertXXX 方法
  4. 方法
    方法名称应该采用首字母小写，驼峰命名法： 如 getUser，lookupClass
    对于一个 public 的方法，都应该对参数进行基本的校验，比如 null 检测
    对外开放 API 的 public 方法都需要标注 @since
    每个 public 方法都应该有简短的注释
    推荐每个 public 的方法的参数和返回值都加上 @Nullable 或者 @NotNull 标注
  5. 常量
    常量必须是全大写，并用 _ 分隔，如 MAX_INTEGER
    常量必须是 static final
  6. 变量
    变量名称必须首字母小写，驼峰命名法
    变量名尽量使用缩写，以简短为主
    不要用拼音，要用英文表示
    如果是集合或数组，用复数名词，或者添加 List, Map 等后缀
  7. 注释
    注释必须和代码保持一致，中文/英文均可
    注释中的第一个句子要以（英文）句号、问号或者感叹号结束。 javadoc 工具会将注释中的第一个句子放在方法汇总表和索引中。
    如果注释中有超过一个段落，用
    标签分隔
    如果注释中有多个章节，用
  8. 异常
    异常类名必须以 Exception 结尾
    所有自定义异常都必须继承自 RuntimeException
    方法尽量不要抛出非 RuntimeException 异常
    异常应该和主要的 Class 放在一起，而不是所有的异常类放在一个包下面
    异常描述应该使用英文句子，尽量不要用中文。
    被 catch 住的 Exception，必须要处理，或者重新抛出
  9. 日志
    日志框架使用 slf4j
    实例不多的对象类，不要使用 static 声明 log
    尽量使用 debug 而不是 info 级别
    启动时候需要输出的重要日志，请用 info 级别
    被 catch 住的 Exception，应该被打印出来 log.error(e)
  10. 单元测试
    单元测试框架用 JUnit
    单元测试覆盖率工具用 Jacoco
    Mock 框架使用 Mockito
    尽可能为每个方法提供单元测试
    覆盖率应该不低于 50%

三、部署环境规范

3.1、环境命名规范

  1. pro（Production environment）：生产环境，面向外部用户的环境，正式环境，连接上互联网即可访问。
  2. sit(System Integration Test ): 系统集成测试，开发人员自己测试流程是否走通。
  3. uat(User Acceptance Test environment): 用户验收测试环境，用于生产环境下的软件测试者测试使用。
  4. test: 测试环境，外部用户无法访问，专门给测试人员使用的，版本相对稳定。
  5. pre ：灰度环境，外部用户可以访问，但是服务器配置相对低，其它和生产一样，外部用户可以访问，版本发布初期，正式版本发布前。
  6. dev （Development environment） ： 开发环境，外部用户无法访问，开发人员使用，版本变动很大。
  7. fat (Feature Acceptance Test environment) : 功能验收测试环境，用于软件测试者测试使用

参考