企业官网建设流程全解析

Metabase 前端开发指南：代码结构、技术栈与工程规范的实战地图

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase

导读

本文基于仓库根目录的 frontend/CLAUDE.md 编写，它是 Metabase 前端开发工作的"总索引"：先带你摸清 1 万多个前端源码文件的组织脉络，再交代 React 18 + TypeScript + Redux Toolkit + Mantine 的技术栈选型，随后给出编码规范、单元测试模式、本地化（i18n）、代码风格（oxfmt + ESLint）、AI 辅助 Skills 加载机制与企业功能插件系统的完整约定。读完本文，你将能快速定位"改哪个文件、按什么规范写、用什么命令验证"，并理解 docs/developers-guide/frontend.md 这份详细前端指南与仓库源码之间的对应关系。

一、前端代码的总体结构

CLAUDE.md 明确指出，这是一个"高层指南"，目录结构可能随开发演进，鼓励用搜索工具发现当前结构并及时更新指南。以下目录划分是当前仓库的基线：

从源码看，frontend/src/metabase下既有actions/、collections/、dashboard/、admin/、home/、models/等业务域目录，也有common/、hooks/、hoc/、forms/、css/等横切支撑目录。值得注意的细节：

• 单元测试与被测文件同目录放置（colocated），例如frontend/src/metabase根部的LoadCurrentUser.unit.spec.tsx紧挨着LoadCurrentUser.tsx；
• API 客户端集中在frontend/src/metabase/api，其中 api.ts 通过buildCreateApi构建 RTK Query 的Api，所有端点定义都应在此且保持"纯声明"（只负责类型与 tag 失效，不掺业务逻辑）。

二、技术栈总览

CLAUDE.md 将前端技术栈总结为一张清单，逐项与仓库对应：

• 框架：React 18 + TypeScript（全量 TypeScript，新文件必须为.ts/.tsx）；
• 状态管理：Redux Toolkit；
• 样式：优先 Mantine style props，其次 CSS Modules；
• UI 组件库：metabase/ui组件，构建于 Mantine v8 之上（对应frontend/src/metabase/ui目录，内含theme.ts、component-theme.ts、Theme.module.css与stories/等）；
• 包管理器：Bun；
• 构建工具：Rspack 为主、Webpack 为遗留方案（仓库根目录并存rspack.main.config.js与rspack.embedding-sdk-bundle.config.js等多份 rspack 配置）；
• 测试：Jest + React Testing Library、Cypress。

这套组合决定了日常开发的关键路径：用 Bun 装依赖与跑脚本，用 Rspack 起构建，Jest 负责单元层，Cypress 负责 E2E 与组件测试层。

三、编码规范：TypeScript 是第一公民

CLAUDE.md 将详细规范"导入"自 docs/developers-guide/frontend.md，并强调：做任何前端改动前先读这份文档。其核心约定包括：

3.1 类型系统

• 全库 TypeScript，禁止在代码中使用any，避免类型断言；
• 通用类型集中在frontend/src/metabase-types，分两类：API Types（反映后端 API 返回的数据）与Store Types（反映 Redux store 中的数据形状）；
• 仅被局部组件使用的类型，就近放在types.ts文件中（参考frontend/src/metabase/data-grid/types.ts的 DataGrid 类型做法）。

在 .claude/skills/typescript-write/SKILL.md 中，这一原则被强化为硬性规则："新代码不得引入any，无论显式还是隐式"；遇到无法避免的断言必须写清理由注释，且不能使用遗留的// Unjustified type cast. FIXME占位。类型守卫（type guard）统一放在frontend/src/metabase-types/guards/，不允许在局部重复定义。

3.2 Redux 与数据获取

• Redux 用于全局状态，action/reducer/selector 一般与使用它们的组件放在一起（如query_builder、dashboard）；
• 尽量少用全局状态：优先使用组件局部 state 或范围受限的 context；
• 数据获取与缓存统一走RTK Query，所有 API 端点定义在frontend/src/metabase/api，需正确类型化，且不得依赖其他应用代码，也不得在端点内塞业务逻辑（仅允许在 API 内做 tag 失效）。这一点在源码中可直接验证：frontend/src/metabase/api/api.ts 通过buildCreateApi创建Api实例，构成了全部端点定义的基础设施。

3.3 UI 组件库与业务逻辑隔离

metabase/ui是基于 Mantine 二次封装的 UI 库：

• 代码中应优先使用 Mantine 组件（以及metabase/ui的封装）；
• metabase/ui目录不得泄漏业务逻辑，只能保持纯展示层；
• 所有加入 UI 库的组件必须附带 Storybook 文件演示用法（对应frontend/src/metabase/ui/stories/）。

3.4 样式优先级

样式模式的推荐顺序是：

1. Mantine Style Props——处理大多数简单样式；
2. CSS Modules——处理更复杂的样式。

Emotion styled components 与全局工具类 CSS 已废弃，新代码不得使用；遇到旧代码中的废弃样式模式，在方便时应顺手迁移（这正是 .claude/skills/emotion-migrate/SKILL.md 这个技能存在的原因）。同时建议熟悉 Mantine 的布局组件（如Center、SimpleGrid），可以省掉大量手写 CSS。

3.5 颜色规范

• 颜色只能通过Mantine color props（主要是c、bg）使用，或在 CSS Modules 中引用变量，例如color: var(--mb-color-text-primary);；
• 禁止字面颜色值（如black、#FFF），也禁止在 CSS Modules 中用color-mix调整变量透明度；
• 颜色键的完整列表在frontend/src/metabase/utils/colors/types/color-keys.ts，明暗两套取值在frontend/src/metabase/utils/colors/constants/themes；
• 该约束贯穿全库：以--mb-color-text-primary为例，可在frontend/src/metabase/admin/components/SettingsSection/SettingsSection.module.css、frontend/src/metabase/actions/containers/ActionCreator/FormCreator/FormFieldEditor/FormFieldEditor.styled.tsx等大量 CSS Modules 与 styled 文件中检索到实际用法；
• 如果设计中需要但颜色键中不存在的颜色，需向设计团队确认，不要自行引入字面值。

四、单元测试：约定与实战模板

规范强调：所有代码必须有测试，且单元测试优先于端到端测试（更快、更易调试），单元测试放在被测组件旁。由于 Metabase 前端即使简单组件也需要大量数据 mock，仓库提供了丰富的辅助设施（app context providers、数据 mock、API mock），文档还特别指出 LLM 很适合模仿既有 mock 模式来搭建测试数据。

4.1 标准 setup 模式

文档给出了可复制的组件测试模板（来自 docs/developers-guide/frontend.md）：

import React from "react"; import userEvent from "@testing-library/user-event"; import { Collection } from "metabase-types/api"; import { createMockCollection } from "metabase-types/api/mocks"; import { renderWithProviders, screen } from "__support__/ui"; import CollectionHeader from "./CollectionHeader"; interface SetupOpts { collection: Collection; } const setup = ({ collection }: SetupOpts) => { const onUpdateCollection = jest.fn(); renderWithProviders( <CollectionHeader collection={collection} onUpdateCollection={onUpdateCollection} />, ); return { onUpdateCollection }; }; describe("CollectionHeader", () => { it("should be able to update the name of the collection", () => { const collection = createMockCollection({ name: "Old name", }); const { onUpdateCollection } = setup({ collection, }); await userEvent.clear(screen.getByDisplayValue("Old name")); await userEvent.type(screen.getByPlaceholderText("Add title"), "New title"); await userEvent.tab(); expect(onUpdateCollection).toHaveBeenCalledWith({ ...collection, name: "New name", }); }); });

两个关键点：一是统一的setup函数封装渲染与返回值；二是renderWithProviders会注入应用所需的 providers（包括 Redux），保证组件在真实运行环境下测试。

4.2 请求 mock 模式

数据请求用fetch-mock配合__support__/server-mocks中的端点辅助函数：

import fetchMock from "fetch-mock"; import { setupCollectionsEndpoints } from "__support__/server-mocks"; interface SetupOpts { collections: Collection[]; } const setup = ({ collections }: SetupOpts) => { setupCollectionsEndpoints({ collections }); // renderWithProviders and other setup }; describe("Component", () => { it("renders correctly", async () => { setup(); expect(await screen.findByText("Collection")).toBeInTheDocument(); }); });

同样以setup函数组织，通过__support__/server-mocks里的辅助函数预设端点数据，组件即可按真实流程渲染并断言。

五、本地化（i18n）：ttag 的使用规范

前端本地化基于ttag，所有面向用户的字符串都必须打标签，其余交给自动化流程处理。规范提供了两种标签形式：

<div>{t`This is a user-facing string`}</div> <div> {c("{0} is a number of engineers").t`${numEngineers} engineers at metabase`} </div>

其中c(...)用于为字符串补充语境说明（context），在含插值参数时尤其有用。另一个重要原则是尽量翻译整个短语而非单词，以适配不同语言的语序。文档给出的反例与正例非常直观：

// ❌ 逐词拼接，各语言语序不同时无法翻译 const output = name + t` is going to the ` + place + t`with` + anotherName; // ✅ 整句打标签 const output = t`${name} is going to the ${place} with ${anotherName}`; // 😍 再加上语境说明 const output = c("{0} and {2} are people's names, and {1} is a place") .t`${name} is going to the ${place} with ${anotherName}`;

六、代码风格：让 lint 承担风格讨论

规范的第一条原则是：尽量不谈前端风格，凡能交给 lint 规则约束的，都用工具强制。仓库对应的工具链是oxfmt + ESLint：

• oxfmt（来自 oxc.rs 工具链）负责格式化 JS/TS 代码，由 CI 强制执行；建议编辑器开启 "format on save"；
• ESLint负责 import 顺序、空格等琐碎规则，并已集成进 Webpack 构建。

配套的脚本命令（定义于仓库根目录 package.json）包括：

6.1 组件写法

• 避免在组件内写renderThing()辅助渲染函数——绝大多数情况下，抽成独立的子组件更可读、可测、可维护：

// don't do this return ( <div> {renderThing1()} {renderThing2()} {thing3Needed && renderThing3()} </div> ); // do this return ( <div> <button onClick={toggleThing3Needed}>toggle</button> <Thing2 randomProp={foo} /> {thing3Needed && <Thing3 randomProp2={bar} />} </div> );

• 避免嵌套三元表达式：逻辑分支依赖字符串值时，优先用对象映射或switch；复杂逻辑推荐 ts-pattern 替代多层 if/else。

6.2 命名与常量

• 常量使用全大写命名：const MIN_HEIGHT = 200;；
• 避免魔法字符串与魔法数字，抽到常量文件并命名语义化：export const MAX_NUM_OPTIONS = 10;；
• 优先声明式而非命令式写法：

// don't do this let foo = []; for (let i = 0; i < list.length; i++) { if (list[i].bar === false) { continue; } foo.push(list[i]); } // do this const foo = list.filter((entry) => entry.bar !== false);

6.3 注释与逻辑表达

• 注释要克制：优先把代码写到能自解释；确实写不清楚时，注释解释"为什么"而不是"是什么"；
• 避免 if 内出现复杂逻辑表达式，先提取为命名清晰的布尔变量：

// don't do this if (typeof children === "string" && children.split(/\n/g).length > 1) { // ... } // do this const isMultilineText = typeof children === "string" && children.split(/\n/g).length > 1; if (isMultilineText) { // ... }

七、AI 辅助编码：按需加载 Skills

CLAUDE.md 引入了一套"技能（Skills）"机制：Skills 根据被修改的文件类型自动适用（哪怕是很小的附带改动），在第一次相关编辑前必须按名称显式调用对应技能；技能持有权威的详细规则，当技能与本文指南或下面备注冲突时，以技能为准。

当前生效的技能映射如下：

这些技能在仓库.claude/skills/下均有实体目录（typescript-write/、typescript-review/、e2e-test/、e2e-test-create/、emotion-migrate/、analytics-events/、metabase-ui-component-from-figma/等），并共享_shared/下的通用约定。例如 .claude/skills/typescript-write/SKILL.md 细化了类型建模、函数签名、命名、注释等硬规则，并引用 .claude/skills/_shared/typescript-commands.md 提供 Lint / Format / Type Check / 单测的精确命令。e2e-test与e2e-test-create则对应 Cypress 场景编写与调试约定（e2e/test/scenarios与e2e/test-component/scenarios是这两类测试的落点）。

八、企业版功能：必须走插件系统

CLAUDE.md 对企业功能给出了一条红线：企业版功能必须使用插件系统（plugin system），绝不允许把企业版代码暴露到 OSS 版本中。这是仓库架构的核心约束之一，解释了为什么企业功能代码全部收纳在enterprise/frontend/src/metabase-enterprise及其子目录（embedding、embedding-sdk-ee、embedding-sdk-package、custom-viz）中，与frontend/src/metabase的 OSS 代码物理隔离。在新增任何面向企业版的功能时，应先确认是否应通过插件机制注入，而不是直接写入公共源码树。

九、常用开发命令速查

CLAUDE.md 引用的共享命令文档 .claude/skills/_shared/typescript-commands.md 汇总了日常开发中最常用的一组命令，均可通过bun run执行（对应 package.json 中定义的脚本）：

Lint 与格式

• bun run lint-eslint-pure——对代码库运行 ESLint（纯检查，不写回）；
• bun run format——用 oxfmt 格式化代码；
• bun run lint-format-pure——仅检查格式是否合规；
• bun run type-check-pure——运行 TypeScript 类型检查。

测试

• bun run test-unit-keep-cljs path/to/file.unit.spec.js——运行指定单测文件；
• bun run test-unit-keep-cljs -t "pattern"——按测试名模式筛选运行；
• bun run test-cljs——运行 ClojureScript 测试（底层先bun install并shadow-cljs compile test，再执行node target/node-tests.js）。

结合 typescript-write/SKILL.md 的约定，完成任何 TS/TSX 改动后都应以bun run type-check-pure收尾验证，这是提交前的标准动作。

十、总结：一份"入口"文档如何组织你的前端开发

frontend/CLAUDE.md的价值在于它是前端工作的第一站索引：先回答"代码在哪里"（目录地图），再回答"用什么写"（技术栈与规范），继而回答"怎么保证质量"（单测模式 + lint/format/type-check 命令 + Skills 加载机制），最后回答"哪些不能碰"（企业版插件系统红线）。真正的细节规范沉淀在 docs/developers-guide/frontend.md 与.claude/skills/各技能文件中，与源码一一对应、可验证。对任何新加入 Metabase 前端开发的工程师（无论是人还是 AI Agent），按本文梳理的路径：先读结构地图定位文件，再调用对应技能遵循权威规则，最后用bun run type-check-pure+bun run lint-eslint-pure+bun run lint-format-pure验证改动，即可获得一条完整、自洽且与仓库实际实现一致的工作流。

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase