4. 契约式设计：前置条件、后置条件与不变量

契约式设计（Design by Contract, DbC）将软件组件之间的交互视为一种正式的“契约”。在 Go 的业务模块边界中，接口不仅是方法签名的集合，更是一组明确的语义约束。这些约束由三个核心概念构成：前置条件、后置条件和不变量。

4.1 三大契约要素的定义与职责

4.2 前置条件：调用方的承诺

前置条件定义了调用方在调用接口方法之前必须确保的状态。在 Go 中，前置条件通常通过参数校验、状态检查或类型断言来实现。

// 前置条件示例：转账操作
type TransferRequest struct {
    FromAccountID string
    ToAccountID   string
    Amount        decimal.Decimal
}

// Transfer 方法的前置条件：
// 1. FromAccountID 和 ToAccountID 不能为空
// 2. Amount 必须大于 0
// 3. FromAccountID 不能等于 ToAccountID
func (s *AccountService) Transfer(ctx context.Context, req TransferRequest) error {
    // 前置条件检查
    if req.FromAccountID == "" || req.ToAccountID == "" {
        return ErrInvalidAccountID
    }
    if req.Amount.LessThanOrEqual(decimal.Zero) {
        return ErrInvalidAmount
    }
    if req.FromAccountID == req.ToAccountID {
        return ErrSameAccountTransfer
    }
    // ... 业务逻辑
}

4.3 后置条件：实现方的保证

后置条件描述了方法执行完成后系统必须处于的状态。在 Go 中，后置条件通常通过返回值、错误码或状态变更来体现。

// 后置条件示例：订单创建
type CreateOrderResult struct {
    OrderID     string
    TotalAmount decimal.Decimal
    Status      OrderStatus
}

// CreateOrder 方法的后置条件：
// 1. 返回的 OrderID 不为空
// 2. 返回的 TotalAmount 等于订单中所有商品金额之和
// 3. 返回的 Status 必须为 OrderStatusPending
func (s *OrderService) CreateOrder(ctx context.Context, items []OrderItem) (*CreateOrderResult, error) {
    // ... 业务逻辑
    
    result := &CreateOrderResult{
        OrderID:     generatedID,
        TotalAmount: calculatedTotal,
        Status:      OrderStatusPending,
    }
    
    // 后置条件验证（可选，用于调试或测试）
    if result.OrderID == "" {
        panic("postcondition failed: OrderID must not be empty")
    }
    if !result.TotalAmount.Equal(calculatedTotal) {
        panic("postcondition failed: TotalAmount mismatch")
    }
    if result.Status != OrderStatusPending {
        panic("postcondition failed: Status must be Pending")
    }
    
    return result, nil
}

4.4 不变量：贯穿始终的约束

不变量是对象在其生命周期中必须始终满足的条件。在 Go 中，不变量通常通过结构体的方法（如 Validate()）或构造函数来维护。

// 不变量示例：银行账户
type BankAccount struct {
    mu       sync.RWMutex
    id       string
    balance  decimal.Decimal
    currency string
    status   AccountStatus
}

// 不变量：
// 1. balance 必须始终大于等于 0
// 2. currency 必须是有效的 ISO 4217 货币代码
// 3. status 必须是 AccountStatusActive 或 AccountStatusFrozen

// Validate 方法用于检查不变量
func (a *BankAccount) Validate() error {
    a.mu.RLock()
    defer a.mu.RUnlock()
    
    if a.balance.LessThan(decimal.Zero) {
        return ErrNegativeBalance
    }
    if !isValidCurrency(a.currency) {
        return ErrInvalidCurrency
    }
    if a.status != AccountStatusActive && a.status != AccountStatusFrozen {
        return ErrInvalidAccountStatus
    }
    return nil
}

// 所有修改状态的方法在返回前都应调用 Validate()
func (a *BankAccount) Deposit(amount decimal.Decimal) error {
    a.mu.Lock()
    defer a.mu.Unlock()
    
    if amount.LessThanOrEqual(decimal.Zero) {
        return ErrInvalidAmount
    }
    
    a.balance = a.balance.Add(amount)
    
    // 后置条件：验证不变量
    if err := a.validateInternal(); err != nil {
        // 回滚操作
        a.balance = a.balance.Sub(amount)
        return err
    }
    return nil
}

4.5 契约要素的交互关系

下图展示了前置条件、后置条件与不变量在方法调用过程中的时序关系：

4.6 Go 中的契约实现模式

在 Go 中，由于语言本身不直接支持 DbC，我们需要通过约定和模式来实现契约。以下是三种常用的实现模式：

4.7 装饰器模式实现契约

装饰器模式是 Go 中实现契约式设计的优雅方式，它通过包装原始接口来添加前置和后置条件检查：

// 原始接口
type AccountRepository interface {
    Save(ctx context.Context, account *Account) error
    FindByID(ctx context.Context, id string) (*Account, error)
}

// 契约装饰器
type ContractAccountRepository struct {
    inner AccountRepository
}

func NewContractAccountRepository(inner AccountRepository) *ContractAccountRepository {
    return &ContractAccountRepository{inner: inner}
}

func (r *ContractAccountRepository) Save(ctx context.Context, account *Account) error {
    // 前置条件：account 不能为 nil，且 ID 不能为空
    if account == nil {
        return ErrAccountNil
    }
    if account.ID == "" {
        return ErrAccountIDEmpty
    }
    
    // 执行实际逻辑
    err := r.inner.Save(ctx, account)
    
    // 后置条件：如果无错误，account 必须已持久化
    if err == nil {
        if account.Version <= 0 {
            panic("postcondition failed: account version must be > 0 after save")
        }
    }
    
    return err
}

func (r *ContractAccountRepository) FindByID(ctx context.Context, id string) (*Account, error) {
    // 前置条件：id 不能为空
    if id == "" {
        return nil, ErrAccountIDEmpty
    }
    
    account, err := r.inner.FindByID(ctx, id)
    
    // 后置条件：如果找到，account 不能为 nil
    if err == nil && account == nil {
        panic("postcondition failed: account must not be nil when no error")
    }
    
    return account, err
}

4.8 契约式设计的业务价值

• 明确的错误边界：前置条件失败时，调用方立即知道是自己的问题，无需深入排查实现方代码。
• 文档即代码：契约条件本身就是最精确的接口文档，不会像注释那样过时。
• 测试驱动：契约条件可以直接转化为测试用例，确保接口行为符合预期。
• 故障隔离：后置条件失败时，可以快速定位是实现方的问题，而不是调用方的问题。