Add test to verify JSON body dumping still works for non-multipart requests

Co-authored-by: kevwan <1918356+kevwan@users.noreply.github.com>

.github/copilot-instructions.md

@@ -8,14 +8,16 @@ go-zero is a web and RPC framework with lots of built-in engineering practices d
 
 ### Key Architecture Components
 
-- **REST API framework** (`rest/`) - HTTP service framework with middleware support
+- **REST API framework** (`rest/`) - HTTP service framework with middleware chain support
-- **RPC framework** (`zrpc/`) - gRPC-based RPC framework with service discovery
+- **RPC framework** (`zrpc/`) - gRPC-based RPC framework with etcd service discovery and p2c_ewma load balancing
-- **Core utilities** (`core/`) - Foundational components including:
+- **Gateway** (`gateway/`) - API gateway supporting both HTTP and gRPC upstreams with proto-based routing
-  - Circuit breakers, rate limiters, load shedding
+- **MCP Server** (`mcp/`) - Model Context Protocol server for AI agent integration via SSE
-  - Caching, stores (Redis, MongoDB, SQL)
+- **Core utilities** (`core/`) - Production-grade components:
-  - Concurrency control, metrics, tracing
+  - Resilience: circuit breakers (`breaker/`), rate limiters (`limit/`), adaptive load shedding (`load/`)
-  - Configuration management
+  - Storage: SQL with cache (`stores/sqlc/`), Redis (`stores/redis/`), MongoDB (`stores/mongo/`)
-- **Code generation tool** (`tools/goctl/`) - CLI tool for generating code from API files
+  - Concurrency: MapReduce (`mr/`), worker pools (`executors/`), sync primitives (`syncx/`)
+  - Observability: metrics (`metric/`), tracing (`trace/`), structured logging (`logx/`)
+- **Code generation tool** (`tools/goctl/`) - CLI tool for generating Go code from `.api` and `.proto` files
 
 ## Coding Standards and Conventions
 
@@ -25,18 +27,22 @@ go-zero is a web and RPC framework with lots of built-in engineering practices d
 2. **Package naming**: Use lowercase, single-word package names when possible
 3. **Error handling**: Always handle errors explicitly, use `errorx.BatchError` for multiple errors
 4. **Context propagation**: Always pass `context.Context` as the first parameter for functions that may block
-5. **Configuration structures**: Use struct tags with JSON annotations and default values
+5. **Configuration structures**: Use struct tags with JSON annotations, defaults, and validation
 
-Example configuration pattern:
+**Pattern**: All service configs embed `service.ServiceConf` for common fields (Name, Log, Mode, Telemetry)
 ```go
 type Config struct {
+    service.ServiceConf              // Always embed for services
     Host     string `json:",default=0.0.0.0"`
-    Port     int    `json:",default=8080"`
+    Port     int    // Required field (no default)
-    Timeout  int    `json:",default=3000"`
+    Timeout  int64  `json:",default=3000"`  // Timeouts in milliseconds
-    Optional string `json:",optional"`
+    Optional string `json:",optional"`      // Optional field
+    Mode     string `json:",default=pro,options=dev|test|rt|pre|pro"`  // Validated options
 }
 ```
 
+**Service modes**: `dev`/`test`/`rt` disable load shedding and stats; `pre`/`pro` enable all resilience features
+
 ### Interface Design
 
 1. **Small interfaces**: Follow Go's preference for small, focused interfaces
@@ -94,25 +100,33 @@ func TestSomething(t *testing.T) {
 
 ### REST API Development
 
-1. **API Definition**: Use `.api` files to define REST APIs
+1. **API Definition**: Use `.api` files to define REST APIs with goctl codegen
-2. **Handler pattern**: Separate business logic into logic packages
+2. **Handler pattern**: Separate business logic into logic packages (handlers call logic layer)
-3. **Middleware**: Use built-in middlewares (tracing, logging, metrics, recovery)
+3. **Middleware chain**: Middlewares wrap via `chain.Chain` interface - use `Append()` or `Prepend()` to control order
-4. **Response handling**: Use `httpx.WriteJson` for JSON responses
+   - Built-in middlewares (all in `rest/handler/`): tracing, logging, metrics, recovery, breaker, shedding, timeout, maxconns, maxbytes, gunzip
-5. **Error handling**: Use `httpx.Error` for HTTP error responses
+   - Custom middleware: `func(http.Handler) http.Handler` - call `next.ServeHTTP(w, r)` to continue chain
+4. **Response handling**: Use `httpx.WriteJson(w, code, v)` for JSON responses
+5. **Error handling**: Use `httpx.Error(w, err)` or `httpx.ErrorCtx(ctx, w, err)` for HTTP error responses
+6. **Route registration**: Routes defined with `Method`, `Path`, and `Handler` - wildcards use `:param` syntax
 
 ### RPC Development
 
-1. **Protocol Buffers**: Use protobuf for service definitions
+1. **Protocol Buffers**: Use protobuf for service definitions, generate code with goctl
-2. **Service discovery**: Integrate with etcd for service registration
+2. **Service discovery**: Use etcd for dynamic service registration/discovery, or direct endpoints for static routing
-3. **Load balancing**: Use built-in load balancing strategies
+3. **Load balancing**: Default is `p2c_ewma` (power of 2 choices with EWMA), configurable via `BalancerName`
-4. **Interceptors**: Implement interceptors for cross-cutting concerns
+4. **Client configuration**: Support `Etcd`, `Endpoints`, or `Target` - use `BuildTarget()` to construct connection string
+5. **Interceptors**: Implement gRPC interceptors for cross-cutting concerns (auth, logging, metrics)
+6. **Health checks**: gRPC health checks enabled by default (`Health: true`)
 
 ### Database Operations
 
-1. **SQL operations**: Use `sqlx` package for database operations
+1. **SQL operations**: Use `sqlx.SqlConn` interface - methods always end with `Ctx` for context support
-2. **Caching**: Implement caching patterns with `cache` package
+2. **Caching pattern**: `stores/sqlc` provides `CachedConn` for automatic cache-aside pattern
-3. **Transactions**: Use proper transaction handling
+   - `QueryRowCtx`: Query with cache key, auto-populate on cache miss
-4. **Connection pooling**: Configure appropriate connection pools
+   - `ExecCtx`: Execute and delete cache keys
+3. **Transactions**: Use `sqlx.SqlConn.TransactCtx()` to get transaction session
+4. **Connection pooling**: Managed automatically (64 max idle/open, 1min lifetime)
+5. **Test helpers**: Use `redistest.CreateRedis(t)` for Redis, SQL mocks for DB testing
 
 Example cache pattern:
 ```go
@@ -158,6 +172,109 @@ err := c.QueryRowCtx(ctx, &dest, key, func(ctx context.Context, conn sqlx.SqlCon
 3. **API documentation**: Maintain API documentation in sync
 4. **README updates**: Update README for significant changes
 
+## GitHub Issue Management
+
+### Understanding and Categorizing Issues
+
+When analyzing GitHub issues, consider these common categories:
+
+1. **Bug Reports**: Stack traces, version info, reproduction steps
+2. **Feature Requests**: Use case, proposed solution, alternatives
+3. **Questions**: Usage, configuration, or architecture
+4. **Documentation Issues**: Missing, unclear, or incorrect docs
+5. **Performance Issues**: Benchmarks, profiling data, resource usage
+
+### Issue Analysis Checklist
+
+- Identify affected component (REST, RPC, Gateway, MCP, Core utilities, goctl)
+- Check versions (go-zero, Go)
+- Look for reproduction steps or code examples
+- Review code snippets, logs, or stack traces
+- Check if related to resilience features (breaker, load shedding, rate limiting)
+- Determine production impact
+
+### Responding to Issues
+
+Be helpful and professional. Ask clarifying questions when needed. Reference relevant documentation and code files. Provide code examples following project conventions. Suggest workarounds when applicable.
+
+### Chinese to English Translation
+
+go-zero has an international user base. When encountering issues or comments written in Chinese, translate them to English to ensure all contributors can participate in discussions.
+
+#### Translation Guidelines
+
+1. **Update issue titles**: Edit the issue title to include English translation only
+2. **Translate comments in place**: Add a comment with the English translation, followed by the original Chinese text
+3. **Keep original Chinese**: After translating, include the original Chinese text in a blockquote for verification
+4. **Encourage English communication**: Politely suggest users write in English for better collaboration
+5. **Maintain technical accuracy**: Preserve technical terms, component names, and code exactly
+6. **Translate naturally**: Avoid literal word-by-word translation; use idiomatic English
+7. **Preserve formatting**: Keep markdown formatting, code blocks, and links intact
+8. **Keep URLs unchanged**: Don't translate URLs or file paths
+
+#### Common Technical Terms (Chinese → English)
+
+- 框架 → **Framework** | 中间件 → **Middleware** | 负载均衡 → **Load Balancing**
+- 熔断器 → **Circuit Breaker** | 限流 → **Rate Limiting** | 降载/过载保护 → **Load Shedding**
+- 服务发现 → **Service Discovery** | 配置 → **Configuration** | 弹性/容错 → **Resilience** | 微服务 → **Microservices**
+
+#### Translation Example
+
+**Original Chinese Title:** `goctl 执行环境问题`
+**Updated Title:** `goctl Execution Environment Issue`
+
+**Original Chinese Comment:** `我在项目中遇到熔断器配置问题`
+**Translation in Comment:**
+```markdown
+I encountered a circuit breaker configuration issue in my project.
+
+> Original (原文): 我在项目中遇到熔断器配置问题
+```
+
+### Common Issue Patterns and Solutions
+
+#### Configuration Issues
+- Check `service.ServiceConf` embedding and struct tags
+- Verify YAML syntax, defaults, and validation rules
+- Reference: [rest/config.go](rest/config.go), [zrpc/config.go](zrpc/config.go)
+
+#### Code Generation (goctl) Issues
+- Verify `.api` or `.proto` file syntax and goctl version
+- Reference: `tools/goctl/` directory
+
+#### RPC Connection Issues
+- Check etcd configuration, service discovery, and endpoints
+- Verify load balancing settings (p2c_ewma)
+
+#### Database/Cache Issues
+- Verify `sqlx.SqlConn` usage with context
+- Check cache key generation, invalidation, and connection pools
+- Use test helpers (`redistest`, `mongtest`)
+
+#### Performance Issues
+- Check if load shedding is enabled (mode: `pre`/`pro`)
+- Review circuit breaker thresholds, rate limiting, and context timeouts
+
+### Referencing Codebase
+
+When explaining issues, reference specific files and patterns:
+- REST API: `rest/`, `rest/handler/`, `rest/httpx/`
+- RPC: `zrpc/`, `zrpc/internal/`
+- Core utilities: `core/breaker/`, `core/limit/`, `core/load/`, etc.
+- Gateway: `gateway/`
+- MCP: `mcp/`
+- Code generation: `tools/goctl/`
+- Examples: `adhoc/` directory contains various examples
+
+### Encouraging Best Practices
+
+When responding to issues, gently guide users toward:
+- Proper error handling with context
+- Using resilience features (breakers, rate limiters)
+- Following testing patterns with table-driven tests
+- Implementing proper resource cleanup
+- Reading existing documentation in `docs/` and `readme.md`
+
 ## Common Patterns to Follow
 
 ### Service Configuration
@@ -189,9 +306,39 @@ Always implement proper resource cleanup using defer and context cancellation.
 ## Build and Test Commands
 
 - Build: `go build ./...`
-- Test: `go test ./...`  
+- Test: `go test ./...`
 - Test with race detection: `go test -race ./...`
 - Format: `gofmt -w .`
-- Generate code: `goctl api go -api *.api -dir .`
+- Code generation:
+  - REST API: `goctl api go -api *.api -dir .`
+  - RPC: `goctl rpc protoc *.proto --go_out=. --go-grpc_out=. --zrpc_out=.`
+  - Model from SQL: `goctl model mysql datasource -url="user:pass@tcp(host:port)/db" -table="*" -dir="./model"`
+
+## Critical Architecture Patterns
+
+### Resilience Design Philosophy
+go-zero implements defense-in-depth with multiple protection layers:
+1. **Circuit Breaker** (`core/breaker`): Google SRE breaker - tracks success/failure, opens on error threshold
+2. **Adaptive Load Shedding** (`core/load`): CPU-based auto-rejection when system overloaded (disabled in dev/test/rt modes)
+3. **Rate Limiting** (`core/limit`): Token bucket (Redis-based) and period limiters
+4. **Timeout Control**: Cascading timeouts via context - set at multiple levels (client, server, handler)
+
+### Middleware Chain Architecture
+`rest/chain` provides middleware composition:
+```go
+// Middleware signature
+type Middleware func(http.Handler) http.Handler
+
+// Chain operations
+chain := chain.New(m1, m2)
+chain.Append(m3)    // Adds to end: m1 -> m2 -> m3
+chain.Prepend(m0)   // Adds to start: m0 -> m1 -> m2 -> m3
+handler := chain.Then(finalHandler)
+```
+
+### Concurrency Patterns
+- **MapReduce** (`core/mr`): Parallel processing with worker pools - use for batch operations
+- **Executors** (`core/executors`): Bulk/period executors for batching operations
+- **SingleFlight** (`core/syncx`): Deduplicates concurrent identical requests
 
 Remember to run tests and ensure all checks pass before submitting changes. The project emphasizes high quality, performance, and reliability, so these should be primary considerations in all development work.

.github/workflows/codeql-analysis.yml

@@ -35,11 +35,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -50,7 +50,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v3
+      uses: github/codeql-action/autobuild@v4
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -64,4 +64,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v4

.github/workflows/go.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code into the Go module directory
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Set up Go 1.x
         uses: actions/setup-go@v6
@@ -52,7 +52,7 @@ jobs:
     runs-on: windows-latest
     steps:
       - name: Checkout codebase
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Set up Go 1.x
         uses: actions/setup-go@v6

.github/workflows/release.yaml

@@ -16,7 +16,7 @@ jobs:
           - goarch: "386"
             goos: darwin
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: zeromicro/go-zero-release-action@master
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/reviewdog.yml

@@ -5,7 +5,12 @@ jobs:
     name: runner / staticcheck
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          check-latest: true
+          cache: true
       - uses: reviewdog/action-staticcheck@v1
         with:
           github_token: ${{ secrets.github_token }}

.github/workflows/version-check.yml

@@ -10,7 +10,7 @@ jobs:
   version-check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Set up Go
         uses: actions/setup-go@v6

core/bloom/bloom.go

@@ -40,7 +40,7 @@ type (
 	}
 )
 
-// New create a Filter, store is the backed redis, key is the key for the bloom filter,
+// New creates a Filter, store is the backed redis, key is the key for the bloom filter,
 // bits is how many bits will be used, maps is how many hashes for each addition.
 // best practices:
 // elements - means how many actual elements

core/collection/cache.go

@@ -81,6 +81,10 @@ func (c *Cache) Del(key string) {
 	delete(c.data, key)
 	c.lruCache.remove(key)
 	c.lock.Unlock()
+
+	// RemoveTimer is called outside the lock to avoid performance impact from this
+	// potentially time-consuming operation. Data integrity is maintained by lruCache,
+	// which will eventually evict any remaining entries when capacity is exceeded.
 	c.timingWheel.RemoveTimer(key)
 }
 

core/collection/timingwheel.go

@@ -164,6 +164,7 @@ func (tw *TimingWheel) Stop() {
 
 func (tw *TimingWheel) drainAll(fn func(key, value any)) {
 	runner := threading.NewTaskRunner(drainWorkers)
+
 	for _, slot := range tw.slots {
 		for e := slot.Front(); e != nil; {
 			task := e.Value.(*timingEntry)
@@ -177,6 +178,8 @@ func (tw *TimingWheel) drainAll(fn func(key, value any)) {
 			}
 		}
 	}
+
+	runner.Wait()
 }
 
 func (tw *TimingWheel) getPositionAndCircle(d time.Duration) (pos, circle int) {

core/collection/timingwheel_test.go

@@ -629,6 +629,157 @@ func TestMoveAndRemoveTask(t *testing.T) {
 	assert.Equal(t, 0, len(keys))
 }
 
+// TestTimingWheel_DrainClosureBug tests the closure capture bug in drainAll
+// Issue: https://github.com/zeromicro/go-zero/issues/5314
+func TestTimingWheel_DrainClosureBug(t *testing.T) {
+	ticker := timex.NewFakeTicker()
+	tw, _ := NewTimingWheelWithTicker(testStep, 10, func(k, v any) {}, ticker)
+	defer tw.Stop()
+
+	// Set multiple timers with different values
+	for i := 0; i < 10; i++ {
+		tw.SetTimer(i, i*10, testStep*5)
+	}
+
+	// Give time for timers to be set
+	time.Sleep(time.Millisecond * 100)
+
+	var mu sync.Mutex
+	received := make(map[int]int)
+	var wg sync.WaitGroup
+	wg.Add(10)
+
+	tw.Drain(func(key, value any) {
+		mu.Lock()
+		defer mu.Unlock()
+		k := key.(int)
+		v := value.(int)
+		received[k] = v
+		wg.Done()
+	})
+
+	wg.Wait()
+
+	// Check if all values match their keys
+	for k, v := range received {
+		expected := k * 10
+		assert.Equal(t, expected, v, "key %d should have value %d, got %d", k, expected, v)
+	}
+}
+
+// TestTimingWheel_RunTasksClosureBug tests the closure capture bug in runTasks
+// Issue: https://github.com/zeromicro/go-zero/issues/5314
+func TestTimingWheel_RunTasksClosureBug(t *testing.T) {
+	ticker := timex.NewFakeTicker()
+	var mu sync.Mutex
+	executed := make(map[int]int)
+	var wg sync.WaitGroup
+
+	tw, _ := NewTimingWheelWithTicker(testStep, 10, func(k, v any) {
+		mu.Lock()
+		defer mu.Unlock()
+		key := k.(int)
+		val := v.(int)
+		executed[key] = val
+		wg.Done()
+	}, ticker)
+	defer tw.Stop()
+
+	// Set multiple timers that should fire in the same tick
+	count := 10
+	wg.Add(count)
+	for i := 0; i < count; i++ {
+		tw.SetTimer(i, i*10, testStep)
+	}
+
+	// Advance ticker to trigger tasks
+	ticker.Tick()
+
+	// Wait for execution with timeout
+	done := make(chan struct{})
+	go func() {
+		wg.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// Success
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for tasks to execute")
+	}
+
+	// Verify all tasks executed with correct values
+	assert.Equal(t, count, len(executed), "should have executed all tasks")
+	for k, v := range executed {
+		expected := k * 10
+		assert.Equal(t, expected, v, "key %d should have value %d, got %d", k, expected, v)
+	}
+}
+
+// TestTimingWheel_RunTasksRaceCondition tests for race conditions in runTasks
+// This test specifically targets the loop variable capture bug
+func TestTimingWheel_RunTasksRaceCondition(t *testing.T) {
+	// Run multiple times to increase likelihood of catching the bug
+	for attempt := 0; attempt < 10; attempt++ {
+		t.Run("", func(t *testing.T) {
+			ticker := timex.NewFakeTicker()
+			var mu sync.Mutex
+			keyValues := make(map[int][]int)
+			var wg sync.WaitGroup
+
+			tw, _ := NewTimingWheelWithTicker(testStep, 10, func(k, v any) {
+				// Add small delay to increase chance of race
+				time.Sleep(time.Microsecond)
+				mu.Lock()
+				defer mu.Unlock()
+				key := k.(int)
+				val := v.(int)
+				keyValues[key] = append(keyValues[key], val)
+				wg.Done()
+			}, ticker)
+			defer tw.Stop()
+
+			// Set many timers rapidly to increase chance of race
+			count := 50
+			wg.Add(count)
+			for i := 0; i < count; i++ {
+				tw.SetTimer(i, i*100, testStep)
+			}
+
+			ticker.Tick()
+
+			done := make(chan struct{})
+			go func() {
+				wg.Wait()
+				close(done)
+			}()
+
+			select {
+			case <-done:
+			case <-time.After(5 * time.Second):
+				t.Fatal("timeout waiting for tasks")
+			}
+
+			// Check for duplicates or wrong values
+			wrongCount := 0
+			for key, values := range keyValues {
+				assert.Equal(t, 1, len(values), "key %d should only execute once, got %v", key, values)
+				if len(values) > 0 {
+					expected := key * 100
+					if values[0] != expected {
+						wrongCount++
+						t.Logf("BUG DETECTED: key %d should have value %d, got %d", key, expected, values[0])
+					}
+				}
+			}
+			if wrongCount > 0 {
+				t.Errorf("Found %d tasks with wrong values due to closure bug", wrongCount)
+			}
+		})
+	}
+}
+
 func BenchmarkTimingWheel(b *testing.B) {
 	b.ReportAllocs()
 

core/conf/config.go

@@ -62,11 +62,7 @@ func Load(file string, v any, opts ...Option) error {
 		return loader([]byte(os.ExpandEnv(string(content))), v)
 	}
 
-	if err = loader(content, v); err != nil {
+	return loader(content, v)
-		return err
-	}
-
-	return validate(v)
 }
 
 // LoadConfig loads config into v from file, .json, .yaml and .yml are acceptable.
@@ -368,5 +364,5 @@ func getFullName(parent, child string) string {
 		return child
 	}
 
-	return strings.Join([]string{parent, child}, ".")
+	return parent + "." + child
 }

core/conf/config_test.go

@@ -1377,3 +1377,242 @@ func (m mockConfig) Validate() error {
 
 	return nil
 }
+
+func TestGetFullName(t *testing.T) {
+	tests := []struct {
+		parent string
+		child  string
+		want   string
+	}{
+		{"", "child", "child"},
+		{"parent", "child", "parent.child"},
+		{"a.b", "c", "a.b.c"},
+		{"root", "nested.field", "root.nested.field"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.parent+"."+tt.child, func(t *testing.T) {
+			got := getFullName(tt.parent, tt.child)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+// validatorConfig is a test config that implements Validate() for testing validation behavior
+type validatorConfig struct {
+	Value int `json:"value"`
+}
+
+func (v *validatorConfig) Validate() error {
+	if v.Value < 10 {
+		return errors.New("value must be >= 10")
+	}
+	return nil
+}
+
+// TestLoadValidation_WithoutEnv tests that validation is called correctly in normal loading path
+func TestLoadValidation_WithoutEnv(t *testing.T) {
+	tests := []struct {
+		name      string
+		extension string
+		content   string
+		wantErr   bool
+		errMsg    string
+	}{
+		{
+			name:      "json valid value",
+			extension: ".json",
+			content:   `{"value": 15}`,
+			wantErr:   false,
+		},
+		{
+			name:      "json invalid value",
+			extension: ".json",
+			content:   `{"value": 5}`,
+			wantErr:   true,
+			errMsg:    "value must be >= 10",
+		},
+		{
+			name:      "yaml valid value",
+			extension: ".yaml",
+			content:   "value: 20\n",
+			wantErr:   false,
+		},
+		{
+			name:      "yaml invalid value",
+			extension: ".yaml",
+			content:   "value: 3\n",
+			wantErr:   true,
+			errMsg:    "value must be >= 10",
+		},
+		{
+			name:      "toml valid value",
+			extension: ".toml",
+			content:   "value = 100\n",
+			wantErr:   false,
+		},
+		{
+			name:      "toml invalid value",
+			extension: ".toml",
+			content:   "value = 1\n",
+			wantErr:   true,
+			errMsg:    "value must be >= 10",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpfile, err := createTempFile(t, tt.extension, tt.content)
+			assert.Nil(t, err)
+
+			var cfg validatorConfig
+			err = Load(tmpfile, &cfg)
+
+			if tt.wantErr {
+				assert.Error(t, err)
+				assert.Contains(t, err.Error(), tt.errMsg)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+// TestLoadValidation_WithEnv tests that validation is called correctly with UseEnv() option
+func TestLoadValidation_WithEnv(t *testing.T) {
+	tests := []struct {
+		name      string
+		extension string
+		content   string
+		envValue  string
+		wantErr   bool
+		errMsg    string
+	}{
+		{
+			name:      "json valid value with env",
+			extension: ".json",
+			content:   `{"value": ${TEST_VALUE}}`,
+			envValue:  "25",
+			wantErr:   false,
+		},
+		{
+			name:      "json invalid value with env",
+			extension: ".json",
+			content:   `{"value": ${TEST_VALUE}}`,
+			envValue:  "7",
+			wantErr:   true,
+			errMsg:    "value must be >= 10",
+		},
+		{
+			name:      "yaml valid value with env",
+			extension: ".yaml",
+			content:   "value: ${TEST_VALUE}\n",
+			envValue:  "50",
+			wantErr:   false,
+		},
+		{
+			name:      "yaml invalid value with env",
+			extension: ".yaml",
+			content:   "value: ${TEST_VALUE}\n",
+			envValue:  "2",
+			wantErr:   true,
+			errMsg:    "value must be >= 10",
+		},
+		{
+			name:      "toml valid value with env",
+			extension: ".toml",
+			content:   "value = ${TEST_VALUE}\n",
+			envValue:  "99",
+			wantErr:   false,
+		},
+		{
+			name:      "toml invalid value with env",
+			extension: ".toml",
+			content:   "value = ${TEST_VALUE}\n",
+			envValue:  "8",
+			wantErr:   true,
+			errMsg:    "value must be >= 10",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Setenv("TEST_VALUE", tt.envValue)
+
+			tmpfile, err := createTempFile(t, tt.extension, tt.content)
+			assert.Nil(t, err)
+
+			var cfg validatorConfig
+			err = Load(tmpfile, &cfg, UseEnv())
+
+			if tt.wantErr {
+				assert.Error(t, err)
+				assert.Contains(t, err.Error(), tt.errMsg)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+// TestLoadValidation_Consistency verifies validation behavior is consistent between paths
+func TestLoadValidation_Consistency(t *testing.T) {
+	// Test that both paths (with and without UseEnv) produce the same validation results
+	const validValue = 15
+
+	formats := []struct {
+		ext     string
+		invalid string
+		valid   string
+	}{
+		{".json", `{"value": 5}`, `{"value": 15}`},
+		{".yaml", "value: 5\n", "value: 15\n"},
+		{".toml", "value = 5\n", "value = 15\n"},
+	}
+
+	for _, format := range formats {
+		t.Run("invalid_"+format.ext, func(t *testing.T) {
+			// Test without UseEnv()
+			tmpfile1, err := createTempFile(t, format.ext, format.invalid)
+			assert.Nil(t, err)
+
+			var cfg1 validatorConfig
+			err1 := Load(tmpfile1, &cfg1)
+
+			// Test with UseEnv()
+			tmpfile2, err := createTempFile(t, format.ext, format.invalid)
+			assert.Nil(t, err)
+
+			var cfg2 validatorConfig
+			err2 := Load(tmpfile2, &cfg2, UseEnv())
+
+			// Both should fail validation
+			assert.Error(t, err1, "validation should fail without UseEnv()")
+			assert.Error(t, err2, "validation should fail with UseEnv()")
+			assert.Contains(t, err1.Error(), "value must be >= 10")
+			assert.Contains(t, err2.Error(), "value must be >= 10")
+		})
+
+		t.Run("valid_"+format.ext, func(t *testing.T) {
+			// Test without UseEnv()
+			tmpfile1, err := createTempFile(t, format.ext, format.valid)
+			assert.Nil(t, err)
+
+			var cfg1 validatorConfig
+			err1 := Load(tmpfile1, &cfg1)
+
+			// Test with UseEnv()
+			tmpfile2, err := createTempFile(t, format.ext, format.valid)
+			assert.Nil(t, err)
+
+			var cfg2 validatorConfig
+			err2 := Load(tmpfile2, &cfg2, UseEnv())
+
+			// Both should pass validation
+			assert.NoError(t, err1, "validation should pass without UseEnv()")
+			assert.NoError(t, err2, "validation should pass with UseEnv()")
+			assert.Equal(t, validValue, cfg1.Value)
+			assert.Equal(t, validValue, cfg2.Value)
+		})
+	}
+}

core/conf/properties.go

@@ -45,7 +45,7 @@ func LoadProperties(filename string, opts ...Option) (Properties, error) {
 
 	raw := make(map[string]string)
 	for i := range lines {
-		pair := strings.Split(lines[i], "=")
+		pair := strings.SplitN(lines[i], "=", 2)
 		if len(pair) != 2 {
 			// invalid property format
 			return nil, &PropertyError{

core/conf/properties_test.go

@@ -92,3 +92,70 @@ func TestLoadBadFile(t *testing.T) {
 	_, err := LoadProperties("nosuchfile")
 	assert.NotNil(t, err)
 }
+
+func TestProperties_valueWithEqualSymbols(t *testing.T) {
+	text := `# test with equal symbols in value
+	db.url=postgres://localhost:5432/db?param=value
+	math.equation=a=b=c
+	base64.data=SGVsbG8=World=Test=
+	url.with.params=http://example.com?foo=bar&baz=qux
+	empty.value=
+	key.with.space = value = with = equals`
+	tmpfile, err := fs.TempFilenameWithText(text)
+	assert.Nil(t, err)
+	defer os.Remove(tmpfile)
+
+	props, err := LoadProperties(tmpfile)
+	assert.Nil(t, err)
+	assert.Equal(t, "postgres://localhost:5432/db?param=value", props.GetString("db.url"))
+	assert.Equal(t, "a=b=c", props.GetString("math.equation"))
+	assert.Equal(t, "SGVsbG8=World=Test=", props.GetString("base64.data"))
+	assert.Equal(t, "http://example.com?foo=bar&baz=qux", props.GetString("url.with.params"))
+	assert.Equal(t, "", props.GetString("empty.value"))
+	assert.Equal(t, "value = with = equals", props.GetString("key.with.space"))
+}
+
+func TestProperties_edgeCases(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		wantErr bool
+		errMsg  string
+	}{
+		{
+			name:    "no equal sign",
+			content: "invalid line without equal",
+			wantErr: true,
+		},
+		{
+			name:    "only equal sign",
+			content: "=",
+			wantErr: false, // "=" 会被解析为空 key 和空 value，len(pair) == 2，是合法的
+		},
+		{
+			name:    "empty key",
+			content: "=value",
+			wantErr: false, // 空 key 也会被 trim，但 len(pair) == 2 所以不会报错
+		},
+		{
+			name:    "equal at end",
+			content: "key.name=",
+			wantErr: false, // 空 value 是合法的
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpfile, err := fs.TempFilenameWithText(tt.content)
+			assert.Nil(t, err)
+			defer os.Remove(tmpfile)
+
+			_, err = LoadProperties(tmpfile)
+			if tt.wantErr {
+				assert.NotNil(t, err, "expected error for case: %s", tt.name)
+			} else {
+				assert.Nil(t, err, "unexpected error for case: %s", tt.name)
+			}
+		})
+	}
+}

core/configcenter/subscriber/etcd.go

@@ -1,6 +1,9 @@
 package subscriber
 
 import (
+	"sync"
+	"sync/atomic"
+
 	"github.com/zeromicro/go-zero/core/discov"
 	"github.com/zeromicro/go-zero/core/logx"
 )
@@ -37,6 +40,7 @@ func NewEtcdSubscriber(conf EtcdConf) (Subscriber, error) {
 func buildSubOptions(conf EtcdConf) []discov.SubOption {
 	opts := []discov.SubOption{
 		discov.WithExactMatch(),
+		discov.WithContainer(newContainer()),
 	}
 
 	if len(conf.User) > 0 {
@@ -65,3 +69,47 @@ func (s *etcdSubscriber) Value() (string, error) {
 
 	return "", nil
 }
+
+type container struct {
+	value     atomic.Value
+	listeners []func()
+	lock      sync.Mutex
+}
+
+func newContainer() *container {
+	return &container{}
+}
+
+func (c *container) OnAdd(kv discov.KV) {
+	c.value.Store([]string{kv.Val})
+	c.notifyChange()
+}
+
+func (c *container) OnDelete(_ discov.KV) {
+	c.value.Store([]string(nil))
+	c.notifyChange()
+}
+
+func (c *container) AddListener(listener func()) {
+	c.lock.Lock()
+	c.listeners = append(c.listeners, listener)
+	c.lock.Unlock()
+}
+
+func (c *container) GetValues() []string {
+	if vals, ok := c.value.Load().([]string); ok {
+		return vals
+	}
+
+	return []string(nil)
+}
+
+func (c *container) notifyChange() {
+	c.lock.Lock()
+	listeners := append(([]func())(nil), c.listeners...)
+	c.lock.Unlock()
+
+	for _, listener := range listeners {
+		listener()
+	}
+}

core/configcenter/subscriber/etcd_test.go

@@ -0,0 +1,186 @@
+package subscriber
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/zeromicro/go-zero/core/discov"
+)
+
+const (
+	actionAdd = iota
+	actionDel
+)
+
+func TestConfigCenterContainer(t *testing.T) {
+	type action struct {
+		act int
+		key string
+		val string
+	}
+	tests := []struct {
+		name   string
+		do     []action
+		expect []string
+	}{
+		{
+			name: "add one",
+			do: []action{
+				{
+					act: actionAdd,
+					key: "first",
+					val: "a",
+				},
+			},
+			expect: []string{
+				"a",
+			},
+		},
+		{
+			name: "add two",
+			do: []action{
+				{
+					act: actionAdd,
+					key: "first",
+					val: "a",
+				},
+				{
+					act: actionAdd,
+					key: "second",
+					val: "b",
+				},
+			},
+			expect: []string{
+				"b",
+			},
+		},
+		{
+			name: "add two, delete one",
+			do: []action{
+				{
+					act: actionAdd,
+					key: "first",
+					val: "a",
+				},
+				{
+					act: actionAdd,
+					key: "second",
+					val: "b",
+				},
+				{
+					act: actionDel,
+					key: "first",
+				},
+			},
+			expect: []string(nil),
+		},
+		{
+			name: "add two, delete two",
+			do: []action{
+				{
+					act: actionAdd,
+					key: "first",
+					val: "a",
+				},
+				{
+					act: actionAdd,
+					key: "second",
+					val: "b",
+				},
+				{
+					act: actionDel,
+					key: "first",
+				},
+				{
+					act: actionDel,
+					key: "second",
+				},
+			},
+			expect: []string(nil),
+		},
+		{
+			name: "add two, dup values",
+			do: []action{
+				{
+					act: actionAdd,
+					key: "first",
+					val: "a",
+				},
+				{
+					act: actionAdd,
+					key: "second",
+					val: "b",
+				},
+				{
+					act: actionAdd,
+					key: "third",
+					val: "a",
+				},
+			},
+			expect: []string{"a"},
+		},
+		{
+			name: "add three, dup values, delete two, add one",
+			do: []action{
+				{
+					act: actionAdd,
+					key: "first",
+					val: "a",
+				},
+				{
+					act: actionAdd,
+					key: "second",
+					val: "b",
+				},
+				{
+					act: actionAdd,
+					key: "third",
+					val: "a",
+				},
+				{
+					act: actionDel,
+					key: "first",
+				},
+				{
+					act: actionDel,
+					key: "second",
+				},
+				{
+					act: actionAdd,
+					key: "forth",
+					val: "c",
+				},
+			},
+			expect: []string{"c"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var changed bool
+			c := newContainer()
+			c.AddListener(func() {
+				changed = true
+			})
+			assert.Nil(t, c.GetValues())
+			assert.False(t, changed)
+
+			for _, order := range test.do {
+				if order.act == actionAdd {
+					c.OnAdd(discov.KV{
+						Key: order.key,
+						Val: order.val,
+					})
+				} else {
+					c.OnDelete(discov.KV{
+						Key: order.key,
+						Val: order.val,
+					})
+				}
+			}
+
+			assert.True(t, changed)
+			assert.ElementsMatch(t, test.expect, c.GetValues())
+		})
+	}
+}

core/discov/internal/registry.go

@@ -386,8 +386,9 @@ func (c *cluster) watch(cli EtcdClient, key watchKey, rev int64) {
 			rev = c.load(cli, key)
 		}
 
-		// log the error and retry
+		// log the error and retry with cooldown to prevent CPU/disk exhaustion
 		logc.Error(cli.Ctx(), err)
+		time.Sleep(coolDownUnstable.AroundDuration(coolDownInterval))
 	}
 }
 
@@ -432,16 +433,16 @@ func (c *cluster) setupWatch(cli EtcdClient, key watchKey, rev int64) (context.C
 	}
 
 	ctx, cancel := context.WithCancel(cli.Ctx())
+	
+	c.lock.Lock()
 	if watcher, ok := c.watchers[key]; ok {
 		watcher.cancel = cancel
 	} else {
 		val := newWatchValue()
 		val.cancel = cancel
-
-		c.lock.Lock()
 		c.watchers[key] = val
-		c.lock.Unlock()
 	}
+	c.lock.Unlock()
 
 	rch = cli.Watch(clientv3.WithRequireLeader(ctx), wkey, ops...)
 

core/discov/internal/registry_test.go

@@ -477,6 +477,72 @@ func TestRegistry_Unmonitor(t *testing.T) {
 	assert.Nil(t, watchVals)
 }
 
+// TestCluster_ConcurrentMonitor tests the race condition fix in setupWatch
+// This test specifically covers the scenario from issue #5394 where:
+// - addListener() writes to the watchers map (with lock)
+// - setupWatch() reads from the watchers map (now with lock after fix)
+// Running with -race flag will detect any race conditions
+func TestCluster_ConcurrentMonitor(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+
+	cli := NewMockEtcdClient(ctrl)
+	cli.EXPECT().Ctx().Return(context.Background()).AnyTimes()
+	cli.EXPECT().Watch(gomock.Any(), gomock.Any(), gomock.Any()).Return(make(chan clientv3.WatchResponse)).AnyTimes()
+
+	c := &cluster{
+		endpoints:  []string{"localhost:2379"},
+		key:        "test-cluster",
+		watchers:   make(map[watchKey]*watchValue),
+		watchGroup: threading.NewRoutineGroup(),
+		done:       make(chan lang.PlaceholderType),
+		lock:       sync.RWMutex{},
+	}
+
+	// Spawn multiple concurrent operations that simulate the race condition:
+	// - Some goroutines call addListener (write to map)
+	// - Some goroutines call setupWatch (read from map)
+	var wg sync.WaitGroup
+	numGoroutines := 20
+	wg.Add(numGoroutines)
+
+	keys := []watchKey{
+		{key: "key-0", exactMatch: false},
+		{key: "key-1", exactMatch: false},
+		{key: "key-2", exactMatch: false},
+	}
+
+	for i := 0; i < numGoroutines; i++ {
+		idx := i
+		go func() {
+			defer wg.Done()
+			key := keys[idx%len(keys)]
+			
+			if idx%2 == 0 {
+				// Half the goroutines add listeners (write operation)
+				c.addListener(key, &mockListener{})
+			} else {
+				// Half the goroutines setup watches (read operation)
+				_, _ = c.setupWatch(cli, key, 0)
+			}
+		}()
+	}
+
+	// Wait for all goroutines to complete
+	wg.Wait()
+
+	// Verify that watchers were correctly added
+	c.lock.RLock()
+	assert.True(t, len(c.watchers) > 0, "watchers should be added")
+	for _, watcher := range c.watchers {
+		assert.NotNil(t, watcher, "watcher should not be nil")
+	}
+	c.lock.RUnlock()
+
+	// Clean up
+	close(c.done)
+}
+
 type mockListener struct {
 }
 

core/discov/subscriber.go

@@ -19,8 +19,9 @@ type (
 		exclusive  bool
 		key        string
 		exactMatch bool
-		items      *container
+		items      Container
 	}
+	KV = internal.KV
 )
 
 // NewSubscriber returns a Subscriber.
@@ -35,7 +36,9 @@ func NewSubscriber(endpoints []string, key string, opts ...SubOption) (*Subscrib
 	for _, opt := range opts {
 		opt(sub)
 	}
-	sub.items = newContainer(sub.exclusive)
+	if sub.items == nil {
+		sub.items = newContainer(sub.exclusive)
+	}
 
 	if err := internal.GetRegistry().Monitor(endpoints, key, sub.exactMatch, sub.items); err != nil {
 		return nil, err
@@ -46,7 +49,7 @@ func NewSubscriber(endpoints []string, key string, opts ...SubOption) (*Subscrib
 
 // AddListener adds listener to s.
 func (s *Subscriber) AddListener(listener func()) {
-	s.items.addListener(listener)
+	s.items.AddListener(listener)
 }
 
 // Close closes the subscriber.
@@ -56,7 +59,7 @@ func (s *Subscriber) Close() {
 
 // Values returns all the subscription values.
 func (s *Subscriber) Values() []string {
-	return s.items.getValues()
+	return s.items.GetValues()
 }
 
 // Exclusive means that key value can only be 1:1,
@@ -88,16 +91,32 @@ func WithSubEtcdTLS(certFile, certKeyFile, caFile string, insecureSkipVerify boo
 	}
 }
 
-type container struct {
+// WithContainer provides a custom container to the subscriber.
-	exclusive bool
+func WithContainer(container Container) SubOption {
-	values    map[string][]string
+	return func(sub *Subscriber) {
-	mapping   map[string]string
+		sub.items = container
-	snapshot  atomic.Value
+	}
-	dirty     *syncx.AtomicBool
-	listeners []func()
-	lock      sync.Mutex
 }
 
+type (
+	Container interface {
+		OnAdd(kv internal.KV)
+		OnDelete(kv internal.KV)
+		AddListener(listener func())
+		GetValues() []string
+	}
+
+	container struct {
+		exclusive bool
+		values    map[string][]string
+		mapping   map[string]string
+		snapshot  atomic.Value
+		dirty     *syncx.AtomicBool
+		listeners []func()
+		lock      sync.Mutex
+	}
+)
+
 func newContainer(exclusive bool) *container {
 	return &container{
 		exclusive: exclusive,
@@ -141,7 +160,7 @@ func (c *container) addKv(key, value string) ([]string, bool) {
 	return nil, false
 }
 
-func (c *container) addListener(listener func()) {
+func (c *container) AddListener(listener func()) {
 	c.lock.Lock()
 	c.listeners = append(c.listeners, listener)
 	c.lock.Unlock()
@@ -170,7 +189,7 @@ func (c *container) doRemoveKey(key string) {
 	}
 }
 
-func (c *container) getValues() []string {
+func (c *container) GetValues() []string {
 	if !c.dirty.True() {
 		return c.snapshot.Load().([]string)
 	}

core/discov/subscriber_test.go

@@ -171,10 +171,10 @@ func TestContainer(t *testing.T) {
 			t.Run(test.name, func(t *testing.T) {
 				var changed bool
 				c := newContainer(exclusive)
-				c.addListener(func() {
+				c.AddListener(func() {
 					changed = true
 				})
-				assert.Nil(t, c.getValues())
+				assert.Nil(t, c.GetValues())
 				assert.False(t, changed)
 
 				for _, order := range test.do {
@@ -193,9 +193,9 @@ func TestContainer(t *testing.T) {
 
 				assert.True(t, changed)
 				assert.True(t, c.dirty.True())
-				assert.ElementsMatch(t, test.expect, c.getValues())
+				assert.ElementsMatch(t, test.expect, c.GetValues())
 				assert.False(t, c.dirty.True())
-				assert.ElementsMatch(t, test.expect, c.getValues())
+				assert.ElementsMatch(t, test.expect, c.GetValues())
 			})
 		}
 	}
@@ -204,12 +204,14 @@ func TestContainer(t *testing.T) {
 func TestSubscriber(t *testing.T) {
 	sub := new(Subscriber)
 	Exclusive()(sub)
-	sub.items = newContainer(sub.exclusive)
+	c := newContainer(sub.exclusive)
+	WithContainer(c)(sub)
+	sub.items = c
 	var count int32
 	sub.AddListener(func() {
 		atomic.AddInt32(&count, 1)
 	})
-	sub.items.notifyChange()
+	c.notifyChange()
 	assert.Empty(t, sub.Values())
 	assert.Equal(t, int32(1), atomic.LoadInt32(&count))
 }
@@ -229,12 +231,13 @@ func TestWithSubEtcdAccount(t *testing.T) {
 func TestWithExactMatch(t *testing.T) {
 	sub := new(Subscriber)
 	WithExactMatch()(sub)
-	sub.items = newContainer(sub.exclusive)
+	c := newContainer(sub.exclusive)
+	sub.items = c
 	var count int32
 	sub.AddListener(func() {
 		atomic.AddInt32(&count, 1)
 	})
-	sub.items.notifyChange()
+	c.notifyChange()
 	assert.Empty(t, sub.Values())
 	assert.Equal(t, int32(1), atomic.LoadInt32(&count))
 }

core/fx/stream.go

@@ -168,7 +168,7 @@ func (s Stream) Count() (count int) {
 	return
 }
 
-// Distinct removes the duplicated items base on the given KeyFunc.
+// Distinct removes the duplicated items based on the given KeyFunc.
 func (s Stream) Distinct(fn KeyFunc) Stream {
 	source := make(chan any)
 
@@ -459,7 +459,7 @@ func (s Stream) Tail(n int64) Stream {
 	return Range(source)
 }
 
-// Walk lets the callers handle each item, the caller may write zero, one or more items base on the given item.
+// Walk lets the callers handle each item, the caller may write zero, one or more items based on the given item.
 func (s Stream) Walk(fn WalkFunc, opts ...Option) Stream {
 	option := buildOptions(opts...)
 	if option.unlimitedWorkers {

core/fx/stream_test.go

@@ -1,8 +1,6 @@
 package fx
 
 import (
-	"io"
-	"log"
 	"math/rand"
 	"reflect"
 	"runtime"
@@ -13,6 +11,7 @@ import (
 	"time"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/zeromicro/go-zero/core/logx/logtest"
 	"github.com/zeromicro/go-zero/core/stringx"
 	"go.uber.org/goleak"
 )
@@ -238,7 +237,7 @@ func TestLast(t *testing.T) {
 
 func TestMap(t *testing.T) {
 	runCheckedTest(t, func(t *testing.T) {
-		log.SetOutput(io.Discard)
+		logtest.Discard(t)
 
 		tests := []struct {
 			mapper MapFunc

core/hash/consistenthash.go

@@ -96,7 +96,7 @@ func (h *ConsistentHash) AddWithWeight(node any, weight int) {
 	h.AddWithReplicas(node, replicas)
 }
 
-// Get returns the corresponding node from h base on the given v.
+// Get returns the corresponding node from h based on the given v.
 func (h *ConsistentHash) Get(v any) (any, bool) {
 	h.lock.RLock()
 	defer h.lock.RUnlock()

core/logx/rotatelogger.go

@@ -66,7 +66,7 @@ type (
 		gzip        bool
 	}
 
-	// SizeLimitRotateRule a rotation rule that make the log file rotated base on size
+	// SizeLimitRotateRule a rotation rule that makes the log file rotated based on size
 	SizeLimitRotateRule struct {
 		DailyRotateRule
 		maxSize    int64

core/logx/writer.go

@@ -444,6 +444,8 @@ func wrapLevelWithColor(level string) string {
 		colour = color.FgRed
 	case levelError:
 		colour = color.FgRed
+	case levelSevere:
+		colour = color.FgRed
 	case levelFatal:
 		colour = color.FgRed
 	case levelInfo:

core/mapping/utils.go

@@ -104,14 +104,13 @@ func convertToString(val any, fullName string) (string, error) {
 func convertTypeFromString(kind reflect.Kind, str string) (any, error) {
 	switch kind {
 	case reflect.Bool:
-		switch strings.ToLower(str) {
+		if str == "1" || strings.EqualFold(str, "true") {
-		case "1", "true":
 			return true, nil
-		case "0", "false":
-			return false, nil
-		default:
-			return false, errTypeMismatch
 		}
+		if str == "0" || strings.EqualFold(str, "false") {
+			return false, nil
+		}
+		return false, errTypeMismatch
 	case reflect.Int:
 		return strconv.ParseInt(str, 10, intSize)
 	case reflect.Int8:

core/mapping/utils_test.go

@@ -334,3 +334,43 @@ func TestValidateValueRange(t *testing.T) {
 func TestSetMatchedPrimitiveValue(t *testing.T) {
 	assert.Error(t, setMatchedPrimitiveValue(reflect.Func, reflect.ValueOf(2), "1"))
 }
+
+func TestConvertTypeFromString_Bool(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    bool
+		wantErr bool
+	}{
+		// true cases
+		{name: "1", input: "1", want: true, wantErr: false},
+		{name: "true lowercase", input: "true", want: true, wantErr: false},
+		{name: "True mixed", input: "True", want: true, wantErr: false},
+		{name: "TRUE uppercase", input: "TRUE", want: true, wantErr: false},
+		{name: "TrUe mixed", input: "TrUe", want: true, wantErr: false},
+		// false cases
+		{name: "0", input: "0", want: false, wantErr: false},
+		{name: "false lowercase", input: "false", want: false, wantErr: false},
+		{name: "False mixed", input: "False", want: false, wantErr: false},
+		{name: "FALSE uppercase", input: "FALSE", want: false, wantErr: false},
+		{name: "FaLsE mixed", input: "FaLsE", want: false, wantErr: false},
+		// error cases
+		{name: "invalid yes", input: "yes", want: false, wantErr: true},
+		{name: "invalid no", input: "no", want: false, wantErr: true},
+		{name: "invalid empty", input: "", want: false, wantErr: true},
+		{name: "invalid 2", input: "2", want: false, wantErr: true},
+		{name: "invalid truee", input: "truee", want: false, wantErr: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := convertTypeFromString(reflect.Bool, tt.input)
+			if tt.wantErr {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+				assert.Equal(t, tt.want, got)
+			}
+		})
+	}
+}

core/mathx/unstable.go

@@ -6,7 +6,7 @@ import (
 	"time"
 )
 
-// An Unstable is used to generate random value around the mean value base on given deviation.
+// An Unstable is used to generate random value around the mean value based on given deviation.
 type Unstable struct {
 	deviation float64
 	r         *rand.Rand

core/mr/mapreduce_test.go

@@ -4,8 +4,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"io"
-	"log"
 	"runtime"
 	"sync/atomic"
 	"testing"
@@ -17,9 +15,6 @@ import (
 
 var errDummy = errors.New("dummy")
 
-func init() {
-	log.SetOutput(io.Discard)
-}
 
 func TestFinish(t *testing.T) {
 	defer goleak.VerifyNone(t)

core/stores/monc/cachedmodel_test.go

@@ -532,7 +532,7 @@ func createModel(t *testing.T, coll mon.Collection) *Model {
 	}
 }
 
-// mustNewTestModel  returns a test Model with the given cache.
+// mustNewTestModel returns a test Model with the given cache.
 func mustNewTestModel(collection mon.Collection, c cache.CacheConf, opts ...cache.Option) *Model {
 	return &Model{
 		Model: &mon.Model{

core/stores/redis/redis.go

@@ -259,12 +259,34 @@ func (s *Redis) BitPosCtx(ctx context.Context, key string, bit, start, end int64
 }
 
 // Blpop uses passed in redis connection to execute blocking queries.
+//
+// For blocking operations, you must create a dedicated RedisNode using CreateBlockingNode to avoid
+// exhausting the connection pool. Blocking commands hold connections for extended periods and should
+// not share the regular connection pool.
+//
+// Example usage:
+//
+//	node, err := redis.CreateBlockingNode(rds)
+//	if err != nil {
+//	    // handle error
+//	}
+//	defer node.Close()
+//
+//	value, err := rds.Blpop(node, "mylist")
+//	if err != nil {
+//	    // handle error
+//	}
+//
 // Doesn't benefit from pooling redis connections of blocking queries
 func (s *Redis) Blpop(node RedisNode, key string) (string, error) {
 	return s.BlpopCtx(context.Background(), node, key)
 }
 
 // BlpopCtx uses passed in redis connection to execute blocking queries.
+//
+// For blocking operations, you must create a dedicated RedisNode using CreateBlockingNode.
+// See Blpop for usage examples.
+//
 // Doesn't benefit from pooling redis connections of blocking queries
 func (s *Redis) BlpopCtx(ctx context.Context, node RedisNode, key string) (string, error) {
 	return s.BlpopWithTimeoutCtx(ctx, node, blockingQueryTimeout, key)
@@ -272,12 +294,18 @@ func (s *Redis) BlpopCtx(ctx context.Context, node RedisNode, key string) (strin
 
 // BlpopEx uses passed in redis connection to execute blpop command.
 // The difference against Blpop is that this method returns a bool to indicate success.
+//
+// For blocking operations, you must create a dedicated RedisNode using CreateBlockingNode.
+// See Blpop for usage examples.
 func (s *Redis) BlpopEx(node RedisNode, key string) (string, bool, error) {
 	return s.BlpopExCtx(context.Background(), node, key)
 }
 
 // BlpopExCtx uses passed in redis connection to execute blpop command.
 // The difference against Blpop is that this method returns a bool to indicate success.
+//
+// For blocking operations, you must create a dedicated RedisNode using CreateBlockingNode.
+// See Blpop for usage examples.
 func (s *Redis) BlpopExCtx(ctx context.Context, node RedisNode, key string) (string, bool, error) {
 	if node == nil {
 		return "", false, ErrNilNode
@@ -297,12 +325,18 @@ func (s *Redis) BlpopExCtx(ctx context.Context, node RedisNode, key string) (str
 
 // BlpopWithTimeout uses passed in redis connection to execute blpop command.
 // Control blocking query timeout
+//
+// For blocking operations, you must create a dedicated RedisNode using CreateBlockingNode.
+// See Blpop for usage examples.
 func (s *Redis) BlpopWithTimeout(node RedisNode, timeout time.Duration, key string) (string, error) {
 	return s.BlpopWithTimeoutCtx(context.Background(), node, timeout, key)
 }
 
 // BlpopWithTimeoutCtx uses passed in redis connection to execute blpop command.
 // Control blocking query timeout
+//
+// For blocking operations, you must create a dedicated RedisNode using CreateBlockingNode.
+// See Blpop for usage examples.
 func (s *Redis) BlpopWithTimeoutCtx(ctx context.Context, node RedisNode, timeout time.Duration,
 	key string) (string, error) {
 	if node == nil {
@@ -630,6 +664,28 @@ func (s *Redis) GetDelCtx(ctx context.Context, key string) (string, error) {
 	return val, err
 }
 
+// GetEx is the implementation of redis getex command.
+// Available since: redis version 6.2.0
+func (s *Redis) GetEx(key string, seconds int) (string, error) {
+	return s.GetExCtx(context.Background(), key, seconds)
+}
+
+// GetExCtx is the implementation of redis getex command.
+// Available since: redis version 6.2.0
+func (s *Redis) GetExCtx(ctx context.Context, key string, seconds int) (string, error) {
+	conn, err := getRedis(s)
+	if err != nil {
+		return "", err
+	}
+
+	val, err := conn.GetEx(ctx, key, time.Duration(seconds)*time.Second).Result()
+	if errors.Is(err, red.Nil) {
+		return "", nil
+	}
+
+	return val, err
+}
+
 // GetSet is the implementation of redis getset command.
 func (s *Redis) GetSet(key, value string) (string, error) {
 	return s.GetSetCtx(context.Background(), key, value)
@@ -1840,6 +1896,29 @@ func (s *Redis) XInfoStreamCtx(ctx context.Context, stream string) (*red.XInfoSt
 
 // XReadGroup reads messages from Redis streams as part of a consumer group.
 // It allows for distributed processing of stream messages with automatic message delivery semantics.
+//
+// For blocking operations, you must create a dedicated RedisNode using CreateBlockingNode to avoid
+// exhausting the connection pool. Blocking commands hold connections for extended periods and should
+// not share the regular connection pool.
+//
+// Example usage:
+//
+//	node, err := redis.CreateBlockingNode(rds)
+//	if err != nil {
+//	    // handle error
+//	}
+//	defer node.Close()
+//
+//	streams, err := rds.XReadGroup(
+//	    node,              // RedisNode created with CreateBlockingNode
+//	    "mygroup",         // consumer group name
+//	    "consumer1",       // consumer ID
+//	    10,                // max number of messages to read
+//	    5*time.Second,     // block duration
+//	    false,             // noAck flag
+//	    "mystream",        // stream name
+//	)
+//
 // Doesn't benefit from pooling redis connections of blocking queries.
 func (s *Redis) XReadGroup(node RedisNode, group string, consumerId string, count int64,
 	block time.Duration, noAck bool, streams ...string) ([]red.XStream, error) {
@@ -1847,6 +1926,10 @@ func (s *Redis) XReadGroup(node RedisNode, group string, consumerId string, coun
 }
 
 // XReadGroupCtx is the context-aware version of XReadGroup.
+//
+// For blocking operations, you must create a dedicated RedisNode using CreateBlockingNode to avoid
+// exhausting the connection pool. See XReadGroup for usage examples.
+//
 // Doesn't benefit from pooling redis connections of blocking queries.
 func (s *Redis) XReadGroupCtx(ctx context.Context, node RedisNode, group string, consumerId string,
 	count int64, block time.Duration, noAck bool, streams ...string) ([]red.XStream, error) {

core/stores/redis/redis_test.go

@@ -1104,6 +1104,45 @@ func TestRedis_GetDel(t *testing.T) {
 	})
 }
 
+func TestRedis_GetEx(t *testing.T) {
+	t.Run("get_ex", func(t *testing.T) {
+		runOnRedis(t, func(client *Redis) {
+			val, err := client.GetEx("getex_key", 10)
+			assert.Equal(t, "", val)
+			assert.Nil(t, err)
+
+			err = client.Set("getex_key", "getex_value")
+			assert.Nil(t, err)
+
+			val, err = client.GetEx("getex_key", 10)
+			assert.Nil(t, err)
+			assert.Equal(t, "getex_value", val)
+			val, err = client.Get("getex_key")
+			assert.Nil(t, err)
+			assert.Equal(t, "getex_value", val)
+
+			ttl, err := client.Ttl("getex_key")
+			assert.Nil(t, err)
+			assert.True(t, ttl > 0 && ttl <= 10)
+
+			val, err = client.GetEx("getex_key", 5)
+			assert.Nil(t, err)
+			assert.Equal(t, "getex_value", val)
+
+			ttl, err = client.Ttl("getex_key")
+			assert.Nil(t, err)
+			assert.True(t, ttl > 0 && ttl <= 5)
+		})
+	})
+
+	t.Run("get_ex_with_error", func(t *testing.T) {
+		runOnRedisWithError(t, func(client *Redis) {
+			_, err := newRedis(client.Addr, badType()).GetEx("hello", 10)
+			assert.Error(t, err)
+		})
+	})
+}
+
 func TestRedis_GetSet(t *testing.T) {
 	t.Run("set_get", func(t *testing.T) {
 		runOnRedis(t, func(client *Redis) {

core/stores/redis/redisblockingnode.go

@@ -13,7 +13,37 @@ type ClosableNode interface {
 	Close()
 }
 
-// CreateBlockingNode returns a ClosableNode.
+// CreateBlockingNode creates a dedicated RedisNode for blocking operations.
+//
+// Blocking Redis commands (like BLPOP, BRPOP, XREADGROUP with block parameter) hold connections
+// for extended periods while waiting for data. Using them with the regular Redis connection pool
+// can exhaust all available connections, causing other operations to fail or timeout.
+//
+// CreateBlockingNode creates a separate Redis client with a minimal connection pool (size 1) that
+// is dedicated to blocking operations. This ensures blocking commands don't interfere with regular
+// Redis operations.
+//
+// Example usage:
+//
+//	rds := redis.MustNewRedis(redis.RedisConf{
+//	    Host: "localhost:6379",
+//	    Type: redis.NodeType,
+//	})
+//
+//	// Create a dedicated node for blocking operations
+//	node, err := redis.CreateBlockingNode(rds)
+//	if err != nil {
+//	    // handle error
+//	}
+//	defer node.Close() // Important: close the node when done
+//
+//	// Use the node for blocking operations
+//	value, err := rds.Blpop(node, "mylist")
+//	if err != nil {
+//	    // handle error
+//	}
+//
+// The returned ClosableNode must be closed when no longer needed to release resources.
 func CreateBlockingNode(r *Redis) (ClosableNode, error) {
 	timeout := readWriteTimeout + blockingQueryTimeout
 

core/stores/sqlx/orm.go

@@ -70,25 +70,16 @@ func getTaggedFieldValueMap(v reflect.Value) (map[string]any, error) {
 }
 
 func getValueInterface(value reflect.Value) (any, error) {
-	switch value.Kind() {
+	if !value.CanAddr() || !value.Addr().CanInterface() {
-	case reflect.Ptr:
+		return nil, ErrNotReadableValue
-		if !value.CanInterface() {
-			return nil, ErrNotReadableValue
-		}
-
-		if value.IsNil() {
-			baseValueType := mapping.Deref(value.Type())
-			value.Set(reflect.New(baseValueType))
-		}
-
-		return value.Interface(), nil
-	default:
-		if !value.CanAddr() || !value.Addr().CanInterface() {
-			return nil, ErrNotReadableValue
-		}
-
-		return value.Addr().Interface(), nil
 	}
+
+	if value.Kind() == reflect.Pointer && value.IsNil() {
+		baseValueType := mapping.Deref(value.Type())
+		value.Set(reflect.New(baseValueType))
+	}
+
+	return value.Addr().Interface(), nil
 }
 
 func isScanFailed(err error) bool {

core/stores/sqlx/orm_test.go

@@ -4,7 +4,9 @@ import (
 	"context"
 	"database/sql"
 	"errors"
+	"reflect"
 	"testing"
+	"time"
 
 	"github.com/DATA-DOG/go-sqlmock"
 	"github.com/stretchr/testify/assert"
@@ -1575,6 +1577,782 @@ func TestAnonymousStructPrError(t *testing.T) {
 	})
 }
 
+func TestUnmarshalRowsZeroValueStructPtr(t *testing.T) {
+	secondNamePtr := "second_ptr"
+	secondAgePtr := int64(30)
+	thirdNamePtr := "third_ptr"
+	thirdAgePtr := int64(0)
+
+	expect := []struct {
+		Name    string
+		NamePtr *string
+		Age     int64
+		AgePtr  *int64
+	}{
+		{
+			Name:    "first",
+			NamePtr: nil,
+			Age:     2,
+			AgePtr:  nil,
+		},
+		{
+			Name:    "second",
+			NamePtr: &secondNamePtr,
+			Age:     3,
+			AgePtr:  &secondAgePtr,
+		},
+		{
+			Name:    "",
+			NamePtr: &thirdNamePtr,
+			Age:     0,
+			AgePtr:  &thirdAgePtr,
+		},
+	}
+
+	var value []struct {
+		Age     int64   `db:"age"`
+		AgePtr  *int64  `db:"age_ptr"`
+		Name    string  `db:"name"`
+		NamePtr *string `db:"name_ptr"`
+	}
+
+	dbtest.RunTest(t, func(db *sql.DB, mock sqlmock.Sqlmock) {
+		rs := sqlmock.NewRows([]string{"name", "name_ptr", "age", "age_ptr"}).
+			AddRow("first", nil, 2, nil).
+			AddRow("second", "second_ptr", 3, 30).
+			AddRow("", "third_ptr", 0, 0)
+
+		mock.ExpectQuery("select (.+) from users where user=?").
+			WithArgs("anyone").WillReturnRows(rs)
+
+		assert.Nil(t, query(context.Background(), db, func(rows *sql.Rows) error {
+			return unmarshalRows(&value, rows, true)
+		}, "select name, name_ptr, age, age_ptr from users where user=?", "anyone"))
+
+		assert.Equal(t, 3, len(value), "应该返回3行数据")
+
+		for i, each := range expect {
+
+			assert.Equal(t, each.Name, value[i].Name)
+			assert.Equal(t, each.Age, value[i].Age)
+
+			if each.NamePtr == nil {
+				assert.Nil(t, value[i].NamePtr)
+			} else {
+				assert.NotNil(t, value[i].NamePtr)
+				assert.Equal(t, *each.NamePtr, *value[i].NamePtr)
+			}
+
+			if each.AgePtr == nil {
+				assert.Nil(t, value[i].AgePtr)
+			} else {
+				assert.NotNil(t, value[i].AgePtr)
+				assert.Equal(t, *each.AgePtr, *value[i].AgePtr)
+			}
+		}
+	})
+}
+
+func TestUnmarshalRowsAllNullStructPtrFields(t *testing.T) {
+	expect := []struct {
+		NamePtr *string
+		AgePtr  *int64
+	}{
+		{
+			NamePtr: nil,
+			AgePtr:  nil,
+		},
+		{
+			NamePtr: stringPtr("second"),
+			AgePtr:  int64Ptr(30),
+		},
+		{
+			NamePtr: nil,
+			AgePtr:  nil,
+		},
+	}
+
+	var value []struct {
+		AgePtr  *int64  `db:"age_ptr"`
+		NamePtr *string `db:"name_ptr"`
+	}
+
+	dbtest.RunTest(t, func(db *sql.DB, mock sqlmock.Sqlmock) {
+		rs := sqlmock.NewRows([]string{"name_ptr", "age_ptr"}).
+			AddRow(nil, nil).
+			AddRow("second", 30).
+			AddRow(nil, nil)
+
+		mock.ExpectQuery("select (.+) from users where user=?").
+			WithArgs("anyone").WillReturnRows(rs)
+
+		assert.Nil(t, query(context.Background(), db, func(rows *sql.Rows) error {
+			return unmarshalRows(&value, rows, true)
+		}, "select name_ptr, age_ptr from users where user=?", "anyone"))
+
+		assert.Equal(t, 3, len(value))
+
+		for i, each := range expect {
+			if each.NamePtr == nil {
+				assert.Nil(t, value[i].NamePtr)
+			} else {
+				assert.NotNil(t, value[i].NamePtr)
+				assert.Equal(t, *each.NamePtr, *value[i].NamePtr)
+			}
+
+			if each.AgePtr == nil {
+				assert.Nil(t, value[i].AgePtr)
+			} else {
+				assert.NotNil(t, value[i].AgePtr)
+				assert.Equal(t, *each.AgePtr, *value[i].AgePtr)
+			}
+		}
+	})
+}
+
+func TestUnmarshalRowsWithSqlNullTypes(t *testing.T) {
+	expect := []struct {
+		Name       string
+		NullName   sql.NullString
+		Age        int64
+		NullAge    sql.NullInt64
+		Score      float64
+		NullScore  sql.NullFloat64
+		Active     bool
+		NullActive sql.NullBool
+	}{
+		{
+			Name: "first",
+			NullName: sql.NullString{
+				String: "",
+				Valid:  false,
+			},
+			Age: 20,
+			NullAge: sql.NullInt64{
+				Int64: 0,
+				Valid: false,
+			},
+			Score: 85.5,
+			NullScore: sql.NullFloat64{
+				Float64: 0,
+				Valid:   false,
+			},
+			Active: true,
+			NullActive: sql.NullBool{
+				Bool:  false,
+				Valid: false,
+			},
+		},
+		{
+			Name: "second",
+			NullName: sql.NullString{
+				String: "not_null_name",
+				Valid:  true,
+			},
+			Age: 25,
+			NullAge: sql.NullInt64{
+				Int64: 30,
+				Valid: true,
+			},
+			Score: 90.0,
+			NullScore: sql.NullFloat64{
+				Float64: 95.5,
+				Valid:   true,
+			},
+			Active: false,
+			NullActive: sql.NullBool{
+				Bool:  true,
+				Valid: true,
+			},
+		},
+		{
+			Name: "third",
+			NullName: sql.NullString{
+				String: "",
+				Valid:  false,
+			},
+			Age: 0,
+			NullAge: sql.NullInt64{
+				Int64: 0,
+				Valid: false,
+			},
+			Score: 0,
+			NullScore: sql.NullFloat64{
+				Float64: 0,
+				Valid:   false,
+			},
+			Active: false,
+			NullActive: sql.NullBool{
+				Bool:  false,
+				Valid: false,
+			},
+		},
+	}
+
+	var value []struct {
+		Name       string          `db:"name"`
+		NullName   sql.NullString  `db:"null_name"`
+		Age        int64           `db:"age"`
+		NullAge    sql.NullInt64   `db:"null_age"`
+		Score      float64         `db:"score"`
+		NullScore  sql.NullFloat64 `db:"null_score"`
+		Active     bool            `db:"active"`
+		NullActive sql.NullBool    `db:"null_active"`
+	}
+
+	dbtest.RunTest(t, func(db *sql.DB, mock sqlmock.Sqlmock) {
+		rs := sqlmock.NewRows([]string{
+			"name", "null_name", "age", "null_age", "score", "null_score", "active", "null_active",
+		}).
+			AddRow("first", nil, 20, nil, 85.5, nil, true, nil).
+			AddRow("second", "not_null_name", 25, 30, 90.0, 95.5, false, true).
+			AddRow("third", nil, 0, nil, 0, nil, false, nil)
+
+		mock.ExpectQuery("select (.+) from users where type=?").
+			WithArgs("test").WillReturnRows(rs)
+
+		assert.Nil(t, query(context.Background(), db, func(rows *sql.Rows) error {
+			return unmarshalRows(&value, rows, true)
+		}, "select name, null_name, age, null_age, score, null_score, active, null_active from users where type=?", "test"))
+
+		assert.Equal(t, 3, len(value))
+
+		for i, each := range expect {
+			assert.Equal(t, each.Name, value[i].Name)
+			assert.Equal(t, each.Age, value[i].Age)
+			assert.Equal(t, each.Score, value[i].Score)
+			assert.Equal(t, each.Active, value[i].Active)
+
+			assert.Equal(t, each.NullName.Valid, value[i].NullName.Valid)
+			if each.NullName.Valid {
+				assert.Equal(t, each.NullName.String, value[i].NullName.String)
+			}
+
+			assert.Equal(t, each.NullAge.Valid, value[i].NullAge.Valid)
+			if each.NullAge.Valid {
+				assert.Equal(t, each.NullAge.Int64, value[i].NullAge.Int64)
+			}
+
+			assert.Equal(t, each.NullScore.Valid, value[i].NullScore.Valid)
+			if each.NullScore.Valid {
+				assert.Equal(t, each.NullScore.Float64, value[i].NullScore.Float64)
+			}
+
+			assert.Equal(t, each.NullActive.Valid, value[i].NullActive.Valid)
+			if each.NullActive.Valid {
+				assert.Equal(t, each.NullActive.Bool, value[i].NullActive.Bool)
+			}
+		}
+	})
+}
+
+func TestUnmarshalRowsSqlNullWithMixedData(t *testing.T) {
+	expect := []struct {
+		Name       string
+		NullName   sql.NullString
+		Age        int64
+		NullAge    sql.NullInt64
+		IsStudent  bool
+		NullActive sql.NullBool
+	}{
+		{
+			Name: "student1",
+			NullName: sql.NullString{
+				String: "",
+				Valid:  false,
+			},
+			Age: 18,
+			NullAge: sql.NullInt64{
+				Int64: 0,
+				Valid: false,
+			},
+			IsStudent: true,
+			NullActive: sql.NullBool{
+				Bool:  false,
+				Valid: false,
+			},
+		},
+		{
+			Name: "student2",
+			NullName: sql.NullString{
+				String: "has_nickname",
+				Valid:  true,
+			},
+			Age: 20,
+			NullAge: sql.NullInt64{
+				Int64: 22,
+				Valid: true,
+			},
+			IsStudent: false,
+			NullActive: sql.NullBool{
+				Bool:  true,
+				Valid: true,
+			},
+		},
+	}
+
+	var value []struct {
+		Name       string         `db:"name"`
+		NullName   sql.NullString `db:"null_name"`
+		Age        int64          `db:"age"`
+		NullAge    sql.NullInt64  `db:"null_age"`
+		IsStudent  bool           `db:"is_student"`
+		NullActive sql.NullBool   `db:"null_active"`
+	}
+
+	dbtest.RunTest(t, func(db *sql.DB, mock sqlmock.Sqlmock) {
+		rs := sqlmock.NewRows([]string{"name", "null_name", "age", "null_age", "is_student", "null_active"}).
+			AddRow("student1", nil, 18, nil, true, nil).
+			AddRow("student2", "has_nickname", 20, 22, false, true)
+
+		mock.ExpectQuery("select (.+) from students where class=?").
+			WithArgs("A").WillReturnRows(rs)
+
+		assert.Nil(t, query(context.Background(), db, func(rows *sql.Rows) error {
+			return unmarshalRows(&value, rows, true)
+		}, "select name, null_name, age, null_age, is_student, null_active from students where class=?", "A"))
+
+		assert.Equal(t, 2, len(value))
+
+		for i, each := range expect {
+			assert.Equal(t, each.Name, value[i].Name)
+			assert.Equal(t, each.Age, value[i].Age)
+			assert.Equal(t, each.IsStudent, value[i].IsStudent)
+
+			assert.Equal(t, each.NullName.Valid, value[i].NullName.Valid)
+			if each.NullName.Valid {
+				assert.Equal(t, each.NullName.String, value[i].NullName.String)
+			}
+
+			assert.Equal(t, each.NullAge.Valid, value[i].NullAge.Valid)
+			if each.NullAge.Valid {
+				assert.Equal(t, each.NullAge.Int64, value[i].NullAge.Int64)
+			}
+
+			assert.Equal(t, each.NullActive.Valid, value[i].NullActive.Valid)
+			if each.NullActive.Valid {
+				assert.Equal(t, each.NullActive.Bool, value[i].NullActive.Bool)
+			}
+		}
+	})
+}
+
+func TestUnmarshalRowsSqlNullTime(t *testing.T) {
+	now := time.Now()
+	futureTime := now.AddDate(1, 0, 0)
+
+	expect := []struct {
+		Name      string
+		BirthDate sql.NullTime
+		LastLogin sql.NullTime
+	}{
+		{
+			Name: "user1",
+			BirthDate: sql.NullTime{
+				Time:  time.Time{},
+				Valid: false,
+			},
+			LastLogin: sql.NullTime{
+				Time:  now,
+				Valid: true,
+			},
+		},
+		{
+			Name: "user2",
+			BirthDate: sql.NullTime{
+				Time:  futureTime,
+				Valid: true,
+			},
+			LastLogin: sql.NullTime{
+				Time:  time.Time{},
+				Valid: false,
+			},
+		},
+	}
+
+	var value []struct {
+		Name      string       `db:"name"`
+		BirthDate sql.NullTime `db:"birth_date"`
+		LastLogin sql.NullTime `db:"last_login"`
+	}
+
+	dbtest.RunTest(t, func(db *sql.DB, mock sqlmock.Sqlmock) {
+		rs := sqlmock.NewRows([]string{"name", "birth_date", "last_login"}).
+			AddRow("user1", nil, now).
+			AddRow("user2", futureTime, nil)
+
+		mock.ExpectQuery("select (.+) from users").
+			WillReturnRows(rs)
+
+		assert.Nil(t, query(context.Background(), db, func(rows *sql.Rows) error {
+			return unmarshalRows(&value, rows, true)
+		}, "select name, birth_date, last_login from users"))
+
+		assert.Equal(t, 2, len(value))
+
+		for i, each := range expect {
+			assert.Equal(t, each.Name, value[i].Name)
+
+			assert.Equal(t, each.BirthDate.Valid, value[i].BirthDate.Valid)
+			if each.BirthDate.Valid {
+				assert.WithinDuration(t, each.BirthDate.Time, value[i].BirthDate.Time, time.Second)
+			}
+
+			assert.Equal(t, each.LastLogin.Valid, value[i].LastLogin.Valid)
+			if each.LastLogin.Valid {
+				assert.WithinDuration(t, each.LastLogin.Time, value[i].LastLogin.Time, time.Second)
+			}
+		}
+	})
+}
+
+func TestUnmarshalRowsSqlNullWithEmptyValues(t *testing.T) {
+	expect := []struct {
+		Name       string
+		NullString sql.NullString
+		NullInt    sql.NullInt64
+		NullFloat  sql.NullFloat64
+		NullBool   sql.NullBool
+	}{
+		{
+			Name: "empty_values",
+			NullString: sql.NullString{
+				String: "",
+				Valid:  true,
+			},
+			NullInt: sql.NullInt64{
+				Int64: 0,
+				Valid: true,
+			},
+			NullFloat: sql.NullFloat64{
+				Float64: 0.0,
+				Valid:   true,
+			},
+			NullBool: sql.NullBool{
+				Bool:  false,
+				Valid: true,
+			},
+		},
+		{
+			Name: "null_values",
+			NullString: sql.NullString{
+				String: "",
+				Valid:  false,
+			},
+			NullInt: sql.NullInt64{
+				Int64: 0,
+				Valid: false,
+			},
+			NullFloat: sql.NullFloat64{
+				Float64: 0.0,
+				Valid:   false,
+			},
+			NullBool: sql.NullBool{
+				Bool:  false,
+				Valid: false,
+			},
+		},
+		{
+			Name: "mixed_values",
+			NullString: sql.NullString{
+				String: "actual_value",
+				Valid:  true,
+			},
+			NullInt: sql.NullInt64{
+				Int64: 0,
+				Valid: true,
+			},
+			NullFloat: sql.NullFloat64{
+				Float64: 0.0,
+				Valid:   false,
+			},
+			NullBool: sql.NullBool{
+				Bool:  true,
+				Valid: true,
+			},
+		},
+	}
+
+	var value []struct {
+		Name       string          `db:"name"`
+		NullString sql.NullString  `db:"null_string"`
+		NullInt    sql.NullInt64   `db:"null_int"`
+		NullFloat  sql.NullFloat64 `db:"null_float"`
+		NullBool   sql.NullBool    `db:"null_bool"`
+	}
+
+	dbtest.RunTest(t, func(db *sql.DB, mock sqlmock.Sqlmock) {
+		rs := sqlmock.NewRows([]string{"name", "null_string", "null_int", "null_float", "null_bool"}).
+			AddRow("empty_values", "", 0, 0.0, false).
+			AddRow("null_values", nil, nil, nil, nil).
+			AddRow("mixed_values", "actual_value", 0, nil, true)
+
+		mock.ExpectQuery("select (.+) from test_table").
+			WillReturnRows(rs)
+
+		assert.Nil(t, query(context.Background(), db, func(rows *sql.Rows) error {
+			return unmarshalRows(&value, rows, true)
+		}, "select name, null_string, null_int, null_float, null_bool from test_table"))
+
+		assert.Equal(t, 3, len(value))
+
+		for i, each := range expect {
+
+			assert.Equal(t, each.Name, value[i].Name)
+
+			assert.Equal(t, each.NullString.Valid, value[i].NullString.Valid)
+			if each.NullString.Valid {
+				assert.Equal(t, each.NullString.String, value[i].NullString.String)
+			} else {
+				assert.Equal(t, "", value[i].NullString.String)
+			}
+
+			assert.Equal(t, each.NullInt.Valid, value[i].NullInt.Valid)
+			if each.NullInt.Valid {
+				assert.Equal(t, each.NullInt.Int64, value[i].NullInt.Int64)
+			} else {
+				assert.Equal(t, int64(0), value[i].NullInt.Int64)
+			}
+
+			assert.Equal(t, each.NullFloat.Valid, value[i].NullFloat.Valid)
+			if each.NullFloat.Valid {
+				assert.Equal(t, each.NullFloat.Float64, value[i].NullFloat.Float64)
+			} else {
+				assert.Equal(t, 0.0, value[i].NullFloat.Float64)
+			}
+
+			assert.Equal(t, each.NullBool.Valid, value[i].NullBool.Valid)
+			if each.NullBool.Valid {
+				assert.Equal(t, each.NullBool.Bool, value[i].NullBool.Bool)
+			} else {
+				assert.Equal(t, false, value[i].NullBool.Bool)
+			}
+		}
+	})
+}
+
+func TestUnmarshalRowsSqlNullStringEmptyVsNull(t *testing.T) {
+	expect := []struct {
+		Name         string
+		EmptyString  sql.NullString
+		NullString   sql.NullString
+		NormalString sql.NullString
+	}{
+		{
+			Name: "row1",
+			EmptyString: sql.NullString{
+				String: "",
+				Valid:  true,
+			},
+			NullString: sql.NullString{
+				String: "",
+				Valid:  false,
+			},
+			NormalString: sql.NullString{
+				String: "hello",
+				Valid:  true,
+			},
+		},
+		{
+			Name: "row2",
+			EmptyString: sql.NullString{
+				String: "   ",
+				Valid:  true,
+			},
+			NullString: sql.NullString{
+				String: "",
+				Valid:  false,
+			},
+			NormalString: sql.NullString{
+				String: "",
+				Valid:  true,
+			},
+		},
+	}
+
+	var value []struct {
+		Name         string         `db:"name"`
+		EmptyString  sql.NullString `db:"empty_string"`
+		NullString   sql.NullString `db:"null_string"`
+		NormalString sql.NullString `db:"normal_string"`
+	}
+
+	dbtest.RunTest(t, func(db *sql.DB, mock sqlmock.Sqlmock) {
+		rs := sqlmock.NewRows([]string{"name", "empty_string", "null_string", "normal_string"}).
+			AddRow("row1", "", nil, "hello").
+			AddRow("row2", "   ", nil, "")
+
+		mock.ExpectQuery("select (.+) from string_test").
+			WillReturnRows(rs)
+
+		assert.Nil(t, query(context.Background(), db, func(rows *sql.Rows) error {
+			return unmarshalRows(&value, rows, true)
+		}, "select name, empty_string, null_string, normal_string from string_test"))
+
+		assert.Equal(t, 2, len(value))
+
+		for i, each := range expect {
+			assert.True(t, value[i].EmptyString.Valid)
+			assert.Equal(t, each.EmptyString.String, value[i].EmptyString.String)
+
+			assert.False(t, value[i].NullString.Valid)
+			assert.Equal(t, "", value[i].NullString.String)
+
+			assert.Equal(t, each.NormalString.Valid, value[i].NormalString.Valid)
+			if each.NormalString.Valid {
+				assert.Equal(t, each.NormalString.String, value[i].NormalString.String)
+			}
+		}
+	})
+}
+
+func TestGetValueInterface(t *testing.T) {
+	t.Run("non_pointer_field", func(t *testing.T) {
+		type testStruct struct {
+			Name string
+			Age  int
+		}
+		s := testStruct{}
+		v := reflect.ValueOf(&s).Elem()
+
+		nameField := v.Field(0)
+		result, err := getValueInterface(nameField)
+		assert.NoError(t, err)
+		assert.NotNil(t, result)
+
+		// Should return pointer to the field
+		ptr, ok := result.(*string)
+		assert.True(t, ok)
+		*ptr = "test"
+		assert.Equal(t, "test", s.Name)
+	})
+
+	t.Run("pointer_field_nil", func(t *testing.T) {
+		type testStruct struct {
+			NamePtr *string
+			AgePtr  *int64
+		}
+		s := testStruct{}
+		v := reflect.ValueOf(&s).Elem()
+
+		// Test with nil pointer field
+		namePtrField := v.Field(0)
+		assert.True(t, namePtrField.IsNil(), "initial pointer should be nil")
+
+		result, err := getValueInterface(namePtrField)
+		assert.NoError(t, err)
+		assert.NotNil(t, result)
+
+		// Should have allocated the pointer
+		assert.False(t, namePtrField.IsNil(), "pointer should be allocated after getValueInterface")
+
+		// Should return pointer to pointer field
+		ptrPtr, ok := result.(**string)
+		assert.True(t, ok)
+		testValue := "initialized"
+		*ptrPtr = &testValue
+		assert.NotNil(t, s.NamePtr)
+		assert.Equal(t, "initialized", *s.NamePtr)
+	})
+
+	t.Run("pointer_field_already_allocated", func(t *testing.T) {
+		type testStruct struct {
+			NamePtr *string
+		}
+		initial := "existing"
+		s := testStruct{NamePtr: &initial}
+		v := reflect.ValueOf(&s).Elem()
+
+		namePtrField := v.Field(0)
+		assert.False(t, namePtrField.IsNil(), "pointer should not be nil initially")
+
+		result, err := getValueInterface(namePtrField)
+		assert.NoError(t, err)
+		assert.NotNil(t, result)
+
+		// Should return pointer to pointer field
+		ptrPtr, ok := result.(**string)
+		assert.True(t, ok)
+
+		// Verify it points to the existing value
+		assert.Equal(t, "existing", **ptrPtr)
+
+		// Modify through the returned pointer
+		newValue := "modified"
+		*ptrPtr = &newValue
+		assert.Equal(t, "modified", *s.NamePtr)
+	})
+
+	t.Run("pointer_field_zero_value", func(t *testing.T) {
+		type testStruct struct {
+			IntPtr *int
+		}
+		s := testStruct{}
+		v := reflect.ValueOf(&s).Elem()
+
+		intPtrField := v.Field(0)
+		result, err := getValueInterface(intPtrField)
+		assert.NoError(t, err)
+
+		// After calling getValueInterface, nil pointer should be allocated
+		assert.NotNil(t, s.IntPtr)
+
+		// Set zero value through returned interface
+		ptrPtr, ok := result.(**int)
+		assert.True(t, ok)
+		zero := 0
+		*ptrPtr = &zero
+		assert.Equal(t, 0, *s.IntPtr)
+	})
+
+	t.Run("not_addressable_value", func(t *testing.T) {
+		type testStruct struct {
+			Name string
+		}
+		s := testStruct{Name: "test"}
+		v := reflect.ValueOf(s) // Non-pointer, not addressable
+
+		nameField := v.Field(0)
+		result, err := getValueInterface(nameField)
+		assert.Error(t, err)
+		assert.Equal(t, ErrNotReadableValue, err)
+		assert.Nil(t, result)
+	})
+
+	t.Run("multiple_pointer_types", func(t *testing.T) {
+		type testStruct struct {
+			StringPtr *string
+			IntPtr    *int
+			Int64Ptr  *int64
+			FloatPtr  *float64
+			BoolPtr   *bool
+		}
+		s := testStruct{}
+		v := reflect.ValueOf(&s).Elem()
+
+		// Test each pointer type gets properly initialized
+		for i := 0; i < v.NumField(); i++ {
+			field := v.Field(i)
+			assert.True(t, field.IsNil(), "field %d should start as nil", i)
+
+			result, err := getValueInterface(field)
+			assert.NoError(t, err, "field %d should not error", i)
+			assert.NotNil(t, result, "field %d result should not be nil", i)
+
+			// After getValueInterface, pointer should be allocated
+			assert.False(t, field.IsNil(), "field %d should be allocated", i)
+		}
+	})
+}
+
+func stringPtr(s string) *string {
+	return &s
+}
+
+func int64Ptr(i int64) *int64 {
+	return &i
+}
+
 func BenchmarkIgnore(b *testing.B) {
 	db, mock, err := sqlmock.New()
 	if err != nil {

core/threading/routinegroup_test.go

@@ -1,13 +1,12 @@
 package threading
 
 import (
-	"io"
-	"log"
 	"sync"
 	"sync/atomic"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/zeromicro/go-zero/core/logx/logtest"
 )
 
 func TestRoutineGroupRun(t *testing.T) {
@@ -25,7 +24,7 @@ func TestRoutineGroupRun(t *testing.T) {
 }
 
 func TestRoutingGroupRunSafe(t *testing.T) {
-	log.SetOutput(io.Discard)
+	logtest.Discard(t)
 
 	var count int32
 	group := NewRoutineGroup()

core/threading/routines_test.go

@@ -3,13 +3,12 @@ package threading
 import (
 	"bytes"
 	"context"
-	"io"
-	"log"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/zeromicro/go-zero/core/lang"
 	"github.com/zeromicro/go-zero/core/logx"
+	"github.com/zeromicro/go-zero/core/logx/logtest"
 )
 
 func TestRoutineId(t *testing.T) {
@@ -17,7 +16,7 @@ func TestRoutineId(t *testing.T) {
 }
 
 func TestRunSafe(t *testing.T) {
-	log.SetOutput(io.Discard)
+	logtest.Discard(t)
 
 	i := 0
 

core/trace/agent.go

@@ -3,14 +3,11 @@ package trace
 import (
 	"context"
 	"fmt"
-	"net/url"
 	"os"
 	"sync"
 
-	"github.com/zeromicro/go-zero/core/lang"
 	"github.com/zeromicro/go-zero/core/logx"
 	"go.opentelemetry.io/otel"
-	"go.opentelemetry.io/otel/exporters/jaeger"
 	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
 	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
 	"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
@@ -21,63 +18,47 @@ import (
 )
 
 const (
-	kindJaeger   = "jaeger"
 	kindZipkin   = "zipkin"
 	kindOtlpGrpc = "otlpgrpc"
 	kindOtlpHttp = "otlphttp"
 	kindFile     = "file"
-	protocolUdp  = "udp"
 )
 
 var (
-	agents = make(map[string]lang.PlaceholderType)
+	once           sync.Once
-	lock   sync.Mutex
+	tp             *sdktrace.TracerProvider
-	tp     *sdktrace.TracerProvider
+	shutdownOnceFn = sync.OnceFunc(func() {
+		if tp != nil {
+			_ = tp.Shutdown(context.Background())
+		}
+	})
 )
 
 // StartAgent starts an opentelemetry agent.
+// It uses sync.Once to ensure the agent is initialized only once,
+// similar to prometheus.StartAgent and logx.SetUp.
+// This prevents multiple ServiceConf.SetUp() calls from reinitializing
+// the global tracer provider when running multiple servers (e.g., REST + RPC)
+// in the same process.
 func StartAgent(c Config) {
 	if c.Disabled {
 		return
 	}
 
-	lock.Lock()
+	once.Do(func() {
-	defer lock.Unlock()
+		if err := startAgent(c); err != nil {
-
+			logx.Error(err)
-	_, ok := agents[c.Endpoint]
+		}
-	if ok {
+	})
-		return
-	}
-
-	// if error happens, let later calls run.
-	if err := startAgent(c); err != nil {
-		return
-	}
-
-	agents[c.Endpoint] = lang.Placeholder
 }
 
 // StopAgent shuts down the span processors in the order they were registered.
 func StopAgent() {
-	lock.Lock()
+	shutdownOnceFn()
-	defer lock.Unlock()
-
-	if tp != nil {
-		_ = tp.Shutdown(context.Background())
-		tp = nil
-	}
 }
 
 func createExporter(c Config) (sdktrace.SpanExporter, error) {
-	// Just support jaeger and zipkin now, more for later
 	switch c.Batcher {
-	case kindJaeger:
-		u, err := url.Parse(c.Endpoint)
-		if err == nil && u.Scheme == protocolUdp {
-			return jaeger.New(jaeger.WithAgentEndpoint(jaeger.WithAgentHost(u.Hostname()),
-				jaeger.WithAgentPort(u.Port())))
-		}
-		return jaeger.New(jaeger.WithCollectorEndpoint(jaeger.WithEndpoint(c.Endpoint)))
 	case kindZipkin:
 		return zipkin.New(c.Endpoint)
 	case kindOtlpGrpc:

core/trace/agent_test.go

@@ -1,10 +1,13 @@
 package trace
 
 import (
+	"context"
+	"errors"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/zeromicro/go-zero/core/logx"
+	"go.opentelemetry.io/otel"
 )
 
 func TestStartAgent(t *testing.T) {
@@ -24,21 +27,16 @@ func TestStartAgent(t *testing.T) {
 		Name: "foo",
 	}
 	c2 := Config{
-		Name:     "bar",
-		Endpoint: endpoint1,
-		Batcher:  kindJaeger,
-	}
-	c3 := Config{
 		Name:     "any",
 		Endpoint: endpoint2,
 		Batcher:  kindZipkin,
 	}
-	c4 := Config{
+	c3 := Config{
 		Name:     "bla",
 		Endpoint: endpoint3,
 		Batcher:  "otlp",
 	}
-	c5 := Config{
+	c4 := Config{
 		Name:     "otlpgrpc",
 		Endpoint: endpoint3,
 		Batcher:  kindOtlpGrpc,
@@ -46,7 +44,7 @@ func TestStartAgent(t *testing.T) {
 			"uptrace-dsn": "http://project2_secret_token@localhost:14317/2",
 		},
 	}
-	c6 := Config{
+	c5 := Config{
 		Name:     "otlphttp",
 		Endpoint: endpoint4,
 		Batcher:  kindOtlpHttp,
@@ -55,22 +53,12 @@ func TestStartAgent(t *testing.T) {
 		},
 		OtlpHttpPath: "/v1/traces",
 	}
-	c7 := Config{
+	c6 := Config{
-		Name:     "UDP",
-		Endpoint: endpoint5,
-		Batcher:  kindJaeger,
-	}
-	c8 := Config{
-		Disabled: true,
-		Endpoint: endpoint6,
-		Batcher:  kindJaeger,
-	}
-	c9 := Config{
 		Name:     "file",
 		Endpoint: endpoint71,
 		Batcher:  kindFile,
 	}
-	c10 := Config{
+	c7 := Config{
 		Name:     "file",
 		Endpoint: endpoint72,
 		Batcher:  kindFile,
@@ -84,28 +72,289 @@ func TestStartAgent(t *testing.T) {
 	StartAgent(c5)
 	StartAgent(c6)
 	StartAgent(c7)
-	StartAgent(c8)
-	StartAgent(c9)
-	StartAgent(c10)
 	defer StopAgent()
 
-	lock.Lock()
+	// With sync.Once, only the first non-disabled config (c1) takes effect.
-	defer lock.Unlock()
+	// Subsequent calls are ignored, which is the desired behavior to prevent
-
+	// multiple servers (REST + RPC) from reinitializing the global tracer.
-	// because remotehost cannot be resolved
+	assert.NotNil(t, tp)
-	assert.Equal(t, 6, len(agents))
+}
-	_, ok := agents[""]
+
-	assert.True(t, ok)
+func TestCreateExporter_InvalidFilePath(t *testing.T) {
-	_, ok = agents[endpoint1]
+	logx.Disable()
-	assert.True(t, ok)
+
-	_, ok = agents[endpoint2]
+	c := Config{
-	assert.False(t, ok)
+		Name:     "test-invalid-file",
-	_, ok = agents[endpoint5]
+		Endpoint: "/non-existent-directory/trace.log",
-	assert.True(t, ok)
+		Batcher:  kindFile,
-	_, ok = agents[endpoint6]
+	}
-	assert.False(t, ok)
+
-	_, ok = agents[endpoint71]
+	_, err := createExporter(c)
-	assert.True(t, ok)
+	assert.Error(t, err)
-	_, ok = agents[endpoint72]
+	assert.Contains(t, err.Error(), "file exporter endpoint error")
-	assert.False(t, ok)
+}
+
+func TestCreateExporter_UnknownBatcher(t *testing.T) {
+	logx.Disable()
+
+	c := Config{
+		Name:     "test-unknown",
+		Endpoint: "localhost:1234",
+		Batcher:  "unknown-batcher-type",
+	}
+
+	_, err := createExporter(c)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "unknown exporter")
+}
+
+func TestCreateExporter_ValidExporters(t *testing.T) {
+	logx.Disable()
+
+	tests := []struct {
+		name    string
+		config  Config
+		wantErr bool
+		errMsg  string
+	}{
+		{
+			name: "valid file exporter",
+			config: Config{
+				Name:     "file-test",
+				Endpoint: "/tmp/trace-test.log",
+				Batcher:  kindFile,
+			},
+			wantErr: false,
+		},
+		{
+			name: "invalid file path",
+			config: Config{
+				Name:     "file-test-invalid",
+				Endpoint: "/invalid-path/that/does/not/exist/trace.log",
+				Batcher:  kindFile,
+			},
+			wantErr: true,
+			errMsg:  "file exporter endpoint error",
+		},
+		{
+			name: "unknown batcher",
+			config: Config{
+				Name:     "unknown-test",
+				Endpoint: "localhost:1234",
+				Batcher:  "invalid-batcher",
+			},
+			wantErr: true,
+			errMsg:  "unknown exporter",
+		},
+		{
+			name: "zipkin",
+			config: Config{
+				Name:     "zipkin",
+				Endpoint: "http://localhost:9411/api/v2/spans",
+				Batcher:  kindZipkin,
+			},
+			wantErr: false,
+		},
+		{
+			name: "otlpgrpc",
+			config: Config{
+				Name:     "otlpgrpc",
+				Endpoint: "localhost:4317",
+				Batcher:  kindOtlpGrpc,
+			},
+			wantErr: false,
+		},
+		{
+			name: "otlpgrpc with headers",
+			config: Config{
+				Name:     "otlpgrpc-headers",
+				Endpoint: "localhost:4317",
+				Batcher:  kindOtlpGrpc,
+				OtlpHeaders: map[string]string{
+					"authorization": "Bearer token123",
+					"x-custom-key":  "custom-value",
+				},
+			},
+			wantErr: false,
+		},
+		{
+			name: "otlphttp",
+			config: Config{
+				Name:     "otlphttp",
+				Endpoint: "localhost:4318",
+				Batcher:  kindOtlpHttp,
+			},
+			wantErr: false,
+		},
+		{
+			name: "otlphttp with headers",
+			config: Config{
+				Name:     "otlphttp-headers",
+				Endpoint: "localhost:4318",
+				Batcher:  kindOtlpHttp,
+				OtlpHeaders: map[string]string{
+					"authorization": "Bearer token456",
+					"x-api-key":     "api-key-value",
+				},
+			},
+			wantErr: false,
+		},
+		{
+			name: "otlphttp with headers and path",
+			config: Config{
+				Name:         "otlphttp-headers-path",
+				Endpoint:     "localhost:4318",
+				Batcher:      kindOtlpHttp,
+				OtlpHttpPath: "/v1/traces",
+				OtlpHeaders: map[string]string{
+					"authorization":  "Bearer token789",
+					"x-custom-trace": "trace-id",
+				},
+			},
+			wantErr: false,
+		},
+		{
+			name: "otlphttp with secure connection",
+			config: Config{
+				Name:           "otlphttp-secure",
+				Endpoint:       "localhost:4318",
+				Batcher:        kindOtlpHttp,
+				OtlpHttpSecure: true,
+				OtlpHeaders: map[string]string{
+					"authorization": "Bearer secure-token",
+				},
+			},
+			wantErr: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			exporter, err := createExporter(tt.config)
+			if tt.wantErr {
+				assert.Error(t, err)
+				if tt.errMsg != "" {
+					assert.Contains(t, err.Error(), tt.errMsg)
+				}
+				assert.Nil(t, exporter)
+			} else {
+				assert.NoError(t, err)
+				assert.NotNil(t, exporter)
+				// Clean up the exporter
+				if exporter != nil {
+					_ = exporter.Shutdown(context.Background())
+				}
+			}
+		})
+	}
+}
+
+func TestStopAgent(t *testing.T) {
+	logx.Disable()
+
+	// StopAgent should be idempotent and safe to call multiple times
+	assert.NotPanics(t, func() {
+		StopAgent()
+		StopAgent()
+		StopAgent()
+	})
+}
+
+func TestStartAgent_WithEndpoint(t *testing.T) {
+	logx.Disable()
+
+	tests := []struct {
+		name    string
+		config  Config
+		wantErr bool
+	}{
+		{
+			name: "empty endpoint - no exporter created",
+			config: Config{
+				Name:    "test-no-endpoint",
+				Sampler: 1.0,
+			},
+			wantErr: false,
+		},
+		{
+			name: "valid endpoint with file exporter",
+			config: Config{
+				Name:     "test-with-endpoint",
+				Endpoint: "/tmp/test-trace.log",
+				Batcher:  kindFile,
+				Sampler:  1.0,
+			},
+			wantErr: false,
+		},
+		{
+			name: "endpoint with invalid exporter type",
+			config: Config{
+				Name:     "test-invalid-batcher",
+				Endpoint: "localhost:1234",
+				Batcher:  "invalid-type",
+				Sampler:  1.0,
+			},
+			wantErr: true,
+		},
+		{
+			name: "endpoint with invalid file path",
+			config: Config{
+				Name:     "test-invalid-path",
+				Endpoint: "/non/existent/path/trace.log",
+				Batcher:  kindFile,
+				Sampler:  1.0,
+			},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Reset tp for each test
+			originalTp := tp
+			tp = nil
+			defer func() {
+				if tp != nil {
+					_ = tp.Shutdown(context.Background())
+				}
+				tp = originalTp
+			}()
+
+			err := startAgent(tt.config)
+			if tt.wantErr {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+				assert.NotNil(t, tp, "TracerProvider should be created")
+			}
+		})
+	}
+}
+
+func TestStartAgent_ErrorHandler(t *testing.T) {
+	// Setup a tracer provider to test error handler
+	originalTp := tp
+	tp = nil
+	defer func() {
+		if tp != nil {
+			_ = tp.Shutdown(context.Background())
+		}
+		tp = originalTp
+	}()
+
+	// Call startAgent to set up the error handler
+	config := Config{
+		Name:    "test-error-handler",
+		Sampler: 1.0,
+	}
+	err := startAgent(config)
+	assert.NoError(t, err)
+	assert.NotNil(t, tp)
+
+	// Verify the error handler was set and can be called without panicking
+	// We test this by calling otel.Handle which will invoke the registered error handler
+	testErr := errors.New("test otel error")
+	assert.NotPanics(t, func() {
+		otel.Handle(testErr)
+	}, "Error handler should handle errors without panicking")
 }

core/trace/config.go

@@ -8,7 +8,7 @@ type Config struct {
 	Name     string  `json:",optional"`
 	Endpoint string  `json:",optional"`
 	Sampler  float64 `json:",default=1.0"`
-	Batcher  string  `json:",default=jaeger,options=jaeger|zipkin|otlpgrpc|otlphttp|file"`
+	Batcher  string  `json:",default=otlpgrpc,options=zipkin|otlpgrpc|otlphttp|file"`
 	// OtlpHeaders represents the headers for OTLP gRPC or HTTP transport.
 	// For example:
 	//  uptrace-dsn: 'http://project2_secret_token@localhost:14317/2'

gateway/internal/headerprocessor.go

@@ -11,16 +11,40 @@ const (
 	metadataPrefix       = "gateway-"
 )
 
+// OpenTelemetry trace propagation headers that need to be forwarded to gRPC metadata.
+// These headers are used by the W3C Trace Context standard for distributed tracing.
+var traceHeaders = map[string]bool{
+	"traceparent": true,
+	"tracestate":  true,
+	"baggage":     true,
+}
+
 // ProcessHeaders builds the headers for the gateway from HTTP headers.
+// It forwards both custom metadata headers (with Grpc-Metadata- prefix)
+// and OpenTelemetry trace propagation headers (traceparent, tracestate, baggage)
+// to ensure distributed tracing works correctly across the gateway.
 func ProcessHeaders(header http.Header) []string {
 	var headers []string
 
 	for k, v := range header {
+		// Forward OpenTelemetry trace propagation headers
+		// These must be lowercase per gRPC metadata conventions
+		if lowerKey := strings.ToLower(k); traceHeaders[lowerKey] {
+			for _, vv := range v {
+				headers = append(headers, lowerKey+":"+vv)
+			}
+			continue
+		}
+
+		// Forward custom metadata headers with Grpc-Metadata- prefix
 		if !strings.HasPrefix(k, metadataHeaderPrefix) {
 			continue
 		}
 
-		key := fmt.Sprintf("%s%s", metadataPrefix, strings.TrimPrefix(k, metadataHeaderPrefix))
+		// gRPC metadata keys are case-insensitive and stored as lowercase,
+		// so we lowercase the key to match gRPC conventions
+		trimmedKey := strings.TrimPrefix(k, metadataHeaderPrefix)
+		key := strings.ToLower(fmt.Sprintf("%s%s", metadataPrefix, trimmedKey))
 		for _, vv := range v {
 			headers = append(headers, key+":"+vv)
 		}

gateway/internal/headerprocessor_test.go

@@ -18,5 +18,93 @@ func TestBuildHeadersWithValues(t *testing.T) {
 	req := httptest.NewRequest("GET", "/", http.NoBody)
 	req.Header.Add("grpc-metadata-a", "b")
 	req.Header.Add("grpc-metadata-b", "b")
-	assert.ElementsMatch(t, []string{"gateway-A:b", "gateway-B:b"}, ProcessHeaders(req.Header))
+	assert.ElementsMatch(t, []string{"gateway-a:b", "gateway-b:b"}, ProcessHeaders(req.Header))
+}
+
+func TestProcessHeadersWithTraceContext(t *testing.T) {
+	req := httptest.NewRequest("GET", "/", http.NoBody)
+	req.Header.Set("traceparent", "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
+	req.Header.Set("tracestate", "key1=value1,key2=value2")
+	req.Header.Set("baggage", "userId=alice,serverNode=DF:28")
+
+	headers := ProcessHeaders(req.Header)
+
+	assert.Len(t, headers, 3)
+	assert.Contains(t, headers, "traceparent:00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
+	assert.Contains(t, headers, "tracestate:key1=value1,key2=value2")
+	assert.Contains(t, headers, "baggage:userId=alice,serverNode=DF:28")
+}
+
+func TestProcessHeadersWithMixedHeaders(t *testing.T) {
+	req := httptest.NewRequest("GET", "/", http.NoBody)
+	req.Header.Set("traceparent", "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
+	req.Header.Set("grpc-metadata-custom", "value1")
+	req.Header.Set("content-type", "application/json")
+	req.Header.Set("tracestate", "key1=value1")
+
+	headers := ProcessHeaders(req.Header)
+
+	// Should include trace headers and grpc-metadata headers, but not regular headers
+	assert.Len(t, headers, 3)
+	assert.Contains(t, headers, "traceparent:00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
+	assert.Contains(t, headers, "tracestate:key1=value1")
+	assert.Contains(t, headers, "gateway-custom:value1")
+}
+
+func TestProcessHeadersTraceparentCaseInsensitive(t *testing.T) {
+	tests := []struct {
+		name        string
+		headerKey   string
+		headerVal   string
+		expectedKey string
+	}{
+		{
+			name:        "lowercase traceparent",
+			headerKey:   "traceparent",
+			headerVal:   "00-trace-span-01",
+			expectedKey: "traceparent",
+		},
+		{
+			name:        "uppercase Traceparent",
+			headerKey:   "Traceparent",
+			headerVal:   "00-trace-span-01",
+			expectedKey: "traceparent",
+		},
+		{
+			name:        "mixed case TraceParent",
+			headerKey:   "TraceParent",
+			headerVal:   "00-trace-span-01",
+			expectedKey: "traceparent",
+		},
+		{
+			name:        "lowercase tracestate",
+			headerKey:   "tracestate",
+			headerVal:   "key=value",
+			expectedKey: "tracestate",
+		},
+		{
+			name:        "mixed case TraceState",
+			headerKey:   "TraceState",
+			headerVal:   "key=value",
+			expectedKey: "tracestate",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest("GET", "/", http.NoBody)
+			req.Header.Set(tt.headerKey, tt.headerVal)
+
+			headers := ProcessHeaders(req.Header)
+
+			assert.Len(t, headers, 1)
+			assert.Contains(t, headers, tt.expectedKey+":"+tt.headerVal)
+		})
+	}
+}
+
+func TestProcessHeadersEmptyHeaders(t *testing.T) {
+	req := httptest.NewRequest("GET", "/", http.NoBody)
+	headers := ProcessHeaders(req.Header)
+	assert.Empty(t, headers)
 }

gateway/server.go

@@ -329,8 +329,9 @@ func createDescriptorSource(cli zrpc.Client, up Upstream) (grpcurl.DescriptorSou
 	return source, nil
 }
 
-// withDialer sets a dialer to create a gRPC client.
+// WithDialer sets a dialer to create a gRPC client.
-func withDialer(dialer func(conf zrpc.RpcClientConf) zrpc.Client) func(*Server) {
+// This allows customization of gRPC client options, such as message size limits.
+func WithDialer(dialer func(conf zrpc.RpcClientConf) zrpc.Client) func(*Server) {
 	return func(s *Server) {
 		s.dialer = dialer
 	}

gateway/server_test.go

@@ -54,7 +54,7 @@ func TestMustNewServer(t *testing.T) {
 	c.Host = "localhost"
 	c.Port = 18881
 
-	s := MustNewServer(c, withDialer(func(conf zrpc.RpcClientConf) zrpc.Client {
+	s := MustNewServer(c, WithDialer(func(conf zrpc.RpcClientConf) zrpc.Client {
 		return zrpc.MustNewClient(conf, zrpc.WithDialOption(grpc.WithContextDialer(dialer())))
 	}), WithHeaderProcessor(func(header http.Header) []string {
 		return []string{"foo"}

go.mod

@@ -1,29 +1,29 @@
 module github.com/zeromicro/go-zero
 
-go 1.21
+go 1.23.0
 
 require (
 	github.com/DATA-DOG/go-sqlmock v1.5.2
-	github.com/alicebob/miniredis/v2 v2.35.0
+	github.com/alicebob/miniredis/v2 v2.36.1
 	github.com/fatih/color v1.18.0
 	github.com/fullstorydev/grpcurl v1.9.3
-	github.com/go-sql-driver/mysql v1.9.0
+	github.com/go-sql-driver/mysql v1.9.3
 	github.com/golang-jwt/jwt/v4 v4.5.2
 	github.com/golang/protobuf v1.5.4
 	github.com/google/uuid v1.6.0
 	github.com/grafana/pyroscope-go v1.2.7
 	github.com/jackc/pgx/v5 v5.7.4
 	github.com/jhump/protoreflect v1.17.0
-	github.com/pelletier/go-toml/v2 v2.2.2
+	github.com/modelcontextprotocol/go-sdk v1.2.0
-	github.com/prometheus/client_golang v1.21.1
+	github.com/pelletier/go-toml/v2 v2.2.4
-	github.com/redis/go-redis/v9 v9.15.0
+	github.com/prometheus/client_golang v1.23.2
+	github.com/redis/go-redis/v9 v9.17.3
 	github.com/spaolacci/murmur3 v1.1.0
 	github.com/stretchr/testify v1.11.1
 	go.etcd.io/etcd/api/v3 v3.5.15
 	go.etcd.io/etcd/client/v3 v3.5.15
-	go.mongodb.org/mongo-driver/v2 v2.3.0
+	go.mongodb.org/mongo-driver/v2 v2.5.0
 	go.opentelemetry.io/otel v1.24.0
-	go.opentelemetry.io/otel/exporters/jaeger v1.17.0
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.24.0
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.24.0
 	go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.24.0
@@ -32,20 +32,20 @@ require (
 	go.opentelemetry.io/otel/trace v1.24.0
 	go.uber.org/automaxprocs v1.6.0
 	go.uber.org/goleak v1.3.0
-	go.uber.org/mock v0.4.0
+	go.uber.org/mock v0.6.0
-	golang.org/x/net v0.35.0
+	golang.org/x/net v0.43.0
-	golang.org/x/sys v0.30.0
+	golang.org/x/sys v0.35.0
 	golang.org/x/time v0.10.0
 	google.golang.org/genproto/googleapis/api v0.0.0-20240711142825-46eb208f015d
 	google.golang.org/grpc v1.65.0
-	google.golang.org/protobuf v1.36.5
+	google.golang.org/protobuf v1.36.11
 	gopkg.in/cheggaaa/pb.v1 v1.0.28
 	gopkg.in/h2non/gock.v1 v1.1.2
 	gopkg.in/yaml.v2 v2.4.0
 	k8s.io/api v0.29.3
 	k8s.io/apimachinery v0.29.4
 	k8s.io/client-go v0.29.3
-	k8s.io/utils v0.0.0-20240711033017-18e509b52bc8
+	k8s.io/utils v0.0.0-20251222233032-718f0e51e6d2
 )
 
 require (
@@ -68,10 +68,10 @@ require (
 	github.com/go-openapi/jsonreference v0.20.2 // indirect
 	github.com/go-openapi/swag v0.22.4 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/golang/snappy v1.0.0 // indirect
 	github.com/google/gnostic-models v0.6.8 // indirect
-	github.com/google/go-cmp v0.6.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
+	github.com/google/jsonschema-go v0.3.0 // indirect
 	github.com/grafana/pyroscope-go/godeltaprof v0.1.9 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.20.0 // indirect
 	github.com/h2non/parth v0.0.0-20190131123155-b4df798d6542 // indirect
@@ -80,7 +80,7 @@ require (
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/klauspost/compress v1.17.11 // indirect
+	github.com/klauspost/compress v1.18.0 // indirect
 	github.com/kylelemons/godebug v1.1.0 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
@@ -91,14 +91,15 @@ require (
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/openzipkin/zipkin-go v0.4.3 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/prometheus/client_model v0.6.1 // indirect
+	github.com/prometheus/client_model v0.6.2 // indirect
-	github.com/prometheus/common v0.62.0 // indirect
+	github.com/prometheus/common v0.66.1 // indirect
-	github.com/prometheus/procfs v0.15.1 // indirect
+	github.com/prometheus/procfs v0.16.1 // indirect
 	github.com/rivo/uniseg v0.2.0 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
-	github.com/xdg-go/scram v1.1.2 // indirect
+	github.com/xdg-go/scram v1.2.0 // indirect
 	github.com/xdg-go/stringprep v1.0.4 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
 	github.com/yuin/gopher-lua v1.1.1 // indirect
 	go.etcd.io/etcd/client/pkg/v3 v3.5.15 // indirect
@@ -108,11 +109,12 @@ require (
 	go.uber.org/atomic v1.10.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
 	go.uber.org/zap v1.24.0 // indirect
-	golang.org/x/crypto v0.33.0 // indirect
+	go.yaml.in/yaml/v2 v2.4.2 // indirect
-	golang.org/x/oauth2 v0.24.0 // indirect
+	golang.org/x/crypto v0.41.0 // indirect
-	golang.org/x/sync v0.11.0 // indirect
+	golang.org/x/oauth2 v0.30.0 // indirect
-	golang.org/x/term v0.29.0 // indirect
+	golang.org/x/sync v0.16.0 // indirect
-	golang.org/x/text v0.22.0 // indirect
+	golang.org/x/term v0.34.0 // indirect
+	golang.org/x/text v0.28.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240701130421-f6361c86f094 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

go.sum

@@ -2,8 +2,8 @@ filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
 filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
 github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
 github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
-github.com/alicebob/miniredis/v2 v2.35.0 h1:QwLphYqCEAo1eu1TqPRN2jgVMPBweeQcR21jeqDCONI=
+github.com/alicebob/miniredis/v2 v2.36.1 h1:Dvc5oAnNOr7BIfPn7tF269U8DvRW1dBG2D5n0WrfYMI=
-github.com/alicebob/miniredis/v2 v2.35.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM=
+github.com/alicebob/miniredis/v2 v2.36.1/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM=
 github.com/benbjohnson/clock v1.1.0 h1:Q92kusRqC1XV2MjkWETPvjJVqKetz1OzxZB7mHJLju8=
 github.com/benbjohnson/clock v1.1.0/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
@@ -53,8 +53,8 @@ github.com/go-openapi/jsonreference v0.20.2/go.mod h1:Bl1zwGIM8/wsvqjsOQLJ/SH+En
 github.com/go-openapi/swag v0.22.3/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14=
 github.com/go-openapi/swag v0.22.4 h1:QLMzNJnMGPRNDCbySlcj1x01tzU8/9LTTL9hZZZogBU=
 github.com/go-openapi/swag v0.22.4/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14=
-github.com/go-sql-driver/mysql v1.9.0 h1:Y0zIbQXhQKmQgTp44Y1dp3wTXcn804QoTptLZT1vtvo=
+github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo=
-github.com/go-sql-driver/mysql v1.9.0/go.mod h1:pDetrLJeA3oMujJuvXc8RJoasr589B6A9fwzD3QMrqw=
+github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
 github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 h1:tfuBGBXKqDEevZMzYi5KSi8KkcZtzBcTgAUUtapy0OI=
 github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572/go.mod h1:9Pwr4B2jHnOSGXyyzV8ROjYa2ojvAY6HCGYYfMoC3Ls=
 github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
@@ -62,18 +62,20 @@ github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
 github.com/golang-jwt/jwt/v4 v4.5.2 h1:YtQM7lnr8iZ+j5q71MGKkNw9Mn7AjHM68uc9g5fXeUI=
 github.com/golang-jwt/jwt/v4 v4.5.2/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
+github.com/golang-jwt/jwt/v5 v5.2.2 h1:Rl4B7itRWVtYIHFrSNd7vhTiz9UpLdi6gZhZ3wEeDy8=
+github.com/golang-jwt/jwt/v5 v5.2.2/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
 github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
-github.com/golang/snappy v1.0.0 h1:Oy607GVXHs7RtbggtPBnr2RmDArIsAefDwvrdWvRhGs=
-github.com/golang/snappy v1.0.0/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
 github.com/google/gnostic-models v0.6.8 h1:yo/ABAfM5IMRsS1VnXjTBvUb61tFIHozhlYvRgGre9I=
 github.com/google/gnostic-models v0.6.8/go.mod h1:5n7qKqH0f5wFt+aWF8CW6pZLLNOfYuF5OpfBSENuI8U=
 github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/gofuzz v1.2.0 h1:xRy4A+RhZaiKjJ1bPfwQ8sedCA+YS2YcCHW6ec7JMi0=
 github.com/google/gofuzz v1.2.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/jsonschema-go v0.3.0 h1:6AH2TxVNtk3IlvkkhjrtbUc4S8AvO0Xii0DxIygDg+Q=
+github.com/google/jsonschema-go v0.3.0/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/pprof v0.0.0-20210720184732-4bb14d4b1be1 h1:K6RDEckDVWvDI9JAJYCmNdQXq6neHJOYx3V6jnqNEec=
 github.com/google/pprof v0.0.0-20210720184732-4bb14d4b1be1/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -103,8 +105,8 @@ github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHm
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
 github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
 github.com/kisielk/sqlstruct v0.0.0-20201105191214-5f3e10d3ab46/go.mod h1:yyMNCyc/Ib3bDTKd379tNMpB/7/H5TjM2Y9QJ5THLbE=
-github.com/klauspost/compress v1.17.11 h1:In6xLpyWOi1+C7tXUUWv2ot1QvBjxevKAaI6IXrJmUc=
+github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
-github.com/klauspost/compress v1.17.11/go.mod h1:pMDklpSncoRMuLFrf1W9Ss9KT+0rH90U12bZKk7uwG0=
+github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
 github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
@@ -123,6 +125,8 @@ github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWE
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-runewidth v0.0.15 h1:UNAjwbU9l54TA3KzvqLGxwWjHmMgBUVhBiTjelZgg3U=
 github.com/mattn/go-runewidth v0.0.15/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/modelcontextprotocol/go-sdk v1.2.0 h1:Y23co09300CEk8iZ/tMxIX1dVmKZkzoSBZOpJwUnc/s=
+github.com/modelcontextprotocol/go-sdk v1.2.0/go.mod h1:6fM3LCm3yV7pAs8isnKLn07oKtB0MP9LHd3DfAcKw10=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
@@ -138,24 +142,24 @@ github.com/onsi/gomega v1.29.0 h1:KIA/t2t5UBzoirT4H9tsML45GEbo3ouUnBHsCfD2tVg=
 github.com/onsi/gomega v1.29.0/go.mod h1:9sxs+SwGrKI0+PWe4Fxa9tFQQBG5xSsSbMXOI8PPpoQ=
 github.com/openzipkin/zipkin-go v0.4.3 h1:9EGwpqkgnwdEIJ+Od7QVSEIH+ocmm5nPat0G7sjsSdg=
 github.com/openzipkin/zipkin-go v0.4.3/go.mod h1:M9wCJZFWCo2RiY+o1eBCEMe0Dp2S5LDHcMZmk3RmK7c=
-github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
-github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prashantv/gostub v1.1.0 h1:BTyx3RfQjRHnUWaGF9oQos79AlQ5k8WNktv7VGvVH4g=
 github.com/prashantv/gostub v1.1.0/go.mod h1:A5zLQHz7ieHGG7is6LLXLz7I8+3LZzsrV0P1IAHhP5U=
-github.com/prometheus/client_golang v1.21.1 h1:DOvXXTqVzvkIewV/CDPFdejpMCGeMcbGCQ8YOmu+Ibk=
+github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
-github.com/prometheus/client_golang v1.21.1/go.mod h1:U9NM32ykUErtVBxdvD3zfi+EuFkkaBvMb09mIfe0Zgg=
+github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
-github.com/prometheus/client_model v0.6.1 h1:ZKSh/rekM+n3CeS952MLRAdFwIKqeY8b62p8ais2e9E=
+github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
-github.com/prometheus/client_model v0.6.1/go.mod h1:OrxVMOVHjw3lKMa8+x6HeMGkHMQyHDk9E3jmP2AmGiY=
+github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
-github.com/prometheus/common v0.62.0 h1:xasJaQlnWAeyHdUBeGjXmutelfJHWMRr+Fg4QszZ2Io=
+github.com/prometheus/common v0.66.1 h1:h5E0h5/Y8niHc5DlaLlWLArTQI7tMrsfQjHV+d9ZoGs=
-github.com/prometheus/common v0.62.0/go.mod h1:vyBcEuLSvWos9B1+CyL7JZ2up+uFzXhkqml0W5zIY1I=
+github.com/prometheus/common v0.66.1/go.mod h1:gcaUsgf3KfRSwHY4dIMXLPV0K/Wg1oZ8+SbZk/HH/dA=
-github.com/prometheus/procfs v0.15.1 h1:YagwOFzUgYfKKHX6Dr+sHT7km/hxC76UB0learggepc=
+github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg=
-github.com/prometheus/procfs v0.15.1/go.mod h1:fB45yRUv8NstnjriLhBQLuOUt+WW4BsoGhij/e3PBqk=
+github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is=
-github.com/redis/go-redis/v9 v9.15.0 h1:2jdes0xJxer4h3NUZrZ4OGSntGlXp4WbXju2nOTRXto=
+github.com/redis/go-redis/v9 v9.17.3 h1:fN29NdNrE17KttK5Ndf20buqfDZwGNgoUr9qjl1DQx4=
-github.com/redis/go-redis/v9 v9.15.0/go.mod h1:huWgSWd8mW6+m0VPhJjSSQ+d6Nh1VICQ6Q5lHuCH/Iw=
+github.com/redis/go-redis/v9 v9.17.3/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370=
 github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
@@ -174,16 +178,16 @@ github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
-github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/xdg-go/pbkdf2 v1.0.0 h1:Su7DPu48wXMwC3bs7MCNG+z4FhcyEuz5dlvchbq0B0c=
 github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI=
-github.com/xdg-go/scram v1.1.2 h1:FHX5I5B4i4hKRVRBCFRxq1iQRej7WO3hhBuJf+UUySY=
+github.com/xdg-go/scram v1.2.0 h1:bYKF2AEwG5rqd1BumT4gAnvwU/M9nBp2pTSxeZw7Wvs=
-github.com/xdg-go/scram v1.1.2/go.mod h1:RT/sEzTbU5y00aCK8UOx6R7YryM0iF1N2MOmC3kKLN4=
+github.com/xdg-go/scram v1.2.0/go.mod h1:3dlrS0iBaWKYVt2ZfA4cj48umJZ+cAEbR6/SjLA88I8=
 github.com/xdg-go/stringprep v1.0.4 h1:XLI/Ng3O1Atzq0oBs3TWm+5ZVgkq2aqdlvP9JtoZ6c8=
 github.com/xdg-go/stringprep v1.0.4/go.mod h1:mPGuuIYwz7CmR2bT9j4GbQqutWS1zV24gijq1dTyGkM=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfSfmXjznFBSZNN13rSJjlIOI1fUNAtF7rmI=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
@@ -197,12 +201,10 @@ go.etcd.io/etcd/client/pkg/v3 v3.5.15 h1:fo0HpWz/KlHGMCC+YejpiCmyWDEuIpnTDzpJLB5
 go.etcd.io/etcd/client/pkg/v3 v3.5.15/go.mod h1:mXDI4NAOwEiszrHCb0aqfAYNCrZP4e9hRca3d1YK8EU=
 go.etcd.io/etcd/client/v3 v3.5.15 h1:23M0eY4Fd/inNv1ZfU3AxrbbOdW79r9V9Rl62Nm6ip4=
 go.etcd.io/etcd/client/v3 v3.5.15/go.mod h1:CLSJxrYjvLtHsrPKsy7LmZEE+DK2ktfd2bN4RhBMwlU=
-go.mongodb.org/mongo-driver/v2 v2.3.0 h1:sh55yOXA2vUjW1QYw/2tRlHSQViwDyPnW61AwpZ4rtU=
+go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
-go.mongodb.org/mongo-driver/v2 v2.3.0/go.mod h1:jHeEDJHJq7tm6ZF45Issun9dbogjfnPySb1vXA7EeAI=
+go.mongodb.org/mongo-driver/v2 v2.5.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
 go.opentelemetry.io/otel v1.24.0 h1:0LAOdjNmQeSTzGBzduGe/rU4tZhMwL5rWgtp9Ku5Jfo=
 go.opentelemetry.io/otel v1.24.0/go.mod h1:W7b9Ozg4nkF5tWI5zsXkaKKDjdVjpD4oAt9Qi/MArHo=
-go.opentelemetry.io/otel/exporters/jaeger v1.17.0 h1:D7UpUy2Xc2wsi1Ras6V40q806WM07rqoCWzXu7Sqy+4=
-go.opentelemetry.io/otel/exporters/jaeger v1.17.0/go.mod h1:nPCqOnEH9rNLKqH/+rrUjiMzHJdV1BlpKcTwRTyKkKI=
 go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.24.0 h1:t6wl9SPayj+c7lEIFgm4ooDBZVb01IhLB4InpomhRw8=
 go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.24.0/go.mod h1:iSDOcsnSA5INXzZtwaBPrKp/lWu/V14Dd+llD0oI2EA=
 go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.24.0 h1:Mw5xcxMwlqoJd97vwPxA8isEaIoxsta9/Q51+TTJLGE=
@@ -227,18 +229,20 @@ go.uber.org/automaxprocs v1.6.0 h1:O3y2/QNTOdbF+e/dpXNNW7Rx2hZ4sTIPyybbxyNqTUs=
 go.uber.org/automaxprocs v1.6.0/go.mod h1:ifeIMSnPZuznNm6jmdzmU3/bfk01Fe2fotchwEFJ8r8=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
-go.uber.org/mock v0.4.0 h1:VcM4ZOtdbR4f6VXfiOpwpVJDL6lCReaZ6mw31wqh7KU=
+go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
-go.uber.org/mock v0.4.0/go.mod h1:a6FSlNadKUHUa9IP5Vyt1zh4fC7uAwxMutEAscFbkZc=
+go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
 go.uber.org/multierr v1.9.0 h1:7fIwc/ZtS0q++VgcfqFDxSBZVv/Xo49/SYnDFupUwlI=
 go.uber.org/multierr v1.9.0/go.mod h1:X2jQV1h+kxSjClGpnseKVIxpmcjrj7MNnI0bnlfKTVQ=
 go.uber.org/zap v1.24.0 h1:FiJd5l1UOLj0wCgbSE0rwwXHzEdAZS6hiiSnxJN/D60=
 go.uber.org/zap v1.24.0/go.mod h1:2kMP+WWQ8aoFoedH3T2sq6iJ2yDWpHbP0f6MQbS9Gkg=
+go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
+go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
-golang.org/x/crypto v0.33.0 h1:IOBPskki6Lysi0lo9qQvbxiQ+FvsCC/YWOecCHAixus=
+golang.org/x/crypto v0.41.0 h1:WKYxWedPGCTVVl5+WHSSrOBT0O8lx32+zxmHxijgXp4=
-golang.org/x/crypto v0.33.0/go.mod h1:bVdXmD7IV/4GdElGPozy6U7lWdRXA4qyRVGJV57uQ5M=
+golang.org/x/crypto v0.41.0/go.mod h1:pO5AFd7FA68rFak7rOAGVuygIISepHftHnr8dr6+sUc=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
@@ -248,16 +252,16 @@ golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLL
 golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
-golang.org/x/net v0.35.0 h1:T5GQRQb2y08kTAByq9L4/bz8cipCdA8FbRTXewonqY8=
+golang.org/x/net v0.43.0 h1:lat02VYK2j4aLzMzecihNvTlJNQUq316m2Mr9rnM6YE=
-golang.org/x/net v0.35.0/go.mod h1:EglIi67kWsHKlRzzVMUD93VMSWGFOMSZgxFjparz1Qk=
+golang.org/x/net v0.43.0/go.mod h1:vhO1fvI4dGsIjh73sWfUVjj3N7CA9WkKJNQm2svM6Jg=
-golang.org/x/oauth2 v0.24.0 h1:KTBBxWqUa0ykRPLtV69rRto9TLXcqYkeswu48x/gvNE=
+golang.org/x/oauth2 v0.30.0 h1:dnDm7JmhM45NNpd8FDDeLhK6FwqbOf4MLCM9zb1BOHI=
-golang.org/x/oauth2 v0.24.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
+golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.11.0 h1:GGz8+XQP4FvTTrjZPzNKTMFtSXH80RAzG+5ghFPgK9w=
+golang.org/x/sync v0.16.0 h1:ycBJEhp9p4vXvUZNszeOq0kGTPghopOL8q0fq3vstxw=
-golang.org/x/sync v0.11.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sync v0.16.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -267,18 +271,18 @@ golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
+golang.org/x/sys v0.35.0 h1:vz1N37gP5bs89s7He8XuIYXpyY0+QlsKmzipCbUtyxI=
-golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.35.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
-golang.org/x/term v0.29.0 h1:L6pJp37ocefwRRtYPKSWOWzOtWSxVajvz2ldH/xi3iU=
+golang.org/x/term v0.34.0 h1:O/2T7POpk0ZZ7MAzMeWFSg6S5IpWd/RXDlM9hgM3DR4=
-golang.org/x/term v0.29.0/go.mod h1:6bl4lRlvVuDgSf3179VpIxBF0o10JUpXWOnI7nErv7s=
+golang.org/x/term v0.34.0/go.mod h1:5jC53AEywhIVebHgPVeg0mj8OD3VO9OzclacVrqpaAw=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.3.8/go.mod h1:E6s5w1FMmriuDzIBO73fBruAKo1PCIq6d2Q6DHfQ8WQ=
-golang.org/x/text v0.22.0 h1:bofq7m3/HAFvbF51jz3Q9wLg3jkvSPuiZu/pD1XwgtM=
+golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
-golang.org/x/text v0.22.0/go.mod h1:YRoo4H8PVmsu+E3Ou7cqLVH8oXWIHVoX0jqUWALQhfY=
+golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
 golang.org/x/time v0.10.0 h1:3usCWA8tQn0L8+hFJQNgzpWbd89begxN66o1Ojdn5L4=
 golang.org/x/time v0.10.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
@@ -286,8 +290,8 @@ golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtn
 golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
 golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
-golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d h1:vU5i/LfpvrRCpgM/VPfJLg5KjxD3E+hfT1SH+d9zLwg=
+golang.org/x/tools v0.36.0 h1:kWS0uv/zsvHEle1LbV5LE8QujrxB3wfQyxHfhOk0Qkg=
-golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
+golang.org/x/tools v0.36.0/go.mod h1:WBDiHKJK8YgLHlcQPYQzNCkUxUypCaa5ZegCVutKm+s=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
@@ -298,8 +302,8 @@ google.golang.org/genproto/googleapis/rpc v0.0.0-20240701130421-f6361c86f094 h1:
 google.golang.org/genproto/googleapis/rpc v0.0.0-20240701130421-f6361c86f094/go.mod h1:Ue6ibwXGpU+dqIcODieyLOcgj7z8+IcskoNIgZxtrFY=
 google.golang.org/grpc v1.65.0 h1:bs/cUb4lp1G5iImFFd3u5ixQzweKizoZJAwBNLR42lc=
 google.golang.org/grpc v1.65.0/go.mod h1:WgYC2ypjlB0EiQi6wdKixMqukr6lBc0Vo+oOgjrM5ZQ=
-google.golang.org/protobuf v1.36.5 h1:tPhr+woSbjfYvY6/GPufUoYizxw1cF/yFoxJ2fmpwlM=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
-google.golang.org/protobuf v1.36.5/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
@@ -325,8 +329,8 @@ k8s.io/klog/v2 v2.110.1 h1:U/Af64HJf7FcwMcXyKm2RPM22WZzyR7OSpYj5tg3cL0=
 k8s.io/klog/v2 v2.110.1/go.mod h1:YGtd1984u+GgbuZ7e08/yBuAfKLSO0+uR1Fhi6ExXjo=
 k8s.io/kube-openapi v0.0.0-20231010175941-2dd684a91f00 h1:aVUu9fTY98ivBPKR9Y5w/AuzbMm96cd3YHRTU83I780=
 k8s.io/kube-openapi v0.0.0-20231010175941-2dd684a91f00/go.mod h1:AsvuZPBlUDVuCdzJ87iajxtXuR9oktsTctW/R9wwouA=
-k8s.io/utils v0.0.0-20240711033017-18e509b52bc8 h1:pUdcCO1Lk/tbT5ztQWOBi5HBgbBP1J8+AsQnQCKsi8A=
+k8s.io/utils v0.0.0-20251222233032-718f0e51e6d2 h1:OfgiEo21hGiwx1oJUU5MpEaeOEg6coWndBkZF/lkFuE=
-k8s.io/utils v0.0.0-20240711033017-18e509b52bc8/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=
+k8s.io/utils v0.0.0-20251222233032-718f0e51e6d2/go.mod h1:xDxuJ0whA3d0I4mf/C4ppKHxXynQ+fxnkmQH0vTHnuk=
 sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd h1:EDPBXCAspyGV4jQlpZSudPeMmr1bNJefnuqLsRAsHZo=
 sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd/go.mod h1:B8JuhiUyNFVKdsE8h686QcCxMaH6HrOAZj4vswFpcB0=
 sigs.k8s.io/structured-merge-diff/v4 v4.4.1 h1:150L+0vs/8DA78h1u02ooW1/fFq/Lwr+sGiqlzvrtq4=

internal/health/health.go

@@ -43,7 +43,7 @@ func AddProbe(probe Probe) {
 	defaultHealthManager.addProbe(probe)
 }
 
-// CreateHttpHandler create health http handler base on given probe.
+// CreateHttpHandler creates a health http handler based on the given probe.
 func CreateHttpHandler(healthResponse string) http.HandlerFunc {
 	return func(w http.ResponseWriter, _ *http.Request) {
 		if defaultHealthManager.IsReady() {

mcp/MIGRATION.md

@@ -0,0 +1,166 @@
+# Migration to Official MCP SDK
+
+This document describes the migration from the custom MCP implementation to the official [go-sdk](https://github.com/modelcontextprotocol/go-sdk).
+
+## Changes
+
+### Dependencies
+
+Added the official MCP SDK:
+```bash
+go get github.com/modelcontextprotocol/go-sdk@v1.2.0
+```
+
+### Type System
+
+All types are now re-exported from the official SDK:
+- `Tool` → `sdkmcp.Tool`
+- `CallToolRequest` → `sdkmcp.CallToolRequest`
+- `CallToolResult` → `sdkmcp.CallToolResult`
+- Content types (`TextContent`, `ImageContent`, etc.)
+- `Prompt`, `Resource`, `Server`, `ServerSession`
+
+### Server Interface
+
+The `McpServer` interface has been simplified:
+
+```go
+type McpServer interface {
+    Start()
+    Stop()
+    Server() *sdkmcp.Server  // Returns underlying SDK server
+}
+```
+
+**Important**: The `AddTool`, `AddPrompt`, and `AddResource` methods have been removed. Use the SDK directly:
+
+```go
+// Old (no longer supported)
+server.AddTool(tool, handler)
+
+// New (use SDK directly)
+sdkmcp.AddTool(server.Server(), tool, handler)
+```
+
+### Configuration
+
+Updated configuration structure:
+- Removed: `ProtocolVersion`, `BaseUrl` (SDK manages these)
+- Added: `UseStreamable` (choose between SSE and Streamable HTTP transport)
+
+```yaml
+mcp:
+  name: my-server
+  version: 1.0.0
+  useStreamable: false  # false = SSE (2024-11-05), true = Streamable HTTP (2025-03-26)
+  sseEndpoint: /sse
+  messageEndpoint: /message
+  sseTimeout: 24h
+  messageTimeout: 30s
+  cors:
+    - http://localhost:3000
+```
+
+### Tool Registration
+
+The SDK uses Go generics for type-safe tool registration:
+
+```go
+import sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
+
+type MyArgs struct {
+    Value string `json:"value" jsonschema:"description=Input value"`
+}
+
+tool := &mcp.Tool{
+    Name:        "my_tool",
+    Description: "Description",
+}
+
+handler := func(ctx context.Context, req *mcp.CallToolRequest, args MyArgs) (*mcp.CallToolResult, any, error) {
+    return &mcp.CallToolResult{
+        Content: []mcp.Content{
+            &mcp.TextContent{Text: "Result"},
+        },
+    }, nil, nil
+}
+
+// Register with explicit type parameters
+sdkmcp.AddTool(server.Server(), tool, handler)
+```
+
+The SDK automatically generates JSON schemas from struct tags.
+
+### Transport Support
+
+Two transports are supported:
+
+1. **SSE (Server-Sent Events)**: 2024-11-05 MCP spec
+   - Default (`UseStreamable: false`)
+   - Endpoint: `/sse` (configurable)
+   - Bidirectional: client sends messages to `/message`
+
+2. **Streamable HTTP**: 2025-03-26 MCP spec
+   - Opt-in (`UseStreamable: true`)
+   - Endpoint: `/sse` (configurable)
+   - Newer protocol with improved streaming
+
+### Example Migration
+
+**Before:**
+```go
+server := mcp.NewMcpServer(c)
+
+tool := &mcp.Tool{Name: "greet", Description: "Greet"}
+handler := func(ctx context.Context, req *mcp.CallToolRequest, args GreetArgs) (*mcp.CallToolResult, any, error) {
+    return &mcp.CallToolResult{
+        Content: []mcp.Content{&mcp.TextContent{Text: "Hello"}},
+    }, nil, nil
+}
+
+if err := server.AddTool(tool, handler); err != nil {
+    log.Fatal(err)
+}
+```
+
+**After:**
+```go
+import sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
+
+server := mcp.NewMcpServer(c)
+
+tool := &mcp.Tool{Name: "greet", Description: "Greet"}
+handler := func(ctx context.Context, req *mcp.CallToolRequest, args GreetArgs) (*mcp.CallToolResult, any, error) {
+    return &mcp.CallToolResult{
+        Content: []mcp.Content{&mcp.TextContent{Text: "Hello"}},
+    }, nil, nil
+}
+
+// Use SDK directly - no error return
+sdkmcp.AddTool(server.Server(), tool, handler)
+```
+
+## Benefits
+
+1. **Official SDK**: Uses the official Model Context Protocol SDK
+2. **Type Safety**: Go generics provide compile-time type checking
+3. **Auto Schema**: JSON schemas generated automatically from struct tags
+4. **Dual Transport**: Supports both SSE and Streamable HTTP transports
+5. **Maintained**: SDK is actively maintained by the MCP team
+
+## Breaking Changes
+
+1. `server.AddTool()` removed → use `sdkmcp.AddTool(server.Server(), ...)`
+2. `server.AddPrompt()` removed (SDK v1.2.0 limitation)
+3. `server.AddResource()` removed (SDK v1.2.0 limitation)
+4. Config fields `ProtocolVersion` and `BaseUrl` removed
+5. All types now come from SDK (re-exported for convenience)
+
+## Migration Checklist
+
+- [ ] Update imports: add `sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"`
+- [ ] Replace `server.AddTool()` with `sdkmcp.AddTool(server.Server(), ...)`
+- [ ] Remove error handling for tool registration (SDK doesn't return errors)
+- [ ] Update config: remove `ProtocolVersion` and `BaseUrl`, add `UseStreamable`
+- [ ] Test with both SSE and Streamable transports
+- [ ] Update documentation/examples

mcp/config.go

@@ -18,17 +18,16 @@ type McpConf struct {
 		// Version is the server version reported in initialize responses
 		Version string `json:",default=1.0.0"`
 
-		// ProtocolVersion is the MCP protocol version implemented
+		// UseStreamable when true uses Streamable HTTP transport (2025-03-26 spec),
-		ProtocolVersion string `json:",default=2024-11-05"`
+		// otherwise uses SSE transport (2024-11-05 spec)
-
+		UseStreamable bool `json:",default=false"`
-		// BaseUrl is the base URL for the server, used in SSE endpoint messages
-		// If not set, defaults to http://localhost:{Port}
-		BaseUrl string `json:",optional"`
 
 		// SseEndpoint is the path for Server-Sent Events connections
+		// Used for SSE transport mode
 		SseEndpoint string `json:",default=/sse"`
 
 		// MessageEndpoint is the path for JSON-RPC requests
+		// Used for Streamable HTTP transport mode
 		MessageEndpoint string `json:",default=/message"`
 
 		// Cors contains allowed CORS origins

mcp/config_test.go

@@ -9,7 +9,7 @@ import (
 )
 
 func TestMcpConfDefaults(t *testing.T) {
-	// Test default values are set correctly when unmarshalled from JSON
+	// Test default values are set correctly
 	jsonConfig := `name: test-service
 port: 8080
 mcp:
@@ -23,41 +23,8 @@ mcp:
 
 	// Check default values
 	assert.Equal(t, "test-mcp-server", c.Mcp.Name)
-	assert.Equal(t, "1.0.0", c.Mcp.Version, "Default version should be 1.0.0")
+	assert.Equal(t, "1.0.0", c.Mcp.Version)
-	assert.Equal(t, "2024-11-05", c.Mcp.ProtocolVersion, "Default protocol version should be 2024-11-05")
+	assert.Equal(t, "/sse", c.Mcp.SseEndpoint)
-	assert.Equal(t, "/sse", c.Mcp.SseEndpoint, "Default SSE endpoint should be /sse")
+	assert.Equal(t, "/message", c.Mcp.MessageEndpoint)
-	assert.Equal(t, "/message", c.Mcp.MessageEndpoint, "Default message endpoint should be /message")
+	assert.Equal(t, 30*time.Second, c.Mcp.MessageTimeout)
-	assert.Equal(t, 30*time.Second, c.Mcp.MessageTimeout, "Default message timeout should be 30s")
-}
-
-func TestMcpConfCustomValues(t *testing.T) {
-	// Test custom values can be set
-	jsonConfig := `{
-		"Name": "test-service",
-		"Port": 8080,
-		"Mcp": {
-			"Name": "test-mcp-server",
-			"Version": "2.0.0",
-			"ProtocolVersion": "2025-01-01",
-			"BaseUrl": "http://example.com",
-			"SseEndpoint": "/custom-sse",
-			"MessageEndpoint": "/custom-message",
-			"Cors": ["http://localhost:3000", "http://example.com"],
-			"MessageTimeout": "60s"
-		}
-	}`
-
-	var c McpConf
-	err := conf.LoadFromJsonBytes([]byte(jsonConfig), &c)
-	assert.NoError(t, err)
-
-	// Check custom values
-	assert.Equal(t, "test-mcp-server", c.Mcp.Name, "Name should be inherited from RestConf")
-	assert.Equal(t, "2.0.0", c.Mcp.Version, "Version should be customizable")
-	assert.Equal(t, "2025-01-01", c.Mcp.ProtocolVersion, "Protocol version should be customizable")
-	assert.Equal(t, "http://example.com", c.Mcp.BaseUrl, "BaseUrl should be customizable")
-	assert.Equal(t, "/custom-sse", c.Mcp.SseEndpoint, "SSE endpoint should be customizable")
-	assert.Equal(t, "/custom-message", c.Mcp.MessageEndpoint, "Message endpoint should be customizable")
-	assert.Equal(t, []string{"http://localhost:3000", "http://example.com"}, c.Mcp.Cors, "CORS settings should be customizable")
-	assert.Equal(t, 60*time.Second, c.Mcp.MessageTimeout, "Tool timeout should be customizable")
 }

mcp/integration_test.go

@@ -1,443 +0,0 @@
-package mcp
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// syncResponseRecorder is a thread-safe wrapper around httptest.ResponseRecorder
-type syncResponseRecorder struct {
-	*httptest.ResponseRecorder
-	mu sync.Mutex
-}
-
-// Create a new synchronized response recorder
-func newSyncResponseRecorder() *syncResponseRecorder {
-	return &syncResponseRecorder{
-		ResponseRecorder: httptest.NewRecorder(),
-	}
-}
-
-// Override Write method to synchronize access
-func (srr *syncResponseRecorder) Write(p []byte) (int, error) {
-	srr.mu.Lock()
-	defer srr.mu.Unlock()
-	return srr.ResponseRecorder.Write(p)
-}
-
-// Override WriteHeader method to synchronize access
-func (srr *syncResponseRecorder) WriteHeader(statusCode int) {
-	srr.mu.Lock()
-	defer srr.mu.Unlock()
-	srr.ResponseRecorder.WriteHeader(statusCode)
-}
-
-// Override Result method to synchronize access
-func (srr *syncResponseRecorder) Result() *http.Response {
-	srr.mu.Lock()
-	defer srr.mu.Unlock()
-	return srr.ResponseRecorder.Result()
-}
-
-// TestHTTPHandlerIntegration tests the HTTP handlers with a real server instance
-func TestHTTPHandlerIntegration(t *testing.T) {
-	// Skip in short test mode
-	if testing.Short() {
-		t.Skip("Skipping integration test in short mode")
-	}
-
-	// Create a test configuration
-	conf := McpConf{}
-	conf.Mcp.Name = "test-integration"
-	conf.Mcp.Version = "1.0.0-test"
-	conf.Mcp.MessageTimeout = 1 * time.Second
-
-	// Create a mock server directly
-	server := &sseMcpServer{
-		conf:      conf,
-		clients:   make(map[string]*mcpClient),
-		tools:     make(map[string]Tool),
-		prompts:   make(map[string]Prompt),
-		resources: make(map[string]Resource),
-	}
-
-	// Register a test tool
-	err := server.RegisterTool(Tool{
-		Name:        "echo",
-		Description: "Echo tool for testing",
-		InputSchema: InputSchema{
-			Properties: map[string]any{
-				"message": map[string]any{
-					"type":        "string",
-					"description": "Message to echo",
-				},
-			},
-		},
-		Handler: func(ctx context.Context, params map[string]any) (any, error) {
-			if msg, ok := params["message"].(string); ok {
-				return fmt.Sprintf("Echo: %s", msg), nil
-			}
-			return "Echo: no message provided", nil
-		},
-	})
-	require.NoError(t, err)
-
-	// Create a test HTTP request to the SSE endpoint
-	req := httptest.NewRequest("GET", "/sse", nil)
-	w := newSyncResponseRecorder()
-
-	// Create a done channel to signal completion of test
-	done := make(chan bool)
-
-	// Start the SSE handler in a goroutine
-	go func() {
-		// lock.Lock()
-		server.handleSSE(w, req)
-		// lock.Unlock()
-		done <- true
-	}()
-
-	// Allow time for the handler to process
-	select {
-	case <-time.After(100 * time.Millisecond):
-		// Expected - handler would normally block indefinitely
-	case <-done:
-		// This shouldn't happen immediately - the handler should block
-		t.Error("SSE handler returned unexpectedly")
-	}
-
-	// Check the initial headers
-	resp := w.Result()
-	assert.Equal(t, "chunked", resp.Header.Get("Transfer-Encoding"))
-	resp.Body.Close()
-
-	// The handler creates a client and sends the endpoint message
-	var sessionId string
-
-	// Give the handler time to set up the client
-	time.Sleep(50 * time.Millisecond)
-
-	// Check that a client was created
-	server.clientsLock.Lock()
-	assert.Equal(t, 1, len(server.clients))
-	for id := range server.clients {
-		sessionId = id
-	}
-	server.clientsLock.Unlock()
-
-	require.NotEmpty(t, sessionId, "Expected a session ID to be created")
-
-	// Now that we have a session ID, we can test the message endpoint
-	messageBody, _ := json.Marshal(Request{
-		JsonRpc: "2.0",
-		ID:      1,
-		Method:  methodInitialize,
-		Params:  json.RawMessage(`{}`),
-	})
-
-	// Create a message request
-	reqURL := fmt.Sprintf("/message?%s=%s", sessionIdKey, sessionId)
-	msgReq := httptest.NewRequest("POST", reqURL, bytes.NewReader(messageBody))
-	msgW := newSyncResponseRecorder()
-
-	// Process the message
-	server.handleRequest(msgW, msgReq)
-
-	// Check the response
-	msgResp := msgW.Result()
-	assert.Equal(t, http.StatusAccepted, msgResp.StatusCode)
-	msgResp.Body.Close() // Ensure response body is closed
-}
-
-// TestHandlerResponseFlow tests the flow of a full request/response cycle
-func TestHandlerResponseFlow(t *testing.T) {
-	// Create a mock server for testing
-	server := &sseMcpServer{
-		conf: McpConf{},
-		clients: map[string]*mcpClient{
-			"test-session": {
-				id:          "test-session",
-				channel:     make(chan string, 10),
-				initialized: true,
-			},
-		},
-		tools:     make(map[string]Tool),
-		prompts:   make(map[string]Prompt),
-		resources: make(map[string]Resource),
-	}
-
-	// Register test resources
-	server.RegisterTool(Tool{
-		Name:        "test.tool",
-		Description: "Test tool",
-		InputSchema: InputSchema{Type: "object"},
-		Handler: func(ctx context.Context, params map[string]any) (any, error) {
-			return "tool result", nil
-		},
-	})
-
-	server.RegisterPrompt(Prompt{
-		Name:        "test.prompt",
-		Description: "Test prompt",
-	})
-
-	server.RegisterResource(Resource{
-		Name:        "test.resource",
-		URI:         "http://example.com",
-		Description: "Test resource",
-	})
-
-	// Create a request with session ID parameter
-	reqURL := fmt.Sprintf("/message?%s=%s", sessionIdKey, "test-session")
-
-	// Test tools/list request
-	toolsListBody, _ := json.Marshal(Request{
-		JsonRpc: "2.0",
-		ID:      1,
-		Method:  methodToolsList,
-		Params:  json.RawMessage(`{}`),
-	})
-
-	toolsReq := httptest.NewRequest("POST", reqURL, bytes.NewReader(toolsListBody))
-	toolsW := newSyncResponseRecorder()
-
-	// Process the request
-	server.handleRequest(toolsW, toolsReq)
-
-	// Check the response code
-	toolsResp := toolsW.Result()
-	assert.Equal(t, http.StatusAccepted, toolsResp.StatusCode)
-	toolsResp.Body.Close()
-
-	// Check the channel message
-	client := server.clients["test-session"]
-	select {
-	case message := <-client.channel:
-		assert.Contains(t, message, `"tools":[{"name":"test.tool"`)
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("Timed out waiting for tools/list response")
-	}
-
-	// Test prompts/list request
-	promptsListBody, _ := json.Marshal(Request{
-		JsonRpc: "2.0",
-		ID:      2,
-		Method:  methodPromptsList,
-		Params:  json.RawMessage(`{}`),
-	})
-
-	promptsReq := httptest.NewRequest("POST", reqURL, bytes.NewReader(promptsListBody))
-	promptsW := newSyncResponseRecorder()
-
-	// Process the request
-	server.handleRequest(promptsW, promptsReq)
-
-	// Check the response code
-	promptsResp := promptsW.Result()
-	assert.Equal(t, http.StatusAccepted, promptsResp.StatusCode)
-	promptsResp.Body.Close()
-
-	// Check the channel message
-	select {
-	case message := <-client.channel:
-		assert.Contains(t, message, `"prompts":[{"name":"test.prompt"`)
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("Timed out waiting for prompts/list response")
-	}
-
-	// Test resources/list request
-	resourcesListBody, _ := json.Marshal(Request{
-		JsonRpc: "2.0",
-		ID:      3,
-		Method:  methodResourcesList,
-		Params:  json.RawMessage(`{}`),
-	})
-
-	resourcesReq := httptest.NewRequest("POST", reqURL, bytes.NewReader(resourcesListBody))
-	resourcesW := newSyncResponseRecorder()
-
-	// Process the request
-	server.handleRequest(resourcesW, resourcesReq)
-
-	// Check the response code
-	resourcesResp := resourcesW.Result()
-	assert.Equal(t, http.StatusAccepted, resourcesResp.StatusCode)
-	resourcesResp.Body.Close()
-
-	// Check the channel message
-	select {
-	case message := <-client.channel:
-		assert.Contains(t, message, `"name":"test.resource"`)
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("Timed out waiting for resources/list response")
-	}
-}
-
-// TestProcessListMethods tests the list processing methods with pagination
-func TestProcessListMethods(t *testing.T) {
-	server := &sseMcpServer{
-		tools:     make(map[string]Tool),
-		prompts:   make(map[string]Prompt),
-		resources: make(map[string]Resource),
-	}
-
-	// Add some test data
-	for i := 1; i <= 5; i++ {
-		tool := Tool{
-			Name:        fmt.Sprintf("tool%d", i),
-			Description: fmt.Sprintf("Tool %d", i),
-			InputSchema: InputSchema{Type: "object"},
-		}
-		server.tools[tool.Name] = tool
-
-		prompt := Prompt{
-			Name:        fmt.Sprintf("prompt%d", i),
-			Description: fmt.Sprintf("Prompt %d", i),
-		}
-		server.prompts[prompt.Name] = prompt
-
-		resource := Resource{
-			Name:        fmt.Sprintf("resource%d", i),
-			URI:         fmt.Sprintf("http://example.com/%d", i),
-			Description: fmt.Sprintf("Resource %d", i),
-		}
-		server.resources[resource.Name] = resource
-	}
-
-	// Create a test client
-	client := &mcpClient{
-		id:          "test-client",
-		channel:     make(chan string, 10),
-		initialized: true,
-	}
-
-	// Test processListTools
-	req := Request{
-		JsonRpc: "2.0",
-		ID:      1,
-		Method:  methodToolsList,
-		Params:  json.RawMessage(`{"cursor": "", "_meta": {"progressToken": "token1"}}`),
-	}
-
-	server.processListTools(context.Background(), client, req)
-
-	// Read response
-	select {
-	case response := <-client.channel:
-		assert.Contains(t, response, `"tools":`)
-		assert.Contains(t, response, `"progressToken":"token1"`)
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("Timed out waiting for tools/list response")
-	}
-
-	// Test processListPrompts
-	req.ID = 2
-	req.Method = methodPromptsList
-	req.Params = json.RawMessage(`{"cursor": "next"}`)
-	server.processListPrompts(context.Background(), client, req)
-
-	// Read response
-	select {
-	case response := <-client.channel:
-		assert.Contains(t, response, `"prompts":`)
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("Timed out waiting for prompts/list response")
-	}
-
-	// Test processListResources
-	req.ID = 3
-	req.Method = methodResourcesList
-	req.Params = json.RawMessage(`{"cursor": "next"}`)
-	server.processListResources(context.Background(), client, req)
-
-	// Read response
-	select {
-	case response := <-client.channel:
-		assert.Contains(t, response, `"resources":`)
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("Timed out waiting for resources/list response")
-	}
-}
-
-// TestErrorResponseHandling tests error handling in the server
-func TestErrorResponseHandling(t *testing.T) {
-	server := &sseMcpServer{
-		tools:     make(map[string]Tool),
-		prompts:   make(map[string]Prompt),
-		resources: make(map[string]Resource),
-	}
-
-	// Create a test client
-	client := &mcpClient{
-		id:          "test-client",
-		channel:     make(chan string, 10),
-		initialized: true,
-	}
-
-	// Test invalid method
-	req := Request{
-		JsonRpc: "2.0",
-		ID:      1,
-		Method:  "invalid_method",
-		Params:  json.RawMessage(`{}`),
-	}
-
-	// Mock handleRequest by directly calling error handler
-	server.sendErrorResponse(context.Background(), client, req.ID, "Method not found", errCodeMethodNotFound)
-
-	// Check response
-	select {
-	case response := <-client.channel:
-		assert.Contains(t, response, `"error":{"code":-32601,"message":"Method not found"}`)
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("Timed out waiting for error response")
-	}
-
-	// Test invalid tool
-	toolReq := Request{
-		JsonRpc: "2.0",
-		ID:      2,
-		Method:  methodToolsCall,
-		Params:  json.RawMessage(`{"name":"non_existent_tool"}`),
-	}
-
-	// Call process method directly
-	server.processToolCall(context.Background(), client, toolReq)
-
-	// Check response
-	select {
-	case response := <-client.channel:
-		assert.Contains(t, response, `"error":{"code":-32602,"message":"Tool 'non_existent_tool' not found"}`)
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("Timed out waiting for error response")
-	}
-
-	// Test invalid prompt
-	promptReq := Request{
-		JsonRpc: "2.0",
-		ID:      3,
-		Method:  methodPromptsGet,
-		Params:  json.RawMessage(`{"name":"non_existent_prompt"}`),
-	}
-
-	// Call process method directly
-	server.processGetPrompt(context.Background(), client, promptReq)
-
-	// Check response
-	select {
-	case response := <-client.channel:
-		assert.Contains(t, response, `"error":{"code":-32602,"message":"Prompt 'non_existent_prompt' not found"}`)
-	case <-time.After(100 * time.Millisecond):
-		t.Fatal("Timed out waiting for error response")
-	}
-}

mcp/parser.go

@@ -1,23 +0,0 @@
-package mcp
-
-import (
-	"fmt"
-
-	"github.com/zeromicro/go-zero/core/mapping"
-)
-
-// ParseArguments parses the arguments and populates the request object
-func ParseArguments(args any, req any) error {
-	switch arguments := args.(type) {
-	case map[string]string:
-		m := make(map[string]any, len(arguments))
-		for k, v := range arguments {
-			m[k] = v
-		}
-		return mapping.UnmarshalJsonMap(m, req, mapping.WithStringValues())
-	case map[string]any:
-		return mapping.UnmarshalJsonMap(arguments, req)
-	default:
-		return fmt.Errorf("unsupported argument type: %T", arguments)
-	}
-}

mcp/parser_test.go

@@ -1,139 +0,0 @@
-package mcp
-
-import (
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-// TestParseArguments_MapStringString tests parsing map[string]string arguments
-func TestParseArguments_MapStringString(t *testing.T) {
-	// Sample request struct to populate
-	type requestStruct struct {
-		Name    string `json:"name"`
-		Message string `json:"message"`
-		Count   int    `json:"count"`
-		Enabled bool   `json:"enabled"`
-	}
-
-	// Create test arguments
-	args := map[string]string{
-		"name":    "test-name",
-		"message": "hello world",
-		"count":   "42",
-		"enabled": "true",
-	}
-
-	// Create a target object to populate
-	var req requestStruct
-
-	// Parse the arguments
-	err := ParseArguments(args, &req)
-
-	// Verify results
-	assert.NoError(t, err, "Should parse map[string]string without error")
-	assert.Equal(t, "test-name", req.Name, "Name should be correctly parsed")
-	assert.Equal(t, "hello world", req.Message, "Message should be correctly parsed")
-	assert.Equal(t, 42, req.Count, "Count should be correctly parsed to int")
-	assert.True(t, req.Enabled, "Enabled should be correctly parsed to bool")
-}
-
-// TestParseArguments_MapStringAny tests parsing map[string]any arguments
-func TestParseArguments_MapStringAny(t *testing.T) {
-	// Sample request struct to populate
-	type requestStruct struct {
-		Name     string            `json:"name"`
-		Message  string            `json:"message"`
-		Count    int               `json:"count"`
-		Enabled  bool              `json:"enabled"`
-		Tags     []string          `json:"tags"`
-		Metadata map[string]string `json:"metadata"`
-	}
-
-	// Create test arguments with mixed types
-	args := map[string]any{
-		"name":    "test-name",
-		"message": "hello world",
-		"count":   42,   // note: this is already an int
-		"enabled": true, // note: this is already a bool
-		"tags":    []string{"tag1", "tag2"},
-		"metadata": map[string]string{
-			"key1": "value1",
-			"key2": "value2",
-		},
-	}
-
-	// Create a target object to populate
-	var req requestStruct
-
-	// Parse the arguments
-	err := ParseArguments(args, &req)
-
-	// Verify results
-	assert.NoError(t, err, "Should parse map[string]any without error")
-	assert.Equal(t, "test-name", req.Name, "Name should be correctly parsed")
-	assert.Equal(t, "hello world", req.Message, "Message should be correctly parsed")
-	assert.Equal(t, 42, req.Count, "Count should be correctly parsed")
-	assert.True(t, req.Enabled, "Enabled should be correctly parsed")
-	assert.Equal(t, []string{"tag1", "tag2"}, req.Tags, "Tags should be correctly parsed")
-	assert.Equal(t, map[string]string{
-		"key1": "value1",
-		"key2": "value2",
-	}, req.Metadata, "Metadata should be correctly parsed")
-}
-
-// TestParseArguments_UnsupportedType tests parsing with an unsupported type
-func TestParseArguments_UnsupportedType(t *testing.T) {
-	// Sample request struct to populate
-	type requestStruct struct {
-		Name    string `json:"name"`
-		Message string `json:"message"`
-	}
-
-	// Use an unsupported argument type (slice)
-	args := []string{"not", "a", "map"}
-
-	// Create a target object to populate
-	var req requestStruct
-
-	// Parse the arguments
-	err := ParseArguments(args, &req)
-
-	// Verify error is returned with correct message
-	assert.Error(t, err, "Should return error for unsupported type")
-	assert.Contains(t, err.Error(), "unsupported argument type", "Error should mention unsupported type")
-	assert.Contains(t, err.Error(), "[]string", "Error should include the actual type")
-}
-
-// TestParseArguments_EmptyMap tests parsing with empty maps
-func TestParseArguments_EmptyMap(t *testing.T) {
-	// Sample request struct to populate
-	type requestStruct struct {
-		Name    string `json:"name,optional"`
-		Message string `json:"message,optional"`
-	}
-
-	// Test empty map[string]string
-	t.Run("EmptyMapStringString", func(t *testing.T) {
-		args := map[string]string{}
-		var req requestStruct
-
-		err := ParseArguments(args, &req)
-
-		assert.NoError(t, err, "Should parse empty map[string]string without error")
-		assert.Empty(t, req.Name, "Name should be empty string")
-		assert.Empty(t, req.Message, "Message should be empty string")
-	})
-
-	// Test empty map[string]any
-	t.Run("EmptyMapStringAny", func(t *testing.T) {
-		args := map[string]any{}
-		var req requestStruct
-
-		err := ParseArguments(args, &req)
-
-		assert.NoError(t, err, "Should parse empty map[string]any without error")
-		assert.Empty(t, req.Name, "Name should be empty string")
-		assert.Empty(t, req.Message, "Message should be empty string")
-	})
-}

mcp/types.go

@@ -2,316 +2,99 @@ package mcp
 
 import (
 	"context"
-	"encoding/json"
-	"fmt"
-	"sync"
 
-	"github.com/zeromicro/go-zero/rest"
+	sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/zeromicro/go-zero/core/logx"
 )
 
-// Cursor is an opaque token used for pagination
+// Re-export commonly used SDK types for convenience
-type Cursor string
+type (
+	// Tool types
+	Tool            = sdkmcp.Tool
+	CallToolParams  = sdkmcp.CallToolParams
+	CallToolResult  = sdkmcp.CallToolResult
+	CallToolRequest = sdkmcp.CallToolRequest
 
-// Request represents a generic MCP request following JSON-RPC 2.0 specification
+	// Content types
-type Request struct {
+	Content      = sdkmcp.Content
-	SessionId string          `form:"session_id"` // Session identifier for client tracking
+	TextContent  = sdkmcp.TextContent
-	JsonRpc   string          `json:"jsonrpc"`    // Must be "2.0" per JSON-RPC spec
+	ImageContent = sdkmcp.ImageContent
-	ID        any             `json:"id"`         // Request identifier for matching responses
+	AudioContent = sdkmcp.AudioContent
-	Method    string          `json:"method"`     // Method name to invoke
-	Params    json.RawMessage `json:"params"`     // Parameters for the method
-}
 
-func (r Request) isNotification() (bool, error) {
+	// Prompt types
-	switch val := r.ID.(type) {
+	Prompt          = sdkmcp.Prompt
-	case int:
+	PromptMessage   = sdkmcp.PromptMessage
-		return val == 0, nil
+	GetPromptParams = sdkmcp.GetPromptParams
-	case int64:
+	GetPromptResult = sdkmcp.GetPromptResult
-		return val == 0, nil
+
-	case float64:
+	// Resource types
-		return val == 0.0, nil
+	Resource           = sdkmcp.Resource
-	case string:
+	ResourceContents   = sdkmcp.ResourceContents
-		return len(val) == 0, nil
+	ReadResourceParams = sdkmcp.ReadResourceParams
-	case nil:
+	ReadResourceResult = sdkmcp.ReadResourceResult
-		return true, nil
+
-	default:
+	// Session and server types
-		return false, fmt.Errorf("invalid type %T", val)
+	Server         = sdkmcp.Server
+	ServerSession  = sdkmcp.ServerSession
+	ServerOptions  = sdkmcp.ServerOptions
+	Implementation = sdkmcp.Implementation
+
+	// Transport types
+	SSEHandler            = sdkmcp.SSEHandler
+	StreamableHTTPHandler = sdkmcp.StreamableHTTPHandler
+)
+
+// ToolHandler is a generic function signature for tool handlers.
+// Handlers should accept context, request, and typed arguments, and return
+// a result, metadata, and error.
+//
+// Deprecated: Use ToolHandlerFor directly from the SDK types.
+type ToolHandler[Args any, Meta any] func(
+	ctx context.Context,
+	req *CallToolRequest,
+	args Args,
+) (*CallToolResult, Meta, error)
+
+// PromptHandler is a function signature for prompt handlers.
+type PromptHandler func(
+	ctx context.Context,
+	req *sdkmcp.GetPromptRequest,
+	args map[string]string,
+) (*GetPromptResult, error)
+
+// ResourceHandler is a function signature for resource handlers.
+type ResourceHandler func(
+	ctx context.Context,
+	req *sdkmcp.ReadResourceRequest,
+	uri string,
+) (*ReadResourceResult, error)
+
+// AddTool registers a tool with the MCP server using type-safe generics.
+// The SDK automatically generates JSON schema from the Args struct tags.
+//
+// Example:
+//
+//	type GreetArgs struct {
+//	    Name string `json:"name" jsonschema:"description=Name to greet"`
+//	}
+//
+//	tool := &mcp.Tool{
+//	    Name: "greet",
+//	    Description: "Greet someone",
+//	}
+//
+//	handler := func(ctx context.Context, req *mcp.CallToolRequest, args GreetArgs) (*mcp.CallToolResult, any, error) {
+//	    return &mcp.CallToolResult{
+//	        Content: []mcp.Content{&mcp.TextContent{Text: "Hello " + args.Name}},
+//	    }, nil, nil
+//	}
+//
+//	mcp.AddTool(server, tool, handler)
+func AddTool[In, Out any](server McpServer, tool *Tool, handler func(context.Context, *CallToolRequest, In) (*CallToolResult, Out, error)) {
+	// Access internal server - only works with mcpServerImpl
+	if impl, ok := server.(*mcpServerImpl); ok {
+		sdkmcp.AddTool(impl.mcpServer, tool, handler)
+	} else {
+		logx.Error("AddTool: server must be of type *mcpServerImpl to use this helper")
 	}
 }
-
-type PaginatedParams struct {
-	Cursor string `json:"cursor"`
-	Meta   struct {
-		ProgressToken any `json:"progressToken"`
-	} `json:"_meta"`
-}
-
-// Result is the base interface for all results
-type Result struct {
-	Meta map[string]any `json:"_meta,omitempty"` // Optional metadata
-}
-
-// PaginatedResult is a base for results that support pagination
-type PaginatedResult struct {
-	Result
-	NextCursor Cursor `json:"nextCursor,omitempty"` // Opaque token for fetching next page
-}
-
-// ListToolsResult represents the response to a tools/list request
-type ListToolsResult struct {
-	PaginatedResult
-	Tools []Tool `json:"tools"` // List of available tools
-}
-
-// Message Content Types
-
-// RoleType represents the sender or recipient of messages in a conversation
-type RoleType string
-
-// PromptArgument defines a single argument that can be passed to a prompt
-type PromptArgument struct {
-	Name        string `json:"name"`                  // Argument name
-	Description string `json:"description,omitempty"` // Human-readable description
-	Required    bool   `json:"required,omitempty"`    // Whether this argument is required
-}
-
-// PromptHandler is a function that dynamically generates prompt content
-type PromptHandler func(ctx context.Context, args map[string]string) ([]PromptMessage, error)
-
-// Prompt represents an MCP Prompt definition
-type Prompt struct {
-	Name        string           `json:"name"`                  // Unique identifier for the prompt
-	Description string           `json:"description,omitempty"` // Human-readable description
-	Arguments   []PromptArgument `json:"arguments,omitempty"`   // Arguments for customization
-	Content     string           `json:"-"`                     // Static content (internal use only)
-	Handler     PromptHandler    `json:"-"`                     // Handler for dynamic content generation
-}
-
-// PromptMessage represents a message in a conversation
-type PromptMessage struct {
-	Role    RoleType `json:"role"`    // Message sender role
-	Content any      `json:"content"` // Message content (TextContent, ImageContent, etc.)
-}
-
-// TextContent represents text content in a message
-type TextContent struct {
-	Text        string       `json:"text"`                  // The text content
-	Annotations *Annotations `json:"annotations,omitempty"` // Optional annotations
-}
-
-type typedTextContent struct {
-	Type string `json:"type"`
-	TextContent
-}
-
-// ImageContent represents image data in a message
-type ImageContent struct {
-	Data     string `json:"data"`     // Base64-encoded image data
-	MimeType string `json:"mimeType"` // MIME type (e.g., "image/png")
-}
-
-type typedImageContent struct {
-	Type string `json:"type"`
-	ImageContent
-}
-
-// AudioContent represents audio data in a message
-type AudioContent struct {
-	Data     string `json:"data"`     // Base64-encoded audio data
-	MimeType string `json:"mimeType"` // MIME type (e.g., "audio/mp3")
-}
-
-type typedAudioContent struct {
-	Type string `json:"type"`
-	AudioContent
-}
-
-// FileContent represents file content
-type FileContent struct {
-	URI      string `json:"uri"`      // URI identifying the file
-	MimeType string `json:"mimeType"` // MIME type of the file
-	Text     string `json:"text"`     // File content as text
-}
-
-// EmbeddedResource represents a resource embedded in a message
-type EmbeddedResource struct {
-	Type     string          `json:"type"`     // Always "resource"
-	Resource ResourceContent `json:"resource"` // The resource data
-}
-
-// Annotations provides additional metadata for content
-type Annotations struct {
-	Audience []RoleType `json:"audience,omitempty"` // Who should see this content
-	Priority *float64   `json:"priority,omitempty"` // Optional priority (0-1)
-}
-
-// Tool-related Types
-
-// ToolHandler is a function that handles tool calls
-type ToolHandler func(ctx context.Context, params map[string]any) (any, error)
-
-// Tool represents a Model Context Protocol Tool definition
-type Tool struct {
-	Name        string      `json:"name"`        // Unique identifier for the tool
-	Description string      `json:"description"` // Human-readable description
-	InputSchema InputSchema `json:"inputSchema"` // JSON Schema for parameters
-	Handler     ToolHandler `json:"-"`           // Not sent to clients
-}
-
-// InputSchema represents tool's input schema in JSON Schema format
-type InputSchema struct {
-	Type       string         `json:"type"`
-	Properties map[string]any `json:"properties"`         // Property definitions
-	Required   []string       `json:"required,omitempty"` // List of required properties
-}
-
-// CallToolResult represents a tool call result that conforms to the MCP schema
-type CallToolResult struct {
-	Result
-	Content []any `json:"content"`           // Content items (text, images, etc.)
-	IsError bool  `json:"isError,omitempty"` // True if tool execution failed
-}
-
-// Resource represents a Model Context Protocol Resource definition
-type Resource struct {
-	URI         string          `json:"uri"`                   // Unique resource identifier (RFC3986)
-	Name        string          `json:"name"`                  // Human-readable name
-	Description string          `json:"description,omitempty"` // Optional description
-	MimeType    string          `json:"mimeType,omitempty"`    // Optional MIME type
-	Handler     ResourceHandler `json:"-"`                     // Internal handler not sent to clients
-}
-
-// ResourceHandler is a function that handles resource read requests
-type ResourceHandler func(ctx context.Context) (ResourceContent, error)
-
-// ResourceContent represents the content of a resource
-type ResourceContent struct {
-	URI      string `json:"uri"`                // Resource URI (required)
-	MimeType string `json:"mimeType,omitempty"` // MIME type of the resource
-	Text     string `json:"text,omitempty"`     // Text content (if available)
-	Blob     string `json:"blob,omitempty"`     // Base64 encoded blob data (if available)
-}
-
-// ResourcesListResult represents the response to a resources/list request
-type ResourcesListResult struct {
-	PaginatedResult
-	Resources []Resource `json:"resources"` // List of available resources
-}
-
-// ResourceReadParams contains parameters for a resources/read request
-type ResourceReadParams struct {
-	URI string `json:"uri"` // URI of the resource to read
-}
-
-// ResourceReadResult contains the result of a resources/read request
-type ResourceReadResult struct {
-	Result
-	Contents []ResourceContent `json:"contents"` // Array of resource content
-}
-
-// ResourceSubscribeParams contains parameters for a resources/subscribe request
-type ResourceSubscribeParams struct {
-	URI string `json:"uri"` // URI of the resource to subscribe to
-}
-
-// ResourceUpdateNotification represents a notification about a resource update
-type ResourceUpdateNotification struct {
-	URI     string          `json:"uri"`     // URI of the updated resource
-	Content ResourceContent `json:"content"` // New resource content
-}
-
-// Client and Server Types
-
-// mcpClient represents an SSE client connection
-type mcpClient struct {
-	id          string      // Unique client identifier
-	channel     chan string // Channel for sending SSE messages
-	initialized bool        // Tracks if client has sent notifications/initialized
-}
-
-// McpServer defines the interface for Model Context Protocol servers
-type McpServer interface {
-	Start()
-	Stop()
-	RegisterTool(tool Tool) error
-	RegisterPrompt(prompt Prompt)
-	RegisterResource(resource Resource)
-}
-
-// sseMcpServer implements the McpServer interface using SSE
-type sseMcpServer struct {
-	conf          McpConf
-	server        *rest.Server
-	clients       map[string]*mcpClient
-	clientsLock   sync.Mutex
-	tools         map[string]Tool
-	toolsLock     sync.Mutex
-	prompts       map[string]Prompt
-	promptsLock   sync.Mutex
-	resources     map[string]Resource
-	resourcesLock sync.Mutex
-}
-
-// Response Types
-
-// errorObj represents a JSON-RPC error object
-type errorObj struct {
-	Code    int    `json:"code"`    // Error code
-	Message string `json:"message"` // Error message
-}
-
-// Response represents a JSON-RPC response
-type Response struct {
-	JsonRpc string    `json:"jsonrpc"`         // Always "2.0"
-	ID      any       `json:"id"`              // Same as request ID
-	Result  any       `json:"result"`          // Result object (null if error)
-	Error   *errorObj `json:"error,omitempty"` // Error object (null if success)
-}
-
-// Server Information Types
-
-// serverInfo provides information about the server
-type serverInfo struct {
-	Name    string `json:"name"`    // Server name
-	Version string `json:"version"` // Server version
-}
-
-// capabilities describes the server's capabilities
-type capabilities struct {
-	Logging struct{} `json:"logging"`
-	Prompts struct {
-		ListChanged bool `json:"listChanged"` // Server will notify on prompt changes
-	} `json:"prompts"`
-	Resources struct {
-		Subscribe   bool `json:"subscribe"`   // Server supports resource subscriptions
-		ListChanged bool `json:"listChanged"` // Server will notify on resource changes
-	} `json:"resources"`
-	Tools struct {
-		ListChanged bool `json:"listChanged"` // Server will notify on tool changes
-	} `json:"tools"`
-}
-
-// initializationResponse is sent in response to an initialize request
-type initializationResponse struct {
-	ProtocolVersion string       `json:"protocolVersion"` // Protocol version
-	Capabilities    capabilities `json:"capabilities"`    // Server capabilities
-	ServerInfo      serverInfo   `json:"serverInfo"`      // Server information
-}
-
-// ToolCallParams contains the parameters for a tool call
-type ToolCallParams struct {
-	Name       string         `json:"name"`       // Tool name
-	Parameters map[string]any `json:"parameters"` // Tool parameters
-}
-
-// ToolResult contains the result of a tool execution
-type ToolResult struct {
-	Type    string `json:"type"`    // Content type (text, image, etc.)
-	Content any    `json:"content"` // Result content
-}
-
-// errorMessage represents a detailed error message
-type errorMessage struct {
-	Code    int    `json:"code"`       // Error code
-	Message string `json:"message"`    // Error message
-	Data    any    `json:",omitempty"` // Additional error data
-}

mcp/types_test.go

@@ -1,271 +0,0 @@
-package mcp
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestResponseMarshaling(t *testing.T) {
-	// Test that the Response struct marshals correctly
-	resp := Response{
-		JsonRpc: "2.0",
-		ID:      123,
-		Result: map[string]string{
-			"key": "value",
-		},
-	}
-
-	data, err := json.Marshal(resp)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"jsonrpc":"2.0"`)
-	assert.Contains(t, string(data), `"id":123`)
-	assert.Contains(t, string(data), `"result":{"key":"value"}`)
-
-	// Test response with error
-	respWithError := Response{
-		JsonRpc: "2.0",
-		ID:      456,
-		Error: &errorObj{
-			Code:    errCodeInvalidRequest,
-			Message: "Invalid Request",
-		},
-	}
-
-	data, err = json.Marshal(respWithError)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"jsonrpc":"2.0"`)
-	assert.Contains(t, string(data), `"id":456`)
-	assert.Contains(t, string(data), `"error":{"code":-32600,"message":"Invalid Request"}`)
-}
-
-func TestRequestUnmarshaling(t *testing.T) {
-	// Test that the Request struct unmarshals correctly
-	jsonStr := `{
-		"jsonrpc": "2.0",
-		"id": 789,
-		"method": "test_method",
-		"params": {"key": "value"}
-	}`
-
-	var req Request
-	err := json.Unmarshal([]byte(jsonStr), &req)
-
-	assert.NoError(t, err)
-	assert.Equal(t, "2.0", req.JsonRpc)
-	assert.Equal(t, float64(789), req.ID)
-	assert.Equal(t, "test_method", req.Method)
-
-	// Check params unmarshaled correctly
-	var params map[string]string
-	err = json.Unmarshal(req.Params, &params)
-	assert.NoError(t, err)
-	assert.Equal(t, "value", params["key"])
-}
-
-func TestToolStructs(t *testing.T) {
-	// Test Tool struct
-	tool := Tool{
-		Name:        "test.tool",
-		Description: "A test tool",
-		InputSchema: InputSchema{
-			Type: "object",
-			Properties: map[string]any{
-				"input": map[string]any{
-					"type":        "string",
-					"description": "Input parameter",
-				},
-			},
-			Required: []string{"input"},
-		},
-		Handler: func(ctx context.Context, params map[string]any) (any, error) {
-			return "result", nil
-		},
-	}
-
-	// Verify fields are correct
-	assert.Equal(t, "test.tool", tool.Name)
-	assert.Equal(t, "A test tool", tool.Description)
-	assert.Equal(t, "object", tool.InputSchema.Type)
-	assert.Contains(t, tool.InputSchema.Properties, "input")
-	propMap, ok := tool.InputSchema.Properties["input"].(map[string]any)
-	assert.True(t, ok, "Property should be a map")
-	assert.Equal(t, "string", propMap["type"])
-	assert.NotNil(t, tool.Handler)
-
-	// Verify JSON marshalling (which should exclude Handler function)
-	data, err := json.Marshal(tool)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"name":"test.tool"`)
-	assert.Contains(t, string(data), `"description":"A test tool"`)
-	assert.Contains(t, string(data), `"inputSchema":`)
-	assert.NotContains(t, string(data), `"Handler":`)
-}
-
-func TestPromptStructs(t *testing.T) {
-	// Test Prompt struct
-	prompt := Prompt{
-		Name:        "test.prompt",
-		Description: "A test prompt description",
-	}
-
-	// Verify fields are correct
-	assert.Equal(t, "test.prompt", prompt.Name)
-	assert.Equal(t, "A test prompt description", prompt.Description)
-
-	// Verify JSON marshalling
-	data, err := json.Marshal(prompt)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"name":"test.prompt"`)
-	assert.Contains(t, string(data), `"description":"A test prompt description"`)
-}
-
-func TestResourceStructs(t *testing.T) {
-	// Test Resource struct
-	resource := Resource{
-		Name:        "test.resource",
-		URI:         "http://example.com/resource",
-		Description: "A test resource",
-	}
-
-	// Verify fields are correct
-	assert.Equal(t, "test.resource", resource.Name)
-	assert.Equal(t, "http://example.com/resource", resource.URI)
-	assert.Equal(t, "A test resource", resource.Description)
-
-	// Verify JSON marshalling
-	data, err := json.Marshal(resource)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"name":"test.resource"`)
-	assert.Contains(t, string(data), `"uri":"http://example.com/resource"`)
-	assert.Contains(t, string(data), `"description":"A test resource"`)
-}
-
-func TestContentTypes(t *testing.T) {
-	// Test TextContent
-	textContent := TextContent{
-		Text: "Sample text",
-		Annotations: &Annotations{
-			Audience: []RoleType{RoleUser, RoleAssistant},
-			Priority: ptr(1.0),
-		},
-	}
-
-	data, err := json.Marshal(textContent)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"text":"Sample text"`)
-	assert.Contains(t, string(data), `"audience":["user","assistant"]`)
-	assert.Contains(t, string(data), `"priority":1`)
-
-	// Test ImageContent
-	imageContent := ImageContent{
-		Data:     "base64data",
-		MimeType: "image/png",
-	}
-
-	data, err = json.Marshal(imageContent)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"data":"base64data"`)
-	assert.Contains(t, string(data), `"mimeType":"image/png"`)
-
-	// Test AudioContent
-	audioContent := AudioContent{
-		Data:     "base64audio",
-		MimeType: "audio/mp3",
-	}
-
-	data, err = json.Marshal(audioContent)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"data":"base64audio"`)
-	assert.Contains(t, string(data), `"mimeType":"audio/mp3"`)
-}
-
-func TestCallToolResult(t *testing.T) {
-	// Test CallToolResult
-	result := CallToolResult{
-		Result: Result{
-			Meta: map[string]any{
-				"progressToken": "token123",
-			},
-		},
-		Content: []interface{}{
-			TextContent{
-				Text: "Sample result",
-			},
-		},
-		IsError: false,
-	}
-
-	data, err := json.Marshal(result)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"_meta":{"progressToken":"token123"}`)
-	assert.Contains(t, string(data), `"content":[{"text":"Sample result"}]`)
-	assert.NotContains(t, string(data), `"isError":`)
-}
-
-func TestRequest_isNotification(t *testing.T) {
-	tests := []struct {
-		name    string
-		id      any
-		want    bool
-		wantErr error
-	}{
-		// integer test cases
-		{name: "int zero", id: 0, want: true, wantErr: nil},
-		{name: "int non-zero", id: 1, want: false, wantErr: nil},
-		{name: "int64 zero", id: int64(0), want: true, wantErr: nil},
-		{name: "int64 max", id: int64(9223372036854775807), want: false, wantErr: nil},
-
-		// floating point number test cases
-		{name: "float64 zero", id: float64(0.0), want: true, wantErr: nil},
-		{name: "float64 positive", id: float64(0.000001), want: false, wantErr: nil},
-		{name: "float64 negative", id: float64(-0.000001), want: false, wantErr: nil},
-		{name: "float64 epsilon", id: float64(1e-300), want: false, wantErr: nil},
-
-		// string test cases
-		{name: "empty string", id: "", want: true, wantErr: nil},
-		{name: "non-empty string", id: "abc", want: false, wantErr: nil},
-		{name: "space string", id: " ", want: false, wantErr: nil},
-		{name: "unicode string", id: "こんにちは", want: false, wantErr: nil},
-
-		// special cases
-		{name: "nil", id: nil, want: true, wantErr: nil},
-
-		// logical type test cases
-		{name: "bool true", id: true, want: false, wantErr: errors.New("invalid type bool")},
-		{name: "bool false", id: false, want: false, wantErr: errors.New("invalid type bool")},
-		{name: "struct type", id: struct{}{}, want: false, wantErr: errors.New("invalid type struct {}")},
-		{name: "slice type", id: []int{1, 2, 3}, want: false, wantErr: errors.New("invalid type []int")},
-		{name: "map type", id: map[string]int{"a": 1}, want: false, wantErr: errors.New("invalid type map[string]int")},
-		{name: "pointer type", id: new(int), want: false, wantErr: errors.New("invalid type *int")},
-		{name: "func type", id: func() {}, want: false, wantErr: errors.New("invalid type func()")},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			req := Request{
-				SessionId: "test-session",
-				JsonRpc:   "2.0",
-				ID:        tt.id,
-				Method:    "testMethod",
-				Params:    json.RawMessage(`{}`),
-			}
-
-			got, err := req.isNotification()
-
-			if (err != nil) != (tt.wantErr != nil) {
-				t.Fatalf("error presence mismatch: got error = %v, wantErr %v", err, tt.wantErr)
-			}
-			if err != nil && tt.wantErr != nil && err.Error() != tt.wantErr.Error() {
-				t.Fatalf("error message mismatch:\ngot  %q\nwant %q", err.Error(), tt.wantErr.Error())
-			}
-
-			if got != tt.want {
-				t.Errorf("isNotification() = %v, want %v for ID %v (%T)", got, tt.want, tt.id, tt.id)
-			}
-		})
-	}
-}

mcp/util.go

@@ -1,107 +0,0 @@
-package mcp
-
-import "fmt"
-
-// formatSSEMessage formats a Server-Sent Event message with proper CRLF line endings
-func formatSSEMessage(event string, data []byte) string {
-	return fmt.Sprintf("event: %s\r\ndata: %s\r\n\r\n", event, string(data))
-}
-
-// ptr is a helper function to get a pointer to a value
-func ptr[T any](v T) *T {
-	return &v
-}
-
-func toTypedContents(contents []any) []any {
-	typedContents := make([]any, len(contents))
-
-	for i, content := range contents {
-		switch v := content.(type) {
-		case TextContent:
-			typedContents[i] = typedTextContent{
-				Type:        ContentTypeText,
-				TextContent: v,
-			}
-		case ImageContent:
-			typedContents[i] = typedImageContent{
-				Type:         ContentTypeImage,
-				ImageContent: v,
-			}
-		case AudioContent:
-			typedContents[i] = typedAudioContent{
-				Type:         ContentTypeAudio,
-				AudioContent: v,
-			}
-		default:
-			typedContents[i] = typedTextContent{
-				Type: ContentTypeText,
-				TextContent: TextContent{
-					Text: fmt.Sprintf("Unknown content type: %T", v),
-				},
-			}
-		}
-	}
-
-	return typedContents
-}
-
-func toTypedPromptMessages(messages []PromptMessage) []PromptMessage {
-	typedMessages := make([]PromptMessage, len(messages))
-
-	for i, msg := range messages {
-		switch v := msg.Content.(type) {
-		case TextContent:
-			typedMessages[i] = PromptMessage{
-				Role: msg.Role,
-				Content: typedTextContent{
-					Type:        ContentTypeText,
-					TextContent: v,
-				},
-			}
-		case ImageContent:
-			typedMessages[i] = PromptMessage{
-				Role: msg.Role,
-				Content: typedImageContent{
-					Type:         ContentTypeImage,
-					ImageContent: v,
-				},
-			}
-		case AudioContent:
-			typedMessages[i] = PromptMessage{
-				Role: msg.Role,
-				Content: typedAudioContent{
-					Type:         ContentTypeAudio,
-					AudioContent: v,
-				},
-			}
-		default:
-			typedMessages[i] = PromptMessage{
-				Role: msg.Role,
-				Content: typedTextContent{
-					Type: ContentTypeText,
-					TextContent: TextContent{
-						Text: fmt.Sprintf("Unknown content type: %T", v),
-					},
-				},
-			}
-		}
-	}
-
-	return typedMessages
-}
-
-// validatePromptArguments checks if all required arguments are provided
-// Returns a list of missing required arguments
-func validatePromptArguments(prompt Prompt, providedArgs map[string]string) []string {
-	var missingArgs []string
-
-	for _, arg := range prompt.Arguments {
-		if arg.Required {
-			if value, exists := providedArgs[arg.Name]; !exists || len(value) == 0 {
-				missingArgs = append(missingArgs, arg.Name)
-			}
-		}
-	}
-
-	return missingArgs
-}

mcp/util_test.go

@@ -1,274 +0,0 @@
-package mcp
-
-import (
-	"bufio"
-	"encoding/json"
-	"fmt"
-	"strings"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-type Event struct {
-	Type string
-	Data map[string]any
-}
-
-func parseEvent(input string) (*Event, error) {
-	var evt Event
-	var dataStr string
-
-	scanner := bufio.NewScanner(strings.NewReader(input))
-	for scanner.Scan() {
-		line := scanner.Text()
-		if strings.HasPrefix(line, "event:") {
-			evt.Type = strings.TrimSpace(strings.TrimPrefix(line, "event:"))
-		} else if strings.HasPrefix(line, "data:") {
-			dataStr = strings.TrimSpace(strings.TrimPrefix(line, "data:"))
-		}
-	}
-	if err := scanner.Err(); err != nil {
-		return nil, err
-	}
-
-	if len(dataStr) > 0 {
-		if err := json.Unmarshal([]byte(dataStr), &evt.Data); err != nil {
-			return nil, fmt.Errorf("failed to parse data: %w", err)
-		}
-	}
-
-	return &evt, nil
-}
-
-// TestToTypedPromptMessages tests the toTypedPromptMessages function
-func TestToTypedPromptMessages(t *testing.T) {
-	// Test with multiple message types in one test
-	t.Run("MixedContentTypes", func(t *testing.T) {
-		// Create test data with different content types
-		messages := []PromptMessage{
-			{
-				Role: RoleUser,
-				Content: TextContent{
-					Text: "Hello, this is a text message",
-					Annotations: &Annotations{
-						Audience: []RoleType{RoleUser, RoleAssistant},
-						Priority: ptr(0.8),
-					},
-				},
-			},
-			{
-				Role: RoleAssistant,
-				Content: ImageContent{
-					Data:     "base64ImageData",
-					MimeType: "image/jpeg",
-				},
-			},
-			{
-				Role: RoleUser,
-				Content: AudioContent{
-					Data:     "base64AudioData",
-					MimeType: "audio/mp3",
-				},
-			},
-			{
-				Role:    "system",
-				Content: "This is a simple string that should be handled as unknown type",
-			},
-		}
-
-		// Call the function
-		result := toTypedPromptMessages(messages)
-
-		// Validate results
-		require.Len(t, result, 4, "Should return the same number of messages")
-
-		// Validate first message (TextContent)
-		msg := result[0]
-		assert.Equal(t, RoleUser, msg.Role, "Role should be preserved")
-
-		// Type assertion using reflection since Content is an interface
-		typed, ok := msg.Content.(typedTextContent)
-		require.True(t, ok, "Should be typedTextContent")
-		assert.Equal(t, ContentTypeText, typed.Type, "Type should be text")
-		assert.Equal(t, "Hello, this is a text message", typed.Text, "Text content should be preserved")
-		require.NotNil(t, typed.Annotations, "Annotations should be preserved")
-		assert.Equal(t, []RoleType{RoleUser, RoleAssistant}, typed.Annotations.Audience, "Audience should be preserved")
-		require.NotNil(t, typed.Annotations.Priority, "Priority should be preserved")
-		assert.Equal(t, 0.8, *typed.Annotations.Priority, "Priority value should be preserved")
-
-		// Validate second message (ImageContent)
-		msg = result[1]
-		assert.Equal(t, RoleAssistant, msg.Role, "Role should be preserved")
-
-		// Type assertion for image content
-		typedImg, ok := msg.Content.(typedImageContent)
-		require.True(t, ok, "Should be typedImageContent")
-		assert.Equal(t, ContentTypeImage, typedImg.Type, "Type should be image")
-		assert.Equal(t, "base64ImageData", typedImg.Data, "Image data should be preserved")
-		assert.Equal(t, "image/jpeg", typedImg.MimeType, "MimeType should be preserved")
-
-		// Validate third message (AudioContent)
-		msg = result[2]
-		assert.Equal(t, RoleUser, msg.Role, "Role should be preserved")
-
-		// Type assertion for audio content
-		typedAudio, ok := msg.Content.(typedAudioContent)
-		require.True(t, ok, "Should be typedAudioContent")
-		assert.Equal(t, ContentTypeAudio, typedAudio.Type, "Type should be audio")
-		assert.Equal(t, "base64AudioData", typedAudio.Data, "Audio data should be preserved")
-		assert.Equal(t, "audio/mp3", typedAudio.MimeType, "MimeType should be preserved")
-
-		// Validate fourth message (unknown type converted to TextContent)
-		msg = result[3]
-		assert.Equal(t, RoleType("system"), msg.Role, "Role should be preserved")
-
-		// Should be converted to a typedTextContent with error message
-		typedUnknown, ok := msg.Content.(typedTextContent)
-		require.True(t, ok, "Unknown content should be converted to typedTextContent")
-		assert.Equal(t, ContentTypeText, typedUnknown.Type, "Type should be text")
-		assert.Contains(t, typedUnknown.Text, "Unknown content type:", "Should contain error about unknown type")
-		assert.Contains(t, typedUnknown.Text, "string", "Should mention the actual type")
-	})
-
-	// Test empty input
-	t.Run("EmptyInput", func(t *testing.T) {
-		messages := []PromptMessage{}
-		result := toTypedPromptMessages(messages)
-		assert.Empty(t, result, "Should return empty slice for empty input")
-	})
-
-	// Test with nil annotations
-	t.Run("NilAnnotations", func(t *testing.T) {
-		messages := []PromptMessage{
-			{
-				Role: RoleUser,
-				Content: TextContent{
-					Text:        "Text with nil annotations",
-					Annotations: nil,
-				},
-			},
-		}
-
-		result := toTypedPromptMessages(messages)
-		require.Len(t, result, 1, "Should return one message")
-
-		typed, ok := result[0].Content.(typedTextContent)
-		require.True(t, ok, "Should be typedTextContent")
-		assert.Equal(t, ContentTypeText, typed.Type, "Type should be text")
-		assert.Equal(t, "Text with nil annotations", typed.Text, "Text content should be preserved")
-		assert.Nil(t, typed.Annotations, "Nil annotations should be preserved as nil")
-	})
-}
-
-// TestToTypedContents tests the toTypedContents function
-func TestToTypedContents(t *testing.T) {
-	// Test with multiple content types in one test
-	t.Run("MixedContentTypes", func(t *testing.T) {
-		// Create test data with different content types
-		contents := []any{
-			TextContent{
-				Text: "Hello, this is a text content",
-				Annotations: &Annotations{
-					Audience: []RoleType{RoleUser, RoleAssistant},
-					Priority: ptr(0.7),
-				},
-			},
-			ImageContent{
-				Data:     "base64ImageData",
-				MimeType: "image/png",
-			},
-			AudioContent{
-				Data:     "base64AudioData",
-				MimeType: "audio/wav",
-			},
-			"This is a simple string that should be handled as unknown type",
-		}
-
-		// Call the function
-		result := toTypedContents(contents)
-
-		// Validate results
-		require.Len(t, result, 4, "Should return the same number of contents")
-
-		// Validate first content (TextContent)
-		typed, ok := result[0].(typedTextContent)
-		require.True(t, ok, "Should be typedTextContent")
-		assert.Equal(t, ContentTypeText, typed.Type, "Type should be text")
-		assert.Equal(t, "Hello, this is a text content", typed.Text, "Text content should be preserved")
-		require.NotNil(t, typed.Annotations, "Annotations should be preserved")
-		assert.Equal(t, []RoleType{RoleUser, RoleAssistant}, typed.Annotations.Audience, "Audience should be preserved")
-		require.NotNil(t, typed.Annotations.Priority, "Priority should be preserved")
-		assert.Equal(t, 0.7, *typed.Annotations.Priority, "Priority value should be preserved")
-
-		// Validate second content (ImageContent)
-		typedImg, ok := result[1].(typedImageContent)
-		require.True(t, ok, "Should be typedImageContent")
-		assert.Equal(t, ContentTypeImage, typedImg.Type, "Type should be image")
-		assert.Equal(t, "base64ImageData", typedImg.Data, "Image data should be preserved")
-		assert.Equal(t, "image/png", typedImg.MimeType, "MimeType should be preserved")
-
-		// Validate third content (AudioContent)
-		typedAudio, ok := result[2].(typedAudioContent)
-		require.True(t, ok, "Should be typedAudioContent")
-		assert.Equal(t, ContentTypeAudio, typedAudio.Type, "Type should be audio")
-		assert.Equal(t, "base64AudioData", typedAudio.Data, "Audio data should be preserved")
-		assert.Equal(t, "audio/wav", typedAudio.MimeType, "MimeType should be preserved")
-
-		// Validate fourth content (unknown type converted to TextContent)
-		typedUnknown, ok := result[3].(typedTextContent)
-		require.True(t, ok, "Unknown content should be converted to typedTextContent")
-		assert.Equal(t, ContentTypeText, typedUnknown.Type, "Type should be text")
-		assert.Contains(t, typedUnknown.Text, "Unknown content type:", "Should contain error about unknown type")
-		assert.Contains(t, typedUnknown.Text, "string", "Should mention the actual type")
-	})
-
-	// Test empty input
-	t.Run("EmptyInput", func(t *testing.T) {
-		contents := []any{}
-		result := toTypedContents(contents)
-		assert.Empty(t, result, "Should return empty slice for empty input")
-	})
-
-	// Test with nil annotations
-	t.Run("NilAnnotations", func(t *testing.T) {
-		contents := []any{
-			TextContent{
-				Text:        "Text with nil annotations",
-				Annotations: nil,
-			},
-		}
-
-		result := toTypedContents(contents)
-		require.Len(t, result, 1, "Should return one content")
-
-		typed, ok := result[0].(typedTextContent)
-		require.True(t, ok, "Should be typedTextContent")
-		assert.Equal(t, ContentTypeText, typed.Type, "Type should be text")
-		assert.Equal(t, "Text with nil annotations", typed.Text, "Text content should be preserved")
-		assert.Nil(t, typed.Annotations, "Nil annotations should be preserved as nil")
-	})
-
-	// Test with custom struct (should be handled as unknown type)
-	t.Run("CustomStruct", func(t *testing.T) {
-		type CustomContent struct {
-			Data string
-		}
-
-		contents := []any{
-			CustomContent{
-				Data: "custom data",
-			},
-		}
-
-		result := toTypedContents(contents)
-		require.Len(t, result, 1, "Should return one content")
-
-		typed, ok := result[0].(typedTextContent)
-		require.True(t, ok, "Custom struct should be converted to typedTextContent")
-		assert.Equal(t, ContentTypeText, typed.Type, "Type should be text")
-		assert.Contains(t, typed.Text, "Unknown content type:", "Should contain error about unknown type")
-		assert.Contains(t, typed.Text, "CustomContent", "Should mention the actual type")
-	})
-}

mcp/vars.go

@@ -1,149 +0,0 @@
-package mcp
-
-import (
-	"time"
-
-	"github.com/zeromicro/go-zero/core/syncx"
-)
-
-// Protocol constants
-const (
-	// JSON-RPC version as defined in the specification
-	jsonRpcVersion = "2.0"
-
-	// Session identifier key used in request URLs
-	sessionIdKey = "session_id"
-
-	// progressTokenKey is used to track progress of long-running tasks
-	progressTokenKey = "progressToken"
-)
-
-// Server-Sent Events (SSE) event types
-const (
-	// Standard message event for JSON-RPC responses
-	eventMessage = "message"
-
-	// Endpoint event for sending endpoint URL to clients
-	eventEndpoint = "endpoint"
-)
-
-// Content type identifiers
-const (
-	// ContentTypeObject is object content type
-	ContentTypeObject = "object"
-
-	// ContentTypeText is text content type
-	ContentTypeText = "text"
-
-	// ContentTypeImage is image content type
-	ContentTypeImage = "image"
-
-	// ContentTypeAudio is audio content type
-	ContentTypeAudio = "audio"
-
-	// ContentTypeResource is resource content type
-	ContentTypeResource = "resource"
-)
-
-// Collection keys for broadcast events
-const (
-	// Key for prompts collection
-	keyPrompts = "prompts"
-
-	// Key for resources collection
-	keyResources = "resources"
-
-	// Key for tools collection
-	keyTools = "tools"
-)
-
-// JSON-RPC error codes
-// Standard error codes from JSON-RPC 2.0 spec
-const (
-	// Invalid JSON was received by the server
-	errCodeInvalidRequest = -32600
-
-	// The method does not exist / is not available
-	errCodeMethodNotFound = -32601
-
-	// Invalid method parameter(s)
-	errCodeInvalidParams = -32602
-
-	// Internal JSON-RPC error
-	errCodeInternalError = -32603
-
-	// Tool execution timed out
-	errCodeTimeout = -32001
-
-	// Resource not found error
-	errCodeResourceNotFound = -32002
-
-	// Client hasn't completed initialization
-	errCodeClientNotInitialized = -32800
-)
-
-// User and assistant role definitions
-const (
-	// RoleUser is the "user" role - the entity asking questions
-	RoleUser RoleType = "user"
-
-	// RoleAssistant is the "assistant" role - the entity providing responses
-	RoleAssistant RoleType = "assistant"
-)
-
-// Method names as defined in the MCP specification
-const (
-	// Initialize the connection between client and server
-	methodInitialize = "initialize"
-
-	// List available tools
-	methodToolsList = "tools/list"
-
-	// Call a specific tool
-	methodToolsCall = "tools/call"
-
-	// List available prompts
-	methodPromptsList = "prompts/list"
-
-	// Get a specific prompt
-	methodPromptsGet = "prompts/get"
-
-	// List available resources
-	methodResourcesList = "resources/list"
-
-	// Read a specific resource
-	methodResourcesRead = "resources/read"
-
-	// Subscribe to resource updates
-	methodResourcesSubscribe = "resources/subscribe"
-
-	// Simple ping to check server availability
-	methodPing = "ping"
-
-	// Notification that client is fully initialized
-	methodNotificationsInitialized = "notifications/initialized"
-
-	// Notification that a request was canceled
-	methodNotificationsCancelled = "notifications/cancelled"
-)
-
-// Event names for Server-Sent Events (SSE)
-const (
-	// Notification of tool list changes
-	eventToolsListChanged = "tools/list_changed"
-
-	// Notification of prompt list changes
-	eventPromptsListChanged = "prompts/list_changed"
-
-	// Notification of resource list changes
-	eventResourcesListChanged = "resources/list_changed"
-)
-
-var (
-	// Default channel size for events
-	eventChanSize = 10
-
-	// Default ping interval for checking connection availability
-	// use syncx.ForAtomicDuration to ensure atomicity in test race
-	pingInterval = syncx.ForAtomicDuration(30 * time.Second)
-)

mcp/vars_test.go

@@ -1,210 +0,0 @@
-// filepath: /Users/kevin/Develop/go/opensource/go-zero/mcp/vars_test.go
-package mcp
-
-import (
-	"encoding/json"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-// TestErrorCodes ensures error codes are applied correctly in error responses
-func TestErrorCodes(t *testing.T) {
-	testCases := []struct {
-		name     string
-		code     int
-		message  string
-		expected string
-	}{
-		{
-			name:     "invalid request error",
-			code:     errCodeInvalidRequest,
-			message:  "Invalid request",
-			expected: `"code":-32600`,
-		},
-		{
-			name:     "method not found error",
-			code:     errCodeMethodNotFound,
-			message:  "Method not found",
-			expected: `"code":-32601`,
-		},
-		{
-			name:     "invalid params error",
-			code:     errCodeInvalidParams,
-			message:  "Invalid parameters",
-			expected: `"code":-32602`,
-		},
-		{
-			name:     "internal error",
-			code:     errCodeInternalError,
-			message:  "Internal server error",
-			expected: `"code":-32603`,
-		},
-		{
-			name:     "timeout error",
-			code:     errCodeTimeout,
-			message:  "Operation timed out",
-			expected: `"code":-32001`,
-		},
-		{
-			name:     "resource not found error",
-			code:     errCodeResourceNotFound,
-			message:  "Resource not found",
-			expected: `"code":-32002`,
-		},
-		{
-			name:     "client not initialized error",
-			code:     errCodeClientNotInitialized,
-			message:  "Client not initialized",
-			expected: `"code":-32800`,
-		},
-	}
-
-	for _, tc := range testCases {
-		t.Run(tc.name, func(t *testing.T) {
-			resp := Response{
-				JsonRpc: jsonRpcVersion,
-				ID:      int64(1),
-				Error: &errorObj{
-					Code:    tc.code,
-					Message: tc.message,
-				},
-			}
-			data, err := json.Marshal(resp)
-			assert.NoError(t, err)
-			assert.Contains(t, string(data), tc.expected, "Error code should match expected value")
-			assert.Contains(t, string(data), tc.message, "Error message should be included")
-			assert.Contains(t, string(data), jsonRpcVersion, "JSON-RPC version should be included")
-		})
-	}
-}
-
-// TestJsonRpcVersion ensures the correct JSON-RPC version is used
-func TestJsonRpcVersion(t *testing.T) {
-	assert.Equal(t, "2.0", jsonRpcVersion, "JSON-RPC version should be 2.0")
-
-	// Test that it's used in responses
-	resp := Response{
-		JsonRpc: jsonRpcVersion,
-		ID:      int64(1),
-		Result:  "test",
-	}
-	data, err := json.Marshal(resp)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"jsonrpc":"2.0"`, "Response should use correct JSON-RPC version")
-
-	// Test that it's expected in requests
-	reqStr := `{"jsonrpc":"2.0","id":1,"method":"test"}`
-	var req Request
-	err = json.Unmarshal([]byte(reqStr), &req)
-	assert.NoError(t, err)
-	assert.Equal(t, jsonRpcVersion, req.JsonRpc, "Request should parse correct JSON-RPC version")
-}
-
-// TestSessionIdKey ensures session ID extraction works correctly
-func TestSessionIdKey(t *testing.T) {
-	// Create a mock server implementation
-	mock := newMockMcpServer(t)
-	defer mock.shutdown()
-
-	// Verify the key constant
-	assert.Equal(t, "session_id", sessionIdKey, "Session ID key should be 'session_id'")
-
-	// Test that session ID is extracted correctly
-	mockR := httptest.NewRequest("GET", "/?"+sessionIdKey+"=test-session", nil)
-
-	// Since the mock server is using the same session key logic,
-	// we can test this by accessing the request query parameters directly
-	sessionID := mockR.URL.Query().Get(sessionIdKey)
-	assert.Equal(t, "test-session", sessionID, "Session ID should be extracted correctly")
-}
-
-// TestEventTypes ensures event types are set correctly in SSE responses
-func TestEventTypes(t *testing.T) {
-	// Test message event
-	assert.Equal(t, "message", eventMessage, "Message event should be 'message'")
-
-	// Test endpoint event
-	assert.Equal(t, "endpoint", eventEndpoint, "Endpoint event should be 'endpoint'")
-
-	// Verify them in an actual SSE format string
-	messageEvent := "event: " + eventMessage + "\ndata: test\n\n"
-	assert.Contains(t, messageEvent, "event: message", "Message event should format correctly")
-
-	endpointEvent := "event: " + eventEndpoint + "\ndata: test\n\n"
-	assert.Contains(t, endpointEvent, "event: endpoint", "Endpoint event should format correctly")
-}
-
-// TestCollectionKeys checks that collection keys are used correctly
-func TestCollectionKeys(t *testing.T) {
-	// Verify collection key constants
-	assert.Equal(t, "prompts", keyPrompts, "Prompts key should be 'prompts'")
-	assert.Equal(t, "resources", keyResources, "Resources key should be 'resources'")
-	assert.Equal(t, "tools", keyTools, "Tools key should be 'tools'")
-}
-
-// TestRoleTypes checks that role types are used correctly
-func TestRoleTypes(t *testing.T) {
-	// Test in annotations
-	annotations := Annotations{
-		Audience: []RoleType{RoleUser, RoleAssistant},
-	}
-	data, err := json.Marshal(annotations)
-	assert.NoError(t, err)
-	assert.Contains(t, string(data), `"audience":["user","assistant"]`, "Role types should marshal correctly")
-}
-
-// TestMethodNames checks that method names are used correctly
-func TestMethodNames(t *testing.T) {
-	// Verify method name constants
-	methods := map[string]string{
-		"initialize":                methodInitialize,
-		"tools/list":                methodToolsList,
-		"tools/call":                methodToolsCall,
-		"prompts/list":              methodPromptsList,
-		"prompts/get":               methodPromptsGet,
-		"resources/list":            methodResourcesList,
-		"resources/read":            methodResourcesRead,
-		"resources/subscribe":       methodResourcesSubscribe,
-		"ping":                      methodPing,
-		"notifications/initialized": methodNotificationsInitialized,
-		"notifications/cancelled":   methodNotificationsCancelled,
-	}
-
-	for expected, actual := range methods {
-		assert.Equal(t, expected, actual, "Method name should be "+expected)
-	}
-
-	// Test in a request
-	for methodName := range methods {
-		req := Request{
-			JsonRpc: jsonRpcVersion,
-			ID:      int64(1),
-			Method:  methodName,
-		}
-		data, err := json.Marshal(req)
-		assert.NoError(t, err)
-		assert.Contains(t, string(data), `"method":"`+methodName+`"`, "Method name should be used in requests")
-	}
-}
-
-// TestEventNames checks that event names are used correctly
-func TestEventNames(t *testing.T) {
-	// Verify event name constants
-	events := map[string]string{
-		"tools/list_changed":     eventToolsListChanged,
-		"prompts/list_changed":   eventPromptsListChanged,
-		"resources/list_changed": eventResourcesListChanged,
-	}
-
-	for expected, actual := range events {
-		assert.Equal(t, expected, actual, "Event name should be "+expected)
-	}
-
-	// Test event names in SSE format
-	for _, eventName := range events {
-		sseEvent := "event: " + eventName + "\ndata: test\n\n"
-		assert.Contains(t, sseEvent, "event: "+eventName, "Event name should format correctly in SSE")
-	}
-}

readme-cn.md

@@ -17,7 +17,7 @@
 <a href="https://trendshift.io/repositories/3263" target="_blank"><img src="https://trendshift.io/api/badge/repositories/3263" alt="zeromicro%2Fgo-zero | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 <a href="https://www.producthunt.com/posts/go-zero?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-go&#0045;zero" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=334030&theme=light" alt="go&#0045;zero - A&#0032;web&#0032;&#0038;&#0032;rpc&#0032;framework&#0032;written&#0032;in&#0032;Go&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 
-## 0. go-zero 介绍
+## go-zero 介绍
 
 go-zero（收录于 CNCF 云原生技术全景图：[https://landscape.cncf.io/?selected=go-zero](https://landscape.cncf.io/?selected=go-zero)）是一个集成了各种工程实践的 web 和 rpc 框架。通过弹性设计保障了大并发服务端的稳定性，经受了充分的实战检验。
 
@@ -25,72 +25,50 @@ go-zero 包含极简的 API 定义和生成工具 goctl，可以根据定义的
 
 使用 go-zero 的好处：
 
-* 轻松获得支撑千万日活服务的稳定性
+* 经过千万日活服务验证的稳定性
-* 内建级联超时控制、限流、自适应熔断、自适应降载等微服务治理能力，无需配置和额外代码
+* 内建弹性保护:级联超时、限流、熔断、降载(无需配置)
-* 微服务治理中间件可无缝集成到其它现有框架使用
+* 极简 API 语法生成多端代码
-* 极简的 API 描述，一键生成各端代码
+* 自动参数校验和丰富的微服务工具包
-* 自动校验客户端请求参数合法性
-* 大量微服务治理和并发工具包
 
 ![架构图](https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/architecture.png)
 
-## 1. go-zero 框架背景
+## go-zero 框架背景
 
-18 年初，我们决定从 `Java+MongoDB` 的单体架构迁移到微服务架构，经过仔细思考和对比，我们决定：
+18 年初，我们决定从 `Java+MongoDB` 的单体架构迁移到微服务架构，选择:
 
-* 基于 Go 语言
+* **基于 Go 语言** - 高效性能、简洁语法、极致部署体验、极低资源成本
-  * 高效的性能
+* **自研微服务框架** - 更快速的问题定位、更便捷的新特性增加
-  * 简洁的语法
-  * 广泛验证的工程效率
-  * 极致的部署体验
-  * 极低的服务端资源成本
-* 自研微服务框架
-  * 有过很多微服务框架自研经验
-  * 需要有更快速的问题定位能力
-  * 更便捷的增加新特性
 
-## 2. go-zero 框架设计思考
+## go-zero 框架设计思考
 
-对于微服务框架的设计，我们期望保障微服务稳定性的同时，也要特别注重研发效率。所以设计之初，我们就有如下一些准则：
+go-zero 遵循以下核心设计准则:
 
-* 保持简单，第一原则
+* **保持简单** - 简单是第一原则
-* 弹性设计，面向故障编程
+* **高可用** - 高并发、易扩展
-* 工具大于约定和文档
+* **弹性设计** - 面向故障编程
-* 高可用、高并发、易扩展
+* **工具驱动** - 工具大于约定和文档
-* 对业务开发友好，封装复杂度
+* **业务友好** - 封装复杂度、一事一法
-* 约束做一件事只有一种方式
 
-我们经历不到半年时间，彻底完成了从 `Java+MongoDB` 到 `Golang+MySQL` 为主的微服务体系迁移，并于 18 年 8 月底完全上线，稳定保障了业务后续迅速增长，确保了整个服务的高可用。
+## go-zero 项目实现和特点
 
-## 3. go-zero 项目实现和特点
+go-zero 集成各种工程实践，主要特点:
 
-go-zero 是一个集成了各种工程实践的包含 web 和 rpc 框架，有如下主要特点：
+* **强大工具支持** - 尽可能少的代码编写
-
+* **极简接口** - 完全兼容 net/http
-* 强大的工具支持，尽可能少的代码编写
+* **高性能** - 优化的速度和效率
-* 极简的接口
+* **弹性设计** - 内建限流、熔断、降载，自动触发、自动恢复
-* 完全兼容 net/http
+* **服务治理** - 内建服务发现、负载均衡、链路跟踪
-* 支持中间件，方便扩展
+* **开发工具** - API 参数自动校验、超时级联控制、自动缓存控制
-* 高性能
-* 面向故障编程，弹性设计
-* 内建服务发现、负载均衡
-* 内建限流、熔断、降载，且自动触发，自动恢复
-* API 参数自动校验
-* 超时级联控制
-* 自动缓存控制
-* 链路跟踪、统计报警等
-* 高并发支撑，稳定保障了疫情期间每天的流量洪峰
-
-如下图，我们从多个层面保障了整体服务的高可用：
 
 ![弹性设计](https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/resilience.jpg)
 
-## 4. 我们使用 go-zero 的基本架构图
+## 我们使用 go-zero 的基本架构图
 
 <img width="1067" alt="image" src="https://user-images.githubusercontent.com/1918356/171880582-11a86658-41c3-466c-95e7-7b1220eecc52.png">
 
 觉得不错的话，别忘 **star** 👏
 
-## 5. Installation
+## Installation
 
 在项目目录下通过如下命令安装：
 
@@ -98,7 +76,57 @@ go-zero 是一个集成了各种工程实践的包含 web 和 rpc 框架，有
 GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/zeromicro/go-zero
 ```
 
-## 6. Quick Start
+## AI 原生开发
+
+go-zero 团队构建了完整的 AI 工具生态，让 Claude、GitHub Copilot、Cursor 生成符合 go-zero 规范的代码。
+
+### 三大核心项目
+
+**[ai-context](https://github.com/zeromicro/ai-context)** - AI 的工作流程指南
+
+**[zero-skills](https://github.com/zeromicro/zero-skills)** - 模式库和示例
+
+**[mcp-zero](https://github.com/zeromicro/mcp-zero)** - 基于 MCP 的代码生成工具
+
+### 快速配置
+
+#### GitHub Copilot
+```bash
+git submodule add https://github.com/zeromicro/ai-context.git .github/ai-context
+ln -s ai-context/00-instructions.md .github/copilot-instructions.md  # macOS/Linux
+# Windows: mklink .github\copilot-instructions.md .github\ai-context\00-instructions.md
+git submodule update --remote .github/ai-context  # 更新
+```
+
+#### Cursor
+```bash
+git submodule add https://github.com/zeromicro/ai-context.git .cursorrules
+git submodule update --remote .cursorrules  # 更新
+```
+
+#### Windsurf
+```bash
+git submodule add https://github.com/zeromicro/ai-context.git .windsurfrules
+git submodule update --remote .windsurfrules  # 更新
+```
+
+#### Claude Desktop
+```bash
+git clone https://github.com/zeromicro/mcp-zero.git && cd mcp-zero && go build
+# 配置: ~/Library/Application Support/Claude/claude_desktop_config.json
+# 或: claude mcp add --transport stdio mcp-zero --env GOCTL_PATH=/path/to/goctl -- /path/to/mcp-zero
+```
+
+### 协同工作原理
+
+AI 助手通过三个工具协同配合:
+1. **ai-context** - 工作流程指导
+2. **zero-skills** - 实现模式
+3. **mcp-zero** - 实时代码生成
+
+**示例**:创建新的 REST API → AI 读取 **ai-context** 了解工作流 → 调用 **mcp-zero** 生成代码 → 参考 **zero-skills** 实现模式 → 生成符合规范的代码 ✅
+
+## Quick Start
 
 0. 完整示例请查看
 
@@ -108,23 +136,22 @@ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/zeromicro
 
 1. 安装 goctl 工具
 
-    `goctl` 读作 `go control`，不要读成 `go C-T-L`。`goctl` 的意思是不要被代码控制，而是要去控制它。其中的 `go` 不是指 `golang`。在设计 `goctl` 之初，我就希望通过 `工具` 来解放我们的双手👈
 
     ```shell
     # Go
     GOPROXY=https://goproxy.cn/,direct go install github.com/zeromicro/go-zero/tools/goctl@latest
-    
+
     # For Mac
     brew install goctl
-    
+
     # docker for all platforms
     docker pull kevinwan/goctl
     # run goctl
     docker run --rm -it -v `pwd`:/app kevinwan/goctl --help
     ```
-    
+
-    确保 goctl 可执行，并且在 $PATH 环境变量里。
+    确保 goctl 可执行并在 $PATH 环境变量里。
-    
+
 2. 快速生成 api 服务
 
     ```shell
@@ -157,7 +184,7 @@ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/zeromicro
       * 可以在 `servicecontext.go` 里面传递依赖给 logic，比如 mysql, redis 等
       * 在 api 定义的 `get/post/put/delete` 等请求对应的 logic 里增加业务处理逻辑
 
-3. 可以根据 api 文件生成前端需要的 Java, TypeScript, Dart, JavaScript 代码
+3. 生成多语言客户端代码
 
     ```shell
     goctl api java -api greet.api -dir greet
@@ -165,17 +192,17 @@ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/zeromicro
     ...
     ```
 
-## 7. Benchmark
+## Benchmark
 
 ![benchmark](https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/benchmark.png)
 
 [测试代码见这里](https://github.com/smallnest/go-web-framework-benchmark)
 
-## 8. 文档
+## 文档
 
 * API 文档
 
-  [https://go-zero.dev/cn/](https://go-zero.dev/cn/)
+  [https://go-zero.dev](https://go-zero.dev)
 
 * awesome 系列（更多文章见『微服务实践』公众号）
 
@@ -192,9 +219,9 @@ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/zeromicro
   | [goctl-android](https://github.com/zeromicro/goctl-android) | 生成 `java (android)` 端 `http client` 请求代码 |
   | [goctl-go-compact](https://github.com/zeromicro/goctl-go-compact) | 合并 `api` 里同一个 `group` 里的 `handler` 到一个 `go` 文件 |
 
-## 9. go-zero 用户
+## go-zero 用户
 
-go-zero 已被许多公司用于生产部署，接入场景如在线教育、电商业务、游戏、区块链等，目前为止，已使用 go-zero 的公司包括但不限于：
+go-zero 已被众多公司用于生产部署，场景涵盖在线教育、电商、游戏、区块链等。目前使用 go-zero 的公司包括但不限于:
 
 >1. 好未来
 >2. 上海晓信信息科技有限公司（晓黑板）
@@ -305,10 +332,13 @@ go-zero 已被许多公司用于生产部署，接入场景如在线教育、电
 >107. 深圳市聚货通信息科技有限公司
 >108. 浙江银盾云科技有限公司
 >109. 南京造世网络科技有限公司
+>110. 温州飞儿云信息技术有限公司
+>111. 统信软件
+>112. 深圳坐标软件集团有限公司
 
 如果贵公司也已使用 go-zero，欢迎在 [登记地址](https://github.com/zeromicro/go-zero/issues/602) 登记，仅仅为了推广，不做其它用途。
 
-## 10. CNCF 云原生技术全景图
+## CNCF 云原生技术全景图
 
 <p float="left">
 <img src="https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/cncf-logo.svg" width="200"/>&nbsp;&nbsp;&nbsp;
@@ -317,13 +347,13 @@ go-zero 已被许多公司用于生产部署，接入场景如在线教育、电
 
 go-zero 收录在 [CNCF Cloud Native 云原生技术全景图](https://landscape.cncf.io/?selected=go-zero)。
 
-## 11. 微信公众号
+## 微信公众号
 
 `go-zero` 相关文章和视频都会在 `微服务实践` 公众号整理呈现，欢迎扫码关注 👏
 
 <img src="https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/zeromicro.jpg" alt="wechat" width="600" />
 
-## 12. 微信交流群
+## 微信交流群
 
 如果文档中未能覆盖的任何疑问，欢迎您在群里提出，我们会尽快答复。
 
@@ -333,10 +363,4 @@ go-zero 收录在 [CNCF Cloud Native 云原生技术全景图](https://landscape
 
 加群之前有劳点一下 ***star***，一个小小的 ***star*** 是作者们回答海量问题的动力！🤝
 
-<img src="https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/wechat.jpg" alt="wechat" width="300" />
+<img src="https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/wechat.jpg" alt="wechat" width="300" />
-
-## 13. 知识星球
-
-官方团队运营的知识星球
-
-<img src="https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/zsxq.jpg" alt="知识星球" width="300" />

readme.md

@@ -42,61 +42,39 @@ go-zero contains simple API description syntax and code generation tool called `
 
 ## Backgrounds of go-zero
 
-In early 2018, we embarked on a transformative journey to redesign our system, transitioning from a monolithic architecture built with Java and MongoDB to a microservices architecture. After careful research and comparison, we made a deliberate choice to:
+In early 2018, we transitioned from a Java+MongoDB monolithic architecture to microservices, choosing:
 
-* Go Beyond with Golang
+* **Golang** - High performance, simple syntax, excellent deployment experience, and low resource consumption
-  * Great performance
+* **Self-designed microservice framework** - Better problem isolation, easier feature extension, and faster issue resolution
-  * Simple syntax
-  * Proven engineering efficiency
-  * Extreme deployment experience
-  * Less server resource consumption
-
-* Self-Design Our Microservice Architecture
-  * Microservice architecture facilitates the creation of scalable, flexible, and maintainable software systems with independent, reusable components.
-  * Easy to locate the problems within microservices.
-  * Easy to extend the features by adding or modifying specific microservices without impacting the entire system.
 
 ## Design considerations on go-zero
 
-By designing the microservice architecture, we expected to ensure stability, as well as productivity. And from just the beginning, we have the following design principles:
+go-zero follows these core design principles:
 
-* Keep it simple
+* **Simplicity** - Keep it simple, first principle
-* High availability
+* **High availability** - Stable under high concurrency
-* Stable on high concurrency
+* **Resilience** - Failure-oriented programming with adaptive protection
-* Easy to extend
+* **Developer friendly** - Encapsulate complexity, one way to do one thing
-* Resilience design, failure-oriented programming
+* **Easy to extend** - Flexible architecture for growth
-* Try best to be friendly to the business logic development, encapsulate the complexity
-* One thing, one way
-
-After almost half a year, we finished the transfer from a monolithic system to microservice system and deployed on August 2018. The new system guaranteed business growth and system stability.
 
 ## The implementation and features of go-zero
 
-go-zero is a web and rpc framework that integrates lots of engineering practices. The features are mainly listed below:
+go-zero integrates engineering best practices:
 
-* Powerful tool included, less code to write
+* **Code generation** - Powerful tools to minimize boilerplate
-* Simple interfaces
+* **Simple API** - Clean interfaces, fully compatible with net/http
-* Fully compatible with net/http
+* **High performance** - Optimized for speed and efficiency
-* Middlewares are supported, easy to extend
+* **Resilience** - Built-in circuit breaker, rate limiting, load shedding, timeout control
-* High performance
+* **Service mesh** - Service discovery, load balancing, call tracing
-* Failure-oriented programming, resilience design
+* **Developer tools** - Auto parameter validation, cache management, metrics and monitoring
-* Builtin service discovery, load balancing
-* Builtin concurrency control, adaptive circuit breaker, adaptive load shedding, auto-trigger, auto recover
-* Auto validation of API request parameters
-* Chained timeout control
-* Auto management of data caching
-* Call tracing, metrics, and monitoring
-* High concurrency protected
-
-As below, go-zero protects the system with a couple of layers and mechanisms:
 
 ![Resilience](https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/resilience-en.png)
 
-##  The simplified architecture that we use with go-zero
+## Architecture with go-zero
 
 <img width="1067" alt="image" src="https://user-images.githubusercontent.com/1918356/171880372-5010d846-e8b1-4942-8fe2-e2bbb584f762.png">
 
-##  Installation
+## Installation
 
 Run the following command under your project:
 
@@ -104,9 +82,59 @@ Run the following command under your project:
 go get -u github.com/zeromicro/go-zero
 ```
 
-##  Quick Start
+## AI-Native Development
 
-1. Full examples can be checked out from below:
+The go-zero team provides AI tooling for Claude, GitHub Copilot, Cursor to generate framework-compliant code.
+
+### Three Core Projects
+
+**[ai-context](https://github.com/zeromicro/ai-context)** - Workflow guide for AI assistants
+
+**[zero-skills](https://github.com/zeromicro/zero-skills)** - Pattern library with examples
+
+**[mcp-zero](https://github.com/zeromicro/mcp-zero)** - Code generation tools via Model Context Protocol
+
+### Quick Setup
+
+#### GitHub Copilot
+```bash
+git submodule add https://github.com/zeromicro/ai-context.git .github/ai-context
+ln -s ai-context/00-instructions.md .github/copilot-instructions.md  # macOS/Linux
+# Windows: mklink .github\copilot-instructions.md .github\ai-context\00-instructions.md
+git submodule update --remote .github/ai-context  # Update
+```
+
+#### Cursor
+```bash
+git submodule add https://github.com/zeromicro/ai-context.git .cursorrules
+git submodule update --remote .cursorrules  # Update
+```
+
+#### Windsurf
+```bash
+git submodule add https://github.com/zeromicro/ai-context.git .windsurfrules
+git submodule update --remote .windsurfrules  # Update
+```
+
+#### Claude Desktop
+```bash
+git clone https://github.com/zeromicro/mcp-zero.git && cd mcp-zero && go build
+# Configure: ~/Library/Application Support/Claude/claude_desktop_config.json
+# Or: claude mcp add --transport stdio mcp-zero --env GOCTL_PATH=/path/to/goctl -- /path/to/mcp-zero
+```
+
+### How It Works
+
+AI assistants use these tools together:
+1. **ai-context** - workflow guidance
+2. **zero-skills** - implementation patterns
+3. **mcp-zero** - real-time code generation
+
+**Example**: Creating a REST API → AI reads **ai-context** for workflow → calls **mcp-zero** to generate code → references **zero-skills** for patterns → produces production-ready code ✅
+
+## Quick Start
+
+1. Full examples:
 
      [Rapid development of microservice systems](https://github.com/zeromicro/zero-doc/blob/main/doc/shorturl-en.md)
 
@@ -114,24 +142,22 @@ go get -u github.com/zeromicro/go-zero
 
 2. Install goctl
 
-   `goctl`can be read as `go control`. `goctl` means not to be controlled by code, instead, we control it. The inside `go` is not `golang`. At the very beginning, I was expecting it to help us improve productivity, and make our lives easier.
-
    ```shell
    # for Go
    go install github.com/zeromicro/go-zero/tools/goctl@latest
-   
+
    # For Mac
    brew install goctl
-   
+
    # docker for all platforms
    docker pull kevinwan/goctl
    # run goctl
    docker run --rm -it -v `pwd`:/app kevinwan/goctl --help
    ```
-   
+
-   make sure goctl is executable and in your $PATH.
+   Ensure goctl is executable and in your $PATH.
-   
+
-3. Create the API file, like greet.api, you can install the plugin of goctl in vs code, api syntax is supported.
+3. Create the API file (greet.api):
 
    ```go
    type (
@@ -150,19 +176,19 @@ go get -u github.com/zeromicro/go-zero
    }
    ```
 
-   the .api files also can be generated by goctl, like below:
+   Generate .api template:
 
    ```shell
    goctl api -o greet.api
    ```
 
-4. Generate the go server-side code
+4. Generate Go server code
 
    ```shell
    goctl api go -api greet.api -dir greet
    ```
 
-   the generated files look like:
+   Generated structure:
 
    ```Plain Text
    ├── greet
@@ -184,7 +210,7 @@ go get -u github.com/zeromicro/go-zero
    └── greet.api                     // api description file
    ```
 
-   the generated code can be run directly:
+   Run the service:
 
    ```shell
    cd greet
@@ -192,15 +218,15 @@ go get -u github.com/zeromicro/go-zero
    go run greet.go -f etc/greet-api.yaml
    ```
 
-   by default, it’s listening on port 8888, while it can be changed in the configuration file.
+   Default port: 8888 (configurable in etc/greet-api.yaml)
 
-   you can check it by curl:
+   Test with curl:
 
    ```shell
    curl -i http://localhost:8888/greet/from/you
    ```
 
-   the response looks like below:
+   Response:
 
    ```http
    HTTP/1.1 200 OK
@@ -208,12 +234,12 @@ go get -u github.com/zeromicro/go-zero
    Content-Length: 0
    ```
 
-5. Write the business logic code
+5. Write business logic
 
-    * the dependencies can be passed into the logic within servicecontext.go, like mysql, redis, etc.
+    * Pass dependencies (mysql, redis, etc.) via servicecontext.go
-    * add the logic code in a logic package according to .api file
+    * Add logic code in the logic package per .api definition
 
-6. Generate code like Java, TypeScript, Dart, JavaScript, etc. just from the api file
+6. Generate client code for multiple languages
 
    ```shell
    goctl api java -api greet.api -dir greet
@@ -234,11 +260,11 @@ go get -u github.com/zeromicro/go-zero
 * [Rapid development of microservice systems - multiple RPCs](https://github.com/zeromicro/zero-doc/blob/main/docs/zero/bookstore-en.md)
 * [Examples](https://github.com/zeromicro/zero-examples)
 
-##  Chat group
+## Chat group
 
 Join the chat via https://discord.gg/4JQvC5A4Fe
 
-##  Cloud Native Landscape
+## Cloud Native Landscape
 
 <p float="left">
 <img src="https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/cncf-logo.svg" width="200"/>&nbsp;&nbsp;&nbsp;

rest/handler/authhandler.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"net/http"
 	"net/http/httputil"
+	"strings"
 
 	"github.com/golang-jwt/jwt/v4"
 	"github.com/zeromicro/go-zero/core/logc"
@@ -99,10 +100,17 @@ func WithUnauthorizedCallback(callback UnauthorizedCallback) AuthorizeOption {
 
 func detailAuthLog(r *http.Request, reason string) {
 	// discard dump error, only for debug purpose
-	details, _ := httputil.DumpRequest(r, true)
+	// Skip dumping request body for multipart/form-data to avoid reading large files
+	dumpBody := !isMultipartFormData(r)
+	details, _ := httputil.DumpRequest(r, dumpBody)
 	logc.Errorf(r.Context(), "authorize failed: %s\n=> %+v", reason, string(details))
 }
 
+func isMultipartFormData(r *http.Request) bool {
+	contentType := r.Header.Get("Content-Type")
+	return strings.Contains(contentType, "multipart/form-data")
+}
+
 func unauthorized(w http.ResponseWriter, r *http.Request, err error, callback UnauthorizedCallback) {
 	writer := response.NewHeaderOnceResponseWriter(w)
 

rest/handler/authhandler_test.go

@@ -5,6 +5,7 @@ import (
 	"net"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 	"time"
 
@@ -90,6 +91,128 @@ func TestAuthHandler_NilError(t *testing.T) {
 	})
 }
 
+func TestAuthHandlerWithJSONBody(t *testing.T) {
+	const key = "B63F477D-BBA3-4E52-96D3-C0034C27694A"
+	
+	// Create a request with JSON body
+	jsonBody := `{"username":"test","password":"secret"}`
+	req := httptest.NewRequest(http.MethodPost, "http://localhost/login", 
+		strings.NewReader(jsonBody))
+	req.Header.Set("Content-Type", "application/json")
+	// Missing authorization header to trigger the unauthorized path
+	
+	handler := Authorize(key)(
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		}))
+	
+	resp := httptest.NewRecorder()
+	handler.ServeHTTP(resp, req)
+	
+	// Should return unauthorized
+	assert.Equal(t, http.StatusUnauthorized, resp.Code)
+}
+
+func TestAuthHandlerWithMultipartFormData(t *testing.T) {
+	const key = "B63F477D-BBA3-4E52-96D3-C0034C27694A"
+	
+	// Create a multipart form-data request
+	// We don't need actual body content since we're testing that
+	// the body is NOT read when Content-Type is multipart/form-data
+	req := httptest.NewRequest(http.MethodPost, "http://localhost/upload", 
+		http.NoBody)
+	req.Header.Set("Content-Type", "multipart/form-data; boundary=----WebKitFormBoundary")
+	// Missing authorization header to trigger the unauthorized path
+	
+	handler := Authorize(key)(
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		}))
+	
+	resp := httptest.NewRecorder()
+	handler.ServeHTTP(resp, req)
+	
+	// Should return unauthorized
+	assert.Equal(t, http.StatusUnauthorized, resp.Code)
+}
+
+func TestAuthHandlerWithMultipartFormDataLargeFile(t *testing.T) {
+	const key = "B63F477D-BBA3-4E52-96D3-C0034C27694A"
+	
+	// Create a multipart form-data request with a simulated large file
+	// This tests that the body is NOT consumed when Content-Type is multipart/form-data
+	largeContent := make([]byte, 1024*1024) // 1MB of data
+	for i := range largeContent {
+		largeContent[i] = byte(i % 256)
+	}
+	
+	req := httptest.NewRequest(http.MethodPost, "http://localhost/upload", 
+		http.NoBody)
+	req.Header.Set("Content-Type", "multipart/form-data; boundary=----WebKitFormBoundary")
+	req.Header.Set("Content-Length", "1048576")
+	// Missing authorization header to trigger the unauthorized path
+	
+	handler := Authorize(key)(
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		}))
+	
+	resp := httptest.NewRecorder()
+	
+	// This should complete quickly without reading the body
+	start := time.Now()
+	handler.ServeHTTP(resp, req)
+	elapsed := time.Since(start)
+	
+	// Should return unauthorized
+	assert.Equal(t, http.StatusUnauthorized, resp.Code)
+	// Should complete in less than 100ms (without reading 1MB of data)
+	assert.Less(t, elapsed, 100*time.Millisecond)
+}
+
+func TestIsMultipartFormData(t *testing.T) {
+	tests := []struct {
+		name        string
+		contentType string
+		expected    bool
+	}{
+		{
+			name:        "multipart/form-data",
+			contentType: "multipart/form-data",
+			expected:    true,
+		},
+		{
+			name:        "multipart/form-data with boundary",
+			contentType: "multipart/form-data; boundary=----WebKitFormBoundary",
+			expected:    true,
+		},
+		{
+			name:        "application/json",
+			contentType: "application/json",
+			expected:    false,
+		},
+		{
+			name:        "application/x-www-form-urlencoded",
+			contentType: "application/x-www-form-urlencoded",
+			expected:    false,
+		},
+		{
+			name:        "empty content type",
+			contentType: "",
+			expected:    false,
+		},
+	}
+	
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodPost, "http://localhost", http.NoBody)
+			req.Header.Set("Content-Type", tt.contentType)
+			result := isMultipartFormData(req)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
 func buildToken(secretKey string, payloads map[string]any, seconds int64) (string, error) {
 	now := time.Now().Unix()
 	claims := make(jwt.MapClaims)

rest/handler/tracehandler.go

@@ -13,7 +13,7 @@ import (
 )
 
 type (
-	// TraceOption defines the method to customize an traceOptions.
+	// TraceOption defines the method to customize a traceOptions.
 	TraceOption func(options *traceOptions)
 
 	// traceOptions is TraceHandler options.

rest/handler/tracehandler_test.go

@@ -21,10 +21,11 @@ import (
 
 func TestOtelHandler(t *testing.T) {
 	ztrace.StartAgent(ztrace.Config{
-		Name:     "go-zero-test",
+		Name:         "go-zero-test",
-		Endpoint: "http://localhost:14268/api/traces",
+		Endpoint:     "http://localhost:14268",
-		Batcher:  "jaeger",
+		OtlpHttpPath: "/v1/traces",
-		Sampler:  1.0,
+		Batcher:      "otlphttp",
+		Sampler:      1.0,
 	})
 	defer ztrace.StopAgent()
 
@@ -84,10 +85,11 @@ func TestTraceHandler(t *testing.T) {
 
 func TestDontTracingSpan(t *testing.T) {
 	ztrace.StartAgent(ztrace.Config{
-		Name:     "go-zero-test",
+		Name:         "go-zero-test",
-		Endpoint: "http://localhost:14268/api/traces",
+		Endpoint:     "http://localhost:14268",
-		Batcher:  "jaeger",
+		OtlpHttpPath: "/v1/traces",
-		Sampler:  1.0,
+		Batcher:      "otlphttp",
+		Sampler:      1.0,
 	})
 	defer ztrace.StopAgent()
 
@@ -129,10 +131,11 @@ func TestDontTracingSpan(t *testing.T) {
 
 func TestTraceResponseWriter(t *testing.T) {
 	ztrace.StartAgent(ztrace.Config{
-		Name:     "go-zero-test",
+		Name:         "go-zero-test",
-		Endpoint: "http://localhost:14268/api/traces",
+		Endpoint:     "http://localhost:14268",
-		Batcher:  "jaeger",
+		OtlpHttpPath: "/v1/traces",
-		Sampler:  1.0,
+		Batcher:      "otlphttp",
+		Sampler:      1.0,
 	})
 	defer ztrace.StopAgent()
 

rest/httpc/requests_test.go

@@ -21,10 +21,11 @@ import (
 
 func TestDoRequest(t *testing.T) {
 	ztrace.StartAgent(ztrace.Config{
-		Name:     "go-zero-test",
+		Name:         "go-zero-test",
-		Endpoint: "http://localhost:14268/api/traces",
+		Endpoint:     "http://localhost:14268",
-		Batcher:  "jaeger",
+		OtlpHttpPath: "/v1/traces",
-		Sampler:  1.0,
+		Batcher:      "otlphttp",
+		Sampler:      1.0,
 	})
 	defer ztrace.StopAgent()
 

rest/httpc/service.go

@@ -2,7 +2,10 @@ package httpc
 
 import (
 	"context"
+	"errors"
+	"net"
 	"net/http"
+	"net/url"
 
 	"github.com/zeromicro/go-zero/core/breaker"
 )
@@ -67,8 +70,44 @@ func (s namedService) do(r *http.Request) (resp *http.Response, err error) {
 		resp, err = s.cli.Do(r)
 		return err
 	}, func(err error) bool {
-		return err == nil && resp.StatusCode < http.StatusInternalServerError
+		return acceptable(resp, err)
 	})
 
 	return
 }
+
+// acceptable determines whether the HTTP request/response should be considered
+// successful for circuit breaker purposes.
+//
+// Returns true (acceptable) for:
+//   - HTTP status codes < 500 (2xx, 3xx, 4xx)
+//   - Context cancellation (user-initiated)
+//   - Non-network errors (application-level errors)
+//
+// Returns false (not acceptable, triggers breaker) for:
+//   - HTTP status codes >= 500 (server errors)
+//   - context.DeadlineExceeded (timeout)
+//   - Network errors (connection refused, DNS failures, etc.)
+func acceptable(resp *http.Response, err error) bool {
+	if err == nil {
+		return resp.StatusCode < http.StatusInternalServerError
+	}
+
+	if errors.Is(err, context.DeadlineExceeded) {
+		return false
+	}
+
+	if errors.Is(err, context.Canceled) {
+		return true
+	}
+
+	// Unwrap url.Error if present
+	var ue *url.Error
+	if errors.As(err, &ue) {
+		err = ue.Unwrap()
+	}
+
+	// Network errors are not acceptable
+	var ne net.Error
+	return !errors.As(err, &ne)
+}

rest/httpc/service_test.go

@@ -2,9 +2,13 @@ package httpc
 
 import (
 	"context"
+	"errors"
+	"net"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/zeromicro/go-zero/rest/internal/header"
@@ -84,3 +88,256 @@ func TestNamedService_DoBadRequest(t *testing.T) {
 	_, err := service.Do(context.Background(), http.MethodPost, "/nodes/:key", val)
 	assert.NotNil(t, err)
 }
+
+// mockNetError implements net.Error interface for testing
+type mockNetError struct {
+	msg       string
+	timeout   bool
+	temporary bool
+}
+
+func (e *mockNetError) Error() string   { return e.msg }
+func (e *mockNetError) Timeout() bool   { return e.timeout }
+func (e *mockNetError) Temporary() bool { return e.temporary }
+
+func TestAcceptable(t *testing.T) {
+	tests := []struct {
+		name     string
+		resp     *http.Response
+		err      error
+		expected bool
+	}{
+		{
+			name: "no error with 2xx status code",
+			resp: &http.Response{
+				StatusCode: http.StatusOK,
+			},
+			err:      nil,
+			expected: true,
+		},
+		{
+			name: "no error with 3xx status code",
+			resp: &http.Response{
+				StatusCode: http.StatusMovedPermanently,
+			},
+			err:      nil,
+			expected: true,
+		},
+		{
+			name: "no error with 4xx status code",
+			resp: &http.Response{
+				StatusCode: http.StatusNotFound,
+			},
+			err:      nil,
+			expected: true,
+		},
+		{
+			name: "no error with 499 status code (just below 500)",
+			resp: &http.Response{
+				StatusCode: 499,
+			},
+			err:      nil,
+			expected: true,
+		},
+		{
+			name: "no error with 500 status code",
+			resp: &http.Response{
+				StatusCode: http.StatusInternalServerError,
+			},
+			err:      nil,
+			expected: false,
+		},
+		{
+			name: "no error with 503 status code",
+			resp: &http.Response{
+				StatusCode: http.StatusServiceUnavailable,
+			},
+			err:      nil,
+			expected: false,
+		},
+		{
+			name:     "context deadline exceeded",
+			resp:     nil,
+			err:      context.DeadlineExceeded,
+			expected: false,
+		},
+		{
+			name:     "context canceled",
+			resp:     nil,
+			err:      context.Canceled,
+			expected: true,
+		},
+		{
+			name:     "wrapped context deadline exceeded",
+			resp:     nil,
+			err:      errors.Join(context.DeadlineExceeded, errors.New("timeout")),
+			expected: false,
+		},
+		{
+			name:     "wrapped context canceled",
+			resp:     nil,
+			err:      errors.Join(context.Canceled, errors.New("canceled")),
+			expected: true,
+		},
+		{
+			name:     "network error - timeout",
+			resp:     nil,
+			err:      &mockNetError{msg: "network timeout", timeout: true, temporary: false},
+			expected: false,
+		},
+		{
+			name:     "network error - temporary",
+			resp:     nil,
+			err:      &mockNetError{msg: "temporary network error", timeout: false, temporary: true},
+			expected: false,
+		},
+		{
+			name:     "network error - connection refused",
+			resp:     nil,
+			err:      &net.OpError{Op: "dial", Net: "tcp", Err: errors.New("connection refused")},
+			expected: false,
+		},
+		{
+			name: "url.Error wrapping network error",
+			resp: nil,
+			err: &url.Error{
+				Op:  "Get",
+				URL: "http://example.com",
+				Err: &mockNetError{msg: "network error", timeout: true},
+			},
+			expected: false,
+		},
+		{
+			name: "url.Error wrapping non-network error",
+			resp: nil,
+			err: &url.Error{
+				Op:  "Get",
+				URL: "http://example.com",
+				Err: errors.New("some other error"),
+			},
+			expected: true,
+		},
+		{
+			name: "url.Error wrapping context.DeadlineExceeded",
+			resp: nil,
+			err: &url.Error{
+				Op:  "Get",
+				URL: "http://example.com",
+				Err: context.DeadlineExceeded,
+			},
+			expected: false,
+		},
+		{
+			name: "url.Error wrapping context.Canceled",
+			resp: nil,
+			err: &url.Error{
+				Op:  "Get",
+				URL: "http://example.com",
+				Err: context.Canceled,
+			},
+			expected: true,
+		},
+		{
+			name:     "generic error (non-network)",
+			resp:     nil,
+			err:      errors.New("some random error"),
+			expected: true,
+		},
+		{
+			name:     "EOF error (non-network)",
+			resp:     nil,
+			err:      errors.New("EOF"),
+			expected: true,
+		},
+		{
+			name:     "nil response with nil error (edge case)",
+			resp:     nil,
+			err:      nil,
+			expected: false, // Will panic in real code, but resp.StatusCode access
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Handle the edge case where resp is nil and err is nil
+			if tt.resp == nil && tt.err == nil {
+				// This would panic in real code, so we skip the actual test
+				// In production, this should never happen
+				return
+			}
+
+			result := acceptable(tt.resp, tt.err)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestAcceptable_RealNetworkTimeout(t *testing.T) {
+	// Create a client with very short timeout
+	client := &http.Client{
+		Timeout: 1 * time.Nanosecond, // Extremely short timeout to force timeout error
+	}
+
+	service := NewServiceWithClient("test", client)
+
+	// Create a server that delays response
+	svr := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(100 * time.Millisecond)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer svr.Close()
+
+	req, err := http.NewRequest(http.MethodGet, svr.URL, nil)
+	assert.NoError(t, err)
+
+	// This should timeout and trigger the circuit breaker
+	resp, err := service.DoRequest(req)
+
+	// The error should be present due to timeout
+	assert.Error(t, err)
+	// Response might be nil due to timeout
+	if resp != nil {
+		t.Logf("Response status: %d", resp.StatusCode)
+	}
+}
+
+func TestAcceptable_Integration(t *testing.T) {
+	tests := []struct {
+		name          string
+		statusCode    int
+		expectBreaker bool // Whether breaker should consider this as failure
+	}{
+		{"200 OK should not trigger breaker", http.StatusOK, false},
+		{"201 Created should not trigger breaker", http.StatusCreated, false},
+		{"400 Bad Request should not trigger breaker", http.StatusBadRequest, false},
+		{"404 Not Found should not trigger breaker", http.StatusNotFound, false},
+		{"500 Internal Server Error should trigger breaker", http.StatusInternalServerError, true},
+		{"502 Bad Gateway should trigger breaker", http.StatusBadGateway, true},
+		{"503 Service Unavailable should trigger breaker", http.StatusServiceUnavailable, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			svr := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(tt.statusCode)
+			}))
+			defer svr.Close()
+
+			service := NewService("test-service-" + tt.name)
+			req, err := http.NewRequest(http.MethodGet, svr.URL, nil)
+			assert.NoError(t, err)
+
+			resp, err := service.DoRequest(req)
+			assert.NoError(t, err)
+			assert.Equal(t, tt.statusCode, resp.StatusCode)
+
+			// The actual breaker behavior is tested implicitly through the acceptable function
+			result := acceptable(resp, nil)
+			if tt.expectBreaker {
+				assert.False(t, result, "Status %d should not be acceptable", tt.statusCode)
+			} else {
+				assert.True(t, result, "Status %d should be acceptable", tt.statusCode)
+			}
+		})
+	}
+}

rest/router/patrouter.go

@@ -19,7 +19,7 @@ const (
 var (
 	// ErrInvalidMethod is an error that indicates not a valid http method.
 	ErrInvalidMethod = errors.New("not a valid http method")
-	// ErrInvalidPath is an error that indicates path is not start with /.
+	// ErrInvalidPath is an error that indicates path does not start with /.
 	ErrInvalidPath = errors.New("path must begin with '/'")
 )
 

tools/goctl/api/dartgen/vars.go

@@ -32,7 +32,7 @@ import '../vars/vars.dart';
 /// Send GET request.
 ///
 /// ok: the function that will be called on success.
-/// fail：the fuction that will be called on failure.
+/// fail：the function that will be called on failure.
 /// eventually：the function that will be called regardless of success or failure.
 Future apiGet(String path,
     {Map<String, String> header,
@@ -47,7 +47,7 @@ Future apiGet(String path,
 ///
 /// data: the data to post, it will be marshaled to json automatically.
 /// ok: the function that will be called on success.
-/// fail：the fuction that will be called on failure.
+/// fail：the function that will be called on failure.
 /// eventually：the function that will be called regardless of success or failure.
 Future apiPost(String path, dynamic data,
     {Map<String, String> header,
@@ -132,7 +132,7 @@ Future _apiRequest(String method, String path, dynamic data,
 	/// data: any request class that will be converted to json automatically
 	/// ok: is called when request succeeds
 	/// fail: is called when request fails
-	/// eventually: is always called until the nearby functions returns
+	/// eventually: is always called after the nearby function returns
 	Future apiPost(String path, dynamic data,
 			{Map<String, String>? header,
 			Function(Map<String, dynamic>)? ok,
@@ -146,7 +146,7 @@ Future _apiRequest(String method, String path, dynamic data,
 	///
 	/// ok: is called when request succeeds
 	/// fail: is called when request fails
-	/// eventually: is always called until the nearby functions returns
+	/// eventually: is always called after the nearby function returns
 	Future apiGet(String path,
 			{Map<String, String>? header,
 			Function(Map<String, dynamic>)? ok,

tools/goctl/api/docgen/gen.go

@@ -36,7 +36,7 @@ func DocCommand(_ *cobra.Command, _ []string) error {
 	}
 
 	if !pathx.FileExists(dir) {
-		return fmt.Errorf("dir %s not exsit", dir)
+		return fmt.Errorf("dir %s not exist", dir)
 	}
 
 	dir, err := filepath.Abs(dir)

tools/goctl/api/gogen/genhandlers.go

@@ -38,9 +38,11 @@ func genHandler(dir, rootPkg, projectPkg string, cfg *config.Config, group spec.
 	}
 
 	var builtinTemplate = handlerTemplate
+	var templateFile = handlerTemplateFile
 	sse := group.GetAnnotation("sse")
 	if sse == "true" {
 		builtinTemplate = sseHandlerTemplate
+		templateFile = sseHandlerTemplateFile
 	}
 
 	return genFile(fileGenConfig{
@@ -49,7 +51,7 @@ func genHandler(dir, rootPkg, projectPkg string, cfg *config.Config, group spec.
 		filename:        filename + ".go",
 		templateName:    "handlerTemplate",
 		category:        category,
-		templateFile:    handlerTemplateFile,
+		templateFile:    templateFile,
 		builtinTemplate: builtinTemplate,
 		data: map[string]any{
 			"PkgName":        pkgName,

tools/goctl/api/gogen/genlogic.go

@@ -61,9 +61,11 @@ func genLogicByRoute(dir, rootPkg, projectPkg string, cfg *config.Config, group
 
 	subDir := getLogicFolderPath(group, route)
 	builtinTemplate := logicTemplate
+	templateFile := logicTemplateFile
 	sse := group.GetAnnotation("sse")
 	if sse == "true" {
 		builtinTemplate = sseLogicTemplate
+		templateFile = sseLogicTemplateFile
 		responseString = "error"
 		returnString = "return nil"
 		resp := responseGoTypeName(route, typesPacket)
@@ -80,7 +82,7 @@ func genLogicByRoute(dir, rootPkg, projectPkg string, cfg *config.Config, group
 		filename:        goFile + ".go",
 		templateName:    "logicTemplate",
 		category:        category,
-		templateFile:    logicTemplateFile,
+		templateFile:    templateFile,
 		builtinTemplate: builtinTemplate,
 		data: map[string]any{
 			"pkgName":      subDir[strings.LastIndex(subDir, "/")+1:],

tools/goctl/api/gogen/gensse_test.go

@@ -0,0 +1,153 @@
+package gogen
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSSEGeneration(t *testing.T) {
+	// Create a temporary directory for test
+	dir := t.TempDir()
+
+	// Create a test API file with SSE annotation
+	apiContent := `syntax = "v1"
+
+type SseReq {
+    Message string ` + "`json:\"message\"`" + `
+}
+
+type SseResp {
+    Data string ` + "`json:\"data\"`" + `
+}
+
+@server (
+    sse: true
+)
+service Test {
+    @handler Sse
+    get /sse (SseReq) returns (SseResp)
+}
+`
+	apiFile := filepath.Join(dir, "test.api")
+	err := os.WriteFile(apiFile, []byte(apiContent), 0644)
+	assert.NoError(t, err)
+
+	// Generate code
+	err = DoGenProject(apiFile, dir, "gozero", false)
+	assert.NoError(t, err)
+
+	// Read generated handler file
+	handlerPath := filepath.Join(dir, "internal/handler/ssehandler.go")
+	handlerContent, err := os.ReadFile(handlerPath)
+	assert.NoError(t, err)
+
+	// Read generated logic file
+	logicPath := filepath.Join(dir, "internal/logic/sselogic.go")
+	logicContent, err := os.ReadFile(logicPath)
+	assert.NoError(t, err)
+
+	handlerStr := string(handlerContent)
+	logicStr := string(logicContent)
+
+	// Verify SSE-specific patterns in handler
+	// Handler should call: err := l.Sse(&req, client)
+	assert.Contains(t, handlerStr, "err := l.Sse(&req, client)",
+		"Handler should call logic with client channel parameter")
+
+	// Handler should NOT have the regular pattern: resp, err := l.Sse(&req)
+	assert.NotContains(t, handlerStr, "resp, err := l.Sse(&req)",
+		"Handler should not use regular pattern with resp return")
+
+	// Handler should use threading.GoSafeCtx
+	assert.Contains(t, handlerStr, "threading.GoSafeCtx",
+		"Handler should use threading.GoSafeCtx for SSE")
+
+	// Handler should create client channel
+	assert.Contains(t, handlerStr, "client := make(chan",
+		"Handler should create client channel")
+
+	// Verify SSE-specific patterns in logic
+	// Logic should have signature: Sse(req *types.SseReq, client chan<- *types.SseResp) error
+	assert.Contains(t, logicStr, "func (l *SseLogic) Sse(req *types.SseReq, client chan<- *types.SseResp) error",
+		"Logic should have SSE signature with client channel parameter")
+
+	// Logic should NOT have regular signature: Sse(req *types.SseReq) (resp *types.SseResp, err error)
+	assert.NotContains(t, logicStr, "(resp *types.SseResp, err error)",
+		"Logic should not have regular signature with resp return")
+}
+
+func TestNonSSEGeneration(t *testing.T) {
+	// Create a temporary directory for test
+	dir := t.TempDir()
+
+	// Create a test API file WITHOUT SSE annotation
+	apiContent := `syntax = "v1"
+
+type SseReq {
+    Message string ` + "`json:\"message\"`" + `
+}
+
+type SseResp {
+    Data string ` + "`json:\"data\"`" + `
+}
+
+service Test {
+    @handler Sse
+    get /sse (SseReq) returns (SseResp)
+}
+`
+	apiFile := filepath.Join(dir, "test.api")
+	err := os.WriteFile(apiFile, []byte(apiContent), 0644)
+	assert.NoError(t, err)
+
+	// Generate code
+	err = DoGenProject(apiFile, dir, "gozero", false)
+	assert.NoError(t, err)
+
+	// Read generated handler file
+	handlerPath := filepath.Join(dir, "internal/handler/ssehandler.go")
+	handlerContent, err := os.ReadFile(handlerPath)
+	assert.NoError(t, err)
+
+	// Read generated logic file
+	logicPath := filepath.Join(dir, "internal/logic/sselogic.go")
+	logicContent, err := os.ReadFile(logicPath)
+	assert.NoError(t, err)
+
+	handlerStr := string(handlerContent)
+	logicStr := string(logicContent)
+
+	// Verify regular (non-SSE) patterns in handler
+	// Handler should call: resp, err := l.Sse(&req)
+	assert.Contains(t, handlerStr, "resp, err := l.Sse(&req)",
+		"Handler should use regular pattern with resp return")
+
+	// Handler should NOT have SSE pattern: err := l.Sse(&req, client)
+	assert.NotContains(t, handlerStr, "err := l.Sse(&req, client)",
+		"Handler should not use SSE pattern")
+
+	// Handler should NOT use threading.GoSafeCtx
+	assert.NotContains(t, handlerStr, "threading.GoSafeCtx",
+		"Handler should not use threading.GoSafeCtx for regular routes")
+
+	// Verify regular (non-SSE) patterns in logic
+	// Logic should have signature: Sse(req *types.SseReq) (resp *types.SseResp, err error)
+	assert.Contains(t, logicStr, "(resp *types.SseResp, err error)",
+		"Logic should have regular signature with resp return")
+
+	// Logic should NOT have SSE signature with client parameter
+	linesToCheck := strings.Split(logicStr, "\n")
+	hasSSESignature := false
+	for _, line := range linesToCheck {
+		if strings.Contains(line, "func (l *SseLogic) Sse") && strings.Contains(line, "client chan<-") {
+			hasSSESignature = true
+			break
+		}
+	}
+	assert.False(t, hasSSESignature,
+		"Logic should not have SSE signature with client channel parameter")
+}

tools/goctl/api/gogen/integration_test.tpl

@@ -31,20 +31,16 @@ func TestServerIntegration(t *testing.T) {
 			Port: 0, // Use random available port
 		},
 	}
-	
+
 	server := rest.MustNewServer(c.RestConf)
 	defer server.Stop()
 
 	ctx := svc.NewServiceContext(c)
 	handler.RegisterHandlers(server, ctx)
 
-	// Start server in background
+	// Create serverless wrapper for testing
-	go func() {
+	serverless, err := rest.NewServerless(server)
-		server.Start()
+	require.NoError(t, err)
-	}()
-
-	// Wait for server to start
-	time.Sleep(100 * time.Millisecond)
 
 	tests := []struct {
 		name           string
@@ -56,7 +52,7 @@ func TestServerIntegration(t *testing.T) {
 	}{
 		{
 			name:           "health check",
-			method:         "GET",
+			method:         http.MethodGet,
 			path:           "/health",
 			expectedStatus: http.StatusNotFound, // Adjust based on actual routes
 			setup:          func() {},
@@ -72,7 +68,7 @@ func TestServerIntegration(t *testing.T) {
 		},
 		{{end}}{{end}}{
 			name:           "not found route",
-			method:         "GET", 
+			method:         http.MethodGet,
 			path:           "/nonexistent",
 			expectedStatus: http.StatusNotFound,
 			setup:          func() {},
@@ -87,10 +83,10 @@ func TestServerIntegration(t *testing.T) {
 			require.NoError(t, err)
 
 			rr := httptest.NewRecorder()
-			server.ServeHTTP(rr, req)
+			serverless.Serve(rr, req)
 
 			assert.Equal(t, tt.expectedStatus, rr.Code)
-			
+
 			// TODO: Add response body assertions
 			t.Logf("Response: %s", rr.Body.String())
 		})
@@ -100,13 +96,13 @@ func TestServerIntegration(t *testing.T) {
 func TestServerLifecycle(t *testing.T) {
 	c := config.Config{
 		RestConf: rest.RestConf{
-			Host: "127.0.0.1", 
+			Host: "127.0.0.1",
 			Port: 0,
 		},
 	}
 
 	server := rest.MustNewServer(c.RestConf)
-	
+
 	// Test server can start and stop without errors
 	ctx := svc.NewServiceContext(c)
 	handler.RegisterHandlers(server, ctx)

tools/goctl/api/parser/g4/ast/apiparser.go

@@ -28,7 +28,7 @@ type (
 		syntax                   *SyntaxExpr
 	}
 
-	// ParserOption defines an function with argument Parser
+	// ParserOption defines a function with argument Parser
 	ParserOption func(p *Parser)
 )
 

tools/goctl/api/parser/g4/ast/service.go

@@ -268,7 +268,7 @@ func (v *ApiVisitor) VisitReplybody(ctx *api.ReplybodyContext) any {
 				v.panic(lit.Expr(), fmt.Sprintf("expecting 'ID', but found golang keyword '%s'", lit.Expr().Text()))
 			}
 		default:
-			v.panic(dt.Expr(), fmt.Sprintf("unsupport %s", dt.Expr().Text()))
+			v.panic(dt.Expr(), fmt.Sprintf("unsupported %s", dt.Expr().Text()))
 		}
 	case *Literal:
 		lit := dataType.Literal.Text()
@@ -276,7 +276,7 @@ func (v *ApiVisitor) VisitReplybody(ctx *api.ReplybodyContext) any {
 			v.panic(dataType.Literal, fmt.Sprintf("expecting 'ID', but found golang keyword '%s'", lit))
 		}
 	default:
-		v.panic(dt.Expr(), fmt.Sprintf("unsupport %s", dt.Expr().Text()))
+		v.panic(dt.Expr(), fmt.Sprintf("unsupported %s", dt.Expr().Text()))
 	}
 
 	return &Body{

tools/goctl/api/parser/g4/ast/type.go

@@ -190,7 +190,7 @@ func (v *ApiVisitor) VisitTypeBlockStruct(ctx *api.TypeBlockStructContext) any {
 		structExpr := v.newExprWithToken(ctx.GetStructToken())
 		structTokenText := ctx.GetStructToken().GetText()
 		if structTokenText != "struct" {
-			v.panic(structExpr, fmt.Sprintf("expecting 'struct', found imput '%s'", structTokenText))
+			v.panic(structExpr, fmt.Sprintf("expecting 'struct', found input '%s'", structTokenText))
 		}
 
 		if api.IsGolangKeyWord(structTokenText, "struct") {

tools/goctl/api/parser/parser.go

@@ -18,7 +18,7 @@ type parser struct {
 }
 
 // Parse parses the api file.
-// Depreacted: use tools/goctl/pkg/parser/api/parser/parser.go:18 instead,
+// Deprecated: use tools/goctl/pkg/parser/api/parser/parser.go:18 instead,
 // it will be removed in the future.
 func Parse(filename string) (*spec.ApiSpec, error) {
 	if env.UseExperimental() {
@@ -63,14 +63,14 @@ func parseContent(content string, skipCheckTypeDeclaration bool, filename ...str
 	return apiSpec, nil
 }
 
-// Depreacted: use tools/goctl/pkg/parser/api/parser/parser.go:18 instead,
+// Deprecated: use tools/goctl/pkg/parser/api/parser/parser.go:18 instead,
 // it will be removed in the future.
 // ParseContent parses the api content
 func ParseContent(content string, filename ...string) (*spec.ApiSpec, error) {
 	return parseContent(content, false, filename...)
 }
 
-// Depreacted: use tools/goctl/pkg/parser/api/parser/parser.go:18 instead,
+// Deprecated: use tools/goctl/pkg/parser/api/parser/parser.go:18 instead,
 // it will be removed in the future.
 // ParseContentWithParserSkipCheckTypeDeclaration parses the api content with skip check type declaration
 func ParseContentWithParserSkipCheckTypeDeclaration(content string, filename ...string) (*spec.ApiSpec, error) {
@@ -227,7 +227,7 @@ func (p parser) astTypeToSpec(in ast.DataType) spec.Type {
 		return spec.PointerType{RawName: v.PointerExpr.Text(), Type: spec.DefineStruct{RawName: raw}}
 	}
 
-	panic(fmt.Sprintf("unspported type %+v", in))
+	panic(fmt.Sprintf("unsupported type %+v", in))
 }
 
 func (p parser) stringExprs(docs []ast.Expr) []string {

tools/goctl/api/swagger/annotation.go

@@ -24,10 +24,15 @@ func getFirstUsableString(def ...string) string {
 	}
 
 	for _, val := range def {
-		str, err := strconv.Unquote(val)
+		// Try to unquote if it's a quoted string
-		if err == nil && len(str) != 0 {
+		if str, err := strconv.Unquote(val); err == nil && len(str) != 0 {
 			return str
 		}
+
+		// Otherwise, use the value as-is if it's not empty
+		if len(val) != 0 {
+			return val
+		}
 	}
 
 	return ""

tools/goctl/api/swagger/annotation_test.go

@@ -89,3 +89,108 @@ func Test_getListFromInfoOrDefault(t *testing.T) {
 	assert.Equal(t, []string{"query"}, getListFromInfoOrDefault(unquotedProperties, "tags", []string{"default"}))
 	assert.Equal(t, []string{"default"}, getListFromInfoOrDefault(unquotedProperties, "empty", []string{"default"}))
 }
+
+func Test_getFirstUsableString(t *testing.T) {
+	t.Run("empty input", func(t *testing.T) {
+		result := getFirstUsableString()
+		assert.Equal(t, "", result, "should return empty string for no arguments")
+	})
+
+	t.Run("single plain string", func(t *testing.T) {
+		result := getFirstUsableString("Check server health status.")
+		assert.Equal(t, "Check server health status.", result)
+	})
+
+	t.Run("single quoted string", func(t *testing.T) {
+		// This is how Go would represent a quoted string literal
+		result := getFirstUsableString(`"Check server health status."`)
+		assert.Equal(t, "Check server health status.", result, "should unquote quoted strings")
+	})
+
+	t.Run("multiple plain strings", func(t *testing.T) {
+		result := getFirstUsableString("", "second", "third")
+		assert.Equal(t, "second", result, "should return first non-empty string")
+	})
+
+	t.Run("handler name fallback", func(t *testing.T) {
+		// Simulates the real use case: @doc text, handler name
+		result := getFirstUsableString("", "HealthCheck")
+		assert.Equal(t, "HealthCheck", result, "should fallback to handler name")
+	})
+
+	t.Run("doc text over handler name", func(t *testing.T) {
+		// Simulates the real use case with @doc text
+		result := getFirstUsableString("Check server health status.", "HealthCheck")
+		assert.Equal(t, "Check server health status.", result, "should use doc text over handler name")
+	})
+
+	t.Run("empty strings before valid", func(t *testing.T) {
+		result := getFirstUsableString("", "", "valid")
+		assert.Equal(t, "valid", result, "should skip empty strings")
+	})
+
+	t.Run("all empty strings", func(t *testing.T) {
+		result := getFirstUsableString("", "", "")
+		assert.Equal(t, "", result, "should return empty if all are empty")
+	})
+
+	t.Run("quoted then plain", func(t *testing.T) {
+		result := getFirstUsableString(`"quoted"`, "plain")
+		assert.Equal(t, "quoted", result, "should unquote first quoted string")
+	})
+
+	t.Run("plain then quoted", func(t *testing.T) {
+		result := getFirstUsableString("plain", `"quoted"`)
+		assert.Equal(t, "plain", result, "should use first plain string")
+	})
+
+	t.Run("invalid quoted string", func(t *testing.T) {
+		// String that looks quoted but isn't valid Go syntax
+		result := getFirstUsableString(`"incomplete`, "fallback")
+		assert.Equal(t, `"incomplete`, result, "should use as-is if unquote fails but not empty")
+	})
+
+	t.Run("whitespace only", func(t *testing.T) {
+		result := getFirstUsableString("   ", "fallback")
+		assert.Equal(t, "   ", result, "should not trim whitespace, return as-is")
+	})
+
+	t.Run("real world API doc scenario", func(t *testing.T) {
+		// This is the actual bug scenario from issue #5229
+		atDocText := "Check server health status."
+		handlerName := "HealthCheck"
+		
+		result := getFirstUsableString(atDocText, handlerName)
+		assert.Equal(t, "Check server health status.", result, 
+			"should use @doc text for API summary")
+	})
+
+	t.Run("real world with empty doc", func(t *testing.T) {
+		// When @doc is empty, should fall back to handler name
+		atDocText := ""
+		handlerName := "HealthCheck"
+		
+		result := getFirstUsableString(atDocText, handlerName)
+		assert.Equal(t, "HealthCheck", result, 
+			"should fallback to handler name when @doc is empty")
+	})
+
+	t.Run("complex summary with special characters", func(t *testing.T) {
+		result := getFirstUsableString("Get user by ID: /users/{id}")
+		assert.Equal(t, "Get user by ID: /users/{id}", result, 
+			"should handle special characters in plain strings")
+	})
+
+	t.Run("multiline string", func(t *testing.T) {
+		result := getFirstUsableString("Line 1\nLine 2")
+		assert.Equal(t, "Line 1\nLine 2", result, 
+			"should handle multiline strings")
+	})
+
+	t.Run("unicode characters", func(t *testing.T) {
+		result := getFirstUsableString("健康检查", "HealthCheck")
+		assert.Equal(t, "健康检查", result, 
+			"should handle unicode characters")
+	})
+}
+

tools/goctl/api/swagger/parameter.go

@@ -8,28 +8,37 @@ import (
 	apiSpec "github.com/zeromicro/go-zero/tools/goctl/api/spec"
 )
 
-func isPostJson(ctx Context, method string, tp apiSpec.Type) (string, bool) {
+func isRequestBodyJson(ctx Context, method string, tp apiSpec.Type) (string, bool) {
-	if !strings.EqualFold(method, http.MethodPost) {
+	// Support HTTP methods that commonly use request bodies with JSON
+	// POST, PUT, PATCH are standard methods with bodies
+	// DELETE can also have a body (though less common)
+	method = strings.ToUpper(method)
+	if method != http.MethodPost && method != http.MethodPut &&
+		method != http.MethodPatch && method != http.MethodDelete {
 		return "", false
 	}
+
 	structType, ok := tp.(apiSpec.DefineStruct)
 	if !ok {
 		return "", false
 	}
-	var isPostJson bool
+
+	var hasJsonField bool
 	rangeMemberAndDo(ctx, structType, func(tag *apiSpec.Tags, required bool, member apiSpec.Member) {
 		jsonTag, _ := tag.Get(tagJson)
-		if !isPostJson {
+		if !hasJsonField {
-			isPostJson = jsonTag != nil
+			hasJsonField = jsonTag != nil
 		}
 	})
-	return structType.RawName, isPostJson
+
+	return structType.RawName, hasJsonField
 }
 
 func parametersFromType(ctx Context, method string, tp apiSpec.Type) []spec.Parameter {
 	if tp == nil {
 		return []spec.Parameter{}
 	}
+
 	structType, ok := tp.(apiSpec.DefineStruct)
 	if !ok {
 		return []spec.Parameter{}
@@ -43,15 +52,13 @@ func parametersFromType(ctx Context, method string, tp apiSpec.Type) []spec.Para
 	rangeMemberAndDo(ctx, structType, func(tag *apiSpec.Tags, required bool, member apiSpec.Member) {
 		headerTag, _ := tag.Get(tagHeader)
 		hasHeader := headerTag != nil
-
 		pathParameterTag, _ := tag.Get(tagPath)
 		hasPathParameter := pathParameterTag != nil
-
 		formTag, _ := tag.Get(tagForm)
 		hasForm := formTag != nil
-
 		jsonTag, _ := tag.Get(tagJson)
 		hasJson := jsonTag != nil
+
 		if hasHeader {
 			minimum, maximum, exclusiveMinimum, exclusiveMaximum := rangeValueFromOptions(headerTag.Options)
 			resp = append(resp, spec.Parameter{
@@ -75,6 +82,7 @@ func parametersFromType(ctx Context, method string, tp apiSpec.Type) []spec.Para
 				},
 			})
 		}
+
 		if hasPathParameter {
 			minimum, maximum, exclusiveMinimum, exclusiveMaximum := rangeValueFromOptions(pathParameterTag.Options)
 			resp = append(resp, spec.Parameter{
@@ -98,6 +106,7 @@ func parametersFromType(ctx Context, method string, tp apiSpec.Type) []spec.Para
 				},
 			})
 		}
+
 		if hasForm {
 			minimum, maximum, exclusiveMinimum, exclusiveMaximum := rangeValueFromOptions(formTag.Options)
 			if strings.EqualFold(method, http.MethodGet) {
@@ -145,8 +154,8 @@ func parametersFromType(ctx Context, method string, tp apiSpec.Type) []spec.Para
 					},
 				})
 			}
-
 		}
+
 		if hasJson {
 			minimum, maximum, exclusiveMinimum, exclusiveMaximum := rangeValueFromOptions(jsonTag.Options)
 			if required {
@@ -179,9 +188,10 @@ func parametersFromType(ctx Context, method string, tp apiSpec.Type) []spec.Para
 			properties[jsonTag.Name] = schema
 		}
 	})
+
 	if len(properties) > 0 {
 		if ctx.UseDefinitions {
-			structName, ok := isPostJson(ctx, method, tp)
+			structName, ok := isRequestBodyJson(ctx, method, tp)
 			if ok {
 				resp = append(resp, spec.Parameter{
 					ParamProps: spec.ParamProps{
@@ -213,5 +223,6 @@ func parametersFromType(ctx Context, method string, tp apiSpec.Type) []spec.Para
 			})
 		}
 	}
+
 	return resp
 }

tools/goctl/api/swagger/parameter_test.go

@@ -8,7 +8,7 @@ import (
 	apiSpec "github.com/zeromicro/go-zero/tools/goctl/api/spec"
 )
 
-func TestIsPostJson(t *testing.T) {
+func TestIsRequestBodyJson(t *testing.T) {
 	tests := []struct {
 		name     string
 		method   string
@@ -18,13 +18,18 @@ func TestIsPostJson(t *testing.T) {
 		{"POST with JSON", http.MethodPost, true, true},
 		{"POST without JSON", http.MethodPost, false, false},
 		{"GET with JSON", http.MethodGet, true, false},
-		{"PUT with JSON", http.MethodPut, true, false},
+		{"PUT with JSON", http.MethodPut, true, true},
+		{"PUT without JSON", http.MethodPut, false, false},
+		{"PATCH with JSON", http.MethodPatch, true, true},
+		{"PATCH without JSON", http.MethodPatch, false, false},
+		{"DELETE with JSON", http.MethodDelete, true, true},
+		{"DELETE without JSON", http.MethodDelete, false, false},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			testStruct := createTestStruct("TestStruct", tt.hasJson)
-			_, result := isPostJson(testingContext(t), tt.method, testStruct)
+			_, result := isRequestBodyJson(testingContext(t), tt.method, testStruct)
 			assert.Equal(t, tt.expected, result)
 		})
 	}
@@ -41,6 +46,12 @@ func TestParametersFromType(t *testing.T) {
 	}{
 		{"POST JSON with definitions", http.MethodPost, true, true, 1, true},
 		{"POST JSON without definitions", http.MethodPost, false, true, 1, true},
+		{"PUT JSON with definitions", http.MethodPut, true, true, 1, true},
+		{"PUT JSON without definitions", http.MethodPut, false, true, 1, true},
+		{"PATCH JSON with definitions", http.MethodPatch, true, true, 1, true},
+		{"PATCH JSON without definitions", http.MethodPatch, false, true, 1, true},
+		{"DELETE JSON with definitions", http.MethodDelete, true, true, 1, true},
+		{"DELETE JSON without definitions", http.MethodDelete, false, true, 1, true},
 		{"GET with form", http.MethodGet, false, false, 1, false},
 		{"POST with form", http.MethodPost, false, false, 1, false},
 	}

tools/goctl/change.md

@@ -11,7 +11,7 @@
 ## swagger
 1. [bug fix] remove example generation when request body are `query`, `path` and `header`
 - it not supported in api spec 2.0
-- it's will generate example when request body is json format.
+- it will generate example when request body is json format.
 2. [features] swagger generation supported definitions
 - supported response definitions
 - supported json request body definitions

tools/goctl/docker/docker.go

@@ -73,6 +73,7 @@ func dockerCommand(_ *cobra.Command, _ []string) (err error) {
 
 	base := varStringBase
 	port := varIntPort
+	etcDir := filepath.Join(filepath.Dir(goFile), etcDir)
 	if _, err := os.Stat(etcDir); os.IsNotExist(err) {
 		return generateDockerfile(goFile, base, port, version, timezone)
 	}
@@ -170,7 +171,7 @@ func generateDockerfile(goFile, base string, port int, version, timezone string,
 	t := template.Must(template.New("dockerfile").Parse(text))
 	return t.Execute(out, Docker{
 		Chinese:     env.InChina(),
-		GoMainFrom:  path.Join(projPath, goFile),
+		GoMainFrom:  path.Join(projPath, filepath.Base(goFile)),
 		GoRelPath:   projPath,
 		GoFile:      goFile,
 		ExeFile:     exeName,

tools/goctl/docker/docker_test.go

@@ -0,0 +1,376 @@
+package docker
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestDockerCommand_EtcDirResolution(t *testing.T) {
+	// Create a temporary project structure
+	tempDir := t.TempDir()
+	
+	// Create project structure: project/service/api/
+	serviceDir := filepath.Join(tempDir, "service", "api")
+	etcDir := filepath.Join(serviceDir, "etc")
+	require.NoError(t, os.MkdirAll(etcDir, 0755))
+	
+	// Create a Go file
+	goFile := filepath.Join(serviceDir, "api.go")
+	require.NoError(t, os.WriteFile(goFile, []byte("package main\n\nfunc main() {}"), 0644))
+	
+	// Create a config file
+	configFile := filepath.Join(etcDir, "config.yaml")
+	require.NoError(t, os.WriteFile(configFile, []byte("Name: test\n"), 0644))
+	
+	// Create go.mod at the root
+	goModFile := filepath.Join(tempDir, "go.mod")
+	require.NoError(t, os.WriteFile(goModFile, []byte("module test\n\ngo 1.21\n"), 0644))
+	
+	// Test: etc directory should be found relative to Go file, not CWD
+	t.Run("etc directory resolved relative to go file", func(t *testing.T) {
+		// Save and restore original working directory
+		originalWd, err := os.Getwd()
+		require.NoError(t, err)
+		defer func() {
+			require.NoError(t, os.Chdir(originalWd))
+		}()
+		
+		// Change to temp directory (not service/api directory)
+		require.NoError(t, os.Chdir(tempDir))
+		
+		// The relative path from tempDir to the go file
+		relGoFile := filepath.Join("service", "api", "api.go")
+		
+		// Test the etc directory resolution logic
+		resolvedEtcDir := filepath.Join(filepath.Dir(relGoFile), "etc")
+		
+		// Verify the resolved path exists
+		_, err = os.Stat(resolvedEtcDir)
+		assert.NoError(t, err, "etc directory should be found at service/api/etc")
+		
+		// Verify it's the correct path (use EvalSymlinks to handle /private on macOS)
+		absResolvedEtc, err := filepath.Abs(resolvedEtcDir)
+		require.NoError(t, err)
+		absResolvedEtc, err = filepath.EvalSymlinks(absResolvedEtc)
+		require.NoError(t, err)
+		expectedEtc, err := filepath.EvalSymlinks(etcDir)
+		require.NoError(t, err)
+		assert.Equal(t, expectedEtc, absResolvedEtc)
+	})
+	
+	t.Run("etc directory with empty goFile", func(t *testing.T) {
+		// When goFile is empty, should default to "./etc"
+		goFile := ""
+		resolvedEtcDir := filepath.Join(filepath.Dir(goFile), "etc")
+		
+		// Should resolve to just "etc"
+		assert.Equal(t, "etc", resolvedEtcDir)
+	})
+	
+	t.Run("etc directory with absolute path", func(t *testing.T) {
+		// When goFile is absolute path
+		absGoFile := filepath.Join(tempDir, "service", "api", "api.go")
+		resolvedEtcDir := filepath.Join(filepath.Dir(absGoFile), "etc")
+		
+		// Should resolve correctly
+		_, err := os.Stat(resolvedEtcDir)
+		assert.NoError(t, err)
+	})
+}
+
+func TestGenerateDockerfile_GoMainFromPath(t *testing.T) {
+	tests := []struct {
+		name         string
+		goFile       string
+		projPath     string
+		expectedPath string
+	}{
+		{
+			name:         "relative path with subdirectory",
+			goFile:       "service/api/api.go",
+			projPath:     "service/api",
+			expectedPath: "service/api/api.go",
+		},
+		{
+			name:         "simple filename",
+			goFile:       "main.go",
+			projPath:     ".",
+			expectedPath: "main.go",
+		},
+		{
+			name:         "nested service path",
+			goFile:       "internal/service/user/user.go",
+			projPath:     "internal/service/user",
+			expectedPath: "internal/service/user/user.go",
+		},
+		{
+			name:         "deep nested path",
+			goFile:       "cmd/api/internal/handler/handler.go",
+			projPath:     "cmd/api/internal/handler",
+			expectedPath: "cmd/api/internal/handler/handler.go",
+		},
+	}
+	
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Simulate the fix: using filepath.Base instead of full path
+			goMainFrom := filepath.Join(tt.projPath, filepath.Base(tt.goFile))
+			
+			assert.Equal(t, tt.expectedPath, goMainFrom,
+				"GoMainFrom should not duplicate path segments")
+			
+			// Verify the old buggy behavior would have been wrong
+			if tt.goFile != filepath.Base(tt.goFile) {
+				buggyPath := filepath.Join(tt.projPath, tt.goFile)
+				assert.NotEqual(t, tt.expectedPath, buggyPath,
+					"Old implementation would have created incorrect path")
+			}
+		})
+	}
+}
+
+func TestGenerateDockerfile_PathJoinBehavior(t *testing.T) {
+	t.Run("demonstrates the bug and fix", func(t *testing.T) {
+		projPath := "service/api"
+		goFile := "service/api/api.go"
+		
+		// OLD (buggy) behavior: path duplication
+		buggyPath := filepath.Join(projPath, goFile)
+		assert.Equal(t, "service/api/service/api/api.go", buggyPath,
+			"Bug: path segments are duplicated")
+		
+		// NEW (fixed) behavior: correct path
+		fixedPath := filepath.Join(projPath, filepath.Base(goFile))
+		assert.Equal(t, "service/api/api.go", fixedPath,
+			"Fix: using filepath.Base prevents duplication")
+	})
+}
+
+func TestFindConfig(t *testing.T) {
+	tempDir := t.TempDir()
+	etcDir := filepath.Join(tempDir, "etc")
+	require.NoError(t, os.MkdirAll(etcDir, 0755))
+	
+	t.Run("finds config matching go file name", func(t *testing.T) {
+		// Create config files
+		require.NoError(t, os.WriteFile(
+			filepath.Join(etcDir, "api.yaml"), []byte("test"), 0644))
+		require.NoError(t, os.WriteFile(
+			filepath.Join(etcDir, "other.yaml"), []byte("test"), 0644))
+		
+		cfg, err := findConfig("api.go", etcDir)
+		assert.NoError(t, err)
+		assert.Equal(t, "api.yaml", cfg)
+	})
+	
+	t.Run("returns first config when no match", func(t *testing.T) {
+		etcDir2 := filepath.Join(tempDir, "etc2")
+		require.NoError(t, os.MkdirAll(etcDir2, 0755))
+		require.NoError(t, os.WriteFile(
+			filepath.Join(etcDir2, "config.yaml"), []byte("test"), 0644))
+		
+		cfg, err := findConfig("main.go", etcDir2)
+		assert.NoError(t, err)
+		assert.Equal(t, "config.yaml", cfg)
+	})
+	
+	t.Run("returns error when no yaml files", func(t *testing.T) {
+		emptyDir := filepath.Join(tempDir, "empty")
+		require.NoError(t, os.MkdirAll(emptyDir, 0755))
+		
+		_, err := findConfig("api.go", emptyDir)
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "no yaml file")
+	})
+	
+	t.Run("handles path in go file name", func(t *testing.T) {
+		// Test with service/api/api.go - should extract just "api"
+		cfg, err := findConfig("service/api/api.go", etcDir)
+		assert.NoError(t, err)
+		assert.Equal(t, "api.yaml", cfg)
+	})
+}
+
+func TestGetFilePath(t *testing.T) {
+	// Create a temporary directory with go.mod
+	tempDir := t.TempDir()
+	require.NoError(t, os.WriteFile(
+		filepath.Join(tempDir, "go.mod"),
+		[]byte("module testproject\n\ngo 1.21\n"),
+		0644,
+	))
+	
+	// Create subdirectories
+	serviceDir := filepath.Join(tempDir, "service", "api")
+	require.NoError(t, os.MkdirAll(serviceDir, 0755))
+	
+	originalWd, err := os.Getwd()
+	require.NoError(t, err)
+	defer func() {
+		require.NoError(t, os.Chdir(originalWd))
+	}()
+	
+	t.Run("returns relative path from go.mod", func(t *testing.T) {
+		require.NoError(t, os.Chdir(tempDir))
+		
+		path, err := getFilePath("service/api")
+		assert.NoError(t, err)
+		assert.Equal(t, "service/api", path)
+	})
+	
+	t.Run("handles current directory", func(t *testing.T) {
+		require.NoError(t, os.Chdir(tempDir))
+		
+		path, err := getFilePath(".")
+		assert.NoError(t, err)
+		// Current directory returns empty string when at go.mod root
+		assert.True(t, path == "." || path == "")
+	})
+}
+
+// Integration test to verify the complete fix
+func TestDockerCommandIntegration(t *testing.T) {
+	// Create a complete project structure
+	tempDir := t.TempDir()
+	
+	// Setup: project/service/api/
+	serviceDir := filepath.Join(tempDir, "service", "api")
+	etcDir := filepath.Join(serviceDir, "etc")
+	require.NoError(t, os.MkdirAll(etcDir, 0755))
+	
+	// Create files
+	goFile := filepath.Join(serviceDir, "api.go")
+	require.NoError(t, os.WriteFile(goFile, []byte("package main\n\nfunc main() {}"), 0644))
+	configFile := filepath.Join(etcDir, "api.yaml")
+	require.NoError(t, os.WriteFile(configFile, []byte("Name: test-api\n"), 0644))
+	goModFile := filepath.Join(tempDir, "go.mod")
+	require.NoError(t, os.WriteFile(goModFile, []byte("module testproject\n\ngo 1.21\n"), 0644))
+	goSumFile := filepath.Join(tempDir, "go.sum")
+	require.NoError(t, os.WriteFile(goSumFile, []byte(""), 0644))
+	
+	originalWd, err := os.Getwd()
+	require.NoError(t, err)
+	defer func() {
+		require.NoError(t, os.Chdir(originalWd))
+	}()
+	
+	t.Run("etc directory detected from different working directory", func(t *testing.T) {
+		// Change to project root (not service/api)
+		require.NoError(t, os.Chdir(tempDir))
+		
+		// Relative path to Go file
+		relGoFile := filepath.Join("service", "api", "api.go")
+		
+		// Apply the fix: resolve etc directory relative to go file
+		resolvedEtcDir := filepath.Join(filepath.Dir(relGoFile), "etc")
+		
+		// Verify etc directory is found
+		stat, err := os.Stat(resolvedEtcDir)
+		assert.NoError(t, err)
+		assert.True(t, stat.IsDir())
+		
+		// Verify config can be found
+		cfg, err := findConfig(relGoFile, resolvedEtcDir)
+		assert.NoError(t, err)
+		assert.Equal(t, "api.yaml", cfg)
+	})
+	
+	t.Run("GoMainFrom path is correct", func(t *testing.T) {
+		require.NoError(t, os.Chdir(tempDir))
+		
+		goFileRel := filepath.Join("service", "api", "api.go")
+		
+		// Simulate getFilePath return value
+		projPath := "service/api"
+		
+		// Apply the fix: use filepath.Base
+		goMainFrom := filepath.Join(projPath, filepath.Base(goFileRel))
+		
+		assert.Equal(t, "service/api/api.go", goMainFrom)
+		
+		// Verify no path duplication
+		assert.NotContains(t, goMainFrom, "service/api/service/api")
+	})
+}
+
+// Test that specifically validates the bug described in PR #4343
+func TestPR4343_BugFixes(t *testing.T) {
+	t.Run("Bug 1: etc directory check uses correct base path", func(t *testing.T) {
+		// Setup: Create a project structure where etc is NOT in CWD but IS relative to Go file
+		tempDir := t.TempDir()
+		serviceDir := filepath.Join(tempDir, "service", "api")
+		etcDir := filepath.Join(serviceDir, "etc")
+		require.NoError(t, os.MkdirAll(etcDir, 0755))
+		
+		// Create a config file
+		require.NoError(t, os.WriteFile(
+			filepath.Join(etcDir, "config.yaml"),
+			[]byte("Name: test\n"),
+			0644,
+		))
+		
+		originalWd, err := os.Getwd()
+		require.NoError(t, err)
+		defer func() {
+			require.NoError(t, os.Chdir(originalWd))
+		}()
+		
+		// Change to project root (CWD = tempDir)
+		require.NoError(t, os.Chdir(tempDir))
+		
+		goFile := filepath.Join("service", "api", "api.go")
+		
+		// OLD (buggy) behavior: checks for "etc" in CWD
+		_, errOld := os.Stat("etc")
+		assert.Error(t, errOld, "Bug: etc not found in CWD")
+		
+		// NEW (fixed) behavior: checks for "etc" relative to go file
+		etcDirResolved := filepath.Join(filepath.Dir(goFile), "etc")
+		stat, errNew := os.Stat(etcDirResolved)
+		assert.NoError(t, errNew, "Fix: etc found relative to go file")
+		assert.True(t, stat.IsDir())
+		
+		// Verify config is accessible
+		cfg, err := findConfig(goFile, etcDirResolved)
+		assert.NoError(t, err)
+		assert.Equal(t, "config.yaml", cfg)
+	})
+	
+	t.Run("Bug 2: GoMainFrom path not duplicated", func(t *testing.T) {
+		// Test case from PR description
+		projPath := "service/api"
+		goFile := "service/api/api.go"
+		
+		// OLD (buggy) behavior: duplicates path
+		buggyPath := filepath.Join(projPath, goFile)
+		assert.Equal(t, "service/api/service/api/api.go", buggyPath,
+			"Bug: path duplication occurs with old implementation")
+		
+		// NEW (fixed) behavior: correct path using filepath.Base
+		fixedPath := filepath.Join(projPath, filepath.Base(goFile))
+		assert.Equal(t, "service/api/api.go", fixedPath,
+			"Fix: using filepath.Base() prevents path duplication")
+		
+		// Verify the fix works for various scenarios
+		testCases := []struct {
+			projPath string
+			goFile   string
+			expected string
+		}{
+			{"service/api", "service/api/api.go", "service/api/api.go"},
+			{"cmd/server", "cmd/server/main.go", "cmd/server/main.go"},
+			{"internal/handler", "internal/handler/handler.go", "internal/handler/handler.go"},
+			{".", "main.go", "main.go"},
+		}
+		
+		for _, tc := range testCases {
+			result := filepath.Join(tc.projPath, filepath.Base(tc.goFile))
+			assert.Equal(t, tc.expected, result,
+				"Fix should work for projPath=%s, goFile=%s", tc.projPath, tc.goFile)
+		}
+	})
+}

tools/goctl/go.mod

@@ -1,25 +1,25 @@
 module github.com/zeromicro/go-zero/tools/goctl
 
-go 1.21
+go 1.23
 
 require (
 	github.com/DATA-DOG/go-sqlmock v1.5.2
-	github.com/emicklei/proto v1.14.2
+	github.com/emicklei/proto v1.14.3
 	github.com/fatih/structtag v1.2.0
 	github.com/go-openapi/spec v0.21.1-0.20250328170532-a3928469592e
-	github.com/go-sql-driver/mysql v1.9.0
+	github.com/go-sql-driver/mysql v1.9.3
 	github.com/gookit/color v1.6.0
 	github.com/iancoleman/strcase v0.3.0
-	github.com/spf13/cobra v1.10.1
+	github.com/spf13/cobra v1.10.2
 	github.com/spf13/pflag v1.0.10
 	github.com/stretchr/testify v1.11.1
 	github.com/withfig/autocomplete-tools/integrations/cobra v1.2.1
 	github.com/zeromicro/antlr v0.0.1
 	github.com/zeromicro/ddl-parser v1.0.5
-	github.com/zeromicro/go-zero v1.9.1
+	github.com/zeromicro/go-zero v1.9.4
 	golang.org/x/text v0.22.0
 	google.golang.org/grpc v1.65.0
-	google.golang.org/protobuf v1.36.5
+	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v2 v2.4.0
 )
 
@@ -44,7 +44,7 @@ require (
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/google/gnostic-models v0.6.8 // indirect
-	github.com/google/go-cmp v0.6.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/grafana/pyroscope-go v1.2.7 // indirect
@@ -72,7 +72,7 @@ require (
 	github.com/prometheus/client_model v0.6.1 // indirect
 	github.com/prometheus/common v0.62.0 // indirect
 	github.com/prometheus/procfs v0.15.1 // indirect
-	github.com/redis/go-redis/v9 v9.15.0 // indirect
+	github.com/redis/go-redis/v9 v9.17.2 // indirect
 	github.com/spaolacci/murmur3 v1.1.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yuin/gopher-lua v1.1.1 // indirect

tools/goctl/go.sum

@@ -30,8 +30,8 @@ github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/r
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
 github.com/emicklei/go-restful/v3 v3.11.0 h1:rAQeMHw1c7zTmncogyy8VvRZwtkmkZ4FxERmMY4rD+g=
 github.com/emicklei/go-restful/v3 v3.11.0/go.mod h1:6n3XBCmQQb25CM2LCACGz8ukIrRry+4bhvbpWn3mrbc=
-github.com/emicklei/proto v1.14.2 h1:wJPxPy2Xifja9cEMrcA/g08art5+7CGJNFNk35iXC1I=
+github.com/emicklei/proto v1.14.3 h1:zEhlzNkpP8kN6utonKMzlPfIvy82t5Kb9mufaJxSe1Q=
-github.com/emicklei/proto v1.14.2/go.mod h1:rn1FgRS/FANiZdD2djyH7TMA9jdRDcYQ9IEN9yvjX0A=
+github.com/emicklei/proto v1.14.3/go.mod h1:rn1FgRS/FANiZdD2djyH7TMA9jdRDcYQ9IEN9yvjX0A=
 github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
 github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
 github.com/fatih/structtag v1.2.0 h1:/OdNE99OxoI/PqaW/SuSK9uxxT3f/tcSZgon/ssNSx4=
@@ -50,8 +50,8 @@ github.com/go-openapi/spec v0.21.1-0.20250328170532-a3928469592e h1:auobAirzhPsL
 github.com/go-openapi/spec v0.21.1-0.20250328170532-a3928469592e/go.mod h1:NAKTe9SplQBxIUlHlsuId1jk1I7bWTVV/2q/GtdRi6g=
 github.com/go-openapi/swag v0.23.1 h1:lpsStH0n2ittzTnbaSloVZLuB5+fvSY/+hnagBjSNZU=
 github.com/go-openapi/swag v0.23.1/go.mod h1:STZs8TbRvEQQKUA+JZNAm3EWlgaOBGpyFDqQnDHMef0=
-github.com/go-sql-driver/mysql v1.9.0 h1:Y0zIbQXhQKmQgTp44Y1dp3wTXcn804QoTptLZT1vtvo=
+github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo=
-github.com/go-sql-driver/mysql v1.9.0/go.mod h1:pDetrLJeA3oMujJuvXc8RJoasr589B6A9fwzD3QMrqw=
+github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
 github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 h1:tfuBGBXKqDEevZMzYi5KSi8KkcZtzBcTgAUUtapy0OI=
 github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572/go.mod h1:9Pwr4B2jHnOSGXyyzV8ROjYa2ojvAY6HCGYYfMoC3Ls=
 github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
@@ -62,8 +62,8 @@ github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6
 github.com/google/gnostic-models v0.6.8 h1:yo/ABAfM5IMRsS1VnXjTBvUb61tFIHozhlYvRgGre9I=
 github.com/google/gnostic-models v0.6.8/go.mod h1:5n7qKqH0f5wFt+aWF8CW6pZLLNOfYuF5OpfBSENuI8U=
 github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/gofuzz v1.2.0 h1:xRy4A+RhZaiKjJ1bPfwQ8sedCA+YS2YcCHW6ec7JMi0=
 github.com/google/gofuzz v1.2.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
@@ -148,15 +148,15 @@ github.com/prometheus/common v0.62.0 h1:xasJaQlnWAeyHdUBeGjXmutelfJHWMRr+Fg4QszZ
 github.com/prometheus/common v0.62.0/go.mod h1:vyBcEuLSvWos9B1+CyL7JZ2up+uFzXhkqml0W5zIY1I=
 github.com/prometheus/procfs v0.15.1 h1:YagwOFzUgYfKKHX6Dr+sHT7km/hxC76UB0learggepc=
 github.com/prometheus/procfs v0.15.1/go.mod h1:fB45yRUv8NstnjriLhBQLuOUt+WW4BsoGhij/e3PBqk=
-github.com/redis/go-redis/v9 v9.15.0 h1:2jdes0xJxer4h3NUZrZ4OGSntGlXp4WbXju2nOTRXto=
+github.com/redis/go-redis/v9 v9.17.2 h1:P2EGsA4qVIM3Pp+aPocCJ7DguDHhqrXNhVcEp4ViluI=
-github.com/redis/go-redis/v9 v9.15.0/go.mod h1:huWgSWd8mW6+m0VPhJjSSQ+d6Nh1VICQ6Q5lHuCH/Iw=
+github.com/redis/go-redis/v9 v9.17.2/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370=
 github.com/rogpeppe/go-internal v1.11.0 h1:cWPaGQEPrBb5/AsnsZesgZZ9yb1OQ+GOISoDNXVBh4M=
 github.com/rogpeppe/go-internal v1.11.0/go.mod h1:ddIwULY96R17DhadqLgMfk9H9tvdUzkipdSkR5nkCZA=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spaolacci/murmur3 v1.1.0 h1:7c1g84S4BPRrfL5Xrdp6fOJ206sU9y293DDHaoy0bLI=
 github.com/spaolacci/murmur3 v1.1.0/go.mod h1:JwIasOWyU6f++ZhiEuf87xNszmSA2myDM2Kzu9HwQUA=
-github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
-github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
@@ -185,8 +185,8 @@ github.com/zeromicro/antlr v0.0.1 h1:CQpIn/dc0pUjgGQ81y98s/NGOm2Hfru2NNio2I9mQgk
 github.com/zeromicro/antlr v0.0.1/go.mod h1:nfpjEwFR6Q4xGDJMcZnCL9tEfQRgszMwu3rDz2Z+p5M=
 github.com/zeromicro/ddl-parser v1.0.5 h1:LaVqHdzMTjasua1yYpIYaksxKqRzFrEukj2Wi2EbWaQ=
 github.com/zeromicro/ddl-parser v1.0.5/go.mod h1:ISU/8NuPyEpl9pa17Py9TBPetMjtsiHrb9f5XGiYbo8=
-github.com/zeromicro/go-zero v1.9.1 h1:GZCl4jun/ZgZHnSvX3SSNDHf+tEGmEQ8x2Z23xjHa9g=
+github.com/zeromicro/go-zero v1.9.4 h1:aRLFoISqAYijABtkbliQC5SsI5TbizJpQvoHc9xup8k=
-github.com/zeromicro/go-zero v1.9.1/go.mod h1:bHOl7Xr7EV/iHZWEqsUNJwFc/9WgAMrPpPagYvOaMtY=
+github.com/zeromicro/go-zero v1.9.4/go.mod h1:a17JOTch25SWxBcUgJZYps60hygK3pIYdw7nGwlcS38=
 go.etcd.io/etcd/api/v3 v3.5.15 h1:3KpLJir1ZEBrYuV2v+Twaa/e2MdDCEZ/70H+lzEiwsk=
 go.etcd.io/etcd/api/v3 v3.5.15/go.mod h1:N9EhGzXq58WuMllgH9ZvnEr7SI9pS0k0+DHZezGp7jM=
 go.etcd.io/etcd/client/pkg/v3 v3.5.15 h1:fo0HpWz/KlHGMCC+YejpiCmyWDEuIpnTDzpJLB5fWlA=
@@ -227,6 +227,7 @@ go.uber.org/multierr v1.9.0 h1:7fIwc/ZtS0q++VgcfqFDxSBZVv/Xo49/SYnDFupUwlI=
 go.uber.org/multierr v1.9.0/go.mod h1:X2jQV1h+kxSjClGpnseKVIxpmcjrj7MNnI0bnlfKTVQ=
 go.uber.org/zap v1.24.0 h1:FiJd5l1UOLj0wCgbSE0rwwXHzEdAZS6hiiSnxJN/D60=
 go.uber.org/zap v1.24.0/go.mod h1:2kMP+WWQ8aoFoedH3T2sq6iJ2yDWpHbP0f6MQbS9Gkg=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
@@ -280,8 +281,8 @@ google.golang.org/genproto/googleapis/rpc v0.0.0-20240711142825-46eb208f015d h1:
 google.golang.org/genproto/googleapis/rpc v0.0.0-20240711142825-46eb208f015d/go.mod h1:Ue6ibwXGpU+dqIcODieyLOcgj7z8+IcskoNIgZxtrFY=
 google.golang.org/grpc v1.65.0 h1:bs/cUb4lp1G5iImFFd3u5ixQzweKizoZJAwBNLR42lc=
 google.golang.org/grpc v1.65.0/go.mod h1:WgYC2ypjlB0EiQi6wdKixMqukr6lBc0Vo+oOgjrM5ZQ=
-google.golang.org/protobuf v1.36.5 h1:tPhr+woSbjfYvY6/GPufUoYizxw1cF/yFoxJ2fmpwlM=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
-google.golang.org/protobuf v1.36.5/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

tools/goctl/internal/version/version.go

@@ -6,7 +6,7 @@ import (
 )
 
 // BuildVersion is the version of goctl.
-const BuildVersion = "1.9.1"
+const BuildVersion = "1.9.2"
 
 var tag = map[string]int{"pre-alpha": 0, "alpha": 1, "pre-beta": 2, "beta": 3, "released": 4, "": 5}
 

tools/goctl/model/sql/test/sqlconn.go

@@ -99,12 +99,12 @@ func (conn *MockConn) RawDB() (*sql.DB, error) {
 	return conn.db, nil
 }
 
-// Transact is the implemention of sqlx.SqlConn, nothing to do
+// Transact is the implementation of sqlx.SqlConn, nothing to do
 func (conn *MockConn) Transact(func(session sqlx.Session) error) error {
 	return nil
 }
 
-// TransactCtx is the implemention of sqlx.SqlConn, nothing to do
+// TransactCtx is the implementation of sqlx.SqlConn, nothing to do
 func (conn *MockConn) TransactCtx(ctx context.Context, fn func(context.Context, sqlx.Session) error) error {
 	return nil
 }

tools/goctl/rpc/README.md

@@ -53,7 +53,7 @@ Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持prot
 ```Bash
 $ goctl rpc template -o=user.proto
 ```
-  
+
 ```proto
 syntax = "proto3";
 
@@ -72,7 +72,7 @@ service User {
   rpc Ping(Request) returns(Response);
 }
 ```
-  
+
 
 * 生成rpc服务代码
 
@@ -96,15 +96,16 @@ Examples:
 goctl rpc protoc xx.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=.
 
 Flags:
-      --branch string     The branch of the remote repo, it does work with --remote
+      --branch string            The branch of the remote repo, it does work with --remote
-  -h, --help              help for protoc
+  -h, --help                     help for protoc
-      --home string       The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority
+      --home string              The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority
-  -m, --multiple          Generated in multiple rpc service mode
+  -m, --multiple                 Generated in multiple rpc service mode
-      --remote string     The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority
+      --name-from-filename       Use proto filename instead of package name for service naming (legacy behavior)
-                          	The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
+      --remote string            The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority
-      --style string      The file naming format, see [https://github.com/zeromicro/go-zero/tree/master/tools/goctl/config/readme.md] (default "gozero")
+                                 	The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
-  -v, --verbose           Enable log output
+      --style string             The file naming format, see [https://github.com/zeromicro/go-zero/tree/master/tools/goctl/config/readme.md] (default "gozero")
-      --zrpc_out string   The zrpc output directory
+  -v, --verbose                  Enable log output
+      --zrpc_out string          The zrpc output directory
 ```
 
 ### 参数说明
@@ -112,19 +113,43 @@ Flags:
 * --branch 指定远程仓库模板分支
 * --home 指定goctl模板根目录
 * -m, --multiple 指定生成多个rpc服务模式, 默认为 false, 如果为  false, 则只支持生成一个rpc service, 如果为 true, 则支持生成多个 rpc service，且多个 rpc service 会分组。
+* --name-from-filename 使用proto文件名而非package名称来命名服务（旧版行为）。默认使用package名称，这样可以支持多个proto文件共享同一个package。
 * --style 指定文件输出格式
 * -v, --verbose 显示日志
 * --zrpc_out 指定zrpc输出目录
 
 > ## --multiple
 > 是否开启多个 rpc service 生成，如果开启，则满足一下新特性
-> 1. 支持 1 到多个 rpc service 
+> 1. 支持 1 到多个 rpc service
 > 2. 生成 rpc 服务会按照服务名称分组（尽管只有一个 rpc service）
 > 3. rpc client 的文件目录变更为固定名称 `client`
-> 
+>
 > 如果不开启，则和旧版本 rpc 生成逻辑一样（兼容）
 > 1. 有且只能有一个 rpc service
 
+> ## Service Naming (Multi-Proto File Support)
+>
+> By default, the service name is derived from the **proto package name** (e.g., `package user;` → service name `user`).
+> This enables splitting a large proto file into multiple smaller files that share the same package name,
+> which is particularly useful for AI-assisted development where smaller files are easier to process.
+>
+> **Example: Multiple proto files with same package**
+> ```
+> protos/
+> ├── user_base.proto      # package user;
+> ├── user_auth.proto      # package user;
+> └── user_profile.proto   # package user;
+> ```
+> All three files will generate into a single `user` service.
+>
+> **Legacy behavior (--name-from-filename)**
+>
+> If you need the old behavior where service name is derived from the proto filename,
+> use the `--name-from-filename` flag:
+> ```bash
+> goctl rpc protoc user.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=. --name-from-filename
+> ```
+
 
 ## rpc 服务生成 example
 详情见 [example/rpc](https://github.com/zeromicro/go-zero/tree/master/tools/goctl/example)

tools/goctl/rpc/cli/cli.go

@@ -48,6 +48,9 @@ var (
 	VarBoolClient bool
 	// VarStringModule describes the module name for go.mod.
 	VarStringModule string
+	// VarBoolNameFromFilename describes whether to derive service name from proto filename
+	// instead of the proto package name. Default is false (uses package name).
+	VarBoolNameFromFilename bool
 )
 
 // RPCNew is to generate rpc greet service, this greet service can speed
@@ -94,6 +97,7 @@ func RPCNew(_ *cobra.Command, args []string) error {
 	ctx.ProtocCmd = fmt.Sprintf("protoc -I=%s %s --go_out=%s --go-grpc_out=%s", filepath.Dir(src), filepath.Base(src), filepath.Dir(src), filepath.Dir(src))
 	ctx.IsGenClient = VarBoolClient
 	ctx.Module = VarStringModule
+	ctx.NameFromFilename = VarBoolNameFromFilename
 
 	grpcOptList := VarStringSliceGoGRPCOpt
 	if len(grpcOptList) > 0 {

tools/goctl/rpc/cli/zrpc.go

@@ -104,6 +104,7 @@ func ZRPC(_ *cobra.Command, args []string) error {
 	ctx.ProtocCmd = strings.Join(protocArgs, " ")
 	ctx.IsGenClient = VarBoolClient
 	ctx.Module = VarStringModule
+	ctx.NameFromFilename = VarBoolNameFromFilename
 	g := generator.NewGenerator(style, verbose)
 	return g.Generate(&ctx)
 }

tools/goctl/rpc/cmd.go

@@ -42,6 +42,7 @@ func init() {
 	newCmdFlags.StringVar(&cli.VarStringBranch, "branch")
 	newCmdFlags.StringVar(&cli.VarStringModule, "module")
 	newCmdFlags.BoolVarP(&cli.VarBoolVerbose, "verbose", "v")
+	newCmdFlags.BoolVar(&cli.VarBoolNameFromFilename, "name-from-filename")
 	newCmdFlags.MarkHidden("go_opt")
 	newCmdFlags.MarkHidden("go-grpc_opt")
 	newCmdFlags.BoolVarPWithDefaultValue(&cli.VarBoolClient, "client", "c", true)
@@ -60,6 +61,7 @@ func init() {
 	protocCmdFlags.StringVar(&cli.VarStringBranch, "branch")
 	protocCmdFlags.StringVar(&cli.VarStringModule, "module")
 	protocCmdFlags.BoolVarP(&cli.VarBoolVerbose, "verbose", "v")
+	protocCmdFlags.BoolVar(&cli.VarBoolNameFromFilename, "name-from-filename")
 	protocCmdFlags.MarkHidden("go_out")
 	protocCmdFlags.MarkHidden("go-grpc_out")
 	protocCmdFlags.MarkHidden("go_opt")

tools/goctl/rpc/generator/gen.go

@@ -32,6 +32,9 @@ type ZRpcContext struct {
 	IsGenClient bool
 	// Module is the custom module name for go.mod
 	Module string
+	// NameFromFilename uses proto filename instead of package name for service naming.
+	// Default is false (uses package name, which supports multi-proto files).
+	NameFromFilename bool
 }
 
 // Generate generates a rpc service, through the proto file,

tools/goctl/rpc/generator/mkdir.go

@@ -199,7 +199,9 @@ func mkdir(ctx *ctx.ProjectContext, proto parser.Proto, conf *conf.Config, c *ZR
 			return nil, err
 		}
 	}
-	serviceName := strings.TrimSuffix(proto.Name, filepath.Ext(proto.Name))
+
+	serviceName := determineServiceName(proto, c)
+
 	return &defaultDirContext{
 		ctx:         ctx,
 		inner:       inner,
@@ -270,3 +272,16 @@ func (d *defaultDirContext) GetServiceName() stringx.String {
 func (d *Dir) Valid() bool {
 	return len(d.Filename) > 0 && len(d.Package) > 0
 }
+
+// determineServiceName returns the service name based on the proto file and context.
+// By default, it uses the proto package name (supports multi-proto files).
+// Falls back to filename if --name-from-filename flag is set or package name is empty.
+func determineServiceName(proto parser.Proto, c *ZRpcContext) string {
+	if c != nil && c.NameFromFilename {
+		return strings.TrimSuffix(proto.Name, filepath.Ext(proto.Name))
+	}
+	if proto.Package.Package != nil && len(proto.Package.Name) > 0 {
+		return proto.Package.Name
+	}
+	return strings.TrimSuffix(proto.Name, filepath.Ext(proto.Name))
+}

tools/goctl/rpc/generator/mkdir_test.go

@@ -0,0 +1,147 @@
+package generator
+
+import (
+	"testing"
+
+	"github.com/emicklei/proto"
+	"github.com/stretchr/testify/assert"
+	"github.com/zeromicro/go-zero/tools/goctl/rpc/parser"
+)
+
+func TestServiceNameDetermination(t *testing.T) {
+	tests := []struct {
+		name             string
+		protoName        string
+		packageName      string
+		hasPackage       bool
+		nameFromFilename bool
+		expectedName     string
+	}{
+		{
+			name:             "default uses package name when available",
+			protoName:        "user.proto",
+			packageName:      "userservice",
+			hasPackage:       true,
+			nameFromFilename: false,
+			expectedName:     "userservice",
+		},
+		{
+			name:             "flag enabled uses filename instead of package",
+			protoName:        "user.proto",
+			packageName:      "userservice",
+			hasPackage:       true,
+			nameFromFilename: true,
+			expectedName:     "user",
+		},
+		{
+			name:             "fallback to filename when package is empty",
+			protoName:        "order.proto",
+			packageName:      "",
+			hasPackage:       true,
+			nameFromFilename: false,
+			expectedName:     "order",
+		},
+		{
+			name:             "fallback to filename when package is nil",
+			protoName:        "product.proto",
+			packageName:      "",
+			hasPackage:       false,
+			nameFromFilename: false,
+			expectedName:     "product",
+		},
+		{
+			name:             "flag enabled with nil package uses filename",
+			protoName:        "catalog.proto",
+			packageName:      "",
+			hasPackage:       false,
+			nameFromFilename: true,
+			expectedName:     "catalog",
+		},
+		{
+			name:             "handles proto file with complex name",
+			protoName:        "user-service.proto",
+			packageName:      "user",
+			hasPackage:       true,
+			nameFromFilename: false,
+			expectedName:     "user",
+		},
+		{
+			name:             "handles proto file with complex name and flag",
+			protoName:        "user-service.proto",
+			packageName:      "user",
+			hasPackage:       true,
+			nameFromFilename: true,
+			expectedName:     "user-service",
+		},
+		{
+			name:             "nil context uses package name",
+			protoName:        "account.proto",
+			packageName:      "accountpb",
+			hasPackage:       true,
+			nameFromFilename: false,
+			expectedName:     "accountpb",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Build the proto struct
+			p := parser.Proto{
+				Name: tt.protoName,
+			}
+			if tt.hasPackage {
+				p.Package = parser.Package{
+					Package: &proto.Package{
+						Name: tt.packageName,
+					},
+				}
+			}
+
+			// Build the context
+			var ctx *ZRpcContext
+			if tt.name != "nil context uses package name" {
+				ctx = &ZRpcContext{
+					NameFromFilename: tt.nameFromFilename,
+				}
+			}
+
+			// Call the helper function to determine service name
+			serviceName := determineServiceName(p, ctx)
+			assert.Equal(t, tt.expectedName, serviceName)
+		})
+	}
+}
+
+func TestServiceNameWithNilContext(t *testing.T) {
+	p := parser.Proto{
+		Name: "test.proto",
+		Package: parser.Package{
+			Package: &proto.Package{
+				Name: "testpkg",
+			},
+		},
+	}
+
+	// nil context should use package name
+	serviceName := determineServiceName(p, nil)
+	assert.Equal(t, "testpkg", serviceName)
+}
+
+func TestServiceNameFallbackWithEmptyPackage(t *testing.T) {
+	p := parser.Proto{
+		Name: "myservice.proto",
+		Package: parser.Package{
+			Package: &proto.Package{
+				Name: "", // empty package name
+			},
+		},
+	}
+
+	ctx := &ZRpcContext{
+		NameFromFilename: false,
+	}
+
+	// Should fall back to filename when package name is empty
+	serviceName := determineServiceName(p, ctx)
+	assert.Equal(t, "myservice", serviceName)
+}