faaaf29f67
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
4.8 KiB
4.8 KiB
api-gateway 对接契约
§1 我提供什么（对外接口）
1.1 gRPC 接口（如有）
无。api-gateway 是 HTTP 入口，不对外提供 gRPC。
1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
|---|---|---|---|
| ANY | /api/auth/* | 代理到 iam 认证相关（登录/注册/刷新 token） | 公开（登录注册免认证） |
| ANY | /api/teacher/* | 代理到 teacher-bff GraphQL（:3003） | JWT 必需 |
| ANY | /api/student/* | 代理到 student-bff GraphQL（:3009） | JWT 必需 |
| ANY | /api/parent/* | 代理到 parent-bff GraphQL（:3010） | JWT 必需 |
| ANY | /api/admin/* | 代理到 teacher-bff GraphQL admin namespace | JWT 必需 + admin 角色 |
| GET | /healthz | 网关健康检查（liveness） | 公开 |
| GET | /readyz | 网关就绪检查（readiness，含 iam 连通性） | 公开 |
| GET | /metrics | Prometheus 指标端点 | 公开（内网） |
1.3 GraphQL schema（如 BFF）
不适用。api-gateway 仅做 HTTP 反向代理 + JWT 验签，不解析 GraphQL。
1.4 Kafka 事件发布（如有）
无。api-gateway 不发布事件。
1.5 错误码前缀
GW_（如 GW_UNAUTHORIZED、GW_RATE_LIMITED、GW_CIRCUIT_OPEN、GW_BACKEND_UNAVAILABLE）
§2 我消费什么（依赖上游）
2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
|---|---|---|---|
| iam (ai06) | IamService.GetPublicKey | 启动时拉取 RS256 公钥，用于 JWT 验签 | iam 就绪前使用本地固定 mock 公钥（与 mock 私钥配对签发 mock JWT） |
| iam (ai06) | IamService.GetEffectiveAccess | 权限校验（可选，部分路由需要细粒度权限） | iam 就绪前放行所有请求（仅校验 JWT 签名） |
2.2 Kafka 事件订阅（异步）
无。api-gateway 不订阅 Kafka 事件。
2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
|---|---|---|---|
| teacher-bff (ai03) | POST /graphql | 反向代理教师端 GraphQL 请求 | teacher-bff 就绪前返回 502，前端使用本地 mock 数据 |
| student-bff (ai04) | POST /graphql | 反向代理学生端 GraphQL 请求 | student-bff 就绪前返回 502 |
| parent-bff (ai05) | POST /graphql | 反向代理家长端 GraphQL 请求 | parent-bff 就绪前返回 502 |
§3 就绪信号
3.1 我依赖的上游就绪标志
- iam gRPC 50052 启用（ai06）—— GetPublicKey 拉取验签公钥
- teacher-bff GraphQL :3003 启用（ai03）
- student-bff GraphQL :3009 启用（ai04）
- parent-bff GraphQL :3010 启用（ai05）
3.2 我的就绪标志（供下游消费）
- api-gateway HTTP :8080 启用（/healthz 返回 200）
- /readyz 返回 200（含 iam 连通性检查通过）
- JWT 验签链路打通（使用 iam 公钥校验 access_token）
- /api/auth/* 代理到 iam 认证链路可用
- /api/teacher/* /api/student/* /api/parent/* 反向代理到各 BFF 可用
- 限流（IP 级令牌桶）+ 熔断（各后端独立熔断器）生效
§4 Mock 策略
4.1 我提供的 mock
在 api-gateway 真实就绪前，为下游（各前端 portal）提供以下 mock：
- HTTP mock：使用 MSW（Mock Service Worker）或本地 nginx 拦截
- /api/auth/login 返回固定 JWT（mock 签发）+ UserInfo
- /api/teacher/* /api/student/* /api/parent/* 直接返回各 BFF 的 mock GraphQL 响应
- /healthz /readyz 返回 200
- JWT mock：前端开发期使用固定 mock JWT（api-gateway 就绪前不走真实验签）
4.2 我消费的 mock
在真实上游就绪前，api-gateway 使用以下 mock：
- iam 公钥：使用本地固定 mock RS256 公钥（与 mock 私钥配对），验签 mock JWT
- iam 权限校验：GetEffectiveAccess 返回 allowed=true，放行所有请求
- 各 BFF 代理：BFF 就绪前返回 503 + Retry-After，前端降级到本地 mock 数据