试翻译memcached协议

说明：memcached以下简称mm

 

 

这阵子接触了mm，想细看看它的协议没找着中文版，因此自己试着将其翻译来，并与大家分享！本人英语水平不够，望大家多多指教！排版不怎么好看，因为完全照原文的排版。好了，开始看协议了：

 

协议

 

mm一般采用TCP协议通信（关于mm采用UDP通信的详情参见文章最后）。户可以通过连接mm在服务器打开的动态端口向服务器发送命令、读取数据，最终关闭连接。

 

客户在与mm通信时如果想关闭连接，不需要发送任何命令，并且可以在任时刻关闭连接。但是，mm提倡用户将连接缓存起来，而不是每次重新建立新的连接，因为设计mm时就是希望mm在同时有成百上千的连接时，也能有很高的效率，缓存连接能节省建立连接需花费的时间，相对而言，在服务器端新建一个连接的开销是可以忽略的。

 

mm的数据有两种：文本行和非结构化数据。文本行用于向服务器发送命令或服务器给出响应，非结构化数据用于向服务器存取的数据。服务器返回非结构化数据给客户时，它会按照收到数据时的格式以字节流返回，并且不关心也不知道流中非结构化数据字节的顺序。对于非结构化数据中的字符没有什么限制，但应该通过数据前的文本行让服务器和客户确定数据的长度。

 

文本行与非结构化数据都是以 \r \n 结束，但是非结构化数据中可能会出现\r、\n 或者任何八位字符。也正是因此，当一个客户向服务器存储一个数据时，必须给出数据块的长度来标识数据块何时结束，客户取数据时也必须用这长度标识数据块结束位置，尽管数据块末尾有\r \n，但不会依据它们判断数据块是否结束。

 

keys：

向mm存取数据时总是以键（key）—值（value）形式，key应该是唯一的。目mm允许的key最大长度为250个字符，一般情况下，这么长的key足够用了，另外，key中不能包含控制字符和空格。

 

 

命令：

mm的所有命令分为三种：

1：Storage命令：

Storage命令有六种："set", "add", "replace", "append","prepend","cas"，当客户服务器请求存储数据时，客户端发送一行命令，再接着发送数据块，然后客户会等待服务器给出响应，在响应的某一行中会指示操作是否成功。

 

2：Retrieval命令

Retrieva命令只有两种："get","gets"，该命令将根据给出的key的集合向服务器数据。取数据时，先发送一命令行，命令行包括所有待取数据的key。服务器收到命令后会查找相应的数据，每找到一个条目就会向客户发送一个，每个条目首先用一行显示当前条目的相关信息，而数据紧跟其后，最后以“END”结束。

 

3：其他命令：

所有的其他命令都不包含非结构化数据。客户发送这些命令中某一条后，服器会给出数行响应，并在以“END”结束。

 

命令行总是以命令名称开始，如果有参数的话参数紧跟其后，以空格隔开。令名称都是小写的，并且区分大小写。

 

生存时间：

一些发送给服务器的命令可能包含某类时限（根据客户请求的条目或操作定），生存时间有两种形式，一种是Unix时间：从1970年1月1日开始的秒钟数，另外一种则从当前时间开始的 秒针数。后者的最大值为60*60*24*30（即一个月的时间），如果用户给的时间超过了这个值，那么服务器会把客户给的时间按Unix时间处理。

 

错误字符串：

用户每次发出请求得到的回应都有可能是一条错误字符串。mm中有三种出信息：

1：“ERROR\ r \ n”

该提示说明客户发送了一条不存在的命令。

2：“CLIENT_ERROR< error >\ r\ n”

该提示说明客户在输入时出了错，比如：用户输入时违反了协议。< error >为便于阅读的具体错误提示。

3：“SERVER_ERROR< error >\ r\ n”

该提示说明服务器执行命令时出了错，< error >同上。某些严重服务器错（通常不会发生）导致服务器不能继续提供服务，此时服务器会关闭所有的客户连接，这也是服务器会主动关闭客户连接的唯一情况。

 

在后面介绍每条命令时，将不再提及这些错误字符串，但客户应该考虑到它出现的可能。

 

命令详解：

 

Storage命令：

 

客户首先应发送一个命令行，命令行的格式如下：

< command name >< key >< flags >< exptime >< bytes >[ noreply ]\ r\ n

 

< command name >即 set、add、replace、append、prepend

（cas使用格式为：cas< key >< flags >< exptime >< bytes >< cas unpiue >[ noreply ]\ r\ n）

set ：存储数据

add ：当key在服务器不存在时，存储数据

replace ：当key在服务器已存在时，替换掉相应的数据。

append ：当key在服务器已存在时，将数据添加到服务器中与key对应的数据之后，否则相当set命令。

prepend ：当key在服务器已存在时，将数据添加到服务器中与key对应的数据之前。

 

append与prepend命令不会更新flags和 exptime ，他们只会对数据部分进行更新，并忽略新的flags和exptime。

 

cas ：仅当在自己上一次拿到数据后，没有人更新数据时，才会储存数据。

 

< key > ：待存储条目（键值对形式）的key

< flags > ：一个16位的无符号十进制整数，它与数据存放在一起，或同时被返回给客户。客户可以用它来保存对数据说明的特定信息，；另外它对服务器是不透明的。在mm1.2.1或更高的版本中，flags可能为32位。

< exptime > ：生存时间，如果它为0，则当前数据会随服务器运行而一直存在，除非被调用delete命令将其删除，如果不为0，那么在生存时间到达时，服务器将不能保证该数据仍然存在。

< bytes > ：即将储存的数据的字节数，不包含结尾的“\ r\ n”当数据为空时，bytes为0。

< cas unique >对已存在条目唯一的64位的值，会在使用 gets 命令时返回

[ noreply ] ：告诉服务器不需给出任何回应，可选项。当请求的内容难以辨析，甚至服务器无法确定识别出 noreply ，服务器会发送一个错误字符串给客户，并会间隔一小会后才能继续从客户端接受数据，因此客户应发送有效的请求。

 

在这行命令后，客户发送数据块：

< data block >\ r\ n

< data block >是一块任意字节组成的数据，其长度为之前命令行中给出的长度。

 

客户收到响应可能为：

 

“STORED\ r\ n”：执行成功。

“NOT_STORED\ r\ n”：数据存储失败，但并不是因为出现某个错误造成的，通常是因为执行“add”或“replace”命令没有找到相应key或待操作的条目处于删除队列（参见之后的“delete”命令）。

“EXISTS\ r\ n”：由于使用 cas 命令时，操作对象在上次获取后被他人修改了。

“NOT_FOUND\ r\ n”：由于使用cas命令时，操作对象不存在或已经被删除了。

 

Retrieval命令：

retrieval命令如下：

get < key >*\ r\ n

gets < key >*\ r\ n

< key >*：一个或多个key，以空格隔开。

执行这命令后，客户会收到0或多个条目，每个条目以文本行开始，数据块紧跟其后，所有数据传输完后，服务器会发送一字符串“END\ r\ n”标识结束。

服务器发送的每个条目按照一下格式：

VALUE< key >< flags >< bytes >[< cas unpiue >]\ r\ n

< data block >\ r\ n

各参数详解参照Storage命令中解释。

当服务器中没有包含客户请求的某个key时，服务器不会向客户送回该key值，可能是数据没有存储过，或者被删除了，或者到了设定的生存时间，或者被其他客户删除了。

 

删除命令：

delete命令允许客户直接删除条目，其格式如下：

delete < key >[< time >][ noreply ]\ r\ n

< key>：客户想要得到的条目的key

 

< time > ：以秒为单位的时间或者直到某一刻的Unix时间，在用户设置的这段时间内，服务器会将key所对应的条目置于删除队列中，并拒绝客户对该条目执行 add和replace命令，get命令也不能获取该条目，但是set命令可以使用，过着这段时间，该条目将被从服务器内存中删除。

< time >是可选项，缺省时默认为0，表示立即删除当前条目，之后执行Storage命令均能成功。

[ noreply ]：参照Storage命令中解释。

 

客户收到响应可能为：

 

“DELETE\ r\ n”删除成功。

“NOT_FOUND\ r\ n”：待删除内容没有找到。

 

可以参考随后的“flush_all”命令，它能使mm服务器中所有数据失效。

 

增大/减小命令

incr 与decr 命令用于增大或减小某些条目的数据。待操作条目的数据应为64位十进制无符号整数，如果不是，命令将其当0处理，如果待操作的数据不存在，服务器不会创建一个为0的数据进行操作，而是显示操作失败。

命令格式：

incr< key >< value >[noreply]\ r\ n

decr< key >< value >[noreply]\ r\ n

< key>：待修改条目的key

< value >：是64位十进制无符号整数，代表要增加或减少的量。

[ noreply ]：参照Storage命令中解释。

客户收到响应可能为：

“NOT_FOUND\ r\ n”：待修改条目没有找到

< value >\ r\ n ：执行成功，< value >为执行成功后的值。

 

注意：

当执行 decr 命令使值小于0时会发生下越界，新值将被设为0。执行incr产生上越界时将会产生一个64位的结果。

 

另外，数字减小到长度小于原长度后，将会用空格填补在数字末尾，所以返回的数字长度是不可靠的。

 

 

状态统计

 

stats命令用于查询服务器关于当前持有的数据和内部数据的状态统计。可以采用无参数和有参数两种格式。

无参数：stats\ r\ n

服务器将会传回general-purpose的统计状态。

有参数：stats< args >\ r\ n

服务器将根据< args >传回各种内部数据，为了方便mm开发者使用，这些参数经常改动，所以在当前版本协议中。

 

general-purpose统计

服务器接受到 stats命令后，将会传回数行这样的数据：

STAT< name>< value >\ r\ n

最终以 END\ r\ n结束。

每一行数据中< name >是统计量的名字，< value >为统计量的值。在下面的表格中列出了响应 stats命令的所有统计量名字、统计量的类型、以及名字的意义。其中32u代表32位无符号整数，64u代表64位无符号整数，32u:32u代表两个被冒号隔开的32位无符号整数。

 

 

名字                            类型       含义

pid                               32u        服务器进程ID

uptime                          32u        服务器启动了多少时间（以秒为单位）

time                              32u        服务器端当前的Unix时间

version                         string     服务器的版本号

pointer_size                  32u        主机操作系统默认的指针大小（通常为32或64）

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         原文：Number of connection structures allocated

                            by the server

cmd_get                        64u        执行取数据操作的次数

cmd_set                        64u         执行存储数据操作的次数

get_hits                         64u         请求成功次数

get_misses                    64u         请求时未找到相应key的次数

evictions                        64u         删除有效条目的次数                                                                                    

bytes_read                    64u         服务器从网络读取到数据的字节数

bytes_written                64u         服务器向网络发送的字节数

limit_maxbytes              32u        服务器允许使用的最大存储量的字节数

threads                         32u         请求的工作线程数目，参见doc/threads.txt

还有一些写不下，置于附件中