834e2c61fd
阶段1交付：services/api-gateway/docs/01-understanding.md - 8节内容：架构位置/限界上下文/契约/技术栈/阶段归属/黄金模板对齐审计 - 审计13项差距（3高：缺/metrics、/readyz stub、auth.go死代码；4中：log/slog缺失、go.mod版本不匹配、HS256待升RS256、DevMode风险；6低） 阶段2交付：services/api-gateway/docs/02-architecture-design.md - 9节内容：内部分层图/路由表矩阵9下游/限流策略表/熔断阈值表/JWT RS256流程含JWKS缓存/CORS白名单/请求ID注入/metrics 7项指标/P0-P3实施优先级 同步更新 docs/troubleshooting/known-issues.md 工作经验日志（追加ai01条目） AI Agent: ai01 (api-gateway/push-gateway) Branch: main Coordinator: coord
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）：
| 变量 | 默认值 | 说明 |
|---|---|---|
API_GATEWAY_PORT |
8080 | 监听端口 |
JWT_SECRET |
（必填） | HS256 签名密钥（P1） |
JWT_ISSUER |
next-edu-cloud | JWT 签发者 |
JWT_AUDIENCE |
next-edu-cloud | JWT 受众 |
DEV_MODE |
false | 开发模式旁路：true 时接受 Bearer dev-token（仅本地） |
CLASSES_SERVICE_URL |
http://localhost:3001 | classes 服务地址 |
IAM_SERVICE_URL |
http://localhost:3002 | iam 服务地址 |
TEACHER_BFF_URL |
http://localhost:3003 | teacher-bff 服务地址 |
OTEL_EXPORTER_OTLP_ENDPOINT |
http://localhost:4318 | OpenTelemetry OTLP 端点 |
LOG_LEVEL |
info | 日志级别 |
生产环境警告：
DEV_MODE必须为false或不设。设为true会允许dev-token旁路鉴权并注入固定 admin 身份。