跳到主要内容

.cursor/rules 最佳实践

.cursor/rules 是一个强大的功能，可以帮助团队维护一致的编码标准并改进协作。本指南涵盖了有效设置和管理规则的最佳实践。

理解 .cursor/rules​

.cursor/rules 是一个配置系统，它：

  • 定义项目范围的编码标准
  • 自动化代码组织
  • 强制执行一致的模式
  • 改进团队协作

基本设置​

创建规则文件​

在项目根目录创建 .cursor/rules 文件。

mkdir .cursor
touch .cursor/rules

基本结构​

典型的规则文件结构：

version: 1.0
rules:
  - name: "组件结构"
    pattern: "src/components/**/*.{ts,tsx}"
    template: |
      import React from 'react'
      
      interface ${ComponentName}Props {
        // 属性
      }
      
      export const ${ComponentName}: React.FC<${ComponentName}Props> = () => {
        return (
          <div>
            {/* 组件内容 */}
          </div>
        )
      }

  - name: "服务"
    pattern: "src/services/**/*.ts"
    template: |
      import { ApiClient } from '../utils/apiClient'
      
      export class ${ServiceName}Service {
        private client: ApiClient
        
        constructor() {
          this.client = new ApiClient()
        }
        
        // 服务方法
      }

最佳实践​

1. 一致的命名约定​

使用清晰、描述性的规则名称。

rules:
  - name: "React组件"
    description: "标准React组件结构"
    pattern: "src/components/**/*.tsx"

  - name: "API服务"
    description: "REST API服务模板"
    pattern: "src/services/**/*.ts"

2. 模块化组织​

将相关规则组合在一起：

rules:
  # 组件规则
  - name: "组件/函数"
    pattern: "src/components/**/*.tsx"
    
  - name: "组件/"
    pattern: "src/components/**/*.class.tsx"
    
  # 服务规则
  - name: "服务/REST"
    pattern: "src/services/rest/**/*.ts"
    
  - name: "服务/GraphQL"
    pattern: "src/services/graphql/**/*.ts"

3. 模板变量​

使用描述性的模板变量。

rules:
  - name: "组件模板"
    pattern: "src/components/**/*.tsx"
    template: |
      interface ${ComponentName}Props {
        ${PropName}: ${PropType}
      }
      
      export const ${ComponentName} = ({
        ${PropName}
      }: ${ComponentName}Props) => {
        return (
          <div>
            {${PropName}}
          </div>
        )
      }

4. 文档​

在规则中包含清晰的文档：

rules:
  - name: "API服务"
    description: |
      API服务类的模板。
      包括标准的CRUD操作和错误处理。
    pattern: "src/services/**/*.ts"
    template: |
      /**
       * ${ServiceName} 服务
       * 处理 ${ServiceDescription}
       */
      export class ${ServiceName}Service {
        // 实现
      }

5. 错误处理​

包含错误处理模式。

rules:
  - name: "服务错误处理"
    pattern: "src/services/**/*.ts"
    template: |
      try {
        // 服务逻辑
      } catch (error) {
        if (error instanceof ApiError) {
          // 处理API错误
        } else {
          // 处理其他错误
        }
        throw error
      }

高级模式​

1. 条件模板​

在模板中使用条件。

rules:
  - name: "带Props的组件"
    pattern: "src/components/**/*.tsx"
    template: |
      ${HasProps ? `
      interface ${ComponentName}Props {
        // 属性
      }
      ` : ''}
      
      export const ${ComponentName}${HasProps ? ': React.FC<${ComponentName}Props>' : ''} = () => {
        // 实现
      }

2. 共享模式​

定义可重用的模式。

patterns:
  typescript-header: |
    /**
     * @file ${FileName}
     * @description ${FileDescription}
     * @created ${Date}
     */

rules:
  - name: "组件"
    pattern: "src/components/**/*.tsx"
    template: |
      ${patterns.typescript-header}
      // 组件实现

优化提示​

  1. 文件组织

    • 将相关文件组合在一起
    • 使用一致的目录结构
    • 遵循命名约定

  2. 模板效率

    • 保持模板重点明确
    • 避免冗余代码
    • 对常见元素使用共享模板

  3. 性能考虑

    • 限制模式复杂性
    • 使用特定的文件模板
    • 避免过于宽泛的匹配

常见模式​

React组件​

rules:
  - name: "React函数组件"
    pattern: "src/components/**/*.tsx"
    template: |
      import React from 'react'
      import styles from './${ComponentName}.module.css'
      
      export interface ${ComponentName}Props {
        // 属性
      }
      
      export const ${ComponentName}: React.FC<${ComponentName}Props> = () => {
        return (
          <div className={styles.container}>
            {/* 组件内容 */}
          </div>
        )
      }

服务​

rules:
  - name: "服务"
    pattern: "src/services/**/*.ts"
    template: |
      import { injectable } from 'inversify'
      import { ApiClient } from '@/utils/apiClient'
      
      @injectable()
      export class ${ServiceName}Service {
        constructor(private apiClient: ApiClient) {}
        
        async getAll(): Promise<${EntityName}[]> {
          return this.apiClient.get('/${entityPath}')
        }
        
        async getById(id: string): Promise<${EntityName}> {
          return this.apiClient.get(`/${entityPath}/${id}`)
        }
      }

相关资源​

  • Cursor 配置指南
  • 团队协作技巧](/tutorial/team-collaboration)
  • [代码组织模式

结论​

有效使用 .cursor/rules 可以显著提高代码一致性和团队生产力。通过遵循这些最佳实践，您可以创建可维护和可扩展的代码结构。

相关文章​

  • 高级 Cursor 配置
  • 团队工作流优化](/tutorial/HowTo/team-workflow)
  • [代码生成模式