upkg/example/redis-cache/README.md

Redis Cache Demo

一个完整的 Kubernetes 应用示例，展示 Redis 缓存的使用，支持自动读写分离和重连。

功能特性

• ✅ 自动识别 Kubernetes Headless Service
• ✅ Master-Replica 读写分离
• ✅ 自动重连机制（每10秒检测）
• ✅ HTTP API 接口
• ✅ 健康检查
• ✅ 完整的 K8s 部署配置

架构设计

┌─────────────────┐    ┌─────────────────┐
│   App Pod #1    │    │   App Pod #2    │
│   (Read/Write)  │    │   (Read/Write)  │
└─────────┬───────┘    └─────────┬───────┘
          │                      │
          └──────────┬───────────┘
                     │
    ┌────────────────┴─────────────────┐
    │        Redis Cluster            │
    │  ┌─────┐  ┌─────┐  ┌─────┐    │
    │  │Pod-0│  │Pod-1│  │Pod-2│    │
    │  │Master│ │Replica││Replica│   │
    │  └─────┘  └─────┘  └─────┘    │
    └─────────────────────────────────┘

快速开始

1. 部署 Redis 集群

chmod +x deploy.sh
./deploy.sh

这将创建：

• 3个 Redis Pod（1个master + 2个replica）
• Headless Service（用于自动发现）
• LoadBalancer Service（用于外部访问）

2. 构建和部署应用

# 构建镜像
docker build -t redis-cache-demo:latest .

# 部署应用
kubectl apply -f k8s/app.yaml

# 等待应用就绪
kubectl wait --for=condition=ready pod -l app=redis-cache-demo -n redis-cache-demo --timeout=120s

# 获取服务地址
kubectl get svc redis-cache-demo -n redis-cache-demo

3. 测试 API

获取服务地址后，替换 <SERVICE_IP> 进行测试：

# 健康检查
curl http://<SERVICE_IP>/health

# 设置缓存
curl -X POST http://<SERVICE_IP>/api/cache/test -H 'Content-Type: application/json' -d '{
  "value": "hello world",
  "expires_in": 300
}'

# 获取缓存
curl http://<SERVICE_IP>/api/cache/test

# Hash 操作
curl -X POST http://<SERVICE_IP>/api/hash/user:1/name -H 'Content-Type: application/json' -d '{"value":"张三"}'
curl http://<SERVICE_IP>/api/hash/user:1/name

# 计数器
curl -X POST http://<SERVICE_IP>/api/counter/visits/inc

# 测试重连
curl -X POST http://<SERVICE_IP>/api/test/reconnect

API 文档

基础缓存操作

Method	Path	Description
GET	/api/cache/:key	获取值
POST	/api/cache/:key	设置值
DELETE	/api/cache/:key	删除键

Hash 操作

Method	Path	Description
GET	/api/hash/:key/:field	获取字段值
POST	/api/hash/:key/:field	设置字段值
GET	/api/hash/:key	获取所有字段

计数器

Method	Path	Description
POST	/api/counter/:key/inc	计数器+1
POST	/api/counter/:key/inc/:value	计数器+指定值

系统功能

Method	Path	Description
GET	/health	健康检查
POST	/api/test/reconnect	测试重连功能

环境变量配置

变量名	默认值	说明
PORT	8080	HTTP 服务端口
REDIS_ADDR	-	Redis 地址（支持 headless service）
REDIS_PASSWORD	""	Redis 密码
REDIS_RECONNECT	true	是否启用自动重连
REDIS_RECONNECT_INTERVAL	10s	重连检测间隔

观察读写分离

在多个终端中监控 Redis 请求分布：

# 监控 master（写操作）
kubectl exec -it redis-0 -n redis-cache-demo -- redis-cli monitor

# 监控 replica（读操作）
kubectl exec -it redis-1 -n redis-cache-demo -- redis-cli monitor
kubectl exec -it redis-2 -n redis-cache-demo -- redis-cli monitor

执行应用 API 操作，观察请求如何分布到不同的 Redis 实例。

重连测试

1. 重启 Redis Pod：

   kubectl delete pod redis-1 -n redis-cache-demo
   

2. 继续调用 API，观察自动重连日志：

   kubectl logs -f deployment/redis-cache-demo -n redis-cache-demo
   

本地开发

使用内存缓存进行本地测试：

export REDIS_ADDR=""
go run main.go

使用本地 Redis：

export REDIS_ADDR="localhost:6379"
go run main.go