Cursor 各类编程语言rules规则合集

MDC文件翻译集合

本文档包含了所有.mdc文件的中文翻译。每个文件的内容都以其原始文件名作为标题进行组织。

vue.mdc

Vue.js 最佳实践

组件结构

• 优先使用组合式API而非选项式API
• 保持组件小巧且专注
• 使用正确的TypeScript集成
• 实现适当的props验证
• 使用正确的emit声明
• 保持模板逻辑最小化

组合式API

• 正确使用ref和reactive
• 实现适当的生命周期钩子
• 使用组合式函数进行逻辑复用
• 保持setup函数整洁
• 正确使用计算属性
• 实现适当的侦听器

状态管理

• 使用Pinia进行状态管理
• 保持store模块化
• 使用正确的状态组合
• 实现适当的actions
• 正确使用getters
• 正确处理异步状态

性能

• 正确使用组件懒加载
• 实现适当的缓存
• 正确使用计算属性
• 避免不必要的侦听器
• 正确使用v-show vs v-if
• 实现适当的key管理

路由

• 正确使用Vue Router
• 实现适当的导航守卫
• 正确使用路由元字段
• 正确处理路由参数
• 实现适当的懒加载
• 使用正确的导航方法

表单

• 正确使用v-model
• 实现适当的验证
• 正确处理表单提交
• 显示适当的加载状态
• 使用正确的错误处理
• 实现适当的表单重置

TypeScript集成

• 使用正确的组件类型定义
• 实现适当的prop类型
• 使用正确的emit声明
• 处理正确的类型推断
• 使用正确的组合式函数类型
• 实现适当的store类型

测试

• 编写正确的单元测试
• 实现适当的组件测试
• 正确使用Vue Test Utils
• 正确测试组合式函数
• 实现适当的模拟
• 测试异步操作

最佳实践

• 遵循Vue风格指南
• 使用正确的命名约定
• 保持组件组织有序
• 实现适当的错误处理
• 使用正确的事件处理
• 为复杂逻辑编写文档

构建和工具

• 使用Vite进行开发
• 配置适当的构建设置
• 使用正确的环境变量
• 实现适当的代码分割
• 使用正确的资源处理
• 配置适当的优化

react.mdc

React 最佳实践

组件结构

• 优先使用函数组件而非类组件
• 保持组件小巧且专注
• 将可复用逻辑提取到自定义钩子中
• 使用组合而非继承
• 使用TypeScript实现适当的prop类型
• 将大型组件拆分成更小的、专注的组件

钩子

• 遵循Hooks规则
• 使用自定义钩子实现可复用逻辑
• 保持钩子专注且简单
• 在useEffect中使用适当的依赖数组
• 在需要时在useEffect中实现清理
• 避免嵌套钩子

状态管理

• 使用useState管理局部组件状态
• 使用useReducer处理复杂状态逻辑
• 使用Context API管理共享状态
• 将状态尽可能靠近使用它的地方
• 通过适当的状态管理避免prop钻取
• 仅在必要时使用状态管理库

性能

• 实现适当的记忆化(useMemo, useCallback)
• 对昂贵的组件使用React.memo
• 避免不必要的重渲染
• 实现适当的懒加载
• 在列表中正确使用key属性
• 分析和优化渲染性能

表单

• 对表单输入使用受控组件
• 实现适当的表单验证
• 正确处理表单提交状态
• 显示适当的加载和错误状态
• 对复杂表单使用表单库
• 实现表单的适当可访问性

错误处理

• 实现错误边界
• 正确处理异步错误
• 显示用户友好的错误消息
• 实现适当的后备UI
• 适当记录错误
• 优雅地处理边缘情况

测试

• 为组件编写单元测试
• 为复杂流程实现集成测试
• 使用React Testing Library
• 测试用户交互
• 测试错误场景
• 实现适当的模拟数据

可访问性

• 使用语义化HTML元素
• 实现适当的ARIA属性
• 确保键盘导航
• 使用屏幕阅读器测试
• 处理焦点管理
• 为图片提供适当的alt文本

代码组织

• 将相关组件组织在一起
• 使用适当的文件命名约定
• 实现适当的目录结构
• 将样式保持在组件附近
• 使用适当的导入/导出
• 为复杂的组件逻辑编写文档

svelte.mdc

Svelte 最佳实践

组件结构

• 保持组件小巧且专注
• 使用正确的TypeScript集成
• 实现适当的props类型定义
• 使用正确的事件分发
• 保持标记清晰可读
• 使用正确的插槽实现

响应式

• 使用正确的响应式声明
• 实现适当的存储
• 使用正确的响应式语句
• 正确处理派生值
• 使用正确的生命周期函数
• 实现适当的绑定

状态管理

• 使用正确的Svelte存储
• 保持存储模块化
• 使用正确的派生存储
• 实现适当的actions
• 正确处理异步状态
• 使用正确的存储订阅

性能

• 使用正确的组件懒加载
• 实现适当的过渡
• 使用正确的动画
• 避免不必要的响应式
• 使用正确的事件转发
• 实现适当的key块

路由

• 使用SvelteKit进行路由
• 实现适当的布局
• 使用正确的路由参数
• 正确处理加载状态
• 实现适当的错误页面
• 使用正确的导航方法

表单

• 使用正确的表单绑定
• 实现适当的验证
• 正确处理表单提交
• 显示适当的加载状态
• 使用正确的错误处理
• 实现适当的表单重置

TypeScript集成

• 使用正确的组件类型
• 实现适当的prop类型
• 使用正确的事件类型
• 处理正确的类型推断
• 使用正确的存储类型
• 实现适当的action类型

测试

• 编写正确的单元测试
• 实现适当的组件测试
• 使用正确的测试库
• 正确测试存储
• 实现适当的模拟
• 测试异步操作

最佳实践

• 遵循Svelte风格指南
• 使用正确的命名约定
• 保持组件组织有序
• 实现适当的错误处理
• 使用正确的事件处理
• 为复杂逻辑编写文档

构建和工具

• 使用Vite进行开发
• 配置适当的构建设置
• 使用正确的环境变量
• 实现适当的代码分割
• 使用正确的资源处理
• 配置适当的优化

tailwind.mdc

Tailwind CSS 最佳实践

项目设置

• 使用正确的Tailwind配置
• 正确配置主题扩展
• 设置适当的清除配置
• 使用正确的插件集成
• 配置自定义间距和断点
• 设置适当的颜色调色板

组件样式

• 优先使用工具类而非自定义CSS
• 在需要时使用@apply组合相关工具类
• 使用正确的响应式设计工具类
• 正确实现暗黑模式
• 使用正确的状态变体
• 保持组件样式一致性

布局

• 有效使用Flexbox和Grid工具类
• 实现适当的间距系统
• 在需要时使用容器查询
• 实现适当的响应式断点
• 使用正确的内外边距工具类
• 实现适当的对齐工具类

排版

• 使用正确的字体大小工具类
• 实现适当的行高
• 使用正确的字体粗细工具类
• 正确配置自定义字体
• 使用正确的文本对齐
• 实现适当的文本装饰

颜色

• 使用语义化的颜色命名
• 实现适当的颜色对比度
• 有效使用透明度工具类
• 正确配置自定义颜色
• 使用正确的渐变工具类
• 实现适当的悬停状态

组件

• 在可用时使用shadcn/ui组件
• 正确扩展组件
• 保持组件变体一致性
• 实现适当的动画
• 使用正确的过渡工具类
• 注意可访问性

响应式设计

• 使用移动优先方法
• 实现适当的断点
• 有效使用容器查询
• 正确处理不同屏幕尺寸
• 实现适当的响应式排版
• 使用正确的响应式间距

性能

• 使用正确的清除配置
• 最小化自定义CSS
• 使用正确的缓存策略
• 实现适当的代码分割
• 优化生产环境
• 监控包大小

最佳实践

• 遵循命名约定
• 保持样式组织有序
• 使用适当的文档
• 实现适当的测试
• 遵循可访问性指南
• 使用正确的版本控制

typescript.mdc

TypeScript 最佳实践

类型系统

• 对象定义优先使用接口而非类型
• 对联合类型、交叉类型和映射类型使用type
• 避免使用any，对未知类型优先使用unknown
• 使用严格的TypeScript配置
• 充分利用TypeScript的内置工具类型
• 使用泛型实现可复用的类型模式

命名约定

• 类型名称和接口使用PascalCase
• 变量和函数使用camelCase
• 常量使用UPPER_CASE
• 使用带有助动词的描述性名称（如isLoading、hasError）
• React props接口名称前缀使用'Props'（如ButtonProps）

代码组织

• 将类型定义保持在使用它们的地方附近
• 当需要共享时，从专门的类型文件中导出类型和接口
• 使用桶导出（index.ts）组织导出
• 将共享类型放在types目录中
• 将组件props与其组件放在一起

函数

• 为公共函数使用显式返回类型
• 回调和方法使用箭头函数
• 使用自定义错误类型实现适当的错误处理
• 对复杂类型场景使用函数重载
• 优先使用async/await而非Promises

最佳实践

• 在tsconfig.json中启用严格模式
• 对不可变属性使用readonly
• 利用可辨识联合实现类型安全
• 使用类型守卫进行运行时类型检查
• 实现适当的空值检查
• 除非必要，避免类型断言

错误处理

• 为领域特定错误创建自定义错误类型
• 对可能失败的操作使用Result类型
• 实现适当的错误边界
• 使用带类型化catch子句的try-catch块
• 正确处理Promise拒绝

模式

• 使用建造者模式进行复杂对象创建
• 实现仓储模式进行数据访问
• 使用工厂模式进行对象创建
• 利用依赖注入
• 使用模块模式进行封装

nextjs.mdc

Next.js 最佳实践

项目结构

• 使用App Router目录结构
• 将路由特定组件放在app目录中
• 将共享组件放在components目录中
• 将工具和辅助函数放在lib目录中
• 目录使用小写字母和破折号（如components/auth-wizard）

组件

• 默认使用服务器组件
• 使用'use client'显式标记客户端组件
• 使用带有后备的Suspense包装客户端组件
• 对非关键组件使用动态加载
• 实现适当的错误边界
• 将静态内容和接口放在文件末尾

性能

• 优化图片：使用WebP格式、尺寸数据、懒加载
• 最小化使用'useEffect'和'setState'
• 尽可能使用服务器组件(RSC)
• 对非关键组件使用动态加载
• 实现适当的缓存策略

数据获取

• 尽可能使用服务器组件进行数据获取
• 实现适当的数据获取错误处理
• 使用适当的缓存策略
• 适当处理加载和错误状态

路由

• 使用App Router约定
• 为路由实现适当的加载和错误状态
• 适当使用动态路由
• 在需要时处理并行路由

表单和验证

• 使用Zod进行表单验证
• 实现适当的服务器端验证
• 适当处理表单错误
• 在表单提交期间显示加载状态

状态管理

• 最小化客户端状态
• 谨慎使用React Context
• 尽可能优先使用服务器状态
• 实现适当的加载状态

node-express.mdc

Node.js 和 Express.js 最佳实践

项目结构

• 使用适当的目录结构
• 实现适当的模块组织
• 使用适当的中间件组织
• 按领域保持路由组织
• 实现适当的错误处理
• 使用适当的配置管理

Express设置

• 使用适当的中间件设置
• 实现适当的路由
• 使用适当的错误处理
• 配置适当的安全中间件
• 实现适当的验证
• 使用适当的静态文件服务

API设计

• 使用适当的REST原则
• 实现适当的版本控制
• 使用适当的请求验证
• 正确处理错误
• 实现适当的响应格式
• 正确文档化API

数据库集成

• 使用适当的ORM/ODM
• 实现适当的迁移
• 使用适当的连接池
• 实现适当的事务
• 使用适当的查询优化
• 正确处理数据库错误

认证

• 实现适当的JWT处理
• 使用适当的密码哈希
• 实现适当的会话管理
• 使用适当的OAuth集成
• 实现适当的基于角色的访问
• 正确处理认证错误

安全

• 使用适当的CORS设置
• 实现适当的速率限制
• 使用适当的安全头
• 实现适当的输入验证
• 使用适当的加密
• 处理安全漏洞

性能

• 使用适当的缓存
• 实现适当的异步操作
• 使用适当的连接池
• 实现适当的日志记录
• 使用适当的监控
• 正确处理高流量

测试

• 编写适当的单元测试
• 实现适当的集成测试
• 使用适当的测试运行器
• 实现适当的模拟
• 测试错误场景
• 使用适当的测试覆盖率

部署

• 使用适当的Docker设置
• 实现适当的CI/CD
• 使用适当的环境变量
• 配置适当的日志记录
• 实现适当的监控
• 处理部署错误

最佳实践

• 遵循Node.js最佳实践
• 使用适当的async/await
• 实现适当的错误处理
• 使用适当的日志记录
• 正确处理进程信号
• 正确文档化代码

python.mdc

Python 最佳实践

项目结构

• 使用src布局，路径为src/your_package_name/
• 将测试放在与src/平行的tests/目录中
• 将配置保存在config/或环境变量中
• 在requirements.txt或pyproject.toml中存储依赖
• 将静态文件放在static/目录中
• 使用templates/存放Jinja2模板

代码风格

• 遵循Black代码格式化

• 使用isort进行导入排序

• 遵循PEP 8命名约定：

  • 函数和变量使用snake_case
  • 类使用PascalCase
  • 常量使用UPPER_CASE

• 最大行长度为88个字符（Black默认值）

• 优先使用绝对导入而非相对导入

类型提示

• 为所有函数参数和返回值使用类型提示
• 从typing模块导入类型
• 使用Optional[Type]而不是Type | None
• 使用TypeVar实现泛型类型
• 在types.py中定义自定义类型
• 使用Protocol实现鸭子类型

Flask结构

• 使用Flask工厂模式
• 使用蓝图组织路由
• 使用Flask-SQLAlchemy操作数据库
• 实现适当的错误处理器
• 使用Flask-Login进行认证
• 使用适当的关注点分离构建视图

数据库

• 使用SQLAlchemy ORM
• 使用Alembic实现数据库迁移
• 使用适当的连接池
• 在单独的模块中定义模型
• 实现适当的关系
• 使用适当的索引策略

认证

• 使用Flask-Login进行会话管理
• 使用Flask-OAuth实现Google OAuth
• 使用bcrypt哈希密码
• 使用适当的会话安全
• 实现CSRF保护
• 使用适当的基于角色的访问控制

API设计

• 使用Flask-RESTful构建REST API
• 实现适当的请求验证
• 使用适当的HTTP状态码
• 一致地处理错误
• 使用适当的响应格式
• 实现适当的速率限制

测试

• 使用pytest进行测试
• 为所有路由编写测试
• 使用pytest-cov进行覆盖率测试
• 实现适当的fixture
• 使用pytest-mock进行适当的模拟
• 测试所有错误场景

安全

• 在生产环境中使用HTTPS
• 实现适当的CORS
• 净化所有用户输入
• 使用适当的会话配置
• 实现适当的日志记录
• 遵循OWASP指南

性能

• 使用Flask-Caching实现适当的缓存
• 实现数据库查询优化
• 使用适当的连接池
• 实现适当的分页
• 使用后台任务处理重操作
• 监控应用程序性能

错误处理

• 创建自定义异常类
• 使用适当的try-except块
• 实现适当的日志记录
• 返回适当的错误响应
• 正确处理边缘情况
• 使用适当的错误消息

文档

• 使用Google风格的文档字符串
• 记录所有公共API
• 保持README.md更新
• 使用适当的内联注释
• 生成API文档
• 记录环境设置

开发工作流

• 使用虚拟环境(venv)
• 实现pre-commit钩子
• 使用适当的Git工作流
• 遵循语义化版本
• 使用适当的CI/CD实践
• 实现适当的日志记录

依赖

• 固定依赖版本
• 在生产环境中使用requirements.txt
• 分离开发依赖
• 使用适当的包版本
• 定期更新依赖
• 检查安全漏洞

cpp.mdc

C++ 编程指南

基本原则

• 所有代码和文档使用英语
• 始终声明每个变量和函数的类型（参数和返回值）
• 创建必要的类型和类
• 使用Doxygen风格注释记录公共类和方法
• 不要在函数内留空行
• 遵循单一定义规则(ODR)

命名规范

• 类和结构体使用PascalCase

• 变量、函数和方法使用camelCase

• 常量和宏使用ALL_CAPS

• 文件和目录名使用snake_case

• 环境变量使用UPPERCASE

• 避免魔法数字并定义常量

• 每个函数以动词开头

• 布尔变量使用动词。例如：isLoading、hasError、canDelete等

• 使用完整单词而不是缩写并确保拼写正确

  • 标准缩写除外，如API、URL等

  • 常见缩写除外：

    • i、j、k用于循环
    • err用于错误
    • ctx用于上下文
    • req、res用于请求/响应参数

函数

• 编写短小且单一目的的函数。少于20条指令

• 函数名使用动词加其他内容

• 如果返回布尔值，使用isX或hasX、canX等

• 如果不返回任何内容(void)，使用executeX或saveX等

• 通过以下方式避免嵌套块：

  • 早期检查和返回
  • 提取为工具函数

• 使用标准库算法（std::for_each、std::transform、std::find等）避免函数嵌套

• 简单操作使用lambda函数

• 非简单操作使用命名函数

• 使用默认参数值而不是检查null或nullptr

• 使用结构体或类减少函数参数

  • 使用对象传递多个参数
  • 使用对象返回多个结果
  • 为输入参数和输出声明必要的类型

• 使用单一抽象层次

数据

• 不要滥用基本类型，将数据封装在复合类型中
• 避免在函数中进行数据验证，使用带有内部验证的类
• 优先使用不可变数据
• 对不变的数据使用const
• 对编译时常量使用constexpr
• 对可能为空的值使用std::optional

类

• 遵循SOLID原则

• 优先使用组合而非继承

• 将接口声明为抽象类或概念

• 编写短小且单一目的的类

  • 少于200条指令
  • 少于10个公共方法
  • 少于10个属性

• 使用五法则（或零法则）进行资源管理

• 将成员变量设为私有，必要时提供getter/setter

• 对成员函数使用const正确性

异常

• 使用异常处理意外错误

• 如果捕获异常，应该是为了：

  • 修复预期的问题
  • 添加上下文
  • 否则，使用全局处理器

• 对预期的失败使用std::optional、std::expected或错误码

内存管理

• 优先使用智能指针（std::unique_ptr、std::shared_ptr）而非原始指针
• 使用RAII（资源获取即初始化）原则
• 通过适当的资源管理避免内存泄漏
• 使用std::vector和其他标准容器而非C风格数组

测试

• 遵循测试的Arrange-Act-Assert约定

• 清晰命名测试变量

• 遵循约定：inputX、mockX、actualX、expectedX等

• 为每个公共函数编写单元测试

• 使用测试替身模拟依赖

  • 执行成本不高的第三方依赖除外

• 为每个模块编写集成测试

• 遵循Given-When-Then约定

项目结构

• 使用模块化架构

• 将代码组织到逻辑目录中：

  • include/用于头文件
  • src/用于源文件
  • test/用于测试文件
  • lib/用于库文件
  • doc/用于文档

• 使用CMake或类似的构建系统

• 将接口(.h)与实现(.cpp)分离

• 使用命名空间逻辑组织代码

• 为基础组件创建core命名空间

• 为工具函数创建utils命名空间

标准库

• 尽可能使用C++标准库
• 优先使用std::string而非C风格字符串
• 对集合使用std::vector、std::map、std::unordered_map等
• 对现代类型安全使用std::optional、std::variant、std::any
• 对文件操作使用std::filesystem
• 对时间相关操作使用std::chrono

并发

• 对线程安全使用std::thread、std::mutex、std::lock_guard
• 优先使用基于任务的并行而非基于线程的并行
• 对原子操作使用std::atomic
• 通过适当的同步避免数据竞争
• 必要时使用线程安全的数据结构

database.mdc

数据库最佳实践

Prisma设置

• 使用适当的模式设计
• 实现适当的迁移
• 使用适当的关系定义
• 配置适当的连接
• 实现适当的种子数据
• 使用适当的客户端设置

Prisma模型

• 使用适当的模型命名
• 实现适当的关系
• 使用适当的字段类型
• 定义适当的索引
• 实现适当的约束
• 使用适当的枚举

Prisma查询

• 使用适当的查询优化
• 实现适当的过滤
• 使用适当的关系加载
• 正确处理事务
• 实现适当的分页
• 使用适当的聚合

Supabase设置

• 配置适当的项目设置
• 实现适当的认证
• 使用适当的数据库设置
• 配置适当的存储
• 实现适当的策略
• 使用适当的客户端设置

Supabase安全

• 实现适当的RLS策略
• 使用适当的认证
• 配置适当的权限
• 正确处理敏感数据
• 实现适当的备份
• 使用适当的加密

Supabase查询

• 使用适当的查询优化
• 实现适当的过滤
• 使用适当的连接
• 正确处理实时功能
• 实现适当的分页
• 使用适当的函数

数据库设计

• 使用适当的规范化
• 实现适当的索引
• 使用适当的约束
• 定义适当的关系
• 实现适当的级联
• 使用适当的数据类型

性能

• 使用适当的连接池
• 实现适当的缓存
• 使用适当的查询优化
• 正确处理N+1查询
• 实现适当的批处理
• 监控性能指标

安全

• 使用适当的认证
• 实现适当的授权
• 正确处理敏感数据
• 使用适当的加密
• 实现适当的备份
• 监控安全问题

最佳实践

• 遵循数据库约定
• 使用适当的迁移
• 实现适当的版本控制
• 正确处理错误
• 正确记录模式文档
• 监控数据库健康状况