📚 课程目录第1章接口契约概述

1. 接口契约概述：什么是接口契约、为什么需要接口契约、接口契约在微服务架构中的角色

1.1 什么是接口契约

接口契约（Interface Contract）是服务提供方与消费方之间就交互行为达成的正式约定。在 Go 语言中，接口契约不仅包含方法签名（函数名、参数、返回值），还包含语义约束：前置条件、后置条件、不变式以及错误处理规范。

  核心定义：接口契约 = 语法契约（方法签名）+ 语义契约（行为约束）+ 质量契约（性能、可用性、容错）。

一个典型的 Go 接口契约示例：

// OrderService 定义订单服务的接口契约
type OrderService interface {
    // CreateOrder 创建订单
    // 前置条件：items 非空且每个 item 的 ProductID 和 Quantity 合法
    // 后置条件：返回的 Order 包含有效 ID 和 CreatedAt 时间戳
    // 错误契约：当库存不足时返回 ErrInsufficientStock
    CreateOrder(ctx context.Context, userID string, items []OrderItem) (Order, error)

    // CancelOrder 取消订单
    // 前置条件：orderID 对应的订单状态为 "pending"
    // 后置条件：订单状态变更为 "cancelled"，库存回滚
    // 错误契约：当订单已发货时返回 ErrOrderAlreadyShipped
    CancelOrder(ctx context.Context, orderID string) error
}

1.2 为什么需要接口契约

在大型分布式系统中，没有显式契约的接口会导致以下问题：

问题	无契约时的表现	有契约时的表现
边界模糊	服务间职责交叉，修改一个接口影响多个调用方	契约明确划定边界，修改需双方协商
隐式依赖	调用方依赖实现细节，耦合度高	调用方只依赖契约，实现可独立演进
错误处理混乱	错误类型不统一，调用方难以区分业务错误与系统错误	契约定义错误码和错误类型，调用方可精确处理
测试困难	需要启动完整服务才能验证接口行为	基于契约可生成 mock，实现独立单元测试
文档缺失	接口文档与代码脱节，维护成本高	契约即文档，代码与文档一致

实践建议：在 Go 项目中，接口契约应作为 API 层与业务层之间的防火墙。业务逻辑不直接暴露给外部，而是通过契约层进行适配，这样即使底层实现重构，接口签名和语义也不受影响。

1.3 接口契约在微服务架构中的角色

在微服务架构中，接口契约承担着服务间通信的宪法角色。它定义了服务边界、数据格式、错误处理和版本演进规则。

1.4 接口契约的三大维度

在 Go 微服务实践中，接口契约可以从以下三个维度进行设计：

语法契约（Syntactic Contract）：定义接口的方法签名、参数类型、返回值类型。这是 Go 编译器强制检查的部分。
语义契约（Semantic Contract）：定义业务规则、前置条件、后置条件、不变式。这部分通过文档、测试和代码注释来约束。
质量契约（Quality Contract）：定义性能指标（响应时间、吞吐量）、可用性指标（SLA、错误率）、容错策略（超时、重试、熔断）。

常见误区：很多团队只关注语法契约（接口定义），忽略了语义契约和质量契约。这导致接口签名正确但行为不符合预期，或者在高并发场景下服务雪崩。完整的接口契约必须覆盖三个维度。

1.5 接口契约与 DDD 限界上下文的关系

在领域驱动设计中，限界上下文（Bounded Context）是划分业务边界的核心单元。接口契约正是限界上下文之间的通信协议。

1.6 接口契约的演进策略

在微服务架构中，接口契约需要支持版本演进。常见的策略包括：

策略	描述	适用场景
向后兼容	新增字段或方法，不删除或修改已有字段	内部服务间调用，版本迭代频繁
版本号路由	通过 URL 路径或请求头区分版本（如 /v1/orders, /v2/orders）	对外 API，需要长期维护多个版本
契约测试驱动	使用消费者驱动契约（CDC）测试，确保契约变更不影响已有消费者	多团队协作，服务数量较多
防腐层适配	在消费方侧增加适配层，将外部契约转换为内部模型	集成第三方服务或遗留系统

Go 语言实践：在 Go 中，接口契约的演进应遵循 “最小接口原则”。每个接口只包含调用方真正需要的方法，避免定义大而全的接口。使用 io.Reader、io.Writer 等标准库接口作为设计范例——它们只包含一个方法，却能被广泛复用。

1.7 本章小结

接口契约是微服务架构中服务间通信的基石。它从语法、语义、质量三个维度定义了服务交互的规则，确保服务可以独立演进、独立部署、独立测试。在 DDD 实践中，接口契约是限界上下文之间的通信协议，通过契约隔离内部领域模型与外部依赖，实现业务模块的高内聚、低耦合。