• 易于在服務(wù)器端解析。 URL 參數(shù)鍵包含字段名稱和運(yùn)算符。無(wú)需查看 URL 參數(shù)值即可輕松（屬性名稱、運(yùn)算符）。 GROUP BY
• 當(dāng)運(yùn)算符被用作文字過(guò)濾器術(shù)語(yǔ)時(shí)，無(wú)需轉(zhuǎn)義過(guò)濾器值中的特殊字符。當(dāng)您的過(guò)濾器包含用戶可能設(shè)置的其他自定義元數(shù)據(jù)字段時(shí)尤其如此。

缺點(diǎn)

• 可能需要在服務(wù)器端進(jìn)行更多工作來(lái)解析和分組過(guò)濾器。您可能需要編寫自定義 URL 參數(shù)綁定器或解析器來(lái)將查詢字符串鍵拆分為兩個(gè)部分：字段名稱和運(yùn)算符。然后您需要（屬性名稱，運(yùn)營(yíng)商）。 GROUP BY
• 變量名中的特殊字符可能會(huì)很尷尬。您可能需要編寫一個(gè)自定義綁定器來(lái)將查詢字符串鍵拆分為兩個(gè)部分：字段名稱和運(yùn)算符。
• 難以管理自定義組合過(guò)濾器。具有相同屬性名稱和運(yùn)算符的多個(gè)過(guò)濾器會(huì)產(chǎn)生隱式 AND。如果 API 用戶想要對(duì)過(guò)濾器進(jìn)行“或”操作該怎么辦？即查找價(jià)格小于 10 或大于 100 的所有商品？

冒號(hào)

與括號(hào)方法類似，您可以設(shè)計(jì)一個(gè) API 將運(yùn)算符置于 RHS（而不是 LHS）上。例如，將查找價(jià)格大于或等于 10，但小于或等于 100 的所有商品。 GET /items?price=gte:10&price=lte:100

好處

• 在服務(wù)器端最容易解析，特別是在不支持重復(fù)過(guò)濾器的情況下。不需要定制活頁(yè)夾。許多 API 框架已經(jīng)可以處理 URL 參數(shù)數(shù)組。多個(gè)價(jià)格過(guò)濾器將位于同一變量“價(jià)格”下，該變量可以是序列或映射。

缺點(diǎn)

• 文字值需要特殊處理。例如，將轉(zhuǎn)換為查找 user_id 大于 100 的所有項(xiàng)目。但是，如果我們想要查找 user_id 等于 gt:100 的所有項(xiàng)目（因?yàn)檫@可能是有效 ID）怎么辦？ GET /items?user_id=gt:100

搜索查詢參數(shù)

如果您需要在端點(diǎn)上進(jìn)行搜索，您可以直接使用搜索參數(shù)添加對(duì)過(guò)濾器和范圍的支持。如果您已經(jīng)在使用 ElasticSearch 或其他基于 Lucene 的技術(shù)，您可以直接支持 Lucene 語(yǔ)法或 ElasticSearch 簡(jiǎn)單查詢字符串。

例如，我們可以搜索包含術(shù)語(yǔ) red chair 且價(jià)格大于或等于 10 且小于或等于 100 的商品： GET /items?q=title:red chair AND price:[10 TO 100]

此類 API 可以允許模糊匹配、增強(qiáng)某些術(shù)語(yǔ)等等。

好處

• 為API用戶提供最靈活的查詢
• 后端幾乎不需要解析，可以直接傳遞到搜索引擎或數(shù)據(jù)庫(kù)（只是要小心清理輸入以確保安全）

缺點(diǎn)

• 對(duì)于初學(xué)者來(lái)說(shuō)，開始使用 API 比較困難。需要熟悉Lucene語(yǔ)法。
• 全文搜索并不適用于所有資源。例如，模糊性和術(shù)語(yǔ)提升對(duì)于時(shí)間序列指標(biāo)數(shù)據(jù)沒(méi)有意義。
• 需要 URL 百分比編碼，這使得使用 cURL 或 Postman 更加復(fù)雜。

分頁(yè)

大多數(shù)返回實(shí)體列表的端點(diǎn)都需要某種分頁(yè)。

如果沒(méi)有分頁(yè)，簡(jiǎn)單的搜索可能會(huì)返回?cái)?shù)百萬(wàn)甚至數(shù)十億的點(diǎn)擊量，從而導(dǎo)致額外的網(wǎng)絡(luò)流量。

分頁(yè)需要隱式排序。默認(rèn)情況下，這可能是項(xiàng)目的唯一標(biāo)識(shí)符，但也可以是其他有序字段，例如創(chuàng)建日期。

偏移分頁(yè)

這是最簡(jiǎn)單的分頁(yè)形式。限制/偏移在使用 SQL 數(shù)據(jù)庫(kù)的應(yīng)用程序中變得流行，這些數(shù)據(jù)庫(kù)已經(jīng)將 LIMIT 和 OFFSET 作為 SQL SELECT 語(yǔ)法的一部分。實(shí)現(xiàn)限制/偏移分頁(yè)只需要很少的業(yè)務(wù)邏輯。

限制/偏移分頁(yè)看起來(lái)像。此查詢將返回從第 100 行開始的 20 行。 GET /items?limit=20&offset=100

例子

（假設(shè)查詢按創(chuàng)建日期降序排序）

1. 客戶請(qǐng)求最近的項(xiàng)目： GET /items?limit=20
2. 在滾動(dòng)/下一頁(yè)上，客戶端發(fā)出第二個(gè)請(qǐng)求 GET /items?limit=20&offset=20
3. 在滾動(dòng)/下一頁(yè)上，客戶端發(fā)出第三個(gè)請(qǐng)求 GET /items?limit=20&offset=40

作為 SQL 語(yǔ)句，第三個(gè)請(qǐng)求如下所示：

SELECT

    *

FROM

    Items

ORDER BY Id

LIMIT 20

OFFSET 40;

好處

• 最容易實(shí)現(xiàn)，除了直接將參數(shù)傳遞給 SQL 查詢之外幾乎不需要任何編碼。
• 服務(wù)器上無(wú)狀態(tài)。
• 無(wú)論自定義 sort_by 參數(shù)如何，都可以工作。

缺點(diǎn)

• 對(duì)于大偏移值來(lái)說(shuō)效果不佳。假設(shè)您執(zhí)行一個(gè)具有較大偏移值 1000000 的查詢。數(shù)據(jù)庫(kù)需要掃描并計(jì)算從 0 開始的行，并且將跳過(guò)（即丟棄數(shù)據(jù)）前 1000000 行。
• 當(dāng)新項(xiàng)目插入到表中時(shí)不一致（即頁(yè)面漂移），當(dāng)我們按最新的優(yōu)先順序?qū)?xiàng)目進(jìn)行排序時(shí)，這一點(diǎn)尤其明顯。考慮以下通過(guò)減小 Id 進(jìn)行排序的情況：
  1. 查詢 GET /items?offset=0&limit=15
  2. 表中添加了 10 個(gè)新項(xiàng)目
  3. 查詢 第二個(gè)查詢將僅返回 5 個(gè)新項(xiàng)目，因?yàn)樘砑?10 個(gè)新項(xiàng)目會(huì)將偏移量向后移動(dòng) 10 個(gè)項(xiàng)目。為了解決這個(gè)問(wèn)題，客戶端確實(shí)需要為第二個(gè)查詢偏移 25，但客戶端不可能知道插入到表中的其他對(duì)象。 GET /items?offset=15&limit=15GET /items?offset=25&limit=15

即使有限制，偏移分頁(yè)也很容易實(shí)現(xiàn)和理解，并且可以用于數(shù)據(jù)集上限較小的應(yīng)用程序。

鍵集分頁(yè)

鍵集分頁(yè)使用最后一頁(yè)的過(guò)濾器值來(lái)獲取下一組項(xiàng)目。這些列將被索引。

例子

（假設(shè)查詢按創(chuàng)建日期降序排序）

1. 客戶請(qǐng)求最近的項(xiàng)目： GET /items?limit=20
2. 在滾動(dòng)/下一頁(yè)上，客戶端從之前返回的結(jié)果中找到最小創(chuàng)建日期 2021-01-20T00:00:00。然后使用日期作為過(guò)濾器進(jìn)行第二個(gè)查詢： GET /items?limit=20&created:lte:2021-01-20T00:00:00
3. 在滾動(dòng)/下一頁(yè)上，客戶端從之前返回的結(jié)果中找到最小創(chuàng)建日期 2021-01-19T00:00:00。然后使用日期作為過(guò)濾器進(jìn)行第三次查詢： GET /items?limit=20&created:lte:2021-01-19T00:00:00

SELECT

    *

FROM

    Items

WHERE

  created <= '2021-01-20T00:00:00'

ORDER BY Id

LIMIT 20

好處

• 可與現(xiàn)有過(guò)濾器配合使用，無(wú)需額外的后端邏輯。只需要一個(gè)額外的限制URL參數(shù)。
• 即使將新項(xiàng)目插入表中，也能保持一致的順序。按最新的優(yōu)先排序時(shí)效果很好。
• 即使偏移較大，也能保持一致的性能。

缺點(diǎn)

• 分頁(yè)機(jī)制與過(guò)濾器和排序緊密耦合。即使不打算使用過(guò)濾器，也會(huì)強(qiáng)制 API 用戶添加過(guò)濾器。
• 不適用于低基數(shù)字段，例如枚舉字符串。
• 使用自定義 sort_by 字段時(shí)，API 用戶會(huì)很復(fù)雜，因?yàn)榭蛻舳诵枰鶕?jù)用于排序的字段調(diào)整過(guò)濾器。

鍵集分頁(yè)對(duì)于具有單個(gè)自然高基數(shù)鍵的數(shù)據(jù)非常有效，例如可以使用時(shí)間戳的時(shí)間序列或日志數(shù)據(jù)。

查找分頁(yè)

查找分頁(yè)是鍵集分頁(yè)的擴(kuò)展。通過(guò)添加 after_id 或 start_id URL 參數(shù)，我們可以消除分頁(yè)與過(guò)濾器和排序的緊密耦合。由于唯一標(biāo)識(shí)符本質(zhì)上是高基數(shù)，因此我們不會(huì)遇到與按低基數(shù)字段（如狀態(tài)枚舉或類別名稱）排序不同的問(wèn)題。

基于搜索的分頁(yè)的問(wèn)題是當(dāng)需要自定義排序順序時(shí)很難實(shí)現(xiàn)。

例子

（假設(shè)查詢按創(chuàng)建日期升序排序）

1. 客戶請(qǐng)求最近的項(xiàng)目： GET /items?limit=20
2. 在滾動(dòng)/下一頁(yè)上，客戶端從之前返回的結(jié)果中找到最后一個(gè) id“20”。然后使用它作為起始 id 進(jìn)行第二次查詢： GET /items?limit=20&after_id=20
3. 在滾動(dòng)/下一頁(yè)上，客戶端從之前返回的結(jié)果中找到最后一個(gè) id“40”。然后使用它作為起始 id 進(jìn)行第三次查詢： GET /items?limit=20&after_id=40

尋求分頁(yè)可以被提煉成一個(gè)子句 where

SELECT

    *

FROM

    Items

WHERE

  Id > 20

LIMIT 20

如果按 id 排序，上面的示例可以正常工作，但如果我們想按電子郵件字段排序怎么辦？對(duì)于每個(gè)請(qǐng)求，后端需要首先獲取標(biāo)識(shí)符與 after_id 匹配的項(xiàng)目的電子郵件值。然后，使用該值作為過(guò)濾器執(zhí)行第二個(gè)查詢。 where

讓我們考慮一下查詢，后端將需要兩個(gè)查詢。第一個(gè)查詢可能是使用哈希表進(jìn)行 O(1) 查找，以獲得電子郵件數(shù)據(jù)透視值。將此輸入到第二個(gè)查詢中，以僅檢索電子郵件位于 after_email 之后的項(xiàng)目。我們按電子郵件和 ID 兩列進(jìn)行排序，以確保在兩封電子郵件相同的情況下有穩(wěn)定的排序。這對(duì)于較低基數(shù)字段至關(guān)重要。 GET /items?limit=20&after_id=20&sort_by=email

1.

SELECT

    email AS AFTER_EMAIL

FROM

    Items

WHERE

  Id = 20

2.

SELECT

    *

FROM

    Items

WHERE

  Email >= [AFTER_EMAIL]

ORDER BY Email, Id

LIMIT 20

好處

• 分頁(yè)邏輯與過(guò)濾邏輯沒(méi)有耦合。
• 即使將新項(xiàng)目插入表中，也能保持一致的順序。按最新的優(yōu)先排序時(shí)效果很好。
• 即使偏移較大，也能保持一致的性能。

缺點(diǎn)

• 相對(duì)于基于偏移或基于鍵集的分頁(yè)，后端實(shí)現(xiàn)更復(fù)雜
• 如果從數(shù)據(jù)庫(kù)中刪除項(xiàng)目，則 start_id 可能不是有效的 ID。

Seek 分頁(yè)是一個(gè)很好的整體分頁(yè)策略，也是我們?cè)?Moesif Public API 上實(shí)現(xiàn)的。它需要在后端進(jìn)行更多的工作，但確保不會(huì)給 API 的客戶端/用戶增加額外的復(fù)雜性，同時(shí)即使在更大的搜索范圍內(nèi)也能保持性能。

排序

與過(guò)濾一樣，排序?qū)τ谌魏畏祷卮罅繑?shù)據(jù)的 API 端點(diǎn)來(lái)說(shuō)都是一項(xiàng)重要功能。如果您要返回用戶列表，您的 API 用戶可能希望按上次修改日期或電子郵件進(jìn)行排序。

為了啟用排序，許多 API 添加了 sort 或 sort_by URL 參數(shù)，該參數(shù)可以將字段名稱作為值。

然而，良好的 API 設(shè)計(jì)可以靈活地指定升序或降序。與過(guò)濾器一樣，指定順序需要將三個(gè)組件編碼為鍵/值對(duì)。

格式示例

• GET /users?sort_by=asc(email) 和 GET /users?sort_by=desc(email)
• GET /users?sort_by=+email 和 GET /users?sort_by=-email
• GET /users?sort_by=email.asc 和 GET /users?sort_by=email.desc
• GET /users?sort_by=email&order_by=asc 和 GET /users?sort_by=email&order_by=desc

多列排序

不建議使用排序和順序不配對(duì)的最后一種設(shè)計(jì)。您最終可能允許按兩列或更多列排序：

SELECT

    email

FROM

    Items

ORDER BY Last_Modified DESC, Email ASC

LIMIT 20

要編碼此多列排序，您可以允許多個(gè)字段名稱，例如

GET /users?sort_by=desc(last_modified),asc(email) 或

GET /users?sort_by=-last_modified,+email

如果排序字段和排序不配對(duì)，則需要保留 URL 參數(shù)排序；否則，什么排序應(yīng)該與什么字段名稱配對(duì)是不明確的。然而，許多服務(wù)器端框架在反序列化到映射后可能不會(huì)保留順序。

您還必須確保任何緩存鍵都考慮 URL 參數(shù)排序，但這會(huì)給緩存大小帶來(lái)壓力。

結(jié)論

良好的 API 設(shè)計(jì)是開發(fā)者體驗(yàn) (DX) 的關(guān)鍵組成部分。 API 規(guī)范可以比許多底層服務(wù)器實(shí)現(xiàn)更持久，這需要考慮 API 的未來(lái)用例。

原文鏈接：REST API Design: Filtering, Sorting, and Pagination