3. 接口定义规范：使用 Go interface 进行 API 契约设计

在微服务与分层架构中，接口（Interface）是连接调用方与实现方的唯一契约。Go 语言的 interface{} 机制天然支持隐式实现，这为 API 契约设计提供了极大的灵活性，但也带来了滥用风险。本章将围绕“如何用 Go interface 定义稳定、可 Mock、可治理的 API 契约”展开，给出工程级规范与案例。

3.1 为什么需要接口契约？

没有显式接口的代码，通常表现为：

• 直接依赖具体类型：业务逻辑层直接调用 mysql.UserRepo，导致单元测试必须连接数据库。
• 隐式耦合：修改底层实现时，上层代码被迫重新编译甚至修改。
• 无法 Mock：无法在测试中替换为内存实现或桩对象。

引入接口契约后，上述问题得到系统性解决：

3.2 接口定义规范：从命名到粒度

一个可治理的接口契约，必须满足以下规范：

3.2.1 命名规范

• 接口名：以 “er” 结尾（如 UserRepository、Notifier），或直接描述行为（如 Storage、Cache）。
• 方法名：动词 + 名词，清晰表达业务意图（如 SaveUser、GetOrderByID）。
• 包名：接口定义在消费方（调用方）所在的包，而非实现方。例如 service 包定义 UserRepository，repository/mysql 包实现它。

3.2.2 粒度规范

• 单一职责：一个接口只描述一组高度相关的操作。避免“万能接口”（如 UserService 包含 CRUD + 发邮件 + 生成报表）。
• 方法数量：建议不超过 5 个方法。超过时考虑拆分为多个小接口。
• 参数与返回值：使用具名结构体作为参数/返回值，避免超过 3 个的平铺参数。

type UserService interface {
    Create(ctx context.Context, u *User) error
    Get(ctx context.Context, id int64) (*User, error)
    Update(ctx context.Context, u *User) error
    Delete(ctx context.Context, id int64) error
    SendWelcomeEmail(ctx context.Context, userID int64) error
    GenerateReport(ctx context.Context, start, end time.Time) ([]byte, error)
}

type UserRepository interface {
    Create(ctx context.Context, u *User) error
    Get(ctx context.Context, id int64) (*User, error)
    Update(ctx context.Context, u *User) error
    Delete(ctx context.Context, id int64) error
}

type WelcomeEmailSender interface {
    Send(ctx context.Context, userID int64) error
}

type ReportGenerator interface {
    Generate(ctx context.Context, start, end time.Time) ([]byte, error)
}

3.3 接口契约的层级结构

在典型的三层架构（Handler → Service → Repository）中，接口契约位于 Service 层和 Repository 层的边界：

关键规则：

• 接口定义在消费方：Service 层定义它需要的 Repository 接口，而不是由 Repository 层定义。
• 实现方隐式实现：MySQL、Mock、Cache 等 Repository 实现只需拥有对应方法签名，无需显式声明 implements。
• 依赖注入：在 main 函数或 wire 中，将具体实现注入到消费方。

3.4 接口与 Mock 的协同

接口契约的最大工程收益之一，是让 Mock 依赖隔离成为可能。以下是一个典型的 Mock 实现模式：

// service/user_repository.go —— 接口定义（消费方）
package service

import "context"

type UserRepository interface {
    GetByID(ctx context.Context, id int64) (*User, error)
    Save(ctx context.Context, u *User) error
}

// service/user_service.go —— 业务逻辑
type UserService struct {
    repo UserRepository
}

func NewUserService(repo UserRepository) *UserService {
    return &UserService{repo: repo}
}

func (s *UserService) GetUser(ctx context.Context, id int64) (*User, error) {
    return s.repo.GetByID(ctx, id)
}

// service/mock_user_repository.go —— Mock 实现（测试用）
package service

import "context"

type MockUserRepository struct {
    GetByIDFunc func(ctx context.Context, id int64) (*User, error)
    SaveFunc    func(ctx context.Context, u *User) error
}

func (m *MockUserRepository) GetByID(ctx context.Context, id int64) (*User, error) {
    return m.GetByIDFunc(ctx, id)
}

func (m *MockUserRepository) Save(ctx context.Context, u *User) error {
    return m.SaveFunc(ctx, u)
}

// service/user_service_test.go —— 单元测试
func TestGetUser(t *testing.T) {
    mock := &MockUserRepository{
        GetByIDFunc: func(ctx context.Context, id int64) (*User, error) {
            return &User{ID: id, Name: "Alice"}, nil
        },
    }
    svc := NewUserService(mock)
    user, err := svc.GetUser(context.Background(), 1)
    // 断言 user.Name == "Alice" 且 err == nil
}

3.5 接口治理清单

在 API 设计治理中，接口契约需要纳入以下检查项：

3.6 常见陷阱与避坑

• 陷阱1：接口定义在实现方。导致消费方被迫 import 实现包，破坏依赖方向。
• 陷阱2：接口过于抽象。如 type Repository interface { Execute(ctx context.Context, query string, args ...interface{}) (interface{}, error) }，丧失类型安全。
• 陷阱3：在接口中使用具体类型。如 GetByID(ctx context.Context, id int64) (*sql.Row, error)，将 SQL 细节泄露到契约中。
• 陷阱4：为每个结构体都定义接口。只有存在多个实现或需要 Mock 时，才引入接口。否则过度设计。

3.7 小结

Go interface 是 API 契约设计的核心语法工具。通过将接口定义在消费方、控制粒度、配合 Mock 实现，可以实现：

• 依赖倒置：高层不依赖低层，两者依赖抽象。
• 测试隔离：任意依赖均可替换为 Mock，单测秒级运行。
• 架构演进：替换底层实现（如 MySQL → Redis + MySQL）时，业务层零改动。