Cursor-Django项目：AI辅助编程与Django开发规范融合实践

1. 项目概述与核心价值

最近在尝试用 Cursor 这个 AI 编辑器来提升 Django 项目的开发效率，偶然在 GitHub 上发现了mhgolestan/Cursor-Django这个项目。乍一看，这只是一个简单的 Django 项目模板，但深入研究后，我发现它远不止于此。它更像是一份为 Cursor 编辑器“量身定制”的 Django 开发指南，或者说，是一个精心设计的“提示工程”实践库。对于像我这样，既想拥抱 AI 辅助编程的高效，又希望保持 Django 开发规范性的开发者来说，这个项目提供了一个绝佳的起点和参考。

简单来说，Cursor-Django项目展示了如何将一个标准的 Django 项目与 Cursor 编辑器的 AI 能力（特别是其强大的代码补全、解释和生成功能）进行深度结合。它通过预设的项目结构、清晰的代码注释、以及符合最佳实践的配置，来“引导” Cursor 的 AI 助手生成更准确、更符合项目上下文的高质量代码。这解决了我们在使用 AI 编码工具时的一个常见痛点：AI 生成的代码虽然语法正确，但往往与项目的特定架构、编码风格或业务逻辑脱节，需要开发者花费大量时间进行二次调整和集成。

这个项目适合所有正在或计划使用 Cursor 进行 Django 开发的开发者，无论是想快速搭建一个符合生产环境标准的项目骨架，还是希望学习如何更有效地与 AI 协作，都能从中获得启发。接下来，我将从项目设计、核心配置、实操流程以及避坑经验几个方面，为你深度拆解这个宝藏项目。

2. 项目整体设计与思路拆解

2.1 核心设计哲学：为 AI 提供清晰的上下文

Cursor-Django项目的核心思路非常明确：通过极致的代码清晰度和结构规范性，来最大化 Cursor AI 的理解能力和输出质量。这背后是一个重要的认知转变——我们不再仅仅是写代码给机器或同事看，更是写给 AI 助手看。

传统的 Django 项目模板可能只关注功能模块的划分和基础依赖的安装。而Cursor-Django在此基础上，额外强调了以下几点：

1. 详尽的文档字符串（Docstrings）和类型提示（Type Hints）：在每个模块、类、函数和方法层面，都提供了清晰的说明。这相当于为 AI 建立了一个“代码词典”，让它能准确理解每个元素的职责、输入和输出。例如，一个视图函数不仅会说明它处理什么请求，还会用类型提示明确其接收的request对象类型和返回的HttpResponse类型。
2. 一致且可预测的代码风格：项目严格遵守 PEP 8 和 Django 的编码约定。变量命名、导入顺序、缩进格式都高度统一。这种一致性降低了 AI 的“认知负荷”，让它更容易识别模式并生成风格匹配的新代码。
3. 模块化的项目结构：项目采用了清晰的应用（App）分离原则。将核心业务逻辑、用户认证、API 接口等分别放在不同的应用中。这种结构本身就对 AI 有很强的提示作用，当你在users/目录下要求 AI 生成代码时，它自然会倾向于生成与用户管理相关的代码，而不是混淆其他模块的功能。
4. 环境与配置的显式分离：严格区分开发、测试和生产环境的配置。这通过不同的.env文件和环境变量来实现。AI 在生成涉及配置的代码（如数据库连接、密钥设置）时，可以引用明确的环境变量名，而不是硬编码的字符串，从而生成更安全、更灵活的代码。

2.2 技术栈选型背后的考量

项目选择的技术栈并非最新最炫，而是以“稳定、高效、与 AI 协作友好”为原则：

• Django 4.x：作为成熟稳定的全功能框架，其“约定优于配置”的理念与 AI 辅助编程非常契合。Django 有大量可预测的模式（如 MTV 模式、ORM 查询），AI 学习这些模式后，能非常准确地生成相关代码。
• Django REST Framework (DRF)：对于需要构建 API 的后端项目，DRF 是事实标准。它的序列化器（Serializer）、视图集（ViewSet）等概念高度结构化，AI 能够很好地理解和生成符合规范的 API 代码。
• PostgreSQL：作为首选数据库，不仅因为其功能强大，更因为其与 Django ORM 的集成度极高。AI 在生成模型（Model）字段或复杂查询时，可以基于 PostgreSQL 特有的字段类型（如ArrayField,JSONField）进行更精准的推荐。
• Docker & Docker Compose：提供了一致的开发环境。这对于 AI 协作至关重要。当项目描述中包含了docker-compose.yml文件，AI 就能理解整个服务的运行上下文，从而在生成与部署、服务交互相关的代码或命令时更加准确。
• 预提交钩子（pre-commit）：集成了black,isort,flake8等代码格式化与检查工具。这确保了 AI 生成的代码能立即被自动格式化并检查出潜在问题，形成“AI 生成 -> 自动美化/检查 -> 人工复核”的高效流水线。

注意：这个技术栈是一个“推荐配置”，而非强制。项目的价值在于其组织代码和引导 AI 的思路。你可以根据自己项目的实际需求，替换其中的任何组件（比如用 MySQL 代替 PostgreSQL，或用其他异步框架），但核心的“清晰上下文”设计原则依然适用。

3. 核心细节解析与实操要点

3.1 项目结构：不只是目录，更是给 AI 的“地图”

让我们深入看看Cursor-Django的典型目录结构，并理解每个部分如何服务于 AI 协作：

cursor-django-project/ ├── .cursor/ # 【关键】Cursor 编辑器自定义规则目录 ├── .env.example # 环境变量示例 ├── .pre-commit-config.yaml # 代码质量钩子配置 ├── docker-compose.yml ├── Dockerfile ├── manage.py ├── requirements/ │ ├── base.txt # 核心依赖 │ ├── dev.txt # 开发环境依赖（包含测试、调试工具） │ └── prod.txt # 生产环境依赖 ├── config/ # Django 项目设置目录 │ ├── __init__.py │ ├── settings/ # 【关键】拆分后的设置模块 │ │ ├── __init__.py │ │ ├── base.py # 通用设置 │ │ ├── dev.py # 开发环境设置 │ │ └── prod.py # 生产环境设置 │ ├── urls.py │ └── wsgi.py ├── apps/ # 【关键】所有自定义应用存放于此 │ ├── core/ # 核心应用（可能放公共模型、工具） │ │ ├── __init__.py │ │ ├── models.py │ │ └── ... │ └── users/ # 用户管理应用 │ ├── __init__.py │ ├── models.py │ ├── serializers.py # 如果用了 DRF │ ├── views.py │ ├── urls.py │ └── ... └── ...

核心亮点解析：

1. .cursor/目录：这是项目的灵魂所在。你可以在这里放置rules.mdc文件，定义针对本项目的 AI 助手行为规则。例如，你可以编写规则：“在本项目中，所有模型类必须继承自core.models.BaseModel”，或者“API 视图优先使用 DRF 的GenericAPIView”。当你在项目内激活 Cursor 的 AI 功能时，它会读取这些规则，使生成的代码自动符合你的项目规范。
2. 拆分的settings/模块：将设置按环境（base, dev, prod）拆分是 Django 的最佳实践。Cursor-Django将其显式化。当 AI 需要生成或修改设置时，你可以明确指示它：“更新config/settings/dev.py中的数据库配置”，AI 会精准定位，避免误改生产环境配置。
3. 统一的apps/目录：将所有应用收纳在一个父目录下，使项目结构更紧凑。更重要的是，它为 AI 提供了明确的“搜索范围”。当你新建一个products应用时，AI 会自然地建议你在apps/下创建目录，并生成类似apps/users的应用结构，保持了项目的一致性。

3.2 代码注释与类型提示：AI 的“阅读理解材料”

项目中的代码充满了高质量的注释和类型提示。这不是冗余，而是给 AI 的“高亮笔记”。

示例：一个增强的模型定义

# apps/users/models.py from django.contrib.auth.models import AbstractUser from django.db import models from django.utils.translation import gettext_lazy as _ from core.models import BaseModel # 显式导入基类 class User(AbstractUser, BaseModel): """ 自定义用户模型，扩展了 Django 内置的 AbstractUser。 用于存储系统所有用户的认证和基本信息。 Attributes: phone_number (CharField): 用户的手机号码，用于可选的双因素认证或通知。 avatar (ImageField): 用户的头像图片。 email_verified (BooleanField): 标记用户的邮箱是否已经过验证。 """ phone_number = models.CharField( _("phone number"), max_length=15, blank=True, null=True, help_text=_("User's contact phone number. Optional.") ) avatar = models.ImageField( _("avatar"), upload_to='user_avatars/%Y/%m/%d/', blank=True, null=True, help_text=_("Profile picture of the user.") ) email_verified = models.BooleanField( _("email verified"), default=False, help_text=_("Designates whether the user's email has been verified.") ) def __str__(self) -> str: """返回用户的字符串表示，优先使用邮箱。""" return self.email def get_full_name(self) -> str: """返回用户的全名。如果名和姓都存在，则组合它们，否则返回用户名。""" full_name = f"{self.first_name} {self.last_name}" return full_name.strip() if full_name.strip() else self.username

这段代码给 AI 传递了什么信息？

• 清晰的职责：文档字符串告诉 AI，这个User模型是干什么的（用户认证和信息存储）。
• 字段的详细信息：每个字段的help_text和verbose_name解释了该字段的用途和显示名称。
• 类型与返回值：__str__和get_full_name方法都标注了返回类型-> str，AI 在调用或修改这些方法时，能明确知道会得到什么类型的值。
• 继承关系：明确显示继承了AbstractUser和BaseModel，AI 会知道这个模型拥有 Django 内置的用户字段以及BaseModel中可能定义的如created_at,updated_at等公共字段。

当你在 Cursor 中提问：“为User模型添加一个记录最后登录 IP 地址的字段”，AI 会基于上述上下文，很可能生成一个像last_login_ip = models.GenericIPAddressField(blank=True, null=True)这样符合现有代码风格的字段定义。

3.3 环境配置与 Docker：构建可预测的上下文

项目的docker-compose.yml和Dockerfile定义了完整的服务栈（Django app, PostgreSQL, Redis 等）。.env.example文件列出了所有需要的环境变量。

这对 AI 协作的意义在于：当你的问题涉及到环境或服务时，AI 的答案会基于这个已知的上下文。例如，如果你问：“如何在 Django 中配置 Redis 作为缓存后端？” AI 不会给你一个通用的答案，而是可能会参考项目中已有的docker-compose.yml（其中已经定义了redis服务）和settings/base.py，生成类似下面的代码片段：

# config/settings/base.py 片段 CACHES = { "default": { "BACKEND": "django_redis.cache.RedisCache", "LOCATION": f"redis://{env('REDIS_HOST', default='redis')}:{env('REDIS_PORT', default=6379)}/1", # 引用环境变量 "OPTIONS": { "CLIENT_CLASS": "django_redis.client.DefaultClient", } } }

AI 知道REDIS_HOST和REDIS_PORT应该来自环境变量，并且知道在 Docker Compose 网络中，服务名redis可以作为主机名。这种上下文感知能力极大地提升了生成代码的可用性。

4. 实操过程与核心环节实现

4.1 从零开始：基于 Cursor-Django 初始化项目

假设我们想创建一个名为my_awesome_project的新项目。

1. 获取模板：最直接的方式是使用 Cursor 的“Clone Template”功能（如果你有该项目的访问权限），或者用 Git 命令克隆。

   git clone https://github.com/mhgolestan/Cursor-Django.git my_awesome_project cd my_awesome_project

2. 环境变量配置：复制环境变量示例文件，并根据你的本地环境进行修改。

   cp .env.example .env.dev # 使用编辑器（比如 Cursor 或 VSCode）打开 .env.dev，修改数据库密码、密钥等。 # 例如： # POSTGRES_DB=my_awesome_db # POSTGRES_PASSWORD=your_secure_password_here # SECRET_KEY=your-django-secret-key-here

3. 启动 Docker 服务：这是确保所有依赖（数据库、缓存）就位的关键一步。

   docker-compose up -d postgres redis # 先启动依赖服务 # 等待几秒，确保数据库已启动并可连接

4. 安装 Python 依赖并应用迁移：在 Docker 容器内或本地虚拟环境中进行。

   # 方式一：在项目根目录下，使用 Docker Compose 运行 Django 容器的命令 docker-compose run --rm web python manage.py migrate docker-compose run --rm web python manage.py createsuperuser # 方式二：在本地虚拟环境中（需先安装python3.9+和pip） python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows pip install -r requirements/dev.txt python manage.py migrate --settings=config.settings.dev python manage.py createsuperuser --settings=config.settings.dev

5. 运行开发服务器：

   # Docker 方式 docker-compose up web # 前端会输出日志 # 本地虚拟环境方式 python manage.py runserver --settings=config.settings.dev

   访问http://localhost:8000，你应该能看到 Django 的欢迎页面或项目默认首页。

4.2 核心环节：与 Cursor AI 协作开发一个新功能

现在，让我们实战一下。假设我们要为my_awesome_project添加一个简单的博客功能。

步骤 1：创建博客应用

在 Cursor 编辑器中，打开内置的 AI 聊天面板（通常快捷键是Cmd/Ctrl + K）。输入提示：

“在本项目apps/目录下，创建一个名为blog的 Django 应用。应用需要包含Post模型（标题、内容、作者、发布时间、状态），以及对应的模型管理器和基本的列表、详情视图。请遵循本项目现有的代码风格和结构。”

Cursor AI 可能会执行的操作：

1. 在apps/目录下创建blog/文件夹及__init__.py。
2. 生成apps/blog/models.py，其中Post模型会继承自core.models.BaseModel（如果项目中有），并包含你要求的字段，每个字段都有合适的verbose_name和help_text。
3. 生成apps/blog/admin.py，注册Post模型到 Django 管理后台，并可能添加一些列表过滤器或搜索字段。
4. 生成apps/blog/views.py，包含基于类视图（如ListView,DetailView）的视图。
5. 生成apps/blog/urls.py，定义 URL 路由。
6. 可能会提示你运行makemigrations和migrate命令。

步骤 2：为博客添加 REST API

继续在 Cursor 中提问：

“为刚创建的blog应用中的Post模型，使用 Django REST Framework 创建一套完整的 CRUD API（列表、详情、创建、更新、删除）。包括序列化器（Serializer）、视图集（ViewSet）和路由注册。确保 API 遵循本项目的最佳实践。”

Cursor AI 可能会生成：

1. apps/blog/serializers.py：定义PostSerializer，可能包含字段验证、作者字段的只读处理等。
2. 更新apps/blog/views.py或新建api/views.py：创建PostViewSet，继承自ModelViewSet，并设置queryset、serializer_class，可能还会添加权限类（如IsAuthenticatedOrReadOnly）。
3. 更新apps/blog/urls.py：使用 DRF 的DefaultRouter或SimpleRouter来注册视图集的路由。
4. 可能会更新config/urls.py，将blog应用的 API 路由包含进来。

步骤 3：编写测试

提问：

“为blog应用的Post模型和 API 视图编写单元测试。测试应该覆盖模型创建、API 的 GET、POST、PUT、DELETE 请求。使用 Django 的TestCase。”

AI 会生成apps/blog/tests.py文件，里面包含测试用例类，例如PostModelTest和PostAPITest，使用APIClient来模拟 HTTP 请求，并包含setUp方法和多个test_*方法。

步骤 4：代码质量检查与提交

在终端运行预提交钩子，自动格式化并检查生成的代码：

pre-commit run --all-files

根据输出修复任何格式问题或警告。然后，你可以使用 Cursor 内置的 Git 功能或命令行进行提交。

实操心得：

• 提示词要具体：像上面那样，明确指定目录（apps/）、遵循的风格（“本项目现有风格”）、使用的技术（DRF），AI 的输出会精准得多。
• 分步进行：不要要求 AI 一次性完成一个完整的大型功能。像“创建应用 -> 添加 API -> 编写测试”这样分步进行，每步完成后检查并微调，成功率更高，也更容易理解 AI 生成的代码。
• 善用.cursor/rules.mdc：如果你发现 AI 在某些方面总不符合你的习惯（比如总是生成函数视图而不是类视图），可以把这条规则写入rules.mdc文件，AI 在后续生成中会优先遵守。

5. 常见问题与排查技巧实录

在实际使用Cursor-Django模板和与 AI 协作的过程中，你可能会遇到一些典型问题。以下是我踩过的一些坑和解决方案。

5.1 AI 生成的代码无法运行或导入错误

问题现象：Cursor AI 生成了代码，但运行时出现ImportError、NameError或逻辑错误。

排查思路：

1. 检查导入路径：这是最常见的问题。确保 AI 生成的导入语句与你的项目结构匹配。Cursor-Django使用了apps/目录和可能配置的sys.path修改（在config/settings/base.py中通常有sys.path.insert(0, BASE_DIR / 'apps')）。如果 AI 生成了from blog.models import Post，而你的应用在apps/blog，可能需要手动改为from apps.blog.models import Post，或者确认项目的PYTHONPATH设置正确。
2. 检查依赖是否安装：如果 AI 建议使用某个第三方库（比如django-filter），但你的requirements.txt里没有，自然会导致导入失败。在运行前，先检查并安装缺失的依赖。
3. 逐行审查逻辑：不要盲目信任 AI。对于复杂的业务逻辑，尤其是涉及数据库查询、状态变更的部分，要像审查同事的代码一样仔细阅读 AI 生成的代码。AI 可能会误解你的需求或产生“幻觉”（编造不存在的 API）。

解决技巧：

• 在向 AI 提问时，可以加上“请确保导入路径相对于项目根目录my_awesome_project是正确的”这样的约束。
• 使用 Cursor 的“快速修复”（Quick Fix）功能。当代码出现红色波浪线（错误）时，将光标放在错误处，按Cmd/Ctrl + .，AI 可能会提供修正建议。

5.2 Docker 相关问题

问题：数据库连接失败 (django.db.utils.OperationalError)

可能原因与解决：

1. 数据库服务未启动：运行docker-compose ps确认postgres容器状态是Up。
2. 环境变量未正确加载：确保你使用的是正确的.env文件（如.env.dev），并且docker-compose.yml中web服务通过env_file指定了该文件。有时需要重启容器：docker-compose down && docker-compose up -d。
3. 网络问题：在 Docker Compose 中，服务间使用服务名作为主机名。确保 Django 设置中DATABASES['HOST']使用的是postgres（服务名）而不是localhost。
4. 数据库尚未就绪：PostgreSQL 启动需要几秒钟。可以在docker-compose.yml的web服务中添加depends_on和健康检查，或者简单地在启动后等待片刻再运行迁移命令。

5.3 预提交钩子（pre-commit）失败

问题：运行pre-commit run --all-files时，black或isort格式化失败，或者flake8报出很多警告。

解决：

1. 让工具自动修复：大多数格式化工具都提供自动修复选项。你可以运行：

   black . # 格式化所有 Python 文件 isort . # 优化所有导入语句

   然后再次运行pre-commit。
2. 处理flake8警告：flake8的警告需要手动处理。重点关注以E或F开头的错误（语法错误、严重风格问题），W开头的警告可以根据项目规范选择忽略或修复。你可以通过创建.flake8配置文件来忽略某些特定规则。
3. 更新钩子版本：有时钩子本身版本过旧会导致问题。运行pre-commit autoupdate更新所有钩子到最新版本。

5.4 如何定制 AI 行为（.cursor/rules.mdc）

这是提升协作效率的高级技巧。你可以在项目根目录的.cursor/rules.mdc文件中定义规则。

示例规则：

# .cursor/rules.mdc # 项目范围规则 - 本项目使用 Django 4.2 和 Python 3.10。 - 所有模型必须继承自 `core.models.BaseModel`（如果存在）。 - 优先使用基于类的视图（CBV）而不是函数视图（FBV）。 - 所有视图、序列化器、模型都必须包含完整的文档字符串（Docstring）。 - 数据库查询必须使用 `select_related` 或 `prefetch_related` 来避免 N+1 查询问题。 # 针对特定目录的规则 [apps/blog] - 博客相关的 API 端点路径前缀应为 `/api/v1/blog/`。 - `Post` 模型的 `status` 字段只能包含 ['draft', 'published', 'archived'] 中的值。 [config/settings] - 所有敏感配置（如密钥、数据库密码）必须从环境变量读取，不得硬编码。

当你在对应的目录或文件下与 AI 交互时，它会优先遵守这些规则，生成更符合你预期的代码。

最后一点体会：mhgolestan/Cursor-Django项目最大的价值，在于它提供了一种“人机协同”的范式。它教会我们，高效的 AI 编程不是简单地把需求丢给 AI，然后复制粘贴结果。而是需要我们作为开发者，首先搭建一个清晰、规范、意图明确的“舞台”（即项目结构和代码上下文），然后 AI 才能在这个舞台上出色地“表演”。这个项目就是这个舞台的优秀蓝图。通过学习和应用它的思想，你不仅能更快地启动 Django 项目，更能从根本上提升与任何 AI 编程工具协作的效率和产出质量。