开源数据发现平台：Amundsen Frontend Service 安装 & 开发者指南

Amundsen 是一个数据发现和元数据引擎，旨在提高数据分析师、数据科学家和工程师与数据交互时的生产力。目前，它通过索引数据资源（表格、仪表板、数据流等）并基于使用模式（例如，查询频率高的表格会优先于查询频率低的表格）提供页面排名式的搜索功能来实现这一目标。您可以将其视为数据版的 Google 搜索。该项目以挪威探险家罗尔德·阿蒙森 (Roald Amundsen) 的名字命名，他是第一个发现南极的人。

安装

直接从源码安装独立应用

以下说明用于搭建 Amundsen 应用的独立版本，该方法最适合本地开发。

bash 复制代码

# 克隆仓库
$ git clone https://github.com/amundsen-io/amundsen.git

# 构建静态内容
$ cd amundsen/frontend/amundsen_application/static
$ npm install
$ npm run build # 或使用 npm run dev-build 以获取未压缩的源码
$ cd ../../

# 安装 Python 依赖
$ python3 -m venv venv
$ source venv/bin/activate
$ pip3 install -e ".[all]" .

# 启动服务器
$ python3 amundsen_application/wsgi.py
# 访问 http://localhost:5000 以确认应用正在运行

此时，应用应已在 http://localhost:5000 运行，但你会发现没有数据，且交互会报错。下一步是将独立应用连接到搜索和元数据服务。

使用此处的说明搭建元数据服务的本地副本。
使用此处的说明搭建搜索服务的本地副本。
修改 LocalConfig 中的 LOCAL_HOST、METADATA_PORT 和 SEARCH_PORT 变量，使其指向本地元数据和搜索服务的运行地址，然后使用以下命令重启应用：

bash 复制代码

python3 amundsen_application/wsgi.py

开发者指南

环境

按照从源码直接安装独立应用一节中的安装说明操作。

安装 JavaScript 开发依赖：

bash 复制代码

# 在 ~/<你的克隆仓库路径>/amundsenfrontendlibrary/amundsen_application
$ cd static
$ npm install --only=dev

测试对 JavaScript 静态文件的本地修改：

bash 复制代码

# 在 ~/<你的克隆仓库路径>/amundsenfrontendlibrary/amundsen_application
$ cd static
$ npm run dev-build # 构建开发包

测试对 Python 文件的本地修改，请重新运行 wsgi：

bash 复制代码

# 在 ~/<你的克隆仓库路径>/amundsenfrontendlibrary/amundsen_application
$ python3 wsgi.py

贡献

我们在 Amundsen 主仓库中描述了通用贡献流程，因此这里将涵盖与 Frontend 库相关的项目。阅读我们的 Frontend 策略文档，了解你可以在哪些方面提供帮助。

测试 Python 代码

如果对任何 Python 文件进行了修改，请运行 Python 单元测试、linter 和类型检查器。单元测试使用 py.test 运行，位于 tests/unit。类型检查使用 mypy 运行。Lint 使用 flake8。我们为这些测试分别提供了友好的 make 目标：

bash 复制代码

# 完成环境设置后
make test  # 在 Python 3 中运行单元测试
make lint  # flake8
make mypy  # 类型检查

在提交 PR 之前，请修复所有错误。

测试前端代码

npm run test 会运行我们的前端单元测试。请添加单元测试以覆盖新增代码，并在提交 PR 前修复任何测试失败。你也可以在开发过程中开一个专用终端运行 npm run test:watch，它会持续对修改过的文件运行测试。

要运行特定测试，请执行 npm run test-nocov -t <regex>，其中 <regex> 是任何匹配你想要运行测试块名称的模式。请参见我们的编写单元测试的建议。

开发 React 组件

为了在隔离环境中预览 React 组件，请使用 Storybook。只需在与组件相同的文件夹中添加 <componentName>.story.tsx 文件。在该文件中，展示组件的不同状态。然后运行 npm run storybook，它会在浏览器中打开 storybook 浏览页面。

使用 Storybook 可以大大简化组件的快速迭代，因为某些状态需要多步 UI 操作才能到达。该图库也是一个方便查看可用可复用组件的地方，避免重复造轮子。

前端类型检查

我们在代码库中使用 TypeScript，因此 npm run tsc 会进行类型检查，不过你的 IDE 应该会在代码中直接指出问题。构建命令 npm run build 和 npm run dev-build 也会执行类型检查，但由于它们还会构建源代码，因此速度较慢。运行其中任意命令并在提交 PR 前修复所有失败的检查。

前端 Lint 和格式化

我们有两个 linter ------ ESLint 用于 JavaScript 和 TypeScript 文件，Stylelint 用于 Sass 文件。如果你的 IDE 安装了 ESLint 和 Stylelint 扩展，默认情况下你应该会在编辑器中看到警告。

我们还使用 Prettier 来帮助我们在 TypeScript 和 Sass 代码上保持一致的格式。

每当你想手动运行这些任务时，可以执行：

npm run lint 运行 ESLint，npm run lint:fix 自动修复大部分问题。
npm run stylelint 运行 Stylelint，npm run stylelint:fix 触发自动修复。
npm run format 在 TypeScript 和 Sass 文件上运行 Prettier

我们还会在创建新提交时检查已修改的文件并为其格式化，使你与项目都能轻松保持一致的代码风格。我们利用 Husky 和 Lint-staged 来实现这一点。

可访问性与语义化标记

我们致力于保持应用的可访问性。为此，我们使用 ESLint 的 'airbnb-typescript' 预设，其中包含大量可访问性规则。我们还拥有一组以 "jsx-a11y/" 为前缀的规则，目前处于 "warn" 级别，因此不会报错。我们的目标是移除该 "warn" 级别，并遵守我们列在我们的 ESLint 配置中的所有可访问性规则。

我们还尝试根据语义化标记的最佳实践来建模应用的标记。如果你在某次 PR 中对标记进行了较大改动，请确保你的更改符合此 HTML 语义检查清单。

版式

过去，我们使用多个类来设置标题和正文的样式。如今，我们建议在每个组件的样式表中使用类，并通过使用 @extend 到占位符选择器来扩展这些类，应用适当的文本样式：

scss 复制代码

@import "variables";
@import "typography";

.header-title-text {
  @extend %text-headline-w2;
}

.header-subtitle-text {
  @extend %text-subtitle-w3;
}

你可以在此文件中找到文本占位符选择器的完整列表，并在运行 npm run storybook 时在 storybook 中查看其实现。

图标

直到最近，我们都没有使用特定的图标库，而是使用临时生成的 SVG 来渲染图标。初始加载策略基于使用遮罩的 image 标签，但许多浏览器不支持。

我们转而创建了位于 /components/SVGIcons 文件夹中的自定义图标。然而，鉴于我们需要请求特定设计资源才能获得新图标，我们将采用现成的图标库 BoxIcons 来创建 SVGIcons 文件夹中的图标。要创建它们，我们将在此站点搜索特定 BoxIcon，复制代码并按照当前图标中的模式进行调整。我们还需要在 SVGIcons/index.ts 文件中导出新的图标。

然后，我们将这样使用它们：

tsx 复制代码

import { AlertIcon } from 'components/SVGIcons';

...
  <AlertIcon />

风险提示与免责声明

本文内容基于公开信息研究整理，不构成任何形式的投资建议。历史表现不应作为未来收益保证，市场存在不可预见的波动风险。投资者需结合自身财务状况及风险承受能力独立决策，并自行承担交易结果。作者及发布方不对任何依据本文操作导致的损失承担法律责任。市场有风险，投资须谨慎。