12.7 前端编码规范

:::tip 概述前端编码规范涵盖 Vue 组件、TypeScript、API 模块、样式和代码风格等方面。前端工程位于 ui/ 目录（Vue3 + TypeScript + ElementPlus + Pinia）。 :::

Vue 组件规范

<!-- 推荐的组件结构 -->
<template>
  <!-- 模板内容 -->
</template>

<script setup lang="ts">
// 使用 <script setup lang="ts"> 语法
import { ref, onMounted } from 'vue';

// Props 定义
interface Props {
  id: number;
  name?: string;
}
const props = withDefaults(defineProps<Props>(), {
  name: '',
});

// 响应式数据
const loading = ref(false);
const tableData = ref<any[]>([]);

// 方法
const fetchData = async () => {
  loading.value = true;
  try {
    const res = await getExamplePage({ pageNo: 1, pageSize: 20 });
    tableData.value = res.records;
  } finally {
    loading.value = false;
  }
};

// 生命周期
onMounted(() => fetchData());
</script>

<style scoped>
/* 组件样式 */
</style>

TypeScript 规范

// 接口定义
interface User {
  id: number;
  username: string;
  realname: string;
  status: number;
}

// 枚举定义（统一放 ui/src/enums/ 下，如 pageEnum.ts、httpEnum.ts）
enum UserStatus {
  ENABLE = 1,
  DISABLE = 2,
}

// API 响应类型（分页结构见 12.1/12.2）
interface PageResult<T> {
  records: T[];
  total: number;
  size: number;
  current: number;
  pages: number;
}

// Props 类型
interface TableProps {
  data: any[];
  loading?: boolean;
  columns: Column[];
}

API 模块规范

// ui/src/api/system/user.ts
import { http } from '@/utils/http/axios';

// 查询用 GET + params
export function getUserPage(params?: Record<string, any>) {
  return http.request({ url: '/user/page', method: 'GET', params });
}

// 新增用 POST + data
export function userAdd(data: any) {
  return http.request({ url: '/user/add', method: 'POST', data });
}

// 修改用 PUT + data
export function userUpdate(data: any) {
  return http.request({ url: '/user/update', method: 'PUT', data });
}

// 删除用 DELETE
export function userDelete(id: number) {
  return http.request({ url: '/user/delete/' + id, method: 'DELETE' });
}

:::info 路径前缀 API 函数中 url 不带 /api 前缀——由 ui/.env.production 的 VITE_GLOB_API_URL_PREFIX=/api 在请求层统一拼接。 :::

命名规范

类型	规范	示例
组件文件	PascalCase	`BasicTable.vue`
API 文件	camelCase，按模块分目录（`ui/src/api/{模块}/`）	`system/user.ts`
API 函数	camelCase	`getUserPage`
Store 文件	camelCase（`ui/src/store/modules/`）	`user.ts`
枚举文件	camelCase + Enum 后缀（`ui/src/enums/`）	`pageEnum.ts`
常量	UPPER_SNAKE_CASE	`ACCESS_TOKEN`
CSS 类	kebab-case	`page-container`

代码风格

# ESLint 检查（脚本自带 --fix）
pnpm lint:eslint

# Prettier 格式化
pnpm lint:prettier

# Stylelint 检查
pnpm lint:stylelint

# TypeScript 类型检查
pnpm type:check

:::warning 禁止事项

不要使用 any 类型（除非确实无法确定类型）
不要使用 console.log（生产环境）
不要在模板中写复杂逻辑（提取为 computed 或方法）
不要在 setup 外使用 Composition API :::

3.2 KiB Raw Blame History Unescape Escape