签入版本
This commit is contained in:
小蚂蚁云
@@ -1,142 +1,64 @@
|
||||
# 12.7 前端编码规范
|
||||
# 12.9 前端编码规范
|
||||
|
||||
:::tip 概述
|
||||
前端编码规范涵盖 Vue 组件、TypeScript、API 模块、样式和代码风格等方面。
|
||||
:::tip 建议遵守
|
||||
前端通用风格约定：分层隔离、命名一致、组件复用、类型渐进。配合 `pnpm type:check` 与 `pnpm lint:eslint` 门禁。
|
||||
:::
|
||||
|
||||
## Vue 组件规范
|
||||
## 分层纪律
|
||||
|
||||
```vue
|
||||
<!-- 推荐的组件结构 -->
|
||||
<template>
|
||||
<!-- 模板内容 -->
|
||||
</template>
|
||||
| 层 | 禁止 |
|
||||
|---|---|
|
||||
| views 页面 | 直接 axios、写信封判断、放公共组件 |
|
||||
| api 模块 | UI 逻辑、持 Token、catch 兜底（拦截器已做） |
|
||||
| components 公共组件 | 耦合具体业务模块 |
|
||||
| store | 存可从接口推导的数据 |
|
||||
| utils | import api/views/store（环依赖） |
|
||||
|
||||
<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: '',
|
||||
});
|
||||
| 对象 | 规约 | 示例 |
|
||||
|---|---|---|
|
||||
| api 文件 | 域/模块.ts | system/user.ts |
|
||||
| api 函数 | 模块+动作 | userPage、userAdd |
|
||||
| 页面目录 | 域/模块/ | views/system/user/ |
|
||||
| 组件 | PascalCase | UserTable.vue |
|
||||
| hooks | use-*.ts | use-async.ts |
|
||||
| store | camelCase 模块 | asyncRoute.ts |
|
||||
| 权限码 | 与后端逐字一致 | sys:user:add |
|
||||
|
||||
// 响应式数据
|
||||
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;
|
||||
}
|
||||
};
|
||||
- 公共组件优先（Table/Page/Form/Select/Upload...），不重复造
|
||||
- 页面私有组件放 views 下 components/
|
||||
- props 显式声明 + 类型（vue-types/propTypes）
|
||||
- 事件命名 `update:xxx` / `change`，不滥用全局事件总线
|
||||
|
||||
// 生命周期
|
||||
onMounted(() => fetchData());
|
||||
</script>
|
||||
## 状态与数据
|
||||
|
||||
<style scoped>
|
||||
/* 组件样式 */
|
||||
</style>
|
||||
```
|
||||
- 本地状态 ref/reactive；跨页面才进 Pinia
|
||||
- storage 键走 mutation-types 常量，不散裸字符串
|
||||
- 字典数据走字典接口，不硬编码 options
|
||||
|
||||
## TypeScript 规范
|
||||
## 样式
|
||||
|
||||
```typescript
|
||||
// 接口定义
|
||||
interface User {
|
||||
id: number;
|
||||
username: string;
|
||||
realname: string;
|
||||
status: number;
|
||||
}
|
||||
- 颜色/间距用变量，不硬编码色值
|
||||
- 组件样式 scoped；全局样式进 styles/ 统一管理
|
||||
- 避免 `!important`；层级用变量
|
||||
|
||||
// 枚举定义
|
||||
enum UserStatus {
|
||||
ENABLE = 1,
|
||||
DISABLE = 2,
|
||||
}
|
||||
## 类型
|
||||
|
||||
// API 响应类型
|
||||
interface PageResult<T> {
|
||||
records: T[];
|
||||
total: number;
|
||||
size: number;
|
||||
current: number;
|
||||
pages: number;
|
||||
}
|
||||
- 渐进式补类型：api 泛型 → props → 页面
|
||||
- 枚举用 as const + 类型导出
|
||||
- 临时 any 需注释原因，不扩散
|
||||
|
||||
// Props 类型
|
||||
interface TableProps {
|
||||
data: any[];
|
||||
loading?: boolean;
|
||||
columns: Column[];
|
||||
}
|
||||
```
|
||||
|
||||
## API 模块规范
|
||||
|
||||
```typescript
|
||||
// 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' });
|
||||
}
|
||||
```
|
||||
|
||||
## 命名规范
|
||||
|
||||
| 类型 | 规范 | 示例 |
|
||||
|------|------|------|
|
||||
| 组件文件 | PascalCase | `BasicTable.vue` |
|
||||
| API 文件 | camelCase | `user.ts` |
|
||||
| API 函数 | camelCase | `getUserPage` |
|
||||
| Store 文件 | camelCase | `user.ts` |
|
||||
| 常量 | UPPER_SNAKE_CASE | `ACCESS_TOKEN` |
|
||||
| CSS 类 | kebab-case | `page-container` |
|
||||
|
||||
## 代码风格
|
||||
## 提交前
|
||||
|
||||
```bash
|
||||
# ESLint 检查
|
||||
pnpm type:check
|
||||
pnpm lint:eslint
|
||||
|
||||
# Prettier 格式化
|
||||
pnpm lint:prettier
|
||||
|
||||
# Stylelint 检查
|
||||
pnpm lint:stylelint
|
||||
```
|
||||
|
||||
:::warning 禁止事项
|
||||
- 不要使用 `any` 类型（除非确实无法确定类型）
|
||||
- 不要使用 `console.log`（生产环境）
|
||||
- 不要在模板中写复杂逻辑（提取为 computed 或方法）
|
||||
- 不要在 `setup` 外使用 Composition API
|
||||
:::
|
||||
## 相关
|
||||
|
||||
- [9.14 API 模块编写规范](/zh/frontend/api-module.html)
|
||||
- [12.7 代码审查清单](/zh/standards/code-review.html)
|
||||
|
||||
Reference in New Issue
Block a user