前端开发规范

参考来源: Vue 官方风格指南、Element Plus 最佳实践

---

UI 风格约束

严格禁止（常见 AI 风格）

• ❌ 蓝紫色霓虹渐变、发光描边、玻璃拟态
• ❌ 大面积渐变、过多装饰性几何图形
• ❌ 赛博风、暗黑科技风、AI 风格 UI
• ❌ UI 文案中使用 emoji

后台系统（默认风格）

要素	要求
主题	使用组件库默认主题
配色	黑白灰为主 + 1 个主色点缀
动效	克制，仅保留必要交互反馈

---

技术栈

层级	Vue（首选）	React（备选）
框架	Vue 3 + TypeScript	React 18 + TypeScript
构建	Vite	Vite
路由	Vue Router 4	React Router 6
状态	Pinia	Zustand
UI 库	Element Plus	Ant Design

---

Vue 编码规范

组件基础

<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'
import type { User } from '@/types'

// Props & Emits
const props = defineProps<{ userId: number }>()
const emit = defineEmits<{ (e: 'update', value: string): void }>()

// 响应式状态
const loading = ref(false)
const user = ref<User | null>(null)

// 计算属性
const displayName = computed(() => user.value?.name ?? '未知用户')

// 生命周期
onMounted(async () => { await fetchUser() })

// 方法
async function fetchUser() {
  loading.value = true
  try {
    user.value = await api.getUser(props.userId)
  } finally {
    loading.value = false
  }
}
</script>

<template>
  <div class="user-card">
    <h3>{{ displayName }}</h3>
  </div>
</template>

<style scoped>
.user-card { padding: 16px; }
</style>

命名约定

类型	约定	示例
组件文件	PascalCase.vue	UserCard.vue
Composables	useXxx.ts	useAuth.ts
Store	useXxxStore.ts	useUserStore.ts

---

状态管理（Pinia）

// stores/user.ts
export const useUserStore = defineStore('user', () => {
  const user = ref<User | null>(null)
  const token = ref<string>('')

  const isLoggedIn = computed(() => !!token.value)

  async function login(username: string, password: string) {
    const res = await api.login(username, password)
    token.value = res.token
    user.value = res.user
  }

  return { user, token, isLoggedIn, login }
})

---

交互状态处理

必须处理的状态: loading、empty、error、disabled、submitting

<template>
  <el-skeleton v-if="loading" :rows="5" animated />
  <el-result v-else-if="error" icon="error" :title="error">
    <template #extra>
      <el-button @click="fetchData">重试</el-button>
    </template>
  </el-result>
  <el-empty v-else-if="list.length === 0" description="暂无数据" />
  <template v-else>
    <!-- 正常内容 -->
  </template>
</template>

---

TypeScript 规范

// types/user.ts
export interface User {
  id: number
  username: string
  role: 'admin' | 'user'
}

export interface ApiResponse<T = unknown> {
  code: number
  message: string
  data: T
}

---

API 调用类型安全

规则	说明
✅ API 工具函数支持泛型	get<T>(url): Promise<T> 而非返回 unknown
✅ 调用处指定泛型或断言	get<UserInfo>(url) 或 data as typeof ref.value
❌ 禁止 as any 绕过	掩盖类型问题，后续维护踩坑

// ❌ get() 返回 unknown，赋值报 TS2322
const data = await get('/contact/config')
contact.value = data

// ❌ as any 绕过
contact.value = data as any

// ✅ 泛型约束（推荐）
const data = await get<ContactConfig>('/contact/config')
contact.value = data

// ✅ 类型断言（最小改动）
contact.value = data as typeof contact.value

---

性能优化

场景	方案
大列表	虚拟滚动
路由	懒加载 () => import()
计算	使用 computed 缓存
大数据	使用 shallowRef

// 路由懒加载
const routes = [
  { path: '/dashboard', component: () => import('@/views/Dashboard.vue') }
]

// 请求防抖
import { useDebounceFn } from '@vueuse/core'
const debouncedSearch = useDebounceFn((keyword) => api.search(keyword), 300)

---

目录结构

src/
├── assets/
│   └── styles/          # 全局/共享样式
├── api/                 # API 请求
├── components/          # 通用组件
├── composables/         # 组合式函数
├── router/              # 路由配置
├── stores/              # Pinia stores
├── types/               # TypeScript 类型
├── utils/               # 工具函数
├── views/               # 页面组件
├── App.vue
└── main.ts

---

样式管理规范

规则	说明
❌ 禁止在 .vue 中写大段样式	<style> 块不超过 20 行
❌ 禁止在 .tsx 中写大段内联样式	样式对象/CSS-in-JS 不超过 20 行
✅ 共享样式抽到 src/assets/styles/	按模块拆分文件
✅ 组件内只保留极简样式	Vue: scoped 微调；React: className 引用

src/assets/styles/
├── variables.scss       # 变量（颜色、间距、字号）
├── common.scss          # 通用样式
└── [module].scss        # 按模块拆分

---

请求体完整性规范

规则	说明
❌ 禁止 UI 可选字段未传入 API	用户选择/输入的字段必须全部传入请求体
✅ 提交函数与表单字段一一对应	用 TypeScript interface 约束请求体

// ❌ UI 有支付方式选择器，但请求体没传 payMethod
const payMethod = ref<'wechat' | 'points' | 'mixed'>('wechat')

async function createOrder() {
  await api.createOrder({
    items: orderItems.value,
    addressId: selectedAddress.value.id,
    // payMethod 忘记传了！支付方式选择 UI 形同虚设
  })
}

// ✅ 请求体与 UI 表单字段对应
interface CreateOrderRequest {
  items: OrderItem[]
  addressId: number
  payMethod: 'wechat' | 'points' | 'mixed'  // 类型约束确保不遗漏
}

async function createOrder() {
  const request: CreateOrderRequest = {
    items: orderItems.value,
    addressId: selectedAddress.value.id,
    payMethod: payMethod.value,  // TypeScript 会提示缺少字段
  }
  await api.createOrder(request)
}

---

API 错误处理规范

规则	说明
❌ 禁止静默忽略非成功响应	res.code !== 200 时必须提示用户
✅ 统一错误提示	非成功响应统一 message.error 提示
✅ 网络异常也要处理	try/catch 捕获请求异常

// ❌ 只处理成功，非 200 静默忽略
const res = await api.getList(params)
if (res.code === 200) {
  list.value = res.data
}

// ✅ 成功 + 失败都处理
try {
  const res = await api.getList(params)
  if (res.code === 200) {
    list.value = res.data
  } else {
    message.error(res.message || '加载失败')
  }
} catch (e) {
  message.error('网络异常，请稍后重试')
}

---

类型复用规范

规则	说明
❌ 禁止多个文件重复定义相同接口	PageResponse、BaseResult 等
✅ 通用类型统一放 @/types/common.ts	全局导出，各处引用

// ❌ 每个 api 文件都定义一遍
// api/user.ts
interface PageResponse<T> { list: T[]; total: number }
// api/order.ts
interface PageResponse<T> { list: T[]; total: number } // 重复

// ✅ 统一定义，各处引用
// types/common.ts
export interface PageResponse<T> {
  list: T[]
  total: number
}

// api/user.ts
import type { PageResponse } from '@/types/common'

---

详细参考

文件	内容
references/frontend-style.md	UI 风格、Vue 3 规范、Pinia、API 封装、性能优化
references/miniapp-pitfalls.md	uni-app 陷阱：页面栈只读、Storage 清理时机、生命周期双触发、前端校验镜像
references/date-time.md	dayjs/date-fns 日期加减、账期计算、禁止月末对齐

---

📋 本回复遵循：frontend-dev - [具体章节]