极狐GitLab 中的 URL

概览#

极狐GitLab 支持多种部署配置，这些配置会影响 URL 的生成和解析方式。在以下场景中使用硬编码或绝对 URL 可能会破坏功能：

• 相对 URL 安装 - 带有路径前缀的极狐GitLab 部署，例如 https://example.com/gitlab/。
• Geo 部署 - 具有不同 URL 的主站点和辅助站点
• 组织范围路由 - 基于组织上下文的动态 URL 结构

为确保 URL 在所有部署配置中都能正常工作，请遵循以下指南。

通用指南#

• 使用 Rails 作为生成 URL 的唯一事实来源。如果前端需要 URL，请在 Rails 中生成并传递给前端。
• 对于内部应用链接，使用相对 URL。仅在以下情况下使用绝对 URL：
  • 生成邮件链接。
  • 构造外部服务的 URL。
  • 构建必须在 Web 界面外工作的克隆或下载 URL。

后端指南#

路径和 URL 帮助器#

使用 Rails 路径和 URL 帮助器 生成 URL。

• 所有内部应用链接使用 *_path 帮助器。
• 仅在需要在应用外部使用的链接时使用 *_url 帮助器，例如：
  • 邮件链接。
  • 外部服务的 URL。
  • 必须在 Web 界面外工作的克隆或下载 URL。

ruby
# 正确 - 相对路径
redirect_to project_path(@project)

# 错误 - 绝对 URL
redirect_to project_url(@project)

前端指南#

JavaScript 和 Vue#

不要在 JavaScript 或 Vue 中硬编码或构造 URL。在 Rails 中生成 URL，并通过数据属性、GraphQL 查询或 REST API 传递给前端。

javascript
// 错误 - 不要在前端构造 URL
const endpoint = `${gon.relative_url_root}/${projectPath}/-/refs`;

有关正确的替代方案，请参见以下部分。

JavaScript 路径帮助器#

我们使用 js-routes 来生成与 后端路径帮助器 对应的 JavaScript 路径帮助器。这些帮助器在启动 GDK 时生成，可以在 app/assets/javascripts/lib/utils/path_helpers 目录中查看。路径帮助器支持 相对 URL 安装，这在 app/assets/javascripts/behaviors/configure_path_helpers.js 中进行了全局配置。

找到正确的路径帮助器#

查找正确路径帮助器的最简单方法是在 app/assets/javascripts/lib/utils/path_helpers 目录中搜索你需要的路径的子字符串。例如，如果你需要 /<project path>/-/snippets/new，可以搜索 /-/snippets/new，直到找到接受项目路径作为参数的帮助器。

路径帮助器根据它们在 Rails 中的定义位置进行组织。例如，在 config/routes/project.rb 中定义的路由将在前端的 app/assets/javascripts/lib/utils/path_helpers/project.js 中可用。这也适用于 EE 特定的路径帮助器。例如，在 ee/config/routes/project.rb 中定义的路由将在前端的 ee/app/assets/javascripts/lib/utils/path_helpers/project.js 中可用。

对于更复杂的情况，你可以通过运行 bin/rails routes -c name_of_controller --expanded 来查找特定控制器的路由。例如，如果你想查看项目代码片段的路由，可以运行 bin/rails routes -c projects/snippets --expanded。这将输出：

plaintext
1--[ Route 6 ]--------------------------------------------------------------------------------------------------------------
2前缀            | new_snippet
3动词              | GET
4URI               | /-/snippets/new(.:format)
5控制器#动作 | snippets#new
6源位置   | /config/routes/snippets.rb:3

JavaScript 路径帮助器是 前缀 的驼峰命名并加上 Path 后缀。在上面的示例中，它是 newSnippetPath。源位置 表示路径帮助器将在哪个文件中。在上面的示例中，它将在 app/assets/javascripts/lib/utils/path_helpers/snippets.js 中。

项目路径帮助器#

为了提高可用性并匹配 Rails 功能，在 config/routes.rb#L368 中的项目路径帮助器使用简写名称和参数。与之前需要分别接受 namespacePath 和 projectPath 的 newNamespaceProjectSnippetPath 不同，现在使用 newProjectSnippetPath，它接受一个 projectFullPath 参数。参见 使用路径帮助器 中的示例。

使用路径帮助器#

vue
1<script>
2import { GlLink } from '@gitlab/ui';
3import { newProjectSnippetPath } from '~/lib/utils/path_helpers/project';
4import { newSnippetPath } from '~/lib/utils/path_helpers/snippets';
5
6export default {
7  components: {
8    GlLink
9  },
10  props: {
11    project: {
12      type: Object,
13      required: true,
14    }
15  },
16  methods: {
17    newSnippetPath,
18    newProjectSnippetPath,
19  }
20};
21</script>
22<template>
23  <div>
24    <gl-link :href="newSnippetPath()">{{ __('New snippet') }}</gl-link>
25    <gl-link :href="newProjectSnippetPath(project.fullPath)">{{ __('New project snippet') }}</gl-link>
26  </div>
27</template>

REST API 路径帮助器#

对于 REST API 路径，如 /api/:version/groups/:id，不会生成 JavaScript 路径帮助器。请使用 app/assets/javascripts/rest_api.js 中用于 REST API 路径和实用程序的可复用模式。

通过数据属性传递 URL#

通过 data-* 属性将 URL 从 Rails 传递到前端。例如：

haml
#js-my-app{ data: { base_path: project_iteration_cadences_path(project) } }

javascript
1const initMyApp = () => {
2  const el = document.getElementById('js-my-app');
3
4  if (!el) return false;
5
6  const { basePath } = el.dataset
7}

GraphQL 查询#

避免使用 webUrl 字段。相反，使用 webPath 或其他相对 URL 字段，例如 adminEditPath。如果该 GraphQL 类型上不存在 webPath 字段，请添加它。在添加新的 GraphQL 字段时，请注意 跨版本兼容性。

REST API#

避免使用 web_url 字段。相反，使用 web_path 或其他相对 URL 字段，例如 admin_edit_path。如果 web_path 在 REST API 端点上不存在，请添加它。在向 REST API 端点添加新字段时，请注意 跨版本兼容性。

Vue 路由器#

有关配置 Vue Router 的正确方法，请参见 Vue Router。

HAML 模板#

使用 *_path 帮助器而不是 *_url 帮助器：

haml
-# 正确 - 相对 URL
= link_to _('Dashboard'), dashboard_projects_path

-# 错误 - 绝对 URL
= link_to _('Dashboard'), dashboard_projects_url

链接到帮助页面#

有关如何链接到帮助页面的指南，请参见 链接到 /help。