【翻译】如何构建大型 Vue 应用程序

本文来自 Vue School，这是你学习 vue 很好的站点。原文地址，作者 Daniel Kelly 是 Vue School 的首席讲师，喜欢帮助其他开发人员充分发挥潜力。他拥有 10 多年使用 Vue.js、Nuxt.js 和 Laravel 等技术的开发经验。

如果您感觉翻译侵犯了您的著作权，可以联系我，我会在收到反馈后删除此文。

有一部分链接是原文指向的链接，国内可能无法打开。这个还得您自己想办法喽🧐

什么是可预测的代码库？

可预测性到底是什么意思？最简单的是，它能够直观地从功能请求或错误报告转到代码库中可以解决所述任务的位置。此外，它还能够快速了解​​您可以在代码库中的该位置访问哪些工具来完成手头的任务。

为什么这很重要？嗯，你可能和我一样，有过这样的经历：接手一个项目，或者被介绍到一个现有的项目，然后在第一个任务上，你可能会想：“我甚至不知道从哪里开始！”

可预测代码库的重要性

您甚至可能已经处理代码库一段时间并且有同样的想法！可预测的代码库可以尽可能地减轻这种体验，从而使开发人员更轻松地了解项目并提高持续工作的效率。

我认为这里值得注意的是，虽然可预测性是可能的，但没有一个项目是 100% 可预测的。每个项目，无论是新的还是现有的，都至少有一个轻微的学习曲线。另外，请注意可预测性并不意味着代码库或应用程序作为一个整体可以快速理解。许多大型应用程序过于复杂，无法实现这一点，并且需要时间才能完全掌握。因此，可预测性并不是要看到完整的拼图，而更像是了解某个拼图的形状并能够快速看到它适合的位置。事实上，良好的代码库的本质在于它可以一次理解一部分，而不应该要求其开发人员必须立即考虑整体。

可预测性的关键：标准

那么我们如何在代码库中实现可预测性呢？答案是：标准，简单明了。也许这不是您正在寻找的答案，但这是事实。让任何事情变得可预测的最好方法是让它遵循一套标准。例如，我可以几乎 100% 确定地预测我今天刚买的新全尺寸床单将适合我的床，即使我以前从未用过这些床单。为什么？因为床单的标准尺码系统。

社区范围内的可预测性标准

因此这就引出了一个问题，整个 Vue.js 社区存在什么样的标准？我想说有 4 个可用的标准来源。

1. Vue.js 风格指南
2. Vite 生成的脚手架
3. 官方 Vue.js 库（可以在 Vue.js 网站的 生态系统 -> 官方库 下面找到）
4. 更宽泛地说，最流行的组件框架如 Vuetify 、 Quasar 、 PrimeVue 、 shad-cn vue 等，以及其他流行的社区工具如 VueUse 和 Nuxt。

虽然其中一些比其他的更正式地被视为标准，但我认为它们都提供了在项目和开发人员之间建立一些共同模式的机会，从而产生更可预测的代码库。

官方库和组件库

我们先来谈谈官方库和流行组件库带来的标准化。虽然这些库的主要目的是提供功能，但其副作用是采用了共享标准。

例如，如果您使用 Vue Router，那么您不仅可以受益于包本身的功能，而且最终您可以在一个项目中实现路由，就像在另一个项目中实现路由一样，并且与世界各地的 Vue.js 开发人员实现路由的方式非常相似。

这似乎显而易见，但有一点需要说明。如果 Vue.js 中存在针对某个问题的流行或推荐解决方案（尤其是官方解决方案），我会在使用其他任何解决方案之前深思熟虑。我和其他人一样乐于 DIY 自己的组件、store 等，但通常情况下，从长远来看，使用经过验证的解决方案更有价值。这不仅是因为它们提供的功能、测试覆盖率和文档，还因为它们带来的标准化。

在选择使用这些更标准化的解决方案时，务必牢记您正在构建的是什么。您正在构建一个需要高度定制化和品牌化设计的网站吗？那么，也许流行的组件库并不适合您。或者，您可以从像 Radix Vue 这样的无样式组件库中免费获得相关功能，同时保留对设计的完全控制权。如果应用程序的外观可以更通用一些，那么完全没有必要自己构建所有内容。可以使用流行的 UI 库，例如 Vuetify 、 PrimeVue 或 Quasar。

标准文件结构的开始

当谈到项目标准时，文件结构是一个经常被谈论的话题，虽然 Vue 没有指定特定结构的文档，但它确实从使用 npm create vue@latest 生成的代码库中提供了一个良好的起点。

我们大多数人可能都熟悉这种结构，这太棒了！这意味着我们离可预测性又近了一步！但是……其实并没有太多可以借鉴的地方。对于这种文件结构，你仍然需要做出很多决定。

那么，还有其他社区通用的标准吗？很高兴你问到这个问题！ Nuxt 在 Vue 社区非常流行，并且拥有更深入的文件结构模式。一个 Nuxt 项目的文件结构如下所示：

这比 Nuxt 文档网站更全面，几乎每个文件夹和文件都有一整页的文档。你还能要求更高的透明度和标准化吗？

此外，如果您热衷于领域驱动设计 (DDD)，您甚至可以利用 Nuxt 层来复制此文件结构，但根据您的业务需求将其拆分成独立的逻辑“存储桶”。 如果您有兴趣了解更多信息，我们有一篇专门讨论此主题的文章。

有些人可能会想：“但我的 Vue.js 应用程序不需要服务端渲染，所以我其实不需要 Nuxt。” 然而，我认为没有理由不在不使用 Nuxt 的情况下启动任何新的 Vue.js 项目。不需要服务端渲染？没问题，直接关掉就行了。

export default defineNuxtConfig({
    ssr: false
})

甚至按路由进行配置（没错，获得 SSR 和纯 CSR 的完美组合！）

export default defineNuxtConfig({
    routeRules: {
        "/admin": { ssr: false },
        // all other routes are SSR 所有其他的路由都使用服务端渲染
    }
})

重点在于，Nuxt 提供了大量详尽的文件结构标准，在我看来，放弃这些标准是不负责任的。（更不用说，这些文件结构还带有自动导入功能，让编码体验更加愉悦，而且如果你突然需要快速支持某些服务端 API 端点，Nuxt 也能帮到你）。如果你是 Vue 的专业人士，但刚接触 Nuxt，我推荐你学习 《精通 Nuxt》 或 《Nuxt.js 3 基础课程》 。它其实就是在 Vue 之上叠加的丰富功能。帮自己一个忙，学习起来并不难。

最后，我确实认为可以明智地进行一些补充，而且肯定必须这样做来处理其他用例，但我们稍后会详细讨论这些内容，因为它们在社区层面还没有标准化。

组件推荐规则

现在，重点关注组件的目录，Vue 样式指南为我们提供了一些进一步的建议，使我们的文件结构更加可预测。除其他外，样式指南在定义组件时鼓励以下内容：

• 如果可能，每个组件应在其自己的专用文件 (SFC) 中定义
• 单文件组件应以 PascalCase 命名
• 基础组件应以相同的前缀开头（例如 Base 或 App）
  • 您可以将基础组件视为应用程序范围内的可重用组件，例如按钮或模态框
  • 这将它们组合在一起并声明它们的全局性、可重用性
• 组件名称应始终是多个单词构成的，以免与任何现有或未来的 HTML 元素发生冲突。不要创建 Table 或 Button 为名组件。
• 单实例组件应以前缀 The 开头
  • 例如网站 页眉(header) 或 页脚(footer)，它们应命名为 TheHeader 和 TheFooter
  • 这将它们组合在一起并将它们声明为一次性使用
• 紧密耦合的子组件应以其父组件的名称作为前缀
  • 例如 TodoList 中的 TodoListItem
  • 这将它们组合在一起并声明它们相关
• 组件名称应以最顶层（通常是通用）单词开头，以最具体的单词结尾
  • 例如 SearchWidgetInput 、 SearchWidgetResultsList 、 SearchWidget
  • 这会将文件结构中的相关组件分组在一起

除此之外，完整的风格指南还有许多其他标准，这些标准将帮助您的项目对社区范围内的开发人员来说更加可预测。我不会在这里一一列举它们，但强烈建议您自己阅读并遵循风格指南。

一些推荐的个人/团队范围的可预测性标准

虽然官方消息来源为整个 Vue.js 社区制定了一些很好的标准，但还有其他一些模式并没有被广泛采用，根据我的经验，这些模式也同样有用，并且可以成为您或您团队项目的标准。这些标准是必要的，因为社区范围的标准并不是 100% 全面的，但在如何决定和维护团队标准时要小心并严格……如果你不这样做，它可能会成为不断变化的规则的兔子洞。这就是我对 Vue.js 项目标准的一些建议。

标准化路由/页面命名约定

另一种有意义的做法是命名路由和页面组件的标准化方法。在典型的 CRUD 应用程序中，每个资源都有以下不同的页面：

1. 所有资源的列表
2. 单个资源的视图
3. 创建资源的表单
4. 以及编辑资源的表单

虽然其中一些可能最终成为嵌套路由（例如从列表页面内查看模态叠加中的单个资源），但它们通常最终具有带有相应页面的专用路由。

由于我有 PHP Laravel框架 的使用经验，因此在命名路由并以可预测的方式定义其路径时，我本能地采用了 Laravel 现有的标准。这使得我经验丰富的 Laravel 团队能够更快速、更直观地使用 Vue。以“照片”资源为例，我推荐的 Laravel 命名约定 ，以及适用于 Vue 的命名约定，在 Nuxt 项目中如下：

Nuxt 项目中的页面文件结构示例。

让我们分析一下它的作用。

• C - create.vue 页面是您创建新照片的地方。（用户访问： /photos/create ）
• R - [id].vue 页面是您可以读取单个照片资源的页面。index.vue 页面可以一次列出多张照片，方便用户嵌套查看他们感兴趣的照片。（用户访问 /photos/[whatever-the-id-is] ）
• U - edit-[id].vue 页面是您更新照片资源的地方。（用户访问： /photos/edit-[whatever-the-id-is] ）
• D - 不需要专门的页面，因为它通常只是 index.vue 或 [id].vue 页面上的弹出窗口

标准化 API 端点命名约定

当然，这些只是视图。它们可能需要一些 API 端点来从数据库获取数据或将数据发送到数据库。如果您已经使用其他技术设置了后端，那就太好了！……希望它的端点能够按照一定的标准进行组织。如果您还没有设置后端，那么 Nuxt server/api 目录中的以下结构会非常有效。

让我们也来分解一下它。

• C - 对 /api/photos/ POST 请求由 index.post.ts 处理，并在数据库中创建新照片
• R - 对 /api/photos/[whatever-the-id-is] 的 GET 请求由 [id].get.ts 处理，并返回该帖子的具体信息。对 /api/photos GET 请求也由 index.get.ts 处理，并返回照片的分页列表。
• U - 对 /api/photos/[whatever-the-id-is] 的 PUT 请求由 [id].put.ts 处理，并更新数据库中的照片数据
• D - 对 /api/photos/[whatever-the-id-is] 的 DELETE 请求由 [id].delete.ts 处理，并从数据库中删除（或软删除）该资源

一些更全面的文件结构标准

除了 Nuxt 提供的开箱即用的文件结构外，我还建议标准化一些目录。以下是我根据最近开发的 Vue/Nuxt 项目，对一些团队标准目录提出的建议。

将页面特定组件与页面组件放在一起

有时，你的组件可能只在单个页面或单个资源的几个页面中有用（例如上文中的 photos 资源）。在这种情况下，我发现将这些组件存储在 pages/[resource (ie. photos)] 目录下的某个目录中会很有帮助，而不是放在 components 目录中。我喜欢把这个目录称为 partials 。它在文件系统中的样子如下：

这可以避免我在开发页面时在完全不同的目录之间来回切换。此外，它还能让我快速知道 PhotoForm.vue 仅在 4 个图片页面中的一个或多个中使用。

如果您担心 Nuxt 将这些部分转换为实际页面（实际上它确实会），您可以在构建时轻松删除它们。

// app/router.options.ts

import type { RouterConfig } from "@nuxt/schema";

// https://router.vuejs.org/api/interfaces/routeroptions.html
export default <RouterConfig>{
    routes: (_routes) => {
        if (import.meta.env.MODE === "production") {
            _routes = _routes.filter(route => !route.path.includes("partials"));
        }
        return _routes;
    },
};

在中心位置收集类型

我喜欢在所有 Vue/Nuxt 项目中包含的另一个标准目录是 @/types 目录。这是我定义项目所有类型的中心枢纽。即使这些类型是使用 Prisma 或 Drizzle 之类的工具自动生成的，我也喜欢从这个自定义目录中导入和导出这些生成的类型。为什么？因为这意味着当我想要导入和使用类型时，我不必考虑文件位置。我写 import {} from "@/types" ，然后就会得到一个包含所有类型（无论是自定义的还是生成的）的自动完成选项列表。

验证器文件夹

所有应用程序的一个共同需求是能够在用户输入进入数据库之前在后端验证用户输入，并且通常也在前端验证用户输入，这样用户就可以快速、立即获得他们需要修复的内容的反馈。

为了在我的项目中组织这些资源，我喜欢创建一个 @/validators 目录，然后为每种不同的资源类型创建一个文件。像这样：

请注意，扩展名前的 .validator 关键字并没有什么特别之处，它只是为了方便文件搜索而制定的命名规则。然后，在每个文件中，我将使用 Zod 来定义各种请求类型的实际验证逻辑。如下所示：

import { z } from "zod";

const BaseRules = z.object({
    id: z.string().uuid(),
    title: z.string().min(1),
    content: z.string().min(1),
});

const fields = Object.keys(BaseRules.shape) as [keyof typeof BaseRules.shape];

export const CreateRules = BaseRules.omit({ id: true });

export const UpdateRules = BaseRules;

export const DeleteRules = z.object({
    id: z.string().uuid(),
});

export const ReadRules = z.object({
    id: z.string().uuid(),
    include: z.enum(fields).optional(), // for limiting the fields to return
});

export const ListRules = z.object({
    keywords: z.string().optional(), // for searching
    limit: z.number().int().positive().optional(), // for pagination
    offset: z.number().int().positive().optional(), // for pagination
    sortBy: z.enum(fields).optional(),
    sortOder: z.enum(["asc", "desc"]).optional(),
    include: z.enum(fields).optional(), // for limiting the fields to return
});

现在，我可以同时在 API 端点和前端页面组件中导入这些不同的规则，以便在服务器端和客户端进行验证，同时只需声明一次验证器。我喜欢将 Zod 与 Formkit 搭配使用来进行前端验证。您可以在我们的 FormKit 课程 或 FormKit Zod 插件的文档中学习如何操作 。

或者，您可能想考虑使用 Valibot 来处理这些验证。它本质上与 Zod 相同，但其模块化架构意味着它可进行树优化。这意味着您发送到浏览器进行前端验证的验证规则将仅包含您实际用于应用的规则。

可预测性总结

虽然您最好不要忽视一些社区范围的标准，但您也可以为您或您的团队制定许多标准，以使您的代码库更具可预测性。虽然上面提到的一些标准已被证明对我有用，但其他标准可能也适合您或您的团队。最重要的是在各个项目中坚持使用它们，以便它们能够实现其目的。

虽然可预测性标准对于您的大型 Vue.js 应用程序大有裨益，但您仍有许多工作要做。请务必设置代码检查和格式化工具，例如 ESLint 和 Prettier ，以保持代码整洁、无错误且一致。您可以通过提示在新的 Vue 项目中设置这些工具，也可以使用 Nuxt 的 ESLint 模块 。

最后，如果您想获得更多有关构建大型 Vue.js 应用程序的技巧，请查看我在 2023 年 Vue Conf US 上所做的演讲。

译者结语

关于 Nuxt 的使用在国内还没有很好的课程，如果你可以访问 YouTube，你可以去订阅一下Alexander Lichter的频道，这个频道专注于 Nuxt 和 Vue 生态有关的视频，对你使用 Nuxt 应该有很大的帮助。此频道的作者目前已加入尤大创建的 VoidZero 公司担任开发者关系一职。

如果你想看下如何从零搭建一个 Nuxt 项目，可以看下 Syntax 的 CJ 发布的 Full Stack App Build | Travel Log w/ Nuxt, Vue, Better Auth, Drizzle, Tailwind, DaisyUI, MapLibre。