feat(student-bff): 完整实现 student-bff 聚合层

包含 src 全部实现、Dockerfile、shared-ts/bff 包等

services/student-bff/src/main.ts

@@ -0,0 +1,114 @@
+/**
+ * student-bff 启动入口.
+ *
+ * 仲裁依据:
+ *   - coord-final-decisions §1 G1 (Dockerfile 多阶段构建, EXPOSE 3009)
+ *   - coord-final-decisions §1 G3 (/healthz liveness)
+ *   - coord-final-decisions §1 G5 (/metrics 端点)
+ *   - coord-final-decisions §1 G6 (OTel tracer)
+ *   - coord-final-decisions §1 G8 (GlobalErrorFilter)
+ *   - coord-final-decisions §1 G9 (优雅关闭 SIGTERM)
+ *   - coord-final-decisions §2 B1 (GraphQL Yoga endpoint: POST /graphql)
+ *   - port-allocation.md (HTTP 3009, 无 gRPC 对外)
+ *
+ * 启动流程:
+ *   1. initTracer (OTel)
+ *   2. NestFactory.create(AppModule)
+ *   3. app.useGlobalFilters(GlobalErrorFilter)
+ *   4. 挂载 GraphQL Yoga middleware (POST /graphql)
+ *   5. 注册 /metrics 端点
+ *   6. app.listen(3009)
+ *   7. SIGTERM → app.close() → 关闭 Redis/gRPC/Tracer
+ */
+import "reflect-metadata";
+import { NestFactory } from "@nestjs/core";
+import type { NestExpressApplication } from "@nestjs/platform-express";
+import { AppModule } from "./app.module.js";
+import { GlobalErrorFilter } from "./shared/errors/global-error.filter.js";
+import { initTracer, shutdownTracer } from "./shared/observability/tracer.js";
+import { logger } from "./shared/observability/logger.js";
+import { metricsRegistry } from "./shared/observability/metrics.js";
+import { env } from "./config/env.js";
+import { GRAPHQL_YOGA } from "./student/student.module.js";
+import { REDIS_CLIENT } from "./shared/cache/cache.module.js";
+import { DOWNSTREAM_CLIENT } from "./shared/downstream/downstream.module.js";
+import { CircuitBreakerService } from "./shared/circuit-breaker/circuit-breaker.service.js";
+import type { Redis } from "ioredis";
+import type { DownstreamClient } from "@edu/shared-ts/bff";
+import type { YogaServerInstance } from "graphql-yoga";
+import type { Request, Response, NextFunction } from "express";
+
+async function bootstrap(): Promise<void> {
+  initTracer();
+
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+    logger: ["log", "error", "warn"],
+  });
+
+  // G8 全局错误过滤器
+  app.useGlobalFilters(new GlobalErrorFilter());
+
+  app.enableShutdownHooks();
+
+  // B1 GraphQL Yoga endpoint 挂载
+  const yoga = (await app.resolve(GRAPHQL_YOGA)) as YogaServerInstance<
+    Record<string, unknown>,
+    unknown
+  >;
+  const httpAdapter = app.getHttpAdapter().getInstance();
+  httpAdapter.use(
+    "/graphql",
+    (req: Request, res: Response, next: NextFunction) => {
+      yoga.handle(req, res).catch((err: unknown) => {
+        logger.error({ err }, "GraphQL Yoga handle error");
+        next(err);
+      });
+    },
+  );
+
+  // G5 Prometheus 指标端点 (不鉴权)
+  httpAdapter.get("/metrics", async (_req: Request, res: Response) => {
+    res.set("Content-Type", metricsRegistry.contentType);
+    res.end(await metricsRegistry.metrics());
+  });
+
+  await app.listen(env.PORT);
+  logger.info(
+    {
+      port: env.PORT,
+      graphql: "/graphql",
+      playground: env.GRAPHQL_PLAYGROUND && env.NODE_ENV === "development",
+      mockUpstream: env.MOCK_UPSTREAM,
+      devMode: env.DEV_MODE,
+    },
+    "Student BFF started",
+  );
+
+  // G9 优雅关闭: SIGTERM → 关闭 HTTP → Redis → gRPC → Tracer
+  process.on("SIGTERM", async () => {
+    logger.info("SIGTERM received, shutting down gracefully");
+    try {
+      await app.close();
+
+      const redis = app.get<Redis>(REDIS_CLIENT);
+      await redis.quit();
+
+      const downstream = app.get<DownstreamClient>(DOWNSTREAM_CLIENT);
+      await downstream.close();
+
+      const circuitBreaker = app.get<CircuitBreakerService>(CircuitBreakerService);
+      await circuitBreaker.shutdown();
+
+      await shutdownTracer();
+      logger.info("Graceful shutdown complete");
+    } catch (err) {
+      logger.error({ err }, "Error during graceful shutdown");
+      process.exit(1);
+    }
+  });
+}
+
+bootstrap().catch((err: unknown) => {
+  logger.error({ err }, "Failed to start Student BFF");
+  process.exit(1);
+});