Cursor AI代码编辑器完整使用指南：从安装到高级用法

# ============================================
# .cursor/rules 目录结构
# ============================================

# 在项目根目录创建 .cursor/rules/ 目录
# 放入以下文件：

# 1. 代码风格规则：.cursor/rules/code-style.mdc
# 文件位置：project/.cursor/rules/code-style.mdc

```markdown
# 代码风格规则

## Python
- 使用 type hints 标注所有函数参数和返回值类型
- 类名使用 PascalCase，函数名使用 snake_case
- 每个函数必须有 docstring，说明参数和返回值
- 使用 dataclass 而非字典存储结构化数据

## React/TypeScript
- 组件文件后缀：.tsx
- 样式文件后缀：.module.css
- 使用 functional component + hooks
- Props 类型定义使用 interface
- 禁止使用 any，全部用具体类型

## Git提交规范
- 使用 conventional commits 格式
- feat: 新功能
- fix: bug修复
- docs: 文档更新
- refactor: 重构
- test: 测试
```

# 2. 安全规则：.cursor/rules/security.mdc
```markdown
# 安全规则

## 禁止
- 禁止在代码中硬编码密钥，使用环境变量
- 禁止SQL拼接，使用参数化查询
- 禁止用户输入直接拼HTML，使用转义或DOMPurify
- 禁止在客户端存储敏感信息

## 必须
- 所有API必须验证输入
- 密码必须加盐哈希存储
- 文件上传必须检查文件类型和大小
- 敏感操作必须记录日志
```

# 3. 性能规则：.cursor/rules/performance.mdc
```markdown
# 性能规则

## 数据库
- 避免 N+1 查询，使用 eager loading 或 join
- 大数据量分页使用 cursor 而非 offset
- 批量操作使用 bulk_write 而非循环单条

## 前端
- 列表渲染使用虚拟滚动（超过100条时）
- 图片使用懒加载
- 避免不必要的 re-render，使用 useMemo/useCallback
```

# ============================================
# 模型选择策略
# ============================================

# Cursor支持的模型（截至2025年）：

# 1. Claude 3.5 Sonnet（推荐）
# 优势：代码理解能力强，长上下文（200K），性价比高
# 适用：复杂重构、代码审查、长文件分析
# 设置：Settings → Models → Default → Claude 3.5 Sonnet

# 2. GPT-4o
# 优势：通用能力强，代码生成质量稳定
# 适用：新功能开发、需要GPT能力的场景
# 限制：贵，速度慢

# 3. Cursor Small（内置）
# 优势：免费、响应快、适合简单任务
# 适用：代码补全、简单注释、重命名变量

# 4. 本地模型（Ollama）
# 优势：免费、完全私有、不限额度
# 劣势：需要本地GPU，效果不如云端模型
# 设置：Settings → Models → Use local model → Ollama

# 5. Claude 3 Opus
# 优势：最强代码能力
# 适用：最复杂的架构设计、代码生成
# 限制：贵、慢

# ============================================
# 按任务选模型
# ============================================

# 简单任务（补全、注释、重命名）→ Cursor Small
# 标准任务（函数生成、bug修复）→ Claude 3.5 Sonnet  
# 复杂任务（多文件重构、架构设计）→ Claude 3.5 Sonnet
# 最高要求（关键代码审查）→ Claude 3.5 Opus 或 GPT-4o

# 配置方法：快捷键 Cmd/Ctrl + K 后，点击模型名称切换

# ============================================
# 原始代码（monolithic_app.py）
# 这是一个混乱的单体应用，所有代码都写在一个文件里
# ============================================

from flask import Flask, request, jsonify
import sqlite3
from datetime import datetime

app = Flask(__name__)

# 直接硬编码数据库路径
DB_PATH = 'app.db'

def get_db():
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    return conn

@app.route('/users', methods=['GET'])
def get_users():
    db = get_db()
    cursor = db.execute('SELECT * FROM users')
    users = cursor.fetchall()
    db.close()
    return jsonify([dict(row) for row in users])

@app.route('/users', methods=['POST'])
def create_user():
    data = request.json
    # 没有参数验证
    db = get_db()
    db.execute('INSERT INTO users (name, email) VALUES (?, ?)',
               [data['name'], data['email']])
    db.commit()
    db.close()
    return jsonify({'status': 'created'}), 201

@app.route('/users/', methods=['GET'])
def get_user(user_id):
    db = get_db()
    cursor = db.execute('SELECT * FROM users WHERE id = ?', [user_id])
    user = cursor.fetchone()
    db.close()
    if not user:
        return jsonify({'error': 'not found'}), 404
    return jsonify(dict(user))

# ... 后面还有1000多行类似代码

# ============================================
# 步骤1：打开Composer，描述重构目标
# ============================================

"""
将 monolithic_app.py 重构为模块化Flask应用，分以下步骤：

Step 1 - 创建目录结构：
```
app/
├── __init__.py          # Flask应用工厂
├── config.py            # 配置管理
├── models/
│   ├── __init__.py
│   └── user.py          # User模型
├── routes/
│   ├── __init__.py
│   └── user_routes.py   # 用户相关路由
├── services/
│   ├── __init__.py
│   └── user_service.py  # 业务逻辑
├── schemas/
│   ├── __init__.py
│   └── user_schema.py   # 请求/响应验证
├── utils/
│   ├── __init__.py
│   └── database.py      # 数据库连接工具
├── tests/
│   ├── __init__.py
│   └── test_user.py     # 单元测试
├── requirements.txt
└── run.py               # 启动脚本
```

Step 2 - 重构规则：
- 使用应用工厂模式（Application Factory）
- 模型层和数据访问层分离
- 使用 marshmallow 做请求验证
- 环境变量配置所有敏感信息
- 添加类型注解
- 添加完整的docstring

Step 3 - 保持API兼容性：
- 所有路由路径保持不变
- 所有请求/响应格式保持不变
- 确保重构后原有功能不变
"""

# Cursor会逐步执行：
# 1. 先创建目录结构和空文件
# 2. 逐个文件填充内容
# 3. 每步都显示diff，你可以审批

# ============================================
# Cursor生成的结果示例
# ============================================

# app/__init__.py - Flask应用工厂
"""
Flask应用工厂
创建并配置Flask应用实例
"""
from flask import Flask
from app.config import config
from app.routes import register_routes
from app.extensions import init_extensions

def create_app(config_name: str = "development") -> Flask:
    """
    创建并配置Flask应用
    
    Args:
        config_name: 配置名称，可选 'development' | 'production' | 'testing'
    
    Returns:
        配置好的Flask应用实例
    """
    app = Flask(__name__)
    
    # 加载配置
    app.config.from_object(config[config_name])
    
    # 初始化扩展（如SQLAlchemy、Ma等）
    init_extensions(app)
    
    # 注册路由蓝图
    register_routes(app)
    
    # 注册错误处理
    register_error_handlers(app)
    
    return app

# app/models/user.py - 模型层
"""
User数据模型
"""
from dataclasses import dataclass
from datetime import datetime
from typing import Optional

@dataclass
class User:
    """
    用户数据类
    
    Attributes:
        id: 用户ID（数据库主键）
        name: 用户名
        email: 邮箱地址
        created_at: 创建时间
        updated_at: 更新时间
    """
    id: Optional[int]
    name: str
    email: str
    created_at: Optional[datetime] = None
    updated_at: Optional[datetime] = None
    
    def to_dict(self) -> dict:
        """转换为字典格式，用于JSON序列化"""
        return {
            "id": self.id,
            "name": self.name,
            "email": self.email,
            "created_at": self.created_at.isoformat() if self.created_at else None,
            "updated_at": self.updated_at.isoformat() if self.updated_at else None
        }
    
    @classmethod
    def from_db_row(cls, row) -> "User":
        """从数据库行创建User实例"""
        return cls(
            id=row["id"],
            name=row["name"],
            email=row["email"],
            created_at=datetime.fromisoformat(row["created_at"]) if row.get("created_at") else None,
            updated_at=datetime.fromisoformat(row["updated_at"]) if row.get("updated_at") else None
        )

# app/schemas/user_schema.py - 验证层
"""
用户相关的数据验证模式
使用marshmallow做请求/响应验证
"""
from marshmallow import Schema, fields, validate, validates, ValidationError

class UserCreateSchema(Schema):
    """创建用户的请求验证模式"""
    name = fields.Str(
        required=True,
        validate=validate.Length(min=1, max=100),
        error_messages={"required": "用户名不能为空"}
    )
    email = fields.Email(
        required=True,
        error_messages={
            "required": "邮箱不能为空",
            "invalid": "邮箱格式不正确"
        }
    )
    
    @validates("name")
    def validate_name(self, value):
        """用户名验证：不能包含特殊字符"""
        if not value.replace(" ", "").replace("_", "").replace("-", "").isalnum():
            raise ValidationError("用户名只能包含字母、数字、下划线和连字符")

class UserResponseSchema(Schema):
    """用户响应数据模式"""
    id = fields.Int(dump_only=True)
    name = fields.Str()
    email = fields.Email()
    created_at = fields.DateTime(format="iso")
    updated_at = fields.DateTime(format="iso")

class UserUpdateSchema(Schema):
    """更新用户的请求验证模式"""
    name = fields.Str(validate=validate.Length(min=1, max=100))
    email = fields.Email()

# app/services/user_service.py - 业务逻辑层
"""
用户服务层
处理用户相关的业务逻辑
"""
from typing import List, Optional
from app.models.user import User
from app.repositories.user_repository import UserRepository

class UserService:
    """
    用户服务类
    封装用户相关的业务逻辑
    """
    
    def __init__(self, repository: Optional[UserRepository] = None):
        """
        初始化服务
        
        Args:
            repository: 用户仓库实例，默认创建新实例
        """
        self.repository = repository or UserRepository()
    
    def get_all_users(self) -> List[User]:
        """
        获取所有用户列表
        
        Returns:
            User对象列表
        """
        rows = self.repository.find_all()
        return [User.from_db_row(row) for row in rows]
    
    def get_user_by_id(self, user_id: int) -> Optional[User]:
        """
        根据ID获取用户
        
        Args:
            user_id: 用户ID
        
        Returns:
            User对象，如果不存在返回None
        """
        row = self.repository.find_by_id(user_id)
        return User.from_db_row(row) if row else None
    
    def create_user(self, name: str, email: str) -> User:
        """
        创建新用户
        
        Args:
            name: 用户名
            email: 邮箱地址
        
        Returns:
            创建的User对象
        
        Raises:
            ValueError: 如果邮箱已存在
        """
        # 检查邮箱是否已存在
        existing = self.repository.find_by_email(email)
        if existing:
            raise ValueError(f"邮箱 {email} 已被注册")
        
        user_id = self.repository.create(name=name, email=email)
        return self.get_user_by_id(user_id)
    
    def update_user(self, user_id: int, name: Optional[str] = None, 
                    email: Optional[str] = None) -> Optional[User]:
        """
        更新用户信息
        
        Args:
            user_id: 用户ID
            name: 新用户名（可选）
            email: 新邮箱（可选）
        
        Returns:
            更新后的User对象，不存在返回None
        """
        if not self.repository.exists(user_id):
            return None
        
        self.repository.update(user_id, name=name, email=email)
        return self.get_user_by_id(user_id)
    
    def delete_user(self, user_id: int) -> bool:
        """
        删除用户
        
        Args:
            user_id: 用户ID
        
        Returns:
            是否删除成功
        """
        return self.repository.delete(user_id)

# app/routes/user_routes.py - 路由层
"""
用户路由
定义所有用户相关的HTTP接口
"""
from flask import Blueprint, request, jsonify
from marshmallow import ValidationError
from app.schemas.user_schema import (
    UserCreateSchema, 
    UserUpdateSchema, 
    UserResponseSchema
)
from app.services.user_service import UserService
from app.utils.decorators import handle_errors

user_bp = Blueprint('users', __name__, url_prefix='/users')
user_service = UserService()
user_schema = UserResponseSchema()

@user_bp.route('', methods=['GET'])
@handle_errors
def get_users():
    """
    获取用户列表
    
    Returns:
        JSON: 用户列表
    """
    users = user_service.get_all_users()
    return jsonify([user.to_dict() for user in users])

@user_bp.route('', methods=['POST'])
@handle_errors
def create_user():
    """
    创建新用户
    
    Request Body:
        - name: 用户名（必填）
        - email: 邮箱（必填）
    
    Returns:
        JSON: 创建的用户信息
    """
    # 验证请求数据
    schema = UserCreateSchema()
    try:
        data = schema.load(request.json)
    except ValidationError as e:
        return jsonify({"errors": e.messages}), 400
    
    # 创建用户
    user = user_service.create_user(name=data['name'], email=data['email'])
    return jsonify(user.to_dict()), 201

@user_bp.route('/', methods=['GET'])
@handle_errors
def get_user(user_id: int):
    """
    获取单个用户
    
    Args:
        user_id: 用户ID
    
    Returns:
        JSON: 用户信息，404则返回错误
    """
    user = user_service.get_user_by_id(user_id)
    if not user:
        return jsonify({"error": "用户不存在"}), 404
    return jsonify(user.to_dict())

@user_bp.route('/', methods=['PUT', 'PATCH'])
@handle_errors
def update_user(user_id: int):
    """
    更新用户信息
    
    Args:
        user_id: 用户ID
    
    Request Body:
        - name: 新用户名（可选）
        - email: 新邮箱（可选）
    
    Returns:
        JSON: 更新后的用户信息，404则返回错误
    """
    schema = UserUpdateSchema()
    try:
        data = schema.load(request.json)
    except ValidationError as e:
        return jsonify({"errors": e.messages}), 400
    
    user = user_service.update_user(user_id, **data)
    if not user:
        return jsonify({"error": "用户不存在"}), 404
    return jsonify(user.to_dict())

@user_bp.route('/', methods=['DELETE'])
@handle_errors
def delete_user(user_id: int):
    """
    删除用户
    
    Args:
        user_id: 用户ID
    
    Returns:
        JSON: 空或成功消息，404则返回错误
    """
    success = user_service.delete_user(user_id)
    if not success:
        return jsonify({"error": "用户不存在"}), 404
    return jsonify({"status": "deleted"}), 200

# 在Composer中执行验证：
"""
运行以下验证，确保重构后API兼容性：

1. 启动应用
   cd app && python run.py &

2. 测试原有API端点（保持兼容性）
   # GET /users
   curl http://localhost:5000/users
   # 预期：返回用户列表，格式与原来一致

   # POST /users
   curl -X POST http://localhost:5000/users \
     -H "Content-Type: application/json" \
     -d '{"name": "test", "email": "test@example.com"}'
   # 预期：返回201创建成功

   # GET /users/:id
   curl http://localhost:5000/users/1
   # 预期：返回该用户信息

3. 检查新功能
   - 参数验证是否工作
   - 错误处理是否返回正确格式
   
4. 生成测试覆盖率报告
   pytest --cov=app --cov-report=term-missing
   # 预期：核心功能测试覆盖率 > 90%
"""

# 问题1：AI完全无响应
# 解决方案：
1. 检查网络连接（Cursor需要联网）
2. 检查API Key是否有效：Settings → Models → API Keys
3. 切换模型试试（有时某个模型服务不稳定）
4. 重启Cursor：完全退出后重新打开

# 问题2：补全慢/卡顿
# 解决方案：
1. 减少同时打开的文件数量（AI需要分析所有打开的文件）
2. 关闭不需要的扩展（扩展会消耗资源）
3. 降低模型速度设置：Settings → Models → Speed → "Faster"
4. 使用Cursor Small模型（最快）

# 问题3：Context上下文丢失
# 解决方案：
1. 定期清理没用的Context引用
2. 打开Composer后按 Clear 按钮清空历史
3. 拆分大文件：超过2000行的文件AI可能处理不好

# 问题：提示 "Invalid API Key" 或 "Quota exceeded"
# 排查步骤：

# 1. 检查Key是否正确
# Settings → Models → API Keys
# 确认复制的Key没有多余空格

# 2. 检查Key来源
# OpenAI Key: https://platform.openai.com/api-keys
# Anthropic Key: https://console.anthropic.com/settings/keys

# 3. 检查用量
# OpenAI: https://platform.openai.com/usage
# 确认还有额度

# 4. 检查账单
# 有时候欠费也会导致无法使用
# OpenAI需要先充值才能用

# 5. 尝试其他模型
# 如果OpenAI Key出问题，切换到Anthropic试试
# Settings → Models → Default Model → Claude 3.5 Sonnet