GitLab의 URL

요약

GitLab은 URL이 생성되고 해석되는 방식에 영향을 미치는 여러 배포 구성을 지원합니다. 모든 배포 구성에서 URL이 올바르게 작동하도록 하려면 아래 가이드라인을 따르십시오. URL을 생성하려면 Rails 경로 및 URL 헬퍼를 사용하십시오.

개요#

GitLab은 URL이 생성되고 해석되는 방식에 영향을 미치는 여러 배포 구성을 지원합니다. 하드코딩되거나 절대적인 URL을 사용하면 다음 시나리오에서 기능이 중단될 수 있습니다:

상대 URL 설치 - 경로 접두사가 있는 GitLab 배포(예: https://example.com/gitlab/)
Geo 배포 - 다른 URL을 가진 기본 및 보조 사이트
조직 범위 라우트 - 조직 컨텍스트를 기반으로 하는 동적 URL 구조

모든 배포 구성에서 URL이 올바르게 작동하도록 하려면 아래 가이드라인을 따르십시오.

일반 가이드라인#

URL 생성을 위해 Rails를 단일 진실의 원천으로 사용하십시오. 프론트엔드에 URL이 필요한 경우 Rails에서 생성하고 프론트엔드로 전달하십시오.
내부 애플리케이션 링크에 상대 URL을 사용하십시오. 절대 URL은 다음과 같은 경우에만 사용하십시오:
- 이메일용 링크 생성.
- 외부 서비스용 URL 구성.
- 웹 인터페이스 외부에서 작동해야 하는 클론 또는 다운로드 URL 빌드.

백엔드 가이드라인#

경로 및 URL 헬퍼#

URL을 생성하려면 Rails 경로 및 URL 헬퍼를 사용하십시오.

모든 내부 애플리케이션 링크에 *_path 헬퍼를 사용하십시오.
다음과 같이 애플리케이션 외부에서 사용해야 하는 링크에만 *_url 헬퍼를 사용하십시오:
- 이메일용 링크.
- 외부 서비스용 URL.
- 웹 인터페이스 외부에서 작동해야 하는 클론 또는 다운로드 URL.

# 올바른 예 - 상대 경로
redirect_to project_path(@project)

# 잘못된 예 - 절대 URL
redirect_to project_url(@project)

프론트엔드 가이드라인#

JavaScript 및 Vue#

JavaScript 또는 Vue에서 URL을 하드코딩하거나 구성하지 마십시오. Rails에서 URL을 생성하고 데이터 속성, GraphQL 쿼리 또는 REST API를 통해 프론트엔드로 전달하십시오.

// 잘못된 예 - 프론트엔드에서 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를 실행할 수 있습니다. 다음과 같이 출력됩니다:

--[ Route 6 ]--------------------------------------------------------------------------------------------------------------
Prefix            | new_snippet
Verb              | GET
URI               | /-/snippets/new(.:format)
Controller#Action | snippets#new
Source Location   | /config/routes/snippets.rb:3

JavaScript 경로 헬퍼는 camelCase로 된 Prefix에 Path 접미사가 붙습니다. 위의 예에서는 newSnippetPath가 됩니다. Source Location은 경로 헬퍼가 위치할 파일을 나타냅니다. 위의 예에서는 app/assets/javascripts/lib/utils/path_helpers/snippets.js에 위치합니다.

app/assets/javascripts/lib/utils/path_helpers/*.js는 GitLab Development Kit을 시작할 때 생성되어야 합니다. 경로 헬퍼가 생성되지 않거나 오래된 경로 헬퍼로 인해 오류가 발생하는 경우, bundle exec rake gitlab:js:routes를 실행하여 경로 헬퍼를 수동으로 생성할 수 있습니다. 마찬가지로 yarn clean && gdk restart를 실행하여 캐시를 지우고 GDK를 재시작할 수 있습니다.

프로젝트 경로 헬퍼#

사용성을 향상하고 config/routes.rb#L368의 Rails 기능과 일치시키기 위해 프로젝트 경로 헬퍼는 약식 이름과 인수를 사용합니다. namespacePath와 projectPath를 별도로 받는 newNamespaceProjectSnippetPath 대신, 하나의 projectFullPath 인수를 받는 newProjectSnippetPath를 사용합니다. 경로 헬퍼 사용하기의 예를 참조하십시오.

경로 헬퍼 사용하기#

<script>
import { GlLink } from '@gitlab/ui';
import { newProjectSnippetPath } from '~/lib/utils/path_helpers/project';
import { newSnippetPath } from '~/lib/utils/path_helpers/snippets';

export default {
  components: {
    GlLink
  },
  props: {
    project: {
      type: Object,
      required: true,
    }
  },
  methods: {
    newSnippetPath,
    newProjectSnippetPath,
  }
};
</script>
<template>
  <div>
    <gl-link :href="newSnippetPath()">{{ __('New snippet') }}</gl-link>
    <gl-link :href="newProjectSnippetPath(project.fullPath)">{{ __('New project snippet') }}</gl-link>
  </div>

</template>

데이터 속성으로 URL 전달#

data-* 속성을 사용하여 Rails에서 프론트엔드로 URL을 전달하십시오. 예:

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

const initMyApp = () => {
  const el = document.getElementById('js-my-app');

  if (!el) return false;

  const { basePath } = el.dataset
}

GraphQL 쿼리#

webUrl 필드 사용을 피하십시오. 대신 webPath 또는 다른 상대 URL 필드(예: adminEditPath)를 사용하십시오. 해당 GraphQL 유형에 webPath 필드가 없는 경우 추가하십시오. 새 GraphQL 필드를 추가할 때 업데이트 전반의 호환성에 주의하십시오.

REST API#

web_url 필드 사용을 피하십시오. 대신 web_path 또는 다른 상대 URL 필드(예: admin_edit_path)를 사용하십시오. REST API 엔드포인트에 web_path가 없는 경우 추가하십시오. REST API 엔드포인트에 새 필드를 추가할 때 업데이트 전반의 호환성에 주의하십시오.

Vue 라우터#

Vue Router를 올바르게 구성하는 방법은 Vue Router를 참조하십시오.

HAML 템플릿#

*_url 헬퍼 대신 *_path 헬퍼를 사용하십시오:

-# 올바른 예 - 상대 URL
= link_to _('Dashboard'), dashboard_projects_path

-# 잘못된 예 - 절대 URL
= link_to _('Dashboard'), dashboard_projects_url

도움말 페이지 링크#

도움말 페이지에 링크하는 방법에 대한 지침은 /help에 링크하기를 참조하십시오.