Merge pull request #18 from golang-io/dev

feat: add ConnTimeout option, improve GenId entropy and refine logging

Author: luopengift

options.go

@@ -54,9 +54,10 @@ type Options struct {
 	Cookies  []http.Cookie // HTTP Cookies
 
 	// ===== 客户端配置 / Client Configuration =====
-	Timeout  time.Duration // 请求超时时间 / Request timeout
-	MaxConns int           // 最大连接数（连接池大小）/ Maximum connections (connection pool size)
-	Verify   bool          // 是否验证TLS证书 / Whether to verify TLS certificates
+	Timeout     time.Duration // 请求超时时间（整个请求的总超时）/ Request timeout (total timeout for the whole request)
+	ConnTimeout time.Duration // TCP 连接建立超时（拨号超时）/ TCP connection establishment timeout (dial timeout)
+	MaxConns    int           // 最大连接数（连接池大小）/ Maximum connections (connection pool size)
+	Verify      bool          // 是否验证TLS证书 / Whether to verify TLS certificates
 
 	// ===== 传输层配置 / Transport Layer Configuration =====
 	Transport        http.RoundTripper                           // 自定义传输层 / Custom transport
@@ -114,12 +115,13 @@ type Option func(*Options)
 //   - Options: 合并后的配置选项 / Merged configuration options
 func newOptions(opts []Option, extends ...Option) Options {
 	opt := Options{
-		URL:      "http://127.0.0.1:80",
-		RawQuery: make(url.Values),
-		Header:   make(http.Header),
-		Timeout:  30 * time.Second,
-		MaxConns: 100,
-		Proxy:    http.ProxyFromEnvironment,
+		URL:         "http://127.0.0.1:80",
+		RawQuery:    make(url.Values),
+		Header:      make(http.Header),
+		Timeout:     30 * time.Second,
+		ConnTimeout: 10 * time.Second,
+		MaxConns:    100,
+		Proxy:       http.ProxyFromEnvironment,
 
 		OnStart:    func(s *http.Server) { log.Printf("http(s) serve %s", s.Addr) },
 		OnShutdown: func(s *http.Server) { log.Printf("http shutdown") },
@@ -228,6 +230,12 @@ func Method(method string) Option {
 //	    requests.Body("data"),
 //	)
 //
+// ⚠️ Unix Socket 限制 / Unix Socket Limitation:
+//   - Unix socket 路径只能在「会话级」（requests.New）设置，因为 Transport 在创建会话时即固化拨号逻辑。
+//   - 在「请求级」传入 unix:// 不会改变已建好的 Transport，不会生效；如需切换 socket 请新建 Session。
+//   - The Unix socket path can only be set at the "session level" (requests.New), because the Transport
+//     fixes its dial logic when the session is created. Passing unix:// at the "request level" does NOT
+//     take effect; create a new Session to switch sockets.
 // 参数 / Parameters:
 //   - url: 目标 URL 地址 / Target URL address
 //
@@ -361,6 +369,10 @@ func Body(body any) Option {
 //   - 发送大量数据时，减少网络传输量 / Reduce network transmission when sending large data
 //   - 服务器支持 gzip 解压时 / When server supports gzip decompression
 //
+// 错误处理 / Error Handling:
+//   - 压缩出错不再 panic，也不中断请求：仅记录日志，跳过压缩（不设置 body 与编码头）
+//   - Compression errors no longer panic nor abort the request: just logged, compression is skipped (body and encoding headers left unset)
+//
 // 示例 / Example:
 //
 //	largeData := strings.Repeat("data", 10000)
@@ -548,6 +560,33 @@ func Timeout(timeout time.Duration) Option {
 	}
 }
 
+// ConnTimeout 设置 TCP 连接建立（拨号）超时时间
+// ConnTimeout sets the TCP connection establishment (dial) timeout duration
+//
+// 参数 / Parameters:
+//   - timeout: 拨号超时时间 / Dial timeout duration
+//
+// 说明 / Notes:
+//   - 仅控制建立连接（TCP 握手 + DNS 解析）阶段的超时
+//   - Only controls the timeout for the connection establishment phase (TCP handshake + DNS)
+//   - 与 Timeout 不同：Timeout 控制整个请求的总耗时，ConnTimeout 仅控制拨号
+//   - Differs from Timeout: Timeout controls the total request duration, ConnTimeout only the dial phase
+//   - 默认值为 10 秒 / Default is 10 seconds
+//   - 仅在会话级（New）配置生效，因 Transport 在创建时固化拨号逻辑
+//   - Only effective at session level (New), since the Transport fixes dial logic at creation time
+//
+// 示例 / Example:
+//
+//	sess := requests.New(
+//	    requests.URL("https://api.example.com"),
+//	    requests.ConnTimeout(3*time.Second), // 3秒拨号超时 / 3s dial timeout
+//	)
+func ConnTimeout(timeout time.Duration) Option {
+	return func(o *Options) {
+		o.ConnTimeout = timeout
+	}
+}
+
 // Verify 设置是否验证 TLS/SSL 证书
 // Verify sets whether to verify TLS/SSL certificates
 //

request.go

@@ -126,7 +126,14 @@ func NewRequestWithContext(ctx context.Context, options Options) (*http.Request,
 
 	// 设置请求头
 	// Set headers
-	r.Header = options.Header
+	// 仅在 options.Header 非 nil 时覆盖，否则保留 http.NewRequestWithContext 已初始化的非 nil Header，
+	// 避免后续 r.AddCookie 等操作在 nil map 上 panic（用户绕过 newOptions 直接构造 Options 时可能为 nil）
+	// Only overwrite when options.Header is non-nil; otherwise keep the non-nil Header initialized by
+	// http.NewRequestWithContext, to avoid panics in subsequent r.AddCookie on a nil map (possible when
+	// users construct Options directly, bypassing newOptions)
+	if options.Header != nil {
+		r.Header = options.Header
+	}
 
 	// 添加Cookie
 	// Add cookies

request_test.go

@@ -193,3 +193,28 @@ func TestNewRequestWithContext(t *testing.T) {
 		})
 	}
 }
+
+// TestNewRequestWithContext_NilHeader 验证 Options.Header 为 nil 时不会覆盖掉
+// http.NewRequestWithContext 初始化的非 nil Header，从而保证后续 AddCookie 不 panic。
+// （用户绕过 newOptions 直接构造 Options 时 Header 可能为 nil）
+func TestNewRequestWithContext_NilHeader(t *testing.T) {
+	// 直接构造 Options，Header 故意保持 nil，并带上 Cookie 触发 r.AddCookie
+	options := Options{
+		Method:  "GET",
+		URL:     "http://example.com",
+		Header:  nil,
+		Cookies: []http.Cookie{{Name: "session", Value: "123"}},
+	}
+
+	req, err := NewRequestWithContext(context.Background(), options)
+	if err != nil {
+		t.Fatalf("NewRequestWithContext() 错误 = %v", err)
+	}
+	if req.Header == nil {
+		t.Fatal("Header 不应为 nil，应保留 http.NewRequestWithContext 初始化的非 nil Header")
+	}
+	cookies := req.Cookies()
+	if len(cookies) != 1 || cookies[0].Name != "session" || cookies[0].Value != "123" {
+		t.Errorf("Cookie 设置不正确: %+v", cookies)
+	}
+}