Java開(kāi)發(fā) 前后端規(guī)約

\1. 【強(qiáng)制】前后端交互的 API，需要明確協(xié)議、域名、路徑、請(qǐng)求方法、請(qǐng)求內(nèi)容、狀態(tài)碼、響應(yīng)體。

• 說(shuō)明： 1） 協(xié)議：生產(chǎn)環(huán)境必須使用 HTTPS。 2） 路徑：每一個(gè) API 需對(duì)應(yīng)一個(gè)路徑，表示 API 具體的請(qǐng)求地址： a） 代表一種資源，只能為名詞，推薦使用復(fù)數(shù)，不能為動(dòng)詞，請(qǐng)求方法已經(jīng)表達(dá)動(dòng)作意義。 b） URL 路徑不能使用大寫(xiě)，單詞如果需要分隔，統(tǒng)一使用下劃線。 c） 路徑禁止攜帶表示請(qǐng)求內(nèi)容類(lèi)型的后綴，比如".json",".xml"，通過(guò) accept 頭表達(dá)即可。 3） 請(qǐng)求方法：對(duì)具體操作的定義，常見(jiàn)的請(qǐng)求方法如下： a） GET：從服務(wù)器取出資源。 b） POST：在服務(wù)器新建一個(gè)資源。 c） PUT：在服務(wù)器更新資源。 d） DELETE：從服務(wù)器刪除資源。 4） 請(qǐng)求內(nèi)容：URL 帶的參數(shù)必須無(wú)敏感信息或符合安全要求；body 里帶參數(shù)時(shí)必須設(shè)置 Content-Type。 5） 響應(yīng)體：響應(yīng)體 body 可放置多種數(shù)據(jù)類(lèi)型，由 Content-Type 頭來(lái)確定。

\2. 【強(qiáng)制】前后端數(shù)據(jù)列表相關(guān)的接口返回，如果為空，則返回空數(shù)組[]或空集合 {}。

• 說(shuō)明：此條約定有利于數(shù)據(jù)層面上的協(xié)作更加高效，減少前端很多瑣碎的 null 判斷。

\3. 【強(qiáng)制】服務(wù)端發(fā)生錯(cuò)誤時(shí)，返回給前端的響應(yīng)信息必須包含 HTTP 狀態(tài)碼，errorCode、errorMessage、用戶(hù)提示信息四個(gè)部分。

• 說(shuō)明：四個(gè)部分的涉眾對(duì)象分別是瀏覽器、前端開(kāi)發(fā)、錯(cuò)誤排查人員、用戶(hù)。其中輸出給用戶(hù)的提示信息

• 要求：簡(jiǎn)短清晰、提示友好，引導(dǎo)用戶(hù)進(jìn)行下一步操作或解釋錯(cuò)誤原因，提示信息可以包括錯(cuò)誤原因、上下文環(huán)境、推薦操作等。 errorCode：參考附表 3。errorMessage：簡(jiǎn)要描述后端出錯(cuò)原因，便于錯(cuò)誤排查人員快速定位問(wèn)題，注意不要包含敏感數(shù)據(jù)信息。

• 正例：常見(jiàn)的 HTTP 狀態(tài)碼如下 1） 200 OK: 表明該請(qǐng)求被成功地完成，所請(qǐng)求的資源發(fā)送到客戶(hù)端。 2） 401 Unauthorized: 請(qǐng)求要求身份驗(yàn)證，常見(jiàn)對(duì)于需要登錄而用戶(hù)未登錄的情況。 3） 403 Forbidden：服務(wù)器拒絕請(qǐng)求，常見(jiàn)于機(jī)密信息或復(fù)制其它登錄用戶(hù)鏈接訪問(wèn)服務(wù)器的情況。 4） 404 Not Found: 服務(wù)器無(wú)法取得所請(qǐng)求的網(wǎng)頁(yè)，請(qǐng)求資源不存在。 5） 500 Internal Server Error: 服務(wù)器內(nèi)部錯(cuò)誤。

\4. 【強(qiáng)制】在前后端交互的 JSON 格式數(shù)據(jù)中，所有的 key 必須為小寫(xiě)字母開(kāi)始的 lowerCamelCase 風(fēng)格，符合英文表達(dá)習(xí)慣，且表意完整。

• 正例：errorCode / errorMessage / assetStatus / menuList / orderList / configFlag

• 反例：ERRORCODE / ERROR_CODE / error_message / error-message / errormessage / ErrorMessage / msg

\5. 【強(qiáng)制】errorMessage 是前后端錯(cuò)誤追蹤機(jī)制的體現(xiàn)，可以在前端輸出到 type="hidden"文字類(lèi)控件中，或者用戶(hù)端的日志中，幫助我們快速地定位出問(wèn)題。

\6. 【強(qiáng)制】對(duì)于需要使用超大整數(shù)的場(chǎng)景，服務(wù)端一律使用 String 字符串類(lèi)型返回，禁止使用 Long 類(lèi)型。

• 說(shuō)明：Java 服務(wù)端如果直接返回 Long 整型數(shù)據(jù)給前端，JS 會(huì)自動(dòng)轉(zhuǎn)換為 Number 類(lèi)型（注：此類(lèi)型為雙精度浮點(diǎn)數(shù)，表示原理與取值范圍等同于 Java 中的 Double）。Long 類(lèi)型能表示的最大值是 2 的 63 次方-1，在取值范圍之內(nèi)，超過(guò) 2 的 53 次方 (9007199254740992)的數(shù)值轉(zhuǎn)化為 JS 的 Number 時(shí)，有些數(shù)值會(huì)有精度損失。擴(kuò)展說(shuō)明，在 Long 取值范圍內(nèi)，任何 2 的指數(shù)次整數(shù)都是絕對(duì)不會(huì)存在精度損失的，所以說(shuō)精度損失是一個(gè)概率問(wèn)題。若浮點(diǎn)數(shù)尾數(shù)位與指數(shù)位空間不限，則可以精確表示任何整數(shù)，但很不幸，雙精度浮點(diǎn)數(shù)的尾數(shù)位只有 52 位。

• 反例：通常在訂單號(hào)或交易號(hào)大于等于 16 位，大概率會(huì)出現(xiàn)前后端單據(jù)不一致的情況，比如，"orderId": 362909601374617692，前端拿到的值卻是: 362909601374617660。

\7. 【強(qiáng)制】HTTP 請(qǐng)求通過(guò) URL 傳遞參數(shù)時(shí)，不能超過(guò) 2048 字節(jié)。

• 說(shuō)明：不同瀏覽器對(duì)于 URL 的最大長(zhǎng)度限制略有不同，并且對(duì)超出最大長(zhǎng)度的處理邏輯也有差異，2048字節(jié)是取所有瀏覽器的最小值。

• 反例：某業(yè)務(wù)將退貨的商品 id 列表放在 URL 中作為參數(shù)傳遞，當(dāng)一次退貨商品數(shù)量過(guò)多時(shí)，URL 參數(shù)超長(zhǎng)，傳遞到后端的參數(shù)被截?cái)?，?dǎo)致部分商品未能正確退貨。

\8. 【強(qiáng)制】HTTP 請(qǐng)求通過(guò) body 傳遞內(nèi)容時(shí)，必須控制長(zhǎng)度，超出最大長(zhǎng)度后，后端解析會(huì)出錯(cuò)。

• 說(shuō)明：nginx 默認(rèn)限制是 1MB，tomcat 默認(rèn)限制為 2MB，當(dāng)確實(shí)有業(yè)務(wù)需要傳較大內(nèi)容時(shí)，可以通過(guò)調(diào)大服務(wù)器端的限制。

\9. 【強(qiáng)制】在翻頁(yè)場(chǎng)景中，用戶(hù)輸入?yún)?shù)的小于 1，則前端返回第一頁(yè)參數(shù)給后端；后端發(fā)現(xiàn)用戶(hù)輸入的參數(shù)大于總頁(yè)數(shù)，直接返回最后一頁(yè)。

\10. 【強(qiáng)制】服務(wù)器內(nèi)部重定向必須使用 forward；外部重定向地址必須使用 URL 統(tǒng)一代理模塊生成，否則會(huì)因線上采用 HTTPS 協(xié)議而導(dǎo)致瀏覽器提示“不安全”，并且還會(huì)帶來(lái) URL 維護(hù)不一致的問(wèn)題。

\11. 【推薦】服務(wù)器返回信息必須被標(biāo)記是否可以緩存，如果緩存，客戶(hù)端可能會(huì)重用之前的請(qǐng)求結(jié)果。

• 說(shuō)明：緩存有利于減少交互次數(shù)，減少交互的平均延遲。

• 正例：http 1.1 中，s-maxage 告訴服務(wù)器進(jìn)行緩存，時(shí)間單位為秒，用法如下，

response.setHeader("Cache-Control", "s-maxage=" + cacheSeconds);

\12. 【推薦】服務(wù)端返回的數(shù)據(jù)，使用 JSON 格式而非 XML。

說(shuō)明：盡管 HTTP 支持使用不同的輸出格式，例如純文本，JSON，CSV，XML，RSS 甚至 HTML。如果我們使用的面向用戶(hù)的服務(wù)，應(yīng)該選擇 JSON 作為通信中使用的標(biāo)準(zhǔn)數(shù)據(jù)交換格式，包括請(qǐng)求和響應(yīng)。此外，application/JSON 是一種通用的 MIME 類(lèi)型，具有實(shí)用、精簡(jiǎn)、易讀的特點(diǎn)。

\13. 【推薦】前后端的時(shí)間格式統(tǒng)一為"yyyy-MM-dd HH:mm:ss"，統(tǒng)一為 GMT。

14.【參考】在接口路徑中不要加入版本號(hào)，版本控制在 HTTP 頭信息中體現(xiàn)，有利于向前兼容。

• 說(shuō)明：當(dāng)用戶(hù)在低版本與高版本之間反復(fù)切換工作時(shí)，會(huì)導(dǎo)致遷移復(fù)雜度升高，存在數(shù)據(jù)錯(cuò)亂風(fēng)險(xiǎn)。