ADR 0002 interface defined by consumer

0002 · 接口由使用方定义而非提供方

• 状态：Accepted
• 范围：项目级

背景

Go 社区惯例：接口在使用方声明。提供方预定义接口会导致消费者被迫引入无关方法签名，且多个下游服务需要的方法子集往往不同。

决策

XKit 包默认导出具体类型。接口仅在以下场景由 XKit 自身定义：

1. 该接口就是包的主契约（如 xcache.Cache、xmetrics.Observer、xdlock.Locker）。
2. 有多个并列实现需要统一抽象（如 xsampling.Sampler、xcache 的 Memory/Redis 双实现）。

其他情况一律由调用方按需声明最小接口。

备选方案（被拒）

• 全面接口化：为每个组件预定义 Xxxer 接口——增加无价值表面积，违反"接受接口返回具体类型"。
• 完全不提供接口：单实现场景可行，多实现场景会让消费者自行 wrap，重复 mock 代码。

影响

• 正向：包对外表面积小；消费方可自由 shape 最小接口。
• 代价：测试双路径（mock 消费方接口）需要额外一个适配层。

代码引用

• pkg/util/xkeylock.Locker（主契约）
• pkg/storage/xcache.Cache（多实现）
• 反例约束：pkg/util/xlru 不导出接口（memory/xlru 记录的设计决策）