a4cd970c54
- go.mod: 新增 github.com/sony/gobreaker/v2 v2.1.0 - go.sum: 同步校验和 - README: 新增 P6 中间件链说明、健康检查端点表、测试说明、配置环境变量表
3.8 KiB
3.8 KiB
API Gateway
Go (Gin) 实现的 API 网关，所有外部请求的统一入口。
职责
- 路由转发：
/api/v1/classes/*→ classes 服务（P1），后续阶段追加 iam/core-edu/content/msg 等路由 - JWT 鉴权：P1 HS256（测试密钥），P2 起 RS256（IAM 签发，Gateway 公钥校验）
- 请求 ID 注入：生成或透传
X-Request-ID，全链路追踪 - 限流（P6）：基于令牌桶的 per-IP 限流，超限返回 429
- 熔断（P6）：基于 gobreaker v2 的下游服务熔断，5xx 错误率 > 50% 触发 OPEN
- CORS / 安全头 / Recovery（P6）：标准化中间件链
中间件链（P6）
请求处理顺序（自外向内）：
Request → RequestID → CORS → Security → Recovery → RateLimit → Auth → CircuitBreaker → Proxy → Response
| 中间件 | 文件 | 职责 |
|---|---|---|
| RequestID | internal/middleware/requestid.go |
生成/透传 X-Request-ID |
| CORS | internal/middleware/cors.go |
跨域允许 |
| Security | internal/middleware/security.go |
安全响应头（X-Content-Type-Options 等） |
| Recovery | internal/middleware/recovery.go |
panic 兜底返回 500 |
| RateLimit | internal/middleware/ratelimit.go |
per-IP 令牌桶限流，超限 429 |
| Auth | internal/middleware/auth.go |
JWT 校验，注入 x-user-id/x-user-roles 头 |
| CircuitBreaker | internal/middleware/circuit-breaker.go |
下游 5xx 错误率 > 50% 触发熔断，返回 503 |
健康检查
| 端点 | 用途 | 鉴权 |
|---|---|---|
GET /healthz |
存活探针（liveness） | 无 |
GET /readyz |
就绪探针（readiness） | 无 |
GET /health |
兼容端点（返回 { status, timestamp }） |
无 |
开发
cd services/api-gateway
go mod tidy
go run main.go
测试
# 单元 + 集成测试
cd services/api-gateway
go test ./internal/middleware/... -v -cover
# 测试覆盖
# - circuit-breaker_test.go: 5 用例（ClosedToOpen / OpenToHalfOpen / HalfOpenToClosed / HalfOpenToOpen / 4xxNotCounted）
# - ratelimit_test.go: 5 用例（AllowUnderBurst / RejectOverBurst / RefillTokens / PerIPIsolation / CleanupExpiredBuckets）
构建
# 本地构建
go build ./...
# Docker 构建
docker build -t edu/api-gateway .
配置
通过环境变量配置（见 internal/config/config.go）：
| 变量 | 默认值 | 说明 |
|---|---|---|
PORT |
8080 | 监听端口 |
JWT_SECRET |
（必填） | HS256 签名密钥（P1） |
JWT_PUBLIC_KEY |
（P2） | RS256 公钥 |
CLASSES_SERVICE_URL |
http://localhost:3001 | classes 服务地址 |
RATE_LIMIT_RPS |
10 | 每秒令牌数 |
RATE_LIMIT_BURST |
20 | 突发容量 |