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

協(xié)議

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

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

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

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

關(guān)鍵字 Keys

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

命令Commands

memcahe有3種類(lèi)型的命令：

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

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

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

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

超時(shí)時(shí)間 Expiration times

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

錯(cuò)誤信息 Error strings

       每個(gè)命令都有可能被反饋以一個(gè)錯(cuò)誤消息。這些錯(cuò)誤消息有以下三個(gè)類(lèi)型：

l         “ERROR"r"n” 

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

l         "CLIENT_ERROR <error>"r"n"

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

l         "SERVER_ERROR <error>"r"n"

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

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

存儲(chǔ)命令 Storage commands

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

其中：

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

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

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

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

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

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

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

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

l         "NOT_STORED"r"n"    表示發(fā)送的數(shù)據(jù)沒(méi)有存儲(chǔ)，但這不因?yàn)殄e(cuò)誤，而是發(fā)生在add或者replace命令不能滿(mǎn)足條件時(shí)，或者數(shù)據(jù)項(xiàng)正處于要?jiǎng)h除的隊(duì)列中。

l         錯(cuò)誤消息

讀取命令 Retrieval command:

       讀取命令如下所示：

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

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

       返回?cái)?shù)據(jù)項(xiàng)的格式如下：

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

       <flags>是存儲(chǔ)該數(shù)據(jù)項(xiàng)時(shí)，客戶(hù)端命令中的標(biāo)志字段。

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

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

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

刪除 Deletion

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

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

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

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

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

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

l         其他錯(cuò)誤消息

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

增加/減少 Increment/Decrement

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

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

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

<value>是對(duì)該數(shù)據(jù)行進(jìn)行增加或者減少的操作數(shù)。它是一個(gè)32位的無(wú)符號(hào)整數(shù)。

       反饋信息有如下幾種：

l         "NOT_FOUND"r"n"

表明在服務(wù)器上沒(méi)有找到該數(shù)據(jù)項(xiàng)。

l         "<value>"r"n "

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

l         錯(cuò)誤信息。

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

統(tǒng)計(jì) Statistics

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

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

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

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

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

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

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

其他命令 Other commands

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

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

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

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

l         "VERSION <version>"r"n"

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

l         錯(cuò)誤消息。

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

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

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

UDP協(xié)議 UDP protocol

       當(dāng)基于TCP協(xié)議的連接數(shù)超過(guò)TCP連接的上限時(shí)，我們可以使用UDP協(xié)議來(lái)替代。但是UDP協(xié)議接口不提供可靠的傳輸，所以多用在不嚴(yán)格要求成功的操作上；典型的get請(qǐng)求會(huì)因?yàn)榫彺娴膯?wèn)題，引起丟失或者不完整的傳輸。

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

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

       0 - 1                     請(qǐng)求ID

       2 - 3                     序列號(hào)

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

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

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

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