github.com/zeromicro/go-zero
v1.10.3
#57 most downloaded on Go modules
zeromicro/go-zero
What this package is like to depend on
Last release 9 days ago
15 Aug 2026
Ships on a steady schedule
a new release about every 2 weeks
Rarely documented
notes for 6 of 48 stable releases
Nothing withdrawn
no release was ever pulled
5 years old
1007 releases · first in 2022
104 releases in the last 12 months
see the full history below
Release timeline
1007 releases · Jan 2022 to Aug 2026Releases
latest 60 of 1007-
v1.10.4-0.20260815090822-11f21098ddd915 Aug 2026 pre-releaseNothing published for this version
-
v1.10.4-0.20260812164116-ebe46e1ce07412 Aug 2026 pre-releaseNothing published for this version
-
v1.10.4-0.20260811011537-91a4cdbaf4e911 Aug 2026 pre-releaseNothing published for this version
-
v1.10.4-0.20260809062150-f7805d5e322309 Aug 2026 pre-releaseNothing published for this version
-
v1.10.4-0.20260807161114-fc22f7501a2207 Aug 2026 pre-releaseNothing published for this version
-
v1.10.4-0.20260807011720-2bd5b8495b0207 Aug 2026 pre-releaseNothing published for this version
-
v1.10.4-0.20260804223529-984e146c6c7404 Aug 2026 pre-releaseNothing published for this version
-
v1.10.4-0.20260801052810-8017edb6719a01 Aug 2026 pre-releaseNothing published for this version
-
v1.10.331 Jul 2026Release notes
Open source →Highlights
Core
stringx.FirstN: returns empty string for negativen(#5620)stringx.Substr: rejectsstart > stopto prevent slice panic (#5616)mapping: fixed unmarshaling of pointer-to-slice fields (#5662)collection: optimized queue growth strategy (#5704)
Redis
- Added
XGroupSetID/XGroupSetIDCtxto update a consumer group's last-delivered ID (#5637) - Fixed circuit breaker tripping under high concurrency / with incompatible servers (#5654), plus minor refactor (#5666)
Docs
- Added Korean translations (#5579)
Dependencies
go-redis/v99.19.0 → 9.21.0mongo-driver/v22.6.0 → 2.8.0pelletier/go-toml/v22.3.1 → 2.4.3
New Contributors
@Vierblatt, @sapirbaruch, @SAY-5, @jeonghyeon-net, @Meppo, @puneetdixit200, @lxffong, @014-code — thank you for your first contributions! 🎉
Full Changelog: v1.10.2...v1.10.3
-
v1.10.3-0.20260815090822-11f21098ddd915 Aug 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260811011537-91a4cdbaf4e911 Aug 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260809062150-f7805d5e322309 Aug 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260721011650-84313f2e922f21 Jul 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260717112727-6a6b81ef20d517 Jul 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260712090704-35a7ca9d98b112 Jul 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260627160903-f910257ec95b27 Jun 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260627111846-99515480cf1027 Jun 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260623150720-726cd0141a7d23 Jun 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260621134920-48ca7f03b51221 Jun 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260612001303-6f46837c05af12 Jun 2026 pre-releaseNothing published for this version
-
v1.10.3-0.20260609014519-ca8b50a7a57909 Jun 2026 pre-releaseNothing published for this version
-
v1.10.225 May 2026Release notes
Open source →New Features
mcp — Opt-in HTTP request metadata bridge for tool handlers (#5550)
Added
WithRequestMetadataExtractoroption to the MCP server. When set, HTTP request metadata (headers, query parameters, path variables) is captured and injected into each handler'scontext.Context. Handlers retrieve it via the provided context helpers:server := mcp.NewMcpServer(conf, mcp.WithRequestMetadataExtractor(mcp.DefaultRequestMetadataExtractor)) server.AddTool(tool, func(ctx context.Context, req *mcp.ServerRequest) (*mcp.ToolResult, error) { tenantID, _ := mcp.HeaderFromContext(ctx, "X-Tenant-ID") userID, _ := mcp.QueryFromContext(ctx, "user_id") // ... })
Available helpers:
RequestMetadataFromContext,HeaderFromContext,QueryFromContext,PathFromContext. Fully backward-compatible — existingNewMcpServer(c)calls are unaffected.Bug Fixes
discov— Go 1.26 etcd URI compatibility (#5548)Go 1.26 enforces strict RFC 3986 URI parsing and rejects comma-separated hosts in the URI authority component.
BuildDiscovTargetwas producing URIs in the formetcd://host1:2379,host2:2379/key, which broke all gRPC services using etcd service discovery with multiple endpoints on Go 1.26+.The etcd target URL format has been updated to place hosts in the path and the etcd key in a query parameter:
# Before (breaks Go 1.26): etcd://host1:2379,host2:2379/my-service-key # After (RFC 3986 compliant, works on all Go versions): etcd:///host1:2379,host2:2379?key=my-service-keydiscov— Unbounded memory growth on duplicate etcd PUT events (#5580)Fixed two related bugs in discov that caused memory to grow without bound in long-running zRPC services:
- Redundant
OnAddcalls:handleWatchEventscalledOnAddon every etcdPUTevent regardless of whether the value changed (e.g. lease refreshes, watch reconnects). Duplicate PUTs are now skipped; value changes fireOnDelete(old)followed byOnAdd(new)to keep listeners consistent. - Unbounded slice growth in
addKv: Keys were appended to the internalcontainer.valuesslice unconditionally, causing a single etcd key to accumulate thousands of duplicates over time.addKvnow returns early for exact duplicates, and cleans up stale entries when a key moves to a new server address.
New Contributors
- @caltechustc made their first contribution in #5596
Full Changelog: v1.10.1...v1.10.2
- Redundant
-
v1.10.2-0.20260731171917-925f8a2bcc1531 Jul 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260721011650-84313f2e922f21 Jul 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260712090704-35a7ca9d98b112 Jul 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260627160903-f910257ec95b27 Jun 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260623150720-726cd0141a7d23 Jun 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260612001303-6f46837c05af12 Jun 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260525110539-0c79f5562ec325 May 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260524105353-34f16a857ea424 May 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260516043505-7b5e7b1c26c816 May 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260513143006-4ea0d9e9eaee13 May 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260511151745-3738be1945da11 May 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260425091104-5b74b9ab7b9725 Apr 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260411074158-22bdae07878111 Apr 2026 pre-releaseNothing published for this version
-
v1.10.2-0.20260328150148-3f91a79a2b1c28 Mar 2026 pre-releaseNothing published for this version
-
v1.10.128 Mar 2026Release notes
Open source →🎉 Highlights
This patch release adds JSON5 configuration support, generic Redis command execution via
Do/DoCtx, upgrades Go to 1.24, and includes critical security fixes incore/codec.✨ New Features
- core/conf: Add JSON5 configuration support (#5433)
- core/stores/redis: Add
Do/DoCtxfor generic command execution (#5442)
🐛 Bug Fixes
- rest/httpc: Reject request body for HEAD method in
buildRequest(#5457) - core/codec: Critical security fixes (#5479)
🔧 Improvements
- core: Replace
TakeOneusage withcmp.Or(#5461) - core/stringx: Replace manual char filter with
strings.Map(#5453) - core/stores/redis: Reorder
Eval/EvalCtxafterDo/DoCtxfor consistent method ordering (#5502) - core/mathx: Add godoc comment to
Numericaltype constraint (#5470) - Upgrade Go version to 1.24 and update dependencies (#5499)
🧪 Testing
- Add missing edge case tests for
CalcEntropyand string utilities (#5471) - Add unit tests for
Hash,Hashdeterminism, andMd5Hexedge cases (#5469)
📦 Dependencies
- Bumped
github.com/grafana/pyroscope-gofrom 1.2.7 to 1.2.8 (#5513) - Bumped
github.com/pelletier/go-toml/v2from 2.2.4 to 2.3.0 (#5512) - Bumped
github.com/alicebob/miniredis/v2from 2.36.1 to 2.37.0 (#5444) - Bumped
github.com/modelcontextprotocol/go-sdkfrom 1.3.0 to 1.3.1 (#5435) - Bumped
github.com/redis/go-redis/v9from 9.17.3 to 9.18.0 (#5432)
👥 New Contributors
- @1911860538 made their first contribution in #5453
- @amshithnair made their first contribution in #5469
- @mmfiRan made their first contribution in #5442
Full Changelog: v1.10.0...v1.10.1
-
v1.10.1-0.20260322123930-6ffa9cabec9422 Mar 2026 pre-releaseNothing published for this version
-
v1.10.1-0.20260315150257-04ed6373664815 Mar 2026 pre-releaseNothing published for this version
-
v1.10.1-0.20260314131946-ec802e25a60714 Mar 2026 pre-releaseNothing published for this version
-
v1.10.1-0.20260228122953-8a2e09dfd17a28 Feb 2026 pre-releaseNothing published for this version
-
v1.10.1-0.20260221050451-220d438fe7f521 Feb 2026 pre-releaseNothing published for this version
-
v1.10.1-0.20260215122543-7e96317fad9615 Feb 2026 pre-releaseNothing published for this version
-
v1.10.012 Feb 2026Release notes
Open source →🎉 Highlights
This release brings Go 1.23 support, MCP SDK migration, and several important bug fixes including race condition resolutions.
✨ New Features
- Go 1.23 Support: Upgraded minimum Go version to 1.23 (#5359)
- MCP Framework: Migrated to official go-sdk with simplified API (#5362)
- Gateway Enhancement: Exported
WithDialeroption for custom gRPC client configuration (#5406)
🐛 Bug Fixes
- Circuit Breaker: Fixed context cancellation incorrectly triggering breaker in httpc (#5360)
- Service Discovery: Resolved data race in service discovery map access (#5408)
- Configuration: Fixed support for equal signs in property values (#5392)
- Configuration: Removed redundant validation (#5372)
🔧 Improvements
- MCP Routes: Refactored routes and hardened AddTool implementation (#5375)
- Testing: Added comprehensive validation tests for Load function (#5388)
🗑️ Deprecations
- Jaeger Exporter: Removed due to official deprecation (#5361)
📦 Dependencies
- Bumped
go.mongodb.org/mongo-driver/v2from 2.4.1 to 2.5.0 (#5385, #5393) - Bumped
github.com/alicebob/miniredis/v2from 2.35.0 to 2.36.1 (#5381, #5386) - Bumped
github.com/redis/go-redis/v9from 9.17.2 to 9.17.3 (#5390) - Bumped
github.com/modelcontextprotocol/go-sdkfrom 1.2.0 to 1.3.0 (#5413)
👥 New Contributors
Full Changelog: v1.9.4...v1.10.0
-
v1.9.5-0.20260206151605-b139a82c2ebc06 Feb 2026 pre-releaseNothing published for this version
-
v1.9.5-0.20260201042916-4d5ed2c45d9a01 Feb 2026 pre-releaseNothing published for this version
-
v1.9.5-0.20260130231809-a2310bf9d75630 Jan 2026 pre-releaseNothing published for this version
-
v1.9.5-0.20260124232105-b20f0e3d60e224 Jan 2026 pre-releaseNothing published for this version
-
v1.9.5-0.20251225162145-8e7e5695eb2025 Dec 2025 pre-releaseNothing published for this version
-
v1.9.5-0.20251225061509-4b631f37856125 Dec 2025 pre-releaseNothing published for this version
-
v1.9.423 Dec 2025Release notes
Open source →We're excited to announce go-zero v1.9.4! This release includes important improvements, performance optimizations, and new features to enhance your microservices development experience.
New Features
- Kubernetes EndpointSlice Support: Migrated zrpc kube resolver from deprecated Endpoints API to EndpointSlice API for improved scalability and performance in Kubernetes environments (#4987)
- Redis GETEX Command: Added support for Redis GETEX command, enabling atomic get-and-expire operations (#5323)
Improvements
- Logging Improvements:
- Timing Wheel: Added missing
Wait()call and improved code clarity in timing wheel implementation (#5315) - Service Discovery: Added retry cooldown mechanism in etcd discovery to prevent CPU/disk exhaustion during authentication errors (#5347)
- Configuration Center: Fixed incorrect value notifications in configuration center updates (#5348)
- RPC Metrics: Corrected slow threshold priority handling in zrpc stat interceptor (#5310)
Performance Optimizations
- Optimized
getFullNamefunction in configuration module for better efficiency (#5328) - Improved bool parsing performance by using
strings.EqualFoldin mapping module (#5324)
New Contributors
Welcome to our new contributors!
Full Changelog
For a complete list of changes, see: v1.9.3...v1.9.4
-
v1.9.4-0.20251213050135-5c9ea81db2e813 Dec 2025 pre-releaseNothing published for this version
-
v1.9.4-0.20251211150908-3d291328d82511 Dec 2025 pre-releaseNothing published for this version
-
v1.9.4-0.20251207033756-7b23f73268bc07 Dec 2025 pre-releaseNothing published for this version
-
v1.9.4-0.20251205013053-0a724447cdc805 Dec 2025 pre-releaseNothing published for this version
-
v1.9.4-0.20251120132650-72dd970969b020 Nov 2025 pre-releaseNothing published for this version
-
v1.9.4-0.20251119144628-577a611dc38919 Nov 2025 pre-releaseNothing published for this version
-
v1.9.316 Nov 2025Release notes
Open source →We are excited to announce the release of go-zero v1.9.3! This release brings several important enhancements and bug fixes that improve the framework's reliability, performance, and alignment with industry best practices.
🎉 Highlights
- Consistent Hash Load Balancing: New gRPC load balancer for session affinity
- gRPC Best Practices: Changed NonBlock default to align with gRPC recommendations
- Improved Distributed Tracing: Fixed gateway trace header propagation
- ORM Improvements: Fixed zero value scanning for pointer destinations
✨ New Features
Consistent Hash Balancer Support (#5246)
Contributor: @zhoushuguang
A new consistent hash load balancer has been added to the zRPC package, enabling session affinity for gRPC services.
Key Features:
- Hash-based request routing to maintain session affinity
- Distributes requests based on a hash key from context
- Minimal request redistribution on node changes
- Built on go-zero's existing
core/hash/ConsistentHashimplementation
Usage Example:
// Set hash key in context ctx := zrpc.SetHashKey(ctx, "user_123") // Requests with the same key will be routed to the same backend resp, err := client.SomeMethod(ctx, req)
Configuration:
c := zrpc.RpcClientConf{ Endpoints: []string{"localhost:8080", "localhost:8081"}, BalancerName: "consistent_hash", // Use consistent hash balancer }
Benefits:
- Enables stateful service interactions
- Improves cache hit rates on backend services
- Reduces session data synchronization overhead
- Maintains load distribution while supporting affinity
🐛 Bug Fixes
Fixed Gateway Trace Headers (#5256, #5248)
Contributor: @kevwan
Fixed an issue where OpenTelemetry trace propagation headers were not being properly forwarded through the gateway to upstream gRPC services, breaking distributed tracing.
Problem:
The gateway was not forwarding critical W3C Trace Context headers (traceparent,tracestate,baggage) to gRPC metadata, causing trace context to be lost at the gateway boundary.Solution:
- Enhanced
ProcessHeadersfunction to forward trace propagation headers - Headers are now properly converted to lowercase per gRPC metadata conventions
- Maintains distributed tracing across HTTP → gRPC boundaries
Impact:
- End-to-end tracing now works correctly through the gateway
- Improved observability for microservice architectures
- Better debugging and performance analysis capabilities
Technical Details:
// Trace headers now properly forwarded var traceHeaders = map[string]bool{ "traceparent": true, // W3C Trace Context "tracestate": true, // Additional trace state "baggage": true, // W3C Baggage propagation }
Fixed Multiple Trace Initialization (#5244)
Contributor: @kevwan
Problem:
When running multiple services (e.g., REST + RPC) in the same process, the trace agent could be initialized multiple times, potentially causing resource leaks or unexpected behavior.Solution:
- Used
sync.Onceto ensure trace agent is initialized only once - Aligned with similar patterns used in
prometheus.StartAgentandlogx.SetUp - Added
sync.OnceFuncfor shutdown to prevent double cleanup
Code Changes:
var ( once sync.Once shutdownOnceFn = sync.OnceFunc(func() { if tp != nil { _ = tp.Shutdown(context.Background()) } }) ) func StartAgent(c Config) { if c.Disabled { return } once.Do(func() { if err := startAgent(c); err != nil { logx.Error(err) } }) }
Benefits:
- Prevents resource conflicts in multi-server processes
- Ensures single global tracer provider instance
- Safer concurrent initialization
- Proper cleanup on shutdown
Fixed ORM Zero Value Scanning for Pointer Destinations (#5270)
Contributor: @lerity-yao (first contribution! 🎊)
Problem:
When scanning database results into struct fields with pointer types, zero values (0, false, empty string) were not being properly distinguished from NULL values. This caused nil pointers to be set to zero values incorrectly.Solution:
Enhanced thegetValueInterfacefunction to properly initialize nil pointers before scanning, ensuring the SQL driver can correctly populate them with zero or non-zero values.Code Changes:
func getValueInterface(value reflect.Value) (any, error) { if !value.CanAddr() || !value.Addr().CanInterface() { return nil, ErrNotReadableValue } // Initialize nil pointer before scanning if value.Kind() == reflect.Pointer && value.IsNil() { baseValueType := mapping.Deref(value.Type()) value.Set(reflect.New(baseValueType)) } return value.Addr().Interface(), nil }
Impact:
type User struct { Name string `db:"name"` // Always set Age *int `db:"age"` // Can distinguish NULL vs 0 Active *bool `db:"active"` // Can distinguish NULL vs false } // Before: age=0 and age=NULL both resulted in nil pointer // After: age=0 → *int(0), age=NULL → nil pointer ✓
Benefits:
- Correct handling of NULL vs zero values
- Better semantic representation of optional fields
- Prevents unexpected nil pointer dereferences
- Aligns with Go's SQL scanning best practices
🔄 Breaking Changes (With Backward Compatibility)
Changed NonBlock Default to True (#5259)
Contributor: @kevwan
Motivation:
Aligned with gRPC official best practices which discourage blocking dials.Change:
// zrpc/config.go type RpcClientConf struct { // Before: NonBlock bool `json:",optional"` // After: NonBlock bool `json:",default=true"` // Now defaults to true }
Why This Matters:
- Blocking dials are deprecated:
grpc.WithBlock()is an anti-pattern - Connection state is dynamic: Being connected at dial time doesn't guarantee future connectivity
- RPCs handle waiting: All RPCs automatically wait until connection or deadline
- Simpler code: No need to check "ready" state before making calls
Migration Guide:
For most users, no action required - the new default is the recommended behavior.
If you explicitly need blocking behavior (not recommended):
// Option 1: Configuration c := zrpc.RpcClientConf{ NonBlock: false, // Explicit blocking } // Option 2: Client option (deprecated) client := zrpc.MustNewClient(c, zrpc.WithBlock())
Backward Compatibility:
- Existing configs with
NonBlock: falsecontinue to work - New
WithBlock()option available (marked deprecated) - No changes needed for services already using
NonBlock: true
Documentation:
See GRPC_NONBLOCK_CHANGE.md for detailed migration guide and rationale.
👥 New Contributors
We're thrilled to welcome new contributors to the go-zero community! 🎉
- @JackGod001 - Made their first contribution in #4343
- @stemlaud - Made their first contribution in #5245
- @gfischer7 - Made their first contribution in #5254
- @lerity-yao - Made their first contribution in #5270 (ORM fix)
Thank you for your contributions! We look forward to your continued involvement in the project.
📦 Installation & Upgrade
Install
go get -u github.com/zeromicro/[email protected]
Update
# Update go.mod go get -u github.com/zeromicro/[email protected] go mod tidy
🔗 Links
- Full Changelog: v1.9.2...v1.9.3
- Documentation: https://go-zero.dev
- GitHub Repository: https://github.com/zeromicro/go-zero
📝 Detailed Changes
Core Enhancements
Load Balancing
- Added consistent hash balancer for gRPC (
zrpc/internal/balancer/consistenthash) - Context-based hash key API:
SetHashKey()andGetHashKey() - Configurable replica count and hash function
- Comprehensive test coverage
Distributed Tracing
- Fixed trace header propagation in gateway
- Proper handling of W3C Trace Context headers
- Case-insensitive header matching per gRPC conventions
- Single initialization with
sync.Oncepattern
ORM/Database
- Fixed pointer field scanning for zero values
- Proper NULL vs zero value distinction
- Enhanced
getValueInterface()with nil pointer initialization - Support for
sql.Null*types
gRPC Client
- Changed NonBlock default to true
- Added deprecated
WithBlock()option for compatibility - Explicit handling of both blocking and non-blocking modes
- Updated client initialization logic
Testing & Quality
- Added comprehensive test coverage for all changes
- Edge case handling in ORM tests
- Gateway trace header test cases
- Consistent hash balancer benchmarks
🙏 Acknowledgments
Special thanks to all contributors, issue reporters, and community members who made this release possible. Your feedback and contributions continue to make go-zero better!
💬 Feedback
If you encounter any issues or have suggestions for future releases, please:
- Open an issue: https://github.com/zeromicro/go-zero/issues
Happy coding with go-zero! 🚀
-
v1.9.3-0.20260206151605-b139a82c2ebc06 Feb 2026 pre-releaseNothing published for this version
-
v1.9.3-0.20251225162145-8e7e5695eb2025 Dec 2025 pre-releaseNothing published for this version