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在此基础上额外强调了以下几点详尽的文档字符串Docstrings和类型提示Type Hints在每个模块、类、函数和方法层面都提供了清晰的说明。这相当于为 AI 建立了一个“代码词典”让它能准确理解每个元素的职责、输入和输出。例如一个视图函数不仅会说明它处理什么请求还会用类型提示明确其接收的request对象类型和返回的HttpResponse类型。一致且可预测的代码风格项目严格遵守 PEP 8 和 Django 的编码约定。变量命名、导入顺序、缩进格式都高度统一。这种一致性降低了 AI 的“认知负荷”让它更容易识别模式并生成风格匹配的新代码。模块化的项目结构项目采用了清晰的应用App分离原则。将核心业务逻辑、用户认证、API 接口等分别放在不同的应用中。这种结构本身就对 AI 有很强的提示作用当你在users/目录下要求 AI 生成代码时它自然会倾向于生成与用户管理相关的代码而不是混淆其他模块的功能。环境与配置的显式分离严格区分开发、测试和生产环境的配置。这通过不同的.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 │ └── ... └── ...核心亮点解析.cursor/目录这是项目的灵魂所在。你可以在这里放置rules.mdc文件定义针对本项目的 AI 助手行为规则。例如你可以编写规则“在本项目中所有模型类必须继承自core.models.BaseModel”或者“API 视图优先使用 DRF 的GenericAPIView”。当你在项目内激活 Cursor 的 AI 功能时它会读取这些规则使生成的代码自动符合你的项目规范。拆分的settings/模块将设置按环境base, dev, prod拆分是 Django 的最佳实践。Cursor-Django将其显式化。当 AI 需要生成或修改设置时你可以明确指示它“更新config/settings/dev.py中的数据库配置”AI 会精准定位避免误改生产环境配置。统一的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_length15, blankTrue, nullTrue, help_text_(Users contact phone number. Optional.) ) avatar models.ImageField( _(avatar), upload_touser_avatars/%Y/%m/%d/, blankTrue, nullTrue, help_text_(Profile picture of the user.) ) email_verified models.BooleanField( _(email verified), defaultFalse, help_text_(Designates whether the users 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方法都标注了返回类型- strAI 在调用或修改这些方法时能明确知道会得到什么类型的值。继承关系明确显示继承了AbstractUser和BaseModelAI 会知道这个模型拥有 Django 内置的用户字段以及BaseModel中可能定义的如created_at,updated_at等公共字段。当你在 Cursor 中提问“为User模型添加一个记录最后登录 IP 地址的字段”AI 会基于上述上下文很可能生成一个像last_login_ip models.GenericIPAddressField(blankTrue, nullTrue)这样符合现有代码风格的字段定义。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: fredis://{env(REDIS_HOST, defaultredis)}:{env(REDIS_PORT, default6379)}/1, # 引用环境变量 OPTIONS: { CLIENT_CLASS: django_redis.client.DefaultClient, } } }AI 知道REDIS_HOST和REDIS_PORT应该来自环境变量并且知道在 Docker Compose 网络中服务名redis可以作为主机名。这种上下文感知能力极大地提升了生成代码的可用性。4. 实操过程与核心环节实现4.1 从零开始基于 Cursor-Django 初始化项目假设我们想创建一个名为my_awesome_project的新项目。获取模板最直接的方式是使用 Cursor 的“Clone Template”功能如果你有该项目的访问权限或者用 Git 命令克隆。git clone https://github.com/mhgolestan/Cursor-Django.git my_awesome_project cd my_awesome_project环境变量配置复制环境变量示例文件并根据你的本地环境进行修改。cp .env.example .env.dev # 使用编辑器比如 Cursor 或 VSCode打开 .env.dev修改数据库密码、密钥等。 # 例如 # POSTGRES_DBmy_awesome_db # POSTGRES_PASSWORDyour_secure_password_here # SECRET_KEYyour-django-secret-key-here启动 Docker 服务这是确保所有依赖数据库、缓存就位的关键一步。docker-compose up -d postgres redis # 先启动依赖服务 # 等待几秒确保数据库已启动并可连接安装 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 --settingsconfig.settings.dev python manage.py createsuperuser --settingsconfig.settings.dev运行开发服务器# Docker 方式 docker-compose up web # 前端会输出日志 # 本地虚拟环境方式 python manage.py runserver --settingsconfig.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 可能会执行的操作在apps/目录下创建blog/文件夹及__init__.py。生成apps/blog/models.py其中Post模型会继承自core.models.BaseModel如果项目中有并包含你要求的字段每个字段都有合适的verbose_name和help_text。生成apps/blog/admin.py注册Post模型到 Django 管理后台并可能添加一些列表过滤器或搜索字段。生成apps/blog/views.py包含基于类视图如ListView,DetailView的视图。生成apps/blog/urls.py定义 URL 路由。可能会提示你运行makemigrations和migrate命令。步骤 2为博客添加 REST API继续在 Cursor 中提问“为刚创建的blog应用中的Post模型使用 Django REST Framework 创建一套完整的 CRUD API列表、详情、创建、更新、删除。包括序列化器Serializer、视图集ViewSet和路由注册。确保 API 遵循本项目的最佳实践。”Cursor AI 可能会生成apps/blog/serializers.py定义PostSerializer可能包含字段验证、作者字段的只读处理等。更新apps/blog/views.py或新建api/views.py创建PostViewSet继承自ModelViewSet并设置queryset、serializer_class可能还会添加权限类如IsAuthenticatedOrReadOnly。更新apps/blog/urls.py使用 DRF 的DefaultRouter或SimpleRouter来注册视图集的路由。可能会更新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/、遵循的风格“本项目现有风格”、使用的技术DRFAI 的输出会精准得多。分步进行不要要求 AI 一次性完成一个完整的大型功能。像“创建应用 - 添加 API - 编写测试”这样分步进行每步完成后检查并微调成功率更高也更容易理解 AI 生成的代码。善用.cursor/rules.mdc如果你发现 AI 在某些方面总不符合你的习惯比如总是生成函数视图而不是类视图可以把这条规则写入rules.mdc文件AI 在后续生成中会优先遵守。5. 常见问题与排查技巧实录在实际使用Cursor-Django模板和与 AI 协作的过程中你可能会遇到一些典型问题。以下是我踩过的一些坑和解决方案。5.1 AI 生成的代码无法运行或导入错误问题现象Cursor AI 生成了代码但运行时出现ImportError、NameError或逻辑错误。排查思路检查导入路径这是最常见的问题。确保 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设置正确。检查依赖是否安装如果 AI 建议使用某个第三方库比如django-filter但你的requirements.txt里没有自然会导致导入失败。在运行前先检查并安装缺失的依赖。逐行审查逻辑不要盲目信任 AI。对于复杂的业务逻辑尤其是涉及数据库查询、状态变更的部分要像审查同事的代码一样仔细阅读 AI 生成的代码。AI 可能会误解你的需求或产生“幻觉”编造不存在的 API。解决技巧在向 AI 提问时可以加上“请确保导入路径相对于项目根目录my_awesome_project是正确的”这样的约束。使用 Cursor 的“快速修复”Quick Fix功能。当代码出现红色波浪线错误时将光标放在错误处按Cmd/Ctrl .AI 可能会提供修正建议。5.2 Docker 相关问题问题数据库连接失败 (django.db.utils.OperationalError)可能原因与解决数据库服务未启动运行docker-compose ps确认postgres容器状态是Up。环境变量未正确加载确保你使用的是正确的.env文件如.env.dev并且docker-compose.yml中web服务通过env_file指定了该文件。有时需要重启容器docker-compose down docker-compose up -d。网络问题在 Docker Compose 中服务间使用服务名作为主机名。确保 Django 设置中DATABASES[HOST]使用的是postgres服务名而不是localhost。数据库尚未就绪PostgreSQL 启动需要几秒钟。可以在docker-compose.yml的web服务中添加depends_on和健康检查或者简单地在启动后等待片刻再运行迁移命令。5.3 预提交钩子pre-commit失败问题运行pre-commit run --all-files时black或isort格式化失败或者flake8报出很多警告。解决让工具自动修复大多数格式化工具都提供自动修复选项。你可以运行black . # 格式化所有 Python 文件 isort . # 优化所有导入语句然后再次运行pre-commit。处理flake8警告flake8的警告需要手动处理。重点关注以E或F开头的错误语法错误、严重风格问题W开头的警告可以根据项目规范选择忽略或修复。你可以通过创建.flake8配置文件来忽略某些特定规则。更新钩子版本有时钩子本身版本过旧会导致问题。运行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 来避免 N1 查询问题。 # 针对特定目录的规则 [apps/blog] - 博客相关的 API 端点路径前缀应为 /api/v1/blog/。 - Post 模型的 status 字段只能包含 [draft, published, archived] 中的值。 [config/settings] - 所有敏感配置如密钥、数据库密码必须从环境变量读取不得硬编码。当你在对应的目录或文件下与 AI 交互时它会优先遵守这些规则生成更符合你预期的代码。最后一点体会mhgolestan/Cursor-Django项目最大的价值在于它提供了一种“人机协同”的范式。它教会我们高效的 AI 编程不是简单地把需求丢给 AI然后复制粘贴结果。而是需要我们作为开发者首先搭建一个清晰、规范、意图明确的“舞台”即项目结构和代码上下文然后 AI 才能在这个舞台上出色地“表演”。这个项目就是这个舞台的优秀蓝图。通过学习和应用它的思想你不仅能更快地启动 Django 项目更能从根本上提升与任何 AI 编程工具协作的效率和产出质量。
Cursor-Django项目：AI辅助编程与Django开发规范融合实践
发布时间：2026/5/19 3:32:55
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在此基础上额外强调了以下几点详尽的文档字符串Docstrings和类型提示Type Hints在每个模块、类、函数和方法层面都提供了清晰的说明。这相当于为 AI 建立了一个“代码词典”让它能准确理解每个元素的职责、输入和输出。例如一个视图函数不仅会说明它处理什么请求还会用类型提示明确其接收的request对象类型和返回的HttpResponse类型。一致且可预测的代码风格项目严格遵守 PEP 8 和 Django 的编码约定。变量命名、导入顺序、缩进格式都高度统一。这种一致性降低了 AI 的“认知负荷”让它更容易识别模式并生成风格匹配的新代码。模块化的项目结构项目采用了清晰的应用App分离原则。将核心业务逻辑、用户认证、API 接口等分别放在不同的应用中。这种结构本身就对 AI 有很强的提示作用当你在users/目录下要求 AI 生成代码时它自然会倾向于生成与用户管理相关的代码而不是混淆其他模块的功能。环境与配置的显式分离严格区分开发、测试和生产环境的配置。这通过不同的.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 │ └── ... └── ...核心亮点解析.cursor/目录这是项目的灵魂所在。你可以在这里放置rules.mdc文件定义针对本项目的 AI 助手行为规则。例如你可以编写规则“在本项目中所有模型类必须继承自core.models.BaseModel”或者“API 视图优先使用 DRF 的GenericAPIView”。当你在项目内激活 Cursor 的 AI 功能时它会读取这些规则使生成的代码自动符合你的项目规范。拆分的settings/模块将设置按环境base, dev, prod拆分是 Django 的最佳实践。Cursor-Django将其显式化。当 AI 需要生成或修改设置时你可以明确指示它“更新config/settings/dev.py中的数据库配置”AI 会精准定位避免误改生产环境配置。统一的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_length15, blankTrue, nullTrue, help_text_(Users contact phone number. Optional.) ) avatar models.ImageField( _(avatar), upload_touser_avatars/%Y/%m/%d/, blankTrue, nullTrue, help_text_(Profile picture of the user.) ) email_verified models.BooleanField( _(email verified), defaultFalse, help_text_(Designates whether the users 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方法都标注了返回类型- strAI 在调用或修改这些方法时能明确知道会得到什么类型的值。继承关系明确显示继承了AbstractUser和BaseModelAI 会知道这个模型拥有 Django 内置的用户字段以及BaseModel中可能定义的如created_at,updated_at等公共字段。当你在 Cursor 中提问“为User模型添加一个记录最后登录 IP 地址的字段”AI 会基于上述上下文很可能生成一个像last_login_ip models.GenericIPAddressField(blankTrue, nullTrue)这样符合现有代码风格的字段定义。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: fredis://{env(REDIS_HOST, defaultredis)}:{env(REDIS_PORT, default6379)}/1, # 引用环境变量 OPTIONS: { CLIENT_CLASS: django_redis.client.DefaultClient, } } }AI 知道REDIS_HOST和REDIS_PORT应该来自环境变量并且知道在 Docker Compose 网络中服务名redis可以作为主机名。这种上下文感知能力极大地提升了生成代码的可用性。4. 实操过程与核心环节实现4.1 从零开始基于 Cursor-Django 初始化项目假设我们想创建一个名为my_awesome_project的新项目。获取模板最直接的方式是使用 Cursor 的“Clone Template”功能如果你有该项目的访问权限或者用 Git 命令克隆。git clone https://github.com/mhgolestan/Cursor-Django.git my_awesome_project cd my_awesome_project环境变量配置复制环境变量示例文件并根据你的本地环境进行修改。cp .env.example .env.dev # 使用编辑器比如 Cursor 或 VSCode打开 .env.dev修改数据库密码、密钥等。 # 例如 # POSTGRES_DBmy_awesome_db # POSTGRES_PASSWORDyour_secure_password_here # SECRET_KEYyour-django-secret-key-here启动 Docker 服务这是确保所有依赖数据库、缓存就位的关键一步。docker-compose up -d postgres redis # 先启动依赖服务 # 等待几秒确保数据库已启动并可连接安装 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 --settingsconfig.settings.dev python manage.py createsuperuser --settingsconfig.settings.dev运行开发服务器# Docker 方式 docker-compose up web # 前端会输出日志 # 本地虚拟环境方式 python manage.py runserver --settingsconfig.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 可能会执行的操作在apps/目录下创建blog/文件夹及__init__.py。生成apps/blog/models.py其中Post模型会继承自core.models.BaseModel如果项目中有并包含你要求的字段每个字段都有合适的verbose_name和help_text。生成apps/blog/admin.py注册Post模型到 Django 管理后台并可能添加一些列表过滤器或搜索字段。生成apps/blog/views.py包含基于类视图如ListView,DetailView的视图。生成apps/blog/urls.py定义 URL 路由。可能会提示你运行makemigrations和migrate命令。步骤 2为博客添加 REST API继续在 Cursor 中提问“为刚创建的blog应用中的Post模型使用 Django REST Framework 创建一套完整的 CRUD API列表、详情、创建、更新、删除。包括序列化器Serializer、视图集ViewSet和路由注册。确保 API 遵循本项目的最佳实践。”Cursor AI 可能会生成apps/blog/serializers.py定义PostSerializer可能包含字段验证、作者字段的只读处理等。更新apps/blog/views.py或新建api/views.py创建PostViewSet继承自ModelViewSet并设置queryset、serializer_class可能还会添加权限类如IsAuthenticatedOrReadOnly。更新apps/blog/urls.py使用 DRF 的DefaultRouter或SimpleRouter来注册视图集的路由。可能会更新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/、遵循的风格“本项目现有风格”、使用的技术DRFAI 的输出会精准得多。分步进行不要要求 AI 一次性完成一个完整的大型功能。像“创建应用 - 添加 API - 编写测试”这样分步进行每步完成后检查并微调成功率更高也更容易理解 AI 生成的代码。善用.cursor/rules.mdc如果你发现 AI 在某些方面总不符合你的习惯比如总是生成函数视图而不是类视图可以把这条规则写入rules.mdc文件AI 在后续生成中会优先遵守。5. 常见问题与排查技巧实录在实际使用Cursor-Django模板和与 AI 协作的过程中你可能会遇到一些典型问题。以下是我踩过的一些坑和解决方案。5.1 AI 生成的代码无法运行或导入错误问题现象Cursor AI 生成了代码但运行时出现ImportError、NameError或逻辑错误。排查思路检查导入路径这是最常见的问题。确保 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设置正确。检查依赖是否安装如果 AI 建议使用某个第三方库比如django-filter但你的requirements.txt里没有自然会导致导入失败。在运行前先检查并安装缺失的依赖。逐行审查逻辑不要盲目信任 AI。对于复杂的业务逻辑尤其是涉及数据库查询、状态变更的部分要像审查同事的代码一样仔细阅读 AI 生成的代码。AI 可能会误解你的需求或产生“幻觉”编造不存在的 API。解决技巧在向 AI 提问时可以加上“请确保导入路径相对于项目根目录my_awesome_project是正确的”这样的约束。使用 Cursor 的“快速修复”Quick Fix功能。当代码出现红色波浪线错误时将光标放在错误处按Cmd/Ctrl .AI 可能会提供修正建议。5.2 Docker 相关问题问题数据库连接失败 (django.db.utils.OperationalError)可能原因与解决数据库服务未启动运行docker-compose ps确认postgres容器状态是Up。环境变量未正确加载确保你使用的是正确的.env文件如.env.dev并且docker-compose.yml中web服务通过env_file指定了该文件。有时需要重启容器docker-compose down docker-compose up -d。网络问题在 Docker Compose 中服务间使用服务名作为主机名。确保 Django 设置中DATABASES[HOST]使用的是postgres服务名而不是localhost。数据库尚未就绪PostgreSQL 启动需要几秒钟。可以在docker-compose.yml的web服务中添加depends_on和健康检查或者简单地在启动后等待片刻再运行迁移命令。5.3 预提交钩子pre-commit失败问题运行pre-commit run --all-files时black或isort格式化失败或者flake8报出很多警告。解决让工具自动修复大多数格式化工具都提供自动修复选项。你可以运行black . # 格式化所有 Python 文件 isort . # 优化所有导入语句然后再次运行pre-commit。处理flake8警告flake8的警告需要手动处理。重点关注以E或F开头的错误语法错误、严重风格问题W开头的警告可以根据项目规范选择忽略或修复。你可以通过创建.flake8配置文件来忽略某些特定规则。更新钩子版本有时钩子本身版本过旧会导致问题。运行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 来避免 N1 查询问题。 # 针对特定目录的规则 [apps/blog] - 博客相关的 API 端点路径前缀应为 /api/v1/blog/。 - Post 模型的 status 字段只能包含 [draft, published, archived] 中的值。 [config/settings] - 所有敏感配置如密钥、数据库密码必须从环境变量读取不得硬编码。当你在对应的目录或文件下与 AI 交互时它会优先遵守这些规则生成更符合你预期的代码。最后一点体会mhgolestan/Cursor-Django项目最大的价值在于它提供了一种“人机协同”的范式。它教会我们高效的 AI 编程不是简单地把需求丢给 AI然后复制粘贴结果。而是需要我们作为开发者首先搭建一个清晰、规范、意图明确的“舞台”即项目结构和代码上下文然后 AI 才能在这个舞台上出色地“表演”。这个项目就是这个舞台的优秀蓝图。通过学习和应用它的思想你不仅能更快地启动 Django 项目更能从根本上提升与任何 AI 编程工具协作的效率和产出质量。
相关文章
基于MCP协议为Gemini模型构建安全可控的外部工具链
1. 项目概述：当MCP遇上Gemini，一个AI代理的“瑞士军刀”诞生了如果你最近在折腾AI Agent（智能体）或者RAG（检索增强生成）应用，大概率听说过“Model Context Protocol”，也就是MCP。简…
Unity与AI智能体通信框架设计：从原理到实战集成指南
1. 项目概述：一个连接Unity与AI智能体的客户端框架最近在探索如何将大型语言模型（LLM）这类AI智能体引入到Unity游戏或仿真环境中，发现了一个挺有意思的开源项目——nuskey8/UnityAgentClient。简单来说，这是一个专门为…
Emacs实时语法检查：Flymake与Flymake-cursor配置全攻略
1. 项目概述：Emacs 编辑器的实时语法检查伴侣如果你是一个 Emacs 用户，并且主要用它来写代码，那么你一定经历过这样的场景：写下一行代码，保存，切换到终端运行编译或语法检查命令，看到一堆错误提…
![OctoBase源码解析：深入理解Rust实现的本地优先数据库引擎 [特殊字符]](images/php.jpg)
OctoBase源码解析：深入理解Rust实现的本地优先数据库引擎 [特殊字符]
OctoBase源码解析：深入理解Rust实现的本地优先数据库引擎 🐙 【免费下载链接】OctoBase 🐙 OctoBase is the open-source database behind AFFiNE, local-first, yet collaborative. A light-weight, scalable, data engine written in Rust.…
CGDB性能优化：大型项目调试的10个终极技巧 [特殊字符]
CGDB性能优化：大型项目调试的10个终极技巧 🚀 【免费下载链接】cgdb Console front-end to the GNU debugger 项目地址: https://gitcode.com/gh_mirrors/cg/cgdb CGDB作为一款轻量级的GNU调试器控制台前端，在大型项目调试中展现出了卓…
AI复活尼安德特人：史前思维模拟的伦理审查
一、AI复活尼安德特人：从分子到思维的技术跃迁当我们谈论AI“复活”尼安德特人时，早已超越了科幻电影中克隆完整生物体的想象。如今的技术路径呈现出分层递进的特征：从宾夕法尼亚大学团队实现的分子层面“复活”——利用AI从尼安德特人蛋白质…
金字塔建造算法：用现代工具验证古代工程奇迹
一、跨越时空的工程对话 当软件测试从业者盯着屏幕上的代码缺陷报告时，或许很难将自己的工作与四千六百年前吉萨高原上的巨石堆砌联系起来。但从工程逻辑的本质来看，两者却有着惊人的相似性——都是在复杂系统中追求精度、效率与可靠性，都需…
LISN：EMC测试中的“守门员”，如何精准捕获传导干扰？
1. LISN：EMC测试中的“守门员”是什么？ 想象一下足球比赛中的守门员，他的任务是阻止对方进球，同时确保己方球门的安全。在EMC（电磁兼容性）测试中，LISN（线路阻抗稳定网络）…
PCIe 4.0/5.0硬件设计必看：你的Rx EQ和Package如何影响压力眼图校准？
PCIe 4.0/5.0硬件设计中的Rx EQ与封装优化：压力眼图校准的关键考量 在高速串行接口设计中，PCIe 4.0/5.0的信号完整性挑战将硬件工程师的注意力聚焦于接收端均衡(Rx EQ)和封装设计的微妙平衡。当信号速率突破16GT/s大关，传统的"设计-验证…
5分钟快速上手：biliTickerBuy开源工具助你轻松抢购B站会员购热门票务
5分钟快速上手：biliTickerBuy开源工具助你轻松抢购B站会员购热门票务 【免费下载链接】biliTickerBuy b站会员购购票辅助工具 项目地址: https://gitcode.com/GitHub_Trending/bi/biliTickerBuy biliTickerBuy是一款专为B站会员购平台设计的开源辅助工具&…
一口气讲清楚 Monorepo、Turborepo、pnpm、Changesets 到底是什么？
你肯定遇到过这种情况：项目里同时有前端、后端、公共组件，放在一个仓库嫌乱，拆成多个仓库又改一个公共函数要在五个项目里各改一遍。于是出现了 Monorepo、Turborepo、pnpm、Changesets 这四个词。它们不是互相替代，而是分别解决工…
从ok-skills项目解析技能树：设计理念、技术实现与工程实践
1. 项目概述与核心价值最近在GitHub上看到一个挺有意思的项目，叫“ok-skills”。光看这个名字，可能有点摸不着头脑，但点进去一看，发现这是一个关于“技能树”或“知识图谱”的开源项目。简单来说，它试图用一种结构化的…
【实用小程序】超轻量级文件上传下载中心 (File Download Server)
站内源码及jar包下载 一、项目概述 文件下载中心一个基于 Java 内置 HTTP 服务器（com.sun.net.httpserver）构建的轻量级文件管理服务。它零第三方依赖，单 JAR 包即可运行，适合在内网环境或临时场景中快速搭建文件共享站点。 你的团队需要临时共享一批日志文件或交付物，…
py每日spider案例之某website之xin东方选课搜索接口(难度一般 扣取代码即可)
加密位置: 逆向接口参数: 逆向接口: const g = globalThis; g.window = g; g.self = g; g.location = {<
终极轻量级Android文本编辑器Markor：多格式笔记应用完全指南
终极轻量级Android文本编辑器Markor：多格式笔记应用完全指南 【免费下载链接】markor Text editor - Notes & ToDo (for Android) - Markdown, todo.txt, plaintext, math, .. 项目地址: https://gitcode.com/gh_mirrors/ma/markor 在移动设备上寻找一款…
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项目地址:…
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南 【免费下载链接】STL-Volume-Model-Calculator STL Volume Model Calculator Python 项目地址: https://gitcode.com/gh_mirrors/st/STL-Volume-Model-Calculator 你是否曾经为3D打印项目…
通过Taotoken CLI工具一键配置团队开发环境与模型密钥
通过Taotoken CLI工具一键配置团队开发环境与模型密钥 1. CLI工具安装与基本使用 Taotoken提供的CLI工具可通过npm全局安装或直接使用npx运行。对于需要频繁使用CLI的团队，推荐全局安装： npm install -g taotoken/taotoken对于临时使用或项目级配置&a…