xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
96a936e154e5e06fce93f0454edd7df57cae0a3b
Edu/services/api-gateway
History
SpecialX 61d824924a fix: 修复集成测试中发现的全部 bug — 15 服务端到端验证通过 
修复涵盖 6 大类问题：

1. api-gateway
   - 路径前缀剥离 /api 而非 /api/v1，保留下游 /v1/ controller 前缀
   - JWKS URL 默认值修复
   - publicPaths 白名单对齐 /v1/iam/*

2. iam
   - iam.module.ts exports 补充 PermissionCacheService 和 IamRepository
   - main.ts resolveProtoPath() 多路径探测 proto 文件

3. core-edu
   - app.module.ts AuthMiddleware 全局注册

4. BFF 层 GraphQL 端点（teacher-bff / parent-bff / student-bff）
   - teacher-bff: mock dataScope OWN→SELF 对齐 GraphQL enum；WHATWG Request header .get() 提取
   - parent-bff: handleNodeRequestAndResponse 不存在 → 直接 yoga(req,res)；WHATWG Request header .get() 提取
   - student-bff: auth.resolver 移除 ActionState 信封返回扁平对象；WHATWG Request header .get() 提取

5. ai
   - Kafka 事务降级 + 10s 超时
   - gRPC 拦截器降级
   - dev mode 禁用事务模式

6. 前端 + 共享包
   - teacher-portal: MF 插件条件实例化 + transpilePackages + extensionAlias
   - ui-components: error-boundary.tsx 添加 use client
   - ui-tokens: tailwind-theme.css 移除 @layer base
   - shared-ts: 导出从源码改为 dist 编译产物；OutboxModule global:true

7. infra
   - .gitignore 补充 keys/ *.pem *.key secrets/ 排除规则
   - infra/init-sql/02-all-services-schema.sql 36 张表 DDL

验证结果：
- TS typecheck: 19 个 workspace 项目全部通过
- Go vet + Ruff: 通过
- 15 服务全部启动成功
- 3 个 BFF GraphQL 端点 + 4 个前端页面全部 200
- Gateway → iam → core-edu 端到端链路验证通过

AI identity: trae-main（集成测试修复会话）
2026-07-11 01:41:46 +08:00
..
docs
feat(api-gateway): 实现 W1-W8 网关硬化与 P2-P5 路由扩展
2026-07-10 18:15:48 +08:00
internal
fix: 修复集成测试中发现的全部 bug — 15 服务端到端验证通过
2026-07-11 01:41:46 +08:00
Dockerfile
feat(infra): 新增生产 Dockerfile 与部署 compose
2026-07-08 15:12:34 +08:00
go.mod
feat(api-gateway): 实现 W1-W8 网关硬化与 P2-P5 路由扩展
2026-07-10 18:15:48 +08:00
go.sum
fix: code compliance audit and fix across all services
2026-07-09 17:28:27 +08:00
main.go
feat(api-gateway): 实现 W1-W8 网关硬化与 P2-P5 路由扩展
2026-07-10 18:15:48 +08:00
README.md
feat(api-gateway): 实现 W1-W8 网关硬化与 P2-P5 路由扩展
2026-07-10 18:15:48 +08:00

README.md

API Gateway

Go (Gin) 实现的 API 网关，所有外部请求的统一入口。

职责

  • 路由转发：/api/v1/<service>/* → 下游服务（iam / teacher-bff / student-bff / parent-bff / core-edu / content / msg / ai / data-ana）
  • JWT 鉴权：RS256（IAM 签发，Gateway 通过 JWKS 公钥校验），DevMode 下支持 dev-token 旁路
  • 请求 ID 注入：生成或透传 X-Request-Id（req-<uuid-v4> 格式），全链路追踪
  • 限流：基于令牌桶的 per-IP 限流（100 rps，突发 20），超限返回 429 + GW_RATE_LIMITED
  • 熔断：基于 gobreaker v2 的下游服务熔断，5xx 错误率 > 50% 触发 OPEN，返回 503 + GW_CIRCUIT_OPEN
  • 可观测性：slog 结构化日志 + 7 个业务 metrics + OpenTelemetry tracer（资源属性完整）
  • CORS / 安全头 / Recovery：标准化中间件链

中间件链

请求处理顺序（自外向内）：

Request → Recovery → OTel → RequestID → CORS → SecurityHeaders → RequestBodyLimit → RateLimit
  → [api/v1 组] CircuitBreaker → AuthMiddleware(RS256) → Metrics → Proxy → Response
中间件 文件 职责
Recovery internal/middleware/recovery.go panic 兜底返回 500 + GW_INTERNAL_ERROR
OTel otelgin.Middleware OpenTelemetry 自动埋点
RequestID internal/middleware/requestid.go 生成/透传 X-Request-Id（req-<uuid-v4>）
CORS internal/middleware/cors.go 跨域允许（从 Config 读取白名单）
SecurityHeaders internal/middleware/security.go 安全响应头 + 请求体限制（413 GW_REQUEST_TOO_LARGE）
RateLimit internal/middleware/ratelimit.go per-IP 令牌桶限流，超限 429 GW_RATE_LIMITED
CircuitBreaker internal/middleware/circuit-breaker.go 下游 5xx 错误率 > 50% 触发熔断，503 GW_CIRCUIT_OPEN
Auth internal/middleware/auth.go JWT RS256 校验（JWKS），注入 x-user-id/x-user-roles/x-data-scope
Metrics internal/observability/metrics.go HTTP 请求计数 + 延迟统计（7 个业务指标）

路由表

前缀 目标服务 端口 鉴权
/api/v1/iam/* iam 3002 JWT（register/login/refresh 白名单）
/api/v1/teacher/* teacher-bff 3003 JWT
/api/v1/student/* student-bff 3009 JWT
/api/v1/parent/* parent-bff 3010 JWT
/api/v1/classes/* core-edu 3004 JWT
/api/v1/exams/* core-edu 3004 JWT
/api/v1/homework/* core-edu 3004 JWT
/api/v1/grades/* core-edu 3004 JWT
/api/v1/textbooks/* content 3005 JWT
/api/v1/chapters/* content 3005 JWT
/api/v1/knowledge-points/* content 3005 JWT
/api/v1/questions/* content 3005 JWT
/api/v1/notifications/* msg 3007 JWT
/api/v1/messages/* msg 3007 JWT
/api/v1/ai/* ai 3008 JWT
/api/v1/analytics/* data-ana 3006 JWT
/api/v1/dashboard/* data-ana 3006 JWT

健康检查

端点 用途 鉴权
GET /healthz 存活探针（liveness） 无
GET /readyz 就绪探针（readiness，并行 ping 下游 /healthz，软失败规则） 无
GET /metrics Prometheus 指标端点（7 个业务指标 + Go runtime） 无

开发

cd services/api-gateway
go run main.go

DevMode（接受 Bearer dev-token 旁路鉴权）：

DEV_MODE=true go run main.go

测试

cd services/api-gateway
go test ./internal/middleware/... -v -cover

构建

go build ./...
docker build -t edu/api-gateway .

配置

通过环境变量配置（见 internal/config/config.go）：

变量 默认值 说明
API_GATEWAY_PORT 8080 监听端口
ENV development 部署环境（production 时 W7 防护生效）
DEV_MODE false 开发模式旁路：true 时接受 Bearer dev-token（仅非生产）
IAM_JWKS_URL http://localhost:3002/.well-known/jwks.json RS256 公钥端点（非 DevMode 必填）
JWT_ISSUER next-edu-cloud JWT 签发者校验
JWT_AUDIENCE next-edu-cloud JWT 受众校验
CORS_ORIGINS （空，用开发默认白名单） CORS 白名单（逗号分隔）
CLASSES_SERVICE_URL http://localhost:3001 classes 服务地址（遗留，路由实际走 core-edu）
IAM_SERVICE_URL http://localhost:3002 iam 服务地址
TEACHER_BFF_URL http://localhost:3003 teacher-bff 服务地址
STUDENT_BFF_URL http://localhost:3009 student-bff 服务地址
PARENT_BFF_URL http://localhost:3010 parent-bff 服务地址
CORE_EDU_SERVICE_URL http://localhost:3004 core-edu 服务地址
CONTENT_SERVICE_URL http://localhost:3005 content 服务地址
DATA_ANA_SERVICE_URL http://localhost:3006 data-ana 服务地址
MSG_SERVICE_URL http://localhost:3007 msg 服务地址
AI_SERVICE_URL http://localhost:3008 ai 服务地址
OTEL_EXPORTER_OTLP_ENDPOINT http://localhost:4318 OpenTelemetry OTLP 端点
LOG_LEVEL info 日志级别

生产环境警告：DEV_MODE=true 且 ENV=production 时服务 panic 拒绝启动（W7 防护）。

关联文档

Reference in New Issue View Git Blame Copy Permalink