重拾後端之Spring Boot（一）：REST API的搭建可以這樣簡單

接灰的電子產品發表於2017-01-24
後端Spring BootRESTAPI

重拾後端之Spring Boot（一）：REST API的搭建可以這樣簡單
重拾後端之Spring Boot（二）：MongoDb的無縫整合
重拾後端之Spring Boot（三）：找回熟悉的Controller，Service
重拾後端之Spring Boot（四）：使用 JWT 和 Spring Security 保護 REST API
重拾後端之 Spring Boot（五） -- 跨域、自定義查詢及分頁
重拾後端之Spring Boot（六） -- 熱載入、容器和多專案

話說我當年接觸Spring的時候著實興奮了好一陣，IoC的概念當初第一次聽說，感覺有種開天眼的感覺。記得當時的web框架和如今的前端框架的局面差不多啊，都是群雄紛爭。但一晃好多年沒寫過後端，程式碼這東西最怕手生，所以當作重新學習了，順便寫個學習筆記。

Spring Boot是什麼？

還恍惚記得當初寫Spring的時候要配置好多xml（在當時還是相對先進的模式），雖然實現了鬆耦合，但這些xml卻又成為了專案甩不掉的負擔 -- 隨著專案越做越大，這些xml的可讀性和可維護性極差。後來受.Net平臺中Annotation的啟發，Java世界中也引入了後設資料的修飾符，Spring也可以使用這種方式進行配置。到了近些年，隨著Ruby on Rails的興起而流行開的 Convention over configuration 理念開始深入人心。那什麼是 Convention over configuration 呢？簡單來說就是犧牲一部分的自由度來減少配置的複雜度，打個比方就是如果你如果遵從我定義的一系列規則（打個比方，檔案目錄結構必須是blablabla的樣子，檔案命名必須是nahnahnah 的樣子），那麼你要配置的東西就非常簡單甚至可以零配置。既然已經做到這個地步了，各種腳手架專案就紛紛湧現了，目的只有一個：讓你更專注在程式碼的編寫，而不是浪費在各種配置上。這兩年前端也有類似趨勢，各種前端框架的官方CLI紛紛登場：create-react-app，angular-cli，vue-cli等等。

那麼Spring Boot就是Spring框架的腳手架了，它可以幫你快速搭建、釋出一個Spring應用。官網列出了Spring Boot的幾個主要目標

  • 提供一種快速和廣泛適用的Spring開發體驗
  • 開箱即用卻又可以適應各種變化
  • 提供一系列開發中常用的“非功能性”的特性（比如嵌入式伺服器、安全、度量、自檢及外部配置等）
  • 不生成任何程式碼，不需要xml配置

安裝Spring Boot

官方推薦的方式是通過sdkman（ sdkman.io/install.htm… ）來進行安裝，當然這是對 *nix 而言。題外話，如果你使用的是Windows 10，真心希望大家安裝Windows 10的Linux子系統，微軟官方出品、原生支援，比虛擬機器不知道快到那裡去了 具體安裝過程可以參考 linux.cn/article-720… 。安裝 sdkman 的步驟非常簡單，就兩步：

  1. 開啟一個terminal，輸入 curl -s "https://get.sdkman.io" | bash
  2. 安裝結束後，重啟terminal，輸入 source "$HOME/.sdkman/bin/sdkman-init.sh"

可以在terminal中驗證一下是否安裝成功 sdk version，如果你看到了版本號就是安裝好了。

接下來，就可以安裝Spring Boot了，還是開啟terminal輸入 sdk install springboot就ok了。

當然其實Mac的童鞋可以省略掉之前的sdkman安裝直接使用 brew 安裝，也是兩步：

  1. 在terminal中輸入 brew tap pivotal/tap
  2. 然後 brew install springboot

驗證的話可以輸入 spring --version 看看是否正常輸出了版本號。

建立一個工程

有很多種方法可以建立一個Spring Boot專案，其中最簡單的一種是通過一個叫Spring Initializr的線上工具 http://start.spring.io/ 進行工程的生成。如下圖所示，只需填寫一些引數就可以生成一個工程包了。

使用Spring Initializr進行工程的生成
使用Spring Initializr進行工程的生成

如果你使用Intellij IDEA進行開發，裡面也整合了這個工具，大家可以自行嘗試。

Intellij IDEA中整合了 Spring Initializr
Intellij IDEA中整合了 Spring Initializr

但下面我們要做的不是通過這種方式，而是手動的通過命令列方式建立。建立的是gradle工程，而不是maven的，原因呢是因為個人現在對於xml型別的配置檔案比較無感;-)，官方推薦使用gradle 2.14.1版本，請自行安裝gradle。下面來建立一個gradle工程，其實步驟也不算太難：

  1. 新建一個工程目錄 mkdir todo
  2. 在此目錄下使用gradle進行初始化 gradle init（就和在node中使用 npm init 的效果類似）

這個命令幫我們建立一個一個使用gradle進行管理的模版工程：

  • build.gradle：有過Android開發經驗的童鞋可能覺得很親切的，這個就是我們用於管理和配置工程的核心檔案了。
  • gradlew：用於 *nix 環境下的gradle wrapper檔案。
  • gradlew.bat：用於 Windows 環境下的gradle wrapper檔案
  • setting.gradle：用於管理多專案的gradle工程時使用，單專案時可以不做理會。
  • gradle目錄：wrapper的jar和屬性設定檔案所在的資料夾。

簡單說兩句什麼是 gradle wrapper。你是否有過這樣的經歷？在安裝/編譯一個工程時需要一些先決條件，需要安裝一些軟體或設定一些引數。如果這一切比較順利還好，但很多時候我們會發現這樣那樣的問題，比如版本不對，引數沒設定等等。gradle wrapper 就是這樣一個讓你不會浪費時間在配置問題上的方案。它會對應一個開發中使用的gradle版本，以確保任何人任何時候得到的結果是一致的。

  • ./gradlew <task>: 在 *nix 平臺上執行，例如Linux或Mac OS X
  • gradlew <task> 在Windows平臺執行（是通過gradlew.bat來執行的）

更多關於wrapper的知識可以去 docs.gradle.org/current/use… 檢視。

那麼下面我們開啟預設生成的 build.gradle 檔案，將其改造成下面的樣子：

/*
 * 這個build檔案是由Gradle的 `init` 任務生成的。
 *
 * 更多關於在Gradle中構建Java專案的資訊可以檢視Gradle使用者文件中的
 * Java專案快速啟動章節
 * https://docs.gradle.org/3.3/userguide/tutorial_java_projects.html
 */
// 在這個段落中你可以宣告你的build指令碼需要的依賴和解析下載該依賴所使用的倉儲位置
buildscript {
    ext {
        springBootVersion = '1.4.3.RELEASE'
    }
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
    }
}
/*
 * 在這個段落中你可以宣告使用哪些外掛
 * apply plugin: 'java' 代表這是一個Java專案，需要使用java外掛
 * 如果想生成一個 `Intellij IDEA` 的工程，類似的如果要生成 
 * eclipse工程，就寫 apply plugin: 'eclipse'
 * 同樣的我們要學的是Spring Boot，所以應用Spring Boot外掛
 */
apply plugin: 'java' 
apply plugin: 'idea' 
apply plugin: 'eclipse'
apply plugin: 'org.springframework.boot'

// 在這個段落中你可以宣告編譯後的Jar檔案資訊
jar {
    baseName = 'todo'
    version = '0.0.1-SNAPSHOT'
}

// 在這個段落中你可以宣告在哪裡可以找到你的專案依賴
repositories {
    // 使用 'jcenter' 作為中心倉儲查詢解析你的專案依賴。
    // 你可以宣告任何 Maven/Ivy/file 型別的依賴類庫倉儲位置
    mavenCentral()
}

// 在這個段落中你可以宣告原始檔和目標編譯後的Java版本相容性
sourceCompatibility = 1.8
targetCompatibility = 1.8

// 在這個段落你可以宣告你的專案的開發和測試所需的依賴類庫
dependencies {
    compile('org.springframework.boot:spring-boot-starter-web')
    testCompile('org.springframework.boot:spring-boot-starter-test')
}複製程式碼

首先指令碼依賴中的 spring-boot-gradle-plugin 有什麼作用呢？它提供了以下幾個功能：

  1. 簡化執行和釋出：它可以把所有classpath的類庫構建成一個單獨的可執行jar檔案，這樣可以簡化你的執行和釋出等操作。
  2. 自動搜尋入口檔案：它會掃描 public static void main() 函式並且標記這個函式的宿主類為可執行入口。
  3. 簡化依賴：一個典型的Spring應用還是需要很多依賴類庫的，想要配置正確這些依賴挺麻煩的，所以這個外掛提供了內建的依賴解析器會自動匹配和當前Spring Boot版本匹配的依賴庫版本。

在最後一個段落中，我們看到我們的專案依賴兩個類庫，一個是 spring-boot-starter-web ，另一個是 spring-boot-starter-test。Spring Boot提供了一系列依賴類庫的“模版”，這些“模版”封裝了很多依賴類庫，可以讓我們非常方便的引用自己想實現的功能所需要的類庫。如果我們去看看這個 spring-boot-starter-web 中究竟引用了什麼，我們可以看看它的artifact檔案（到 search.maven.org/ 可以檢視）：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starters</artifactId>
        <version>1.4.3.RELEASE</version>
    </parent>
    <artifactId>spring-boot-starter-web</artifactId>
    <name>Spring Boot Web Starter</name>
    <description>Starter for building web, including RESTful, applications using Spring
        MVC. Uses Tomcat as the default embedded container</description>
    <url>http://projects.spring.io/spring-boot/</url>
    <organization>
        <name>Pivotal Software, Inc.</name>
        <url>http://www.spring.io</url>
    </organization>
    <properties>
        <main.basedir>${basedir}/../..</main.basedir>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </dependency>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-validator</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webmvc</artifactId>
        </dependency>
    </dependencies>
</project>複製程式碼

IDE支援

一般做Java開發，大部分團隊還是喜歡用一個IDE，雖然我還是更偏愛文字編輯器型別的（比如sublime，vscode，atom等）。但是如果非挑一個重型IDE的話，我更喜歡Intellij IDEA。

使用IDEA的import project功能選中 build.gradle，將工程匯入。由於是個gradle工程，請把 View->Tools Window->Gradle 的檢視視窗調出來。

Gradle工具視窗
Gradle工具視窗

點選左上角的重新整理按鈕可以將所有依賴下載類庫下來。注意IDEA有時提示是否要配置wrapper使用帶原始碼的gradle包。

提示使用帶原始碼的gradle以便有API的文件
提示使用帶原始碼的gradle以便有API的文件

如果遇到不知道什麼原因導致一直重新整理完成不了的情況，請在專案屬性中選擇 Use local gradle distribution

image_1b77vqast1d2h1qioeepsdm1tkb9.png-192.5kB
image_1b77vqast1d2h1qioeepsdm1tkb9.png-192.5kB

第一個Web API

領域物件

那麼我們的原始碼目錄在哪裡呢？我們得手動建立一個，這個目錄一般情況下是 src/main/java。好的，下面我們要開始第一個RESTful的API搭建了，首先還是在 src/main/java 下新建一個 package。既然是本機的就叫 dev.local 吧。我們還是來嘗試建立一個 Todo 的Web API，在 dev.local 下建立一個子 package: todo，然後建立一個Todo的領域物件：

package dev.local.todo;

/**
 * Todo是一個領域物件（domain object）
 * Created by wangpeng on 2017/1/24.
 */
public class Todo {
    private String id;
    private String desc;
    private boolean completed;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getDesc() {
        return desc;
    }

    public void setDesc(String desc) {
        this.desc = desc;
    }

    public boolean isCompleted() {
        return completed;
    }

    public void setCompleted(boolean completed) {
        this.completed = completed;
    }
}複製程式碼

這個物件很簡單，只是描述了todo的幾個屬性： id 、 desc 和 completed 。我們的API返回或接受的引數就是以這個物件為模型的類或集合。

構造Controller

我們經常看到的RESTful API是這樣的：http://local.dev/todos、http://local.dev/todos/1 。Controller就是要暴露這樣的API給外部使用。現在我們同樣的在 todo 下建立一個叫 TodoController 的java檔案

package dev.local.todo;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * 使用@RestController來標記這個類是個Controller
 */
@RestController
public class TodoController {
    // 使用@RequstMapping指定可以訪問的URL路徑
    @RequestMapping("/todos")
    public List<Todo> getAllTodos() {
        List<Todo> todos = new ArrayList<>();
        Todo item1 = new Todo();
        item1.setId("1");
        item1.setCompleted(false);
        item1.setDesc("go swimming");
        todos.add(item1);
        Todo item2 = new Todo();
        item2.setId("1");
        item2.setCompleted(true);
        item2.setDesc("go for lunch");
        todos.add(item2);
        return todos;
    }
}複製程式碼

上面這個檔案也比較簡單，但注意到以下幾個事情：

  • @RestController 和 @RequestMapping 這兩個是後設資料註釋，原來在.Net中很常見，後來Java也引進過來。一方面它們可以增加程式碼的可讀性，另一方面也有效減少了程式碼的編寫。具體機理就不講了，簡單來說就是利用Java的反射機制和IoC模式結合把註釋的特性或屬性注入到被註釋的物件中。
  • 我們看到 List<Todo> getAllTodos() 方法中簡單的返回了一個List，並未做任何轉換成json物件的處理，這個是Spring會自動利用 Jackson 這個類庫的方法將其轉換成了json。

我們到這就基本接近成功了，但是現在缺少一個入口，那麼在 dev.local 包下面建立一個 Applicaiton.java 吧。

package dev.local;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * Spring Boot 應用的入口檔案
 * Created by wangpeng on 2017/1/24.
 */
@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}複製程式碼

同樣的我們只需標註這個類是 @SpringBootApplication 就萬事大吉了。可以使用下面任意一種方法去啟動我們的Web服務：

  1. 命令列中： ./gradlew bootRun
  2. IDEA中在 Application 中右鍵選擇 Run 'Application'

IDE中右鍵啟動應用
IDE中右鍵啟動應用

啟動後，開啟瀏覽器訪問 http://localhost:8080/todos 就可以看到我們的json形式的返回結果了。

瀏覽器直接訪問一下的效果
瀏覽器直接訪問一下的效果

配置Spring Beans工具

由於使用的是Spring框架，Spring工具視窗也是需要的，一般來說如果你安裝了Spring外掛的話，IDEA會自動探測到你的專案是基於Spring的。一般在你增加了Applicaiton入口後，會提示是否新增context。

檢測到Spring配置，但提示尚未關聯
檢測到Spring配置，但提示尚未關聯

遇到這種情況，請點提示框的右方的下箭頭展開提示。

展開後的提示框
展開後的提示框

點選 Create Default Context 會將目前的所有沒有map的Spring配置檔案都放在這個預設配置的上下文中。在Spring的工具視窗中可以看到下圖效果。

建立Spring配置的預設上下文
建立Spring配置的預設上下文

本章程式碼：github.com/wpcfan/spri…

重拾後端之Spring Boot（一）：REST API的搭建可以這樣簡單
重拾後端之Spring Boot（二）：MongoDb的無縫整合
重拾後端之Spring Boot（三）：找回熟悉的Controller，Service
重拾後端之Spring Boot（四）：使用 JWT 和 Spring Security 保護 REST API

相關文章