尧图网站建设 
Loki 中的 smithy-goAWS SDK for Go v2 运行时与 Smithy 代码生成全解析【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/lokiSmithy Go 是 AWS 官方为 Smithy 建模语言提供的 Go 语言代码生成器与配套运行时runtime它是 aws-sdk-go-v2 的底层基础也是 Loki 在接入 S3 对象存储时经由 aws-sdk-go-v2 间接依赖的关键组件。本文以仓库内 vendor 目录中 vendored 的 smithy-go 官方 README 为主体结合 go.mod、vendor/modules.txt 与 Loki 的 S3 存储客户端源码完整讲解 smithy-go 的构建插件体系、go-codegen配置项、支持的序列化协议以及它如何以smithy.APIError的形式把 AWS 错误码暴露给 Loki 做重试与降级处理。Smithy Go 是什么代码生成器 运行时Smithy 是一种与语言无关的接口定义语言IDL用于描述服务模型service model。Smithy Go 则是 Smithy 官方为 Go 生态提供的两大部分代码生成器code generators根据 Smithy 模型生成 Go 客户端、服务端骨架或纯类型shape代码smithy-go 运行时runtime为生成的代码提供中间件middleware、序列化/反序列化、端点解析、事件流eventstream、签名、重试等基础设施。在 Loki 仓库中smithy-go 以 Go module 依赖的形式被 vendored 在 vendor/github.com/aws/smithy-go 目录下。根据 vendor/modules.txt 的记录当前 vendored 版本为v1.28.1其 go_module_metadata.go 中同样标注goModuleVersion 1.28.1。而 go.mod 中 Loki 直接依赖的github.com/aws/aws-sdk-go-v2 v1.45.1正是建立在 smithy-go 运行时之上这也是 smithy-go 进入 Loki 依赖树的直接原因。版本与 Go 环境要求smithy-go 官方 README 明确指出smithy-go 运行时要求最低 Go 1.24 版本。从仓库实际情况看Loki 的 go.mod 声明go 1.26.6完全满足该前提。若要在本地构建依赖 smithy-go 的模块需要保证 Go 工具链版本不低于运行时要求的最低版本。稳定性声明README 开头给出两条明确警告使用者需要知悉所有接口均可能发生变化All interfaces are subject to change这是 AWS 对 smithy-go 公共 API 的官方定调意味着运行时接口在后续版本中存在调整的可能不保证严格的向后兼容。客户端代码生成尚不稳定go-codegen生成的客户端缺少部分原本在 SDK 侧实现的功能例如 retries可能存在 bug且生成客户端的公共 API 不稳定。AWS 鼓励使用者实验并在 issue 中反馈但对生产环境的任意客户端生成非 aws-sdk-go-v2 生态需保持谨慎。三个构建插件Build Pluginssmithy-go 仓库通过 Smithy 构建插件build plugin的形式对外提供代码生成能力README 中的插件清单如下IDGAV prefix描述go-codegensoftware.amazon.smithy.go:smithy-go-codegen基于 Smithy 模型实现 Go 客户端代码生成go-server-codegensoftware.amazon.smithy.go:smithy-go-codegen基于 Smithy 模型实现 Go 服务端代码生成go-shape-codegensoftware.amazon.smithy.go:smithy-go-codegen基于 Smithy 模型实现 Go shape仅类型代码生成三个插件共享同一个 Maven 构件software.amazon.smithy.go:smithy-go-codegen通过smithy-build.json中的插件名区分用途。其中go-server-codegen与go-shape-codegen在 README 中均标注为 work-in-progress目前暂无文档属于未稳定的进行中功能唯一有完整配置文档的是go-codegen。从当前仓库的 vendored 目录结构看vendor/github.com/aws/smithy-go 只包含运行时包如middleware、encoding、transport/http、endpoints等代码生成器本体Java 侧实现位于上游源码树的codegen/目录并未随 Loki 一并 vendored——这符合 Go 依赖 vendoring 只打包运行时 Go 源码的惯例。go-codegen配置详解go-codegen的全部配置项由GoSettings承载。README 说明GoSettings包含所有从smithy-build.json启用的设置以及辅助方法与类型最权威的顶级属性清单可在GoSettings::from()中查看。由于上游代码生成器未随仓库 vendored这里以 README 记录的配置表为准。顶层配置项设置类型必填说明servicestring是要为其生成客户端的服务的 Shape IDmodulestring是在generated.json以及启用generateGoMod时的go.mod和doc.go中的模块名generateGoModboolean否是否生成默认的go.mod文件默认值为falsegoDirectivestring否模块的 Go directive即 go.mod 首行的 go 指令默认值为受支持的最低 Go 版本需要特别说明两个字段的联动generateGoMod: true时生成器会额外产出go.mod此时goDirective决定该文件的 go 指令版本不启用generateGoMod时goDirective仅作为模块元数据写入generated.json。默认情况下goDirective会回退到 smithy-go 运行时支持的最低 Go 版本即 1.24。完整配置示例README 给出了一个基于smithy init快速启动示例example.weather#Weather服务的smithy-build.json{ version: 1.0, sources: [ models ], maven: { dependencies: [ software.amazon.smithy.go:smithy-go-codegen:[0.1.0,2.0) ] }, plugins: { go-codegen: { service: example.weather#Weather, module: github.com/example/weather, generateGoMod: true, goDirective: 1.24 } } }该示例的要点sources: [models]指定 Smithy 模型文件的目录maven.dependencies声明引入smithy-go-codegen构件版本范围为[0.1.0, 2.0)即 0.1.0 且 2.0.0plugins[go-codegen]内的四个字段与上表一一对应service用 Shape ID 精确锁定要生成的服务module决定生成 Go 模块名generateGoMod: true自动生成go.modgoDirective: 1.24显式指定 Go 指令版本。协议的选择方式客户端使用何种协议由客户端Options上的Protocol字段配置。SDK 会根据建模服务上应用的协议 traits 自动配置默认协议。README 列出了go-codegen支持的全部协议协议备注smithy.protocols#rpcv2CborSmithy RPC v2CBOR 二进制编码aws.protocols#restJson1AWS REST-JSON v1aws.protocols#restXmlAWS REST-XMLaws.protocols#awsJson1_0AWS JSON v1.0aws.protocols#awsJson1_1AWS JSON v1.1aws.protocols#awsQueryAWS Query表单编码aws.protocols#ec2QueryAWS EC2 Query七种协议覆盖了 AWS 服务的主流序列化风格其中 REST-JSON 与 JSON 系协议在 aws-sdk-go-v2 生态中使用最为广泛。运行时核心中间件栈Middleware Stack虽然 README 只对代码生成做了配置层面的说明但 smithy-go 真正在运行时发挥作用的是其中间件middleware机制。从 vendor/github.com/aws/smithy-go/middleware/stack.go 的源码注释可以完整还原一次请求的处理链路即五个步骤依次串联Initialize - Serialize - Build - Finalize - Deserialize - Handler各步骤职责如下均出自 stack.go 的包内文档注释Initialize准备输入参数设置必要的默认参数如幂等令牌、预签名 URLSerialize将准备好的输入序列化为目标传输可消费的数据结构如 REST-JSON 序列化把输入参数转换为 RequestBuild向已序列化的传输消息追加元数据如 HTTP 的Content-Length头、请求体校验和对消息的修饰会复制到所有请求尝试Finalize发送前做最后准备如重试与 AWS SigV4 请求签名此时消息已完整仅按接收方预期做调整Deserialize响应由底层 handler 返回后将其反序列化为结构化类型或错误。中间件通过 middleware.go 定义的Handler、HandlerFunc与Middleware三个接口组合成链每个中间件围绕底层 handler 以调用栈方式装饰既可中途返回错误或响应也可调用next.Handler将输入向下传递。这种协议无关、传输无关的栈式设计正是 aws-sdk-go-v2 各服务客户端能够统一获得重试、签名、日志、度量等横切能力的原因。smithy-go 在 Loki 中的落地S3 错误码与重试Loki 以 S3 作为块存储chunk storage的后端之一其对象存储客户端建立在 aws-sdk-go-v2 之上因此运行时层直接消费 smithy-go 的能力。最直观的实证在 pkg/storage/chunk/client/aws/s3_storage_client.gogithub.com/aws/smithy-go ... // S3 error codes returned by the AWS SDK as smithy.APIError values. const ( errCodeRequestTimeout RequestTimeout // 400 errCodeTooManyRequestsException TooManyRequestsException // 429 errCodeInternalError InternalError // 500 errCodeServiceUnavailable ServiceUnavailable // 503 errCodeSlowDown SlowDown // 503 )这里体现了 smithy-go 运行时一个重要的错误模型设计AWS SDK 返回的所有服务端错误统一以smithy.APIError类型暴露每个错误携带一个错误码ErrorCode字符串。Loki 据此识别 S3 返回的RequestTimeout400、TooManyRequestsException429、InternalError500、ServiceUnavailable503、SlowDown503等错误码用于驱动请求重试与降级策略从而在 S3 限流或短暂故障时保持日志写入的韧性。除此之外pkg/storage/bucket/s3/config.go 直接导入aws-sdk-go-v2/service/s3/types使用其ObjectStorageClass枚举supportedStorageClasses与BucketLookupType校验 S3 存储类与 bucket 查找模式配置而 pkg/storage/chunk/client/aws/s3_storage_client.go 引入的aws-sdk-go-v2/config、credentials与service/s3则是 aws-sdk-go-v2 基于 smithy-go 代码生成产物的典型消费方式。也就是说Loki 日常使用的 S3 读写、SSE 加密SSE-KMS/SSE-S3等能力最终都由 smithy-go 运行时在底层支撑。许可证smithy-go 采用 Apache-2.0 许可证详见 vendor/github.com/aws/smithy-go/LICENSE与 Loki 自身的 Apache-2.0 授权相容这也是它能够以依赖形式嵌入 vendor/github.com/aws/smithy-go 并随 Loki 分发的法律前提。小结smithy-go 虽在 Loki 中处于依赖链深处却是理解 aws-sdk-go-v2 工作方式的钥匙上游由go-codegen插件根据 Smithy 模型生成客户端代码运行时通过五步中间件栈统一处理序列化、签名、重试等横切逻辑并把服务端错误统一归一为smithy.APIError。对 Loki 运维者而言理解这一点有助于排查 S3 相关错误日志RequestTimeout、SlowDown等错误码均源自 smithy-go 的错误模型对 Go 开发者而言vendor/github.com/aws/smithy-go/middleware/stack.go 与 middleware.go 是学习中间件链式调用范式的现成范本可复用于自研 SDK 或 API 客户端的横切能力设计。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Loki 中的 smithy-go：AWS SDK for Go v2 运行时与 Smithy 代码生成全解析
Loki 中的 smithy-goAWS SDK for Go v2 运行时与 Smithy 代码生成全解析【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/lokiSmithy Go 是 AWS 官方为 Smithy 建模语言提供的 Go 语言代码生成器与配套运行时runtime它是 aws-sdk-go-v2 的底层基础也是 Loki 在接入 S3 对象存储时经由 aws-sdk-go-v2 间接依赖的关键组件。本文以仓库内 vendor 目录中 vendored 的 smithy-go 官方 README 为主体结合 go.mod、vendor/modules.txt 与 Loki 的 S3 存储客户端源码完整讲解 smithy-go 的构建插件体系、go-codegen配置项、支持的序列化协议以及它如何以smithy.APIError的形式把 AWS 错误码暴露给 Loki 做重试与降级处理。Smithy Go 是什么代码生成器 运行时Smithy 是一种与语言无关的接口定义语言IDL用于描述服务模型service model。Smithy Go 则是 Smithy 官方为 Go 生态提供的两大部分代码生成器code generators根据 Smithy 模型生成 Go 客户端、服务端骨架或纯类型shape代码smithy-go 运行时runtime为生成的代码提供中间件middleware、序列化/反序列化、端点解析、事件流eventstream、签名、重试等基础设施。在 Loki 仓库中smithy-go 以 Go module 依赖的形式被 vendored 在 vendor/github.com/aws/smithy-go 目录下。根据 vendor/modules.txt 的记录当前 vendored 版本为v1.28.1其 go_module_metadata.go 中同样标注goModuleVersion 1.28.1。而 go.mod 中 Loki 直接依赖的github.com/aws/aws-sdk-go-v2 v1.45.1正是建立在 smithy-go 运行时之上这也是 smithy-go 进入 Loki 依赖树的直接原因。版本与 Go 环境要求smithy-go 官方 README 明确指出smithy-go 运行时要求最低 Go 1.24 版本。从仓库实际情况看Loki 的 go.mod 声明go 1.26.6完全满足该前提。若要在本地构建依赖 smithy-go 的模块需要保证 Go 工具链版本不低于运行时要求的最低版本。稳定性声明README 开头给出两条明确警告使用者需要知悉所有接口均可能发生变化All interfaces are subject to change这是 AWS 对 smithy-go 公共 API 的官方定调意味着运行时接口在后续版本中存在调整的可能不保证严格的向后兼容。客户端代码生成尚不稳定go-codegen生成的客户端缺少部分原本在 SDK 侧实现的功能例如 retries可能存在 bug且生成客户端的公共 API 不稳定。AWS 鼓励使用者实验并在 issue 中反馈但对生产环境的任意客户端生成非 aws-sdk-go-v2 生态需保持谨慎。三个构建插件Build Pluginssmithy-go 仓库通过 Smithy 构建插件build plugin的形式对外提供代码生成能力README 中的插件清单如下IDGAV prefix描述go-codegensoftware.amazon.smithy.go:smithy-go-codegen基于 Smithy 模型实现 Go 客户端代码生成go-server-codegensoftware.amazon.smithy.go:smithy-go-codegen基于 Smithy 模型实现 Go 服务端代码生成go-shape-codegensoftware.amazon.smithy.go:smithy-go-codegen基于 Smithy 模型实现 Go shape仅类型代码生成三个插件共享同一个 Maven 构件software.amazon.smithy.go:smithy-go-codegen通过smithy-build.json中的插件名区分用途。其中go-server-codegen与go-shape-codegen在 README 中均标注为 work-in-progress目前暂无文档属于未稳定的进行中功能唯一有完整配置文档的是go-codegen。从当前仓库的 vendored 目录结构看vendor/github.com/aws/smithy-go 只包含运行时包如middleware、encoding、transport/http、endpoints等代码生成器本体Java 侧实现位于上游源码树的codegen/目录并未随 Loki 一并 vendored——这符合 Go 依赖 vendoring 只打包运行时 Go 源码的惯例。go-codegen配置详解go-codegen的全部配置项由GoSettings承载。README 说明GoSettings包含所有从smithy-build.json启用的设置以及辅助方法与类型最权威的顶级属性清单可在GoSettings::from()中查看。由于上游代码生成器未随仓库 vendored这里以 README 记录的配置表为准。顶层配置项设置类型必填说明servicestring是要为其生成客户端的服务的 Shape IDmodulestring是在generated.json以及启用generateGoMod时的go.mod和doc.go中的模块名generateGoModboolean否是否生成默认的go.mod文件默认值为falsegoDirectivestring否模块的 Go directive即 go.mod 首行的 go 指令默认值为受支持的最低 Go 版本需要特别说明两个字段的联动generateGoMod: true时生成器会额外产出go.mod此时goDirective决定该文件的 go 指令版本不启用generateGoMod时goDirective仅作为模块元数据写入generated.json。默认情况下goDirective会回退到 smithy-go 运行时支持的最低 Go 版本即 1.24。完整配置示例README 给出了一个基于smithy init快速启动示例example.weather#Weather服务的smithy-build.json{ version: 1.0, sources: [ models ], maven: { dependencies: [ software.amazon.smithy.go:smithy-go-codegen:[0.1.0,2.0) ] }, plugins: { go-codegen: { service: example.weather#Weather, module: github.com/example/weather, generateGoMod: true, goDirective: 1.24 } } }该示例的要点sources: [models]指定 Smithy 模型文件的目录maven.dependencies声明引入smithy-go-codegen构件版本范围为[0.1.0, 2.0)即 0.1.0 且 2.0.0plugins[go-codegen]内的四个字段与上表一一对应service用 Shape ID 精确锁定要生成的服务module决定生成 Go 模块名generateGoMod: true自动生成go.modgoDirective: 1.24显式指定 Go 指令版本。协议的选择方式客户端使用何种协议由客户端Options上的Protocol字段配置。SDK 会根据建模服务上应用的协议 traits 自动配置默认协议。README 列出了go-codegen支持的全部协议协议备注smithy.protocols#rpcv2CborSmithy RPC v2CBOR 二进制编码aws.protocols#restJson1AWS REST-JSON v1aws.protocols#restXmlAWS REST-XMLaws.protocols#awsJson1_0AWS JSON v1.0aws.protocols#awsJson1_1AWS JSON v1.1aws.protocols#awsQueryAWS Query表单编码aws.protocols#ec2QueryAWS EC2 Query七种协议覆盖了 AWS 服务的主流序列化风格其中 REST-JSON 与 JSON 系协议在 aws-sdk-go-v2 生态中使用最为广泛。运行时核心中间件栈Middleware Stack虽然 README 只对代码生成做了配置层面的说明但 smithy-go 真正在运行时发挥作用的是其中间件middleware机制。从 vendor/github.com/aws/smithy-go/middleware/stack.go 的源码注释可以完整还原一次请求的处理链路即五个步骤依次串联Initialize - Serialize - Build - Finalize - Deserialize - Handler各步骤职责如下均出自 stack.go 的包内文档注释Initialize准备输入参数设置必要的默认参数如幂等令牌、预签名 URLSerialize将准备好的输入序列化为目标传输可消费的数据结构如 REST-JSON 序列化把输入参数转换为 RequestBuild向已序列化的传输消息追加元数据如 HTTP 的Content-Length头、请求体校验和对消息的修饰会复制到所有请求尝试Finalize发送前做最后准备如重试与 AWS SigV4 请求签名此时消息已完整仅按接收方预期做调整Deserialize响应由底层 handler 返回后将其反序列化为结构化类型或错误。中间件通过 middleware.go 定义的Handler、HandlerFunc与Middleware三个接口组合成链每个中间件围绕底层 handler 以调用栈方式装饰既可中途返回错误或响应也可调用next.Handler将输入向下传递。这种协议无关、传输无关的栈式设计正是 aws-sdk-go-v2 各服务客户端能够统一获得重试、签名、日志、度量等横切能力的原因。smithy-go 在 Loki 中的落地S3 错误码与重试Loki 以 S3 作为块存储chunk storage的后端之一其对象存储客户端建立在 aws-sdk-go-v2 之上因此运行时层直接消费 smithy-go 的能力。最直观的实证在 pkg/storage/chunk/client/aws/s3_storage_client.gogithub.com/aws/smithy-go ... // S3 error codes returned by the AWS SDK as smithy.APIError values. const ( errCodeRequestTimeout RequestTimeout // 400 errCodeTooManyRequestsException TooManyRequestsException // 429 errCodeInternalError InternalError // 500 errCodeServiceUnavailable ServiceUnavailable // 503 errCodeSlowDown SlowDown // 503 )这里体现了 smithy-go 运行时一个重要的错误模型设计AWS SDK 返回的所有服务端错误统一以smithy.APIError类型暴露每个错误携带一个错误码ErrorCode字符串。Loki 据此识别 S3 返回的RequestTimeout400、TooManyRequestsException429、InternalError500、ServiceUnavailable503、SlowDown503等错误码用于驱动请求重试与降级策略从而在 S3 限流或短暂故障时保持日志写入的韧性。除此之外pkg/storage/bucket/s3/config.go 直接导入aws-sdk-go-v2/service/s3/types使用其ObjectStorageClass枚举supportedStorageClasses与BucketLookupType校验 S3 存储类与 bucket 查找模式配置而 pkg/storage/chunk/client/aws/s3_storage_client.go 引入的aws-sdk-go-v2/config、credentials与service/s3则是 aws-sdk-go-v2 基于 smithy-go 代码生成产物的典型消费方式。也就是说Loki 日常使用的 S3 读写、SSE 加密SSE-KMS/SSE-S3等能力最终都由 smithy-go 运行时在底层支撑。许可证smithy-go 采用 Apache-2.0 许可证详见 vendor/github.com/aws/smithy-go/LICENSE与 Loki 自身的 Apache-2.0 授权相容这也是它能够以依赖形式嵌入 vendor/github.com/aws/smithy-go 并随 Loki 分发的法律前提。小结smithy-go 虽在 Loki 中处于依赖链深处却是理解 aws-sdk-go-v2 工作方式的钥匙上游由go-codegen插件根据 Smithy 模型生成客户端代码运行时通过五步中间件栈统一处理序列化、签名、重试等横切逻辑并把服务端错误统一归一为smithy.APIError。对 Loki 运维者而言理解这一点有助于排查 S3 相关错误日志RequestTimeout、SlowDown等错误码均源自 smithy-go 的错误模型对 Go 开发者而言vendor/github.com/aws/smithy-go/middleware/stack.go 与 middleware.go 是学习中间件链式调用范式的现成范本可复用于自研 SDK 或 API 客户端的横切能力设计。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考