學了這麼厲害的 Kotlin 可不可以拿它來開發後端(Backend)，答案是當然可以的！
我們使用 Kotlin 跟 Gradle 來做開發
先做一個非常簡單的 API 再來慢慢進階
前端？後端？前台？後台？有差嗎？
在這邊簡單解釋一下 Web 技術這些詞彙的定義，大家也常常搞錯。
-
前端 (Frontend)：由後端 (Backend) 收到資料，透過瀏覽器渲染出來跟使用者互動的介面 (UI) 與程式都稱前端。
-
後端 (Backend)：也就是伺服器 (Server) 的部分，專門處理由使用者的要求，提供對應資料的程式。
-
前台：大家比較通俗的講法，使用者看得到的操作得到的區域，如同舞台一般。
-
後台：大家比較通俗的講法，通常是指管理者介面，如同舞台的後台。
那前台、後台跟前端、後端有關係嗎？
答案是：沒有什麼關係。
前台需要有前端（介面），也需要後端（伺服器程式）幫忙，後台也是。
工作上可以細分成：
- 前台的前端
- 前台的後端
- 後台的前端
- 後台的後端
分別有前端工程師與後端工程師負責開發。
今天的主題是後端開發的主題，所以沒有介面只有資料。
學習目標
- 手把手製作一個 REST API
- 熟悉 Spring boot 的 Annotation 寫法
- 調整 404 頁面
準備開發環境
這邊有三種做法，好壞都不一
- 直接推薦：InteliJ IDEA Ultimate 付費版
- Visual studio code 外掛 Spring Initializr plug-ins
- Spring Tools 4 for Eclipse (前身為 STS3)
💡 小提醒：這個需要付費版 InteliJ IDEA Ultimate， 免費的 Community 會無法正確 Compile，小弟已經親身試過了。
小弟建議使用 InteliJ，因為他的優異程式碼提示、搜尋與重構等功能好過其他的 IDE 編輯器
小提醒：因為 InteliJ IDEA 有可能會小改版，介面可能會稍微長的不太一樣，如果真有找不到選項、或者文章失效歡迎聯繫小弟我。
開新專案
New Project，選擇 Spring Initializr
- Group: <自己填>
- Artifact: <自己填>
- Type: Gradle Project (Generate a Gradle based project archive.)
- Language: Kotlin
- Packaging: Jar
- Java Version: 11 (選更新的版本也可以)
- Version: <自己填>
- Name: <自己填>
- Description: <自己填>
- Package: <自己填>
然後按「Next」。
這邊選擇二個：
- Web > Spring Web
- Developer Tools > Spring Boot DevTools
不選也沒關係，後面可以自行新增。
按下「Finish」完成建立專案。
如果直接新增完跑的話，Log 大概會長這樣。
瀏覽會長這樣：
資料夾結構
如果都是預設值的話，會看到以下資料夾結構：
- src/main/kotlin/\<packageName>/
主要程式碼的目錄 - src/test/kotlin/\<packageName>/
測試程式碼的目錄 - build.gradle.kts
專案的 gradle 檔案 - src/main/resources/static
存放一些靜態資源（例如：JavaScript、css、圖片…等） - src/main/resources/templates
存放一些樣板檔案 - src/main/resources/application.properties
參數設定配置檔，存放一些資料連線資訊、雜項設定等等
修改啟動的連接埠 (Port)
找到 application.properties 檔案，加入這句即可
server.port=8086啟動 Port 就改成 8086 了
其他參數請見：
https://docs.spring.io/spring-boot/docs/current/reference/html/appendix-application-properties.html
增加 Dependencies
打開 build.gradle.kts 找到 dependencies { } 的區塊
dependencies {
implementation("org.springframework.boot:spring-boot-starter-web")
developmentOnly("org.springframework.boot:spring-boot-devtools")
}即是 Spring Web 跟 Spring Boot DevTools
觀察檔案
DemoApplication.kt （如果沒改名字的話）
或者有 @SpringBootApplication 標明字樣的檔案
即主要程式，程式的進入點
可以找到一個
fun main(args: Array<String>) {
runApplication<DemoApplication>(*args)
}可以找到 main 即程式進入點
寫第一個 Controller 寫一隻 API
著手來寫第一個 Controller
定義資料 Model
我們先定義幾個的 model class，
GeneralMessageResponse 是用來顯示範例 API 資料用的
GeneralMessageResponse.kt
package com.example.demo.model
data class GeneralMessageResponse(val message:String)就這樣二句，就可以定義好資料 Model。
GeneralErrorResponse 用來顯示錯誤訊息的
GeneralErrorResponse.kt
package com.example.demo.model
data class GeneralErrorResponse(var message:String)寫一個 Controller
製作一個 class 名叫 HelloController 使用 @RestController 標示，內容如下：
HelloController.kt
package com.example.demo
import com.example.demo.model.GeneralMessageResponse
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController
@RestController
class HelloController{
@RequestMapping("/")
fun hello(): GeneralMessageResponse {
return GeneralMessageResponse("Hello, world!")
}
}做一個方法 (Method)，方法名稱可以自訂，標上 @RequestMapping 標示，回傳一個物件
即回傳的資料
@RequestMapping 上面需標明綁定的 API 路徑（不可重複）
可綁定何種傳送方式 (GET, POST, PUT, DELETE)
可編譯此專案，並瀏覽之
預設會是 http://localhost:8080/
會得到以下結果：
{"message":"Hello, world!"}新增另外一個 Method
在剛剛的 HelloController 在新增一個方法 (Method)，名叫 getHello()。
程式碼片段如下：
@RequestMapping("/hello", method = [RequestMethod.GET])
fun getHello(@RequestParam("name", defaultValue = "World") name: String): GeneralMessageResponse {
return GeneralMessageResponse("Hello, $name")
}比起剛剛的 Method 多了參數，只接受 GET 方法（使用其他方式存取會錯誤，因為沒定義）
不標明等於接收所有的方式
參數部分使用 @RequestParam 修飾字標明，標上參數名稱，
defaultValue 如果沒填資料的話的預設值為何
然後像剛才一樣，回傳一個 JSON 物件
方式＋名稱 的組合不可重複，但可接受同名但不同的方式的 Method
例如這樣是合法的：
@RequestMapping("/hello")
fun hello(): GeneralMessageResponse {
return GeneralMessageResponse("Hello, world (from default method)!")
}
@RequestMapping("/hello", method = [RequestMethod.GET])
fun getHello(@RequestParam("name", defaultValue = "World") name: String): GeneralMessageResponse {
return GeneralMessageResponse("Hello, $name (from get)")
}
@RequestMapping("/hello", method = [RequestMethod.POST])
fun postHello(@RequestParam("name", defaultValue = "World") name: String): GeneralMessageResponse {
return GeneralMessageResponse("Hello, $name (from post)")
}後面 Restful API 的時候會再提到。
錯誤處理
錯誤處理有二個部分，不太一樣：
- 執行時出現 Exception 時，可自訂回傳的錯誤訊息
- 當存取一個不存在的 API 時，預設回的訊息（ 404 Not found 頁面）
處理 Exception 錯誤
先新增一個 GeneralErrorResponse 做為錯誤訊息的回應
GeneralErrorResponse.kt
package com.example.demo.model
import com.fasterxml.jackson.annotation.JsonInclude
@JsonInclude(JsonInclude.Include.NON_NULL)
data class GeneralErrorResponse(
val message:String,
val requestUrl: String? = null,
val errorStackStace: String? = null
)新增一個 ThrowableExtension.kt 新增一個 stackTraceAsString() 拿到 stackTrace 的字串
ThrowableExtension.kt
package com.example.demo.utils
import java.io.PrintWriter
import java.io.StringWriter
fun Throwable.stackTraceAsString(): String {
val errors = StringWriter()
this.printStackTrace(PrintWriter(errors))
return errors.toString()
}最後新增 GlobalExceptionHandler 用來處理全域的 API 錯誤問題
GlobalExceptionHandler.kt
package com.example.demo
import com.example.demo.model.GeneralErrorResponse
import com.example.demo.utils.stackTraceAsString
import org.springframework.http.HttpStatus
import org.springframework.web.bind.annotation.ControllerAdvice
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.ResponseBody
import org.springframework.web.bind.annotation.ResponseStatus
import javax.servlet.http.HttpServletRequest
@ControllerAdvice
class GlobalExceptionHandler {
@ExceptionHandler(Throwable::class)
@ResponseStatus(value = HttpStatus.BAD_REQUEST)
@ResponseBody
fun handleException(request: HttpServletRequest, error: Exception): GeneralErrorResponse {
return GeneralErrorResponse("Error occurred!", request.requestURL.toString(), error.stackTraceAsString())
}
}這邊使用了 @ControllerAdvice 與 @ExceptionHandler 標示
當然不同情境有不同的用法，這邊示範回傳一個 JSON
最後在 Controller 新增一個測試用的 Exception 方法
@RequestMapping("/testErr")
fun testErr() {
throw Exception("test exception")
}然後瀏覽測試之。
處理 404 Not found 頁面
這裡處理當存取一個不存在的 API 時，預設回的資料。
我們再新增一個 Controller 名叫 MyErrorController 實作 ErrorController 介面，
範例如下：
MyErrorController.kt
package com.example.demo
import com.example.demo.model.GeneralErrorResponse
import org.springframework.boot.web.servlet.error.ErrorController
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController
@RestController
class MyErrorController : ErrorController {
override fun getErrorPath(): String {
return "/error"
}
@RequestMapping("/error")
fun handleError(): GeneralErrorResponse {
return GeneralErrorResponse("404 Error")
}
}這裡需實作 ErrorController 介面，定義錯誤發生的預設 Path 將走去哪裡
這裡使用 "/error"
然後綁定前述的值，回應一個預設訊息。
參考資料
- https://blog.csdn.net/hry2015/article/details/78806295
- https://matthung0807.blogspot.com/2019/12/spring-boot-controlleradvice.html
- https://matthung0807.blogspot.com/2018/03/spring-mvc-restcontrollercontroller.html
- https://www.baeldung.com/jackson-ignore-null-fields
- https://www.baeldung.com/exception-handling-for-rest-with-spring