外观
峰云CMS 项目开发规范
本文档是峰云CMS全栈项目的快速开发参考指南，适用于所有参与项目开发的 AI 助手和开发人员。
核心原则
- 类型安全优先：严格遵循 TypeScript 类型约束，前后端接口类型必须一致
- 框架规范遵循：遵循项目现有的架构模式和代码规范
- 代码质量约束：确保代码符合 ESLint 与 TS 编译检查要求
- 性能与安全：考虑 XSS/CSRF 防护、SQL 注入等安全漏洞
技术栈概览
前端技术栈
- 核心框架：Vue 3.5+ (Composition API)
- UI 组件库：Element Plus 2.10+
- 状态管理：Pinia 3.0+ (支持持久化)
- 路由管理：Vue Router 4.5+
- HTTP 请求：Axios 1.7+
- 构建工具：Vite 6.3+
- 类型检查：TypeScript 5.8+
后端技术栈
- 运行环境：Node.js 22.18.0+ (原生支持 TypeScript)
- Web 框架：Express.js 4.21+
- 数据库：MySQL/MariaDB
- ORM/查询构建器：Knex.js 3.1+
- 参数验证：Zod 3.25+
- 身份认证：JWT + express-session
全栈框架
- SSR/SSG 框架：Nuxt 4.2+
- 模板引擎：EJS 3.1+
- 文档站点：VitePress 2.0+
快速开发指南
TypeScript 关键规范
类型导入
typescript
// ✅ 正确：类型导入使用 type 关键字
import { ElMessage, type FormInstance } from "element-plus";
import { getUserInfo } from "#services/user";
// ❌ 错误
import { ElMessage, FormInstance } from "element-plus";
import * as UserService from "#services/user";1
2
3
4
5
6
7
2
3
4
5
6
7
类型命名规范
- 接口参数类型：
ParamsApi*(如ParamsApiGetUserInfo) - 接口返回类型：
ReturnApi*(如ReturnApiGetUserInfo) - 列表项类型：
*ListItem(如UserListItem) - 服务层函数返回：
TReturn<T>(如[Error | null, T | undefined])
Vue 组件开发规范
vue
<script setup lang="ts">
interface Props {
title: string;
count?: number;
}
interface Emits {
update: [value: number];
delete: [id: number];
}
const props = withDefaults(defineProps<Props>(), {
count: 0,
});
const emit = defineEmits<Emits>();
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
后端控制器规范
typescript
// 控制器函数名以 c 开头
export const cGetUserInfo: ExpressRequestHandler = async (req, res, next) => {
try {
const data: ParamsApiGetUserInfo = sGetUserInfo.parse(req.query);
const [err, result] = await getUserInfo(data);
if (err) {
res.fail(err.message);
return;
}
res.success<ReturnApiGetUserInfo>(result);
} catch (err) {
next(err);
}
};1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
参数验证规范
typescript
// Schema 命名以 s 开头
export const sGetUserInfo = zod.object({
id: zod.coerce.number().int().positive("用户ID必须为正整数"),
name: zod.string().optional(),
});1
2
3
4
5
2
3
4
5
数据库查询规范
typescript
// 分页查询：列表查询和计数查询分开执行
const [list, totalResult] = await Promise.all([
query.clone().limit(limit).offset(offset),
query.clone().clearSelect().count("id as count").first(),
]);1
2
3
4
5
2
3
4
5
开发环境
环境要求
- Node.js v22.18.0+ (原生支持 TypeScript)
- MySQL/MariaDB 数据库
快速启动
bash
# 集成环境开发
npm run dev:int
# 预发布环境开发
npm run dev:pre
# 生产环境开发
npm run dev:production1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
所有服务通过 9000 端口代理，避免跨域问题。
代码检查
bash
# 执行代码检查和格式化
npm run lint1
2
2
数据库迁移
bash
# 运行数据库迁移
cross-env MODE=int NODE_ENV=production npx knex migrate:latest --knexfile knexfile.mts --env production1
2
2
代码质量约束
- 函数长度 ≤ 50 行
- 组件 Props ≤ 10 个
- 路由层级 ≤ 3 层
- 前端首屏 JS ≤ 200KB
- 接口响应时间 ≤ 2 秒