一略步、關(guān)于命名

1透敌、項(xiàng)目命名

項(xiàng)目名使用小寫英文單詞盯滚，多個(gè)之間使用連字符 "-" 踢械，例如 my-test

2、包命名

2.1魄藕、項(xiàng)目基本包

com.company.{項(xiàng)目英文名（較長(zhǎng)時(shí)適當(dāng)簡(jiǎn)化）}.{模塊名（可選）}
例如：test 包命名為 com.dhsg.test

注意：包命名全為小寫英文字母内列，不可以使用大寫英文字母，不可以使用 "_"背率、"-" 等符號(hào)

2.2话瞧、模塊

• config：配置類
• filter：過(guò)濾器
• common：公共類，定義常量類寝姿，組件
• enums：枚舉類（由于 enum 是 java 的關(guān)鍵字交排，所以使用 enums）
• entity：數(shù)據(jù)庫(kù)相關(guān)的實(shí)體類
• vo：數(shù)據(jù)模型類(參數(shù)模型，數(shù)據(jù)傳輸模型等）
• controller：控制層接口
• service：服務(wù)層接口
• service.impl：服務(wù)層接口實(shí)現(xiàn)
• mapper：數(shù)據(jù)庫(kù)訪問(wèn)層接口
• exception：異常
• util：工具類

3饵筑、類命名

類名首字母大寫埃篓，如果由多個(gè)單詞組成，每個(gè)單詞的首字母都要大寫根资，也即大駝峰式命名法
例如：MyFirstClass.java

public class MyFirstClass{

}

注意：

• 如果類名由多個(gè)單詞組成架专，每個(gè)單詞的首字母都要大寫，包括第一個(gè)單詞
• 接口類名前面要加前綴 "I" 玄帕，例如服務(wù)層的一個(gè)接口類部脚，IHelloService.java

4、變量命名

變量名首字母小寫桨仿，如果由多個(gè)單詞組成睛低，則除了第一個(gè)單詞其他每個(gè)單詞的首字母都要大寫，也即小駝峰式命名法
例如：String myName = "小駝峰式命名法";

5服傍、常量命名

常量名全部大寫钱雷，如果由多個(gè)單詞組成，則每個(gè)單詞直接用下劃線 "_" 分隔
例如：public static final String SYSTEM_COLOR= "RED";

6吹零、方法命名

同變量命名一樣罩抗，使用小駝峰式命名法
例如：

public void myFunction(){

}

7、補(bǔ)充

• 名稱只能由字母灿椅、數(shù)字套蒂、下劃線、$符號(hào)組成
• 不能以數(shù)字開(kāi)頭
• 名稱不能使用 JAVA 中的關(guān)鍵字
• 堅(jiān)決不允許出現(xiàn)中文及拼音命名

二茫蛹、關(guān)于日志

1操刀、統(tǒng)一使用 slf4j 和 logback 完成日志功能

        <!-- slf4j -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>1.7.25</version>
        </dependency>

        <!-- logback -->
        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-core</artifactId>
            <version>1.2.3</version>
        </dependency>
        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
            <version>1.2.3</version>
        </dependency>

2、輸出日志格式

%boldGreen(%date{yyyy-MM-dd HH:mm:ss}) | %highlight(%-5level) | %cyan(%thread) | %magenta(%logger) | %n %msg %n%n

3婴洼、輸出位置

統(tǒng)一將日志文件輸出到項(xiàng)目根目錄下的 log 文件夾

4骨坑、使用示例

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Example {

    private static final Logger logger = LoggerFactory.getLogger(Example.class);

    public void function(){
        
        logger.error("error");
        logger.warn("warn");
        logger.info("info");
        logger.debug("debug");
        logger.trace("trace");

    }

}

三、關(guān)于異常

四、關(guān)于接口

1欢唾、URL 命名

模板：URL = scheme://{domain}/{version}/{endpoint}/[?query][#fragment]

scheme：指底層用的協(xié)議且警，如 http、https礁遣、ftp
domain：服務(wù)器的 IP 地址或者域名斑芜，例如 https://api.example.com
version：版本，例如 https://api.example.com/v1/祟霍，另一種做法是杏头，將版本號(hào)放在 HTTP 頭信息中，但不如放入 URL 方便和直觀浅碾。Github 采用這種做法大州。
endpoint：資源路徑，表示 API 的具體網(wǎng)址垂谢，要為復(fù)數(shù)厦画。舉例來(lái)說(shuō)，有一個(gè) API 提供產(chǎn)品的信息滥朱，還包括各種訂單和用戶的信息根暑，則它的路徑應(yīng)該設(shè)計(jì)成下面這樣。

• https://api.example.com/v1/products
• https://api.example.com/v1/orders
• https://api.example.com/v1/customers

query：為發(fā)送給服務(wù)器的參數(shù)

• ?limit=10：指定返回記錄的數(shù)量徙邻。
• ?offset=10：指定返回記錄的開(kāi)始位置排嫌。
• ?page=2&per_page=100：指定第幾頁(yè)，以及每頁(yè)的記錄數(shù)缰犁。
• ?sortby=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序淳地，以及排序順序。

fragment：錨點(diǎn)帅容，定位到頁(yè)面的資源颇象，錨點(diǎn)為資源 id

補(bǔ)充：

1. 正斜杠分隔符 "/" 必須用來(lái)指示層級(jí)關(guān)系。
2. 應(yīng)該使用連字符 "-" 來(lái)提高 URI 的可讀性并徘。
3. URI 路徑中首選小寫字母遣钳。
4. URI 路徑名詞均為復(fù)數(shù)，使用數(shù)據(jù)庫(kù)表名加后綴 "s" 麦乞。
5. POST 方式避免使用 URI 編碼的參數(shù)蕴茴，盡量保持 URI 的干凈。

2姐直、接口方法命名

根據(jù)該接口的方法類型來(lái)命名方法名倦淀，例如
當(dāng)該接口的 URI 為 "/orders"，則

• GET：getOrders
• POST：postOrders
• PUT：putOrders
• DELETE：deleteOrders

3声畏、接口傳參

根據(jù)該接口的方法類型來(lái)定義撞叽，例如

• GET：

當(dāng)參數(shù)含有層級(jí)關(guān)系的個(gè)時(shí)候，優(yōu)先使用 "/" 分割傳值方式，例如：
https://www.example.com/v1.1/products/{id值}

當(dāng)有可選參數(shù)時(shí)候能扒，使用 ?param1="xxx"&m2="xxx" 方式，例如：
https://www.example.com/v1.1/products?type="xxx"&name="xxx"

補(bǔ)充：
URI 保持簡(jiǎn)約層級(jí)風(fēng)格辫狼，可以混合使用初斑，比如查找某商戶下的產(chǎn)品：
https://www.example.com/v1.1/products?type="xxx"&name="xxx"

• POST：

Json 格式包裝參數(shù)提交，body 攜帶參數(shù)數(shù)據(jù)膨处，例如：

POST  https://www.example.com/v1.1/products

Content-Type: application/json;charset=utf-8
{
"type":"類型1",
"name":"產(chǎn)品名稱1"见秤，
"price": 1000.00
}

• PUT：

Json 格式包裝參數(shù)提交，body 攜帶參數(shù)數(shù)據(jù)真椿，例如鹃答。

PUT https://www.example.com/v1.1/products

Content-Type: application/json;charset=utf-8
{
"type":"類型1",
"name":"產(chǎn)品名稱1"，
"price": 1000.00
}

• DELETE：

使用 "/" 分割傳值方式突硝，例如刪除產(chǎn)品信息：
DELETE https://www.example.com/v1.1/products/{id} #

4测摔、響應(yīng)體格式

在 common 包下新建兩個(gè)類

CommonResult.java

import lombok.Data;

import java.io.Serializable;

/**
 * 統(tǒng)一返回格式
 *
 * @author dhsg
 * @date 2019-10-14
 **/
@Data
public class CommonResult implements Serializable {

    /**
     * 返回狀態(tài)，1表示成功,0表示失敗
     */
    private int status;

    /**
     * 返回信息
     */
    private String message;

    /**
     * 返回實(shí)體數(shù)據(jù)json格式
     */
    private Object data;

    /**
     * 有參構(gòu)造函數(shù)
     *
     * @param status  返回狀態(tài)解恰，1表示成功,0表示失敗
     * @param message 返回信息
     * @param data    返回實(shí)體數(shù)據(jù)json格式
     */
    public CommonResult(int status, String message, Object data) {
        this.status = status;
        this.message = message;
        this.data = data;
    }

    /**
     * 無(wú)參構(gòu)造函數(shù)
     */
    public CommonResult() {
    }

}

CommonResultUtil.java

/**
 * 統(tǒng)一返回工具類
 *
 * @author dhsg
 * @date 2019-10-14
 **/
public class CommonResultUtil {

    /**
     * 成功標(biāo)識(shí)碼
     */
    private static Integer SUCCESS_CODE = 1;

    /**
     * 失敗標(biāo)識(shí)碼
     */
    private static Integer FAIL_CODE = 0;

    /**
     * 返回成功
     */
    public static CommonResult success() {
        return new CommonResult(SUCCESS_CODE, "", null);
    }

    /**
     * 返回成功,并帶上信息和數(shù)據(jù)
     * @param message 返回信息
     * @param data    返回實(shí)體數(shù)據(jù)json格式
     */
    public static CommonResult success(String message, Object data) {
        return new CommonResult(SUCCESS_CODE, message, data);
    }


    /**
     * 返回失敗
     */
    public static CommonResult fail() {
        return new CommonResult(FAIL_CODE, "", null);
    }

    /**
     * 返回失敗,并帶上信息
     * @param message 返回信息
     */
    public static CommonResult fail(String message) {
        return new CommonResult(FAIL_CODE, message, null);
    }

}

使用示例

return CommonResultUtil.success("查詢成功", null);

5锋八、接口注釋

controller 層統(tǒng)一使用 swagger2 組件管理 rest 接口文檔。

五护盈、關(guān)于注釋

1挟纱、類注釋

在每個(gè)類前面必須加上類注釋，注釋模板如下：

/**
* 類的詳細(xì)說(shuō)明
*
* @author  類創(chuàng)建者姓名
* @date    創(chuàng)建日期 YYYY-MM-DD
*/

2腐宋、屬性注釋

在每個(gè)屬性前面必須加上屬性注釋紊服，注釋模板如下：

/** 
* 提示信息 
*/

例如：

/** 
* 系統(tǒng)名稱 
*/
private String systemName = null;

3、方法注釋

在每個(gè)方法前面必須加上方法注釋胸竞，注釋模板如下：

/**
* 方法的詳細(xì)使用說(shuō)明
*
* @param  參數(shù)名 參數(shù)1的使用說(shuō)明
* @return 返回結(jié)果的說(shuō)明
* @throws 異常類型 注明從此類方法中拋出異常的說(shuō)明
*/

例如：

    /**
     * 一個(gè)用于說(shuō)明方法上如何注釋的例子
     * @param param1 參數(shù)1說(shuō)明
     * @param param2 參數(shù)2說(shuō)明
     * @return 返回說(shuō)明
     * @throws Exception 異常說(shuō)明
     */
    public String myFunction(String param1,int param2) throws Exception{
        return null;
    }

4欺嗤、方法內(nèi)注釋

在方法內(nèi)部的代碼上方使用單行或者多行注釋，該注釋根據(jù)實(shí)際情況添加撤师。
例如：

    /**
     * 一個(gè)用于說(shuō)明方法上如何注釋的例子
     * @param param1 參數(shù)1說(shuō)明
     * @param param2 參數(shù)2說(shuō)明
     * @return 返回說(shuō)明
     * @throws Exception 異常說(shuō)明
     */
    public String myFunction(String param1,int param2) throws Exception{

        // 單行注釋剂府，控制臺(tái)打印 param1
        System.out.println(param1);

        // 多行注釋
        // 控制臺(tái)打印 param2
        System.out.println(param2);
        return null;
    }

注意：一定要在代碼的上方寫注釋，不可以追加在代碼尾部剃盾，像下面的寫法是不被允許的

System.out.println(param1); // 控制臺(tái)打印 param1 

5腺占、其他

• 注釋中的說(shuō)明信息使用中文
• 在開(kāi)發(fā)過(guò)程中，常常有一些方法有了新的實(shí)現(xiàn)思路痒谴，但是還沒(méi)完全做好衰伯，于是需要先把舊的方法注釋一下。但是在開(kāi)發(fā)好了之后积蔚，一定要記得還原或者刪除這些不需要的代碼意鲸，保持代碼的整潔。

六、版本控制

1怎顾、拉取原則

• 每日開(kāi)始工作拉取
• 提交之前拉取

2读慎、提交原則

• 提交代碼必須構(gòu)建成功（編譯，打包成功）
• 提交代碼必須完整（不能漏掉一些文件）
• 提交代碼必須忽略到本地臨時(shí)文件（target, logs, .idea, *.iml,dist 等）

3槐雾、提交注釋

• 使用中文填寫注釋
• 注釋要反映本次提交變更的情況夭委，注釋描述添加前綴，前綴如下
  【創(chuàng)建】 通常在項(xiàng)目創(chuàng)建時(shí)使用
  【新增】
  【修改】
  【刪除】
  【修復(fù)-number】 修復(fù) Bug 使用募强，number 是 Bug 編號(hào)
  例如：【新增】 新增一個(gè)控制器類 HelloController.java

七株灸、項(xiàng)目管理

1、使用 maven 做項(xiàng)目管理

2擎值、pom.xml 中新增依賴的時(shí)候慌烧，必須添加注釋

例如：

        <!-- web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

3、所有微服務(wù)工程必須依賴父 maven 工程鸠儿，作為父 maven 工程的子工程

4屹蚊、關(guān)于一些依賴的版本，需要在父 maven 的 pom 文件中指定作為常量引用

5捆交、項(xiàng)目結(jié)構(gòu)

八淑翼、開(kāi)發(fā)環(huán)境

• 開(kāi)發(fā)環(huán)境：JDK 1.8+
• 開(kāi)發(fā)工具：IntelliJ IDEA 2018（安裝 Lombok Plugin）
• 構(gòu)建工具：Maven 3.x
• 代碼管理工具：Git / TortoiseGit
• Spring Cloud 版本：Finchley.RELEASE
• Spring Boot 版本：2.0.3.RELEASE
• Tomcat 版本：8
• slf4j 版本：1.7.25
• logback 版本：1.2.3