# 后端开发指南 ## 目的使用 Next.js 14、tRPC、BullMQ 和 TypeScript 模式在 Langfuse 的后端包（web、worker、packages/shared）之间建立一致性和最佳实践。 ## 何时使用此技能工作时自动激活： * 创建或修改 tRPC 路由器和过程 * 创建或修改公共 API 端点 (REST) * 创建或修改BullMQ队列消费者和生产者 * 用业务逻辑构建服务 * 验证API请求 * 根据权限访问资源 * 实现中间件（tRPC、NextAuth、公共 API） * 使用 Prisma (PostgreSQL) 或 ClickHouse 进行数据库操作 * 通过 OpenTelemetry、DataDog、logger 和traceException 实现可观察性 * 使用 Zod v4 进行输入验证 * 来自env变量的环境配置 * 后端测试和重构 ** ** ## 快速入门 ### UI：新的 tRPC 功能清单（Web） * **Router** : 在 `features/[feature]/server/*Router.ts` 中定义 * **过程** ：使用适当的过程类型（受保护、公共） * **身份验证** ：通过中间件使用 JWT 授权。 * **权限检查** ：根据资源和角色访问资源 * **验证** ：Zod v4 输入模式 * **服务** ：服务文件中的业务逻辑 * **错误处理** ：使用traceException包装器 * **测试** ：`__tests__/`中的单元+集成测试 * **配置** : 通过 env.mjs 访问 ### SDK：新的公共 API 端点清单（Web） * **路由文件** : 在 `pages/api/public/` 中创建 * **包装器** ：使用 `withMiddlewares` \+ `createAuthedProjectAPIRoute` * **类型** ：在 `features/public-api/types/` 中定义 * **身份验证** ：通过基本身份验证进行授权 * **验证** ：查询/正文/响应的 Zod 模式 * **版本控制** ：查询/正文/响应的 API 路径和 Zod 架构中的版本控制 * **测试** : 在 `__tests__/async/` 中添加端到端测试 ### 新队列处理器清单（工作人员） * **处理器** : 在 `worker/src/queues/` 中创建 * **队列类型** : 在 `packages/shared/src/server/queues` 中创建队列类型 * **Service** : `features/` 或 `worker/src/features/` 中的业务逻辑 * **错误处理** ：区分队列处理失败的错误和导致事件成功的错误。 * **队列注册** : 添加到app.ts中的WorkerManager * **测试** : 在worker中添加vitest测试 ** ** ## 架构概述 ### 分层架构 # 网页包 (Next.js 14) ┌─ tRPC API ────────────────┐ ┌── 公共 REST API ──────────┐ │ │ │ │ │ HTTP 请求 │ │ HTTP 请求 │ │ ↓ │ │ ↓ │ │ tRPC 流程 │ │ withMiddlewares + │ │ (protectedProjectProcedure)│ │ createAuthedProjectAPIRoute │ │ ↓ │ │ ↓ │ │ 服务（业务逻辑） │ │ 服务（业务逻辑） │ │ ↓ │ │ ↓ │ │ Prisma / ClickHouse │ │ Prisma / ClickHouse │ │ │ │ │ └──────────────────────────────┘ └──────────────────────────────┘ ↓ [可选]：发布到Redis BullMQ队列 ↓ ┌─ 工人套餐（快递）────────────────────────────────┐ │ │ │ BullMQ 队列作业 │ │ ↓ │ │ 队列处理器（处理作业） │ │ ↓ │ │ 服务（业务逻辑） │ │ ↓ │ │ Prisma / ClickHouse │ │ │ └──────────────────────────────────────────────────────────────┘ **关键原则：** * **Web** ：UI 的 tRPC 程序或 SDK → 服务 → 数据库的公共 API 路由 * **Worker** ：队列处理器→服务→数据库 * **packages/shared** : Web 和 Worker 的共享代码有关完整详细信息，请参阅 [architecture-overview.md]()。 ** ** ## 目录结构 ### 网页包 (`/web/`) 网页/src/ ├── features/ # 按特征组织的代码 │ ├── [功能名称]/ │ │ ├── server/ # 后端逻辑 │ │ │ ├── *Router.ts # tRPC 路由器 │ │ │ └── service.ts # 业务逻辑 │ │ ├── 组件/ # React 组件 │ │ └── types/ # 特征类型 ├── 服务器/ │ ├── API/ │ │ ├── 路由器/ # tRPC 路由器 │ │ ├── trpc.ts # tRPC 设置和中间件 │ │ └── root.ts # 主路由器 │ ├── auth.ts # NextAuth.js 配置 │ └── db.ts # 数据库客户端 ├── 页数/ │ ├── API/ │ │ ├── public/ # 公共 REST API │ │ └── trpc/ # tRPC端点 │ └── [routes].tsx # Next.js 页面 ├── __tests__/ # 玩笑测试 │ └── async/ # 集成测试 ├── Instrumentation.ts # OpenTelemetry（首次导入） └── env.mjs # 环境配置 ### 工人包 (`/worker/`) 工人/src/ ├── 队列/ # BullMQ 处理器 │ ├── evalQueue.ts │ ├── ingestionQueue.ts │ └──workerManager.ts ├── features/ # 业务逻辑 │ └── 【特点】/ │ └── 服务.ts ├── Instrumentation.ts # OpenTelemetry（首次导入） ├── app.ts # 快速设置+队列注册 ├── env.ts # 环境配置 └──index.ts # 服务器启动 ### 共享包（`/packages/shared/`）共享/src/ ├── server/ # 服务器实用程序 │ ├── auth/ # 身份验证助手 │ ├── clickhouse/ # ClickHouse 客户端和架构 │ ├── 仪器/ # OpenTelemetry 助手 │ ├── llm/ # LLM 集成实用程序 │ ├── redis/ # Redis 队列和缓存 │ ├── repositories/ # 数据仓库 │ ├── services/ # 共享服务 │ ├── utils/ # 服务器实用程序 │ ├── 记录器.ts │ └── 队列.ts ├── crypto/ # 加密实用程序 ├── features/ # 特定于功能的代码 ├── tableDefinitions/ # 表模式 ├── utils/ # 共享实用程序 ├── 常量.ts ├── db.ts # Prisma 客户端 ├── env.ts # 环境配置 └──index.ts # 主要导出 **导入路径（package.json 导出）：** 共享包公开了不同用例的特定导入路径：导入路径|地图至 |用于 ---|---|--- `@langfuse/共享` | `dist/src/index.js` |通用类型、模式、实用程序、常量 `@langfuse/shared/src/db` | `dist/src/db.js` | Prisma 客户端和数据库类型 `@langfuse/shared/src/server` | `dist/src/server/index.js` |服务器端实用程序（队列、身份验证、服务、检测） `@langfuse/shared/src/server/auth/apiKeys` | `dist/src/server/auth/apiKeys.js` | API 密钥管理实用程序 `@langfuse/共享/加密` | `dist/src/加密/index.js` |加密和签名实用程序 **使用示例：** // 常规导入 - 类型、模式、常量、接口导入{ 云配置架构，字符串无 HTML，注释队列对象类型，类型 APIScoreV2，输入列定义，角色，来自“@langfuse/shared”； // 数据库 - Prisma 客户端和类型从“@langfuse/shared/src/db”导入{ prisma, Prisma, JobExecutionStatus }；从“@langfuse/shared”导入{类型DB作为数据库}； // 服务器实用程序 - 队列、服务、身份验证、检测导入{ 记录器，仪器异步，跟踪异常，雷迪斯，获取轨迹表，存储服务，发送会员邀请电子邮件，无效ApiKeysForProject，记录增量，记录直方图，来自“@langfuse/shared/src/server”； // API密钥管理（具体路径）从“@langfuse/shared/src/server/auth/apiKeys”导入{createAndAddApiKeysToDb}； // 加密实用程序从“@langfuse/shared/encryption”导入{加密、解密、签名、验证}； **什么去了哪里：** 共享包提供了 Web 包和工作包使用的类型、实用程序和服务器代码。它有**5个导出路径**来控制前端与后端访问：导入路径|用途 |包含什么 ---|---|--- `@langfuse/共享` | ✅ 前端+后端 | Prisma 类型、Zod 模式、常量、表定义、域模型、实用程序 `@langfuse/shared/src/db` | 🔒 仅后端 | Prisma 客户端实例 `@langfuse/shared/src/server` | 🔒 仅后端 |服务、存储库、队列、身份验证、ClickHouse、LLM 集成、检测 `@langfuse/shared/src/server/auth/apiKeys` | 🔒 仅后端 | API密钥管理（分开以避免循环依赖） `@langfuse/共享/加密` | 🔒 仅后端 |数据库字段加密/解密 **命名约定：** * tRPC 路由器： `camelCaseRouter.ts` \- `datasetRouter.ts` * 服务：功能目录中的`service.ts` * 队列处理器： `camelCaseQueue.ts` \- `evalQueue.ts` * 公共 API：`kebab-case.ts` \- `dataset-items.ts` ** ** ## 核心原则 ### 1\. tRPC 过程委托给服务 // ❌ NEVER：过程中的业务逻辑导出常量traceRouter = createTRPCRouter({ byId: protectedProjectProcedure .input(z.object({ traceId: z.string() })) .query(async ({ 输入, ctx }) => { // 这里有200行逻辑 }), }); // ✅ 始终：委托给服务导出常量traceRouter = createTRPCRouter({ byId: protectedProjectProcedure .input(z.object({ traceId: z.string() })) .query(async ({ 输入, ctx }) => { 返回等待 getTraceById(input.traceId); }), }); ### 2\.通过 env.mjs 访问配置，切勿通过 process.env // ❌从不（除了 env.mjs 本身） const dbUrl = process.env.DATABASE_URL; // ✅ 永远从“@/src/env.mjs”导入{env}； const dbUrl = env.DATABASE_URL; ### 3\.使用 Zod v4 验证所有输入从“zod/v4”导入{z}； const 架构 = z.object({ 电子邮件：z.string().email(), 项目ID: z.string(), }); const 已验证 = schema.parse(输入); ### 4\.服务直接使用 Prisma 进行简单 CRUD 或使用存储库进行复杂查询 // 服务直接使用 Prisma 进行简单的 CRUD 从“@langfuse/shared/src/db”导入{prisma}； const 数据集 = 等待 prisma.dataset.findUnique({ where: { id: datasetId, projectId }, // 始终按projectId过滤以实现租户隔离 }); // 或者使用存储库进行复杂查询（跟踪、观察、分数）从“@langfuse/shared/src/server”导入{ getTracesTable }； const 痕迹 = 等待 getTracesTable({ 项目ID, 过滤器：[...]，限制：1000， }); ### 6\.可观察性：OpenTelemetry + DataDog（后端不是 Sentry） **Langfuse 使用 OpenTelemetry 实现后端可观察性，并将跟踪和日志发送到 DataDog。** // 导入可观察性实用程序导入{ logger, // 具有 OpenTelemetry/DataDog 上下文的 Winston 记录器 traceException, // 记录 OpenTelemetry span 的异常 InstrumentAsync, // 创建检测范围来自“@langfuse/shared/src/server”； // 结构化日志记录（包括trace_id、span_id、dd.trace_id） logger.info("处理数据集", { datasetId, projectId }); logger.error("创建数据集失败", { error: err.message }); // 将异常记录到 OpenTelemetry（发送到 DataDog）尝试{ 等待操作（）； } 捕获（错误）{ 跟踪异常（错误）； // 记录到当前跨度抛出错误； } // 检测关键操作（自动检测所有 API 路由） const 结果 = 等待 InstrumentAsync( { name: "数据集.create" }, 异步（跨度）=> { span.setAttributes({ datasetId, projectId }); // 此处操作返回数据集； }, ）； **注意**：前端使用Sentry，但后端（tRPC、API 路由、服务、worker）使用 OpenTelemetry + DataDog。 ### 7\.需要全面测试为所有新功能和错误修复编写测试。有关详细示例，请参阅 [testing-guide.md]()。 **测试类型：** 类型 |框架|地点 |目的 ---|---|---|--- 整合|开玩笑| `web/src/__tests__/async/` |完整的 API 端点测试 tRPC |开玩笑| `web/src/__tests__/async/` |带身份验证的 tRPC 过程服务 |开玩笑| `web/src/__tests__/async/repositories/` |存储库/服务功能工人|维泰斯特 | `worker/src/__tests__/` |队列处理器和流 **简单示例：** // 集成测试（公共 API） const res = 等待 makeZodVerifiedAPICall( PostDatasetsV1Response, "POST", "/api/public/datasets", { name: "测试数据集" }, auth ）；期望(res.status).toBe(200); // tRPC 测试 const { 调用者 } = 等待准备(); // 创建会话+调用者 const 响应 = 等待 caller.automations.getAutomations({ projectId }); 期望（响应）.toHaveLength（1）； // 服务测试 const 结果 = 等待 getObservationsWithModelDataFromEventsTable({ 项目Id，过滤器：[...]，限制：1000，偏移量：0 }); Expect(result.length).toBeGreaterThan(0); // 工人测试（vitest） conststream=await getObservationStream({projectId,filter:[]}); 常量行= []；对于等待（流的常量块）rows.push（块）；期望（行）.toHaveLength（2）； **关键原则：** * 使用唯一ID（`randomUUID()`）以避免测试干扰 * 清理测试数据或使用唯一的项目ID * 测试必须是独立的并且可以按任何顺序运行 * 切勿在测试中使用 `pruneDatabase` ### 8\.始终按项目 ID 过滤以实现租户隔离 // ✅ 正确：按projectId 过滤以进行租户隔离 const 跟踪 = 等待 prisma.trace.findUnique({ where: { id: traceId, projectId }, // 多租户数据隔离所需 }); // ✅ 正确：ClickHouse 查询也需要 projectId const 痕迹 = 等待 queryClickhouse({ 查询：` SELECT * FROM 轨迹 WHERE 项目 ID = {项目 ID：字符串} AND 时间戳 >= {startTime: DateTime64(3)} `, 参数：{ 项目 ID，开始时间 }， }); ** ** ## 常见导入 // tRPC（网络）从“zod/v4”导入{z}；导入{ 创建TRPCR路由器，受保护的项目程序，来自“@/src/server/api/trpc”；从“@trpc/server”导入{TRPCError}； // 数据库从“@langfuse/shared/src/db”导入{prisma}；从“@prisma/client”导入类型 { Prisma }； // 点击House 导入{ 查询Clickhouse, 查询ClickhouseStream, upsertClickhouse，来自“@langfuse/shared/src/server”； // 可观测性 - OpenTelemetry + DataDog（后端不是 Sentry）导入{ logger, // 具有 OTEL/DataDog 跟踪上下文的 Winston 记录器 traceException, // 记录 OpenTelemetry span 的异常 InstrumentAsync, // 为操作创建检测范围来自“@langfuse/shared/src/server”； // 配置从“@/src/env.mjs”导入{env}； // 网页 // 或从“./env”导入{env}； // 工人 // 公共 API（网络）从“@/src/features/public-api/server/withMiddlewares”导入{ withMiddlewares }；从“@/src/features/public-api/server/createAuthedProjectAPIRoute”导入{ createAuthedProjectAPIRoute }； // 队列处理（Worker）从“bullmq”导入{作业}；从“@langfuse/shared/src/server”导入{QueueName，TQueueJobTypes}； ** ** ## 快速参考 ### HTTP 状态代码代码|使用案例 ---|--- 200 | 200成功 201 | 201已创建 400 |错误的请求 401 | 401未经授权 403 | 403禁止 404 | 404未找到 500 | 500服务器错误 ### 可供参考的示例功能参考现有的 Langfuse 功能以了解实现模式： * **数据集** (`web/src/features/datasets/`) - 包含 tRPC 路由器、公共 API 和服务的完整功能 * **提示** (`web/src/features/prompts/`) - 具有版本控制和模板的功能 * **评估** (`web/src/features/evals/`) - 与工作人员集成的复杂功能 * **公共 API** (`web/src/features/public-api/`) - 中间件和路由模式 ** ** ## 要避免的反模式 ❌ 路由/过程中的业务逻辑 ❌ 直接使用 process.env（始终使用 env.mjs/env.ts） ❌ 缺少错误处理 ❌ 无输入验证（始终使用 Zod v4） ❌ 租户范围查询上缺少 projectId 过滤器 ❌ console.log 而不是 logger/traceException (OpenTelemetry) ** ** ## 导航指南需要... |读这个 ---|--- 了解架构 | [architecture-overview.md]() 创建路由/控制器 | [routing-and-controllers.md]() 组织业务逻辑 | [services-and-repositories.md]() 创建中间件 | [middleware-guide.md]() 数据库访问| [database-patterns.md]() 管理配置| [configuration.md]() 编写测试 | [testing-guide.md]() ** ** ## 资源文件 ### [architecture-overview.md]() 三层架构（tRPC/Public API → 服务 → 数据访问）、tRPC/Public API/Worker 的请求生命周期、Next.js 14 目录结构、双数据库系统（PostgreSQL + ClickHouse）、关注点分离、复杂查询的存储库模式 ### [routing-and-controllers.md]() Next.js 基于文件的路由、tRPC 路由器模式、公共 REST API 路由、分层架构（入口点 → 服务 → 存储库 → 数据库）、服务层组织、要避免的反模式 ### [services-and-repositories.md]() 服务层概述、依赖注入模式、单例模式、数据访问的存储库模式、服务设计原则、缓存策略、测试服务 ### [middleware-guide.md]() tRPC 中间件（withErrorHandling、withOtelInstrumentation、enforceUserIsAuthed）、七种 tRPC 过程类型（publicProcedure、authentiatedProcedure、protectedProjectProcedure 等）、公共 API 中间件（withMiddlewares、createAuthedProjectAPIRoute）、身份验证模式（tRPC 的 NextAuth、公共 API 的基本身份验证） ### [database-patterns.md]() 双数据库架构（通过 Prisma 的 PostgreSQL + 通过直接客户端的 ClickHouse）、PostgreSQL CRUD 操作、ClickHouse 查询模式（queryClickhouse、queryClickhouseStream、upsertClickhouse）、复杂查询的存储库模式、通过 projectId 过滤进行租户隔离、何时使用哪个数据库 ### [configuration.md]() 使用 Zod 进行环境变量验证、特定于包的配置（带有 t3-oss/env-nextjs 的 web/env.mjs、worker/env.ts、shared/env.ts）、NEXT_PUBLIC_LANGFUSE_CLOUD_REGION 使用、用于企业功能的 LANGFUSE_EE_LICENSE_KEY、环境管理的最佳实践 ### [testing-guide.md]() 集成测试（带有 makeZodVerifiedAPICall 的公共 API）、tRPC 测试（createInnerTRPCContext、appRouter.createCaller）、服务级别测试（存储库/服务函数）、工作测试（带流的 vitest）、测试隔离原则、运行测试（Jest for web、vitest forworker） ** ** ## 相关技能 * **数据库验证** \- 验证列名和架构一致性 * **技能开发人员** \- 用于创建和管理技能的元技能 ** ** **技能状态**：完成 ✅ **行数**：~540 行 **渐进式披露**：7 个资源文件 ✅

后端开发指南

包含技能