目錄

Day 23 - Http Status Code(Http 狀態碼)介紹

古古

2024/07/23


哈囉大家好,我是古古。

在上一篇文章中,我們有介紹要如何去設計和實作 RESTful API,因此大家就可以透過前面所學到的內容,實際的在 Spring Boot 中實作出 RESTful API 出來了。

那麼接著這篇文章,我們就會回頭來介紹一下 Http response 中也很重要的一個部分,也就是 Http status code(Http 狀態碼),所以我們就開始吧!

什麼是 Http status code(Http 狀態碼)? #

Http status code 又稱為 Http 狀態碼,他是屬於 Http response 的一部分,而 Http status code 的用途,就是「用來表示這次 Http 請求的結果為何」。

所以簡單來說,Http status code 就是會透過一個簡短的數字,呈現這一次請求結果為何,因此前端就可以透過 Http status code,快速的知道這一次的 Http 請求是成功還是失敗了。

Http status code 中的分類 #

在 Http status code 的世界中,可以根據「首位數字」,分成 5 個大類,分別是:

  • 1xx:資訊
  • 2xx:成功
  • 3xx:重新導向
  • 4xx:前端請求錯誤
  • 5xx:後端處理有問題

而在每一個大類中,可以再去細分出更多的 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,如果大家在工作上遇到比較罕見的 Http status code 時,可以再上網查詢一下相關的含義。

1xx:資訊 #

首先我們先從 1 開頭的大類開始看起,1 開頭的 Http status code 代表的是「取得資訊」的意思。

不過因為在實際的應用中,1 開頭的 Http status code 非常少用,因此在這個大類中,就沒有常見的 Http status code。

2xx:成功(200、201、202) #

看完了 1 開頭的大類,接著我們可以看 2 開頭的大類。

2 開頭的 http status code 所代表的,就都是「請求成功」的意思。 而 2 開頭的 Http status code,他們在使用上可以說是非常頻繁了,常見的有以下三個:

200 OK #

首先第一個是 200 OK,200 所代表的,就是「這一次的 Http 請求成功了」。

200 可以說是使用最廣泛的一個 Http status code,通常只要看到 200,就表示這一次的請求成功了(特殊情境例外),因此 200 可以說是工程師裡面的天使等級的角色。

201 Created #

接著是 201 Created,201 所代表的,不僅是這一次的 Http 請求成功而已,他還額外表示「有一個新的資源成功的被創建了」的含義。

也因為 201 除了表示請求成功之外,還多表示了「創建資源成功」的含義,因此 201 通常會被用在 POST 請求的 response 中(因為 REST 風格中的 POST 就是對應到資料庫的創建操作)。

202 Accepted #

最後一個則是 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 時,也可以參考他的短語描述。

3xx:重新導向 #

看完了 2 開頭的 Http status code,接著我們可以來看 3 開頭的大類。

3 開頭的 http status code 所代表的,都是「重新導向」的意思。 而在 3 開頭的大類中,常見的有以下兩個:

301 Moved Permanently #

首先是 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 #

而至於 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 中,供前端存取新網址。

4xx:前端請求錯誤 #

看完了 3 開頭的大類之後,接著我們也可以繼續來看 4 開頭的 Http status code 的含義。

4 開頭的 Http status code 所代表的,都是「前端請求錯誤」的意思。 4 開頭的大類在使用上的頻率也很高,常見的有以下四個:

400 Bad Request #

首先是 400 Bad Request,400 所代表的,就是「前端的請求參數有錯誤」的意思。

舉例來說,當前端在請求後端的 API 時,如果前端的請求參數名字寫錯了、或是請求參數的格式有問題…等等,都可以被歸類在 400 這個 Http status code 中。

所以大家以後只要看到 400,通常就是前端請求的參數寫錯了,因此可以回頭檢查一下請求參數的設置是否正確。

401 Unauthorized、403 Forbidden #

再來是 401 和 403,通常他們兩個會一起介紹,因為他們是很容易被搞混的 Http staus code。

首先 401 所代表的,是「沒有通過身份驗證」的意思。

而 403 所代表的,則是「這一次的請求因為權限不足,所以被後端拒絕」。

舉例來說,大家可以把 401 想像成是會員的「身份驗證錯誤」,譬如說帳密輸入錯誤時,後端就會返回 401 的錯誤給前端,告訴前端「這個人並不是我們網站的會員」。

而 403 則是「權限不足」的意思,譬如說普通會員想要看 VIP 會員才能觀看的影片時,這時候後端就會返回 403 的錯誤給前端,告訴前端「這個會員的權限不足,所以我們不能讓他看 VIP 會員才能看的影片」。

所以簡單來說,當大家看到 401 的時候,就是表示「這個使用者根本不是我們家的會員」,而看到 403 的時候,就表示「這個會員沒有權限執行這個功能」。 因此 401 和 403 之間的差別,要再麻煩大家留意一下,這兩個真的很容易被搞混。

404 Not Found #

在 4 開頭的大類中,最後一個是 404 Not Found,而 404 所代表的,是「這個網頁不存在」的意思,通常就是由於 url 輸入錯誤、或是 url 失效(該資源被移走)所導致的。

404 也是一個生活中滿常碰到的 Http status code,有時候大家在網路上看文章的時候,偶爾會遇到 404 Not Found 的錯誤,就是因為這篇文章被刪除了,導致 url 失效,因此才會出現 404 的錯誤。

5xx:後端處理有問題 #

看完了 4 開頭的 Http status code 之後,最後我們可以來看一下 5 開頭的 Http status code 有哪些。

5 開頭的 Http status code 所代表的,都是「後端處理有問題」的意思。 也因為 5 開頭的大類是用來表示「後端處理有問題」的情況,因此 5 開頭的 Http status code 也可以說是後端工程師最不想看見的一類(因為看見了這個,通常就表示你或你同事要加班修 bug 了🥹),常見的有以下三個:

500 Internal Server Error #

首先是 500 Internal Server Error,500 所代表的,是「後端在處理這次請求時,發生了錯誤」,這個錯誤有可能是因為後端程式出了 bug、或是其他的原因造成的。

500 是一個滿常見的 Http status code,通常只要看到 500,就表示是後端這邊有問題,所以後端工程師就得去檢查一下,是不是 Spring Boot 程式寫出 bug、或是伺服器出現問題…等等,所以一般來說,大家都很恐懼看到 500 這個 Http status code,因為這就表示後端這邊出問題了,需要後端工程師盡快解決。

503 Service Unavailable #

再來是 503 Service Unavailable,503 所代表的,是「臨時維護或者流量太大,所以後端目前沒有辦法處理請求」。

因此當大家看到 503 的錯誤時,就可能是下面這兩種情況:

  • 瞬間流量太高,導致後端伺服器忙不過來,使得後端程式沒辦法正常運作
  • 後端程式剛好處在維護期間

不過不管是哪一種情況,503 就都是表示後端程式目前沒辦法正常提供服務,因此前端在這段期間內,仍舊是無法正常 call API 的。

504 Gateway Timeout #

最後一個則是 504 Gateway Timeout,504 所代表的,是「這一次的請求超時了」。

所謂的「請求超時」,意思是「這一次 Http 請求花了太長的時間都還沒有完成,所以直接被強制結束」的意思。

因此當大家看到 504 時,就表示後端的內部系統出了問題,沒辦法在容許的時間內執行完所有程式,所以這時後端為了避免前端等太久,就會強制結束該程式,直接返回一個 504 的錯誤給前端,避免讓前端無止盡的等待。

常用的 Http status code 總結 #

所以總結上面的介紹的話,所謂的 Http status code,就是「用來表示這次 Http 請求的結果為何」,並且我們可以根據「首位數字」,將 Http status code 區分成 5 大類,分別是:

  • 1xx:資訊
  • 2xx:成功
  • 3xx:重新導向
  • 4xx:前端請求錯誤
  • 5xx:後端處理有問題

因此透過 Http Status Code,我們就可以快速的知道這一次 API 的請求結果為何了!

下圖也統整這篇文章中所提到的 Http Status Code 給大家參考:

總結 #

這篇文章我們先介紹了 Http status code 的用途,並且詳細介紹了 Http status code 中的五個大類,以及常見的 Http status code 有哪些。

所以到這篇文章為止,有關 Spring MVC 的介紹就告一個段落了,在這個 Spring MVC 的部分中,我們介紹了以下內容:

  • 「Http 協議」和「JSON 格式」的用法,了解前後端的溝通方式有哪些
  • 常見的 Http method(GET 和 POST)的用法
  • 如何透過 @RequestParam@RequestBody@RequestHeader@PathVariable 這四種註解,去接住前端所傳過來的參數
  • 如何設計 RESTful API、如何在 Spring Boot 中實作 RESTful API
  • 常見的 Http status code 有哪些

所以透過 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 折優惠)。