在我的工作中，我從零開始搭建了不少軟件項(xiàng)目，其中包含了基礎(chǔ)代碼框架和持續(xù)集成基礎(chǔ)設(shè)施等，這些內(nèi)容在敏捷開發(fā)中通常被稱為“第0個(gè)迭代”要做的事情。但是，當(dāng)項(xiàng)目運(yùn)行了一段時(shí)間之后再來反觀，我總會發(fā)現(xiàn)一些不足的地方，要么測試分類沒有分好，要么基本的編碼架子沒有考慮周全。

另外，我在工作中也會接觸到很多既有項(xiàng)目，公司內(nèi)部和外部的都有，多數(shù)項(xiàng)目的編碼實(shí)踐我都是不滿意的。比如，我曾經(jīng)新加入一個(gè)項(xiàng)目的時(shí)候，前前后后請教了3位同事才把該項(xiàng)目在本地運(yùn)行起來;又比如在另一項(xiàng)目中，我發(fā)現(xiàn)前端請求對應(yīng)的Java類命名規(guī)范不統(tǒng)一，有被后綴為Request的，也有被后綴為Command的。

[[271607]]

再者，工作了這么多年之后，我越來越發(fā)現(xiàn)基礎(chǔ)知識以及系統(tǒng)性學(xué)習(xí)的重要性。誠然，技術(shù)框架的發(fā)展使得我們可以快速地實(shí)現(xiàn)業(yè)務(wù)功能，但是當(dāng)軟件出了問題之后有時(shí)卻需要將各方面的知識融會貫通并在大腦里綜合反應(yīng)才能找到解決思路。

基于以上，我希望整理出一套公共性的項(xiàng)目模板出來，旨在盡量多地包含日常開發(fā)之所需，減少開發(fā)者的重復(fù)性工作以及提供一些最佳實(shí)踐。對于后端開發(fā)而言，我選擇了當(dāng)前被行業(yè)大量使用的Spring Boot，基于此整理出了一套公共的、基礎(chǔ)性的實(shí)踐方式，在結(jié)合了自己的經(jīng)驗(yàn)以及其他項(xiàng)目的優(yōu)秀實(shí)踐之后，總結(jié)出本文以饗開發(fā)者。

本文以一個(gè)簡單的電商訂單系統(tǒng)為例，源代碼請?jiān)L問：

• git clone https://github.com/e-commerce-sample/order-backend
• git checkout a443dace

所使用的技術(shù)棧主要包括：Spring Boot、Gradle、MySQL、Junit 5、Rest Assured、Docker等。

第一步：從寫好README開始

一份好的README可以給人以項(xiàng)目全景概覽，可以使新人快速上手項(xiàng)目，可以降低溝通成本。同時(shí)，README應(yīng)該簡明扼要，條理清晰，建議包含以下方面：

• 項(xiàng)目簡介：用一兩句話簡單描述該項(xiàng)目所實(shí)現(xiàn)的業(yè)務(wù)功能;
• 技術(shù)選型：列出項(xiàng)目的技術(shù)棧，包括語言、框架和中間件等;
• 本地構(gòu)建：列出本地開發(fā)過程中所用到的工具命令;
• 領(lǐng)域模型：核心的領(lǐng)域概念，比如對于示例電商系統(tǒng)來說有Order、Product等;
• 測試策略：自動化測試如何分類，哪些必須寫測試，哪些沒有必要寫測試;
• 技術(shù)架構(gòu)：技術(shù)架構(gòu)圖;
• 部署架構(gòu)：部署架構(gòu)圖;
• 外部依賴：項(xiàng)目運(yùn)行時(shí)所依賴的外部集成方，比如訂單系統(tǒng)會依賴于會員系統(tǒng);
• 環(huán)境信息：各個(gè)環(huán)境的訪問方式，數(shù)據(jù)庫連接等;
• 編碼實(shí)踐：統(tǒng)一的編碼實(shí)踐，比如異常處理原則、分頁封裝等;
• FAQ：開發(fā)過程中常見問題的解答。

需要注意的是，README中的信息可能隨著項(xiàng)目的演進(jìn)而改變(比如引入了新的技術(shù)?；蛘呒尤肓诵碌念I(lǐng)域模型)，因此也是需要持續(xù)更新的。雖然我們知道，軟件文檔的一個(gè)痛點(diǎn)便是無法與項(xiàng)目實(shí)際進(jìn)展保持同步，但是就README這點(diǎn)信息來講，還是建議開發(fā)者們不要吝嗇那一點(diǎn)點(diǎn)敲鍵盤的時(shí)間。

此外，除了保持README的持續(xù)更新，一些重要的架構(gòu)決定可以通過示例代碼的形式記錄在代碼庫中，新開發(fā)者可以通過直接閱讀這些示例代碼快速了解項(xiàng)目的通用實(shí)踐方式以及架構(gòu)選擇，請參考ThoughtWorks的技術(shù)雷達(dá)。

一鍵式本地構(gòu)建

為了避免諸如前文中所提到的“請教了3位同事才本地構(gòu)建成功”的尷尬，為了減少“懶惰”的程序員們的手動操作，也為了為所有開發(fā)者提供一種一致的開發(fā)體驗(yàn)，我們希望用一個(gè)命令就可以完成所有的事情。這里，對于不同的場景我總結(jié)出了以下命令：

• 生成IDE工程：idea.sh，生成IntelliJ工程文件并自動打開IntelliJ
• 本地運(yùn)行：run.sh，本地啟動項(xiàng)目，自動啟動本地?cái)?shù)據(jù)庫，監(jiān)聽調(diào)試端口5005
• 本地構(gòu)建：local-build.sh，只有本地構(gòu)建成功才能提交代碼

以上3個(gè)命令基本上可以完成日常開發(fā)之所需，此時(shí)，對于新人的開發(fā)流程大致為：

1. 拉取代碼;
2. 運(yùn)行idea.sh，自動打開IntelliJ;
3. 編寫代碼，包含業(yè)務(wù)代碼和自動化測試;
4. 運(yùn)行run.sh，進(jìn)行本地調(diào)試或必要的手動測試(本步驟不是必需);
5. 運(yùn)行l(wèi)ocal-build.sh，完成本地構(gòu)建;
6. 再次拉取代碼，保證local-build.sh成功，提交代碼。

事實(shí)上，這些命令腳本的內(nèi)容非常簡單，比如run.sh文件內(nèi)容為：

#!/usr/bin/env bash 
./gradlew clean bootRun 

然而，這種顯式化的命令卻可以減少新人的恐懼感，因?yàn)樗麄冎恍枰肋\(yùn)行這3個(gè)命令就可以搞開發(fā)了。另外，一個(gè)小小的細(xì)節(jié)：本地構(gòu)建的local-build.sh命令本來可以重命名為更簡單的build.sh，但是當(dāng)我們在命令行中使用Tab鍵自動補(bǔ)全的時(shí)候，會發(fā)現(xiàn)自動補(bǔ)全到了build目錄，而不是build.sh命令，并不方便，因此命名為了local-build.sh。細(xì)節(jié)雖小，但是卻體現(xiàn)了一個(gè)宗旨，即我們希望給開發(fā)者一種極簡的開發(fā)體驗(yàn)，我把這些看似微不足道的東西稱作是對程序員的“人文關(guān)懷”。

目錄結(jié)構(gòu)

Maven所提倡的目錄結(jié)構(gòu)當(dāng)前已經(jīng)成為事實(shí)上的行業(yè)標(biāo)準(zhǔn)，Gradle在默認(rèn)情況下也采用了Maven的目錄結(jié)構(gòu)，這對于多數(shù)項(xiàng)目來說已經(jīng)足夠了。此外，除了Java代碼，項(xiàng)目中還存在其他類型的文件，比如Gradle插件的配置、工具腳本和部署配置等。無論如何，項(xiàng)目目錄結(jié)構(gòu)的原則是簡單而有條理，不要隨意地增加多余的文件夾，并且也需要及時(shí)重構(gòu)。

在示例項(xiàng)目中，頂層只有2個(gè)文件夾，一個(gè)是用于放置Java源代碼和項(xiàng)目配置的src文件夾，另一個(gè)是用于放置所有Gradle配置的gradle文件夾，此外，為了方便開發(fā)人員使用，將上文提到的3個(gè)常用腳本直接放到根目錄下：

└── order-backend 
    ├── gradle // 文件夾，用于放置所有Gradle配置 
    ├── src // 文件夾，Java源代碼 
    ├── idea.sh //生成IntelliJ工程 
    ├── local-build.sh // 提交之前的本地構(gòu)建 
    └── run.sh // 本地運(yùn)行 

對于gradle而言，我們刻意地將Gradle插件腳本與插件配置放到了一起，比如Checkstyle：

├── gradle 
│   ├── checkstyle 
│   │   ├── checkstyle.gradle 
│   │   └── checkstyle.xml 

事實(shí)上，在默認(rèn)情況下Checkstyle插件會從項(xiàng)目根目錄下的config目錄查找checkstyle.xml配置文件，但是這一方面增加了多余的文件夾，另一方面與該插件相關(guān)的設(shè)施分散在了不同的地方，違背了廣義上的內(nèi)聚原則。

基于業(yè)務(wù)分包

早年的Java分包方式通常是基于技術(shù)的，比如與domain包平級的有controller包、service包和infrastructure包等。這種方式當(dāng)前并不被行業(yè)所推崇，而是應(yīng)該首先基于業(yè)務(wù)分包。比如，在訂單示例項(xiàng)目中，有兩個(gè)重要的領(lǐng)域?qū)ο驩rder和Product(在DDD中稱為聚合根)，所有的業(yè)務(wù)都圍繞它們展開，因此分別創(chuàng)建order包和product包，再分別在包下創(chuàng)建與之相關(guān)的各個(gè)子包。此時(shí)的order包如下：

├── order 
│   ├── OrderApplicationService.java 
│   ├── OrderController.java 
│   ├── OrderNotFoundException.java 
│   ├── OrderRepository.java 
│   ├── OrderService.java 
│   └── model 
│       ├── Order.java 
│       ├── OrderFactory.java 
│       ├── OrderId.java 
│       ├── OrderItem.java 
│       └── OrderStatus.java 

可以看到，在order包下我們直接放置了OrderController和OrderRepository等類，而沒有必要再為這些類劃分單獨(dú)的子包。而對于領(lǐng)域模型Order來講，由于包含了多個(gè)對象，因此基于內(nèi)聚性原則將它們歸到model包中。但是這并不是一個(gè)必須，如果業(yè)務(wù)足夠簡單，我們甚至可以將所有類直接放到業(yè)務(wù)包下，product包便是如此：

└── product 
    ├── Product.java 
    ├── ProductApplicationService.java 
    ├── ProductController.java 
    ├── ProductId.java 
    └── ProductRepository.java 

在編碼實(shí)踐中，我們總是基于一個(gè)業(yè)務(wù)用例來實(shí)現(xiàn)代碼，在技術(shù)分包場景下，我們需要在分散的各包中來回切換，增加了代碼導(dǎo)航的成本;另外，代碼提交的變更內(nèi)容也是散落的，在查看代碼提交歷史時(shí)，無法直觀的看出該次提交是關(guān)于什么業(yè)務(wù)功能的。在業(yè)務(wù)分包下，我們只需要在單個(gè)統(tǒng)一的包下修改代碼，減少了代碼導(dǎo)航成本;另外一個(gè)好處是，如果哪天我們需要將某個(gè)業(yè)務(wù)遷移到另外的項(xiàng)目(比如識別出了獨(dú)立的微服務(wù))，那么直接整體移動業(yè)務(wù)包即可。

當(dāng)然，基于業(yè)務(wù)分包并不意味著所有的代碼都必須囿于業(yè)務(wù)包下，這里的邏輯是：優(yōu)先進(jìn)行業(yè)務(wù)分包，然后對于一些不隸屬于任何業(yè)務(wù)的代碼可以單獨(dú)分包，比如一些util類、公共配置等。比如我們依然可以創(chuàng)建一個(gè)common包，下面放置了Spring公共配置、異常處理框架和日志等子包：

└── common 
    ├── configuration 
    ├── exception 
    ├── loggin 
    └── utils 

自動化測試分類

在當(dāng)前的微服務(wù)和前后端分離的開發(fā)模式下，后端項(xiàng)目僅提供純粹的業(yè)務(wù)API，而不包含UI邏輯，因此后端項(xiàng)目不會再包含諸如WebDriver的重量級端到端測試。同時(shí)，后端項(xiàng)目作為向外提供業(yè)務(wù)功能的獨(dú)立運(yùn)行單元，在API級別也應(yīng)該有相應(yīng)的測試。

此外，程序中有些框架性代碼，要么是諸如Controller之類的技術(shù)性框架代碼，要么是基于某種架構(gòu)風(fēng)格的代碼(比如DDD實(shí)踐中的ApplicationService)，這些代碼一方面并不包含業(yè)務(wù)邏輯，一方面是很薄的一個(gè)抽象層(即實(shí)現(xiàn)相對簡單)，用單元測試來覆蓋顯得沒有必要，因此筆者的觀點(diǎn)是可以不為此編寫單獨(dú)的單元測試。再者，程序中有些重要的組件性代碼，比如訪問數(shù)據(jù)庫的Repository或者分布式鎖，使用單元測試實(shí)際上“測不到點(diǎn)上”，而使用API測試又顯得在分類邏輯上不合理，為此我們可以專門創(chuàng)建一種測試類型謂之組件測試。

基于以上，我們可以對自動化測試做個(gè)分類：

• 單元測試：核心的領(lǐng)域模型，包括領(lǐng)域?qū)ο?比如Order類)，F(xiàn)actory類，領(lǐng)域服務(wù)類等;
• 組件測試：不適合寫單元測試但是又必須測試的類，比如Repository類，在有些項(xiàng)目中，這種類型測試也被稱為集成測試;
• API測試：模擬客戶端測試各個(gè)API接口，需要啟動程序。

Gradle在默認(rèn)情況下只提供src/test/java目錄用于測試，對于以上3種類型的測試，我們需要將它們分開以便于管理(也是職責(zé)分離的體現(xiàn))。為此，可以通過Gradle提供的SourceSets對測試代碼進(jìn)行分類：

sourceSets { 
    componentTest { 
        compileClasspath += sourceSets.main.output + sourceSets.test.output 
        runtimeClasspath += sourceSets.main.output + sourceSets.test.output 
    } 
 
    apiTest { 
        compileClasspath += sourceSets.main.output + sourceSets.test.output 
        runtimeClasspath += sourceSets.main.output + sourceSets.test.output 
    } 
} 

到此，3種類型的測試可以分別編寫在以下目錄：

• 單元測試：src/test/java
• 組件測試：src/componentTest/java
• API測試：src/apiTest/java

需要注意的是，這里的API測試更多強(qiáng)調(diào)的是對業(yè)務(wù)功能的測試，有些項(xiàng)目中可能還會存在契約測試和安全測試等，雖然從技術(shù)上講都是對API的訪問，但是這些測試都是單獨(dú)的關(guān)注點(diǎn)，因此建議分開對待。

值得一提的是，由于組件測試和API測試需要啟動程序，也即需要準(zhǔn)備好本地?cái)?shù)據(jù)庫，我們采用了Gradle的docker-compose插件(或者jib插件)，該插件會在運(yùn)行測試之前自動運(yùn)行Docker容器(比如MySQL)：

apply plugin: 'docker-compose' 
 
 
dockerCompose { 
    useComposeFiles = ['docker/mysql/docker-compose.yml'] 
} 
 
bootRun.dependsOn composeUp 
componentTest.dependsOn composeUp 
apiTest.dependsOn composeUp 

更多的測試分類配置細(xì)節(jié)，比如JaCoCo測試覆蓋率配置等，請參考本文的示例項(xiàng)目代碼。對Gradle不熟悉的讀者可以參考筆者的Gradle學(xué)習(xí)系列文章。

日志處理

在日志處理中，除了完成基本配置外，還有2個(gè)需要考慮的點(diǎn)：

1.在日志中加入請求標(biāo)識，便于鏈路追蹤。在處理一個(gè)請求的過程中有時(shí)會輸出多條日志，如果每條日志都共享統(tǒng)一的請求ID，那么在日志追蹤時(shí)會更加方便。此時(shí)，可以使用Logback原生提供的MDC(Mapped Diagnostic Context)功能，創(chuàng)建一個(gè)RequestIdMdcFilter：

protected void doFilterInternal(HttpServletRequest request, 
                                    HttpServletResponse response, 
                                    FilterChain filterChain) 
            throws ServletException, IOException { 
        //request id in header may come from Gateway, eg. Nginx 
        String headerRequestId = request.getHeader(HEADER_X_REQUEST_ID); 
        MDC.put(REQUEST_ID, isNullOrEmpty(headerRequestId) ? newUuid() : headerRequestId); 
        try { 
            filterChain.doFilter(request, response); 
        } finally { 
            clearMdc(); 
        } 
    } 

2.集中式日志管理，在多節(jié)點(diǎn)部署的場景下，各個(gè)節(jié)點(diǎn)的日志是分散的，為此可以引入諸如ELK之類的工具將日志統(tǒng)一輸出到ElasticSearch中。本文的示例項(xiàng)目使用了RedisAppender將日志輸出到Logstash：

<appender name="REDIS" class="com.cwbase.logback.RedisAppender"> 
    <tags>ecommerce-order-backend-${ACTIVE_PROFILE}</tags> 
    <host>elk.yourdomain.com</host> 
    <port>6379</port> 
    <password>whatever</password> 
    <key>ecommerce-ordder-log</key> 
    <mdc>true</mdc> 
    <type>redis</type> 
</appender> 

 

當(dāng)然，統(tǒng)一日志的方案還有很多，比如Splunk和Graylog等。

異常處理

在設(shè)計(jì)異常處理的框架時(shí)，需要考慮以下幾點(diǎn)：

• 向客戶端提供格式統(tǒng)一的異常返回
• 異常信息中應(yīng)該包含足夠多的上下文信息，最好是結(jié)構(gòu)化的數(shù)據(jù)以便于客戶端解析
• 不同類型的異常應(yīng)該包含唯一標(biāo)識，以便客戶端精確識別

異常處理通常有兩種形式，一種是層級式的，即每種具體的異常都對應(yīng)了一個(gè)異常類，這些類最終繼承自某個(gè)父異常;另一種是單一式的，即整個(gè)程序中只有一個(gè)異常類，再以一個(gè)字段來區(qū)分不同的異常場景。層級式異常的好處是能夠顯式化異常含義，但是如果層級設(shè)計(jì)不好可能導(dǎo)致整個(gè)程序中充斥著大量的異常類;單一式的好處是簡單，而其缺點(diǎn)在于表意性不夠。

本文的示例項(xiàng)目使用了層級式異常，所有異常都繼承自一個(gè)AppException：

public abstract class AppException extends RuntimeException { 
    private final ErrorCode code; 
    private final Map<String, Object> data = newHashMap(); 
} 

這里，ErrorCode枚舉中包含了異常的唯一標(biāo)識、HTTP狀態(tài)碼以及錯(cuò)誤信息;而data字段表示各個(gè)異常的上下文信息。

在示例系統(tǒng)中，在沒有找到訂單時(shí)拋出異常：

public class OrderNotFoundException extends AppException { 
    public OrderNotFoundException(OrderId orderId) { 
        super(ErrorCode.ORDER_NOT_FOUND, ImmutableMap.of("orderId", orderId.toString())); 
    } 
} 

在返回異常給客戶端時(shí)，通過一個(gè)ErrorDetail類來統(tǒng)一異常格式：

public final class ErrorDetail { 
    private final ErrorCode code; 
    private final int status; 
    private final String message; 
    private final String path; 
    private final Instant timestamp; 
    private final Map<String, Object> data = newHashMap(); 
} 

最終返回客戶端的數(shù)據(jù)為：

{ 
  requestId: "d008ef46bb4f4cf19c9081ad50df33bd", 
  error: { 
    code: "ORDER_NOT_FOUND", 
    status: 404, 
    message: "沒有找到訂單", 
    path: "/order", 
    timestamp: 1555031270087, 
    data: { 
      orderId: "123456789" 
    } 
  } 
} 

可以看到，ORDER_NOT_FOUND與data中的數(shù)據(jù)結(jié)構(gòu)是一一對應(yīng)的，也即對于客戶端來講，如果發(fā)現(xiàn)了ORDER_NOT_FOUND，那么便可確定data中一定存在orderId字段，進(jìn)而完成精確的結(jié)構(gòu)化解析。

后臺任務(wù)與分布式鎖

除了即時(shí)完成客戶端的請求外，系統(tǒng)中通常會有一些定時(shí)性的例行任務(wù)，比如定期地向用戶發(fā)送郵件或者運(yùn)行數(shù)據(jù)報(bào)表等;另外，有時(shí)從設(shè)計(jì)上我們會對請求進(jìn)行異步化處理。此時(shí)，我們需要搭建后臺任務(wù)相關(guān)基礎(chǔ)設(shè)施。Spring原生提供了任務(wù)處理(TaskExecutor)和任務(wù)計(jì)劃(TaskSchedulor)機(jī)制;而在分布式場景下，還需要引入分布式鎖來解決并發(fā)沖突，為此我們引入一個(gè)輕量級的分布式鎖框架ShedLock。

啟用Spring任務(wù)配置如下：

@Configuration 
@EnableAsync 
@EnableScheduling 
public class SchedulingConfiguration implements SchedulingConfigurer { 
 
    @Override 
    public void configureTasks(ScheduledTaskRegistrar taskRegistrar) { 
        taskRegistrar.setScheduler(newScheduledThreadPool(10)); 
    } 
 
    @Bean(destroyMethod = "shutdown") 
    @Primary 
    public TaskExecutor taskExecutor() { 
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); 
        executor.setCorePoolSize(2); 
        executor.setMaxPoolSize(5); 
        executor.setQueueCapacity(10); 
        executor.setTaskDecorator(new LogbackMdcTaskDecorator()); 
        executor.initialize(); 
        return executor; 
    } 
 
} 

然后配置Shedlock：

@Configuration 
@EnableSchedulerLock(defaultLockAtMostFor = "PT30S") 
public class DistributedLockConfiguration { 
 
    @Bean 
    public LockProvider lockProvider(DataSource dataSource) { 
        return new JdbcTemplateLockProvider(dataSource); 
    } 
 
 
    @Bean 
    public DistributedLockExecutor distributedLockExecutor(LockProvider lockProvider) { 
        return new DistributedLockExecutor(lockProvider); 
    } 
 
 
} 

實(shí)現(xiàn)后臺任務(wù)處理：

@Scheduled(cron = "0 0/1 * * * ?") 
    @SchedulerLock(name = "scheduledTask", lockAtMostFor = THIRTY_MIN, lockAtLeastFor = ONE_MIN) 
    public void run() { 
        logger.info("Run scheduled task."); 
    } 

為了支持代碼直接調(diào)用分布式鎖，基于Shedlock的LockProvider創(chuàng)建DistributedLockExecutor：

public class DistributedLockExecutor { 
    private final LockProvider lockProvider; 
 
    public DistributedLockExecutor(LockProvider lockProvider) { 
        this.lockProvider = lockProvider; 
    } 
 
    public <T> T executeWithLock(Supplier<T> supplier, LockConfiguration configuration) { 
        Optional<SimpleLock> lock = lockProvider.lock(configuration); 
        if (!lock.isPresent()) { 
            throw new LockAlreadyOccupiedException(configuration.getName()); 
        } 
 
        try { 
            return supplier.get(); 
        } finally { 
            lock.get().unlock(); 
        } 
    } 
 
} 

使用時(shí)在代碼中直接調(diào)用：

public String doBusiness() { 
        return distributedLockExecutor.executeWithLock(() -> "Hello World.", 
                new LockConfiguration("key", Instant.now().plusSeconds(60))); 
    } 

本文的示例項(xiàng)目使用了基于JDBC的分布式鎖，事實(shí)上任何提供原子操作的機(jī)制都可用于分布式鎖，Shedlock還提供基于Redis、ZooKeeper和Hazelcast等的分布式鎖實(shí)現(xiàn)機(jī)制。

統(tǒng)一代碼風(fēng)格

除了Checkstyle統(tǒng)一代碼格式之外，項(xiàng)目中有些通用的公共的編碼實(shí)踐方式也需要在整個(gè)開發(fā)團(tuán)隊(duì)中進(jìn)行統(tǒng)一，包括但不限于以下方面：

• 客戶端的請求數(shù)據(jù)類統(tǒng)一使用相同后綴，比如Command
• 返回給客戶端的數(shù)據(jù)統(tǒng)一使用相同后綴，比如Represetation
• 統(tǒng)一對請求處理的流程框架，比如采用傳統(tǒng)的3層架構(gòu)或者DDD戰(zhàn)術(shù)模式
• 提供一致的異常返回(請參考“異常處理”小節(jié))
• 提供統(tǒng)一的分頁結(jié)構(gòu)類
• 明確測試分類以及統(tǒng)一的測試基礎(chǔ)類(請參考“自動化測試分類”小節(jié))

靜態(tài)代碼檢查

靜態(tài)代碼檢查主要包含以下Gradle插件，具體配置請參考本文示例代碼：

• Checkstyle：用于檢查代碼格式，規(guī)范編碼風(fēng)格
• Spotbugs：Findbugs的繼承者
• Dependency check：OWASP提供的Java類庫安全性檢查
• Sonar：用于代碼持續(xù)改進(jìn)的跟蹤

健康檢查

健康檢查主要用于以下場景：

• 我們希望初步檢查程序是否運(yùn)行正常
• 有些負(fù)載均衡軟件會通過一個(gè)健康檢查URL判斷節(jié)點(diǎn)的可達(dá)性

此時(shí)，可以實(shí)現(xiàn)一個(gè)簡單的API接口，該接口不受權(quán)限管控，可以公開訪問。如果該接口返回HTTP的200狀態(tài)碼，便可初步認(rèn)為程序運(yùn)行正常。此外，我們還可以在該API中加入一些額外的信息，比如提交版本號、構(gòu)建時(shí)間、部署時(shí)間等。

啟動本文的示例項(xiàng)目：

./run.sh 

然后訪問健康檢查API：http://localhost:8080/about，結(jié)果如下：

{ 
  requestId: "698c8d29add54e24a3d435e2c749ea00", 
  buildNumber: "unknown", 
  buildTime: "unknown", 
  deployTime: "2019-04-11T13:05:46.901+08:00[Asia/Shanghai]", 
  gitRevision: "unknown", 
  gitBranch: "unknown", 
  environment: "[local]" 
} 

以上接口在示例項(xiàng)目中用了一個(gè)簡單的Controller實(shí)現(xiàn)，事實(shí)上Spring Boot的Acuator框架也能夠提供相似的功能。

API文檔

軟件文檔的難點(diǎn)不在于寫，而在于維護(hù)。多少次，當(dāng)我對照著項(xiàng)目文檔一步一步往下走時(shí)，總得不到正確的結(jié)果，問了同事之后得到回復(fù)“哦，那個(gè)已經(jīng)過時(shí)了”。本文示例項(xiàng)目所采用的Swagger在一定程度上降低了API維護(hù)的成本，因?yàn)镾wagger能自動識別代碼中的方法參數(shù)、返回對象和URL等信息，然后自動地實(shí)時(shí)地創(chuàng)建出API文檔。

配置Swagger如下：

@Configuration 
@EnableSwagger2 
@Profile(value = {"local", "dev"}) 
public class SwaggerConfiguration { 
 
    @Bean 
    public Docket api() { 
        return new Docket(SWAGGER_2) 
                .select() 
                .apis(basePackage("com.ecommerce.order")) 
                .paths(any()) 
                .build(); 
    } 
} 

啟動本地項(xiàng)目，訪問http://localhost:8080/swagger-ui.html：

Swagger API文檔

數(shù)據(jù)庫遷移

在傳統(tǒng)的開發(fā)模式中，數(shù)據(jù)庫由專門的運(yùn)維團(tuán)隊(duì)或者DBA來維護(hù)，要對數(shù)據(jù)庫進(jìn)行修改需要向DBA申請，告之遷移內(nèi)容，最后由DBA負(fù)責(zé)數(shù)據(jù)庫變更實(shí)施。在持續(xù)交付和DevOps運(yùn)動中，這些工作逐步提前到開發(fā)過程，當(dāng)然并不是說不需要DBA了，而是這些工作可以由開發(fā)者和運(yùn)維人員一同完成。另外，在微服務(wù)場景下，數(shù)據(jù)庫被包含在單個(gè)服務(wù)的邊界之內(nèi)，因此基于內(nèi)聚性原則(咦，這好像是本文第三次提到內(nèi)聚原則了，可見其在軟件開發(fā)中的重要性)，數(shù)據(jù)庫的變更最好也與項(xiàng)目代碼一道維護(hù)在代碼庫中。

本文的示例項(xiàng)目采用了Flyway作為數(shù)據(jù)庫遷移工具，加入了Flyway依賴后，在src/main/sources/db/migration目錄下創(chuàng)建遷移腳本文件即可：

resources/ 
├── db 
│   └── migration 
│       ├── V1__init.sql 
│       └── V2__create_product_table.sql 

遷移腳本的命名需要遵循一定的規(guī)則以保證腳本執(zhí)行順序，另外遷移文件生效之后不要任意修改，因?yàn)镕lyway會檢查文件的checksum，如果checksum不一致將導(dǎo)致遷移失敗。

多環(huán)境構(gòu)建

在軟件的開發(fā)流程中，我們需要將軟件部署到多個(gè)環(huán)境，經(jīng)過多輪驗(yàn)證后才能最終上線。在不同的階段中，軟件的運(yùn)行態(tài)可能是不一樣的，比如本地開發(fā)時(shí)可能將所依賴的第三方系統(tǒng)stub掉;持續(xù)集成構(gòu)建時(shí)可能使用的是測試用的內(nèi)存數(shù)據(jù)庫等等。為此，本文的示例項(xiàng)目推薦采用以下環(huán)境：

• local：用于開發(fā)者本地開發(fā)
• ci：用于持續(xù)集成
• dev：用于前端開發(fā)聯(lián)調(diào)
• qa：用于測試人員
• uat：類生產(chǎn)環(huán)境，用于功能驗(yàn)收(有時(shí)也稱為staging環(huán)境)
• prod：正式的生產(chǎn)環(huán)境

CORS

在前后端分離的系統(tǒng)中，前端單獨(dú)部署，有時(shí)連域名都和后端不同，此時(shí)需要進(jìn)行跨域處理。傳統(tǒng)的做法可以通過JSONP，但這是一種比較“trick”的做法，當(dāng)前更通用的實(shí)踐是采用CORS機(jī)制，在Spring Boot項(xiàng)目中，啟用CORS配置如下：

@Configuration 
public class CorsConfiguration { 
    @Bean 
    public WebMvcConfigurer corsConfigurer() { 
        return new WebMvcConfigurer() { 
            @Override 
            public void addCorsMappings(CorsRegistry registry) { 
                registry.addMapping("/**"); 
            } 
        }; 
    } 
} 

對于使用Spring Security的項(xiàng)目，需要保證CORS工作于Spring Security的過濾器之前，為此Spring Security專門提供了相應(yīng)配置：

@EnableWebSecurity 
public class WebSecurityConfig extends WebSecurityConfigurerAdapter { 
 
    @Override 
    protected void configure(HttpSecurity http) throws Exception { 
        http 
            // by default uses a Bean by the name of corsConfigurationSource 
            .cors().and() 
            ... 
    } 
 
    @Bean 
    CorsConfigurationSource corsConfigurationSource() { 
        CorsConfiguration configuration = new CorsConfiguration(); 
        configuration.setAllowedOrigins(Arrays.asList("https://example.com")); 
        configuration.setAllowedMethods(Arrays.asList("GET","POST")); 
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); 
        source.registerCorsConfiguration("/**", configuration); 
        return source; 
    } 
} 

常用第三方類庫

這里列出一些比較常見的第三方庫，開發(fā)者們可以根據(jù)項(xiàng)目所需引入：

• Guava：來自Google的常用類庫
• Apache Commons：來自Apache的常用類庫
• Mockito：主要用于單元測試的mock
• DBUnit：測試中管理數(shù)據(jù)庫測試數(shù)據(jù)
• Rest Assured：用于Rest API測試
• Jackson 2：Json數(shù)據(jù)的序列化和反序列化
• jjwt：Jwt token認(rèn)證
• Lombok：自動生成常見Java代碼，比如equals()方法，getter和setter等;
• Feign：聲明式Rest客戶端
• Tika：用于準(zhǔn)確檢測文件類型
• itext：生成Pdf文件等
• zxing：生成二維碼
• Xstream：比Jaxb更輕量級的XML處理庫

總結(jié)

本文通過一個(gè)示例項(xiàng)目談及到了項(xiàng)目之初開發(fā)者搭建后端工程的諸多方面，其中的絕大多數(shù)實(shí)踐均在筆者的項(xiàng)目中真實(shí)落地。讀完本文之后你可能會發(fā)現(xiàn)，文中的很多內(nèi)容都是很基礎(chǔ)很簡單的。沒錯(cuò)，的確沒有什么難的東西，但是要系統(tǒng)性地搭建好后端項(xiàng)目的基礎(chǔ)框架卻不見得是每個(gè)開發(fā)團(tuán)隊(duì)都已經(jīng)做到的事情，而這恰恰是本文的目的。最后，需要提醒的是，本文提到的實(shí)踐方式只是一個(gè)參考，一方面依然存在考慮不周的地方，另一方面示例項(xiàng)目中用到的技術(shù)工具還存在其他替代方案，請根據(jù)自己項(xiàng)目的實(shí)際情況進(jìn)行取舍。

作者：無知者云

鏈接：https://www.jianshu.com/p/bd8136129dfb

來源：簡書

簡書著作權(quán)歸作者所有，任何形式的轉(zhuǎn)載都請聯(lián)系作者獲得授權(quán)并注明出處。