4. Provider SDK 选择：Plugin SDK v2 与 Plugin Framework 对比

在定制服务目录类型的 Terraform Provider 时，SDK 选型直接决定了开发效率、维护成本和功能边界。当前 HashiCorp 官方维护两套 SDK：Terraform Plugin SDK v2（成熟稳定）与 Terraform Plugin Framework（新一代架构）。本章从服务目录场景出发，系统对比两者的设计哲学、能力差异与迁移路径。

4.1 两代 SDK 的定位与演进

Plugin SDK v2 自 2020 年发布以来，支撑了数百个官方与社区 Provider，是当前生态最广泛的开发基础。Plugin Framework 于 2022 年进入 GA，旨在解决 v2 在类型系统、协议扩展和资源生命周期管理上的结构性限制。

4.2 服务目录场景下的 SDK 适配性分析

服务目录基础设施类型通常具有以下特征，直接影响 SDK 选择：

• 复杂嵌套结构：例如虚拟机规格包含 CPU、内存、磁盘阵列，磁盘阵列又包含多个卷定义。
• 条件验证逻辑：某些参数组合必须互斥或依赖，如“若启用高可用，则必须指定备用区域”。
• 导入与漂移检测：服务目录中的资源可能由外部系统创建，需要支持 terraform import 和状态漂移自动修复。
• 多版本兼容：服务目录 API 可能同时存在 v1/v2 版本，Provider 需按版本切换行为。

下表从服务目录典型需求出发，对比两套 SDK 的适配程度：

4.3 架构对比：从 Schema 定义到协议交互

两套 SDK 在架构层面的核心差异体现在 Schema 定义方式和协议交互流程上。下图展示了 Plugin SDK v2 与 Plugin Framework 在 Provider 启动、资源注册、状态同步三个阶段的架构对比：

4.4 代码对比：同一资源的不同实现

以定义一个“服务目录 - 虚拟机规格”资源为例，展示两套 SDK 在 Schema 定义和 CRUD 实现上的差异：

Plugin SDK v2 实现片段

// Schema 定义
func resourceVMInstance() *schema.Resource {
    return &schema.Resource{
        Create: resourceVMInstanceCreate,
        Read:   resourceVMInstanceRead,
        Update: resourceVMInstanceUpdate,
        Delete: resourceVMInstanceDelete,
        Schema: map[string]*schema.Schema{
            "name": {
                Type:     schema.TypeString,
                Required: true,
            },
            "cpu": {
                Type:     schema.TypeInt,
                Required: true,
            },
            "memory_mb": {
                Type:     schema.TypeInt,
                Required: true,
            },
            "disks": {
                Type:     schema.TypeList,
                Optional: true,
                Elem: &schema.Resource{
                    Schema: map[string]*schema.Schema{
                        "size_gb": {Type: schema.TypeInt, Required: true},
                        "type":    {Type: schema.TypeString, Required: true},
                    },
                },
            },
        },
    }
}

// Create 实现
func resourceVMInstanceCreate(d *schema.ResourceData, m interface{}) error {
    name := d.Get("name").(string)
    cpu := d.Get("cpu").(int)
    // 手动处理嵌套列表
    disks := d.Get("disks").([]interface{})
    for _, disk := range disks {
        diskMap := disk.(map[string]interface{})
        _ = diskMap["size_gb"].(int)
    }
    // 调用 API 创建资源
    d.SetId("vm-" + name)
    return nil
}

Plugin Framework 实现片段

// Schema 定义
func (r *vmInstanceResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
    resp.Schema = schema.Schema{
        Attributes: map[string]schema.Attribute{
            "name": schema.StringAttribute{
                Required: true,
            },
            "cpu": schema.Int64Attribute{
                Required: true,
            },
            "memory_mb": schema.Int64Attribute{
                Required: true,
            },
            "disks": schema.ListAttribute{
                Optional: true,
                ElementType: types.ObjectType{
                    AttrTypes: map[string]attr.Type{
                        "size_gb": types.Int64Type,
                        "type":    types.StringType,
                    },
                },
            },
        },
    }
}

// Create 实现
func (r *vmInstanceResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
    var data vmInstanceModel
    diags := req.Plan.Get(ctx, &data)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
    // 直接使用强类型结构体，无需手动类型断言
    _ = data.Name.ValueString()
    _ = data.CPU.ValueInt64()
    // 嵌套对象自动解析
    for _, disk := range data.Disks.Elements() {
        diskObj := disk.(types.Object)
        var diskModel diskModel
        diskObj.As(ctx, &diskModel, types.ObjectAsOptions{})
        _ = diskModel.SizeGB.ValueInt64()
    }
    // 调用 API 创建资源
    data.ID = types.StringValue("vm-" + data.Name.ValueString())
    diags = resp.State.Set(ctx, &data)
    resp.Diagnostics.Append(diags...)
}

4.5 服务目录场景的选型决策矩阵

综合以上分析，以下决策矩阵可帮助团队根据服务目录的具体需求选择 SDK：

4.6 本章小结

Plugin SDK v2 与 Plugin Framework 并非简单的版本升级，而是两种不同的架构设计。对于服务目录基础设施类型开发：

• 简单 CRUD 类型（属性扁平、无嵌套、无复杂验证）可继续使用 SDK v2，开发效率高。
• 复杂服务目录类型（嵌套结构、条件验证、导入支持）应优先选择 Plugin Framework，其强类型系统和扩展接口可显著降低维护成本。
• 团队技术储备和现有代码库也是重要考量因素，不建议为“追新”而盲目迁移。