企业官网建设流程全解析

• 可观测性
• 后端

本篇技术指南聚焦 highlight.io 开源全栈可观测平台（error monitoring、session replay、logging、distributed tracing）前端（app.highlight.io）中 Apollo Client GraphQL 定义的组织方式与维护流程。你将掌握：查询与变更定义分别存放在哪里、修改后如何触发 graphql-codegen 自动重新生成前端 Hooks 与 TypeScript 类型、watch 模式如何在开发时实时同步，以及最终生成产物（schemas / operations / hooks）在 React 组件中的实际用法。

一、核心问题：前端 GraphQL 定义放在哪里

在前端（frontend/目录，即 app.highlight.io 所运行的 React + Vite + Apollo Client 应用）中，Apollo Client 的 GraphQL 操作定义集中托管在 frontend/src/graph/operators 目录下，并按“查询”与“变更”两种操作类型拆分为两个文件：

• 查询（Query）定义：frontend/src/graph/operators/query.gql
• 变更（Mutation）定义：frontend/src/graph/operators/mutation.gql

这两个.gql文件是整个前端数据访问层的事实来源（source of truth）。它们同时承担两类职责：

1. 作为 Apollo Client 运行时实际发送的 GraphQL 文档；
2. 作为 graphql-codegen 的输入文档（documents），驱动前端 Hooks 与其他 TypeScript 定义的生成。

以query.gql为例，文件中既包含可复用的 Fragment，也包含实际查询。文件开头定义的SessionPayloadFragment展示了典型 Fragment 写法：从SessionPayload类型中选取events、errors（含结构化堆栈structured_stack_trace、request_id等字段）、rage_clicks、session_comments（含作者与附件信息）以及last_user_interaction_time，见 frontend/src/graph/operators/query.gql。

mutation.gql则定义了平台中几乎所有的写操作，例如将错误组标记为已读、将 Session 标记为已读、静默评论线程、更新计费计划、切换错误组状态等，见 frontend/src/graph/operators/mutation.gql。其写法遵循标准 GraphQL mutation 语法，例如：

mutation MarkErrorGroupAsViewed($error_secure_id: String!, $viewed: Boolean!) { markErrorGroupAsViewed(error_secure_id: $error_secure_id, viewed: $viewed) { secure_id viewed } }

二、修改定义后会发生什么：自动重新生成

这是本流程中最关键的行为约定：修改这两个文件，就会重新生成前端 Hooks 和其他 TypeScript 定义。

具体机制是：当本地前端开发服务器运行时，graphql-codegen 会以 watch 模式监听这两个.gql文件，一旦发生变更便重新生成代码。从 frontend/package.json 中的 scripts 可以看到：

"codegen": "graphql-codegen --config codegen.yml", "dev:gql": "graphql-codegen --config --watch codegen.yml", "dev": "run-p --print-label --race 'dev:**'"

其中dev通过run-p（npm-run-all）并行启动包括dev:gql在内的多个开发进程，dev:gql即携带--watch参数的 codegen 进程。因此，只要按开发文档启动了前端，这个监听进程就会一直运行——你保存.gql文件的瞬间，生成的 Hooks 与类型便已更新，无需手动执行任何命令。

前端完整的本地运行方式参见 开发部署指南。

三、codegen 配置逐项解析

代码生成行为由 frontend/codegen.yml 统一控制。该配置的三个关键部分决定了生成的输入、输出与形态：

1. Schema 来源：schema: '../backend/private-graph/graph/schema.graphqls'，即类型定义直接取自后端私有 GraphQL 服务的 schema 文件，保证前端生成类型与后端契约严格一致。
2. 输入文档：documents: 'src/**/**.gql'，即扫描frontend/src下所有.gql文件（涵盖operators目录中的两个定义文件以及页面内可能存在的内联.gql文件）。
3. 三份输出产物，均由overwrite: true强制覆盖：
   • src/graph/generated/schemas.tsx：基于 schema 与文档生成的基础 TypeScript 类型。其中通过scalars配置把后端自定义标量映射为前端友好的类型：Any: any、Timestamp: string、Int64: number、StringArray: string[]，保证Timestamp这类字段在 TypeScript 中被当作字符串处理。
   • src/graph/generated/operations.tsx：基于文档生成的操作级类型（使用typescript-operations插件），并通过named-operations-object（useConsts: true）为每个操作生成命名常量。
   • src/graph/generated/hooks.tsx：使用typescript-react-apollo插件生成 React Hooks，配置withHOC: false、withComponent: false、withHooks: true，即只生成 Hooks 形态的封装，不生成 HOC 与 render-prop 组件。

此外，配置还通过hooks.afterAllFileWrite钩子对生成文件统一执行prettier --write，保证生成代码风格与手写代码一致。

四、生成产物与真实使用方式

每次保存.gql文件后，frontend/src/graph/generated 目录下的三个文件会被重新生成：

• schemas.tsx：GraphQL 类型的 TypeScript 映射；
• operations.tsx：每个 query/mutation 的参数与返回类型；
• hooks.tsx：可直接在组件中使用的 React Hooks。

以 frontend/src/graph/generated/hooks.tsx 中的useMarkErrorGroupAsViewedMutation为例，生成代码为每个 mutation 提供了完整注释、useMarkErrorGroupAsViewedMutation导出以及底层Apollo.useMutation调用，并带有DocumentNode常量（如MarkErrorGroupAsViewedDocument）。

实际页面中通过相对路径引用生成产物，例如 frontend/src/pages/Internal/InternalPage.tsx 中的导入：

import { ... } from '../../graph/generated/hooks'

也就是说，日常业务开发流程是：先写.gql定义 → codegen 自动生成 Hooks → 在组件中导入并使用，全程不需要手写任何类型或请求封装。

五、新增或修改操作的标准操作步骤

在 highlight.io 前端新增一个 GraphQL 操作，按以下步骤即可：

1. 确认操作类型：读取数据写入frontend/src/graph/operators/query.gql；写入数据（创建、更新、删除、标记状态等）写入frontend/src/graph/operators/mutation.gql。
2. 编写操作：使用与后端schema.graphqls一致的字段名与参数类型。建议充分利用 Fragment 复用公共字段子集，减少重复。
3. 保存文件：若开发服务器已运行，dev:gql的 watch 进程会立即重新生成schemas.tsx、operations.tsx、hooks.tsx；若未运行，可手动执行yarn codegen（参见 frontend/package.json）。
4. 校验生成结果：确认frontend/src/graph/generated/hooks.tsx中出现了对应的useXxxQuery/useXxxMutation，且参数类型正确（注意Timestamp映射为string、Int64映射为number）。
5. 在组件中使用：从../../graph/generated/hooks导入生成的 Hook 并传入变量。

六、常见注意事项

• 不要手改生成目录：frontend/src/graph/generated下三个文件是纯生成产物，任何手写修改都会在下次 codegen 时被overwrite: true覆盖，务必只修改operators中的源定义。
• 字段必须与后端 schema 对齐：由于codegen.yml直接以backend/private-graph/graph/schema.graphqls为 schema，前端引用的字段若与后端不一致，codegen 会直接报错，这实际上起到“契约校验”的作用。
• Scalar 映射决定类型体验：Any、Timestamp、Int64、StringArray四个标量的映射是提升类型体验的关键，新增自定义标量时需同步在codegen.yml的scalars中补充映射。
• mutation 的命名约定：定义中的操作名（如MarkErrorGroupAsViewed）会直接决定生成 Hooks 的名称，命名时使用 PascalCase 动词短语，便于检索。

综上，highlight.io 前端将“GraphQL 定义 → 类型/请求层”的生成链路收敛为两个.gql源文件与一个codegen.yml配置，配合 watch 模式实现了修改即生效的开发体验；理解并善用这条链路，是参与 app.highlight.io 前端开发时最基础也最高效的一环。

• 可观测性
• 后端