PackageTrack
Sign in Get early access

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 2026
2023 2024 2025 2026
Release Pre-release

Releases

latest 60 of 1007
  1. v1.10.4-0.20260815090822-11f21098ddd9 15 Aug 2026 pre-release

    Nothing published for this version

  2. v1.10.4-0.20260812164116-ebe46e1ce074 12 Aug 2026 pre-release

    Nothing published for this version

  3. v1.10.4-0.20260811011537-91a4cdbaf4e9 11 Aug 2026 pre-release

    Nothing published for this version

  4. v1.10.4-0.20260809062150-f7805d5e3223 09 Aug 2026 pre-release

    Nothing published for this version

  5. v1.10.4-0.20260807161114-fc22f7501a22 07 Aug 2026 pre-release

    Nothing published for this version

  6. v1.10.4-0.20260807011720-2bd5b8495b02 07 Aug 2026 pre-release

    Nothing published for this version

  7. v1.10.4-0.20260804223529-984e146c6c74 04 Aug 2026 pre-release

    Nothing published for this version

  8. v1.10.4-0.20260801052810-8017edb6719a 01 Aug 2026 pre-release

    Nothing published for this version

  9. v1.10.3 31 Jul 2026
    Release notes

    Highlights

    Core

    • stringx.FirstN: returns empty string for negative n (#5620)
    • stringx.Substr: rejects start > stop to prevent slice panic (#5616)
    • mapping: fixed unmarshaling of pointer-to-slice fields (#5662)
    • collection: optimized queue growth strategy (#5704)

    Redis

    • Added XGroupSetID/XGroupSetIDCtx to 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/v9 9.19.0 → 9.21.0
    • mongo-driver/v2 2.6.0 → 2.8.0
    • pelletier/go-toml/v2 2.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

    Open source →
  10. v1.10.3-0.20260815090822-11f21098ddd9 15 Aug 2026 pre-release

    Nothing published for this version

  11. v1.10.3-0.20260811011537-91a4cdbaf4e9 11 Aug 2026 pre-release

    Nothing published for this version

  12. v1.10.3-0.20260809062150-f7805d5e3223 09 Aug 2026 pre-release

    Nothing published for this version

  13. v1.10.3-0.20260721011650-84313f2e922f 21 Jul 2026 pre-release

    Nothing published for this version

  14. v1.10.3-0.20260717112727-6a6b81ef20d5 17 Jul 2026 pre-release

    Nothing published for this version

  15. v1.10.3-0.20260712090704-35a7ca9d98b1 12 Jul 2026 pre-release

    Nothing published for this version

  16. v1.10.3-0.20260627160903-f910257ec95b 27 Jun 2026 pre-release

    Nothing published for this version

  17. v1.10.3-0.20260627111846-99515480cf10 27 Jun 2026 pre-release

    Nothing published for this version

  18. v1.10.3-0.20260623150720-726cd0141a7d 23 Jun 2026 pre-release

    Nothing published for this version

  19. v1.10.3-0.20260621134920-48ca7f03b512 21 Jun 2026 pre-release

    Nothing published for this version

  20. v1.10.3-0.20260612001303-6f46837c05af 12 Jun 2026 pre-release

    Nothing published for this version

  21. v1.10.3-0.20260609014519-ca8b50a7a579 09 Jun 2026 pre-release

    Nothing published for this version

  22. v1.10.2 25 May 2026
    Release notes

    New Features

    mcp — Opt-in HTTP request metadata bridge for tool handlers (#5550)

    Added WithRequestMetadataExtractor option to the MCP server. When set, HTTP request metadata (headers, query parameters, path variables) is captured and injected into each handler's context.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 — existing NewMcpServer(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. BuildDiscovTarget was producing URIs in the form etcd://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-key
    

    discov — 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 OnAdd calls: handleWatchEvents called OnAdd on every etcd PUT event regardless of whether the value changed (e.g. lease refreshes, watch reconnects). Duplicate PUTs are now skipped; value changes fire OnDelete(old) followed by OnAdd(new) to keep listeners consistent.
    • Unbounded slice growth in addKv: Keys were appended to the internal container.values slice unconditionally, causing a single etcd key to accumulate thousands of duplicates over time. addKv now returns early for exact duplicates, and cleans up stale entries when a key moves to a new server address.

    New Contributors

    Full Changelog: v1.10.1...v1.10.2

    Open source →
  23. v1.10.2-0.20260731171917-925f8a2bcc15 31 Jul 2026 pre-release

    Nothing published for this version

  24. v1.10.2-0.20260721011650-84313f2e922f 21 Jul 2026 pre-release

    Nothing published for this version

  25. v1.10.2-0.20260712090704-35a7ca9d98b1 12 Jul 2026 pre-release

    Nothing published for this version

  26. v1.10.2-0.20260627160903-f910257ec95b 27 Jun 2026 pre-release

    Nothing published for this version

  27. v1.10.2-0.20260623150720-726cd0141a7d 23 Jun 2026 pre-release

    Nothing published for this version

  28. v1.10.2-0.20260612001303-6f46837c05af 12 Jun 2026 pre-release

    Nothing published for this version

  29. v1.10.2-0.20260525110539-0c79f5562ec3 25 May 2026 pre-release

    Nothing published for this version

  30. v1.10.2-0.20260524105353-34f16a857ea4 24 May 2026 pre-release

    Nothing published for this version

  31. v1.10.2-0.20260516043505-7b5e7b1c26c8 16 May 2026 pre-release

    Nothing published for this version

  32. v1.10.2-0.20260513143006-4ea0d9e9eaee 13 May 2026 pre-release

    Nothing published for this version

  33. v1.10.2-0.20260511151745-3738be1945da 11 May 2026 pre-release

    Nothing published for this version

  34. v1.10.2-0.20260425091104-5b74b9ab7b97 25 Apr 2026 pre-release

    Nothing published for this version

  35. v1.10.2-0.20260411074158-22bdae078781 11 Apr 2026 pre-release

    Nothing published for this version

  36. v1.10.2-0.20260328150148-3f91a79a2b1c 28 Mar 2026 pre-release

    Nothing published for this version

  37. v1.10.1 28 Mar 2026
    Release notes

    🎉 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 in core/codec.

    ✨ New Features

    • core/conf: Add JSON5 configuration support (#5433)
    • core/stores/redis: Add Do/DoCtx for 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 TakeOne usage with cmp.Or (#5461)
    • core/stringx: Replace manual char filter with strings.Map (#5453)
    • core/stores/redis: Reorder Eval/EvalCtx after Do/DoCtx for consistent method ordering (#5502)
    • core/mathx: Add godoc comment to Numerical type constraint (#5470)
    • Upgrade Go version to 1.24 and update dependencies (#5499)

    🧪 Testing

    • Add missing edge case tests for CalcEntropy and string utilities (#5471)
    • Add unit tests for Hash, Hash determinism, and Md5Hex edge cases (#5469)

    📦 Dependencies

    • Bumped github.com/grafana/pyroscope-go from 1.2.7 to 1.2.8 (#5513)
    • Bumped github.com/pelletier/go-toml/v2 from 2.2.4 to 2.3.0 (#5512)
    • Bumped github.com/alicebob/miniredis/v2 from 2.36.1 to 2.37.0 (#5444)
    • Bumped github.com/modelcontextprotocol/go-sdk from 1.3.0 to 1.3.1 (#5435)
    • Bumped github.com/redis/go-redis/v9 from 9.17.3 to 9.18.0 (#5432)

    👥 New Contributors

    Full Changelog: v1.10.0...v1.10.1

    Open source →
  38. v1.10.1-0.20260322123930-6ffa9cabec94 22 Mar 2026 pre-release

    Nothing published for this version

  39. v1.10.1-0.20260315150257-04ed63736648 15 Mar 2026 pre-release

    Nothing published for this version

  40. v1.10.1-0.20260314131946-ec802e25a607 14 Mar 2026 pre-release

    Nothing published for this version

  41. v1.10.1-0.20260228122953-8a2e09dfd17a 28 Feb 2026 pre-release

    Nothing published for this version

  42. v1.10.1-0.20260221050451-220d438fe7f5 21 Feb 2026 pre-release

    Nothing published for this version

  43. v1.10.1-0.20260215122543-7e96317fad96 15 Feb 2026 pre-release

    Nothing published for this version

  44. v1.10.0 12 Feb 2026
    Release notes

    🎉 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 WithDialer option 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/v2 from 2.4.1 to 2.5.0 (#5385, #5393)
    • Bumped github.com/alicebob/miniredis/v2 from 2.35.0 to 2.36.1 (#5381, #5386)
    • Bumped github.com/redis/go-redis/v9 from 9.17.2 to 9.17.3 (#5390)
    • Bumped github.com/modelcontextprotocol/go-sdk from 1.2.0 to 1.3.0 (#5413)

    👥 New Contributors

    Full Changelog: v1.9.4...v1.10.0

    Open source →
  45. v1.9.5-0.20260206151605-b139a82c2ebc 06 Feb 2026 pre-release

    Nothing published for this version

  46. v1.9.5-0.20260201042916-4d5ed2c45d9a 01 Feb 2026 pre-release

    Nothing published for this version

  47. v1.9.5-0.20260130231809-a2310bf9d756 30 Jan 2026 pre-release

    Nothing published for this version

  48. v1.9.5-0.20260124232105-b20f0e3d60e2 24 Jan 2026 pre-release

    Nothing published for this version

  49. v1.9.5-0.20251225162145-8e7e5695eb20 25 Dec 2025 pre-release

    Nothing published for this version

  50. v1.9.5-0.20251225061509-4b631f378561 25 Dec 2025 pre-release

    Nothing published for this version

  51. v1.9.4 23 Dec 2025
    Release notes

    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:
      • Fixed missing color for levelSevere in log output formatting (#5281)
      • Resolved test log timing and scheduling issues (#5305)
    • 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 getFullName function in configuration module for better efficiency (#5328)
    • Improved bool parsing performance by using strings.EqualFold in 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

    Open source →
  52. v1.9.4-0.20251213050135-5c9ea81db2e8 13 Dec 2025 pre-release

    Nothing published for this version

  53. v1.9.4-0.20251211150908-3d291328d825 11 Dec 2025 pre-release

    Nothing published for this version

  54. v1.9.4-0.20251207033756-7b23f73268bc 07 Dec 2025 pre-release

    Nothing published for this version

  55. v1.9.4-0.20251205013053-0a724447cdc8 05 Dec 2025 pre-release

    Nothing published for this version

  56. v1.9.4-0.20251120132650-72dd970969b0 20 Nov 2025 pre-release

    Nothing published for this version

  57. v1.9.4-0.20251119144628-577a611dc389 19 Nov 2025 pre-release

    Nothing published for this version

  58. v1.9.3 16 Nov 2025
    Release notes

    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/ConsistentHash implementation

    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 ProcessHeaders function 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.Once to ensure trace agent is initialized only once
    • Aligned with similar patterns used in prometheus.StartAgent and logx.SetUp
    • Added sync.OnceFunc for 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 the getValueInterface function 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:

    1. Blocking dials are deprecated: grpc.WithBlock() is an anti-pattern
    2. Connection state is dynamic: Being connected at dial time doesn't guarantee future connectivity
    3. RPCs handle waiting: All RPCs automatically wait until connection or deadline
    4. 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: false continue 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! 🎉

    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


    📝 Detailed Changes

    Core Enhancements

    Load Balancing

    • Added consistent hash balancer for gRPC (zrpc/internal/balancer/consistenthash)
    • Context-based hash key API: SetHashKey() and GetHashKey()
    • 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.Once pattern

    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:

    Happy coding with go-zero! 🚀

    Open source →
  59. v1.9.3-0.20260206151605-b139a82c2ebc 06 Feb 2026 pre-release

    Nothing published for this version

  60. v1.9.3-0.20251225162145-8e7e5695eb20 25 Dec 2025 pre-release

    Nothing published for this version

Every package, every release, already written down.

The archive is open and free. Watching your own project is what we are building next.

Browse the archive