213 lines
14 KiB
Markdown
213 lines
14 KiB
Markdown
---
|
||
title: Nuxt3 代码规范
|
||
description: 这是一份提供给AI大模型的Nuxt3框架规范、编程标准，可以有效提高Cursor等大模型对Nuxt.js框架的编写能力。
|
||
date: 2025-07-12
|
||
img: https://lijue-me.oss-cn-chengdu.aliyuncs.com/20250624125918171.png
|
||
navigation:
|
||
icon: simple-icons:nuxtdotjs
|
||
---
|
||
## 概述
|
||
这是一份提供给AI大模型的Nuxt3框架规范、编程标准，可以有效提高Cursor等大模型对Nuxt.js框架的编写能力。
|
||
|
||
---
|
||
description: 本规则为 Nuxt.js 项目提供全面的最佳实践和编码标准，涵盖代码组织、性能、安全性、测试和常见陷阱。旨在确保 Nuxt.js 应用程序的可维护性、可扩展性和安全性。
|
||
globs: *.vue,*.js,*.ts,*.mjs,*.mts,*.jsx,*.tsx,*.config.js,*.config.ts
|
||
---
|
||
|
||
- **启用 ESLint 支持：** 使用 `@nuxt/eslint` 模块来配置项目感知的 ESLint。这确保代码质量和一致性。
|
||
- 运行 `npx nuxi module add eslint` 添加模块。
|
||
- 根据需要自定义生成的 `eslint.config.mjs` 文件。
|
||
- **采用 Nuxt.js 模块：** 利用 Nuxt.js 模块来封装功能并维护干净的代码库。在实现自定义解决方案之前先探索现有模块（例如，用于服务端身份验证的 `@nuxt/auth`）。
|
||
- **约定优于配置：** 遵循 Nuxt.js 约定来简化开发和协作。除非绝对必要，否则避免偏离约定。
|
||
- **高效利用 Nuxt 布局：** 为多个页面共享的组件创建可重用布局，以确保一致性并节省开发时间。布局位于 `layouts/` 目录中。
|
||
- **使用 Pinja 管理状态：** 使用 Pinia 进行状态管理。根据功能或特性组织 store 模块，以提高可维护性。
|
||
- **将页面分解为组件：** 将页面分解为小的、可重用的组件，以增强可维护性、可测试性和可重用性。每个组件都应该有单一责任。
|
||
- **明智地利用 Nuxt 插件：** 使用 Nuxt 插件在 Vue.js 初始化之前运行代码或添加全局功能。注意插件对性能的影响。插件位于 `plugins/` 目录中。
|
||
- **针对 SEO 和性能进行优化：** 利用 Nuxt.js 的服务端渲染 (SSR) 来优化 SEO。为图片实现懒加载并优化资源以最小化初始加载时间。使用 Lighthouse 等工具识别性能瓶颈。
|
||
- **实现错误处理和验证：** 实现强大的错误处理和验证机制，以提供无缝的用户体验。使用 Nuxt.js 中间件拦截请求和响应进行错误处理和数据验证。
|
||
- **为代码编写文档：** 使用 JSDoc 等工具为组件、模块和自定义函数提供清晰简洁的文档。
|
||
- **拥抱测试：** 使用 Jest、Vue Test Utils 和 Vitest 等工具编写单元测试、集成测试和端到端测试。
|
||
|
||
## 1. 代码组织和结构：
|
||
|
||
- **目录结构：**
|
||
- `components/`：可重用的 Vue 组件。
|
||
- `composables/`：可重用的组合式函数。
|
||
- `layouts/`：应用程序布局。
|
||
- `middleware/`：路由中间件。
|
||
- `pages/`：应用程序页面（路由定义）。
|
||
- `plugins/`：Nuxt.js 插件。
|
||
- `server/`：API 路由和服务端逻辑。
|
||
- `static/`：静态资源（例如，图片、字体）。
|
||
- `store/`：Pinia stores（可选，但推荐）。
|
||
- `utils/`：工具函数。
|
||
- **文件命名约定：**
|
||
- 组件：`PascalCase.vue`（例如，`MyComponent.vue`）
|
||
- 组合式函数：`usePascalCase.js` 或 `usePascalCase.ts`（例如，`useCounter.js`）
|
||
- 布局：`kebab-case.vue`（例如，`default.vue` 或 `custom-layout.vue`）
|
||
- 页面：`kebab-case.vue`（例如，`index.vue`、`about.vue`、`product-details.vue`）
|
||
- 插件：`kebab-case.js` 或 `kebab-case.ts`（例如，`analytics.js`）
|
||
- Stores：`kebab-case.js` 或 `kebab-case.ts`（例如，`user-store.js`）
|
||
- 工具函数：`camelCase.js` 或 `camelCase.ts`（例如，`formatDate.js`）
|
||
- **模块组织：**
|
||
- 将相关功能分组到单独的模块中。
|
||
- 在 `nuxt.config.js` 或 `nuxt.config.ts` 中使用 `@nuxt/modules` 数组注册模块。
|
||
- 创建自定义模块来封装复杂逻辑。
|
||
- **组件架构：**
|
||
- 优先使用组合而非继承。
|
||
- 对简单的 UI 元素使用函数式组件。
|
||
- 设计组件时考虑可重用性和可测试性。
|
||
- 考虑使用插槽进行灵活的组件组合。
|
||
- **代码分割：**
|
||
- 利用动态导入进行基于路由的代码分割。
|
||
- 使用 `import()` 将大组件分割成更小的块。
|
||
- 使用 Webpack Bundle Analyzer 等工具分析包大小。
|
||
|
||
## 2. 常见模式和反模式：
|
||
|
||
- **设计模式：**
|
||
- **组合式 API：** 使用组合式 API 来组织组件逻辑。
|
||
- **Store 模式 (Pinia)：** 使用 Pinia 实现集中式状态管理系统。
|
||
- **中间件模式：** 使用中间件进行身份验证、授权和数据验证。
|
||
- **插件模式：** 为全局功能和第三方库集成创建插件。
|
||
- **推荐方法：**
|
||
- **API 通信：** 在组件内使用 `useFetch` 或 `useAsyncData` 组合式函数进行 API 调用。
|
||
- **表单处理：** 利用 Vue 的内置表单处理功能与 `v-model` 和像 VeeValidate 这样的验证库。
|
||
- **身份验证：** 使用 `@nuxt/auth` 库或自定义解决方案实现安全的身份验证流程。
|
||
- **授权：** 使用中间件和 Pinia stores 实现基于角色的访问控制 (RBAC)。
|
||
- **反模式：**
|
||
- **直接修改 props：** 避免从子组件直接修改父组件数据。请使用 `emit` 代替。
|
||
- **过度使用全局状态：** 将全局状态的使用限制在必要的应用程序数据上。对本地数据考虑使用组件级状态。
|
||
- **忽略错误处理：** 始终处理 API 调用和其他异步操作中的潜在错误。
|
||
- **编写过于复杂的组件：** 将大组件分解为更小、更易管理的部分。
|
||
- **状态管理最佳实践：**
|
||
- **单一数据源：** 在 Pinia stores 中为应用程序状态维护单一、一致的数据源。
|
||
- **不可变性：** 将状态视为不可变的。使用函数来更新 store 而不是直接操作数据。
|
||
- **清晰的命名约定：** 为 store 模块、actions 和 mutations 使用描述性名称。
|
||
- **模块化：** 根据功能或特性将 stores 分成模块。
|
||
- **错误处理模式：**
|
||
- **集中式错误处理：** 实现全局错误处理器来捕获未处理的异常。
|
||
- **错误边界：** 使用错误边界来隔离组件故障并防止级联错误。
|
||
- **用户友好的错误消息：** 为用户提供清晰和有用的错误消息。
|
||
|
||
## 3. 性能考虑：
|
||
|
||
- **优化技术：**
|
||
- **懒加载：** 为图片、组件和路由实现懒加载。
|
||
- **代码分割：** 将应用程序分割成更小的块以获得更快的初始加载时间。
|
||
- **Tree Shaking：** 在构建过程中删除未使用的代码。
|
||
- **缓存：** 缓存 API 响应和静态资源以减少服务器负载。
|
||
- **图片优化：** 使用 `nuxt/image` 等工具优化图片。使用适当的图片格式（WebP）。将图片大小调整为适当大小。考虑使用 CDN 进行图片交付。
|
||
- **内存管理：**
|
||
- **避免内存泄漏：** 在组件卸载时清理事件监听器和定时器。
|
||
- **使用弱引用：** 在可能的情况下对 DOM 元素使用弱引用。
|
||
- **最小化对象创建：** 避免创建不必要的对象和数组。
|
||
- **渲染优化：**
|
||
- **虚拟化：** 对大列表使用虚拟化以提高渲染性能。
|
||
- **记忆化：** 记忆化昂贵的计算以避免冗余计算。有效使用 `computed` 属性以避免不必要的重新渲染。
|
||
- **防抖和节流：** 对事件处理器使用防抖和节流以减少函数调用次数。
|
||
- **包大小优化：**
|
||
- **分析包大小：** 使用 Webpack Bundle Analyzer 识别大依赖项。
|
||
- **删除未使用的依赖项：** 删除未使用的依赖项以减少包大小。
|
||
- **使用更小的替代方案：** 考虑使用更小的替代方案来替代大型库。
|
||
- **优化依赖项：** 检查依赖项并确保您使用的是最高效的版本。
|
||
- **懒加载策略：**
|
||
- **基于路由的懒加载：** 仅在访问相应路由时加载组件。
|
||
- **基于组件的懒加载：** 仅在组件在视口中可见时加载组件。
|
||
|
||
## 4. 安全最佳实践：
|
||
|
||
- **常见漏洞：**
|
||
- **跨站脚本攻击 (XSS)：** 通过正确清理用户输入和使用 Vue 的内置 HTML 转义来防止 XSS 攻击。
|
||
- **跨站请求伪造 (CSRF)：** 通过实现 CSRF 令牌来防止 CSRF 攻击。
|
||
- **SQL 注入：** 避免原始 SQL 查询。使用 ORM（对象关系映射器）来防止 SQL 注入。
|
||
- **身份验证和授权缺陷：** 实现安全的身份验证和授权机制。
|
||
- **不安全的直接对象引用 (IDOR)：** 实现适当的访问控制以防止对资源的未授权访问。
|
||
- **输入验证：**
|
||
- **服务端验证：** 始终在服务端验证用户输入。
|
||
- **客户端验证：** 提供客户端验证以获得更好的用户体验（但不要依赖它作为验证的唯一来源）。
|
||
- **清理输入：** 清理用户输入以删除潜在的有害字符。
|
||
- **身份验证和授权模式：**
|
||
- **JWT（JSON Web Tokens）：** 使用 JWT 进行身份验证和授权。
|
||
- **OAuth 2.0：** 为第三方身份验证实现 OAuth 2.0。
|
||
- **基于角色的访问控制 (RBAC)：** 实现 RBAC 来根据用户角色控制对资源的访问。
|
||
- **数据保护策略：**
|
||
- **加密：** 对静态和传输中的敏感数据进行加密。
|
||
- **散列：** 使用强散列算法对密码和其他敏感数据进行散列。
|
||
- **数据屏蔽：** 在日志和其他非生产环境中屏蔽敏感数据。
|
||
- **安全的 API 通信：**
|
||
- **HTTPS：** 始终使用 HTTPS 进行 API 通信。
|
||
- **API 速率限制：** 实现 API 速率限制以防止滥用。
|
||
- **身份验证和授权：** 对所有 API 端点要求身份验证和授权。
|
||
|
||
## 5. 测试方法：
|
||
|
||
- **单元测试：**
|
||
- **测试单个组件：** 孤立地测试单个组件。
|
||
- **模拟依赖项：** 模拟外部依赖项以在测试期间隔离组件。
|
||
- **验证组件行为：** 验证组件正确渲染并按预期行为。
|
||
- **集成测试：**
|
||
- **测试组件交互：** 测试组件之间的交互。
|
||
- **测试数据流：** 测试组件和 stores 之间的数据流。
|
||
- **测试 API 集成：** 测试与外部 API 的集成。
|
||
- **端到端测试：**
|
||
- **模拟用户交互：** 模拟用户交互以测试应用程序的功能。
|
||
- **测试整个应用程序流程：** 从头到尾测试整个应用程序流程。
|
||
- **使用浏览器自动化工具：** 使用 Cypress 或 Playwright 等浏览器自动化工具。
|
||
- **测试组织：**
|
||
- **按功能组织测试：** 按功能或特性组织测试。
|
||
- **使用描述性测试名称：** 使用描述性测试名称来清楚地说明每个测试正在测试什么。
|
||
- **保持测试隔离：** 保持测试彼此隔离以避免干扰。
|
||
- **模拟和存根：**
|
||
- **使用模拟对象：** 使用模拟对象在测试期间替换外部依赖项。
|
||
- **使用存根：** 使用存根用简化版本替换复杂函数。
|
||
- **避免过度模拟：** 避免模拟太多代码，因为这会使测试效果降低。
|
||
|
||
## 6. 常见陷阱和注意事项：
|
||
|
||
- **常见错误：**
|
||
- **错误的 `this` 上下文：** 注意 Vue 组件中的 `this` 上下文，使用箭头函数或 `bind` 来维护正确的上下文。
|
||
- **异步数据处理：** 使用 `async/await` 或 Promises 正确处理异步数据加载。
|
||
- **忘记取消订阅：** 在组件卸载时取消订阅事件监听器和定时器以防止内存泄漏。
|
||
- **过度使用 `forceUpdate`：** 除非绝对必要，否则避免使用 `forceUpdate`，因为它会对性能产生负面影响。
|
||
- **边缘情况：**
|
||
- **服务端渲染 (SSR)：** 了解客户端和服务端渲染之间的差异。
|
||
- **浏览器兼容性：** 在不同浏览器中测试应用程序以确保兼容性。
|
||
- **可访问性：** 在设计和开发应用程序时考虑可访问性。
|
||
- **版本特定问题：**
|
||
- **Nuxt 2 vs Nuxt 3：** 了解 Nuxt 2 和 Nuxt 3 之间的差异。
|
||
- **Vue 2 vs Vue 3：** 了解 Vue 2 和 Vue 3 之间的差异。
|
||
- **依赖项更新：** 仔细检查依赖项更新是否存在潜在的破坏性更改。
|
||
- **兼容性问题：**
|
||
- **浏览器支持：** 确保与目标浏览器兼容。
|
||
- **设备兼容性：** 在不同设备上测试应用程序。
|
||
- **操作系统兼容性：** 确保与目标操作系统兼容。
|
||
- **调试策略：**
|
||
- **使用浏览器开发者工具：** 使用浏览器开发者工具检查应用程序的状态和网络活动。
|
||
- **使用 Vue Devtools：** 使用 Vue Devtools 检查 Vue 组件和数据。
|
||
- **使用日志记录：** 使用日志记录来跟踪应用程序的行为。
|
||
|
||
## 7. 工具和环境：
|
||
|
||
- **推荐的开发工具：**
|
||
- **VS Code：** Visual Studio Code 是一个流行的代码编辑器，具有出色的 Vue.js 支持。
|
||
- **Vue Devtools：** Vue Devtools 是一个浏览器扩展，为 Vue.js 应用程序提供调试工具。
|
||
- **ESLint：** ESLint 是一个强制执行编码标准的代码检查器。
|
||
- **Prettier：** Prettier 是一个自动格式化代码的代码格式化器。
|
||
- **构建配置：**
|
||
- **`nuxt.config.js` 或 `nuxt.config.ts`：** 在 `nuxt.config.js` 或 `nuxt.config.ts` 中配置应用程序的构建设置。
|
||
- **Webpack：** Nuxt 使用 Webpack 来打包应用程序。
|
||
- **Vite：** Nuxt 3 默认使用 Vite 来打包应用程序，提供更快的构建和开发时间。
|
||
- **代码检查和格式化：**
|
||
- **ESLint：** 使用 ESLint 强制执行编码标准。
|
||
- **Prettier：** 使用 Prettier 自动格式化代码。
|
||
- **Husky：** 使用 Husky 在提交前运行代码检查器和格式化器。
|
||
- **部署最佳实践：**
|
||
- **服务端渲染 (SSR)：** 将应用程序部署到支持 SSR 的服务器。
|
||
- **静态站点生成 (SSG)：** 为内容丰富的应用程序生成静态站点。
|
||
- **CDN：** 使用 CDN 交付静态资源。
|
||
- **CI/CD 集成：**
|
||
- **持续集成 (CI)：** 使用 Jenkins、GitLab CI 或 GitHub Actions 等 CI 工具自动化构建和测试过程。
|
||
- **持续部署 (CD)：** 使用 CD 工具自动化部署过程。
|
||
|
||
通过遵循这些最佳实践，您可以构建强健、可维护且可扩展的 Nuxt.js 应用程序。 |