編碼規(guī)范

2023-02-19 09:32 作者:小劉Java之路 0人讀過(guò) | 我要投稿

RESTful ?API

RESTful 是?種架構(gòu)設(shè)計(jì)?格。核?思想是?切皆資源。RESTful架構(gòu)中，將所有的東?都視為資源，每個(gè)資源對(duì)應(yīng)了?個(gè)URI（統(tǒng)?資源標(biāo)識(shí)符）所有的操作都是對(duì)資源的增刪改查，這些操作對(duì)應(yīng)了 HTTP 的 GET、POST、PUT、DELETE。

Endponits（端點(diǎn)）

端口是特定資源集合URL。在端點(diǎn)的設(shè)計(jì)中，你必須遵循下列約定：

URL 的命名必須 全部小寫(xiě)，多個(gè)單詞使用中橫線(xiàn)-連接，而不是使用下劃線(xiàn)-

瀏覽器中超鏈接顯示的默認(rèn)效果是，?字并附帶下劃線(xiàn)，如果API以 _ 隔斷單詞，?者會(huì)重疊，影響可讀性。

URL中的資料（resource）的命名必須是名詞，并且必須是復(fù)數(shù)形式
必須優(yōu)先使用RESTful類(lèi)型的URL
URL必須是易讀的。

在實(shí)際的項(xiàng)目開(kāi)發(fā)中，為了保證URL的全局統(tǒng)一，這里規(guī)定URL必須添加系統(tǒng)名，并且所有的URL必須使用

/api作為前綴。

如下所示：??

/api/<系統(tǒng)名>/< 資源名 >/<?資源名>

注意：

1.URL通常區(qū)別大小寫(xiě)（機(jī)器名稱(chēng)除外）參考W3C ? URL規(guī)范

2.Tomcat中URL就是區(qū)分大小寫(xiě)，URL參數(shù)同樣區(qū)分大小寫(xiě)。且URL格式驗(yàn)證非常格式。

舉例：

http://api.highzap.com/api/users 能正常訪(fǎng)問(wèn)。?地址：http://api.highzap.com//api/users （僅僅是多了?個(gè) “/”）訪(fǎng)問(wèn)時(shí)會(huì)響應(yīng)404 找不到此路徑。同樣的情況在 .NET寫(xiě)的?站中卻能正常訪(fǎng) 問(wèn)，且URL與參數(shù)都不區(qū)分??寫(xiě)。

HTTP 動(dòng)詞

客戶(hù)端對(duì)于資源的具體操作類(lèi)型（增刪改查），由 HTTP 動(dòng)詞表示。常?的 HTTP 動(dòng)詞有下?五個(gè)

GET （get） :從服務(wù)器取出資源（?項(xiàng)或多項(xiàng)）。
POST ?(post) :在服務(wù)器新建?個(gè)資源。
PUT ?(put) : 在服務(wù)器更新資源（客戶(hù)端提供改變后的完整資源）。
PATCH (patch): 在服務(wù)器更新資源（客戶(hù)端提供改變的屬性）。
DELETE (delete) : 從服務(wù)器刪除資源。

其中

1.刪除資源必須使? DELETE ?法

2.創(chuàng)建資源必須使? POST ?法

3.更新資源應(yīng)該使? PUT ?法

4.獲取資源信息必須使? GET ?法

針對(duì)每?個(gè)端點(diǎn)來(lái)說(shuō)，下?列出所有可?的 HTTP 動(dòng)詞和端點(diǎn)的組合

Java實(shí)現(xiàn)代碼參考 ?

https://www.yuque.com/docs/share/f28a24ea-32f8-4f03-8e1f-80e1dd84b27f?# 《Maven私服配置》

問(wèn)題：

能不能在我以前的maven的settings的配置中配置私服

Version （版本管理）

在URL中嵌入版本編號(hào)

這種做法是版本號(hào)直觀、易于調(diào)試，緩存友好。
1.這種做法是版本號(hào)直觀、易于調(diào)試，緩存友好。

Filter (資源過(guò)濾)

對(duì)于資源集合來(lái)說(shuō)，可以通過(guò)URL參數(shù)對(duì)其進(jìn)?過(guò)濾。

常見(jiàn)的過(guò)濾參數(shù)

??常見(jiàn)的過(guò)濾參數(shù)：

?limit=10：指定返回記錄的數(shù)量 ?offset=10：指定返回記錄的開(kāi)始位置。

?page=2&size=100：指定第??，以及每?的記錄數(shù)。

?sort_by=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序，以及排序順序。

?station_type_id=1：指定篩選條件

URL參數(shù)命名規(guī)范

所有 URL 參數(shù) 必須是全?寫(xiě)，必須使?下劃線(xiàn) _ 類(lèi)型的參數(shù)形式。

注意：是URL參數(shù)采取全?寫(xiě)的形式，多個(gè)單詞間使? "_" 分隔。

經(jīng)常使?的、復(fù)雜的查詢(xún) 應(yīng)該標(biāo)簽化，降低維護(hù)成本。如

1 ?列出未關(guān)閉的按照名稱(chēng)升序排列的交易信息

2 GET /trades?status=closed&sort=sortby=name&order=asc

3 # 可為其定制快捷?式

4 GET /trades/recently_closed

pagination (分頁(yè))

分?就是?種最典型的資源過(guò)濾，分?參數(shù)必須固定為 page 、 size 、其他參數(shù)。

JWT （Json Web Token）是?業(yè)普遍采?的?種認(rèn)證協(xié)議

客戶(hù)端在獲得 access_token 的同時(shí)在響應(yīng)中還包含?個(gè)名為 expires_in 的數(shù)據(jù)，它表示當(dāng)前 token 會(huì)在多少秒后失效， refresh_token 刷新令牌?于在 token 到期后重新獲取 token ，?般 refresh_token 的過(guò)期時(shí)間為?個(gè)?，? token 的過(guò)期時(shí)間則?較短。

{
2?"access_token":?"token ...",
3?"refresh_token":?"refresh_token ...",
4?"token_type":?"Bearer",
5?"expires_in":?3600
6?}

客戶(hù)端請(qǐng)求時(shí)攜帶Token

客戶(hù)端在請(qǐng)求需要認(rèn)證的 API 時(shí)，必須在請(qǐng)求頭 Authorization 中帶上 access_token 。

Authorization: Bearer ? <Token>

令牌過(guò)期/?效

當(dāng)使?過(guò)期/或?效的 token 訪(fǎng)問(wèn)時(shí)，服務(wù)端應(yīng)該返回 401 錯(cuò)誤碼。

1?HTTP/1.1?401?Unauthorized
2?Content-Type:?application/json
3?Cache-Control:?no-store
4?Pragma:?no-cache
5
6?{
7?"errcode":401001
8?"errmsg":?"?效的令牌"
9?}