Memcached通信協議(中文版)

                                                       memcache通信協議

協議
關鍵字 Keys
命令Commands
超時時間 Expiration times
錯誤信息 Error strings
存儲命令 Storage commands
讀取命令 Retrieval command
刪除 Deletion
增加/減少 Increment/Decrement
統計 Statistics
多用途統計 General-purpose statistics
其他命令 Other commands
UDP協議 UDP protocol

協議

       memcached的客戶端通過TCP連接與服務器通信（UDP協議的接口也可以使用，詳細說明請參考”UDP 協議”部分）。一個給定的運行中的memcached服務器在某個（可配置的）端口上監聽連接；客戶端連接該端口，發送命令給服務器，讀取反饋，最後關閉連接。

       沒有必要發送一個專門的命令去結束會話。客戶端可以在不需要該連接的時候就關閉它。注意：我們鼓勵客戶端緩存它們與服務器的連接，而不是每次要存儲或讀取數據的時候再次重新建立與服務器的連接。memcache同時打開很多連接不會對性能造成到大的影響，這是因爲memcache在設計之處，就被設計成即使打開了很多連接（數百或者需要時上千個連接）也可以高效的運行。緩存連接可以節省與服務器建立TCP連接的時間開銷（於此相比，在服務器段爲建立一個新的連接所做準備的開銷可以忽略不計）。

       memcache通信協議有兩種類型的數據：文本行和非結構化數據。文本行用來發送從客戶端到服務器的命令以及從服務器回送的反饋信息。非結構化的數據用在客戶端希望存儲或者讀取數據時。服務器會以字符流的形式嚴格準確的返回相應數據在存儲時存儲的數據。服務器不關注字節序，它也不知道字節序的存在。memcahce對非結構化數據中的字符沒有任何限制，可以是任意的字符，讀取數據時，客戶端可以在前次返回的文本行中確切的知道接下來的數據塊的長度。

       文本行通常以“"r"n”結束。非結構化數據通常也是以“"r"n”結束，儘管"r、"n或者其他任何8位字符可以出現在數據塊中。所以當客戶端從服務器讀取數據時，必須使用前面提供的數據塊的長度，來確定數據流的結束，二不是依據跟隨在字符流尾部的“"r"n”來確定數據流的結束，儘管實際上數據流格式如此。

關鍵字 Keys

memcached使用關鍵字來區分存儲不同的數據。關鍵字是一個字符串，可以唯一標識一條數據。當前關鍵字的長度限制是250個字符（當然目前客戶端似乎沒有需求用這麼長的關鍵字）；關鍵字一定不能包含控制字符和空格。

命令Commands

memcahe有3種類型的命令：

l         存儲命令—（3個命令：set、add和replace）要求服務器安裝關鍵字存儲數據。客戶端發送一個命令行，然後一個數據塊；命令執行後客戶端等待一行反饋，用來表示命令執行成功與否。

l         讀取命令-- （只有1個命令：get）要求服務器根據一組關鍵字讀取數據（在一個請求總可以包含一個或多個關鍵字）。客戶端發送一個包含請求關鍵字的命令行；命令傳遞到服務器後，服務器就查找每一個關鍵字下的數據，然戶將數據以“一個關鍵字數據，一個反饋信息行跟着一個數據塊”的格式回送數據，直到服務器發送“END”的反饋行。

l         其他命令，如flush_all，version等。這些命令不使用非結構化的數據。對於這些命令，客戶端發送一個文本的命令行，根據命令的特性等待一行數據或者在最後一行以“END“結尾的幾行反饋信息。

所有的命令行總是以命令的名字開始，緊接着是以空格分割的參數。命令名稱都是小寫，並且是大小寫敏感的。

超時時間 Expiration times

       一些發送到服務器的命令包含超時時間（該超時時間對應於：數據項保存時間；客戶端操作限時）。在這些例子中，被髮送的真實時間要麼是UNIX時間戳（自1970年1月1日零時起的秒數數值），或者從當前時間開始算起的秒數。對於後一種情況，秒數的數值不能超過60*60*24*30（30天的秒數）；如果秒數的數值大於了這個數值，服務器會認爲該數值是UNIX時間戳，而不是自當前時間開始的秒數偏移值。

錯誤信息 Error strings

       每個命令都有可能被反饋以一個錯誤消息。這些錯誤消息有以下三個類型：

l         “ERROR"r"n” 

意味着客戶端發送了一個在協議中不存在的命令。

l         "CLIENT_ERROR <error>"r"n"

表示客戶端輸入的命令行上存在某種錯誤，輸入不符合協議規定。<error>是一個人工可讀（human-readable）的錯誤註釋。

l         "SERVER_ERROR <error>"r"n"

表示服務器在執行命令時發生了某些錯誤，致使服務器無法執行下去。<error>也是一個人工可讀（human-readable）的錯誤註釋。在一些情況下，錯誤導致服務器不能再爲客戶端服務（這樣的情況很少發生），服務器就會在發生錯誤消息後主動關閉連接。這也是服務器主動關閉到客戶端連接的唯一情況。

       後續秒數各種命令的時候，我們不再贅述錯誤消息的情況，當我們要清楚錯誤是存在的，不可忽略。

存儲命令 Storage commands

       首先，客戶端發生如下這樣的命令：

<command name> <key> <flags> <exptime> <bytes>"r"n

<data block>"r"n

其中：

<command name> 是 set、add或者replace。set表示存儲該數據；add表示如果服務器沒有保存該關鍵字的情況下，存儲該數據；replace表示在服務器已經擁有該關鍵字的情況下，替換原有內容。

<key>是客戶端要求服務器存儲數據的關鍵字。

<flags>是一個16位的無符號整數，服務器將它和數據一起存儲並且當該數據被檢索時一起返回。客戶端可能使用該數值作爲一個位圖來存儲特殊數據信息；這個字段對服務器不是透明的。

<exptime>是超時時間。如果值爲0表示該數據項永遠不超時（但有時候該數據項可能被刪除以爲其他數據騰出空間）；如果值不爲0，可能是絕對的UNIX時間，也可能是自現在開始的偏移值，它保證客戶段在這個超時時間到達後，客戶端將取不到該數據項。

<bytes>是隨後數據的字節數，不包括終結符”"r"n”。<bytes>有可能是0，它後面將是一個空的數據塊。

<data block>是真正要存儲數據流。

       發送命令行和數據後，客戶端等待反饋，可以是如下幾種情況：

l         "STORED"r"n"              表示存儲數據成功。

l         "NOT_STORED"r"n"    表示發送的數據沒有存儲，但這不因爲錯誤，而是發生在add或者replace命令不能滿足條件時，或者數據項正處於要刪除的隊列中。

l         錯誤消息

讀取命令 Retrieval command:

       讀取命令如下所示：

get <key>*"r"n

<key>*表示一個或多個使用空格分割的關鍵字字符串。

       發送命令後，客戶端等待返回一個或多個數據項，每個數據項的格式是一個文本行，後跟着一個數據塊。當所有的數據項發送完畢後，服務器發送字符串”END"r"n”表示服務器反饋數據的結束。

       返回數據項的格式如下：

VALUE <key> <flags> <bytes>"r"n

<data block>"r"n

<key>是發生數據項的關鍵字。

       <flags>是存儲該數據項時，客戶端命令中的標誌字段。

       <bytes>是緊跟文本行後數據塊的長度，不包括終結符”"r"n”。

<data block>是數據項的數據部分。

       如果請求命令行中的有些關鍵字對應的數據項沒有被返回，這意味着服務器沒有該關鍵字標示下的數據項（有可能是從來沒有被存儲過，或者存儲過但被刪除掉以騰出內存空間，或者數據項超時了，再或者它被某個客戶端刪除了）。

刪除 Deletion

刪除命令允許直接刪除數據項，命令格式如下：

delete <key> <time>"r"n

<key>是客戶端希望服務器刪除數據項的關鍵字

<time>是客戶端希望服務器阻止add和replace命令使用該關鍵字數據項的秒數，可以是相對時間也可以是UNIX的絕對時間。在這段時間內，數據項被放入一個刪除隊列，它不能被get命令讀取，在其上使用add和replace也會失敗，但使用set命令可以成功。當這個時間過去後，數據項從服務器的內存中真正的刪除。該參數是可選參數，如果不存在默認爲0，這意味着立即從服務器上刪除。

       服務器返回信息：

l         "DELETED"r"n"          表示數據項刪除成功

l         "NOT_FOUND"r"n"      表示該關鍵字指定的數據項在服務器上沒有找到

l         其他錯誤消息

下面的flush_all命令使得所有存在的數據項立即失效。

增加/減少 Increment/Decrement

       “incr”和”decr”命令用來修改以及存在的數據項的內容，增加或者減少它。該數據被當作32位無符號整數處理。如果當前數據非此類數據，則經將該內容當作0來處理。另外在其上施加incr/decr命令的數據項必須是業已存在的；對於不存在的數據項不會將它作爲0對待，而是以錯誤結束。

       客戶端發送命令行如下格式：

incr <key> <value>"r"n

或者

decr <key> <value>"r"n

<key>是客戶端要修改數據項的關鍵字

<value>是對該數據行進行增加或者減少的操作數。它是一個32位的無符號整數。

       反饋信息有如下幾種：

l         "NOT_FOUND"r"n"

表明在服務器上沒有找到該數據項。

l         "<value>"r"n "

value是執行完增加/減少命令後，該數據項新的數值。

l         錯誤信息。

注意到“decr”命令的下溢問題，如果客戶端嘗試減少的數量小於0，其結果是0。“incr”命令的溢出問題沒有檢查。另外減少一個數據而使它減少了長度，但不保證減少它返回時的長度。該數字可能是附加空格的數字，但這只是實現的優化，所以你不能相信它。

統計 Statistics

       “stats”命令用來查詢服務器的運行情況和其他內部數據。它有兩種情況，以有無參數來區分：

stats"r"n

或者

stats <args>"r"n

       第一種情況它導致服務器輸出一般統計信息以及設置信息和文檔化內容。

       第二種情況根據<args>具體的參數，服務器發送各種內部數據。這部分沒有在協議中文檔化，因爲與memcache的開發者有關其可能是隨時變化的。

多用途統計 General-purpose statistics

       當接收到沒有帶參數的“stats”命令後，服務器發送許多類似與如下格式的文本行：

STAT <name> <value>"r"n

       當類似的文本行全部發送完畢後，服務器發送如下的文本行結束反饋信息：

END"r"n

       在所有STAT文本行中，<name>是該統計項目的名稱，<value>是其數據。下面是一份stats命令反饋的所有統計項目的列表，後面跟着其值的數據類型。在數據類型列中，”32u”表示一個32位無符號整數，”64u”表示一個64位無符號整數，”32u:32u”表示是兩個用冒號分割的32位無符號整數。

名稱	值類型	含義
pid	32u	服務器進程的進程號
uptime	32u	服務器自運行以來的秒數
time	32u	當前服務器上的UNIX時間
version	string	服務器的版本字符串
rusage_user	32u:32u	服務器進程積累的用戶時間（秒:微妙）
rusage_system	32u:32u	服務器進程積累的系統時間（秒:微妙）
curr_items	32u	當前在服務器上存儲的數據項的個數
total_items	32u	在服務器上曾經保存過的數據項的個數
bytes	64u	當前服務器上保存數據的字節數
curr_connections	32u	處於打開狀態的連接數目
total_connections	32u	曾經打開過的所有連接的數目
connection_structures	32u	服務器分配的連接結構體的個數
cmd_get	64u	get命令請求的次數
cmd_set	64u	存儲命令請求的次數
get_hits	64u	關鍵字獲取命中的次數
get_misses	64u	關鍵字獲取沒有命中的次數
evictions	64u	所有因超時而被替換出內存的數據項的個數
bytes_read	64u	服務器從網絡上讀取到的字節數
bytes_write	64u	服務器向網絡上寫的字節數
limit_maxbytes	64u	服務器允許存儲數據的最大值

其他命令 Other commands

"flush_all"是一個帶有可選數字參數的命令，它的執行總是成功的，服務器總是響應以"OK"r"n"字符串。它的作用是使得所有的數據項立即（默認）或者經過一個指定的超時時間後全部失效。在置數據項失效後，對於讀取命令將不會返回任何內容，除非在失效後這些數據再次被存儲。flush_all並沒有真正的釋放這些存在過的數據項佔用的內存空間；數據空間真實被佔用的情況發生在使用新的數據項覆蓋老的數據項時。該命令作用最準確的定義是：它導致所有更新時間早於該命令設定的時間點的數據項，在被檢索時被忽略，其表現就像已被刪除了一樣。

       使用帶有延時flush_all命令的目的是，當你有個memcached服務器池，需要刷新所有的內容時，但不能在同一時間刷洗所有的服務器，這樣就可能因爲所有的服務器突然都要重新建立數據內容，而導致數據庫壓力的顛簸。延時選項允許你設置他們隔10秒失效（設置第一個延時爲0，第二個10秒，第三個20秒等等）。

"version"是一個沒有參數的命令，命令格式如下：

version"r"n

       服務器發回的反饋信息如下：

l         "VERSION <version>"r"n"

<version>是從服務器返回的版本字符串。

l         錯誤消息。

"verbosity"是一個帶有數字參數的命令。它的執行總是成功的，服務器反饋以"OK"r"n"表示執行完成。它用來設置日誌輸出的詳細等級。                                        

"quit"是一個沒有參數的命令。其格式如下：

quit"r"n

       當服務器接受到此命令後，就關閉與該客戶的連接。不管怎樣，客戶端可以在任意不需要該連接的時刻關閉它，而不需要發送該命令。

UDP協議 UDP protocol

       當基於TCP協議的連接數超過TCP連接的上限時，我們可以使用UDP協議來替代。但是UDP協議接口不提供可靠的傳輸，所以多用在不嚴格要求成功的操作上；典型的get請求會因爲緩存的問題，引起丟失或者不完整的傳輸。

       每個UDP數據包包含一個簡單的幀頭，接着就是如TCP協議描述的數據格式的數據流。在當前的實現中，請求必須包含在一個單獨的UDP數據包中，但返回可能分散在多個數據包中。（唯一的可以拆分請求數據包的是大的多關鍵字get請求和set請求，鑑於可靠性相比而言他們更適合用TCP傳輸。）

       幀頭有8字節長，如下是其格式（所有的數字都是16位網絡字節序整形，高位在前）：

       0 - 1                     請求ID

       2 - 3                     序列號

       4 - 5                     在當前的消息中含有的數據包的個數

       6-7                保留以後使用，當前必須爲0

       請求ID由客戶端提供。它的典型值是一個從隨機種子開始遞增值，實際上客戶端可以使用任意的請求ID。服務器的反饋信息中包含了和請求命令中一樣的請求ID。客戶端憑藉這個請求ID區分來自於同一服務器的反饋。每一個包含未知請求ID的數據包，可能是由於延時反饋造成，這些數據包都應該拋棄不用。

       序列號從0到n-1，n是消息中總的數據包的個數。客戶端按照序列號排序重組數據包；結果序列中包含了一個完整的如TCP協議一樣格式的反饋信息（包含了“"r"n”總結字符串）。