fix(net/gclient): fix form field value truncation when uploading files (#4627)

## What does this PR do?

Fixes #4156

When posting form data with file upload, if a field value contains `=`
or `&`, the value was being truncated.

### Example

```go
data := g.Map{
    "file":      "@file:/path/to/file.txt",
    "fieldName": "aaa=1&b=2",
}
client.Post(ctx, "/upload", data)
```

**Expected**: Server receives `fieldName = "aaa=1&b=2"`
**Actual (before fix)**: Server receives `fieldName = "aaa"` (truncated)

## Root Cause Analysis

The issue was caused by three problems in the original code:

### Problem 1: Global URL encoding disable (httputils.go)

```go
// Original code - PROBLEMATIC
if urlEncode {
    for k, v := range m {
        if gstr.Contains(k, fileUploadingKey) || gstr.Contains(gconv.String(v), fileUploadingKey) {
            urlEncode = false  // Disables URL encoding for ALL values!
            break
        }
    }
}
```

When any value contained `@file:`, URL encoding was disabled for ALL
values, causing `"aaa=1&b=2"` to remain unencoded. The `&` character was
then treated as a parameter separator.

### Problem 2: Split on all `=` characters (gclient_request.go)

```go
// Original code - PROBLEMATIC
array := strings.Split(item, "=")  // Splits on ALL '=' characters
```

This caused `"fieldName=aaa=1"` to be split into `["fieldName", "aaa",
"1"]`.

### Problem 3: No URL decoding for field values

URL-encoded values were written directly to the multipart form without
decoding.

## Solution

### Fix 1: Remove global URL encoding disable

Only `@file:` prefixed values are kept unencoded for file upload
detection. Other values are properly URL-encoded.

### Fix 2: Use SplitN to limit split count

```go
array := strings.SplitN(item, "=", 2)  // Only split on first '='
```

### Fix 3: Add URL decoding for field values

```go
if v, err := gurl.Decode(fieldValue); err == nil {
    fieldValue = v
}
```

## Compatibility Analysis

| Scenario | Before | After | Compatible |
|----------|--------|-------|------------|
| Normal form POST (no file upload) | ✅ Works | ✅ Works | ✅ Yes |
| File upload + normal field values | ✅ Works | ✅ Works | ✅ Yes |
| File upload + field values containing `=` or `&` | ❌ Truncated | ✅
Works | ✅ Fixed |
| Field value is `@file:` (no path) | ✅ Works | ✅ Works | ✅ Yes |
| Field value starts with `@file:` but file doesn't exist | ❌ Error | ❌
Error | ✅ Yes |
| User sends pre-encoded value like `"aaa%3D1"` | ✅ Works | ✅ Works | ✅
Yes |
| Content-Type: application/json | ✅ Works | ✅ Works | ✅ Yes |
| Content-Type: application/xml | ✅ Works | ✅ Works | ✅ Yes |

### Breaking Change Assessment

**No breaking changes.** The fix only affects the file upload scenario
where field values contain special characters (`=`, `&`). Previously
this scenario was broken, now it works correctly.

### Edge Cases

1. **Literal `@file:` value**: GoFrame treats `@file:` as a special
marker for file upload. This is a framework design decision and remains
unchanged.

2. **URL decode failure**: If URL decoding fails (e.g., invalid `%XX`
sequence), the original value is preserved.

## Test Coverage

Added comprehensive tests covering:

- `Test_Issue4156` - Basic fix verification
- `Test_Issue4156_MultipleSpecialChars` - Multiple `=`, `&`, `%`, `+`,
spaces
- `Test_Issue4156_MultipleFields` - Multiple fields with special
characters
- `Test_Issue4156_NoFileUpload` - Normal POST without file upload
- `Test_Issue4156_PreEncodedValue` - Pre-encoded values like `%3D`
- `Test_Issue4156_EmptyAndSpecialValues` - Edge cases (`=` at start/end,
only special chars)
- `TestBuildParams_*` - httputil.BuildParams comprehensive tests

All tests pass, including existing `Test_Issue3748` which tests the
`@file:` marker handling.

## Files Changed

- `internal/httputil/httputils.go` - Remove global URL encoding disable,
adjust `@file:` condition
- `internal/httputil/httputils_test.go` - Add comprehensive BuildParams
tests
- `net/gclient/gclient_request.go` - Use SplitN, add URL decoding
- `net/gclient/gclient_z_unit_issue_test.go` - Add Issue 4156 test cases

internal/httputil/httputils.go

@@ -13,7 +13,6 @@ import (
 
 	"github.com/gogf/gf/v2/encoding/gurl"
 	"github.com/gogf/gf/v2/internal/empty"
-	"github.com/gogf/gf/v2/text/gstr"
 	"github.com/gogf/gf/v2/util/gconv"
 )
 
@@ -47,15 +46,6 @@ func BuildParams(params any, noUrlEncode ...bool) (encodedParamStr string) {
 	if len(noUrlEncode) == 1 {
 		urlEncode = !noUrlEncode[0]
 	}
-	// If there's file uploading, it ignores the url encoding.
-	if urlEncode {
-		for k, v := range m {
-			if gstr.Contains(k, fileUploadingKey) || gstr.Contains(gconv.String(v), fileUploadingKey) {
-				urlEncode = false
-				break
-			}
-		}
-	}
 	s := ""
 	for k, v := range m {
 		// Ignore nil attributes.
@@ -67,8 +57,8 @@ func BuildParams(params any, noUrlEncode ...bool) (encodedParamStr string) {
 		}
 		s = gconv.String(v)
 		if urlEncode {
-			if strings.HasPrefix(s, fileUploadingKey) && len(s) > len(fileUploadingKey) {
-				// No url encoding if uploading file.
+			if strings.HasPrefix(s, fileUploadingKey) {
+				// No url encoding if value starts with file uploading marker.
 			} else {
 				s = gurl.Encode(s)
 			}

internal/httputil/httputils_test.go

@@ -51,3 +51,132 @@ func TestIssue4023(t *testing.T) {
 		t.Assert(params, "key1=value1")
 	})
 }
+
+// TestBuildParams_SpecialCharacters tests URL encoding of special characters.
+func TestBuildParams_SpecialCharacters(t *testing.T) {
+	// Test special characters are properly URL encoded.
+	gtest.C(t, func(t *gtest.T) {
+		data := g.Map{
+			"key": "value=with=equals",
+		}
+		params := httputil.BuildParams(data)
+		// = should be encoded as %3D
+		t.Assert(gstr.Contains(params, "key=value%3Dwith%3Dequals"), true)
+	})
+
+	gtest.C(t, func(t *gtest.T) {
+		data := g.Map{
+			"key": "value&with&ampersand",
+		}
+		params := httputil.BuildParams(data)
+		// & should be encoded as %26
+		t.Assert(gstr.Contains(params, "key=value%26with%26ampersand"), true)
+	})
+
+	gtest.C(t, func(t *gtest.T) {
+		data := g.Map{
+			"key": "value with spaces",
+		}
+		params := httputil.BuildParams(data)
+		// space should be encoded as + or %20
+		t.Assert(gstr.Contains(params, "key=value") && gstr.Contains(params, "with") && gstr.Contains(params, "spaces"), true)
+	})
+
+	gtest.C(t, func(t *gtest.T) {
+		data := g.Map{
+			"key": "value%percent",
+		}
+		params := httputil.BuildParams(data)
+		// % should be encoded as %25
+		t.Assert(gstr.Contains(params, "key=value%25percent"), true)
+	})
+}
+
+// TestBuildParams_FileUploadMarker tests that @file: prefix is not URL encoded.
+func TestBuildParams_FileUploadMarker(t *testing.T) {
+	// Test @file: with path is not encoded.
+	gtest.C(t, func(t *gtest.T) {
+		data := g.Map{
+			"file": "@file:/path/to/file.txt",
+		}
+		params := httputil.BuildParams(data)
+		// @file: should NOT be encoded
+		t.Assert(gstr.Contains(params, "file=@file:/path/to/file.txt"), true)
+	})
+
+	// Test @file: without path is not encoded.
+	gtest.C(t, func(t *gtest.T) {
+		data := g.Map{
+			"name": "@file:",
+		}
+		params := httputil.BuildParams(data)
+		// @file: alone should NOT be encoded
+		t.Assert(gstr.Contains(params, "name=@file:"), true)
+	})
+
+	// Test @file: with path does not affect other fields encoding.
+	gtest.C(t, func(t *gtest.T) {
+		data := g.Map{
+			"file":  "@file:/path/to/file.txt",
+			"field": "value=1&b=2",
+		}
+		params := httputil.BuildParams(data)
+		// @file: should NOT be encoded
+		t.Assert(gstr.Contains(params, "@file:/path/to/file.txt"), true)
+		// Other field's special characters SHOULD be encoded
+		t.Assert(gstr.Contains(params, "field=value%3D1%26b%3D2"), true)
+	})
+}
+
+// TestBuildParams_NoUrlEncode tests the noUrlEncode parameter.
+func TestBuildParams_NoUrlEncode(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		data := g.Map{
+			"key": "value=1&b=2",
+		}
+		// With noUrlEncode = true, special characters should NOT be encoded.
+		params := httputil.BuildParams(data, true)
+		t.Assert(gstr.Contains(params, "key=value=1&b=2"), true)
+	})
+
+	gtest.C(t, func(t *gtest.T) {
+		data := g.Map{
+			"key": "value=1&b=2",
+		}
+		// With noUrlEncode = false (default), special characters SHOULD be encoded.
+		params := httputil.BuildParams(data, false)
+		t.Assert(gstr.Contains(params, "key=value%3D1%26b%3D2"), true)
+	})
+}
+
+// TestBuildParams_StringInput tests string input is returned as-is.
+func TestBuildParams_StringInput(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		data := "key=value&key2=value2"
+		params := httputil.BuildParams(data)
+		t.Assert(params, "key=value&key2=value2")
+	})
+
+	gtest.C(t, func(t *gtest.T) {
+		data := []byte("key=value&key2=value2")
+		params := httputil.BuildParams(data)
+		t.Assert(params, "key=value&key2=value2")
+	})
+}
+
+// TestBuildParams_SliceInput tests slice input.
+func TestBuildParams_SliceInput(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		data := []any{g.Map{"a": "1", "b": "2"}}
+		params := httputil.BuildParams(data)
+		t.Assert(gstr.Contains(params, "a=1"), true)
+		t.Assert(gstr.Contains(params, "b=2"), true)
+	})
+
+	gtest.C(t, func(t *gtest.T) {
+		// Empty slice
+		data := []any{}
+		params := httputil.BuildParams(data)
+		t.Assert(params, "")
+	})
+}

net/gclient/gclient_request.go

@@ -18,6 +18,7 @@ import (
 	"time"
 
 	"github.com/gogf/gf/v2/encoding/gjson"
+	"github.com/gogf/gf/v2/encoding/gurl"
 	"github.com/gogf/gf/v2/errors/gcode"
 	"github.com/gogf/gf/v2/errors/gerror"
 	"github.com/gogf/gf/v2/internal/httputil"
@@ -248,7 +249,7 @@ func (c *Client) prepareRequest(ctx context.Context, method, url string, data ..
 				isFileUploading = false
 			)
 			for _, item := range strings.Split(params, "&") {
-				array := strings.Split(item, "=")
+				array := strings.SplitN(item, "=", 2)
 				if len(array) < 2 {
 					continue
 				}
@@ -287,6 +288,14 @@ func (c *Client) prepareRequest(ctx context.Context, method, url string, data ..
 						fieldName  = array[0]
 						fieldValue = array[1]
 					)
+					// Decode URL-encoded field name and value.
+					// If decoding fails, use the original value.
+					if v, err := gurl.Decode(fieldName); err == nil {
+						fieldName = v
+					}
+					if v, err := gurl.Decode(fieldValue); err == nil {
+						fieldValue = v
+					}
 					if err = writer.WriteField(fieldName, fieldValue); err != nil {
 						return nil, gerror.Wrapf(
 							err, `write form field failed with "%s", "%s"`, fieldName, fieldValue,

net/gclient/gclient_z_unit_issue_test.go

@@ -80,3 +80,262 @@ func Test_Issue3748(t *testing.T) {
 		t.AssertNil(err)
 	})
 }
+
+// https://github.com/gogf/gf/issues/4156
+func Test_Issue4156(t *testing.T) {
+	s := g.Server(guid.S())
+	s.BindHandler("/upload", func(r *ghttp.Request) {
+		// Return the fieldName value received
+		r.Response.Write(r.Get("fieldName"))
+	})
+	s.SetDumpRouterMap(false)
+	s.Start()
+	defer s.Shutdown()
+
+	clientHost := fmt.Sprintf("http://127.0.0.1:%d", s.GetListenedPort())
+	time.Sleep(100 * time.Millisecond)
+
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		// When posting form with file upload, if value contains '=', it should not be truncated.
+		data := g.Map{
+			"file":      "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"fieldName": "aaa=1&b=2",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		// The complete value should be received, not truncated at '='
+		t.Assert(content, "aaa=1&b=2")
+	})
+}
+
+// Test_Issue4156_MultipleSpecialChars tests file upload with various special characters in field values.
+func Test_Issue4156_MultipleSpecialChars(t *testing.T) {
+	s := g.Server(guid.S())
+	s.BindHandler("/upload", func(r *ghttp.Request) {
+		r.Response.Write(r.Get("field"))
+	})
+	s.SetDumpRouterMap(false)
+	s.Start()
+	defer s.Shutdown()
+
+	clientHost := fmt.Sprintf("http://127.0.0.1:%d", s.GetListenedPort())
+	time.Sleep(100 * time.Millisecond)
+
+	// Test with multiple equals signs
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "a=1=2=3",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(content, "a=1=2=3")
+	})
+
+	// Test with multiple ampersands
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "a&b&c&d",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(content, "a&b&c&d")
+	})
+
+	// Test with percent sign
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "100%complete",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(content, "100%complete")
+	})
+
+	// Test with plus sign
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "1+2+3",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(content, "1+2+3")
+	})
+
+	// Test with spaces
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "hello world test",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(content, "hello world test")
+	})
+
+	// Test with mixed special characters
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "key=value&foo=bar%20test+plus",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(content, "key=value&foo=bar%20test+plus")
+	})
+}
+
+// Test_Issue4156_MultipleFields tests file upload with multiple fields containing special characters.
+func Test_Issue4156_MultipleFields(t *testing.T) {
+	s := g.Server(guid.S())
+	s.BindHandler("/upload", func(r *ghttp.Request) {
+		// Return all field values as JSON-like format
+		r.Response.Writef("field1=%s,field2=%s,field3=%s",
+			r.Get("field1"), r.Get("field2"), r.Get("field3"))
+	})
+	s.SetDumpRouterMap(false)
+	s.Start()
+	defer s.Shutdown()
+
+	clientHost := fmt.Sprintf("http://127.0.0.1:%d", s.GetListenedPort())
+	time.Sleep(100 * time.Millisecond)
+
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":   "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field1": "a=1",
+			"field2": "b&2",
+			"field3": "c%3",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(strings.Contains(content, "field1=a=1"), true)
+		t.Assert(strings.Contains(content, "field2=b&2"), true)
+		t.Assert(strings.Contains(content, "field3=c%3"), true)
+	})
+}
+
+// Test_Issue4156_NoFileUpload tests that normal POST without file upload still works correctly.
+func Test_Issue4156_NoFileUpload(t *testing.T) {
+	s := g.Server(guid.S())
+	s.BindHandler("/post", func(r *ghttp.Request) {
+		r.Response.Write(r.Get("field"))
+	})
+	s.SetDumpRouterMap(false)
+	s.Start()
+	defer s.Shutdown()
+
+	clientHost := fmt.Sprintf("http://127.0.0.1:%d", s.GetListenedPort())
+	time.Sleep(100 * time.Millisecond)
+
+	// Test normal POST with special characters (no file upload)
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"field": "a=1&b=2",
+		}
+		content := client.PostContent(ctx, "/post", data)
+		t.Assert(content, "a=1&b=2")
+	})
+
+	// Test POST with Content-Type: application/x-www-form-urlencoded
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		client.SetHeader("Content-Type", "application/x-www-form-urlencoded")
+		data := g.Map{
+			"field": "value=with=equals&and&ampersand",
+		}
+		content := client.PostContent(ctx, "/post", data)
+		t.Assert(content, "value=with=equals&and&ampersand")
+	})
+}
+
+// Test_Issue4156_PreEncodedValue tests that pre-encoded values are handled correctly.
+func Test_Issue4156_PreEncodedValue(t *testing.T) {
+	s := g.Server(guid.S())
+	s.BindHandler("/upload", func(r *ghttp.Request) {
+		r.Response.Write(r.Get("field"))
+	})
+	s.SetDumpRouterMap(false)
+	s.Start()
+	defer s.Shutdown()
+
+	clientHost := fmt.Sprintf("http://127.0.0.1:%d", s.GetListenedPort())
+	time.Sleep(100 * time.Millisecond)
+
+	// Test with already URL-encoded value - should preserve the encoding
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "value%3Dwith%26encoding", // User wants to send literal %3D
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		// The literal %3D and %26 should be preserved
+		t.Assert(content, "value%3Dwith%26encoding")
+	})
+}
+
+// Test_Issue4156_EmptyAndSpecialValues tests edge cases with empty and special values.
+func Test_Issue4156_EmptyAndSpecialValues(t *testing.T) {
+	s := g.Server(guid.S())
+	s.BindHandler("/upload", func(r *ghttp.Request) {
+		r.Response.Write(r.Get("field"))
+	})
+	s.SetDumpRouterMap(false)
+	s.Start()
+	defer s.Shutdown()
+
+	clientHost := fmt.Sprintf("http://127.0.0.1:%d", s.GetListenedPort())
+	time.Sleep(100 * time.Millisecond)
+
+	// Test with value starting with =
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "=startWithEquals",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(content, "=startWithEquals")
+	})
+
+	// Test with value ending with =
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "endWithEquals=",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(content, "endWithEquals=")
+	})
+
+	// Test with only special characters
+	gtest.C(t, func(t *gtest.T) {
+		client := gclient.New()
+		client.SetPrefix(clientHost)
+		data := g.Map{
+			"file":  "@file:" + gtest.DataPath("upload", "file1.txt"),
+			"field": "=&=&=",
+		}
+		content := client.PostContent(ctx, "/upload", data)
+		t.Assert(content, "=&=&=")
+	})
+}