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

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

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

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

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

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

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

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

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

\4. 【強(qiáng)制】在前后端交互的 JSON 格式數(shù)據(jù)中，所有的 key 必須為小寫字母開始的 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"文字類控件中，或者用戶端的日志中，幫助我們快速地定位出問題。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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