Agent Substrate 项目中的 AWS SDK v2 `presigned-url` 模块：CHANGELOG 全解读与预签名中间件实现剖析-平芜编程栈

人工智能
AI Agent
Agent 沙箱
云原生
容器运行时
零信任

【免费下载链接】substrate

Agent Substrate: the core system

项目地址：https://gitcode.com/GitHub_Trending/substrate7/substrate

本篇技术指南以 Agent Substrate 仓库（核心系统）所 vendor 的 AWS SDK for Go v2 内部模块service/internal/presigned-url的 CHANGELOG.md 为骨架，结合模块源码与仓库内实际调用方，完整梳理该模块的版本演进脉络、公开 API 契约与底层预签名中间件实现，帮助读者理解 AWS SDK 内部预签名（presigned URL）机制的运作原理，以及如何在当前仓库中定位、验证这些实现。

说明：该模块在 Agent Substrate 中是 AWS SDK v2 的间接依赖（见 go.mod 中github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23 // indirect），因此本文严格以 CHANGELOG 与 vendor 源码为事实依据，不涉及对项目业务层的臆测。

模块定位：AWS SDK v2 内部的预签名定制层

presigned-url是 AWS SDK for Go v2 的内部工具模块（路径中带有internal），其职责在 doc.go 中定义得非常明确：

"Package presignedurl provides the customizations for API clients to fill in presigned URLs into input parameters."

即：为 API 客户端提供"把预签名 URL 回填到请求输入参数中"的定制能力。它不直接对用户暴露，而是被 S3、STS 等需要跨区域/跨账号预签名能力的服务客户端所引用。当前仓库 vendor 的版本为v1.13.23，与 go_module_metadata.go 中goModuleVersion = "1.13.23"一致，也与 go.mod/go.sum 记录的版本吻合。

为什么需要"把预签名 URL 回填进输入参数"？

在 AWS 服务间互调场景中（例如 S3 的CopyObject跨区域复制、STS 的AssumeRole配合 S3 跨账号访问），服务端需要拿到一个"已经签好名"的 URL，才能代替客户端发起后续请求。该模块的中间件在请求正式发送前（Initialize 阶段）完成：

读取用户输入中携带的源区域（SourceRegion）与预签名 URL（PresignedURL）；
若用户已显式提供预签名 URL，直接透传；
否则基于签名器（v4 signer）为请求生成预签名 URL，并把目标区域（客户端配置的 region）写入参数副本，再回填到原始输入。

这样上层业务代码无需手工拼装签名 URL，只需声明区域信息即可。

CHANGELOG 版本演进全景

该 CHANGELOG 从 v1.1.0（2021-05-14）一路记录到 v1.13.23（2026-04-29），约 100 个版本条目。整体呈现三个鲜明特征：

依赖更新占绝对主体

绝大多数条目是Dependency Update: Updated to the latest SDK module versions，这是 AWS SDK v2 采用**细粒度多模块仓库（multi-module repo）**策略的必然结果——每个service/*与service/internal/*都是独立模块，任何底层组件（smithy-go、signer、aws 核心包）发版都会触发全量模块的连带更新。以最近几版为例：

版本	日期	关键变更
v1.13.23	2026-04-29	升级 smithy-go v1.25.1，同步最新 SDK 模块
v1.13.22	2026-04-17	升级 smithy-go v1.25.0（支持`endpointBdd`trait）
v1.13.19	2026-03-03	使用 go fix 现代化非 codegen 文件；最低 Go 版本提升至 1.24
v1.13.15	2025-12-02	升级 smithy-go v1.24.0，中间件系统分配占用降低约 10%
v1.13.10	2025-10-16	最低 Go 版本提升至 1.23
v1.13.0	2025-07-28	新增 HTTP 拦截器（interceptors）支持
v1.12.0	2024-10-04	新增 HTTP 客户端指标（metrics）支持
v1.11.18	2024-08-15	最低 Go 版本提升至 1.21
v1.11.0	2024-02-13	最低 Go 版本提升至 1.20
v1.10.0	2023-10-31	破坏性变更：最低 Go 版本提升至 1.19

两条 Go 版本策略主线

CHANGELOG 清晰记录了 AWS SDK 对 Go 运行时版本的支持节奏，与官方"go version support policy"一致：

v1.10.0（2023-10-31）：标注为BREAKING CHANGE，最低 Go 版本提升至 1.19；
v1.11.0（2024-02-13）：提升至 1.20；
v1.11.18（2024-08-15）：提升至 1.21；
v1.13.10（2025-10-16）：提升至 1.23；
v1.13.19（2026-03-03）：提升至 1.24。

对使用方（包括 Agent Substrate）的启示是：升级该模块时必须保证构建工具链的 Go 版本不低于模块要求的最低版本，否则编译会直接失败。

值得关注的性能与 Bug Fix 条目

v1.13.15：smithy-go v1.24.0 显著降低了中间件系统的内存分配足迹，官方观测到每次 SDK 调用分配量下降约 10%（该数据来自官方 CHANGELOG 陈述，非本文测算）；
v1.13.13：smithy-go v1.23.2 在未启用 metrics 系统时进一步被动减少整体分配；
v1.11.5：移除对go-cmp的依赖；
v1.11.3 / v1.11.4：修复内部 APIAddAsIsPresigningMiddleware的拼写错误，并在 v1.11.4 通过AddAsIsPresigingMiddleware别名保持向后兼容（该别名至今仍保留在源码中，见下文）。

核心源码解析：预签名中间件如何工作

URLPresigner 与 ParameterAccessor：中间件的两个依赖注入点

middleware.go 定义了中间件的全部关键类型：

type URLPresigner interface { PresignURL(ctx context.Context, srcRegion string, params any) (*v4.PresignedHTTPRequest, error) } type ParameterAccessor struct { GetPresignedURL func(any) (string, bool, error) GetSourceRegion func(any) (string, bool, error) CopyInput func(any) (any, error) SetDestinationRegion func(any, string) error SetPresignedURL func(any, string) error } type Options struct { Accessor ParameterAccessor Presigner URLPresigner }

URLPresigner负责真正调用 v4 签名器生成*v4.PresignedHTTPRequest；
ParameterAccessor是一组针对具体服务输入结构体的读写函数集合（由各服务生成的 codegen 代码提供），把通用中间件与具体 API 输入解耦；
Options把两者组装后交给AddMiddleware挂载到 smithy 中间件栈的Initialize 阶段（Before 位置）。

HandleInitialize 的六步执行逻辑

func (m *presign) HandleInitialize(ctx, input, next) (...) { // 1. 若输入中已存在 PresignedURL，直接跳过，交给下一个中间件 if _, ok, err := m.options.Accessor.GetPresignedURL(input.Parameters); err != nil { ... } else if ok { return next.HandleInitialize(ctx, input) } // 2. 若未设置 SourceRegion（或为空），同样跳过 srcRegion, ok, err := m.options.Accessor.GetSourceRegion(input.Parameters) ... else if !ok || len(srcRegion) == 0 { return next.HandleInitialize(ctx, input) } // 3. 复制输入参数，避免目标区域泄漏进原始请求参数 paramCpy, err := m.options.Accessor.CopyInput(input.Parameters) // 4. 目标区域取客户端配置的 region（awsmiddleware.GetRegion(ctx)） dstRegion := awsmiddleware.GetRegion(ctx) m.options.Accessor.SetDestinationRegion(paramCpy, dstRegion) // 5. 调用 Presigner 生成预签名请求 presignedReq, err := m.options.Presigner.PresignURL(ctx, srcRegion, paramCpy) // 6. 将生成的 URL 回填到原始输入 m.options.Accessor.SetPresignedURL(input.Parameters, presignedReq.URL) return next.HandleInitialize(ctx, input) }

设计要点：

幂等性：用户已提供 URL 时直接透传，中间件不会重复签名；
无副作用：通过CopyInput复制参数后再设置目标区域，保证dstRegion不会污染原始输入（对应 CHANGELOG 中反复强调的"保持请求纯净"的工程取向）；
错误包装：所有失败路径均以fmt.Errorf("presign middleware failed, %w", err)风格包装，便于上层用errors.Is/As展开根因。

isPresigning 哨兵：区分"预签名流程"与"正常请求流程"

context.go 提供了一套基于 smithy 栈值（stack values）的上下文标记机制：

func WithIsPresigning(ctx context.Context) context.Context { return middleware.WithStackValue(ctx, isPresigningKey{}, true) } func GetIsPresigning(ctx context.Context) bool { v, _ := middleware.GetStackValue(ctx, isPresigningKey{}).(bool) return v } func AddAsIsPresigningMiddleware(stack *middleware.Stack) error { return stack.Initialize.Add(asIsPresigningMiddleware{}, middleware.Before) }

AddAsIsPresigningMiddleware把整个调用链标记为"预签名流程"，使后续中间件（如下游的校验和、HTTP 拦截器等）可以感知上下文并调整行为。这是 CHANGELOG v1.11.3/v1.11.4 修复的拼写错误相关 API；源码中保留的兼容别名：

// Deprecated: This API was released with a typo. Use AddAsIsPresigningMiddleware instead. func AddAsIsPresigingMiddleware(stack *middleware.Stack) error { return AddAsIsPresigningMiddleware(stack) }

与 CHANGELOG v1.11.4 "Restore typo'd APIAddAsIsInternalPresigingMiddlewareas an alias for backwards compatibility" 的记录完全对应，是 CHANGELOG 事实在源码中的直接验证。

仓库内的实际调用链验证

该模块在当前仓库中的真实消费方全部位于 vendor 的 AWS SDK 服务客户端内：

S3 客户端：在初始化中间件栈时调用presignedurlcust.AddAsIsPresigningMiddleware(stack)；
S3 presign_post 流程：同样挂载该中间件，用于 POST 表单预签名；
STS 客户端：引入该模块，配合跨区域预签名场景；
checksum 模块：通过presignedurlcust.GetIsPresigning(ctx)判断当前是否为预签名流程，仅在非预签名且 HTTPS 请求下计算输入校验和——这是WithIsPresigning哨兵价值的典型体现。

从调用链可以推断：该模块的典型使用路径是S3 跨区域操作（如 CopyObject 携带 SourceRegion）与 STS/S3 组合的跨账号场景，SDK 在初始化阶段注入中间件，请求时自动生成并回填预签名 URL。当前 Agent Substrate 仓库仅将其作为间接依赖 vendor 进来（go.mod），未在项目自有业务代码中直接 import。

版本升级路径与落地建议

基于 CHANGELOG 的演进规律，使用方可按如下方式处理该依赖：

确认版本与 Go 工具链匹配：当前仓库锁定 v1.13.23，要求Go ≥ 1.24（v1.13.19 起）。升级该模块前先检查本机go version；
常规升级：由于绝大多数版本仅包含依赖同步，可用go get github.com/aws/aws-sdk-go-v2/service/internal/presigned-url@latest跟随最新版，并同步升级同族的 aws-sdk-go-v2 核心模块与 smithy-go；
关注 Feature 版本：v1.13.0（HTTP 拦截器）与 v1.12.0（HTTP 客户端 metrics）是两个实质性能力增强，若上层服务客户端依赖这些能力，需确保主 SDK 版本与之配套；
避免使用已废弃 API：编码时应使用AddAsIsPresigningMiddleware（正确拼写），而非 deprecated 的AddAsIsPresigingMiddleware别名；
验证路径：升级后可参照 go.sum 校验模块哈希，并运行仓库的hack/verify/go-modules.sh类校验脚本确认依赖一致性。

小结

service/internal/presigned-url虽然只是一个"内部工具模块"，但其 CHANGELOG 完整折射出 AWS SDK for Go v2 的版本治理节奏（Go 版本策略、smithy-go 联动、性能优化与兼容性修复）。结合 middleware.go 与 context.go 的源码，可以清晰还原"读取源区域 → 复制参数 → 注入目标区域 → v4 签名 → 回填 URL"的完整预签名流水线，以及"isPresigning 哨兵"如何影响下游校验逻辑。对 Agent Substrate 的开发者而言，理解该模块有助于在涉及 S3/STS 跨区域、跨账号访问时正确排障与升级依赖。