README
¶
🔧 Go 微服务工具包 / Go Microservice Kit
生产级 Go 微服务工具包，集成 gRPC、中间件链、熔断器、服务发现和分布式追踪
❓ 为什么选择这个项目？| Why This Project?
中文： 构建生产级 Go 微服务需要整合大量横切关注点：认证、限流、熔断、追踪、服务发现。现有框架要么过于庞大（go-kit），要么功能不全（go-micro）。本项目提供开箱即用的微服务工具包，让你专注于业务逻辑而非基础设施。
English: Building production Go microservices requires wiring many cross-cutting concerns: auth, rate limiting, circuit breaking, tracing, service discovery. Existing frameworks are either too heavy (go-kit) or lack features (go-micro). This project provides a ready-to-use toolkit so you can focus on business logic, not infrastructure.
📊 功能对比 | Feature Comparison
| 项目 | 优势 | 不足 | 推荐度 |
|---|---|---|---|
| go-kit/kit | 成熟稳定 | 学习曲线陡峭，样板代码多 | ⭐⭐⭐ |
| micro/micro | 功能全面 | 框架绑定强，灵活性低 | ⭐⭐⭐ |
| go-kratos/kratos | protobuf 优先 | 依赖较多，定制性一般 | ⭐⭐⭐⭐ |
| go-zero/go-zero | 代码生成 | 生成代码难定制 | ⭐⭐⭐⭐ |
🚀 一键部署 | Deploy with One Click
🗺️ Roadmap | 路线图
- 支持 etcd 服务发现 / etcd service discovery support
- 添加 GraphQL 网关 / GraphQL gateway support
- 集成 OpenPolicyAgent / OpenPolicyAgent integration
- 支持 WebSocket 长连接 / WebSocket long connection support
👥 Contributors | 贡献者
⭐ Star History | Star 历史
A production-ready Go microservice toolkit with gRPC, middleware chain, circuit breaker, service discovery, and distributed tracing.
🏗️ Architecture Diagram
graph TB
Client[Client / API Gateway]
subgraph "Transport Layer"
HTTP[HTTP Server<br/>Chi Router]
GRPC[gRPC Server<br/>Interceptors Chain]
end
subgraph "HTTP Middleware"
CORS[CORS]
ReqID[Request ID]
RL1[Rate Limiter]
JWT1[JWT Auth]
LOG1[Logging]
REC1[Recovery]
end
subgraph "gRPC Interceptors"
REC2[Recovery]
LOG2[Logging]
RL2[Rate Limiter]
CB[Circuit Breaker]
JWT2[JWT Auth]
OT[OpenTelemetry]
end
subgraph "Business Logic Layer"
SVC[Service Handlers]
end
subgraph "Infrastructure"
Redis[(Redis Cache<br/>go-redis/v9)]
Consul[(Consul<br/>Service Discovery)]
Jaeger[(Jaeger<br/>Distributed Tracing)]
end
subgraph "Observability"
Prom[Prometheus Metrics]
Grafana[Grafana Dashboards]
JUI[Jaeger UI]
end
Client --> HTTP
Client --> GRPC
HTTP --> CORS --> ReqID --> RL1 --> JWT1 --> LOG1 --> REC1 --> SVC
GRPC --> REC2 --> LOG2 --> RL2 --> CB --> JWT2 --> OT --> SVC
SVC --> Redis
SVC --> Consul
SVC --> Jaeger
Prom --> Grafana
Jaeger --> JUI
⚡ Benchmark / Performance
Benchmarks run on AMD Ryzen 9 5950X, Go 1.21, Ubuntu 22.04.
HTTP Middleware Chain Overhead
| Middleware Stack | Throughput (req/s) | P50 Latency | P99 Latency | Alloc/Op |
|---|---|---|---|---|
| Baseline (no middleware) | 48,200 | 0.21ms | 0.58ms | 128 B |
| + Logging + Recovery | 45,600 | 0.22ms | 0.63ms | 256 B |
| + JWT Auth | 42,100 | 0.24ms | 0.71ms | 512 B |
| + Rate Limiter | 39,800 | 0.26ms | 0.82ms | 384 B |
| Full Stack | 36,500 | 0.28ms | 0.95ms | 1.2 KB |
gRPC Unary Call Performance
| Scenario | Throughput (calls/s) | P50 Latency | P99 Latency |
|---|---|---|---|
| No interceptor | 62,000 | 0.16ms | 0.42ms |
| Full interceptor chain | 54,200 | 0.19ms | 0.58ms |
| With circuit breaker (closed) | 53,800 | 0.19ms | 0.61ms |
Circuit Breaker Recovery
| Metric | Value |
|---|---|
| Open → Half-Open transition | 5s (configurable) |
| Half-Open probe success threshold | 3 consecutive successes |
| Full recovery time (after backend restored) | ~8s |
Service Discovery (Consul)
| Operation | Avg Latency | P99 Latency |
|---|---|---|
| Service registration | 12ms | 28ms |
| DNS lookup (cached) | 0.3ms | 0.8ms |
| Health check round | 45ms | 120ms |
Run benchmarks yourself:
make bench
🚀 Quick Start (One-liner)
curl -fsSL https://raw.githubusercontent.com/gal111111/go-microservice-kit/main/docker-compose.demo.yml | docker compose -f - up -d
Or with Go install:
go install github.com/gal111111/go-microservice-kit@latest && go-microservice-kit -config config.yaml
🎯 Use Cases / Who Is This For?
Who should use go-microservice-kit?
- Backend Engineers building production Go microservices who don't want to wire up middleware, tracing, and service discovery from scratch
- Platform Teams establishing internal Go microservice standards and shared infrastructure patterns
- Teams migrating from monoliths who need a battle-tested starting point with all cross-cutting concerns handled
- DevOps Engineers who want observability, health checks, and graceful shutdown built-in from day one
- Startups that need enterprise-grade reliability without enterprise-grade complexity
Real-world use cases
| Use Case | How go-microservice-kit Helps |
|---|---|
| E-commerce order service | JWT auth + rate limiting + circuit breaker protect downstream inventory/payment services |
| Fintech transaction processor | Distributed tracing + structured logging for audit compliance |
| SaaS multi-tenant API | Per-tenant rate limiting + Redis caching + service discovery for tenant isolation |
| IoT data ingestion pipeline | gRPC for high-throughput + circuit breaker for unreliable downstream services |
| Real-time notification service | Dual HTTP/gRPC support + Consul service discovery for dynamic scaling |
🗺️ Roadmap
v1.0 (Current)
- HTTP + gRPC dual protocol support
- JWT authentication middleware
- Token bucket rate limiting
- Three-state circuit breaker
- Consul service discovery
- OpenTelemetry + Jaeger tracing
- Prometheus metrics
- Docker Compose full stack
v1.1 (Next)
- etcd service discovery backend
- GraphQL gateway integration
- Open Policy Agent authorization
- WebSocket long connection support
- Health check gRPC reflection
v1.2 (Planned)
- Service mesh integration (Istio/Linkerd)
- Distributed transaction support (Saga pattern)
- Configuration hot-reload
- Plugin system for custom middleware
- Kubernetes Helm chart
v2.0 (Future)
- Multi-language SDK (Python, TypeScript)
- Web dashboard for service topology
- AI-powered anomaly detection
- Event sourcing support
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Client / Gateway │
└──────────────┬──────────────────────────┬───────────────────────┘
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────────┐
│ HTTP Server │ │ gRPC Server │
│ (Chi Router) │ │ (Interceptors Chain) │
│ │ │ │
│ ┌────────────────┐ │ │ ┌──────────────────────┐ │
│ │ CORS │ │ │ │ Recovery │ │
│ │ Request ID │ │ │ │ Logging │ │
│ │ Rate Limiter │ │ │ │ Rate Limiter │ │
│ │ JWT Auth │ │ │ │ Circuit Breaker │ │
│ │ Logging │ │ │ │ JWT Auth │ │
│ │ Recovery │ │ │ │ OpenTelemetry │ │
│ └────────────────┘ │ │ └──────────────────────┘ │
└──────────┬───────────┘ └──────────┬───────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ Business Logic Layer │
└──────────┬────────────────────┬──────────────────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Redis Cache │ │ Consul Registry │ │ Jaeger Tracing │
│ (go-redis/v9) │ │ (Service Disc.) │ │ (OpenTelemetry)│
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ Monitoring & Observability │
│ │
│ Prometheus Metrics │ Grafana Dashboards │ Jaeger UI │
└──────────────────────────────────────────────────────────────┘
Features
- Dual Protocol Support - HTTP (Chi) + gRPC server with shared business logic
- Middleware Chain - Ordered interceptor pipeline for both HTTP and gRPC
- JWT Authentication - HMAC-SHA256 token generation and validation
- Token Bucket Rate Limiting - Per-client rate limiting with configurable rate/burst
- Circuit Breaker - Three-state (Closed/Half-Open/Open) with configurable thresholds
- Panic Recovery - Graceful panic handling with stack trace logging
- Service Discovery - Consul-based registration, health checks, and service watching
- Distributed Tracing - OpenTelemetry + Jaeger with gRPC OTLP export
- Structured Logging - Zap-based logging with development/production modes
- Prometheus Metrics - Built-in /metrics endpoint for monitoring
- Redis Integration - go-redis/v9 with connection pooling
- Graceful Shutdown - Signal-based shutdown with timeout and service deregistration
- Docker Compose - Full stack with Redis, Consul, Jaeger, Prometheus, Grafana
- Multi-stage Docker Build - Minimal Alpine-based production image
Quick Start
Prerequisites
- Go 1.21+
- Docker & Docker Compose
- Make (optional)
Using Docker Compose (Recommended)
# Clone the repository
git clone https://github.com/gal111111/go-microservice-kit.git
cd go-microservice-kit
# Start the full stack
make docker-up
# Check service health
curl http://localhost:8080/health
Running Locally
# Install dependencies
go mod tidy
# Run the service
go run .
# Or use make
make run
Generate a JWT Token
curl -X POST http://localhost:8080/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"user_id": "1", "username": "admin", "role": "admin"}'
Access Protected Endpoints
curl http://localhost:8080/api/v1/users \
-H "Authorization: Bearer <your-token>"
Access Monitoring
| Service | URL |
|---|---|
| HTTP API | http://localhost:8080 |
| gRPC | localhost:9090 |
| Health Check | http://localhost:8080/health |
| Prometheus Metrics | http://localhost:8080/metrics |
| Consul UI | http://localhost:8500 |
| Jaeger UI | http://localhost:16686 |
| Grafana | http://localhost:3000 (admin/admin) |
| Prometheus | http://localhost:9091 |
Project Structure
go-microservice-kit/
├── main.go # 入口：优雅关闭、配置加载
├── config/
│ └── config.go # Viper配置：环境变量绑定、默认值
├── middleware/
│ ├── auth.go # JWT认证中间件
│ ├── logging.go # 请求日志中间件（zap）
│ ├── ratelimit.go # 令牌桶限流器
│ ├── circuitbreaker.go # 熔断器模式实现
│ └── recovery.go # Panic恢复中间件
├── server/
│ ├── grpc_server.go # gRPC服务器：拦截器链、KeepAlive
│ └── http_server.go # HTTP服务器：Chi路由、CORS、JWT
├── discovery/
│ └── consul.go # Consul服务发现：注册、注销、监听
├── tracing/
│ └── jaeger.go # OpenTelemetry Jaeger追踪
├── pkg/
│ ├── response/
│ │ └── response.go # 标准化响应类型
│ └── errors/
│ └── errors.go # 自定义错误类型与错误码
├── Dockerfile # 多阶段Docker构建
├── docker-compose.yml # 全栈编排
├── Makefile # 构建、测试、部署命令
└── config.yaml # 配置文件
Configuration
Configuration is managed via Viper with environment variable override support. All config keys can be overridden with SECTION_KEY format (e.g., SERVER_PORT=8080).
See config.yaml for all available options with defaults.
Make Commands
make build # 编译项目
make run # 运行项目
make test # 运行测试（含覆盖率）
make lint # 代码检查
make tidy # 整理依赖
make clean # 清理构建产物
make docker-build # 构建Docker镜像
make docker-up # 启动Docker Compose
make docker-down # 停止Docker Compose
make fmt # 格式化代码
make vet # 静态分析
make all # 完整CI流程
License
MIT License
Documentation
¶
There is no documentation for this package.
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.