在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

etcd-io/etcd

菜单

客户端 API

相关源文件

目的与范围

本文档提供了关于 etcd 客户端 API 的技术信息，该 API 允许应用程序以编程方式与 etcd 集群进行交互。客户端 API 提供了执行键值操作、监视更改、管理租约和处理集群操作的接口。有关命令行界面的信息，请参阅 etcdctl CLI。

客户端库概述

etcd 提供客户端库，使应用程序能够使用定义明确的 API 与 etcd 集群进行通信。主要客户端库是 clientv3，这是一个 Go 客户端，使用 gRPC 与 etcd 服务器进行通信。

来源： client/v3/go.mod

etcd 客户端库以模块化结构组织，以保持关注点的清晰分离。

来源： go.mod、client/v3/go.mod、etcdctl/go.mod

客户端架构

clientv3 库围绕多个服务接口构建，每个接口处理特定的功能。

来源： client/v3/go.mod、etcdctl/go.mod

请求处理流程

下图说明了客户端请求是如何处理的。

来源： client/v3/go.mod

关键客户端接口

KV 服务

KV 服务提供在 etcd 中操作键值对的操作。

  • Put：存储键值对
  • Get：检索一个或多个键值对
  • Delete：删除一个或多个键值对
  • Compact：压缩 etcd 中的事件历史
  • Txn：创建事务（具有原子性保证的多个操作）

Watch 服务

Watch 服务提供监视键更改的方法。

  • Watch：在键或键前缀上建立监视，并返回一个事件通道。

Lease 服务

Lease 服务提供生存时间 (TTL) 功能。

  • Grant：创建具有指定 TTL 的租约
  • Revoke：撤销租约
  • KeepAlive：通过刷新 TTL 来保持租约有效
  • TimeToLive：获取关于租约的信息

Auth 服务

Auth 服务提供身份验证和授权能力。

  • AuthEnable/AuthDisable：启用或禁用身份验证
  • UserAdd/UserDelete：添加或删除用户
  • RoleAdd/RoleDelete：添加或删除角色
  • UserGrantRole：向用户授予角色

Cluster 服务

Cluster 服务提供集群管理操作。

  • MemberList：列出集群中的所有成员
  • MemberAdd：向集群添加新成员
  • MemberRemove：从集群中移除成员
  • MemberUpdate：更新成员的对等 URL

Maintenance 服务

Maintenance 服务提供集群维护操作。

  • Alarm：管理警报（列出、解除）
  • Status：获取 etcd 成员的状态
  • Defragment：对成员的后端数据库进行碎片整理
  • Snapshot：创建 etcd 数据库的快照

来源： etcdctl/go.mod、client/v3/go.mod

客户端使用示例

以下是如何使用 etcd 客户端的基本示例。

来源： client/v3/go.mod

配置选项

创建客户端时，可以指定各种配置选项。

来源： client/v3/go.mod

高级特性

事务

etcd 通过 Txn API 支持原子 If/Then/Else 事务。

分布式锁

客户端库提供了用于分布式协调的实用程序。

来源： client/v3/go.mod

错误处理

etcd 客户端返回的错误可以通过 clientv3/v3rpc 包进行检查。

来源： client/v3/go.mod

指标与监控

etcd 客户端提供 Prometheus 指标，可用于监视客户端操作。

  • 发送/接收的字节数
  • 活动连接数
  • 请求延迟
  • 请求失败率

来源： client/v3/go.mod，其中包含 github.com/prometheus/client_golang 作为依赖项。

版本控制与兼容性

etcd 客户端遵循语义版本控制，并在主要版本号内保持向后兼容性。客户端库版本与它们设计的 etcd 服务器版本相匹配。

当前的客户端库是 v3，它与 etcd 的 v3 API 一起工作。旧的 v2 客户端为向后兼容性而维护，但不推荐用于新应用程序。

来源： client/v3/go.mod、go.mod