앱 초기화 개발 가이드라인(리포지터리 및 Blob 페이지)
GitLab v19.6요약
리포지터리(트리) 페이지와 Blob 페이지는 동일한 공유 Vue 앱을 마운트하지만, 사용자가 페이지에 도달하는 방식에 따라 서로 다른 진입점이 앱을 부트스트랩합니다. 이 페이지에서 ~/는 app/assets/javascripts의 별칭이며, "트리"와 "리포지터리"라는 단어는 같은 의미로 사용합니다.
리포지터리(트리) 페이지와 Blob 페이지는 동일한 공유 Vue 앱을 마운트하지만, 사용자가 페이지에 도달하는 방식에 따라 서로 다른 진입점이 앱을 부트스트랩합니다. 다음 절에서는 각 흐름에서 어떤 앱이 마운트되는지, 그리고 각 진입점이 무엇을 초기화해야 하는지 설명합니다.
이 페이지에서 ~/는 app/assets/javascripts의 별칭이며, "트리"와
"리포지터리"라는 단어는 같은 의미로 사용합니다.
요약#
트리 페이지 번들은 사용자가 리포지터리 페이지에서 Blob으로 이동할 때 앱을 초기화합니다. Blob 페이지 번들은 사용자가 Blob URL을 직접 불러올 때(예: 페이지를 새로 고칠 때) 앱을 초기화합니다. 첫 번째 흐름은 콘텐츠 영역만 교체하므로 더 빠릅니다.
두 흐름 모두 동일한 공유 부트스트랩인
initRepositoryPage()를 호출하므로, 같은 Vue Router를 만들고 같은 공유 리포지터리 앱
(~/repository/components/legacy_app.vue)을 마운트하며, 트리와 Blob 사이의
이동은 양방향 모두 클라이언트 측에서 이루어집니다. 두 흐름의 차이는
어떤 페이지 번들이 부트스트랩을 호출하는지, 그리고 어떤 HAML이 마운트 지점을 제공하는지입니다.
따라서 각 진입점은 다음 모든 흐름에 맞는 올바른 데이터로 앱을 초기화해야 합니다.
- 트리 페이지에서 Blob으로의 클라이언트 측 이동.
- Blob 페이지 직접 접근.
- 프로젝트 개요 페이지에서 Blob으로의 클라이언트 측 이동.
라우터#
~/repository/router.js에서 라우트 경로가 렌더링할 Vue 컴포넌트를 결정합니다.
TreePage:~/repository/pages/tree.vueBlobPage:~/repository/pages/blob.vueIndexPage:~/repository/pages/index.vue
트리와 Blob 라우트는 각각 여러 번(*PathDecoded,
*PathEncoded, *PathEncodedSlashes, 일반 형태) 등록되므로, 특수 문자(#, % 등)가 들어 있는 ref도
백엔드가 어떻게 인코딩했든 올바르게 해석됩니다.
공유 부트스트랩#
initRepositoryPage()(~/repository/init_repository_page.js)는 두 페이지가 공유하는
모든 요소를 연결합니다. 순서는 다음과 같습니다.
- 주 마운트 지점을 선택합니다.
#js-tree-list(트리 페이지) 또는#js-view-blob-app(Blob 페이지)이며, 둘 다 없으면null을 반환합니다. createRouter(projectPath, escapedRef, fullName). 라우터 기준 경로는 미리 인코딩된 ref를 사용해야 합니다. 라우트 패턴에 인코딩된 변형이 포함되어 있어서,#이나%가 들어 있는 원본 ref를 쓰면 이중 인코딩됩니다.projectPath,projectShortPath,ref쿼리에 대한 Apollo 캐시 쓰기. 앱이 캐시에서 이 값을 읽으므로, 어떤 앱이든 마운트되기 전에 이 작업이 이루어집니다. Blob 페이지에서는 작업 항목 630950의 통합 헬퍼가 반영될 때까지 헤더 마운트 지점의 dataset에서 짧은 경로를 가져옵니다.initFileTreeBrowser(#js-file-browser):~/repository/file_tree_browser/.initHeaderApp(#js-repository-blob-header-app):~/repository/init_header_app.js. 헤더 영역 앱은 브레드크럼과 Web IDE 버튼도 렌더링합니다.initLastCommitApp(#js-last-commit):~/repository/init_last_commit_app.js.initForkInfoApp(#js-fork-info):~/repository/init_fork_info_app.js.- 첫 번째 단계에서 선택한 마운트 지점의 주 리포지터리 앱(
~/repository/components/legacy_app.vue).
이 함수는 { router, data, apolloProvider, projectPath }를 반환하므로, EE 래퍼가
중복 인스턴스를 만들지 않고 같은 라우터와 Apollo 프로바이더에 코드 소유자 앱을 마운트할 수 있습니다.
단일 리포지터리 앱#
repository_single_vue_app 기능 플래그는 트리 페이지와 Blob 페이지의 개별 마운트 지점을
app/views/projects/_repository_app.html.haml이 렌더링하는 마운트 지점 하나인 #js-repository-app으로 대체합니다.
페이지 데이터는 TreeHelper#vue_repository_app_data에서 가져옵니다.
에픽 23817은 모든 리포지터리 앱을
이 루트로 통합하는 작업을 추적합니다.
#js-repository-app이 있으면 initRepositoryPage()는
initRepositoryApp()(~/repository/init_repository_app.js)에 처리를 위임하고 기존 방식의
마운트 지점은 건너뜁니다. initRepositoryApp()은 다음을 수행합니다.
parseRepositoryAppDataset()(~/repository/utils/parse_repository_app_dataset.js)으로 dataset을 한 번에 파싱합니다. JSON 값은 예외를 던지지 않고 빈 값으로 대체됩니다. 잘못된 값 하나가 페이지 전체의 마운트를 중단시킬 수 있기 때문입니다.- 기존 방식과 마찬가지로 라우터를 만들고 Apollo 캐시를 시딩합니다.
- 헤더 영역과 리포지터리 앱을 모두 포함하는 단일
provide로~/repository/components/app.vue를 마운트합니다. - 기존 방식과 같은
{ router, data, apolloProvider, projectPath }형태를 반환합니다.
app.vue는 Vue 2에서 요구하는 대로 래퍼 요소 하나를 렌더링합니다. 이 래퍼에는
파일 트리 브라우저, 헤더 영역, 포크 정보, 마지막 커밋, <router-view>가
들어 있습니다.
Blob 라우트에서 app.vue는 ~/repository/components/blob_auxiliary_viewer.vue도
마지막 커밋 컨테이너 안에 렌더링합니다. 이 위치는 _blob.html.haml이 서버에서 렌더링한
보조 뷰어를 두는 곳입니다. 단일 리포지터리 앱 레이아웃은 해당 파셜과
#js-blob-auxiliary-viewer 마운트 지점을 렌더링하지 않습니다. 이 컴포넌트는 경로를 키로 사용하므로
클라이언트 측 이동이 일어날 때마다 알림을 다시 불러옵니다.
두 페이지 번들도 #js-repository-app을 확인합니다.
~/pages/projects/show/index.js는#js-tree-list또는#js-repository-app이 있으면 리포지터리 번들을 불러옵니다.initBlobShow는#js-repository-app이 있으면BlobViewer로 대체하지 않고 공유 부트스트랩과initBlob을 호출합니다.
파일 트리 브라우저#
트리 페이지 로드와 Blob 페이지 직접 로드 모두 initFileTreeBrowser
(~/repository/file_tree_browser/index.js)로 파일 트리 브라우저를 마운트합니다.
- 두 HAML 진입점 모두 레이아웃 이동을 막기 위해 너비 320픽셀을 미리 확보한 상태로
마운트 지점
#js-file-browser를 렌더링합니다. 이 너비는file_tree_browser.vue의TREE_WIDTH와 일치해야 합니다. - 파일 트리 브라우저는 리포지터리 앱과 라우터 인스턴스를 공유하므로, 브라우저에서 파일을 선택하면 클라이언트 측 이동이 일어납니다. 트리에서 Blob으로, Blob에서 Blob으로의 이동은 전체 페이지 로드 없이 이루어집니다.
- 파일 트리 브라우저는 트리와 Blob 라우트에서 렌더링되지만,
프로젝트 루트 라우트(
projectRoot)에서는 스스로 숨깁니다. - Pinia 스토어가 펼침, 미리 보기, 표시 상태를 유지하므로 라우트가 바뀌어도 상태가 유지됩니다.
트리 페이지 로드#
HAML 파셜:
app/views/projects/tree/show.html.haml은app/views/projects/_files.html.haml을 렌더링하고, 이 파일이 다시app/views/projects/_tree_content.html.haml을 렌더링합니다. 이들이#js-tree-list,#js-last-commit및 나머지 마운트 지점을 제공합니다.
초기화:
~/pages/projects/tree/show/index.js는ee_else_ce/repository를 가져와initTree(),initAmbiguousRefModal()(#js-ambiguous-ref-modal),addShortcutsExtension(ShortcutsNavigation)을 호출합니다.- CE:
~/repository/index.js(setupVueRepositoryList)가SimpleViewer와BlobContent성능 플러그인 컴포넌트를 등록하고, 이 페이지의 모든 요소를 마운트하는 공유 부트스트랩에 처리를 위임합니다. - EE:
ee/app/assets/javascripts/repository/index.js가 CE 초기화를 감싸고,setupVueRepositoryList가 반환하는 라우터와 Apollo 프로바이더로 코드 소유자 앱(#js-code-owners)도 추가로 마운트합니다.
- CE:
페이지의 Vue 앱:
~/repository/components/header_area.vue~/repository/components/last_commit.vue~/repository/components/legacy_app.vue:~/repository/pages/tree.vue와~/repository/components/tree_content.vue를 렌더링합니다.~/repository/file_tree_browser/file_tree_browser.vue~/repository/components/fork_info.vue~/vue_shared/components/ref/components/ambiguous_ref_modal.vueee/app/assets/javascripts/vue_shared/components/code_owners/code_owners.vue(EE 전용)
트리에서 Blob으로 이동(클라이언트 측)#
사용자가 트리 페이지에서 Blob으로 이동할 때는 어떤 앱도 다시 초기화되지 않습니다.
라우터가 이미 마운트된 리포지터리 앱 안에서 TreePage를 BlobPage로 교체하고
(app.vue가 <router-view>를 렌더링), 나머지 앱(헤더 영역, 마지막 커밋,
파일 트리 브라우저)은 라우트 변경에 스스로 반응합니다.
빠른 경로는 콘텐츠 영역만 교체하고 나머지는 모두 마운트된 상태로 유지합니다.
그 결과, 클라이언트 측 이동으로 도달한 Blob은 show_blob_bundle.js를 실행하지 않으므로,
해당 번들에서만 설정되는 항목(예: initAuxiliaryViewer와 기존 방식의 initBlob 동작)은
이 흐름에서 초기화되지 않습니다. 이에 해당하는
기능은 공유 Vue 앱 안에 있거나(예: last_commit.vue는 GraphQL로 파이프라인 상태를 직접
가져옴) 두 진입점에서 모두 마운트되어야 합니다(예: 코드 소유자).
Blob 페이지 직접 접근#
Blob 페이지 직접 접근은 사용자가 Blob URL을 불러오거나 새로 고칠 때 발생합니다.
HAML 파셜:
app/views/projects/blob/show.html.haml은#js-view-blob-app을 제공하는app/views/projects/blob/_blob.html.haml을 렌더링합니다.
초기화:
~/pages/projects/blob/show/index.js는 얇은 shim입니다. 로직은~/blob/show/show_blob_bundle.js(initBlobShow)에 있습니다.- EE 페이지 진입점은
initEEBlobShow(ee/app/assets/javascripts/blob/show/blob_show_bundle.js)를 호출하고, 이 함수가initBlobShow를 호출한 뒤 코드 소유자 앱(#js-code-owners)도 추가로 마운트합니다. initBlobShow는 항상initPerformancePlugin,initAmbiguousRefModal(#js-ambiguous-ref-modal),showAlertFromLocalStorage를 실행합니다.#js-view-blob-app이 있는 경우: 공유 부트스트랩이BlobPage를 렌더링하는 리포지터리 앱을 포함해 모든 요소를 마운트하고, 이어서initAuxiliaryViewer와initBlob(기존 방식의 Blob 동작: 줄 링크, blame 단축키 등)이 실행됩니다.#js-view-blob-app이 없는 경우의 대체 동작은 확장 Blob 보기(?expanded=true)에서 발생하며,new BlobViewer(),initBlob(),initForkInfoApp(#js-fork-info)을 실행합니다. 동적~/code_navigation가져오기도 이 대체 동작에서만, 그리고#js-code-navigation이 있을 때만 실행됩니다.- 두 경우 모두 번들은
initWebIdeLink(#js-blob-web-ide-link)를 호출하지만, 이 함수의 마운트 지점은 Blob 헤더 HAML(app/views/projects/blob/_header.html.haml)에서 오며,_blob.html.haml은 이 헤더를 확장 보기에서만 렌더링합니다. Vue Blob 페이지에서는 헤더 영역 앱이 Web IDE 버튼을 렌더링하므로 이 호출은 일찍 반환됩니다. - 리치 뷰어의 목차는 Vue Blob 페이지 안에서
blob_header.vue가 렌더링하므로 별도의 마운트 지점이 없습니다.
페이지의 Vue 앱:
~/repository/components/header_area.vue~/repository/components/last_commit.vue~/repository/components/legacy_app.vue:~/repository/pages/blob.vue와~/repository/components/blob_content_viewer.vue를 렌더링합니다.~/repository/file_tree_browser/file_tree_browser.vue~/repository/components/fork_info.vue~/vue_shared/components/ref/components/ambiguous_ref_modal.vueee/app/assets/javascripts/vue_shared/components/code_owners/code_owners.vue(EE 전용)
Blob에서 트리로 이동(클라이언트 측)#
Blob에서 트리로의 이동도 클라이언트 측에서 이루어집니다. 라우터가 이미 마운트된
리포지터리 앱 안에서 BlobPage를 TreePage로 교체합니다. 페이지를 해체하는 요소가 없으므로,
Blob 직접 로드 시 show_blob_bundle.js에서만 설정된 항목
(initAuxiliaryViewer와 기존 방식의 initBlob 동작)은 사용자가 Blob 라우트를 벗어난 뒤에도
그대로 유지됩니다.
프로젝트 개요 페이지#
프로젝트 개요 페이지는 사용자의 프로젝트 개요 설정(Preferences > Behavior > Project overview content)과
리포지터리가 비어 있는지 여부에 따라 서로 다른 HAML 파셜을 사용합니다.
~/pages/projects/show/index.js는 동적 가져오기로 조건에 따라
앱을 초기화합니다.
#js-tree-list가 있는 경우:ee_else_ce/repository를 동적으로 가져오며, 위에서 설명한 트리 초기화와 같습니다..blob-viewer가 있는 경우(README):~/blob/viewer를 동적으로 가져오고 (new BlobViewer())initHeaderApp({ isReadmeView: true })를 호출합니다..project-show-activity가 있는 경우:~/activities를 동적으로 가져옵니다.
개요 콘텐츠와 관계없이 initWebIdeLink(#js-tree-web-ide-link)는
항상 실행됩니다.
관련 파셜:
app/views/projects/_readme.html.hamlapp/views/projects/_activity.html.haml
빈 리포지터리의 경우 initCodeDropdown
(#js-project-show-empty-page #js-code-dropdown)도 ~/pages/projects/show/index.js에 있으며
ee_else_ce/repository/components/code_dropdown/compact_code_dropdown.vue를 마운트합니다.
마운트 지점은 app/views/projects/empty.html.haml이 렌더링하는
app/views/projects/buttons/_code.html.haml에서 옵니다.