尧图网页设计 
Terraform AWS Provider 资源生命周期代码审查指南CRUD 顺序、错误处理与 AutoFlex 转换规范【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws本指南围绕 terraform-provider-aws 仓库内维护者使用的代码审查技能文档.agents/skills/review-lifecycle/SKILL.md展开系统讲解 Framework 资源Resource生命周期代码的审查要点CRUD 四步操作的顺序约束、smerr/smarterr错误处理规范以及 AutoFlex 模型与 AWS SDK 结构体之间的转换约定。读者读完可掌握对该仓库internal/service/**/*.go中非测试资源代码的完整评审清单并理解每一条规定背后的源码实现依据。适用范围与审查角色该技能文档由review-pr技能加载用于在审查 PR 时检查非测试资源逻辑代码即internal/service/**/*.go下的 Create/Read/Update/Delete、错误包装、flex.Expand/flex.Flatten/flex.Diff调用。审查者需代入maintainer维护者视角。审查范围具体包括三个方面CRUD 步骤顺序每个生命周期方法的调用次序是否符合仓库既定模板错误处理是否使用smerr/smarterr统一包装而非裸用框架诊断AutoFlex模型model与 SDK 结构体之间的转换是否走 AutoFlex 自动生成路径。注册注解Registration Annotations工厂函数上方的契约每个工厂函数factory function上方必须有一行注册注解用于把 Go 结构体与 Terraform 资源名绑定。审查时需标记缺失注解或工厂函数名/资源名不一致的情况。构造Construct注解Annotation资源Framework// FrameworkResource(aws_svc_thing, nameHuman Name)数据源Framework// FrameworkDataSource(aws_svc_thing, nameHuman Name)列表资源Framework// FrameworkListResource(aws_svc_thing)列表资源SDKv2// SDKListResource(aws_svc_thing)其中aws_svc_thing是 Terraform 侧资源地址如aws_iam_rolename为面向用户的可读名称。注解既是代码生成工具见 internal/generate 下各生成器解析的输入也是审查时核对资源注册是否正确的第一道关卡。结构体嵌入Struct Embeds组合而非手写新建资源结构体必须通过嵌入框架提供的组合组件来获得标准行为标准模板如下type fooResource struct { framework.ResourceWithModel[fooResourceModel] framework.WithTimeouts // only when a timeouts block is present framework.WithImportByIdentity // not WithImportByID for new resources }审查要点新资源必须使用framework.WithImportByIdentity若新资源出现framework.WithImportByID直接标记。WithImportByID只是把导入 ID 原样透传到id属性见 internal/framework/with_import_by_id.go其实现为resource.ImportStatePassthroughID(ctx, path.Root(names.AttrID), request, response)而WithImportByIdentity会依据资源标识类型ARN、单例、单参数、多参数分派到不同的导入器见 internal/framework/with_import_by_identity.go这正是仓库按资源标识identity导入设计参见 docs/resource-identity.md在生命周期层的要求。使用framework.ResourceWithModel[T]而非ResourceWithConfigure前者在 internal/framework/resource_with_model.go 中组合了ResourceWithConfigure、withNoOpUpdate与withModel并额外提供ValidateModel——当模型包含timeouts字段时会在校验前把空白 timeouts 块注入 schema避免Expected framework type ... Received framework type ...这类类型不匹配错误。数据源使用framework.DataSourceWithModel[T]。WithTimeouts仅在资源确实含timeouts块时嵌入。其实现见 internal/framework/with_timeouts.go提供SetDefaultCreateTimeout/CreateTimeout等四个方向的方法读取配置失败时回退到默认值并打 warning 日志。CRUD 步骤顺序逐方法审查清单这是该技能的核心部分。每个生命周期方法的调用顺序都有固定模板偏离即标记。Create先 Expand 后 Flatten标准顺序获取 client → 读取 plan →flex.Expand→ 给带标签资源设置input.Tags getTagsIn(ctx)→ 调用 AWS Create API →flex.Flatten把输出写回 plan → wait →resp.State.Set(ctx, plan)。需要重点标记的问题Create 之后没有把 API 返回的输出读回 plan。这会直接导致计算属性computed attributes在 state 中保持 unknown后续依赖该属性的资源无法正确解析。ReadNotFound 要优雅退出标准顺序获取 client → 读取 state → finder 查找 → 命中retry.NotFound(err)时追加fwdiag.NewResourceNotFoundWarningDiagnostic(err)警告、调用resp.State.RemoveResource(ctx)并返回 → 否则 flatten →resp.State.Set。retry.NotFound在 internal/retry/error.go 中实现用于识别 finder 层包装过的未找到错误fwdiag见 internal/errs/fwdiag则提供框架诊断的辅助构造。资源被外部删除时这种处理方式让 Terraform 在 plan/apply 时自然重建而不是报错中断。Update先 Diff 再决定是否调 API标准顺序获取 client → 读取 plan 和 state →diff, d : flex.Diff(ctx, plan, state)→ 用diff.HasChanges()作门槛 → 调 AWS modify → flatten 输出回 plan → wait →resp.State.Set(ctx, plan)。需要标记的两类问题未经过HasChanges()判断就无条件调用 API——即使配置无变化也会触发无意义的 modify 请求modify 之后再重新 fetch state——此时远端返回值可能尚未最终一致正确的做法是把 modify 的响应 flatten 回 plan。另外以下三种情况应省略 Update 方法API 本身不支持更新每个属性都带RequiresReplace()即任何变更都走销毁重建Create 复用于修改场景。Delete静默吞掉 ResourceNotFound标准顺序获取 client → 读取 state → 构造 input → 调 AWS delete用errs.IsA*awstypes.ResourceNotFoundException静默吞掉资源已不存在的异常 → wait。删除语义要求幂等资源已被外部删除时不应报错。错误处理一律走 smerr / smarterr规范要求使用smerr/smarterr绝不裸用resp.Diagnostics.AddError具体规则如下上游upstream诊断smerr.AddEnrich(ctx, resp.Diagnostics, req.Plan.Get(ctx, plan))注意是AddEnrich不是已废弃的EnrichAppendAPI 错误smerr.AddError(ctx, resp.Diagnostics, err, smerr.ID, plan.Name.String())。必须给smerr.ID传入标识符——Create 中传plan.Name其他方法中传state.ID这样错误信息才能定位到具体资源finder/waiter 内部返回的错误用smarterr.NewError(err)包装检测 AWS 异常一律使用errs.IsA*awstypes.Exception——该泛型函数在 internal/errs/errs.go 中实现func IsAT error bool基于类型而非字符串匹配检测未找到使用retry.NotFound(err)识别 finder 层包装过的 not-found 错误。需要标记的反模式裸用resp.Diagnostics.AddError对 AWS 错误做类型断言type assertion用strings.Contains(err.Error(), ...)做基于字符串的错误匹配——AWS 错误消息文本不稳定极易因文案变更导致误判。AutoFlex模型与 SDK 结构体的自动转换新 Framework 代码中模型model↔ SDK 结构体的转换必须使用flex.Expand/flex.Flatten/flex.Diff逐个字段手写aws.String/aws.ToString属于错误写法。flex.Expand模型 → SDK定义在 internal/framework/flex/autoflex_expand.go签名Expand(ctx, tfObject, apiObject any, optFns ...AutoFlexOptionsFunc) diag.Diagnosticsflex.FlattenSDK → 模型定义在 internal/framework/flex/autoflex_flatten.goflex.Diffplan/state 差异定义在 internal/framework/flex/diff.go返回(*Results, diag.Diagnostics)配合Results.HasChanges()使用Update 路径的标准做法。AutoFlex 的命名约定flex.WithFieldNamePrefix(Thing)当 AWS 侧对字段加了前缀时使用例如模型ID对应 SDK 的ThingId复数集合 ↔ 单数块AWS 复数集合字段与 Terraform 侧单数块对应如Parameters↔parameter标签不自动复制AutoFlex 不会把 tags 从一个结构体拷贝到另一个标签相关逻辑由 .agents/skills/review-tags/SKILL.md 技能单独覆盖Update 路径flex.Diff(ctx, plan, state)后调用diff.HasChanges()作为是否调 API 的门槛。与相邻审查技能的协作生命周期审查只是仓库 PR 审查体系的一环相关技能文档集中在 .agents/skills 目录.agents/skills/review-pr/SKILL.md加载本技能的上层 PR 审查入口.agents/skills/review-tags/SKILL.md标签处理专项审查AutoFlex 不处理标签需要该技能补位.agents/skills/review-identity/SKILL.md资源标识identity专项审查与WithImportByIdentity的选用直接相关.agents/skills/review-schema/SKILL.md、.agents/skills/review-tests/SKILL.md分别覆盖 schema 定义与测试用例审查。各技能职责边界清晰本技能专注internal/service/**/*.go的非测试资源代码schema 与测试代码交给对应技能处理。审查清单速查检查项要求违反时的标记点注册注解每个工厂函数上方一行名称一致缺失注解、工厂名/资源名不一致结构体嵌入ResourceWithModel[T]WithImportByIdentity新资源用WithImportByID、误用ResourceWithConfigureCreateExpand → 建输入 → API → Flatten 回 plan → Set不把输出读回 planReadfinder retry.NotFound→ warning RemoveResource找不到资源时报错而非移除Updateflex.DiffHasChanges()门槛无门槛直调 API、modify 后重取 stateDelete静默吞errs.IsA[*awstypes.ResourceNotFoundException]资源不存在时报错错误处理smerr/smarterrsmerr.ID必填裸AddError、类型断言、字符串匹配AutoFlexflex.Expand/Flatten/Diff字段名前缀用WithFieldNamePrefix手写aws.String/aws.ToString这套规范保证了仓库内数千个 AWS 资源在生命周期行为上的一致性资源创建后状态必然完整回写、删除幂等、错误信息可定位到具体资源标识、模型转换由 AutoFlex 统一承担。按此清单审查既能把 PR 中的生命周期缺陷拦截在合并前也能帮助新贡献者快速对齐仓库既有的 Framework 资源编码约定。【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Terraform AWS Provider 资源生命周期代码审查指南：CRUD 顺序、错误处理与 AutoFlex 转换规范
Terraform AWS Provider 资源生命周期代码审查指南CRUD 顺序、错误处理与 AutoFlex 转换规范【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws本指南围绕 terraform-provider-aws 仓库内维护者使用的代码审查技能文档.agents/skills/review-lifecycle/SKILL.md展开系统讲解 Framework 资源Resource生命周期代码的审查要点CRUD 四步操作的顺序约束、smerr/smarterr错误处理规范以及 AutoFlex 模型与 AWS SDK 结构体之间的转换约定。读者读完可掌握对该仓库internal/service/**/*.go中非测试资源代码的完整评审清单并理解每一条规定背后的源码实现依据。适用范围与审查角色该技能文档由review-pr技能加载用于在审查 PR 时检查非测试资源逻辑代码即internal/service/**/*.go下的 Create/Read/Update/Delete、错误包装、flex.Expand/flex.Flatten/flex.Diff调用。审查者需代入maintainer维护者视角。审查范围具体包括三个方面CRUD 步骤顺序每个生命周期方法的调用次序是否符合仓库既定模板错误处理是否使用smerr/smarterr统一包装而非裸用框架诊断AutoFlex模型model与 SDK 结构体之间的转换是否走 AutoFlex 自动生成路径。注册注解Registration Annotations工厂函数上方的契约每个工厂函数factory function上方必须有一行注册注解用于把 Go 结构体与 Terraform 资源名绑定。审查时需标记缺失注解或工厂函数名/资源名不一致的情况。构造Construct注解Annotation资源Framework// FrameworkResource(aws_svc_thing, nameHuman Name)数据源Framework// FrameworkDataSource(aws_svc_thing, nameHuman Name)列表资源Framework// FrameworkListResource(aws_svc_thing)列表资源SDKv2// SDKListResource(aws_svc_thing)其中aws_svc_thing是 Terraform 侧资源地址如aws_iam_rolename为面向用户的可读名称。注解既是代码生成工具见 internal/generate 下各生成器解析的输入也是审查时核对资源注册是否正确的第一道关卡。结构体嵌入Struct Embeds组合而非手写新建资源结构体必须通过嵌入框架提供的组合组件来获得标准行为标准模板如下type fooResource struct { framework.ResourceWithModel[fooResourceModel] framework.WithTimeouts // only when a timeouts block is present framework.WithImportByIdentity // not WithImportByID for new resources }审查要点新资源必须使用framework.WithImportByIdentity若新资源出现framework.WithImportByID直接标记。WithImportByID只是把导入 ID 原样透传到id属性见 internal/framework/with_import_by_id.go其实现为resource.ImportStatePassthroughID(ctx, path.Root(names.AttrID), request, response)而WithImportByIdentity会依据资源标识类型ARN、单例、单参数、多参数分派到不同的导入器见 internal/framework/with_import_by_identity.go这正是仓库按资源标识identity导入设计参见 docs/resource-identity.md在生命周期层的要求。使用framework.ResourceWithModel[T]而非ResourceWithConfigure前者在 internal/framework/resource_with_model.go 中组合了ResourceWithConfigure、withNoOpUpdate与withModel并额外提供ValidateModel——当模型包含timeouts字段时会在校验前把空白 timeouts 块注入 schema避免Expected framework type ... Received framework type ...这类类型不匹配错误。数据源使用framework.DataSourceWithModel[T]。WithTimeouts仅在资源确实含timeouts块时嵌入。其实现见 internal/framework/with_timeouts.go提供SetDefaultCreateTimeout/CreateTimeout等四个方向的方法读取配置失败时回退到默认值并打 warning 日志。CRUD 步骤顺序逐方法审查清单这是该技能的核心部分。每个生命周期方法的调用顺序都有固定模板偏离即标记。Create先 Expand 后 Flatten标准顺序获取 client → 读取 plan →flex.Expand→ 给带标签资源设置input.Tags getTagsIn(ctx)→ 调用 AWS Create API →flex.Flatten把输出写回 plan → wait →resp.State.Set(ctx, plan)。需要重点标记的问题Create 之后没有把 API 返回的输出读回 plan。这会直接导致计算属性computed attributes在 state 中保持 unknown后续依赖该属性的资源无法正确解析。ReadNotFound 要优雅退出标准顺序获取 client → 读取 state → finder 查找 → 命中retry.NotFound(err)时追加fwdiag.NewResourceNotFoundWarningDiagnostic(err)警告、调用resp.State.RemoveResource(ctx)并返回 → 否则 flatten →resp.State.Set。retry.NotFound在 internal/retry/error.go 中实现用于识别 finder 层包装过的未找到错误fwdiag见 internal/errs/fwdiag则提供框架诊断的辅助构造。资源被外部删除时这种处理方式让 Terraform 在 plan/apply 时自然重建而不是报错中断。Update先 Diff 再决定是否调 API标准顺序获取 client → 读取 plan 和 state →diff, d : flex.Diff(ctx, plan, state)→ 用diff.HasChanges()作门槛 → 调 AWS modify → flatten 输出回 plan → wait →resp.State.Set(ctx, plan)。需要标记的两类问题未经过HasChanges()判断就无条件调用 API——即使配置无变化也会触发无意义的 modify 请求modify 之后再重新 fetch state——此时远端返回值可能尚未最终一致正确的做法是把 modify 的响应 flatten 回 plan。另外以下三种情况应省略 Update 方法API 本身不支持更新每个属性都带RequiresReplace()即任何变更都走销毁重建Create 复用于修改场景。Delete静默吞掉 ResourceNotFound标准顺序获取 client → 读取 state → 构造 input → 调 AWS delete用errs.IsA*awstypes.ResourceNotFoundException静默吞掉资源已不存在的异常 → wait。删除语义要求幂等资源已被外部删除时不应报错。错误处理一律走 smerr / smarterr规范要求使用smerr/smarterr绝不裸用resp.Diagnostics.AddError具体规则如下上游upstream诊断smerr.AddEnrich(ctx, resp.Diagnostics, req.Plan.Get(ctx, plan))注意是AddEnrich不是已废弃的EnrichAppendAPI 错误smerr.AddError(ctx, resp.Diagnostics, err, smerr.ID, plan.Name.String())。必须给smerr.ID传入标识符——Create 中传plan.Name其他方法中传state.ID这样错误信息才能定位到具体资源finder/waiter 内部返回的错误用smarterr.NewError(err)包装检测 AWS 异常一律使用errs.IsA*awstypes.Exception——该泛型函数在 internal/errs/errs.go 中实现func IsAT error bool基于类型而非字符串匹配检测未找到使用retry.NotFound(err)识别 finder 层包装过的 not-found 错误。需要标记的反模式裸用resp.Diagnostics.AddError对 AWS 错误做类型断言type assertion用strings.Contains(err.Error(), ...)做基于字符串的错误匹配——AWS 错误消息文本不稳定极易因文案变更导致误判。AutoFlex模型与 SDK 结构体的自动转换新 Framework 代码中模型model↔ SDK 结构体的转换必须使用flex.Expand/flex.Flatten/flex.Diff逐个字段手写aws.String/aws.ToString属于错误写法。flex.Expand模型 → SDK定义在 internal/framework/flex/autoflex_expand.go签名Expand(ctx, tfObject, apiObject any, optFns ...AutoFlexOptionsFunc) diag.Diagnosticsflex.FlattenSDK → 模型定义在 internal/framework/flex/autoflex_flatten.goflex.Diffplan/state 差异定义在 internal/framework/flex/diff.go返回(*Results, diag.Diagnostics)配合Results.HasChanges()使用Update 路径的标准做法。AutoFlex 的命名约定flex.WithFieldNamePrefix(Thing)当 AWS 侧对字段加了前缀时使用例如模型ID对应 SDK 的ThingId复数集合 ↔ 单数块AWS 复数集合字段与 Terraform 侧单数块对应如Parameters↔parameter标签不自动复制AutoFlex 不会把 tags 从一个结构体拷贝到另一个标签相关逻辑由 .agents/skills/review-tags/SKILL.md 技能单独覆盖Update 路径flex.Diff(ctx, plan, state)后调用diff.HasChanges()作为是否调 API 的门槛。与相邻审查技能的协作生命周期审查只是仓库 PR 审查体系的一环相关技能文档集中在 .agents/skills 目录.agents/skills/review-pr/SKILL.md加载本技能的上层 PR 审查入口.agents/skills/review-tags/SKILL.md标签处理专项审查AutoFlex 不处理标签需要该技能补位.agents/skills/review-identity/SKILL.md资源标识identity专项审查与WithImportByIdentity的选用直接相关.agents/skills/review-schema/SKILL.md、.agents/skills/review-tests/SKILL.md分别覆盖 schema 定义与测试用例审查。各技能职责边界清晰本技能专注internal/service/**/*.go的非测试资源代码schema 与测试代码交给对应技能处理。审查清单速查检查项要求违反时的标记点注册注解每个工厂函数上方一行名称一致缺失注解、工厂名/资源名不一致结构体嵌入ResourceWithModel[T]WithImportByIdentity新资源用WithImportByID、误用ResourceWithConfigureCreateExpand → 建输入 → API → Flatten 回 plan → Set不把输出读回 planReadfinder retry.NotFound→ warning RemoveResource找不到资源时报错而非移除Updateflex.DiffHasChanges()门槛无门槛直调 API、modify 后重取 stateDelete静默吞errs.IsA[*awstypes.ResourceNotFoundException]资源不存在时报错错误处理smerr/smarterrsmerr.ID必填裸AddError、类型断言、字符串匹配AutoFlexflex.Expand/Flatten/Diff字段名前缀用WithFieldNamePrefix手写aws.String/aws.ToString这套规范保证了仓库内数千个 AWS 资源在生命周期行为上的一致性资源创建后状态必然完整回写、删除幂等、错误信息可定位到具体资源标识、模型转换由 AutoFlex 统一承担。按此清单审查既能把 PR 中的生命周期缺陷拦截在合并前也能帮助新贡献者快速对齐仓库既有的 Framework 资源编码约定。【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考