从混沌到秩序：SmartAdmin代码规范与最佳实践全解析
项目地址: https://gitcode.com/lab1024/smart-admin 为什么代码规范比你想象的更重要？
当团队规模从3人扩张到30人，当项目迭代超过50个版本，当线上故障因为一个未规范的变量命名而爆发——你才会真正理解：代码规范不是束缚，而是团队协作的"通用语言"。SmartAdmin作为国内首个以"高质量代码"为核心的中后台开发平台，其代码规范体系历经10年实战打磨，已形成一套兼顾"开发效率"与"系统安全"的双重标准。
读完本文你将掌握：
- 3大维度代码规范（命名/结构/安全）的落地技巧
- 15个前端工程化最佳实践的具体实现
- 5类常见反模式的识别与重构方法
- 基于TypeScript的类型安全保障体系
- 符合国家三级等保要求的代码编写指南
一、命名规范：让代码自己说话
1.1 变量命名的黄金法则
SmartAdmin采用语义化命名三要素：{范围}_{类型}_{描述}，确保变量含义一目了然：
// 👍 推荐：清晰表达变量作用域、类型和业务含义
const userToken: string = localRead(LocalStorageKeyConst.USER_TOKEN);
const employeeList: EmployeeVO[] = [];
// 👎 避免：无意义缩写和单字母变量
const ut = localStorage.getItem('tk'); // 无法直观理解含义
const data = []; // 类型和用途不明确
1.2 常量命名的枚举化实践
系统常量统一使用TypeScript枚举（Enum） 管理，在constants目录下按业务域划分：
// src/constants/system/menu-const.ts
export const MENU_TYPE_ENUM: SmartEnum<number> = {
DIRECTORY: { value: 1, desc: '目录' },
MENU: { value: 2, desc: '菜单' },
BUTTON: { value: 3, desc: '按钮' },
EXTLINK: { value: 4, desc: '外链' }
};
// 使用时获得类型提示和自动补全
if (menu.type === MENU_TYPE_ENUM.BUTTON.value) {
// 处理按钮类型菜单
}
优势：
- 避免魔法数字（如
if(type === 2)） - 提供编译时类型检查
- 统一管理业务状态码和字典值
1.3 文件与目录命名规范
| 文件类型 | 命名规则 | 示例 |
|---|---|---|
| 组件文件 | PascalCase | SideMenu.vue |
| 工具函数 | camelCase | strUtil.ts |
| 常量文件 | kebab-case | menu-const.ts |
| API接口 | kebab-case | employee-api.ts |
| 目录 | kebab-case | components/framework/ |
二、项目结构：模块化与领域驱动设计
2.1 前端项目结构全景图
SmartAdmin采用领域驱动的目录划分方式，将业务逻辑与技术实现分离：
src/
├── api/ # API接口按领域划分
│ ├── system/ # 系统管理领域
│ ├── business/ # 业务功能领域
│ └── support/ # 支撑服务领域
├── components/ # 组件库
│ ├── framework/ # 框架组件
│ ├── system/ # 系统组件
│ └── business/ # 业务组件
├── constants/ # 常量定义
├── store/ # 状态管理
├── router/ # 路由配置
├── theme/ # 主题样式
└── utils/ # 工具函数
2.2 组件设计的单一职责原则
每个组件只负责一个功能，通过组合而非继承扩展功能：
<!-- 👍 推荐：专注于文件上传单一功能 -->
<template>
<a-upload
:action="uploadUrl"
:headers="headers"
:fileList="fileList"
@change="handleChange"
>
<a-button>点击上传</a-button>
</a-upload>
</template>
<script setup lang="ts">
// 仅包含文件上传相关逻辑
import { ref } from 'vue';
import { getToken } from '/@/utils/auth';
const fileList = ref([]);
const uploadUrl = import.meta.env.VITE_APP_API_URL + '/support/file/upload';
</script>
三、安全编码：符合国家三级等保要求
3.1 接口数据加密传输实现
SmartAdmin实现请求/响应双向加密机制，敏感数据自动加密：
// src/lib/axios.ts 加密请求实现
export const postEncryptRequest = (url, data) => {
return request({
data: { encryptData: encryptData(data) }, // 使用国密算法加密
url,
method: 'post',
});
};
// 响应自动解密
if (response.data.dataType === DATA_TYPE_ENUM.ENCRYPT.value) {
response.data.encryptData = response.data.data;
let decryptStr = decryptData(response.data.data); // 国密SM4解密
if (decryptStr) {
response.data.data = JSON.parse(decryptStr);
}
}
3.2 权限控制的三重校验
系统实现页面/按钮/数据三级权限控制，杜绝越权访问：
// src/plugins/privilege-plugin.ts
const privilege = (value: string) => {
// 1. 超级管理员拥有全部权限
if (useUserStore().administratorFlag) return true;
// 2. 功能点权限校验
let userPointsList = useUserStore().getPointList;
return _.some(userPointsList, ['webPerms', value]);
};
// 组件中使用
<template>
<a-button v-if="$privilege('system:user:add')">新增用户</a-button>
</template>
3.3 防SQL注入与XSS攻击
通过参数化查询和输入过滤保障数据安全：
// 👍 推荐：使用参数化查询
const getUser = (id: number) => {
return userMapper.selectById(id); // MyBatis-Plus自动参数化
};
// 避免：字符串拼接SQL
const sql = `SELECT * FROM user WHERE id = ${id}`; // 存在注入风险
四、TypeScript类型安全实践
4.1 接口响应类型定义
所有API响应使用泛型接口定义，确保类型安全：
// src/api/base-model/response-model.ts
export interface ResponseModel<T = any> {
code: number;
msg: string;
data: T;
dataType?: number;
}
// 使用示例
export const getEmployeeList = (params: PageParamModel): Promise<ResponseModel<PageResultModel<EmployeeVO>>> => {
return getRequest('/system/employee/page', params);
};
4.2 业务模型的类型化
核心业务对象使用TypeScript接口明确定义：
// src/api/system/employee-api.ts
export interface EmployeeVO {
id: number;
employeeName: string;
employeeNo: string;
departmentId: number;
departmentName?: string;
positionId: number;
positionName?: string;
// 更多字段...
}
五、工程化最佳实践
5.1 统一错误处理机制
通过Axios拦截器实现全局错误处理：
// src/lib/axios.ts
smartAxios.interceptors.response.use(
(response) => {
const res = response.data;
if (res.code && res.code !== 1) {
// 统一错误提示
message.error(res.msg);
// 30008: Token过期 30012: 长时间未操作
if ([30008, 30012].includes(res.code)) {
Modal.error({
title: '会话超时',
content: '您的登录已过期，请重新登录',
onOk: () => useUserStore().logout()
});
}
return Promise.reject(res);
}
return res;
},
(error) => {
message.error('网络错误: ' + error.message);
return Promise.reject(error);
}
);
5.2 环境变量管理
使用Vite环境变量区分开发/测试/生产环境：
// .env.development
VITE_APP_API_URL = '/api'
VITE_APP_ENV = 'development'
// .env.production
VITE_APP_API_URL = 'https://api.smartadmin.com'
VITE_APP_ENV = 'production'
// 代码中使用
const apiUrl = import.meta.env.VITE_APP_API_URL;
5.3 主题定制与样式规范
采用CSS-in-JS结合主题变量实现样式统一管理：
// src/theme/custom-variables.ts
export const themeVariables = {
primaryColor: '#1677ff',
successColor: '#52c41a',
warningColor: '#faad14',
errorColor: '#ff4d4f',
// 更多主题变量...
};
// 在组件中使用
import { themeVariables } from '/@/theme/custom-variables';
const useStyles = createStyles((theme) => ({
button: {
backgroundColor: themeVariables.primaryColor,
'&:hover': {
backgroundColor: themeVariables.primaryColor + 'cc',
},
},
}));
六、常见反模式与重构方案
6.1 反模式：全局变量污染
问题：在window对象上挂载全局变量
// 👎 不推荐
window.globalData = {
userInfo: null,
permissions: []
};
重构方案：使用Pinia状态管理
// 👍 推荐
// src/store/modules/system/user.ts
export const useUserStore = defineStore('systemUser', {
state: () => ({
userInfo: null as UserInfoVO | null,
permissions: [] as string[]
}),
actions: {
setUserInfo(info: UserInfoVO) {
this.userInfo = info;
}
}
});
6.2 反模式：冗长条件判断
问题：复杂的if-else嵌套
// 👎 不推荐
if (status === 1) {
if (type === 'add') {
handleAdd();
} else if (type === 'edit') {
handleEdit();
}
} else if (status === 2) {
// ...
}
重构方案：使用策略模式
// 👍 推荐
const actionMap = {
'1_add': handleAdd,
'1_edit': handleEdit,
'2_view': handleView,
// 其他组合...
};
const key = `${status}_${type}`;
if (actionMap[key]) {
actionMap[key]();
}
七、代码规范的自动化保障
7.1 ESLint与Prettier配置
项目集成ESLint和Prettier实现代码风格自动检查：
// .eslintrc.js
module.exports = {
root: true,
env: {
browser: true,
es2021: true,
node: true
},
extends: [
'plugin:vue/vue3-essential',
'eslint:recommended',
'@vue/typescript/recommended',
'prettier'
],
rules: {
'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'@typescript-eslint/explicit-module-boundary-types': 'error'
}
};
7.2 Git提交规范与钩子
使用husky和commitlint确保提交信息规范：
// package.json
{
"husky": {
"hooks": {
"pre-commit": "lint-staged",
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
},
"lint-staged": {
"*.{ts,tsx,vue}": ["eslint --fix", "prettier --write"]
}
}
提交信息格式：type(scope): subject
# 示例
feat(login): 增加图形验证码功能
fix(dashboard): 修复数据统计异常问题
docs: 更新API文档
八、总结与实践建议
SmartAdmin的代码规范体系不是一蹴而就的，而是通过"规范-实践-反馈-优化"的循环不断完善。对于团队落地建议：
- 渐进式推行：先从命名规范和文件结构入手，再逐步扩展到安全和性能
- 自动化优先：尽量通过工具而非人工检查规范执行情况
- 案例教学：定期分享团队中的规范正反案例
- 持续优化：每季度回顾规范执行情况，根据业务发展调整
记住：最好的规范是团队成员都能理解并愿意遵守的规范。SmartAdmin提供的不仅是一套代码标准，更是一种高效协作的开发文化。
本文档将随SmartAdmin版本持续更新，最新规范请参考官方文档。如有建议或发现问题，欢迎提交Issue或PR参与共建。
附录：规范速查表
| 规范类型 | 核心要点 | 示例 |
|---|---|---|
| 命名规范 | 变量camelCase，常量UPPER_SNAKE_CASE | userName，MAX_RETRY_COUNT |
| 文件组织 | 按领域划分，功能内聚 | api/system/employee-api.ts |
| 安全编码 | 输入验证，输出编码，最小权限 | 参数化查询，XSS过滤 |
| 性能优化 | 懒加载，缓存复用，减少重绘 | 路由懒加载，组件缓存 |
| 错误处理 | 统一捕获，分类处理，友好提示 | Axios全局拦截器 |
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
