3. 接口契约设计原则：ISP、面向契约与Go隐式实现

在搜索系统的尾延迟治理中，接口契约是连接各模块的“法律条文”。本章聚焦三大核心原则：接口隔离原则（ISP）、面向契约设计（DbC）以及Go语言独特的隐式接口实现。这三者共同决定了搜索系统各组件之间的耦合度与可测试性。

3.1 接口隔离原则（ISP）

ISP要求：客户端不应被迫依赖它们不使用的接口。在搜索系统中，一个“全能”的SearchService接口往往包含查询、索引、缓存管理、日志导出等方法，导致任何实现都必须提供所有方法，即使某些模块只需要查询能力。

3.2 面向契约设计（DbC）

DbC强调：每个接口方法都附带前置条件、后置条件和不变式。在Go中，这些契约通常通过文档注释、单元测试和panic保护来实现。

// QueryExecutor 定义查询执行契约
type QueryExecutor interface {
    // Search 执行全文搜索
    // 前置条件：query 非空，timeout > 0
    // 后置条件：返回结果按相关性降序排列
    // 不变式：不修改底层索引文件
    Search(ctx context.Context, query string, timeout time.Duration) ([]Result, error)
}

契约的三种检查方式：

• 编译期检查：接口签名确保参数类型正确
• 运行期断言：在关键路径使用if !condition { panic("contract violated") }
• 测试期验证：通过go test覆盖前置/后置条件

3.3 Go接口的隐式实现

Go的接口实现是隐式的：类型只要拥有接口要求的所有方法，就自动实现了该接口，无需显式声明implements关键字。这一特性对搜索系统的模块化设计影响深远。

// 定义接口
type Searcher interface {
    Search(ctx context.Context, q string) ([]Result, error)
}

// 隐式实现：无需声明 implements Searcher
type ElasticSearcher struct {
    client *elastic.Client
}

func (e *ElasticSearcher) Search(ctx context.Context, q string) ([]Result, error) {
    // 实际调用ES
    return e.client.Search(q)
}

// 另一个隐式实现
type MockSearcher struct {
    results []Result
}

func (m *MockSearcher) Search(ctx context.Context, q string) ([]Result, error) {
    return m.results, nil
}

隐式实现带来的三大优势：

1. 松耦合：实现方不需要导入接口定义包，只需方法签名一致
2. 易于Mock：测试时只需定义一个满足接口的本地结构体，无需依赖第三方Mock框架
3. 接口演进：新增方法不会破坏已有实现（除非接口被显式断言）

3.4 三原则协同：搜索系统接口契约架构

下图展示了ISP、DbC和隐式实现如何共同构建搜索系统的接口层：

3.5 实战：为搜索尾延迟设计接口契约

以下是一个完整的接口契约示例，专门针对尾延迟治理场景：

// LatencySensitiveSearcher 对延迟敏感的搜索接口
type LatencySensitiveSearcher interface {
    // SearchWithBudget 在指定延迟预算内执行搜索
    // 前置条件：budget > 0 && budget < 5*time.Second
    // 后置条件：若超时返回 partialResults + ErrTimeout
    // 不变式：不修改原始索引
    SearchWithBudget(ctx context.Context, query string, budget time.Duration) ([]Result, error)
}

// 编译期检查：确保结构体实现了接口
var _ LatencySensitiveSearcher = (*ElasticSearcher)(nil)

type ElasticSearcher struct {
    client *elastic.Client
}

func (e *ElasticSearcher) SearchWithBudget(ctx context.Context, query string, budget time.Duration) ([]Result, error) {
    // 前置条件断言
    if query == "" {
        panic("LatencySensitiveSearcher: query must not be empty")
    }
    if budget <= 0 || budget > 5*time.Second {
        panic("LatencySensitiveSearcher: budget out of range")
    }

    // 创建带预算的 context
    ctx, cancel := context.WithTimeout(ctx, budget)
    defer cancel()

    // 执行搜索
    results, err := e.client.Search(ctx, query)
    if err != nil {
        if errors.Is(err, context.DeadlineExceeded) {
            // 返回部分结果
            return results[:min(len(results), 10)], ErrTimeout
        }
        return nil, err
    }
    return results, nil
}

3.6 接口契约的测试策略

利用Go的隐式实现，可以轻松为接口创建测试替身：

// 测试用隐式实现
type FakeSearcher struct {
    results []Result
    delay   time.Duration
}

func (f *FakeSearcher) SearchWithBudget(ctx context.Context, query string, budget time.Duration) ([]Result, error) {
    // 模拟延迟
    select {
    case <-time.After(f.delay):
        return f.results, nil
    case <-ctx.Done():
        return nil, context.DeadlineExceeded
    }
}

func TestSearchWithBudget_Timeout(t *testing.T) {
    searcher := &FakeSearcher{
        results: []Result{{ID: "1", Score: 0.9}},
        delay:   100 * time.Millisecond,
    }

    ctx := context.Background()
    results, err := searcher.SearchWithBudget(ctx, "test", 50*time.Millisecond)

    if !errors.Is(err, ErrTimeout) {
        t.Errorf("expected ErrTimeout, got %v", err)
    }
    if len(results) != 0 {
        t.Errorf("expected empty results on timeout, got %d", len(results))
    }
}