Cursor AI 开发规范（通用版）
通用项目规范文档：
# Cursor AI 开发规范（通用版）
## 响应规则
- 回答简洁直接，避免不必要解释
- 代码示例仅关键部分
- 使用缩写和简写
- 避免重复信息
- 优先 bullet points
- 直接回答核心问题
- 避免客套话
- 使用短语非完整句子
- 列表展示多项内容
## 格式规则
- 最大响应：300 tokens
- 代码注释仅复杂逻辑
- 避免过度 Markdown 格式化
- 代码引用使用行号格式：`12:15:path/file.ts`
- 仅展示修改部分，使用 `...` 省略无关代码
- 避免完整文件输出
## 工具调用优化
- 避免不必要的文件读取
- 优先使用 grep 搜索而非全文读取
- 批量调用独立工具
- 不重复读取已知内容
- 搜索前明确目标
- 使用文件类型过滤提高效率
## 代码展示规则
- 仅展示修改部分
- 使用 `...` 省略无关代码
- 避免完整文件输出
- 关键行号引用格式：`12:15:path/file.ts`
- 新代码使用标准代码块（带语言标识）
- 现有代码使用行号引用格式
## 禁止操作
- 不生成长文档
- 不输出完整配置文件内容
- 不重复用户已知信息
- 不做冗余确认
- 不输出 ASCII art/表格（除非必要）
- 不修改未明确要求修改的文件
## 验证规则生效
每次回答末尾显示：`✓ 规则生效 | Tokens: ~XXX`
---
## 通用代码规范
### 命名规范
- **变量/函数**：camelCase (`getUserInfo`)
- **常量**：UPPER_SNAKE_CASE (`MAX_COUNT`)
- **类/组件**：PascalCase (`UserProfile`)
- **文件/目录**：kebab-case (`user-profile.ts`) 或 camelCase (`userProfile.ts`)
- **CSS 类名**：kebab-case 或 BEM (`block__element--modifier`)
### 代码风格
- 单引号或双引号保持一致
- 行尾分号保持一致
- 缩进：2 空格或 4 空格（项目统一）
- 行宽：80/100/120 字符（项目统一）
- 尾随逗号：多行对象/数组使用
### 注释规范
- 复杂逻辑必须注释
- 函数使用 JSDoc/TSDoc
- 避免冗余注释
- 注释与代码同步更新
---
## 前端框架规范
### Vue 3
- 优先使用 Composition API
- `<script setup>` 语法糖
- Props 类型定义完整
- 响应式数据合理使用 `ref`/`reactive`
- 生命周期钩子正确使用
- 组件卸载时清理副作用
### React
- 函数组件优先
- Hooks 正确使用（依赖数组）
- Props 类型定义（TypeScript/PropTypes）
- 避免不必要的重渲染
- 清理副作用（useEffect return）
### 通用原则
- 组件单一职责
- Props 向下，Events 向上
- 状态提升合理
- 避免过度嵌套
---
## TypeScript 规范
### 类型定义
- 优先使用 `interface`（扩展性）
- 工具类型使用 `type`
- 避免 `any`，使用 `unknown` 或具体类型
- 函数参数和返回值类型明确
### 类型使用
```typescript
// ✅ 好的实践
interface User {
id: number
name: string
}
function getUser(id: number): Promise<User> {
// ...
}
// ❌ 避免
function getUser(id: any): any {
// ...
}
组件开发规范
组件结构
- Props 定义清晰
- 状态管理合理
- 副作用处理完善
- 错误处理到位
- 可访问性考虑（a11y）
组件通信
- 父子：Props + Events/Callbacks
- 跨组件：Context/Store/EventBus
- 全局状态：状态管理库
组件复用
- 提取公共逻辑为 Hooks/Composables
- 通用 UI 组件化
- 避免重复代码
API 调用规范
请求封装
- 统一 HTTP 客户端封装
- 请求/响应拦截器
- 错误统一处理
- Loading 状态管理
数据获取
- 使用 Hooks/Composables 封装
- 缓存策略合理
- 错误重试机制
- 取消请求处理
错误处理
- 统一错误提示
- 错误日志记录
- 用户友好提示
状态管理规范
Store 设计
- 单一数据源
- 不可变更新
- Actions 处理异步
- Getters 计算派生状态
使用原则
- 避免过度使用全局状态
- 组件本地状态优先
- Store 模块化拆分
样式规范
CSS 预处理器
- SCSS/SASS/Less 使用规范
- 变量和混入合理使用
- 嵌套不超过 3 层
命名规范
- BEM：
block__element--modifier - 或 kebab-case：
component-name - 避免全局样式污染
响应式设计
- 移动端优先
- 断点合理设置
- 弹性布局使用
性能优化规范
代码分割
- 路由懒加载
- 组件按需加载
- 第三方库单独打包
资源优化
- 图片压缩和懒加载
- 字体子集化
- 资源 CDN 使用
渲染优化
- 虚拟列表（大数据）
- 防抖节流
- 避免不必要的重渲染
- 使用 memo/useMemo/useCallback
性能指标
- 首屏加载 < 3s
- 交互响应 < 100ms
- 长任务 < 50ms
测试规范
单元测试
- 核心逻辑覆盖
- 边界情况测试
- Mock 外部依赖
集成测试
- 关键流程覆盖
- 用户场景模拟
E2E 测试
- 核心业务流程
- 跨浏览器测试
安全规范
输入验证
- 用户输入验证
- XSS 防护
- SQL 注入防护（后端）
数据安全
- 敏感信息加密
- HTTPS 使用
- Token 安全存储
代码安全
- 避免
eval、innerHTML - 依赖包安全检查
- 环境变量不提交
工具函数规范
工具库使用
- 优先使用成熟库（lodash、date-fns 等）
- 避免重复造轮子
- 单一职责原则
自定义工具
- 通用工具函数化
- 类型定义完整
- 文档注释清晰
- 单元测试覆盖
Git 规范
提交格式
<type>(<scope>): <subject>
<body>
<footer>
提交类型
feat: 新功能fix: 修复 bugrefactor: 重构style: 样式调整chore: 构建/工具变更docs: 文档更新perf: 性能优化test: 测试相关
分支规范
main/master: 主分支develop: 开发分支feature/xxx: 功能分支fix/xxx: 修复分支hotfix/xxx: 热修复分支
提交信息
- 清晰简洁
- 使用中文或英文（项目统一）
- 说明修改原因和影响
代码审查要点
必须检查
建议检查
文档规范
代码文档
- README 清晰
- API 文档完整
- 变更日志维护
- 注释清晰
技术文档
- 架构设计文档
- 开发指南
- 部署文档
- 故障排查文档
环境配置
开发环境
- Node.js 版本统一
- 包管理器统一（npm/yarn/pnpm）
- 编辑器配置（.editorconfig）
- 代码格式化（Prettier）
构建配置
- 环境变量管理
- 构建优化配置
- 多环境支持
禁止事项
- ❌ 生产代码禁止
console.log - ❌ 禁止使用
eval、innerHTML（XSS 风险） - ❌ 禁止硬编码配置
- ❌ 禁止提交敏感信息
- ❌ 禁止使用
any类型（TypeScript） - ❌ 禁止直接操作 DOM（框架场景）
- ❌ 禁止提交包含 TODO/FIXME 的代码（除非必要）
最佳实践
代码质量
- 保持代码简洁
- 遵循 SOLID 原则
- DRY（Don't Repeat Yourself）
- KISS（Keep It Simple, Stupid）
开发流程
- 功能分支开发
- 代码审查必须
- 自动化测试
- 持续集成/部署
团队协作
- 代码规范统一
- 定期 Code Review
- 知识分享
- 技术债务管理
参考资源
这份通用规范涵盖：
- 响应与格式规则
- 通用代码与命名规范
- 前端框架通用原则（Vue/React）
- TypeScript、组件、API、状态管理规范
- 样式、性能、测试、安全规范
- 工具函数、Git、文档规范
- 环境配置、禁止事项、最佳实践
适用于大多数前端项目，不绑定特定技术栈。
浙公网安备 33010602011771号