哈囉大家好,我是古古。
在上一篇文章中,我們有介紹要如何去設計和實作 RESTful API,因此大家就可以透過前面所學到的內容,實際的在 Spring Boot 中實作出 RESTful API 出來了。
那麼接著這篇文章,我們就會回頭來介紹一下 Http response 中也很重要的一個部分,也就是 Http status code(Http 狀態碼),所以我們就開始吧!
Http status code 又稱為 Http 狀態碼,他是屬於 Http response 的一部分,而 Http status code 的用途,就是「用來表示這次 Http 請求的結果為何」。
所以簡單來說,Http status code 就是會透過一個簡短的數字,呈現這一次請求結果為何,因此前端就可以透過 Http status code,快速的知道這一次的 Http 請求是成功還是失敗了。
在 Http status code 的世界中,可以根據「首位數字」,分成 5 個大類,分別是:
而在每一個大類中,可以再去細分出更多的 Http status code 出來。不過其實只要在同一個大類中的 Http status code,他們的意思都是類似的!
舉例來說,只要是 2 開頭的 Http status code,不管你是 200、201、還是 202…等等,只要你是 2 開頭,就都是屬於「2xx」那一個大類,也就是表示「成功」的意思。
像是我們之前在 API Tester 中發起 Http 請求時,就會看到 Spring Boot 回傳了「200」的 Http status coe 給我們。而這個「200」,就是屬於「2xx」的大類,也就是表示「請求成功」的意思。
所以透過 Http status code 的簡短數字,我們就可以快速的知道這一次 Http 請求的結果為何了!
大概了解了 Http status code 的用途之後,接下來我們就詳細的來介紹一下,每一個大類底下都有哪些常見的 Http status code。
補充:因為 Http status code 的數量還滿多的,因此這邊只會列出比較常見的 Http status code,如果大家在工作上遇到比較罕見的 Http status code 時,可以再上網查詢一下相關的含義。
首先我們先從 1 開頭的大類開始看起,1 開頭的 Http status code 代表的是「取得資訊」的意思。
不過因為在實際的應用中,1 開頭的 Http status code 非常少用,因此在這個大類中,就沒有常見的 Http status code。
看完了 1 開頭的大類,接著我們可以看 2 開頭的大類。
2 開頭的 http status code 所代表的,就都是「請求成功」的意思。 而 2 開頭的 Http status code,他們在使用上可以說是非常頻繁了,常見的有以下三個:
首先第一個是 200 OK,200 所代表的,就是「這一次的 Http 請求成功了」。
200 可以說是使用最廣泛的一個 Http status code,通常只要看到 200,就表示這一次的請求成功了(特殊情境例外),因此 200 可以說是工程師裡面的天使等級的角色。
接著是 201 Created,201 所代表的,不僅是這一次的 Http 請求成功而已,他還額外表示「有一個新的資源成功的被創建了」的含義。
也因為 201 除了表示請求成功之外,還多表示了「創建資源成功」的含義,因此 201 通常會被用在 POST 請求的 response 中(因為 REST 風格中的 POST 就是對應到資料庫的創建操作)。
最後一個則是 202 Accepted,202 所代表的,是「這一次的請求已經被接受了,但是尚未處理完成」。 因此大家可以把 202 想像成是「你拜託別人去買東西,但是他還在買的路上,還沒幫你買好」這樣。
所以當大家以後看到 202 時,就表示後端已經開始處理這件事情了,只是他目前還沒處理完成,因此先返回一個 202 給你,告知你需要再等待一段時間才能完成。
補充:每一個 Http status code 其實都會有一個專屬的英文短語,用來表達這個 Http status code 的意思,像是 200 他所對應的英文短語是「OK」,而 202 所對應的短語是「Accepted」。
而這個短語的用途,其實就只是簡短的去描述這個 Http status code 是什麼意思而已,目的是為了幫助工程師了解這個 Http status code 的含義是什麼,因此當大家遇到不熟悉的 Http status code 時,也可以參考他的短語描述。
看完了 2 開頭的 Http status code,接著我們可以來看 3 開頭的大類。
3 開頭的 http status code 所代表的,都是「重新導向」的意思。 而在 3 開頭的大類中,常見的有以下兩個:
首先是 301 Moved Permanently,301 所代表的,是「這個 url 永久性的搬家了」,注意這裡的重點是 「永久性」。
所以當前端去請求某個 API,但是該 API 返回 301 時,就是表示這個 API 搬家了。並且後端在回傳 301 時,通常會將新的 url 放在 response header 中的 Location 中,告訴我們新的搬家地址在哪,因此前端就可以改成去請求新的 url,進而訪問搬家後的網址了。
舉例來說,我之前在架設個人網站時,就有從 https://kucw.github.io 搬家到 https://kucw.io,所以現在如果請求舊的 https://kucw.github.io 網站的話,GitHub 就會返回 301 的 Http status code,告訴前端這個網站已經永久性的搬家了,並且 GitHub 也會將新家的網址(也就是 https://kucw.io)放在 response header 中的 Location 中,因此前端就可以改成去請求新的 url https://kucw.io,進而去訪問搬家後的網址了。
所以當 url 永久性的搬家時,後端就可以返回 301 的 Http status code,用來表示這種情況。
而至於 302 Found,他就和 301 有點細微的差別。302 所代表的,則是「這個 url 暫時性的搬家」,注意這裡的重點是 「暫時性」。
所以假設某個 API 只是「暫時性」的搬家的話(ex: 這個 API 的功能目前正在調整中),那麼後端就可以回傳 302 的值給前端,並且臨時的 url 放在 response header 的 Location 中,因此前端就可以改成去請求臨時的 url,進而訪問臨時的新網址。
補充:所以 301 和 302 的差別,就只差在這個 url 是「永久性的搬家」還是「暫時性的搬家」而已。 如果是永久搬家,那就是回傳 301,如果只是暫時性的搬家,則是回傳 302。不過不管是回傳 301 或是 302,後端都是會將新的(臨時的)url 放在 response header 的 Location 中,供前端存取新網址。
看完了 3 開頭的大類之後,接著我們也可以繼續來看 4 開頭的 Http status code 的含義。
4 開頭的 Http status code 所代表的,都是「前端請求錯誤」的意思。 4 開頭的大類在使用上的頻率也很高,常見的有以下四個:
首先是 400 Bad Request,400 所代表的,就是「前端的請求參數有錯誤」的意思。
舉例來說,當前端在請求後端的 API 時,如果前端的請求參數名字寫錯了、或是請求參數的格式有問題…等等,都可以被歸類在 400 這個 Http status code 中。
所以大家以後只要看到 400,通常就是前端請求的參數寫錯了,因此可以回頭檢查一下請求參數的設置是否正確。
再來是 401 和 403,通常他們兩個會一起介紹,因為他們是很容易被搞混的 Http staus code。
首先 401 所代表的,是「沒有通過身份驗證」的意思。
而 403 所代表的,則是「這一次的請求因為權限不足,所以被後端拒絕」。
舉例來說,大家可以把 401 想像成是會員的「身份驗證錯誤」,譬如說帳密輸入錯誤時,後端就會返回 401 的錯誤給前端,告訴前端「這個人並不是我們網站的會員」。
而 403 則是「權限不足」的意思,譬如說普通會員想要看 VIP 會員才能觀看的影片時,這時候後端就會返回 403 的錯誤給前端,告訴前端「這個會員的權限不足,所以我們不能讓他看 VIP 會員才能看的影片」。
所以簡單來說,當大家看到 401 的時候,就是表示「這個使用者根本不是我們家的會員」,而看到 403 的時候,就表示「這個會員沒有權限執行這個功能」。 因此 401 和 403 之間的差別,要再麻煩大家留意一下,這兩個真的很容易被搞混。
在 4 開頭的大類中,最後一個是 404 Not Found,而 404 所代表的,是「這個網頁不存在」的意思,通常就是由於 url 輸入錯誤、或是 url 失效(該資源被移走)所導致的。
404 也是一個生活中滿常碰到的 Http status code,有時候大家在網路上看文章的時候,偶爾會遇到 404 Not Found 的錯誤,就是因為這篇文章被刪除了,導致 url 失效,因此才會出現 404 的錯誤。
看完了 4 開頭的 Http status code 之後,最後我們可以來看一下 5 開頭的 Http status code 有哪些。
5 開頭的 Http status code 所代表的,都是「後端處理有問題」的意思。 也因為 5 開頭的大類是用來表示「後端處理有問題」的情況,因此 5 開頭的 Http status code 也可以說是後端工程師最不想看見的一類(因為看見了這個,通常就表示你或你同事要加班修 bug 了🥹),常見的有以下三個:
首先是 500 Internal Server Error,500 所代表的,是「後端在處理這次請求時,發生了錯誤」,這個錯誤有可能是因為後端程式出了 bug、或是其他的原因造成的。
500 是一個滿常見的 Http status code,通常只要看到 500,就表示是後端這邊有問題,所以後端工程師就得去檢查一下,是不是 Spring Boot 程式寫出 bug、或是伺服器出現問題…等等,所以一般來說,大家都很恐懼看到 500 這個 Http status code,因為這就表示後端這邊出問題了,需要後端工程師盡快解決。
再來是 503 Service Unavailable,503 所代表的,是「臨時維護或者流量太大,所以後端目前沒有辦法處理請求」。
因此當大家看到 503 的錯誤時,就可能是下面這兩種情況:
不過不管是哪一種情況,503 就都是表示後端程式目前沒辦法正常提供服務,因此前端在這段期間內,仍舊是無法正常 call API 的。
最後一個則是 504 Gateway Timeout,504 所代表的,是「這一次的請求超時了」。
所謂的「請求超時」,意思是「這一次 Http 請求花了太長的時間都還沒有完成,所以直接被強制結束」的意思。
因此當大家看到 504 時,就表示後端的內部系統出了問題,沒辦法在容許的時間內執行完所有程式,所以這時後端為了避免前端等太久,就會強制結束該程式,直接返回一個 504 的錯誤給前端,避免讓前端無止盡的等待。
所以總結上面的介紹的話,所謂的 Http status code,就是「用來表示這次 Http 請求的結果為何」,並且我們可以根據「首位數字」,將 Http status code 區分成 5 大類,分別是:
因此透過 Http Status Code,我們就可以快速的知道這一次 API 的請求結果為何了!
下圖也統整這篇文章中所提到的 Http Status Code 給大家參考:
這篇文章我們先介紹了 Http status code 的用途,並且詳細介紹了 Http status code 中的五個大類,以及常見的 Http status code 有哪些。
所以到這篇文章為止,有關 Spring MVC 的介紹就告一個段落了,在這個 Spring MVC 的部分中,我們介紹了以下內容:
@RequestParam
、@RequestBody
、@RequestHeader
、@PathVariable
這四種註解,去接住前端所傳過來的參數所以透過 Day 13~Day 23 的文章,我們就完成了 Spring MVC 的相關介紹了。
Spring MVC 可以說是在 Spring Boot 開發中非常重要的一環,因為 Spring MVC 掌控了前端和後端之間的溝通,所以只要 Spring MVC 的部分沒有寫好,就會使得前端沒辦法正常的請求後端的 API,進而導致前後端串接失敗。
因此也建議大家可以好好了解 Spring MVC 的用法,在實際的工作上是會非常有幫助的!
那麼從下一篇文章開始,我們就會進入到下一個部分:Spring JDBC,我們會接著來介紹要如何在 Spring Boot 中和「資料庫」進行溝通,那我們就下一篇文章見啦!
補充:本文是擷取自我開設的線上課程 Java 工程師必備!Spring Boot 零基礎入門 的內容,如果你想了解更多的 Spring Boot 的用法,歡迎參考課程簡介 (輸入折扣碼「HH202504KU」即可享 85 折優惠)。