Help us learn about your current experience with the documentation. Take the survey.

前端开发指南

本文档描述了各种指南，以确保 GitLab 前端团队的一致性和质量。

简介

GitLab 基于 Ruby on Rails 构建。它使用 Haml 和基于 JavaScript 的前端，采用 Vue.js。如果您不确定何时在 Haml 页面上使用 Vue，请阅读 此说明。

更多信息请参见 Hamlit。

在 CSS 方面，我们采用基于工具类的 CSS 方法。更多信息以及查找 CSS 工具类定义的位置，请参考本指南的 SCSS 样式部分。

我们还使用 SCSS 和原生 JavaScript，通过 Babel 支持现代 ECMAScript 标准，并通过 webpack 支持 ES 模块。

在进行 API 调用时，我们优先选择 GraphQL。在某些情况下仍会使用 GitLab REST API，例如创建新的简单 Haml 页面或在代码库的遗留部分，但只要可能，我们都应该默认使用 GraphQL。

对于 Vue 中的 客户端状态管理，根据功能的具体需求，我们使用：

Vuex 已被弃用，您应该尽可能 迁移离开它。

学习：如何选择状态管理器？

对于复制字符串和翻译，我们有前端工具可用。更多信息请参见 为翻译准备页面 的 JavaScript 部分。

使用我们的前端资源需要 Node（v12.22.1 或更高版本）和 Yarn（v1.10.0 或更高版本）。您可以在我们的 安装指南 中找到如何安装这些工具的信息。

高级概述

GitLab 核心前端代码位于 app/assets/javascripts。

由于 GitLab 使用 Ruby on Rails 框架，我们使用 Haml 将 Vue 应用程序注入到视图中。例如，要在 Rails 视图中构建 Vue 应用程序，我们会设置一个类似 app/views/projects/pipeline_schedules/index.html.haml 的视图。在此视图中，我们添加一个带有 id（如 #pipeline-schedules-app）的元素。这个元素作为我们前端代码的挂载点。

应用程序结构通常遵循模式：app/assets/javascripts/<feature-name>。例如，特定功能的目录可能看起来像 app/assets/javascripts/ci/pipeline_schedules。在这些类型的目录中，我们将代码组织成 components 或 graphql 等子文件夹，这些文件夹包含构成功能的代码。典型结构可能如下所示：

  • feature_name/
    • components/（构成功能的 Vue 组件）
    • graphql/（查询/变更）
    • utils/（辅助函数）
    • router/（可选：仅适用于 Vue Router 驱动的应用程序）
    • constants.js（共享变量）
    • index.js（注入 Vue 应用程序的文件）

总是有一个顶级的 Vue 组件作为"主"组件，并导入较低级别的组件来构建功能。在所有情况下，都有一个配套文件（通常命名为 index.js 或 app.js，但经常变化），该文件在 Haml 视图上查找注入点（例如 #pipeline-schedules-app）并将 Vue 应用程序挂载到页面上。

我们通过将一个 JavaScript 文件（如 app/assets/javascripts/ci/pipeline_schedules/mount_pipeline_schedules_app.js，它设置了 Vue 应用程序）导入到相关 Haml 视图的相应页面包中来实现这一点，例如 app/assets/javascripts/pages/projects/pipeline_schedules/index/index.js。

通常，一个功能会有多个路由，如 index、show、edit 或 new。对于这些情况，我们通常根据特定路由注入不同的 Vue 应用程序。app/assets/javascripts/pages 内的文件夹结构反映了这种设置。例如，像 app/assets/javascripts/pages/<feature-name>/show 这样的子文件夹对应于 Rails 控制器 app/controllers/<controller-name> 及其操作 def show; end。或者，我们可以将 Vue 应用程序挂载到 index 路由上，并使用 Vue Router 在客户端处理路由。

愿景

作为前端工程师，我们努力为用户提供愉悦的体验。我们应该始终思考这在 GitLab 中的具体应用：优秀的 GitLab 体验意味着帮助我们的用户在发布自己的软件时，能够更快、更有信心地发布他们自己的项目。这意味着每当面临部门未来的选择时，我们应该记住优先考虑这一点。

价值观

我们定义了三个核心价值观：稳定性、速度和可维护性（SSM）

稳定性

尽管速度非常重要，但我们相信 GitLab 现在是一个企业级平台，即使是最小的 MVC 也需要稳定、经过测试且具有良好的架构。我们不应该合并可能引入降级、性能差、混乱或普遍降低用户期望的代码，即使是 MVC 代码。

这是我们希望用户对自己的软件有信心的核心价值观的延伸，为此，他们首先需要对 GitLab 有信心。这意味着我们对自己软件的信心应该达到最高水平。

速度

用户应该能够轻松浏览 GitLab 应用程序。这意味着快速加载时间、易于查找的页面、清晰的 UX 以及一种整体感觉，即他们可以无摩擦地实现目标。

此外，我们希望我们的速度能被我们的开发者感受到并得到认可。这意味着我们应该在流程、工具和文档上投入大量努力和思考，这些都能帮助我们更快地在整个部门取得成功。这不仅有利于我们作为工程师，也有利于我们的用户，因为他们最终能更快地获得高质量的功能。

可维护性

GitLab 现在是一个大型企业级软件，通常需要复杂的代码来提供最佳体验。尽管复杂性是必要的，但我们必须保持警惕，不让它过度增长。为了最小化这一点，我们希望通过封装复杂性来专注于使我们的代码库具有可维护性。这通过以下方式实现：

  • 构建解决常见问题的工具，并使其易于发现。
  • 编写更好的文档，说明我们如何解决问题。
  • 编写松散耦合的组件，可以轻松地从我们的代码库中添加或删除。
  • 移除我们认为不再可接受的旧技术或模式。

通过关注这些方面，我们旨在让工程师能够在明确定义的边界内控制复杂性，并快速与同行分享。

目标

既然我们的价值观已经确定，我们可以基于这些价值观设定目标，并确定在 GitLab 中希望实现什么。

  • 尽可能低的 FID、LCP 和跨页导航时间
  • 与 UI 交互时最小化页面重新加载
  • 每页尽可能少的 Vue 应用程序
  • 对简单页面使用 Ruby ViewComponents，并在可能时避免 Vue 的开销
  • 从 VueX 迁移，但更紧急的是停止同时使用 Apollo 和 VueX
  • 从我们的代码库中移除 jQuery
  • 添加视觉测试框架
  • 将 CSS 包大小减少到最小
  • 降低认知开销并提高我们 CSS 的可维护性
  • 提高我们的流水线速度
  • 构建一套更好的带文档的共享组件

我们在 前端目标 部分详细描述了我们对 GitLab 前端的未来展望

首次贡献者

如果您是首次贡献者，请参阅 参与 GitLab 开发。

当您准备好创建第一个合并请求，或需要了解 GitLab 前端工作流程时，请参阅 入门指南。

要获得 GitLab 前端开发的引导式介绍，您可以观看 前端入职课程，该课程提供为期六周的结构化课程。

有用链接

计划

您可以在带有 frontend-initiative 标签的史诗中找到当前具有跨职能影响的前端计划。

测试

我们如何编写 前端测试、运行 GitLab 测试套件以及调试相关测试问题。

Pajamas 设计系统

具有技术和使用指南的可重用组件可以在我们的 Pajamas 设计系统 中找到。

前端常见问题

阅读 前端常见问题 获取常见的小型有用信息。

国际化 (i18n) 和翻译

前端国际化支持在 将 GitLab 翻译成您的语言 中描述。指南的 外部化部分 解释了可用的辅助函数/方法。

故障排除

遇到前端开发问题？请查看 此故障排除指南 来帮助解决问题。

浏览器支持

支持的浏览器请参见我们的 要求。