my-coding-style

编程规范

代码组织

• 单一职责：每个源文件应具有清晰、聚焦的作用域/目的
• 拆分大文件：当文件过大或处理过多关注点时应拆分
• 常量抽取：将常量移动到专用的 constants.js 文件
• 环境变量统一：编程时若涉及到环境变量部分的代码，必须统一从前后端各自的 .env.* 中读取
• UTF-8 编码：使用 UTF-8 编码，若遇到携带 BOM 标记的文件，则必须移除 BOM 以避免编码出现问题，如果文件中出现乱码，需要及时检测并修复编码问题

JavaScript

• 使用 ES6+ 特性：优先采用现代 JavaScript 语法与特性
• JSDoc 规范：严格遵守 JSDoc 注释规范，记录函数参数、返回值与复杂逻辑

TypeScript

• 显式返回类型：尽可能显式声明返回类型
• 避免复杂内联类型：将复杂类型提取为独立的 type 或 interface 声明
• 类型分离：当使用 TypeScript 时，始终将类型与接口分离到 types.ts 或 types/*.ts
• TSDoc 规范 ：严格遵守 TSDoc 注释规范，记录函数参数、返回值与复杂逻辑

注释

• 中文注释：尽可能遵守中文注释规范，以便开发者更好地理解
• 清晰简洁：注释应当简明扼要，避免冗长
• 解释“为什么”而非“怎么做”：注释应描述理由或意图，而非代码行为

测试（Vitest）

• 测试文件命名：foo.js → foo.test.js（同目录）
• 使用 describe/it API（不使用 test）
• 对复杂输出使用 toMatchSnapshot
• 对语言特定快照使用带显式路径的 toMatchFileSnapshot

前端样式（Sass、UnoCss）

• UnoCSS 优先：Sass 仅在 UnoCSS 无法满足需求时使用
• BEM 命名：当使用 Sass 时，采用 BEM 命名约定

包管理器（pnpm）

• 统一使用 pnpm：前后端项目均使用 pnpm 作为包管理器
• 独立的依赖管理：前后端项目应维护自己的依赖列表，避免全局依赖冲突
• 禁止使用 .pnpm-store：禁止在项目中生成和使用 pnpm 的全局存储目录 .pnpm-store

---

应用开发

框架选择

使用场景	选择
前端	Vite + Vue3
后端	Nestjs + Prisma ORM v7 + PostgreSQL

Vue 约定

约定	偏好
Script 语法	始终使用 <script setup>
JavaScript	优先使用现代 JavaScript 语法，而非 TypeScript
状态	优先 shallowRef() 而非 ref()
对象	使用 ref()，避免 reactive()
Vue 路由	Vue Router
UI 组件库	Element Plus
样式	UnoCSS, Sass
工具库	VueUse, Lodash
仓库状态管理	Pinia, pinia-plugin-persistedstate（持久化插件）
Ajax 请求	Axios

Vue 设计原则

• 模块化/组件化：优先使用模块化和组件化的方式组织代码，避免单一文件过大或过于复杂
• 单一职责：每个模块或组件应专注于一个功能或职责，避免过多关注点混杂在一起
• 单页面专用组件：当某个页面需要设计专用组件时，可以在该页面目录下创建 components 文件夹，例如：src/views/<page-name>/components/<ComponentName>.vue，存放该页面专用组件，避免在全局组件目录下创建仅供单页面使用的组件

Vue 页面结构约定

生成新的 Vue 页面时，必须使用按页面分文件夹的结构：

• src/views/<page-name>/index.vue

规则：

• <page-name> 必须为 kebab-case
• 绝不在 src/views 下直接创建单文件页面（禁止：src/views/home.vue）
• 若用户仅提供页面名称（未含路径），应自动推断并创建文件夹结构
• 需要时将相关文件放在同一文件夹中（例如 index.ts、types.ts、style.scss、__tests__）

示例：

• 请求：“Create Home page” 或 “Create AboutMe page”
• 输出路径：src/views/home/index.vue 或 src/views/about-me/index.vue
• 禁止：src/views/home.vue 或 src/views/about-me.vue

Vue 组件结构约定

生成新的 Vue 组件时，必须使用按组件分文件夹的结构：

• src/components/<ComponentName>/<ComponentName>.vue

规则：

• <ComponentName> 必须为 PascalCase
• 绝不在 src/components 下直接创建单文件组件（禁止：src/components/HelloWorld.vue）
• 若用户仅提供组件名称（未含路径），应自动推断并创建文件夹结构
• 需要时将相关文件放在同一文件夹中（例如 index.ts、types.ts、style.scss、__tests__）

示例：

• 请求：“Create HelloWorld component”
• 输出路径：src/components/HelloWorld/HelloWorld.vue
• 禁止：src/components/HelloWorld.vue

Vue 文件模板

严格按照 <template> 在上，<script setup> 在中，<style> 在下的结构生成 Vue 文件，如下：

<template></template>

<script setup></script>

<style lang="scss" scoped></style>

前端 API 接口文件路径规范

src/api/          # 接口层：按业务模块组织 API 请求与请求封装
    ├── modules/  # API 请求文件
    └── request/  # Axios 封装与配置（请求拦截器和响应拦截器等）

⚠ 注意：api 接口文件禁止直接放在 src/api 下

• 违规的 api 接口文件路径：src/api/user.js
• 合法的 api 接口文件路径：src/api/modules/system/user.js、src/api/modules/menu/index.js、src/api/modules/login.js

前端本地持久化缓存

• Pinia 持久化：使用 pinia-plugin-persistedstate 插件将 Pinia 状态持久化到 localStorage

图标 icons

当前端需要使用 图标/字体图标/icons 时，必须遵循以下约定：

优先级：iconfont 图标 > Element Plus 图标 > UnoCSS 图标 > SVG 图标

• iconfont 图标：高优先级，先查询项目中 src/assets/iconfont 下有无引入 iconfont 资源，优先使用 iconfont 的字体图标，文档链接：iconfont
• Element Plus 图标：中优先级，使用 Element Plus 内置图标，满足常规 UI 需求，文档链接：Element Plus Icon
• UnoCSS 图标：次优先级，使用 UnoCSS 的图标功能，它支持多种图标集，文档链接：UnoCSS Icons
• SVG 图标：最低优先级，当其他图标无法满足需求时，才能使用 SVG 图标，并将 SVG 文件放在 src/assets/svgs 目录下，使用 vite-svg-loader 加载器进行处理
• 图标命名：SVG 图标文件命名应使用 kebab-case，例如：user-profile.svg、home.svg