@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/httpclient/client.go

@@ -0,0 +1,772 @@
+package httpclient
+
+import (
+	"bytes"
+	"context"
+	"crypto/tls"
+	"encoding/json"
+	"fmt"
+	"math"
+	"math/rand"
+	"mime/multipart"
+	"net/http"
+	"net/textproto"
+	neturl "net/url"
+	"strings"
+	"time"
+
+	"github.com/go-resty/resty/v2"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/requestprivacy"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 常量
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	defaultTimeoutMs  = 30000
+	defaultMaxRetries = 3
+	defaultRetryDelay = 1000 * time.Millisecond
+	maxRetryDelay     = 30 * time.Second
+	retryJitterFactor = 0.1
+)
+
+// 可重试的 HTTP 状态码
+var retryableStatusCodes = []int{
+	http.StatusInternalServerError,
+	http.StatusBadGateway,
+	http.StatusServiceUnavailable,
+	http.StatusGatewayTimeout,
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 配置
+// ═══════════════════════════════════════════════════════════════
+
+// RetryConfig 重试配置
+type RetryConfig struct {
+	// 最大重试次数
+	MaxRetries int
+	// 初始延迟
+	RetryDelay time.Duration
+	// 是否使用指数退避
+	UseExponentialBackoff bool
+	// 最大延迟
+	MaxDelay time.Duration
+	// 可重试的状态码
+	RetryableStatusCodes []int
+	// 网络错误是否重试
+	RetryOnNetworkError bool
+}
+
+// URLLogSanitizer 在 URL 进入日志或 transport error 前移除敏感信息。
+type URLLogSanitizer func(string) string
+
+// URLPathSegmentRedactionRule 将指定路径段之后的单个路径参数替换为稳定模板。
+type URLPathSegmentRedactionRule struct {
+	AfterSegment        string
+	Replacement         string
+	PreserveColonSuffix bool
+}
+
+// DefaultRetryConfig 默认重试配置
+var DefaultRetryConfig = RetryConfig{
+	MaxRetries:            defaultMaxRetries,
+	RetryDelay:            defaultRetryDelay,
+	UseExponentialBackoff: true,
+	MaxDelay:              maxRetryDelay,
+	RetryableStatusCodes:  retryableStatusCodes,
+	RetryOnNetworkError:   true,
+}
+
+// Options 客户端配置选项
+type Options struct {
+	// 基础 URL
+	BaseURL string
+	// 超时（毫秒）
+	Timeout time.Duration
+	// 默认请求头
+	Headers map[string]string
+	// 重试配置
+	Retry *RetryConfig
+	// 启用日志
+	EnableLogging bool
+	// 自定义传输层
+	Transport http.RoundTripper
+	// 重定向策略
+	RedirectPolicy resty.RedirectPolicy
+	// URL 日志净化策略
+	URLLogSanitizer URLLogSanitizer
+}
+
+// Response 响应封装
+type Response struct {
+	// 响应数据（原始字节）
+	Body []byte
+	// HTTP 状态码
+	StatusCode int
+	// 状态描述
+	Status string
+	// 响应头
+	Headers http.Header
+	// 重试次数
+	RetryCount int
+	// 总耗时
+	TotalDuration time.Duration
+}
+
+// MultipartFilePart 描述 multipart/form-data 文件字段。
+type MultipartFilePart struct {
+	FieldName   string
+	FileName    string
+	ContentType string
+	Content     []byte
+}
+
+// PreserveRedirectResponsePolicy 禁止自动跳转，并把原始重定向响应交还给上层契约校验。
+func PreserveRedirectResponsePolicy() resty.RedirectPolicy {
+	return resty.RedirectPolicyFunc(func(_ *http.Request, _ []*http.Request) error {
+		return http.ErrUseLastResponse
+	})
+}
+
+// ═══════════════════════════════════════════════════════════════
+// HTTP 客户端
+// ═══════════════════════════════════════════════════════════════
+
+// Client HTTP 客户端封装
+type Client struct {
+	resty           *resty.Client
+	logger          *zap.Logger
+	retryConfig     RetryConfig
+	enableLog       bool
+	timeout         time.Duration
+	redirectPolicy  resty.RedirectPolicy
+	urlLogSanitizer URLLogSanitizer
+}
+
+// New 创建 HTTP 客户端
+func New(logger *zap.Logger, opts ...Options) *Client {
+	var opt Options
+	if len(opts) > 0 {
+		opt = opts[0]
+	}
+
+	timeout := time.Duration(defaultTimeoutMs) * time.Millisecond
+	if opt.Timeout > 0 {
+		timeout = opt.Timeout
+	}
+
+	retryCfg := DefaultRetryConfig
+	if opt.Retry != nil {
+		retryCfg = *opt.Retry
+	}
+
+	r := resty.New().
+		SetTimeout(timeout).
+		SetHeader("Content-Type", "application/json")
+
+	if opt.BaseURL != "" {
+		r.SetBaseURL(opt.BaseURL)
+	}
+	if opt.Transport != nil {
+		r.SetTransport(opt.Transport)
+	}
+	if opt.RedirectPolicy != nil {
+		r.SetRedirectPolicy(opt.RedirectPolicy)
+	}
+
+	for k, v := range opt.Headers {
+		r.SetHeader(k, v)
+	}
+
+	c := &Client{
+		resty:           r,
+		logger:          logger.Named("HttpClient"),
+		retryConfig:     retryCfg,
+		enableLog:       opt.EnableLogging,
+		timeout:         timeout,
+		redirectPolicy:  opt.RedirectPolicy,
+		urlLogSanitizer: opt.URLLogSanitizer,
+	}
+	if c.urlLogSanitizer == nil {
+		c.urlLogSanitizer = sanitizeLogURL
+	}
+
+	return c
+}
+
+// ═══════════════════════════════════════════════════════════════
+// HTTP 方法
+// ═══════════════════════════════════════════════════════════════
+
+// Get 执行 GET 请求
+func (c *Client) Get(ctx context.Context, url string, result any) (*Response, error) {
+	return c.doRequest(ctx, http.MethodGet, url, nil, result)
+}
+
+// GetWithHeaders 执行带额外请求头的 GET 请求
+func (c *Client) GetWithHeaders(
+	ctx context.Context,
+	url string,
+	result any,
+	headers map[string]string,
+) (*Response, error) {
+	return c.doRequestWithHeaders(ctx, http.MethodGet, url, nil, result, headers)
+}
+
+// Post 执行 POST 请求
+func (c *Client) Post(ctx context.Context, url string, body, result any) (*Response, error) {
+	return c.doRequest(ctx, http.MethodPost, url, body, result)
+}
+
+// PostWithHeaders 执行带额外请求头的 POST 请求
+func (c *Client) PostWithHeaders(
+	ctx context.Context,
+	url string,
+	body, result any,
+	headers map[string]string,
+) (*Response, error) {
+	return c.doRequestWithHeaders(ctx, http.MethodPost, url, body, result, headers)
+}
+
+// PostOnceWithHeaders 执行一次带额外请求头的 POST 请求。
+func (c *Client) PostOnceWithHeaders(
+	ctx context.Context,
+	url string,
+	body, result any,
+	headers map[string]string,
+) (*Response, error) {
+	retryCfg := c.retryConfig
+	retryCfg.MaxRetries = 0
+	retryCfg.RetryOnNetworkError = false
+	return c.doRequestWithHeadersUsingRetry(ctx, http.MethodPost, url, body, result, headers, retryCfg)
+}
+
+// PostOnceHTTP1WithHeaders 使用 HTTP/1.1 执行一次带额外请求头的 POST 请求。
+func (c *Client) PostOnceHTTP1WithHeaders(
+	ctx context.Context,
+	url string,
+	body, result any,
+	headers map[string]string,
+) (*Response, error) {
+	return c.PostOnceHTTP1WithHeadersTimeout(ctx, url, body, result, headers, 0)
+}
+
+// PostOnceHTTP1WithHeadersTimeout 使用指定请求超时执行一次 HTTP/1.1 POST。
+//
+// body/result 沿用通用 JSON client 契约，由调用方按外部 API schema 提供具体结构。
+func (c *Client) PostOnceHTTP1WithHeadersTimeout(
+	ctx context.Context,
+	url string,
+	body, result any,
+	headers map[string]string,
+	timeout time.Duration,
+) (*Response, error) {
+	retryCfg := c.retryConfig
+	retryCfg.MaxRetries = 0
+	retryCfg.RetryOnNetworkError = false
+	transport := newHTTP1Transport()
+	defer transport.CloseIdleConnections()
+	if timeout <= 0 {
+		timeout = c.timeout
+	}
+	client := c.WithOptions(Options{
+		Timeout:        timeout,
+		Retry:          &retryCfg,
+		Transport:      transport,
+		RedirectPolicy: c.redirectPolicy,
+		EnableLogging:  c.enableLog,
+	})
+	return client.doRequestWithHeadersUsingRetry(ctx, http.MethodPost, url, body, result, headers, retryCfg)
+}
+
+// PostMultipartOnceHTTP1WithHeadersTimeout 使用 HTTP/1.1 执行一次 multipart/form-data POST。
+func (c *Client) PostMultipartOnceHTTP1WithHeadersTimeout(
+	ctx context.Context,
+	url string,
+	fields map[string]any,
+	files []MultipartFilePart,
+	result any,
+	headers map[string]string,
+	timeout time.Duration,
+) (*Response, error) {
+	body, contentType, err := buildMultipartBody(fields, files)
+	if err != nil {
+		return nil, err
+	}
+	nextHeaders := make(map[string]string, len(headers)+1)
+	for key, value := range headers {
+		nextHeaders[key] = value
+	}
+	nextHeaders["Content-Type"] = contentType
+	return c.PostOnceHTTP1WithHeadersTimeout(ctx, url, body, result, nextHeaders, timeout)
+}
+
+// PostForm 执行 application/x-www-form-urlencoded POST 请求
+func (c *Client) PostForm(ctx context.Context, url string, formData map[string]string, result any) (*Response, error) {
+	return c.doFormRequest(ctx, url, formData, result)
+}
+
+// Put 执行 PUT 请求
+func (c *Client) Put(ctx context.Context, url string, body, result any) (*Response, error) {
+	return c.doRequest(ctx, http.MethodPut, url, body, result)
+}
+
+// Patch 执行 PATCH 请求
+func (c *Client) Patch(ctx context.Context, url string, body, result any) (*Response, error) {
+	return c.doRequest(ctx, http.MethodPatch, url, body, result)
+}
+
+// Delete 执行 DELETE 请求
+func (c *Client) Delete(ctx context.Context, url string, result any) (*Response, error) {
+	return c.doRequest(ctx, http.MethodDelete, url, nil, result)
+}
+
+// Head 执行 HEAD 请求
+func (c *Client) Head(ctx context.Context, url string) (*Response, error) {
+	return c.doRequest(ctx, http.MethodHead, url, nil, nil)
+}
+
+// DoWithHeaders 使用客户端重试策略执行任意 HTTP 方法。
+func (c *Client) DoWithHeaders(
+	ctx context.Context,
+	method, url string,
+	body, result any,
+	headers map[string]string,
+) (*Response, error) {
+	return c.doRequestWithHeaders(ctx, method, url, body, result, headers)
+}
+
+// DoOnceWithHeaders 执行一次任意 HTTP 方法，不重试网络错误或响应状态。
+func (c *Client) DoOnceWithHeaders(
+	ctx context.Context,
+	method, url string,
+	body, result any,
+	headers map[string]string,
+) (*Response, error) {
+	retryCfg := c.retryConfig
+	retryCfg.MaxRetries = 0
+	retryCfg.RetryOnNetworkError = false
+	return c.doRequestWithHeadersUsingRetry(ctx, method, url, body, result, headers, retryCfg)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 底层 Resty 访问
+// ═══════════════════════════════════════════════════════════════
+
+// Resty 获取底层 Resty 客户端（需要高级操作时使用）
+func (c *Client) Resty() *resty.Client {
+	return c.resty
+}
+
+// WithOptions 基于当前 logger 派生一个专用 HTTP 客户端。
+func (c *Client) WithOptions(opts Options) *Client {
+	if opts.URLLogSanitizer == nil {
+		opts.URLLogSanitizer = c.urlLogSanitizer
+	}
+	return New(c.logger, opts)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 内部实现
+// ═══════════════════════════════════════════════════════════════
+
+func (c *Client) doRequest(ctx context.Context, method, url string, body, result any) (*Response, error) {
+	return c.doRequestWithHeaders(ctx, method, url, body, result, nil)
+}
+
+func (c *Client) doRequestWithHeaders(
+	ctx context.Context,
+	method, url string,
+	body, result any,
+	headers map[string]string,
+) (*Response, error) {
+	return c.doRequestWithHeadersUsingRetry(ctx, method, url, body, result, headers, c.retryConfig)
+}
+
+func (c *Client) doRequestWithHeadersUsingRetry(
+	ctx context.Context,
+	method, url string,
+	body, result any,
+	headers map[string]string,
+	retryCfg RetryConfig,
+) (*Response, error) {
+	startTime := time.Now()
+	logURL := c.urlLogSanitizer(url)
+	var retryCount int
+
+	for attempt := 0; attempt <= retryCfg.MaxRetries; attempt++ {
+		if attempt > 0 {
+			retryCount = attempt
+			delay := calculateDelay(retryCfg, attempt-1)
+
+			c.logger.Warn("retrying request",
+				zap.String("method", method),
+				zap.String("url", logURL),
+				zap.Int("attempt", attempt),
+				zap.Int("maxRetries", retryCfg.MaxRetries),
+				zap.Duration("delay", delay),
+			)
+
+			select {
+			case <-ctx.Done():
+				return nil, ctx.Err()
+			case <-time.After(delay):
+			}
+		}
+
+		// 构建请求
+		req := c.resty.R().SetContext(ctx)
+		if len(headers) > 0 {
+			req.SetHeaders(headers)
+		}
+
+		if body != nil {
+			req.SetBody(body)
+		}
+		if result != nil {
+			req.SetResult(result)
+		}
+
+		// 日志
+		if c.enableLog {
+			c.logRequest(method, logURL)
+		}
+
+		resp, err := req.Execute(method, url)
+
+		if err != nil {
+			if shouldReturnResponseDespiteTransportError(resp) {
+				if c.enableLog {
+					c.logResponse(method, logURL, resp.StatusCode(), time.Since(startTime))
+				}
+				return responseFromResty(resp, retryCount, startTime), nil
+			}
+			// 网络错误
+			if retryCfg.RetryOnNetworkError && attempt < retryCfg.MaxRetries {
+				continue
+			}
+			sanitizedErr := sanitizeRequestURLError(err, url, logURL)
+			if c.enableLog {
+				c.logError(method, logURL, sanitizedErr, time.Since(startTime))
+			}
+			return nil, sanitizedErr
+		}
+
+		if c.enableLog {
+			c.logResponse(method, logURL, resp.StatusCode(), time.Since(startTime))
+		}
+
+		// 检查是否需要重试
+		if shouldRetry(retryCfg, resp.StatusCode()) && attempt < retryCfg.MaxRetries {
+			continue
+		}
+
+		return responseFromResty(resp, retryCount, startTime), nil
+	}
+
+	return nil, fmt.Errorf("request failed after %d retries", retryCfg.MaxRetries)
+}
+
+// doFormRequest 执行 form-urlencoded POST，复用重试/日志逻辑
+func (c *Client) doFormRequest(ctx context.Context, url string, formData map[string]string, result any) (*Response, error) {
+	startTime := time.Now()
+	logURL := c.urlLogSanitizer(url)
+	var retryCount int
+	method := http.MethodPost
+
+	for attempt := 0; attempt <= c.retryConfig.MaxRetries; attempt++ {
+		if attempt > 0 {
+			retryCount = attempt
+			delay := calculateDelay(c.retryConfig, attempt-1)
+
+			c.logger.Warn("retrying request",
+				zap.String("method", method),
+				zap.String("url", logURL),
+				zap.Int("attempt", attempt),
+				zap.Int("maxRetries", c.retryConfig.MaxRetries),
+				zap.Duration("delay", delay),
+			)
+
+			select {
+			case <-ctx.Done():
+				return nil, ctx.Err()
+			case <-time.After(delay):
+			}
+		}
+
+		req := c.resty.R().
+			SetContext(ctx).
+			SetHeader("Content-Type", "application/x-www-form-urlencoded").
+			SetFormData(formData)
+
+		if result != nil {
+			req.SetResult(result)
+		}
+
+		if c.enableLog {
+			c.logRequest(method, logURL)
+		}
+
+		resp, err := req.Post(url)
+
+		if err != nil {
+			if shouldReturnResponseDespiteTransportError(resp) {
+				if c.enableLog {
+					c.logResponse(method, logURL, resp.StatusCode(), time.Since(startTime))
+				}
+				return responseFromResty(resp, retryCount, startTime), nil
+			}
+			if c.retryConfig.RetryOnNetworkError && attempt < c.retryConfig.MaxRetries {
+				continue
+			}
+			sanitizedErr := sanitizeRequestURLError(err, url, logURL)
+			if c.enableLog {
+				c.logError(method, logURL, sanitizedErr, time.Since(startTime))
+			}
+			return nil, sanitizedErr
+		}
+
+		if c.enableLog {
+			c.logResponse(method, logURL, resp.StatusCode(), time.Since(startTime))
+		}
+
+		if shouldRetry(c.retryConfig, resp.StatusCode()) && attempt < c.retryConfig.MaxRetries {
+			continue
+		}
+
+		return responseFromResty(resp, retryCount, startTime), nil
+	}
+
+	return nil, fmt.Errorf("request failed after %d retries", c.retryConfig.MaxRetries)
+}
+
+func buildMultipartBody(fields map[string]any, files []MultipartFilePart) ([]byte, string, error) {
+	var body bytes.Buffer
+	writer := multipart.NewWriter(&body)
+	for key, value := range fields {
+		if strings.TrimSpace(key) == "" {
+			return nil, "", fmt.Errorf("multipart field name is required")
+		}
+		fieldValue, err := multipartFieldValue(value)
+		if err != nil {
+			return nil, "", fmt.Errorf("multipart field %s: %w", key, err)
+		}
+		if err := writer.WriteField(key, fieldValue); err != nil {
+			return nil, "", fmt.Errorf("write multipart field %s: %w", key, err)
+		}
+	}
+	for i := range files {
+		if strings.TrimSpace(files[i].FieldName) == "" {
+			return nil, "", fmt.Errorf("multipart file field name is required")
+		}
+		if strings.TrimSpace(files[i].FileName) == "" {
+			return nil, "", fmt.Errorf("multipart file name is required")
+		}
+		header := make(textproto.MIMEHeader)
+		header.Set("Content-Disposition", fmt.Sprintf("form-data; name=%q; filename=%q", escapeQuotes(files[i].FieldName), escapeQuotes(files[i].FileName)))
+		if contentType := strings.TrimSpace(files[i].ContentType); contentType != "" {
+			header.Set("Content-Type", contentType)
+		}
+		part, err := writer.CreatePart(header)
+		if err != nil {
+			return nil, "", fmt.Errorf("create multipart file %s: %w", files[i].FileName, err)
+		}
+		if _, err := part.Write(files[i].Content); err != nil {
+			return nil, "", fmt.Errorf("write multipart file %s: %w", files[i].FileName, err)
+		}
+	}
+	if err := writer.Close(); err != nil {
+		return nil, "", fmt.Errorf("close multipart writer: %w", err)
+	}
+	return body.Bytes(), writer.FormDataContentType(), nil
+}
+
+func multipartFieldValue(value any) (string, error) {
+	switch typed := value.(type) {
+	case nil:
+		return "", nil
+	case string:
+		return typed, nil
+	case bool:
+		if typed {
+			return "true", nil
+		}
+		return "false", nil
+	case int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, float32, float64:
+		return fmt.Sprint(typed), nil
+	default:
+		raw, err := json.Marshal(typed)
+		if err != nil {
+			return "", err
+		}
+		return string(raw), nil
+	}
+}
+
+func escapeQuotes(value string) string {
+	return strings.ReplaceAll(value, `"`, `\"`)
+}
+
+func shouldRetry(retryCfg RetryConfig, statusCode int) bool {
+	for _, code := range retryCfg.RetryableStatusCodes {
+		if statusCode == code {
+			return true
+		}
+	}
+	return false
+}
+
+func shouldReturnResponseDespiteTransportError(resp *resty.Response) bool {
+	if resp == nil {
+		return false
+	}
+	statusCode := resp.StatusCode()
+	return statusCode >= http.StatusOK && statusCode < http.StatusMultipleChoices && len(resp.Body()) > 0
+}
+
+func responseFromResty(resp *resty.Response, retryCount int, startTime time.Time) *Response {
+	return &Response{
+		Body:          resp.Body(),
+		StatusCode:    resp.StatusCode(),
+		Status:        resp.Status(),
+		Headers:       resp.Header(),
+		RetryCount:    retryCount,
+		TotalDuration: time.Since(startTime),
+	}
+}
+
+func calculateDelay(retryCfg RetryConfig, attempt int) time.Duration {
+	if !retryCfg.UseExponentialBackoff {
+		return retryCfg.RetryDelay
+	}
+
+	// 指数退避：delay * 2^attempt
+	delay := float64(retryCfg.RetryDelay) * math.Pow(2, float64(attempt))
+
+	// 添加抖动
+	jitter := delay * retryJitterFactor * rand.Float64() //nolint:gosec // G404: 用于 jitter/退避，不需要密码学安全
+	delay += jitter
+
+	// 限制最大延迟
+	if delay > float64(retryCfg.MaxDelay) {
+		delay = float64(retryCfg.MaxDelay)
+	}
+
+	return time.Duration(delay)
+}
+
+func newHTTP1Transport() *http.Transport {
+	return &http.Transport{
+		Proxy:                 http.ProxyFromEnvironment,
+		ForceAttemptHTTP2:     false,
+		MaxIdleConns:          10,
+		IdleConnTimeout:       90 * time.Second,
+		TLSHandshakeTimeout:   10 * time.Second,
+		ExpectContinueTimeout: 1 * time.Second,
+		TLSNextProto:          map[string]func(string, *tls.Conn) http.RoundTripper{},
+	}
+}
+
+func (c *Client) logRequest(method, url string) {
+	c.logger.Debug("HTTP request",
+		zap.String("method", method),
+		zap.String("url", url),
+	)
+}
+
+func (c *Client) logResponse(method, url string, status int, duration time.Duration) {
+	c.logger.Debug("HTTP response",
+		zap.String("method", method),
+		zap.String("url", url),
+		zap.Int("status", status),
+		zap.Duration("duration", duration),
+	)
+}
+
+func (c *Client) logError(method, url string, err error, duration time.Duration) {
+	c.logger.Error("HTTP request error",
+		zap.String("method", method),
+		zap.String("url", url),
+		zap.Duration("duration", duration),
+		zap.Error(err),
+	)
+}
+
+func sanitizeLogURL(rawURL string) string {
+	parsed, err := neturl.Parse(rawURL)
+	if err != nil {
+		return "[invalid-url]"
+	}
+	parsed.RawQuery = ""
+	parsed.Fragment = ""
+	return parsed.String()
+}
+
+// NewPathSegmentURLLogSanitizer 构造路径参数模板化策略，并始终移除 query 与 fragment。
+func NewPathSegmentURLLogSanitizer(rules ...URLPathSegmentRedactionRule) URLLogSanitizer {
+	prepared := make([]URLPathSegmentRedactionRule, 0, len(rules))
+	for _, rule := range rules {
+		rule.AfterSegment = strings.TrimSpace(rule.AfterSegment)
+		rule.Replacement = strings.TrimSpace(rule.Replacement)
+		if rule.AfterSegment != "" && rule.Replacement != "" {
+			prepared = append(prepared, rule)
+		}
+	}
+	return func(rawURL string) string {
+		parsed, err := neturl.Parse(rawURL)
+		if err != nil {
+			return "[invalid-url]"
+		}
+		parsed.RawQuery = ""
+		parsed.Fragment = ""
+		segments := strings.Split(parsed.Path, "/")
+		for index := 0; index+1 < len(segments); index++ {
+			for _, rule := range prepared {
+				if segments[index] != rule.AfterSegment {
+					continue
+				}
+				replacement := rule.Replacement
+				if rule.PreserveColonSuffix {
+					if suffixIndex := strings.LastIndex(segments[index+1], ":"); suffixIndex >= 0 {
+						replacement += segments[index+1][suffixIndex:]
+					}
+				}
+				segments[index+1] = replacement
+				break
+			}
+		}
+		parsed.Path = strings.Join(segments, "/")
+		parsed.RawPath = ""
+		sanitized := strings.ReplaceAll(parsed.String(), "%7B", "{")
+		return strings.ReplaceAll(sanitized, "%7D", "}")
+	}
+}
+
+type sanitizedURLRequestError struct {
+	message string
+	cause   error
+}
+
+func (e *sanitizedURLRequestError) Error() string { return e.message }
+func (e *sanitizedURLRequestError) Unwrap() error { return e.cause }
+
+func sanitizeRequestURLError(err error, rawURL, sanitizedURL string) error {
+	if err == nil || rawURL == sanitizedURL {
+		return err
+	}
+	message := strings.ReplaceAll(err.Error(), rawURL, sanitizedURL)
+	message = strings.ReplaceAll(message, neturl.QueryEscape(rawURL), neturl.QueryEscape(sanitizedURL))
+	if message == err.Error() {
+		return err
+	}
+	return &sanitizedURLRequestError{message: message, cause: err}
+}
+
+// SanitizeHeaders 清理请求头（脱敏敏感数据），用于日志输出
+func SanitizeHeaders(headers http.Header) map[string]string {
+	return requestprivacy.RedactSensitiveHeaders(headers)
+}