Argilla 前端目录结构全解析从 Nuxt 页面组织到 v1 Clean Architecture 分层【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla本篇文章基于 Argilla 仓库中 argilla-frontend/docs/structure.md 的官方目录说明逐层剖析 Argilla 前端基于 Nuxt 2 Vue 2 的 Web 应用的完整目录体系。你将掌握 assets、components、pages、layouts、middleware、plugins、e2e、v1 等每个目录的职责边界与相互调用关系理解 base 组件与 features 组件的分层哲学并看懂 v1 新架构中依赖注入容器、领域层与基础设施层的真实组织方式从而能够快速定位代码、判断新功能应该落在哪个目录。一、顶层目录总览structure.md给出的官方结构树完整如下. ├── assets │ ├── fonts │ ├── icons │ └── scss ├── database - Vuex modules (to be removed) ├── models - Vuex models (to be removed) ├── store - Vuex store (to be removed) ├── components │ ├── base - Base and stateless components │ ├── features - Features used in just one page │ ├── annotation - Componentes used in Annotation page │ ├── datasets - Components to support datasets page │ ├── global - Components used in multiple pages ex: UserAvatarComponent │ ├── login - Components to support login page │ └── user-settings - Components to support user settings page ├── e2e - E2E tests ├── layouts - Layout components ├── middleware - Nuxt middlewares ├── pages - Nuxt global pages ├── plugins - Nuxt plugins ├── static - Static resources ├── translations - Argilla translation resources ├── v1 - New architecture │ ├── di │ ├── domain │ ├── infrastructure │ └── store │... ├── package.json ├── package-lock.json └── .gitignore对照当前仓库实际内容可以观察到结构演进文档中标记为 to be removed 的databaseVuex modules、modelsVuex models两个目录已经不存在storeVuex store也整体迁移到了 v1/store 之下原本分散在components下的annotation、datasets、global、login、user-settings子目录如今统一收纳进 components/features并在其中新增了dataset-creation、home等功能域translations目录实际名为translation与 nuxt.config.ts 中的langDir: translation/保持一致。理解这份文档基线 仓库现状的差异比单纯背目录更有价值——它反映了一次从 Vuex 状态管理向 Pinia/组合式 API 演进、从扁平组件目录向基础组件 功能组件两级体系演进的重构过程。二、assets样式与图标的统一入口assets是构建期会被打包进应用的静态资源目录与static运行期原样拷贝有本质区别。当前仓库中该目录实际包含assets/scss全部 SCSS 样式源文件其中abstract/存放变量、函数、混入mixin等抽象层定义assets/icons由 SVG 图标生成的 JS 模块如 assets/icons/annotation-mode.js 系列配合 assets/icon-template.js.tmp 模板文件assets/styles.scss全局样式入口。这些资源在 nuxt.config.ts 中被消费css: [~assets/styles.scss], ... styleResources: { scss: ./assets/scss/abstract.scss, },css将全局样式注入所有页面styleResources来自nuxtjs/style-resources模块则把abstract.scss中定义的 SCSS 变量与混入自动注入到每个组件的style中使业务组件无需手动import即可使用主题变量——这是目录结构与构建配置联动的典型例子。图标生成链路同样值得注意package.json 中的generate-icons脚本vsvg -s ./static/icons -t ./assets/icons --tpl ./assets/icon-template.js.tmp把static/icons下的原始 SVG 批量编译为assets/icons下的 JS 模块供 base-icon 组件动态渲染。因此新增一个图标需要同时改动static/icons与assets/icons两个目录且后者是生成产物不应手工编辑。三、componentsbase 与 features 的两级组件哲学components是 Argilla 前端组件体系的核心遵循基础组件与业务组件分离的原则通过 nuxt.config.ts 的自动导入能力全局注册components: [ { path: ~/components, pattern: **/*.vue, pathPrefix: false, level: 1, }, ],pathPrefix: false意味着所有.vue组件都会以文件名为组件名如base-tag目录下的文件即为BaseTag无需在模板中手动import。3.1 base基础且无状态的通用组件base目录argilla-frontend/components/base存放与业务无关、可复用、多为无状态的原子组件例如base-badge、base-tag徽章与标签base-button、base-checkbox、base-switch、base-slider、base-range基础表单控件base-icon图标渲染base-modal、base-tooltip、base-dropdown浮层与弹窗base-input、base-search-bar输入与搜索base-toast、base-feedback全局反馈提示base-render-markdown、base-codeMarkdown 渲染与代码高亮base-progress、base-loading、base-spinner加载与进度展示。这类组件的典型特征是无副作用、不直接依赖后端 API输入输出完全由 props/events 驱动因此可以在任何页面中安全复用。例如base-render-markdown底层借助marked、marked-highlight、marked-katex-extension与dompurify见 package.json实现安全的高亮与数学公式渲染供注释annotation页面的指导语guidelines等场景使用。3.2 features服务于单一页面的功能组件features目录argilla-frontend/components/features按页面/业务域组织当前包含annotation、dataset-creation、global、home、login、user-settings六个功能域与 structure.md 描述的Features used in just one page一脉相承。以最重要的 features/annotation99 个.vue文件、31 个.ts文件为例其内部按职责再次细分container标注流程的容器组件承担数据编排header标注页顶部工具栏guidelines数据集标注指导语的展示pagination记录翻页progress标注进度展示settings标注设置面板shortcuts键盘快捷键。而global如UserAvatarComponent一类的跨页面组件、login、home、dataset-creation、user-settings分别对应登录页、首页、新建数据集流程与用户设置页面。当新功能只属于某个页面时应放入对应功能域只有当组件被多个页面共用且与业务无关时才应该上升到base。四、pages、layouts、middleware 与 pluginsNuxt 四大约定目录4.1 pages文件即路由argilla-frontend/pages 采用 Nuxt 的文件系统路由约定关键页面包括index.vue首页sign-in.vue登录页配套useSignInViewModel.tswelcome-hf-sign-in.vueHugging Face Spaces 环境下的欢迎/登录引导页user-settings.vue用户设置new/_id.vue新建数据集流程动态路由参数iddataset/_id/数据集详情其中settings.vue为数据集设置页annotation-mode/为标注模式页面useDatasetViewModel.ts与useDatasetSettingViewModel.ts分别是两级页面各自的 ViewModel。ViewModel 模式useXxxViewModel.ts是 Argilla 前端的标准做法页面组件只负责渲染业务逻辑收敛到 ViewModel 中再通过 v1 层的 UseCase 与 Repository 访问后端。4.2 layouts页面骨架argilla-frontend/layouts 定义了四类页面骨架Home.vue首页布局、AuthenticationLayout.vue登录/认证布局、AnnotationPage.vue标注页全屏布局、InternalPage.vue内部功能页布局外加app.vue应用根布局与error.vue错误页。不同页面通过 Nuxt 的layout属性选择不同骨架例如标注页面使用沉浸式的AnnotationPage以最大化标注空间。4.3 middleware路由守卫argilla-frontend/middleware 中的两个中间件在 nuxt.config.ts 中被全局挂载router: { middleware: [route-guard, me], base: process.env.BASE_URL ?? /, },route-guard.ts 按路由名做访问控制未登录访问任何页面时记录redirectTo并重定向到sign-in已登录用户访问sign-in则跳回首页在 Hugging Face Spaces 环境下将登录入口重定向到welcome-hf-sign-in对oauth-provider-callback等 OAuth 回调路由做空参数拦截me.ts 通过ts-injecty的useResolve(LoadUserUseCase)加载当前用户若后端返回 401 则触发$auth.logout()并重定向到登录页——这是路由守卫与 v1 架构协同工作的典型链路。4.4 plugins全局注入argilla-frontend/plugins 在 nuxt.config.ts 中以plugins: [{ src: ~/plugins }]整体注册。其入口 plugins/index.ts 使用require.context(./, true, /^\.\/.*\.(ts|js)$/)递归加载目录下所有插件模块并执行其默认导出从而实现新增插件文件即自动注册。插件按职责分子目录axios/axios-cache.tsAPI 响应缓存与axios-global-handler.ts全局错误处理di/依赖注入容器初始化入口di.tsdirectives/自定义指令如tooltip.directive.ts、click-outside.directive.ts、badge.directive.ts、required-field.directive.ts、svg-icon.element.tsextensions/工具扩展如color-generator.ts、copy-to-clipboard.ts、format-number.ts、notification.ts、vue-draggable.tslanguage/language-detector.ts与language-direction.tslogo/Logo 渲染逻辑。五、e2ePlaywright 端到端测试argilla-frontend/e2e 存放基于 Playwright 的端到端测试playwright.config.ts与 package.json 中的e2e/e2e:silent/e2e:report脚本对应并在postgenerate阶段nuxt generate后自动执行静默回归测试。测试目录按页面划分annotation-mode-page标注模式含 autosave、mac 快捷键、元数据筛选与排序等专项 spec、dataset-setting-page、datasets-page、login-page、user-setting-pagecommon/目录则提供 API Mock 工具dataset-api-mock.ts、record-api-mock.ts、question-api-mock.ts、field-api-mock.ts、metadata-api-mock.ts与login-and-wait-for.ts使 E2E 测试可以脱离真实后端独立运行。各 spec 目录下的__screenshots__用于维护 Playwright 视觉回归基线。六、static 与 translation静态资源与多语言argilla-frontend/static 存放运行期原样暴露的静态资源fonts/Raptor 主题字体、icons/与assets/icons对应的 SVG 源文件、images/Logo、登录页截图、帮助信息图、js/handlebars.min.js以及favicon系列与site.webmanifest在 nuxt.config.ts 的head中被引用。argilla-frontend/translation 是 Argilla 的多语言资源目录提供en.js、de.js、es.js、ja.js四种语言文件与 nuxt.config.ts 的nuxtjs/i18n配置一一对应langDir: translation/、defaultLocale: en、fallbackLocale: en、strategy: no_prefix、关闭浏览器语言自动探测。新增语言只需在此目录添加语言文件并在i18n.locales注册。七、v1面向 Clean Architecture 的新架构v1是 Argilla 前端正在演进的新架构argilla-frontend/v1替代以 Vuex 为中心的旧模式其核心是依赖注入 分层职责。整体分为四层7.1 di依赖注入容器argilla-frontend/v1/di/di.ts 中的loadDependencyContainer(context)是 v1 架构的心脏它基于ts-injecty的Container.register(dependencies)将全部 Repository 与 UseCase 显式注册进容器。每个 Repository 注入useAxiosExtension(context)提供的 Axios 实例UseCase 则声明其依赖的 Repository 或 Storageregister(GetDatasetsUseCase) .withDependencies(DatasetRepository, useDatasets) .build(), register(LoadRecordsToAnnotateUseCase) .withDependencies( GetRecordsByCriteriaUseCase, GetDatasetProgressUseCase, GetUserMetricsUseCase, useRecords ) .build(),这种注册表式的写法让组件 → UseCase → Repository → HTTP的依赖链一目了然也便于单元测试中替换依赖实现。7.2 domain纯业务领域层argilla-frontend/v1/domain 分为四部分entities/84 个 TS 文件领域实体模型如dataset/、record/、user/、workspace/、question/、field/、metadata/、vector/等usecases/36 个 TS 文件业务用例如get-datasets-use-case.ts、submit-record-use-case.ts、save-draft-use-case.ts、bulk-annotation-use-case.ts、load-records-to-annotate-use-case.ts、dataset-setting/下的一系列配置更新用例同目录的*.test.ts如get-dataset-fields-grouped-use-case.test.ts、oauth-login-usecase.test.ts展示了对 UseCase 的单元测试方式services/领域服务接口如 v1/domain/services 中的IDatasetRepository定义 Repository 的抽象契约events/领域事件定义。7.3 infrastructure基础设施实现argilla-frontend/v1/infrastructure 是 domain 层的实现落地repositories/19 个 TS 文件如 DatasetRepository.ts直接面向后端 API。以数据集为例create走POST /v1/datasets、publish走PUT /v1/datasets/{id}/publish、import/export走/v1/datasets/{id}/import与/export、update走PATCH /v1/datasets/{id}、进度查询走GET /v1/datasets/{id}/progress配合largeCache()并在写操作后调用revalidateCache使AxiosCache缓存失效。错误统一映射为DATASET_API_ERRORS常量中的语义化错误码供上层做用户提示services/23 个 TS 文件如useRunningEnvironment、useLocalStorage、useAxiosExtension、useRoutes、useRole等横切能力storage/6 个 TS 文件Pinia 状态存储如DatasetStorage、RecordsStorage、DatasetsStorage、MetricsStorage、DatasetSettingStorage、TeamProgressStorageevents/基础设施层事件处理器如UpdateMetricsEventHandler、UpdateTeamProgressEventHandlertypes/后端响应类型定义。7.4 store状态管理v1/store 中的create.ts与non-reactive.ts提供状态创建工具配合pinia/nuxtnuxt.config.ts 中disableVuex: false表明当前仍兼容 Vuex完成从 Vuex 向 Pinia 的渐进迁移这也印证了 structure.md 中Vuex store to be removed的演进方向。八、命名规范kebab-case、PascalCase 与 camelCaseargilla-frontend/docs/conventions.md 定义了全仓库统一的命名约定文件夹名kebab-case例如base-tag、dataset-creation组件名PascalCase例如BaseTag.vue、UserAvatarComponent.vue类名PascalCase例如Question.ts、DatasetRepository.ts变量/常量名camelCase例如firstName: string。这套约定与第 3 节所述的组件自动导入机制深度耦合由于pathPrefix: falsebase-tag目录下的BaseTag.vue恰好能被 Nuxt 识别为base-tag组件Vue 官方也要求组件注册名与文件名保持 PascalCase 一致。遵循此规范即可保证文件名 → 组件名 → 模板标签三者无缝映射。九、目录、配置与请求代理的联动最后将目录结构放回 nuxt.config.ts 这一总调度中看全貌ssr: false表明 Argilla 前端是纯客户端渲染SPAgenerate.dir输出到DIST_FOLDER默认distAxios 采用proxy: true/api/与/share-your-progress两个路径被代理到后端地址BASE_URL默认http://0.0.0.0:6900可通过环境变量API_BASE_URL覆盖前端代码中实际请求如/v1/datasets即经由此代理转发auth策略配置了local策略、redirect: { login: /sign-in, logout: /sign-in }与pages/sign-in.vue、middleware 中的重定向逻辑相互印证publicRuntimeConfig暴露clientVersion取自 package.json 版本与文档站链接供前端运行时读取。十、写给开发者的目录导航建议结合以上分析在 Argilla 前端做功能开发时的目录导航路径可以概括为新增页面→ 在 pages 按路由创建.vue 对应useXxxViewModel.ts需要新骨架时在 layouts 增加布局页面专属 UI→ 在 components/features 对应功能域下新增组件通用无状态组件→ 放到 components/base业务逻辑→ 在 v1/domain/usecases 新增 UseCase并在 v1/di/di.ts 注册依赖访问后端→ 在 v1/infrastructure/repositories 实现 Repository接口契约定义在 v1/domain/services状态共享→ 在 v1/infrastructure/storage 定义 Pinia 存储路由拦截→ 修改 middleware全局能力→ 在 plugins 对应子目录新增插件模块样式与图标→ SCSS 放 assets/scss图标 SVG 源文件放 static/icons 后执行npm run generate-icons文案→ 在 translation 各语言文件同步添加回归保障→ 单元测试跟随 UseCase/组件端到端场景补充到 e2e。掌握这份目录地图你就具备了在 Argilla 前端代码库中按图索骥的能力无论是排查标注流程的 bug、新增数据集设置项还是理解用户登录与路由守卫的完整链路都能快速定位到对应的组件、UseCase 与 Repository。【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
