kv.go

package clientv3

import (

    pb "github.com/coreos/etcd/etcdserver/etcdserverpb"   //protobuffer  

    "golang.org/x/net/context"  

    "google.golang.org/grpc"   //google  rpc 框架

)

type (

    CompactResponse pb.CompactionResponse  //带压缩的响应

    PutResponse     pb.PutResponse   //添加响应

    GetResponse     pb.RangeResponse  // 带区间的响应

    DeleteResponse  pb.DeleteRangeResponse  // 删除带区间数据的响应

    TxnResponse     pb.TxnResponse    //带事务的响应

)

type KV interface {

    // Put puts a key-value pair into etcd.

        //添加键值对到etcd中

    // Note that key,value can be plain bytes array and string is

    // an immutable representation of that bytes array.

       //注意：键值对可以是字节数组或者字符串  字符串是原子性的字节数组

    // To get a string of bytes, do string([]byte(0x10, 0x20)).

        //

    Put(ctx context.Context, key, val string, opts ...OpOption) (*PutResponse, error)

    // Get retrieves keys.

        //获取键对应的值

    // By default, Get will return the value for "key", if any.

        //默认 获取键对应的值  在任何情况下

    // When passed WithRange(end), Get will return the keys in the range [key, end).

        //当opts 使用了 WithRange(end)，将得到键对应的区间[key, end)之间的值

    // When passed WithFromKey(), Get returns keys greater than or equal to key.

             //opts 使用了WithFromKey()，得到大于等于当前key 对应的value

    // When passed WithRev(rev) with rev > 0, Get retrieves keys at the given revision;

                //当opts 使用了 WithRev(rev)，如果版本号rev>0 获取指定的版本号对应的value

    // if the required revision is compacted, the request will fail with ErrCompacted .

    // When passed WithLimit(limit), the number of returned keys is bounded by limit.

             //当opts 使用了 WithLimit(limit)，将得到键对应的区间[key最小值  默认的   end [limit   )的值   例如：  key为 foo   实际的key为 fooN。。。。到foolimit  之间对应的value

    // When passed WithSort(), the keys will be sorted.

             //当opts 使用了 WithSort()，得到的值将排序  按照字典的顺序来排序

    Get(ctx context.Context, key string, opts ...OpOption) (*GetResponse, error)

    // Delete deletes a key, or optionally using WithRange(end), [key, end).

       //  删除一个键值对    更常使用 WithRange(end), [key, end).

    Delete(ctx context.Context, key string, opts ...OpOption) (*DeleteResponse, error)

    // Compact compacts etcd KV history before the given rev.

               // 压缩etcd kv历史数据  通常再给出版本号之前

    Compact(ctx context.Context, rev int64, opts ...CompactOption) (*CompactResponse, error)

    // Do applies a single Op on KV without a transaction.

        //do应用于单一kv操作项，通常是没有事务的

    // Do is useful when declaring operations to be issued at a later time

       //

    // whereas Get/Put/Delete are for better suited for when the operation

    // should be immediately issued at time of declaration.

    // Do applies a single Op on KV without a transaction.

    // Do is useful when creating arbitrary operations to be issued at a

    // later time; the user can range over the operations, calling Do to

    // execute them. Get/Put/Delete, on the other hand, are best suited

    // for when the operation should be issued at the time of declaration.

    Do(ctx context.Context, op Op) (OpResponse, error)

    // Txn creates a transaction.

        //创建事务

    Txn(ctx context.Context) Txn

}

//响应结构体

type OpResponse struct {

    put *PutResponse

    get *GetResponse

    del *DeleteResponse

}

func (op OpResponse) Put() *PutResponse    { return op.put }

func (op OpResponse) Get() *GetResponse    { return op.get }

func (op OpResponse) Del() *DeleteResponse { return op.del }

//kv存储服务客户端的包装

type kv struct {

    remote pb.KVClient

}

//创建kv 服务  带着指定的客户端

func NewKV(c *Client) KV {

    return &kv{remote: RetryKVClient(c)}

}

//创建一个kv服务客户端  带着指定的protobuffer 客户端

func NewKVFromKVClient(remote pb.KVClient) KV {

    return &kv{remote: remote}

}

//kv结构体实现了 kv接口

func (kv *kv) Put(ctx context.Context, key, val string, opts ...OpOption) (*PutResponse, error) {

    r, err := kv.Do(ctx, OpPut(key, val, opts...))

    return r.put, toErr(ctx, err)

}

func (kv *kv) Get(ctx context.Context, key string, opts ...OpOption) (*GetResponse, error) {

    r, err := kv.Do(ctx, OpGet(key, opts...))

    return r.get, toErr(ctx, err)

}

func (kv *kv) Delete(ctx context.Context, key string, opts ...OpOption) (*DeleteResponse, error) {

    r, err := kv.Do(ctx, OpDelete(key, opts...))

    return r.del, toErr(ctx, err)

}

func (kv *kv) Compact(ctx context.Context, rev int64, opts ...CompactOption) (*CompactResponse, error) {

    resp, err := kv.remote.Compact(ctx, OpCompact(rev, opts...).toRequest())

    if err != nil {

        return nil, toErr(ctx, err)

    }

    return (*CompactResponse)(resp), err

}

func (kv *kv) Txn(ctx context.Context) Txn {

    return &txn{

        kv:  kv,

        ctx: ctx,

    }

}

func (kv *kv) Do(ctx context.Context, op Op) (OpResponse, error) {

    for {

        resp, err := kv.do(ctx, op)

        if err == nil {

            return resp, nil

        }

        if isHaltErr(ctx, err) {

            return resp, toErr(ctx, err)

        }

        // do not retry on modifications

        if op.isWrite() {

            return resp, toErr(ctx, err)

        }

    }

}

func (kv *kv) do(ctx context.Context, op Op) (OpResponse, error) {

    var err error

    switch op.t {

    // TODO: handle other ops

    case tRange:

        var resp *pb.RangeResponse

        resp, err = kv.remote.Range(ctx, op.toRangeRequest(), grpc.FailFast(false))

        if err == nil {

            return OpResponse{get: (*GetResponse)(resp)}, nil

        }

    case tPut:

        var resp *pb.PutResponse

        r := &pb.PutRequest{Key: op.key, Value: op.val, Lease: int64(op.leaseID), PrevKv: op.prevKV}

        resp, err = kv.remote.Put(ctx, r)

        if err == nil {

            return OpResponse{put: (*PutResponse)(resp)}, nil

        }

    case tDeleteRange:

        var resp *pb.DeleteRangeResponse

        r := &pb.DeleteRangeRequest{Key: op.key, RangeEnd: op.end, PrevKv: op.prevKV}

        resp, err = kv.remote.DeleteRange(ctx, r)

        if err == nil {

            return OpResponse{del: (*DeleteResponse)(resp)}, nil

        }

    default:

        panic("Unknown op")

    }

    return OpResponse{}, err

}