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

協(xié)議

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

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

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

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

關(guān)鍵字 Keys

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

命令Commands

memcahe有3種類型的命令：

l         存儲命令—（3個命令：set、add和replace）要求服務(wù)器安裝關(guān)鍵字存儲數(shù)據(jù)。客戶端發(fā)送一個命令行，然后一個數(shù)據(jù)塊；命令執(zhí)行后客戶端等待一行反饋，用來表示命令執(zhí)行成功與否。

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

l         其他命令，如flush_all，version等。這些命令不使用非結(jié)構(gòu)化的數(shù)據(jù)。對于這些命令，客戶端發(fā)送一個文本的命令行，根據(jù)命令的特性等待一行數(shù)據(jù)或者在最后一行以“END“結(jié)尾的幾行反饋信息。

所有的命令行總是以命令的名字開始，緊接著是以空格分割的參數(shù)。命令名稱都是小寫，并且是大小寫敏感的。

超時時間 Expiration times

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

錯誤信息 Error strings

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

l         “ERROR"r"n” 

意味著客戶端發(fā)送了一個在協(xié)議中不存在的命令。

l         "CLIENT_ERROR <error>"r"n"

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

l         "SERVER_ERROR <error>"r"n"

表示服務(wù)器在執(zhí)行命令時發(fā)生了某些錯誤，致使服務(wù)器無法執(zhí)行下去。<error>也是一個人工可讀（human-readable）的錯誤注釋。在一些情況下，錯誤導(dǎo)致服務(wù)器不能再為客戶端服務(wù)（這樣的情況很少發(fā)生），服務(wù)器就會在發(fā)生錯誤消息后主動關(guān)閉連接。這也是服務(wù)器主動關(guān)閉到客戶端連接的唯一情況。

       后續(xù)秒數(shù)各種命令的時候，我們不再贅述錯誤消息的情況，當(dāng)我們要清楚錯誤是存在的，不可忽略。

存儲命令 Storage commands

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

其中：

<command name> 是 set、add或者replace。set表示存儲該數(shù)據(jù)；add表示如果服務(wù)器沒有保存該關(guān)鍵字的情況下，存儲該數(shù)據(jù)；replace表示在服務(wù)器已經(jīng)擁有該關(guān)鍵字的情況下，替換原有內(nèi)容。

<key>是客戶端要求服務(wù)器存儲數(shù)據(jù)的關(guān)鍵字。

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

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

<bytes>是隨后數(shù)據(jù)的字節(jié)數(shù)，不包括終結(jié)符”"r"n”。<bytes>有可能是0，它后面將是一個空的數(shù)據(jù)塊。

<data block>是真正要存儲數(shù)據(jù)流。

       發(fā)送命令行和數(shù)據(jù)后，客戶端等待反饋，可以是如下幾種情況：

l         "STORED"r"n"              表示存儲數(shù)據(jù)成功。

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

l         錯誤消息

讀取命令 Retrieval command:

       讀取命令如下所示：

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

       發(fā)送命令后，客戶端等待返回一個或多個數(shù)據(jù)項，每個數(shù)據(jù)項的格式是一個文本行，后跟著一個數(shù)據(jù)塊。當(dāng)所有的數(shù)據(jù)項發(fā)送完畢后，服務(wù)器發(fā)送字符串”END"r"n”表示服務(wù)器反饋數(shù)據(jù)的結(jié)束。

       返回數(shù)據(jù)項的格式如下：

<key>是發(fā)生數(shù)據(jù)項的關(guān)鍵字。

       <flags>是存儲該數(shù)據(jù)項時，客戶端命令中的標志字段。

       <bytes>是緊跟文本行后數(shù)據(jù)塊的長度，不包括終結(jié)符”"r"n”。

<data block>是數(shù)據(jù)項的數(shù)據(jù)部分。

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

刪除 Deletion

刪除命令允許直接刪除數(shù)據(jù)項，命令格式如下：

<key>是客戶端希望服務(wù)器刪除數(shù)據(jù)項的關(guān)鍵字

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

       服務(wù)器返回信息：

l         "DELETED"r"n"          表示數(shù)據(jù)項刪除成功

l         "NOT_FOUND"r"n"      表示該關(guān)鍵字指定的數(shù)據(jù)項在服務(wù)器上沒有找到

l         其他錯誤消息

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

增加/減少 Increment/Decrement

       “incr”和”decr”命令用來修改以及存在的數(shù)據(jù)項的內(nèi)容，增加或者減少它。該數(shù)據(jù)被當(dāng)作32位無符號整數(shù)處理。如果當(dāng)前數(shù)據(jù)非此類數(shù)據(jù)，則經(jīng)將該內(nèi)容當(dāng)作0來處理。另外在其上施加incr/decr命令的數(shù)據(jù)項必須是業(yè)已存在的；對于不存在的數(shù)據(jù)項不會將它作為0對待，而是以錯誤結(jié)束。

       客戶端發(fā)送命令行如下格式：

<key>是客戶端要修改數(shù)據(jù)項的關(guān)鍵字

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

       反饋信息有如下幾種：

l         "NOT_FOUND"r"n"

表明在服務(wù)器上沒有找到該數(shù)據(jù)項。

l         "<value>"r"n "

value是執(zhí)行完增加/減少命令后，該數(shù)據(jù)項新的數(shù)值。

l         錯誤信息。

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

統(tǒng)計 Statistics

       “stats”命令用來查詢服務(wù)器的運行情況和其他內(nèi)部數(shù)據(jù)。它有兩種情況，以有無參數(shù)來區(qū)分：

       第一種情況它導(dǎo)致服務(wù)器輸出一般統(tǒng)計信息以及設(shè)置信息和文檔化內(nèi)容。

       第二種情況根據(jù)<args>具體的參數(shù)，服務(wù)器發(fā)送各種內(nèi)部數(shù)據(jù)。這部分沒有在協(xié)議中文檔化，因為與memcache的開發(fā)者有關(guān)其可能是隨時變化的。

多用途統(tǒng)計 General-purpose statistics

       當(dāng)接收到?jīng)]有帶參數(shù)的“stats”命令后，服務(wù)器發(fā)送許多類似與如下格式的文本行：

       當(dāng)類似的文本行全部發(fā)送完畢后，服務(wù)器發(fā)送如下的文本行結(jié)束反饋信息：

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

其他命令 Other commands

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

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

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

       服務(wù)器發(fā)回的反饋信息如下：

l         "VERSION <version>"r"n"

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

l         錯誤消息。

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

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

       當(dāng)服務(wù)器接受到此命令后，就關(guān)閉與該客戶的連接。不管怎樣，客戶端可以在任意不需要該連接的時刻關(guān)閉它，而不需要發(fā)送該命令。

UDP協(xié)議 UDP protocol

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

       每個UDP數(shù)據(jù)包包含一個簡單的幀頭，接著就是如TCP協(xié)議描述的數(shù)據(jù)格式的數(shù)據(jù)流。在當(dāng)前的實現(xiàn)中，請求必須包含在一個單獨的UDP數(shù)據(jù)包中，但返回可能分散在多個數(shù)據(jù)包中。（唯一的可以拆分請求數(shù)據(jù)包的是大的多關(guān)鍵字get請求和set請求，鑒于可靠性相比而言他們更適合用TCP傳輸。）

       幀頭有8字節(jié)長，如下是其格式（所有的數(shù)字都是16位網(wǎng)絡(luò)字節(jié)序整形，高位在前）：

       0 - 1                     請求ID

       2 - 3                     序列號

       4 - 5                     在當(dāng)前的消息中含有的數(shù)據(jù)包的個數(shù)

       6-7                保留以后使用，當(dāng)前必須為0

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

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