Golang Kratos 系列：领域层model定义是自洽还是直接依赖第三方（三）

在领域层设计中，绝对不应该直接依赖proto生成的模型（如pb.User），而应该创建独立的领域模型。

一、核心原则：领域模型与技术实现解耦

二、具体实施策略

1. 定义领域模型（独立）

// internal/domain/user.go
package domain

type User struct {
    ID       UserID    // 领域专用ID类型
    Name     string    // 业务校验逻辑在此
    Email    Email     // 值对象
    Status   UserStatus 
}

// 业务方法
func (u *User) IsActive() bool {
    return u.Status == StatusActive
}

// 值对象示例
type Email string

func (e Email) Validate() error {
    // 业务规则校验
    if !regexp.Match(`^[^@]+@\w+\.\w+$`, e) {
        return ErrInvalidEmail
    }
    return nil
}

2. 转换层实现（adapter）

// internal/data/user_adapter.go
package data

func toDomainUser(pbUser *pb.User) (*domain.User, error) {
    email := domain.Email(pbUser.Email)
    if err := email.Validate(); err != nil {
        return nil, err
    }
    
    return &domain.User{
        ID:     domain.UserID(pbUser.Id), // 类型转换
        Name:   pbUser.Name,
        Email:  email,
        Status: parseStatus(pbUser.Status), // 枚举映射
    }, nil
}

func toPBUser(domainUser *domain.User) *pb.User {
    return &pb.User{
        Id:     string(domainUser.ID),
        Name:   domainUser.Name,
        Email:  string(domainUser.Email),
        Status: string(domainUser.Status),
    }
}

3. 仓储实现示例

// internal/data/user_repo.go
type UserRepo struct {
    db *gorm.DB
}

func (r *UserRepo) FindByID(id domain.UserID) (*domain.User, error) {
    var pbUser pb.User
    if err := r.db.Where("id = ?", string(id)).First(&pbUser).Error; err != nil {
        return nil, err
    }
    return toDomainUser(&pbUser)
}

三、关键决策依据

1. 反对直接使用pb.User的原因

2. 独立领域模型的优势

四、复杂场景处理

1. 多版本API兼容

// 同时支持v1/v2协议
func toDomainUserV1(v1 *pb.v1.User) *domain.User { /*...*/ }
func toDomainUserV2(v2 *pb.v2.User) *domain.User { /*...*/ }

// 统一领域行为
func (u *domain.User) UpgradePlan() {
    // 无论数据来源是v1还是v2，业务逻辑一致
}

2. 高性能转换

// 批量转换工具函数
func BatchToDomain(pbUsers []*pb.User) ([]*domain.User, error) {
    result := make([]*domain.User, len(pbUsers))
    for i, u := range pbUsers {
        var err error
        if result[i], err = toDomainUser(u); err != nil {
            return nil, err
        }
    }
    return result, nil
}

// 使用sync.Pool减少对象创建开销
var userPool = sync.Pool{
    New: func() interface{} { return new(domain.User) },
}

func PoolToDomain(pbUser *pb.User) (*domain.User, error) {
    u := userPool.Get().(*domain.User)
    // 复用对象填充...
    return u, nil
}

五、Kratos最佳实践

1. 项目结构优化

internal/
├── domain
│   ├── user.go         # 纯业务模型
│   └── validator.go    # 业务规则校验
├── data
│   ├── adapter        # 转换层
│   │   └── user.go    # pb <-> domain转换
│   └── user_repo.go   # 实现domain.Repository
└── service            # 保持对domain的纯净依赖

2. Wire依赖配置

// 确保依赖方向正确
func NewUserService() *service.UserService {
    wire.Build(
        service.NewUserService,
        data.NewUserRepo,   // 实现domain.UserRepository
        domain.NewValidator,
    )
    return &service.UserService{}
}

3. 自动生成工具

# Makefile 生成领域模型（可选）
gen-domain:
    tools/gen-domain -proto=api/user.proto -output=internal/domain/user.go

六、验证指标

1. 编译时检查

   # 确认domain不依赖pb
   grep "import .*pb" internal/domain/*.go
   # 应无输出
   

2. 性能基准测试

   func BenchmarkConversion(b *testing.B) {
       pbUser := generateTestPBUser()
       for i := 0; i < b.N; i++ {
           toDomainUser(pbUser) // 应<100ns/op
       }
   }
   

3. 变更影响测试

   # 修改proto字段后验证：
   - domain层测试不应报错
   - 仅需修改adapter层
   - 业务逻辑测试保持通过
   

结论

必须创建独立领域模型，通过转换层与proto模型隔离。虽然增加了转换代码，但带来的架构收益远超成本：

1. 业务免疫性：proto变更不影响核心逻辑
2. 架构自由度：可随时替换底层技术实现
3. 测试友好性：领域单元测试不依赖外部协议
4. 长期可维护：业务语义与技术实现解耦

这种设计下，proto仅是数据传输载体，而领域模型才是业务真理之源。

同理，对于使用proto或者其他第三方api请求，他的请求和响应结构体在领域层也应该定义领域层的model，而不是直接引用protobuf生成的model或第三方的定义，尤其是不稳定的第三方。
下面举一个外部API和Protobuf模型处理的例子，通过领域建模和防腐层实现彻底解耦：

一、核心架构原则

二、分层设计实现

1. 领域层（独立模型）

// internal/domain/payment.go
type Payment struct {
    ID        PaymentID  // 领域专用ID类型
    Amount    Money      // 值对象
    Status    PaymentStatus
    CreatedAt time.Time
}

// 业务方法
func (p *Payment) IsRefundable() bool {
    return p.Status == StatusCompleted && 
           p.CreatedAt.After(time.Now().Add(-30*24*time.Hour))
}

// 值对象
type Money struct {
    Value    decimal.Decimal
    Currency string 
}

2. 防腐层（Adapter）

// internal/infra/payment/adapter.go

// 转换第三方API响应 → 领域模型
func ToDomainPayment(apiResp *thirdparty.PaymentResponse) (*domain.Payment, error) {
    amount, err := domain.NewMoney(
        apiResp.AmountCents / 100.0,
        apiResp.Currency,
    )
    if err != nil {
        return nil, fmt.Errorf("invalid amount: %w", err)
    }

    return &domain.Payment{
        ID:        domain.PaymentID(apiResp.PaymentID),
        Amount:    amount,
        Status:    parseStatus(apiResp.StatusCode), // 状态码转换
        CreatedAt: apiResp.CreateTime,
    }, nil
}

// 转换领域模型 → API请求
func ToAPIRequest(p *domain.Payment) *thirdparty.CreatePaymentRequest {
    return &thirdparty.CreatePaymentRequest{
        AmountCents: p.Amount.Value.Mul(decimal.NewFromInt(100)).IntPart(),
        Currency:    p.Amount.Currency,
        Metadata:    buildMetadata(p), // 复杂映射逻辑
    }
}

3. 网关接口（领域依赖）

// internal/domain/gateway.go
type PaymentGateway interface {
    Create(payment *Payment) (*Payment, error)  // 使用领域模型
    Query(id PaymentID) (*Payment, error)
}

三、关键决策依据

1. 反对直接引用Proto/API模型的理由

2. 转换层核心职责

四、复杂场景处理

1. 多版本API兼容

// 支持新旧版API响应
func ToDomainPaymentV1(resp *v1.PaymentResponse) (*domain.Payment, error) {
    // 处理v1特定字段
}

func ToDomainPaymentV2(resp *v2.PaymentResponse) (*domain.Payment, error) {
    // 处理v2新增字段
}

// 业务逻辑统一处理
func (s *PaymentService) Process(p *domain.Payment) error {
    // 不感知API版本差异
}

2. 动态字段映射

// 配置化字段映射（JSON/YAML）
type FieldMapping struct {
    Amount struct {
        Source  string `json:"source"`  // "amount_cents"
        Convert string `json:"convert"` // "x / 100"
    } `json:"amount"`
}

func TransformByConfig(resp interface{}, config FieldMapping) (*domain.Payment, error) {
    // 反射+表达式引擎动态转换
}

3. 错误处理标准化

func ToDomainPayment(resp *APIResponse) (*domain.Payment, error) {
    if resp.ErrorCode != "" {
        switch resp.ErrorCode {
        case "LIMIT_EXCEEDED":
            return nil, domain.ErrPaymentLimitExceeded
        default:
            return nil, domain.NewPaymentError(
                resp.ErrorMessage,
                map[string]interface{}{"code": resp.ErrorCode},
            )
        }
    }
    // ...正常转换
}

五、性能优化方案

1. 对象池复用

var paymentPool = sync.Pool{
    New: func() interface{} { return new(domain.Payment) },
}

func PoolToDomain(resp *APIResponse) (*domain.Payment, error) {
    p := paymentPool.Get().(*domain.Payment)
    // 重置并填充数据
    p.ID = domain.PaymentID(resp.ID)
    // ...
    return p, nil
}

func ReleasePayment(p *domain.Payment) {
    paymentPool.Put(p)
}

2. 零拷贝转换

// 使用指针引用大对象
func ToDomainPaymentLarge(resp *LargeAPIResponse) (*domain.Payment, error) {
    return &domain.Payment{
        ID:     domain.PaymentID(resp.ID),
        // 直接引用API数据（只读场景）
        Metadata: (*json.RawMessage)(&resp.Metadata), 
    }, nil
}

3. 并行转换

func BatchConvert(responses []*APIResponse) ([]*domain.Payment, error) {
    result := make([]*domain.Payment, len(responses))
    var wg sync.WaitGroup
    errChan := make(chan error, 1)
    
    for i, resp := range responses {
        wg.Add(1)
        go func(idx int, r *APIResponse) {
            defer wg.Done()
            p, err := ToDomainPayment(r)
            if err != nil {
                select {
                case errChan <- err:
                default:
                }
                return
            }
            result[idx] = p
        }(i, resp)
    }
    
    wg.Wait()
    select {
    case err := <-errChan:
        return nil, err
    default:
        return result, nil
    }
}

六、验证指标

1. 架构纯净度检查

   # 确保domain层无proto/api依赖
   grep -r "import .*pb" ./internal/domain/
   grep -r "import .*thirdparty" ./internal/domain/
   

2. 转换性能基准

   func BenchmarkConversion(b *testing.B) {
       resp := mockAPIResponse()
       b.ResetTimer()
       for i := 0; i < b.N; i++ {
           _, _ = ToDomainPayment(resp) // 应 < 500ns/op
       }
   }
   

3. 变更影响测试

   # 修改API响应结构后：
   - 只允许修改adapter层
   - domain层测试应100%通过
   - service层无需修改
   

结论

必须为所有外部交互定义领域模型，通过防腐层进行转换。虽然需要额外编写适配代码，但收益远超成本：

1. 业务语义完整性：领域模型是业务语言的直接表达
2. 技术隔离：可无缝替换API供应商或协议格式
3. 测试确定性：领域测试不依赖外部数据格式
4. 演进自由：业务规则变更不波及基础设施层

在这种架构下，领域模型成为系统的唯一真相源，外部协议仅是数据输入/输出载体。这是构建可持续演进系统的核心设计原则。