Memcache 协议（中英对照）

转载自：http://www.kuqin.com/web/20080707/10604.html

协议	Protocol
memcached 的客户端使用TCP链接 与 服务器通讯。（UDP接口也同样有效，参考后文的 “UDP协议” ）一个运行中的memcached服务器监视一些（可设置）端口。客户端连接这些端口，发送命令到服务器，读取回应，最后关闭连接。	Clients of memcached communicate with server through TCP connections. (A UDP interface is also available; details are below under "UDP protocol.") A given running memcached server listens on some (configurable) port; clients connect to that port, send commands to the server, read responses, and eventually close the connection.
结束会话不需要发送任何命令。当不再需memcached服务时，要客户端可以在任何时候关闭连接。需要注意的是，鼓励客户端缓存这些连接，而不是每次需要存取数据时都重新打开连接。这是因为memcached 被特意设计成及时开启很多连接也能够高效的工作（数百个，上千个如果需要的话）。缓存这些连接，可以消除建立连接所带来的开销（/*/相对而言，在服务器端建立一个新连接的准备工作所带来的开销，可以忽略不计。）。	There is no need to send any command to end the session. A client may just close the connection at any moment it no longer needs it. Note, however, that clients are encouraged to cache their connections rather than reopen them every time they need to store or retrieve data. This is because memcached is especially designed to work very efficiently with a very large number (many hundreds, more than a thousand if necessary) of open connections. Caching connections will eliminate the overhead associated with establishing a TCP connection (the overhead of preparing for a new connection on the server side is insignificant compared to this).
在memcache协议中发送的数据分两种：文本行 和 自由数据。 文本行被用于来自客户端的命令和服务器的回应。自由数据用于客户端从服务器端存取数据时。同样服务器会以字节流的方式传回自由数据。/*/服务器不用关心自由数据的字节顺序。自由数据的特征没有任何限制；但是通过前文提到的文本行，这项数据的接受者（服务器或客户端），便能够精确地获知所发送的数据库的长度。

andunstructureddata.Textlinesareusedforcommandsfromclients

andresponsesfromservers.Unstructureddataissentwhenaclient

wantstostoreorretrievedata.Theserverwilltransmitback

unstructureddatainexactlythesamewayitreceivedit,asabyte

stream.Theserverdoesn'tcareaboutbyteorderissuesin

unstructureddataandisn'tawareofthem.Therearenolimitationson

charactersthatmayappearinunstructureddata;however,thereader

ofsuchdata(eitheraclientoraserver)willalwaysknow,froma

precedingtextline,theexactlengthofthedatablockbeing

transmitted.

文本行固定以“\r\n”(回车符紧跟一个换行符)结束。自由数据也是同样会以“\r\n”结束，但是\r(回车符)、\n(换行符)，以及任何其他8位字符，均可出现在数据中。因此，当客户端从服务器取回数据时，必须使用数据区块的长度来确定数据区块的结束位置，而不要依据数据区块末尾的“\r\n”，即使它们固定存在于此。

Textlinesarealwaysterminatedby\r\n.Unstructureddatais_also_

terminatedby\r\n,eventhough\r,\noranyother8-bitcharacters

mayalsoappearinsidethedata.Therefore,whenaclientretrieves

datafromaserver,itmustusethelengthofthedatablock(whichit

willbeprovidedwith)todeterminewherethedatablockends,andnot

thefactthat\r\nfollowstheendofthedatablock,eventhoughit

does.键值Keys存储在memcached中的数据通过键值来标识。键值是一个文本字符串，对于需要存取这项数据的客户端而言，它必须是唯一的。键值当前的长度限制设定为250字符（当然，客户端通常不会用到这么长的键）；键值中不能使用制表符和其他空白字符（例如空格，换行等）。

Datastoredbymemcachedisidentifiedwiththehelpofakey.Akey

isatextstringwhichshoulduniquelyidentifythedataforclients

thatareinterestedinstoringandretrievingit.Currentlythe

lengthlimitofakeyissetat250characters(ofcourse,normally

clientswouldn'tneedtousesuchlongkeys);thekeymustnotinclude

controlcharactersorwhitespace.命令Commands所有命令分为3种类型Therearethreetypesofcommands.存储命令（有3项：’set’、’add’、’repalce’）指示服务器储存一些由键值标识的数据。客户端发送一行命令，后面跟着数据区块；然后，客户端等待接收服务器回传的命令行，指示成功与否。

Storagecommands(therearethree:"set","add"and"replace")askthe

servertostoresomedataidentifiedbyakey.Theclientsendsa

commandline,andthenadatablock;afterthattheclientexpectsone

lineofresponse,whichwillindicatesuccessorfaulure.取回命令（只有一项：’get’）指示服务器返回与所给键值相符合的数据（一个请求中右一个或多个键值）。客户端发送一行命令，包括所有请求的键值；服务器每找到一项内容，都会发送回客户端一行关于这项内容的信息，紧跟着是对应的数据区块；直到服务器以一行“END”回应命令结束。

Retrievalcommands(thereisonlyone:"get")asktheserverto

retrievedatacorrespondingtoasetofkeys(oneormorekeysinone

request).Theclientsendsacommandline,whichincludesallthe

requestedkeys;afterthatforeachitemtheserverfindsitsendsto

theclientoneresponselinewithinformationabouttheitem,andone

datablockwiththeitem'sdata;thiscontinuesuntiltheserver

finishedwiththe"END"responseline.

/*?*/其他的命令都不能携带自由数据。在这些命令中，客户端发送一行命令，然后等待（由命令所决定）一行回应，或最终以一行“END”结束的多行命令。

Allothercommandsdon'tinvolveunstructureddata.Inallofthem,

theclientsendsonecommandline,andexpects(dependingonthe

command)eitheronelineofresponse,orseverallinesofresponse

endingwith"END"onthelastline.一行命令固定以命令名称开始，接着是以空格隔开的参数（如果有参数的话）。命令名称大小写敏感，并且必须小写。

Acommandlinealwaysstartswiththenameofthecommand,followedby

parameters(ifany)delimitedbywhitespace.Commandnamesare

lower-caseandarecase-sensitive.一些客户端发送给服务器的命令会包含一些时限（针对内容或客户端请求的操作）。这时，时限的具体内容既可以是Unix时间戳（从1970年1月1日开始的秒钟数），或当前时间开始的秒钟数。对后者而言，不能超过60*60*24*30（30天）；如果超出，服务器将会理解为Unix时间戳，而不是从当前时间起的秒偏移。

Somecommandsinvolveaclientsendingsomekindofexpirationtime

(relativetoanitemortoanoperationrequestedbytheclient)to

theserver.Inallsuchcases,theactualvaluesentmayeitherbe

Unixtime(numberofsecondssinceJanuary1,1970,asa32-bit

value),oranumberofsecondsstartingfromcurrenttime.Inthe

lattercase,thisnumberofsecondsmaynotexceed60*60*24*30(number

ofsecondsin30days);ifthenumbersentbyaclientislargerthan

that,theserverwillconsiderittoberealUnixtimevaluerather

thananoffsetfromcurrenttime.错误字串Errorstrings每一个由客户端发送的命令，都可能收到来自服务器的错误字串回复。这些错误字串会以三种形式出现：Eachcommandsentbyaclientmaybeansweredwithanerrorstring

fromtheserver.Theseerrorstringscomeinthreetypes:-"ERROR\r\n"意味着客户端发送了不存在的命令名称。meanstheclientsentanonexistentcommandname.-"CLIENT_ERROR<error>\r\n"意味着输入的命令行里存在一些客户端错误，例如输入未遵循协议。<error>部分是人类易于理解的错误解说……meanssomesortofclienterrorintheinputline,i.e.theinput

doesn'tconformtotheprotocolinsomeway.<error>isa

human-readableerrorstring.-"SERVER_ERROR<error>\r\n"意味着一些服务器错误，导致命令无法执行。<error>部分是人类易于理解的错误解说。在一些严重的情形下（通常应该不会遇到），服务器将在发送这行错误后关闭连接。这是服务器主动关闭连接的唯一情况。

meanssomesortofservererrorpreventstheserverfromcarrying

outthecommand.<error>isahuman-readableerrorstring.Incases

ofsevereservererrors,whichmakeitimpossibletocontinue

servingtheclient(thisshouldn'tnormallyhappen),theserverwill

closetheconnectionaftersendingtheerrorline.Thisistheonly

caseinwhichtheserverclosesaconnectiontoaclient.在后面每项命令的描述中，这些错误行不会再特别提到，但是客户端必须考虑到这些它们存在的可能性。Inthedescriptionsofindividualcommandsbelow,theseerrorlines

arenotagainspecificallymentioned,butclientsmustallowfortheir

possibility.存储命令Storagecommands首先，客户端会发送一行像这样的命令：First,theclientsendsacommandlinewhichlookslikethis:<commandname><key><flags><exptime><bytes>\r\n-<commandname>是set,add,或者repalce-<commandname>is"set","add"or"replace"set意思是“储存此数据”add意思是“储存此数据，只在服务器*未*保留此键值的数据时”replace意思是“储存此数据，只在服务器*曾*保留此键值的数据时”"set"means"storethisdata"."add"means"storethisdata,butonlyiftheserver*doesn't*already

holddataforthiskey"."replace"means"storethisdata,butonlyiftheserver*does*

alreadyholddataforthiskey".-<key>是接下来的客户端所要求储存的数据的键值-<key>isthekeyunderwhichtheclientaskstostorethedata-<flags>是在取回内容时，与数据和发送块一同保存服务器上的任意16位无符号整形（用十进制来书写）。客户端可以用它作为“位域”来存储一些特定的信息；它对服务器是不透明的。

-<flags>isanarbitrary16-bitunsignedinteger(writtenoutin

decimal)thattheserverstoresalongwiththedataandsendsback

whentheitemisretrieved.Clientsmayusethisasabitfieldto

storedata-specificinformation;thisfieldisopaquetotheserver.-<exptime>是终止时间。如果为0，该项永不过期(虽然它可能被删除，以便为其他缓存项目腾出位置)。如果非0（Unix时间戳或当前时刻的秒偏移），到达终止时间后，客户端无法再获得这项内容。

-<exptime>isexpirationtime.Ifit's0,theitemneverexpires

(althoughitmaybedeletedfromthecachetomakeplaceforother

items).Ifit'snon-zero(eitherUnixtimeoroffsetinsecondsfrom

currenttime),itisguaranteedthatclientswillnotbeableto

retrievethisitemaftertheexpirationtimearrives(measuredby

servertime).-<bytes>是随后的数据区块的字节长度，不包括用于分野的“\r\n”。它可以是0（这时后面跟随一个空的数据区块）。-<bytes>isthenumberofbytesinthedatablocktofollow,*not*

includingthedelimiting\r\n.<bytes>maybezero(inwhichcase

it'sfollowedbyanemptydatablock).在这一行以后，客户端发送数据区块。Afterthisline,theclientsendsthedatablock:<datablock>\r\n-<datablock>是大段的8位数据，其长度由前面的命令行中的<bytes>指定。-<datablock>isachunkofarbitrary8-bitdataoflength<bytes>

fromthepreviousline.发送命令行和数据区块以后，客户端等待回复，可能的回复如下：Aftersendingthecommandlineandthedatablockmtheclientawaits

thereply,whichmaybe:-"STORED\r\n"表明成功.toindicatesuccess.-"NOT_STORED\r\n"表明数据没有被存储，但不是因为发生错误。这通常意味着add或replace命令的条件不成立，或者，项目已经位列删除队列（参考后文的“delete”命令）。

toindicatethedatawasnotstored,butnot

becauseofanerror.Thisnormallymeansthateitherthatthe

conditionforan"add"ora"replace"commandwasn'tmet,orthatthe

itemisinadeletequeue(seethe"delete"commandbelow).取回命令Retrievalcommand一行取回命令如下：Theretrievalcommandlookslikethis:get<key>*\r\n-<key>*表示一个或多个键值，由空格隔开的字串-<key>*meansoneormorekeystringsseparatedbywhitespace.这行命令以后，客户端的等待0个或多个项目，每项都会收到一行文本，然后跟着数据区块。所有项目传送完毕后，服务器发送以下字串：

Afterthiscommand,theclientexpectszeroormoreitems,eachof

whichisreceivedasatextlinefollowedbyadatablock.Afterall

theitemshavebeentransmitted,theserversendsthestring"END\r\n"来指示回应完毕。toindicatetheendofresponse.服务器用以下形式发送每项内容：Eachitemsentbytheserverlookslikethis:VALUE<key><flags><bytes>\r\n

<data block>\r\n- <key> 是所发送的键名- <key> is the key for the item being sent- <flags> 是存储命令所设置的记号

- <flags> is the flags value set by the storage command

- <bytes> 是随后数据块的长度，*不包括* 它的界定符“\r\n”- <bytes> is the length of the data block to follow, *not* including

itsdelimiting\r\n

-<datablock>是发送的数据-<datablock>isthedataforthisitem.如果在取回请求中发送了一些键名，而服务器没有送回项目列表，这意味着服务器没这些键名（可能因为它们从未被存储，或者为给其他内容腾出空间而被删除，或者到期，或者被已客户端删除）。

Ifsomeofthekeysappearinginaretrievalrequestarenotsentback

bytheserverintheitemlistthismeansthattheserverdoesnot

holditemswithsuchkeys(becausetheywereneverstored,orstored

butdeletedtomakespaceformoreitems,orexpired,orexplicitly

deletedbyaclient).删除Deletion命令“delete”允许从外部删除内容：Thecommand"delete"allowsforexplicitdeletionofitems:delete<key><time>\r\n-<key>是客户端希望服务器删除的内容的键名-<key>isthekeyoftheitemtheclientwishestheservertodelete-<time>是一个单位为秒的时间（或代表直到某一刻的Unix时间），在该时间内服务器会拒绝对于此键名的“add”和“replace”命令。此时内容被放入delete队列，无法再通过“get”得到该内容，也无法是用“add”和“replace”命令（但是“set”命令可用）。直到指定时间，这些内容被最终从服务器的内存中彻底清除。

-<time>istheamountoftimeinseconds(orUnixtimeuntilwhich)

theclientwishestheservertorefuse"add"and"replace"commands

withthiskey.Forthisamountofitem,theitemisputintoa

deletequeue,whichmeansthatitwon'tpossibletoretrieveitby

the"get"command,but"add"and"replace"commandwiththiskey

willalsofail(the"set"commandwillsucceed,however).Afterthe

timepasses,theitemisfinallydeletedfromservermemory.<time>参数是可选的，缺省为0（表示内容会立刻清除，并且随后的存储命令均可用）。

Theparameter<time>isoptional,and,ifabsent,defaultsto0

(whichmeansthattheitemwillbedeletedimmediatelyandfurther

storagecommandswiththiskeywillsucceed).此命令有一行回应：Theresponselinetothiscommandcanbeoneof:-"DELETED\r\n"表示执行成功toindicatesuccess-"NOT_FOUND\r\n"表示没有找到这项内容toindicatethattheitemwiththiskeywasnotfound.参考随后的“flush_all”命令使所有内容无效

Seethe"flush_all"commandbelowforimmediateinvalidation

ofallexistingitems.增加/减少Increment/Decrement命令“incr”和“decr”被用来修改数据，当一些内容需要替换、增加或减少时。这些数据必须是十进制的32位无符号整新。如果不是，则当作0来处理。修改的内容必须存在，当使用“incr”/“decr”命令修改不存在的内容时，不会被当作0处理，而是操作失败。

Commands"incr"and"decr"areusedtochangedataforsomeitem

in-place,incrementingordecrementingit.Thedatafortheitemis

treatedasdecimalrepresentationofa32-bitunsignedinteger.Ifthe

currentdatavaluedoesnotconformtosucharepresentation,the

commandsbehaveasifthevaluewere0.Also,theitemmustalready

existforincr/decrtowork;thesecommandswon'tpretendthata

non-existentkeyexistswithvalue0;instead,theywillfail.客户端发送命令行：Theclientsendsthecommandline:incr<key><value>\r\n

或

decr <key> <value>\r\n- <key> 是客户端希望修改的内容的建名

- <key> is the key of the item the client wishes to change

- <value> 是客户端要增加/减少的总数。- <value> is the amount by which the client wants to increase/decreasethe item. It is a decimal representation of a 32-bit unsigned integer.回复为以下集中情形：

The response will be one of:

- "NOT_FOUND\r\n"指示该项内容的值，不存在。to indicate the item with this value was not found- <value>\r\n ，<value>是 增加/减少 。- <value>\r\n , where <value> is the new value of the item's data,

aftertheincrement/decrementoperationwascarriedout.

注意"decr"命令发生下溢：如果客户端尝试减少的结果小于0时，结果会是0。"incr"命令不会发生溢出。Notethatunderflowinthe"decr"commandiscaught:ifaclienttries

todecreasethevaluebelow0,thenewvaluewillbe0.Overflowin

the "incr" command is not checked.

……

Note also that decrementing a number such that it loses length isn't

guaranteedtodecrementitsreturnedlength.ThenumberMAYbe

space-paddedattheend,butthisispurelyanimplementation

optimization,soyoualsoshouldn'trelyonthat.

状态Statistics命令"stats"被用于查询服务器的运行状态和其他内部数据。有两种格式。不带参数的：

Thecommand"stats"isusedtoquerytheserveraboutstatisticsit

maintainsandotherinternaldata.Ithastwoforms.Without

arguments: stats\r\n这会在随后输出各项状态、设定值和文档。另一种格式带有一些参数：

it causes the server to output general-purpose statistics and

settings,documentedbelow.Intheotherformithassomearguments:

stats<args>\r\n通过<args>，服务器传回各种内部数据。因为随时可能发生变动，本文不提供参数的种类及其传回数据。Dependingon<args>,variousinternaldataissentbytheserver.The

kindsofargumentsandthedatasentarenotdocumentedinthisvesion

oftheprotocol,andaresubjecttochangefortheconvenienceof

memcachedevelopers.各种状态General-purposestatistics受到无参数的"stats"命令后，服务器发送多行内容，如下：Uponreceivingthe"stats"commandwithoutarguments,theserversents

anumberoflineswhichlooklikethis:STAT<name><value>\r\n服务器用以下一行来终止这个清单：TheserverterminatesthislistwiththelineEND\r\n在每行状态中，<name>是状态的名字，<value>使状态的数据。以下清单，是所有的状态名称，数据类型，和数据代表的含义。

Ineachlineofstatistics,<name>isthenameofthisstatistic,and

<value>isthedata.Thefollowingisthelistofallnamessentin

responsetothe"stats"command,togetherwiththetypeofthevalue

sent for this name, and the meaning of the value.在“类型”一列中，"32u"表示32位无符号整型，"64u"表示64位无符号整型，"32u:32u"表示用冒号隔开的两个32位无符号整型。

In the type column below, "32u" means a 32-bit unsigned integer, "64u"

meansa64-bitunsignerinteger.'32u:32u'meanstwo32-butunsigned

integersseparatedbyacolon.

名称/Name类型/Type含义/Meaningpid32u服务器进程IDProcessidofthisserverprocessuptime32u服务器运行时间，单位秒Numberofsecondsthisserverhasbeenrunningtime32u服务器当前的UNIX时间currentUNIXtimeaccordingtotheserverversionstring服务器的版本号Versionstringofthisserverrusage_user32u:32u该进程累计的用户时间

(秒:微妙)Accumulatedusertimeforthisprocess

(seconds:microseconds)rusage_system32u:32u该进程累计的系统时间

(秒:微妙)Accumulatedsystemtimeforthisprocess

(seconds:microseconds)curr_items32u服务器当前存储的内容数量Currentnumberofitemsstoredbytheservertotal_items32u服务器启动以来存储过的内容总数Totalnumberofitemsstoredbythisserver

eversinceitstartedbytes64u服务器当前存储内容所占用的字节数Currentnumberofbytesusedbythisserver

tostoreitemscurr_connections32u连接数量Numberofopenconnectionstotal_connections32u服务器运行以来接受的连接总数Totalnumberofconnectionsopenedsince

theserverstartedrunningconnection_structures32u服务器分配的连接结构的数量Numberofconnectionstructuresallocated

bytheservercmd_get32u取回请求总数Cumulativenumberofretrievalrequestscmd_set32u存储请求总数Cumulativenumberofstoragerequestsget_hits32u请求成功的总次数Numberofkeysthathavebeenrequestedand

foundpresentget_misses32u请求失败的总次数Numberofitemsthathavebeenrequested

andnotfoundbytes_read64u服务器从网络读取到的总字节数Totalnumberofbytesreadbythisserver

fromnetworkbytes_written64u服务器向网络发送的总字节数Totalnumberofbytessentbythisserverto

networklimit_maxbytes32u服务器在存储时被允许使用的字节总数Numberofbytesthisserverisallowedto

use for storage.  

其它命令

Other commands

“flush_all”命令有一个可选的数字参数。它总是执行成功，服务器会发送“OK\r\n”回应。它的效果是使已经存在的项目立即失效（缺省），或在指定的时间后。此后执行取回命令，将不会有任何内容返回（除非重新存储同样的键名）。flush_all 实际上没有立即释放项目所占用的内存，而是在随后陆续有新的项目被储存时执行。flush_all 效果具体如下：它导致所有更新时间早于flush_all所设定时间的项目，在被执行取回命令时命令被忽略。

"flush_all" is a command with an optional numeric argument. It always succeeds, and the server sends "OK\r\n" in response. Its effect is to invalidate all existing items immediately (by default) or after the expiration specified. After invalidation none of the items will be returned in response to a retrieval command (unless it's stored again under the same key *after* flush_all has invalidated the items). flush_all doesn't actually free all the memory taken up by existing items; that will happen gradually as new items are stored. The most precise definition of what flush_all does is the following: it causes all items whose update time is earlier than the time at which flush_all was set to be executed to be ignored for retrieval purposes.“version”命令没有参数："version" is a command with no arguments:version\r\n在回应中，服务器发送：In response, the server sends"VERSION <version>\r\n"<version> 是服务器的版本字串。where <version> is the version string for the server.“quit”命令没有参数："quit" is a command with no arguments:quit\r\n接收此命令后，服务器关闭连接。不过，客户端可以在不再需要时，简单地关闭连接就行，并不一定需要发送这个命令。Upon receiving this command, the server closes the connection. However, the client may also simply close the connection when it no longer needs it, without issuing this command.  

UDP 协议

UDP protocol

当来自客户端的连接数远大于TCP连接的上限时，可以使用基于UDP的接口。UDP接口不能保证传输到位，所以只有在不要求成功的操作中使用；比如被用于一个“get”请求时，会因不当的缓存处理而发生错误或回应有遗失。For very large installations where the number of clients is high enough that the number of TCP connections causes scaling difficulties, there is also a UDP-based interface. The UDP interface does not provide guaranteed delivery, so should only be used for operations that aren't required to succeed; typically it is used for "get" requests where a missing or incomplete response can simply be treated as a cache miss.每个UDP数据包都包含一个简单的帧头，数据之后的内容与TCP协议的描述类似。在执行所产生的数据流中，请求必须被包含在单独的一个UDP数据包中，但是回应可能跨越多个数据包。（只有“get”和“set”请求例外，跨越了多个数据包）Each UDP datagram contains a simple frame header, followed by data in the same format as the TCP protocol described above. In the current implementation, requests must be contained in a single UDP datagram, but responses may span several datagrams. (The only common requests that would span multiple datagrams are huge multi-key "get" requests and "set" requests, both of which are more suitable to TCP transport for reliability reasons anyway.)帧头有8字节长，如下（均由16位整数组成，网络字节顺序，高位在前）：The frame header is 8 bytes long, as follows (all values are 16-bit integers in network byte order, high byte first):

• 0-1 请求ID
• 2-3 序号
• 4-5 该信息的数据包总数
• 6-7 保留位，必须为0

• 0-1 Request ID
• 2-3 Sequence number
• 4-5 Total number of datagrams in this message
• 6-7 Reserved for future use; must be 0

请求ID有客户端提供。一般它会是一个从随机基数开始的递增值，不过客户端想用什么样的请求ID都可以。服务器的回应会包含一个和请求中的同样的ID。客户端使用请求ID来区分每一个回应。任何一个没有请求ID的数据包，可能是之前的请求遭到延迟而造成的，应该被丢弃。The request ID is supplied by the client. Typically it will be a monotonically increasing value starting from a random seed, but the client is free to use whatever request IDs it likes. The server's response will contain the same ID as the incoming request. The client uses the request ID to differentiate between responses to outstanding requests if there are several pending from the same server; any datagrams with an unknown request ID are probably delayed responses to an earlier request and should be discarded.序号的返回是从0到n-1，n是该条信息的数据包数量。The sequence number ranges from 0 to n-1, where n is the total number of datagrams in the message. The client should concatenate the payloads of the datagrams for a given response in sequence number order; the resulting byte stream will contain a complete response in the same format as the TCP protocol (including terminating \r\n sequences).