etcd是元数据一致性的事实标准，因其内置raft、线性一致读、租约、watch等能力，可保障目录树、文件属性等强一致性；自研或换用consul/zookeeper会大幅增加运维成本与出错概率。
为什么 etcd 是元数据一致性的事实标准
因为元数据（目录树、文件属性、锁状态、lease 信息）必须强一致，不能靠最终一致性凑合。etcd 自带 Raft 协议、线性一致读、租约（lease）、watch 机制，开箱即用；自己手写 Raft 或对接 Consul/ZooKeeper，运维成本和出错概率会指数级上升。
常见错误现象：list /dir 在不同客户端看到不一致的子项，或 rename 后旧名仍能 stat 到——本质是元数据没走原子写+顺序广播。
- 所有元数据变更必须走
etcd.Put+etcd.Txn，避免并发覆盖（例如同时创建同名文件） - 目录结构建议用前缀路径建模，如
/meta/bucket/file.txt存文件信息，/meta/bucket/下的 key 用WithPrefix扫描 - 租约（lease）必须显式绑定：创建文件时
Put(..., clientv3.WithLease(leaseID))，否则节点宕机后元数据不会自动清理 - Watch 不要只监听单个 key，而是监听目录前缀并做增量解析——
client.Watch(ctx, "/meta/", clientv3.WithPrefix())
fs.FS 接口无法直接保证元数据一致性
fs.FS 和 fs.File 是纯本地抽象，它不定义任何跨进程同步语义。你实现一个 DFSFS 类型并注册到 os.Open("dfs://...")，不代表 Open 调用内部的 Get 就自动带事务或版本校验。
使用场景：客户端调用 os.Stat("dfs://b1/f1") 时，背后其实是发 gRPC 到元数据服务，再查 etcd —— 这中间每一步都得自己加 context 超时、重试、版本比对。
-
Open方法里必须用client.Get(ctx, key)查 etcd，并检查resp.Kvs[0].Version是否匹配预期（比如配合 mtime 或 generation 字段做乐观锁） - 不要在
ReadDir返回前缓存整个目录列表到内存；应返回一个惰性fs.ReadDirFile，每次Readdir调用才去 etcdGet前缀扫描 - 如果业务允许弱一致性，可用
client.Get(ctx, key, clientv3.WithSerializable())降低读延迟，但要接受短暂 stale read
rename 和 delete 的原子性陷阱
rename 在分布式系统中从来不是原子操作，除非你把它拆成 etcd 的多 key 事务 + 状态机。真实情况是：先删旧路径元数据、再写新路径元数据，中间存在窗口期。
错误做法：直接 etcd.Delete(oldKey); etcd.Put(newKey, ...) —— 若第一步成功第二步失败，文件就“消失”了。
- 正确方式是用
client.Txn(ctx).If(...).Then(...).Else(...)把两步打包为条件事务，例如检查 oldKey 存在且 version 匹配 - delete 必须带 revision 校验：
client.Delete(ctx, key, clientv3.WithRev(expectedRev))，防止误删其他客户端刚写入的新版本 - 删除非空目录？etcd 不支持递归删，得自己遍历
WithPrefix+ 批量Delete，并在事务中记录中间状态（如/meta/deleting/bucket/dir/）防中断
客户端断连时元数据状态恢复难在哪
最常被忽略的点：元数据服务本身无状态，但客户端操作可能卡在“半提交”状态。比如客户端发起 Create，etcd 写成功了，但网络断开导致客户端没收到响应——它不知道该重试还是放弃。
解决方案不是加更多超时，而是把客户端意图也落库：
- 每个写请求生成唯一
op_id，先写入/ops/OPID状态为pending，再执行元数据变更，最后更新为done或failed - 客户端启动时扫描
/ops/下所有pending记录，调用client.Get检查对应元数据 key 是否已存在，决定是否补 confirm 或 rollback - 这个
/ops/表本身也要用 lease 绑定，避免僵尸记录堆积
真正卡住进度的，往往不是 etcd 性能，而是你没想清楚“客户端怎么知道自己刚才那一次调用到底算成功还是失败”。这层状态映射，没有标准库能替你做。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
