If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/zeromicro/go-zero shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 19 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live zeromicro/go-zero repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/zeromicro/go-zero.

What it runs against: a local clone of zeromicro/go-zero — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in zeromicro/go-zero | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 41 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of zeromicro/go-zero. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/zeromicro/go-zero.git
#   cd go-zero
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of zeromicro/go-zero and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "zeromicro/go-zero(\\.git)?\\b" \\
  && ok "origin remote is zeromicro/go-zero" \\
  || miss "origin remote is not zeromicro/go-zero (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "core/conf/config.go" \\
  && ok "core/conf/config.go" \\
  || miss "missing critical file: core/conf/config.go"
test -f "core/discov/internal/registry.go" \\
  && ok "core/discov/internal/registry.go" \\
  || miss "missing critical file: core/discov/internal/registry.go"
test -f "core/breaker/breaker.go" \\
  && ok "core/breaker/breaker.go" \\
  || miss "missing critical file: core/breaker/breaker.go"
test -f "core/collection/cache.go" \\
  && ok "core/collection/cache.go" \\
  || miss "missing critical file: core/collection/cache.go"
test -f "core/codec/aesecb.go" \\
  && ok "core/codec/aesecb.go" \\
  || miss "missing critical file: core/codec/aesecb.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 41 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~11d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/zeromicro/go-zero"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

go-zero is a cloud-native Go microservices framework that combines a web/RPC server with the goctl CLI code generator. It generates type-safe service scaffolding, client SDKs (Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript), and integrates resilience patterns (circuit breakers, rate limiting, adaptive load shedding, timeout control) directly into generated code without configuration boilerplate. Monorepo organized by feature: core/ contains reusable components (breaker/, codec/, collection/, bloom/), likely with corresponding rest/ and rpc/ packages for HTTP/gRPC services. cli/ (inferred from goctl references) generates scaffold from .api files (ANTLR grammar in repo for parsing). Heavy use of middleware patterns and interface-based composition throughout.

Go backend engineers and DevOps teams building microservices at scale who need production-grade stability features (handling tens of millions of daily active users) without manually implementing timeouts, circuit breakers, and concurrency controls. Also useful for teams generating multi-platform clients from a single .api definition file.

Production-ready and actively maintained. The codebase is substantial (3.5M+ lines of Go), has comprehensive test coverage (see *_test.go files throughout core/), CI/CD pipelines for CodeQL, Go testing, and release automation (.github/workflows/), and is CNCF Landscape-listed. Latest Go version requirement is 1.24.0, indicating recent dependency updates.

Low risk for core stability but watch for: high dependency count (etcd, gRPC, OpenTelemetry, Kubernetes client libraries) that increases supply-chain surface area; monorepo structure means changes to core/breaker or core/codec affect all consumers; the Lua scripting in core/bloom/ and Redis integration paths add operational complexity. No obvious single-maintainer risk evident, but large monorepo means careful review needed for core changes.

Active maintenance with Go 1.24.0 support, OpenTelemetry instrumentation (otlptrace, zipkin exporters), MongoDB v2 driver integration, and Kubernetes client updates (v0.34.3). Dependabot enabled (.github/dependabot.yml) and issue templates configured for bugs/features/questions, indicating ongoing community engagement.

Clone and explore: git clone https://github.com/zeromicro/go-zero.git && cd go-zero && go mod download. No Makefile install target visible, so dependencies install via go mod. Verify with go test ./core/breaker to validate the local environment against a core package.

Daily commands: No traditional 'dev server' — go-zero is a library + CLI tool. Run tests locally: go test ./... or specific packages: go test ./core/breaker ./core/bloom. For goctl CLI (inferred but not in file list): build with go build -o goctl ./cmd/goctl (path assumes cmd/goctl exists based on typical layout).

• core/conf/config.go — Core configuration loading and unmarshaling engine; foundational for all service initialization
• core/discov/internal/registry.go — Service discovery and registration registry; critical for microservice communication patterns
• core/breaker/breaker.go — Circuit breaker implementation; essential resilience pattern used across RPC/HTTP calls
• core/collection/cache.go — In-memory caching abstraction; load-bearing for performance-critical operations
• core/codec/aesecb.go — Encryption codec interface; demonstrates extension pattern for data protection
• core/contextx/unmarshaler.go — Context-aware request unmarshaling; bridges HTTP/RPC payload binding throughout framework
• core/configcenter/configurator.go — Dynamic config center integration; enables distributed configuration management

Add a New Codec Type (e.g., custom encryption)

1. Create new file in core/codec/ implementing encoding.Codec interface (Encrypt/Decrypt or Zip/Unzip methods) (core/codec/newcodec.go)
2. Add unit tests following naming convention with _test.go suffix (core/codec/newcodec_test.go)
3. Register codec factory in configuration or plugin system if extensibility point exists (core/conf/config.go)

Add a New Collection/Data Structure

1. Create new file in core/collection/ with thread-safe implementation using sync.RWMutex or atomic operations (core/collection/newcollection.go)
2. Define public API matching go-zero conventions (Add, Get, Remove, Len, Range methods) (core/collection/newcollection.go)
3. Write comprehensive unit tests including concurrency tests (core/collection/newcollection_test.go)
4. Document performance characteristics and use cases in file header comments (core/collection/newcollection.go)

Integrate a Custom Config Center or Service Discovery Backend

1. Implement Configurator interface in core/configcenter/configurator.go or Publisher/Registry interfaces in core/discov/ (core/configcenter/newbackend.go)
2. Add subscriber implementation similar to core/configcenter/subscriber/etcd.go for event-driven updates (core/configcenter/subscriber/newbackend.go)
3. Create initialization helpers and connection pooling in core/discov/clients.go pattern (core/discov/newclient.go)
4. Wire initialization through core/conf/config.go to allow declarative configuration (core/conf/config.go)

Add a New Breaker Strategy

1. Create new breaker implementation in core/breaker/newbreaker.go implementing Breaker interface (core/breaker/newbreaker.go)
2. Implement required methods: Name(), Allow(), MarkSuccess(), MarkFailed() (core/breaker/newbreaker.go)
3. Register breaker in Breakers collection via core/breaker/breakers.go factory pattern (core/breaker/breakers.go)
4. Add unit tests demonstrating state transitions and failure thresholds (core/breaker/newbreaker_test.go)

• etcd (via go.etcd.io/etcd/client/v3) — Distributed consensus backend for service discovery, configuration center, and state synchronization across microservice fleet
• Redis (via github.com/redis/go-redis/v9) — Optional distributed cache and bloom filter backend for high-throughput, low-latency request caching and deduplication
• Protocol Buffers (via github.com/golang/protobuf, github.com/jhump/protoreflect) — IDL and serialization format for gRPC service definitions, supporting reflection and dynamic message handling
• Prometheus (via github.com/prometheus/client_golang) — Metrics instrumentation for observability; circuit breaker state, cache hits, service latency
• JWT (via github.com/golang-jwt/jwt/v4) — Stateless authentication token generation and validation for HTTP/RPC services

• etcd as required discovery backend (vs pluggable backends)

  • Why: Simplifies consistency guarantees and operational model; reduces configuration complexity for distributed systems
  • Consequence: Locks users into etcd ecosystem; adds etcd cluster operational burden; custom backends require significant integration work

• Synchronous circuit breaker state machine (vs async state transitions)

  • Why: Deterministic, lock-free failure detection; minimal latency overhead on request path
  • Consequence: State transitions are request-driven, not time-driven; requires explicit MarkSuccess/MarkFailed calls to propagate state

• Thread-safe collections with sync.RWMutex (vs lock-free atomics)

  • Why: Simpler correctness guarantees for complex data structures; easier to reason about semantics
  • Consequence: Higher contention under extreme concurrency; not optimal for ultra-high-frequency operations

• Config validation via struct tags (core/conf/validate.go) vs external schema

  • Why: Single source of truth; schema co-located with code; no separate DSL to learn
  • Consequence: Validation logic scattered in tag definitions; harder to generate documentation; less flexible constraint expressiveness

• Real

Redis required for bloom filter and distributed caching (core/bloom uses Redis Lua scripts); etcd required for service discovery in production (no embedded fallback). Circuit breaker adaptive tuning depends on accurate latency histograms — misconfiguration can mask underlying failures. Protobuf code generation is a prerequisite for gRPC services (not automatic from .api files alone). The repo uses go/1.24.0 features; older Go versions will fail. Lua scripts in core/bloom/setscript.lua and testscript.lua must be loaded into Redis — missing setup causes silent failures.

• Circuit Breaker (Google SRE pattern) — go-zero's core/breaker implements adaptive circuit breaking to prevent cascading failures in microservices; understanding state transitions (closed → open → half-open) is critical for configuring fault tolerance
• Bloom Filter — go-zero uses distributed bloom filters (core/bloom/) backed by Redis + Lua for efficient membership testing without false negatives; useful for rate limiting and cache validation at scale
• Token Bucket Rate Limiting — go-zero integrates token bucket algorithms for request rate limiting and adaptive load shedding; mentioned as builtin but implementation details are in core/ packages
• Adaptive Load Shedding — go-zero automatically sheds requests under overload using real-time latency metrics; prevents cascade failures when downstream services degrade, critical for 'tens of millions of DAU' stability
• Code Generation from API Schema (ANTLR) — goctl CLI parses .api files (using ANTLR grammar) to generate type-safe service scaffolding, clients, and middleware; understanding the schema syntax and code generation templates is essential for extending go-zero
• Chained Timeout Control — go-zero propagates timeouts through RPC call chains (context.Context with deadlines); prevents resource exhaustion from slow upstream services
• Distributed Tracing with OpenTelemetry — go-zero integrates OpenTelemetry exporters (OTLP, Zipkin, stdout) for observability; critical for debugging latency and failures across microservices at scale

• grpc/grpc-go — go-zero builds on gRPC for RPC transport; understanding gRPC internals is essential for debugging service-to-service communication
• etcd-io/etcd — go-zero uses etcd (go.etcd.io/etcd/client/v3) for service discovery and distributed configuration in production deployments
• redis/go-redis — go-zero's distributed bloom filter, caching, and rate limiting rely on redis/go-redis/v9 for Redis operations
• open-telemetry/opentelemetry-go — go-zero integrates OpenTelemetry for observability; this is the canonical instrumentation library for tracing and metrics in Go
• zeromicro/zero-doc — Official documentation and examples repository; where API schema examples and tutorials for goctl code generation live

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for core/codec encryption workflows

The core/codec directory has multiple encryption modules (aesecb, dh, rsa, hmac) with individual unit tests, but lacks integration tests showing how these codecs work together in real microservice scenarios. This would catch compatibility issues and provide usage examples for contributors.

• [ ] Create core/codec/integration_test.go with end-to-end encryption/decryption workflows
• [ ] Test chaining multiple codecs (e.g., RSA + HMAC + GZIP)
• [ ] Add benchmarks comparing different codec combinations
• [ ] Document expected performance characteristics in core/codec/readme.md

Implement metrics and observability tests for core/breaker circuit breaker patterns

The breaker package (breaker.go, googlebreaker.go, nopbreaker.go) implements critical resilience patterns but lacks tests validating that Prometheus metrics are correctly emitted. With go-zero's strong prometheus/opentelemetry dependencies, this is a high-value addition.

• [ ] Create core/breaker/metrics_test.go to validate Prometheus counter/histogram emissions
• [ ] Test metric labels (service, method, state transitions) for breaker.go and googlebreaker.go
• [ ] Add tests verifying metrics are NOT emitted for nopbreaker.go (no-op implementation)
• [ ] Add integration test with real Prometheus client in core/breaker/integration_test.go

Add validation tests for core/conf schema with complex nested structures

The core/conf/validate.go handles configuration validation but the test coverage (validate_test.go) likely lacks edge cases for deeply nested configs with custom validators. Given go-zero's role in microservice infrastructure, robust config validation is critical.

• [ ] Expand core/conf/validate_test.go with tests for recursive/circular struct references
• [ ] Add tests for validation of config arrays and maps with mixed types
• [ ] Test interaction between core/conf/config.go and core/conf/validate.go for YAML/TOML with complex inheritance
• [ ] Add benchmark tests in core/conf/validate_test.go for large config files (1000+ fields)

• Add test coverage for core/collection/ring.go and core/collection/fifo.go edge cases (concurrent append/pop, boundary conditions at capacity limits)
• Document the circuit breaker state machine transitions in core/breaker/googlebreaker.go with inline diagrams or a CIRCUITBREAKER.md guide, as the state machine (closed → open → half-open → closed) is non-obvious
• Extend core/codec with AES-GCM support (authenticated encryption) alongside existing AES-ECB to prevent padding oracle attacks; add tests in core/codec/aesgcm_test.go

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.