你是不是也遇到过这样的场景用 AI 编程工具生成了几百行代码看着功能都实现了但一运行就报错或者代码风格混乱得像“缝合怪”后期维护无从下手又或者你精心设计的提示词AI 却总是“跑偏”生成的结果和你预想的南辕北辙这背后的问题不是 AI 不够强而是我们与 AI 协作的方式还停留在“盲盒式编程”的原始阶段。你输入一个模糊的需求AI 输出一个不确定的结果反复调试效率低下。最近吴恩达教授在 2026 年最新分享中系统性地提出了“规范驱动开发”的理念。这并非一个全新的编程语言或框架而是一套将 AI 编程从“随机探索”升级为“标准化生产”的方法论和工作流。它要解决的正是如何让 AI 成为你团队里那个“懂规矩、守纪律、可预期”的资深工程师而不是一个充满惊喜或惊吓的“魔法黑盒”。本文将带你从零开始实战这套SDD工作流。我们不会空谈理论而是手把手教你如何建立标准化的 AI 编程流程告别“盲盒式编程”真正将 AI 的潜力转化为稳定、可交付的生产力。文章末尾我们也会提供完整的课件代码供你直接实践。1. 规范驱动开发告别“盲盒式编程”的核心方法论“盲盒式编程”是很多开发者使用 AI 辅助编码时的共同痛点。你给 AI 一个任务比如“写一个用户登录的 API”AI 可能会用 Flask 写也可能用 FastAPI可能用 JWT 认证也可能用 Session代码风格可能遵循 PEP 8也可能随心所欲。每次生成的结果都像开盲盒充满了不确定性。规范驱动开发的核心思想就是通过预先定义一套清晰、明确、可执行的“规范”来约束和引导 AI 的代码生成行为确保输出结果的一致性、可维护性和高质量。这听起来有点像“契约测试”或“API 设计先行”但 SDD 将其扩展到了整个开发工作流并与 AI 工具深度集成。它的关键转变在于从“描述问题”到“定义规范”你不再只是告诉 AI“做什么”而是清晰地告诉它“按照什么标准来做”。从“一次性交互”到“结构化工作流”将一次性的、模糊的提示拆解为一系列标准化的、可复用的步骤。从“结果验收”到“过程可控”在代码生成之前规范就已经定义了成功的标准。一个典型的 SDD 工作流包含几个核心环节需求规约 - 架构与接口设计 - 代码生成规范 - 测试与验证规范。AI 在整个流程中是严格遵循这些既定规范的执行者。2. 环境准备打造你的 SDD 实战工作台在开始构建工作流之前我们需要准备好“战场”。SDD 不依赖于某个特定的 IDE但高效的工具体系能让你事半功倍。我们将围绕Cursor和VSCode这两大主流 AI 编程环境进行配置。2.1 核心工具选择与安装AI 编程 IDE二选一或组合使用Cursor内置了强大的 AI 模型如 Claude 3.5 Sonnet深度集成了聊天、编辑、自动完成功能对 SDD 工作流支持非常友好。它是我们本次实战的首选。VSCode 插件如果你更习惯 VSCode可以通过安装Cursor插件或Claude、Codeium、GitHub Copilot等 AI 编程插件来实现类似功能。版本控制Git是必须的。SDD 强调过程的可追溯性每一次规范的变更、AI 生成的代码都需要通过 Git 进行管理。项目管理与文档建议使用Markdown文件在项目根目录管理你的规范文档。例如SPECIFICATION.md、ARCHITECTURE.md、API_DESIGN.md。2.2 Cursor 基础配置与项目初始化假设我们选择 Cursor 作为主战场。首先为我们的 SDD 实战项目创建一个干净的环境。# 1. 创建项目目录 mkdir sdd-practical-tutorial cd sdd-practical-tutorial # 2. 初始化 Git 仓库至关重要 git init # 3. 创建规范文档目录 mkdir -p docs/specs # 4. 创建示例项目源码目录我们以一个简单的 Python Web 服务为例 mkdir -p src/app接下来在 Cursor 中打开这个项目文件夹。你需要熟悉 Cursor 的几个核心功能区域Chat 面板与 AI 进行结构化对话输入规范的地方。编辑器查看和编辑代码。终端运行命令。版本控制查看 Git 变更。3. 第一步从模糊需求到精确规约我们以一个具体的例子贯穿全文构建一个简单的“待办事项Todo管理 API 服务”。传统的 AI 提示可能是“用 FastAPI 写一个 Todo API。” 这太模糊了。在 SDD 中我们的第一步是创建需求规约文档。在docs/specs/requirements.md中我们这样写# 待办事项TodoAPI 服务需求规约 ## 1. 概述 本项目旨在提供一个 RESTful API 服务用于管理个人待办事项Todo Items。核心功能包括创建、读取、更新、删除和查询待办事项。 ## 2. 功能需求 ### 2.1 待办事项模型 一个待办事项应包含以下字段 - id: 唯一标识符整数自增 - title: 标题字符串必填最大长度100字符 - description: 详细描述字符串可选最大长度500字符 - completed: 完成状态布尔值默认 false - created_at: 创建时间时间戳自动生成 - updated_at: 更新时间时间戳自动更新 ### 2.2 API 端点 1. **POST /todos**: 创建新的待办事项。 2. **GET /todos**: 获取所有待办事项列表支持分页和按完成状态过滤。 3. **GET /todos/{id}**: 根据 ID 获取单个待办事项详情。 4. **PUT /todos/{id}**: 更新指定待办事项的全部信息。 5. **PATCH /todos/{id}**: 部分更新指定待办事项如标记完成。 6. **DELETE /todos/{id}**: 删除指定待办事项。 ## 3. 非功能需求 - **框架**: 使用 FastAPI。 - **数据库**: 使用 SQLite 进行本地开发方便演示但代码结构应易于切换至 PostgreSQL 或 MySQL。 - **数据验证**: 使用 Pydantic 模型进行请求/响应数据的严格验证。 - **错误处理**: 统一的错误响应格式JSON包含 HTTP 状态码和错误信息。 - **代码风格**: 遵循 PEP 8使用 black 和 isort 进行格式化。这份文档就是我们的第一层规范。它清晰、无歧义地定义了“做什么”。接下来我们要把这个文档“喂”给 AI。在 Cursor 的 Chat 面板中我们可以这样输入**上下文**请阅读项目根目录下 docs/specs/requirements.md 文件中的需求规约。 **任务**基于此规约为我们设计初步的项目架构并列出需要创建的核心 Python 模块文件及其职责。请以 Markdown 列表形式输出。AI 会根据规约输出类似如下的架构建议这就进入了下一阶段。4. 第二步定义架构与接口规范AI 给出的架构建议可能比较泛。我们需要将其具体化为第二层规范架构与接口设计文档。在docs/specs/architecture.md中定义# 项目架构与接口设计规范 ## 1. 项目结构sdd-practical-tutorial/ ├── src/ │ └── app/ │ ├──init.py │ ├── main.py # FastAPI 应用实例和路由总入口 │ ├── models.py # Pydantic 模型定义请求/响应 │ ├── schemas.py # SQLAlchemy 数据模型定义可选如果不用ORM可省略 │ ├── crud.py # 数据库增删改查操作函数 │ ├── database.py # 数据库连接与会话管理 │ └── routers/ │ └── todos.py # 待办事项相关的路由 ├── docs/ │ └── specs/ # 规范文档 ├── tests/ # 测试文件 ├── requirements.txt # Python 依赖 └── .env.example # 环境变量示例## 2. API 接口详细规范OpenAPI 风格 ### 端点POST /todos - **描述**: 创建新待办事项。 - **请求体**: json { title: string, required, maxLength100, description: string, optional, maxLength500, completed: boolean, optional, defaultfalse }成功响应 (201 Created):{ id: integer, title: string, description: string, completed: boolean, created_at: string (ISO 8601), updated_at: string (ISO 8601) }错误响应:400 Bad Request: 请求体验证失败。500 Internal Server Error: 服务器内部错误。其他端点类似此处省略以节省篇幅实际项目中需完整定义3. 数据库规范使用SQLAlchemy作为 ORM对象关系映射工具。使用Alembic进行数据库迁移管理。表名todos。所有时间字段使用 UTC 时间。现在我们有了更具体的蓝图。接下来我们可以指令 AI 根据这份架构规范生成基础的项目骨架代码。注意我们不是让它直接写业务逻辑而是先搭建符合规范的结构。 在 Cursor Chat 中输入上下文已阅读requirements.md和architecture.md。当前任务请严格按照architecture.md中定义的项目结构在src/app/目录下创建所有指定的空 Python 文件__init__.py,main.py,models.py等。然后在main.py中初始化一个最基本的 FastAPI 应用实例并创建一个健康检查端点GET /health用于验证服务是否启动。请输出具体的代码。## 5. 第三步编写代码生成规范与提示词模板 这是 SDD 最核心的一环。我们不能每次都对 AI 说“写一个创建 Todo 的端点”。我们需要一个可复用的 **提示词模板**这个模板本身也是规范的一部分。 我们在 docs/specs/coding_standards.md 中定义代码规范 markdown # 代码生成与质量标准 ## 1. 通用编程规范 - **语言**: Python 3.9。 - **格式化**: 使用 black 和 isort。生成代码后必须运行 black . 和 isort . 进行格式化。 - **导入排序**: 标准库 - 第三方库 - 本地模块每组之间空一行。 - **类型提示**: 必须为所有函数参数和返回值添加类型提示Type Hints。 - **错误处理**: 使用明确的 try...except 块捕获特定异常并记录日志。 - **日志记录**: 使用 Python 内置的 logging 模块级别设置为 INFO。 ## 2. FastAPI 特定规范 - **依赖注入**: 对于数据库会话等资源使用 FastAPI 的 Depends。 - **响应模型**: 必须使用 response_model 参数确保响应数据结构符合 Pydantic 模型。 - **状态码**: 严格使用正确的 HTTP 状态码如 201 用于创建成功。 - **路径操作函数命名**: 使用 create_item, read_item, update_item, delete_item 等清晰动词。 ## 3. 提示词模板用于生成 CRUD 端点 当需要生成一个新的 API 端点时请遵循以下模板填充信息角色你是一名资深后端工程师严格遵守项目规范。上下文项目使用 FastAPI SQLAlchemy SQLite。项目结构见architecture.md代码规范见本文件。任务为[实体名]实现[HTTP方法] [端点路径]端点。输入Pydantic 模型此处粘贴或描述请求和响应模型定义数据库模型此处粘贴或描述 SQLAlchemy 模型定义业务逻辑描述简要说明这个端点要做什么任何特殊规则输出要求在正确的文件通常是src/app/routers/[实体名].py中实现路径操作函数。函数必须包含完整的类型提示、文档字符串docstring。必须包含错误处理如查找不到资源返回404。必须使用依赖注入获取数据库会话。代码生成后请说明需要如何将其注册到主应用main.py中。有了这个模板当我们接下来需要实现POST /todos时我们的提示词就变得极其规范和高效。我们不再进行开放式聊天而是“填充模板”。6. 完整实战生成符合规范的 Todo 创建端点现在让我们运用以上所有规范生成第一个完整的业务端点。步骤 1定义数据模型首先我们指令 AI 创建 Pydantic 和 SQLAlchemy 模型。在 Cursor Chat 中我们可以引用规范文件并给出精确指令。**上下文**项目规范见 requirements.md 和 coding_standards.md。 **任务**请在 src/app/models.py 中定义用于 Todo 的 Pydantic 模型TodoCreate, TodoUpdate, TodoInDB。然后在 src/app/schemas.py 中定义 SQLAlchemy 的 Todo 模型类。请确保字段类型、约束与需求规约完全一致并添加类型提示。AI 生成的models.py可能如下# src/app/models.py from datetime import datetime from typing import Optional from pydantic import BaseModel, Field class TodoBase(BaseModel): title: str Field(..., max_length100, description待办事项标题) description: Optional[str] Field(None, max_length500, description详细描述) completed: bool Field(False, description是否已完成) class TodoCreate(TodoBase): pass class TodoUpdate(BaseModel): title: Optional[str] Field(None, max_length100) description: Optional[str] Field(None, max_length500) completed: Optional[bool] None class TodoInDB(TodoBase): id: int created_at: datetime updated_at: datetime class Config: from_attributes True # 替代旧的 orm_mode TrueAI 生成的schemas.py可能如下# src/app/schemas.py from sqlalchemy import Boolean, Column, DateTime, Integer, String, Text from sqlalchemy.sql import func from src.app.database import Base # 假设我们已经有了 Base class Todo(Base): __tablename__ todos id Column(Integer, primary_keyTrue, indexTrue) title Column(String(100), nullableFalse) description Column(Text, nullableTrue) completed Column(Boolean, defaultFalse) created_at Column(DateTime(timezoneTrue), server_defaultfunc.now()) updated_at Column(DateTime(timezoneTrue), onupdatefunc.now())步骤 2生成数据库连接和 CRUD 基础接着生成数据库配置和基础的 CRUD 操作函数。**上下文**已有 schemas.py 中的 Todo 模型。 **任务**请创建 src/app/database.py 文件配置 SQLAlchemy 引擎和会话本地化。然后创建 src/app/crud.py 文件实现针对 Todo 模型的创建、读取单个和多个、更新、删除等基础函数。请严格遵循 coding_standards.md 中的错误处理和日志规范。步骤 3应用代码生成模板实现端点现在使用我们定义的提示词模板来生成POST /todos端点。在 Cursor Chat 中我们这样输入**角色**你是一名资深后端工程师严格遵守项目规范。 **上下文**项目使用 FastAPI SQLAlchemy SQLite。项目结构见 architecture.md代码规范见 coding_standards.md。已存在 models.py 和 crud.py。 **任务**为 Todo 实现 POST /todos 端点。 **输入** 1. **Pydantic 模型**请求体使用 TodoCreate成功响应201使用 TodoInDB。 2. **数据库模型**使用 schemas.Todo。 3. **业务逻辑描述**接收 JSON 请求体验证数据通过 CRUD 函数创建新的 Todo 记录到数据库返回创建成功的 Todo 信息包含生成的 id 和时间戳。 **输出要求** 1. 在 src/app/routers/todos.py 中实现路径操作函数 create_todo。 2. 函数必须包含完整的类型提示、文档字符串。 3. 必须包含错误处理如数据库异常返回500。 4. 必须使用依赖注入获取数据库会话。 5. 代码生成后请说明需要如何将其注册到主应用main.py中。AI 将生成类似以下的代码# src/app/routers/todos.py from fastapi import APIRouter, Depends, HTTPException, status from sqlalchemy.orm import Session from typing import List from src.app import crud, models from src.app.database import get_db router APIRouter(prefix/todos, tags[todos]) router.post( /, response_modelmodels.TodoInDB, status_codestatus.HTTP_201_CREATED, summary创建新的待办事项, ) def create_todo( todo_in: models.TodoCreate, db: Session Depends(get_db), ) - models.TodoInDB: 创建一个新的待办事项。 - **title**: 必填最大长度100字符 - **description**: 可选最大长度500字符 - **completed**: 可选默认为 False try: # 调用 CRUD 层函数创建 Todo db_todo crud.create_todo(dbdb, todo_intodo_in) # 将 SQLAlchemy 模型实例转换为 Pydantic 模型实例 return models.TodoInDB.from_orm(db_todo) except Exception as e: # 记录错误日志此处应使用配置好的 logger # logger.error(f创建待办事项失败: {e}) raise HTTPException( status_codestatus.HTTP_500_INTERNAL_SERVER_ERROR, detail内部服务器错误创建待办事项失败。 )同时AI 会说明需要在src/app/main.py中导入并包含这个路由# src/app/main.py from fastapi import FastAPI from src.app.routers import todos # 导入路由模块 from src.app.database import engine, Base # 创建数据库表生产环境应使用 Alembic 迁移 Base.metadata.create_all(bindengine) app FastAPI(titleTodo API Service, version1.0.0) app.include_router(todos.router) # 注册路由 app.get(/health) def health_check(): return {status: healthy}步骤 4运行与验证创建requirements.txt并安装依赖然后运行服务。# requirements.txt fastapi0.104.0 uvicorn[standard]0.24.0 sqlalchemy2.0.0 pydantic2.0.0 # 安装依赖 pip install -r requirements.txt # 运行开发服务器 cd src uvicorn app.main:app --reload --host 0.0.0.0 --port 8000访问http://localhost:8000/docs你应该能看到自动生成的 Swagger UI 文档并且可以测试POST /todos端点。这是对你和 AI 协作成果的第一次验证。7. 将规范固化从文档到自动化检查规范如果只停留在文档很容易被遗忘。SDD 的最终目标是让规范“活”起来融入开发流程。预提交钩子使用pre-commit工具在代码提交前自动运行black、isort、mypy类型检查和pytest。# .pre-commit-config.yaml repos: - repo: https://github.com/psf/black rev: 23.11.0 hooks: - id: black - repo: https://github.com/PyCQA/isort rev: 5.12.0 hooks: - id: isortCI/CD 集成在 GitHub Actions 或 GitLab CI 中加入代码风格检查、类型检查和单元测试的步骤确保合并到主分支的代码都符合规范。规范即代码将最重要的架构决策如项目结构、依赖关系写入pyproject.toml或setup.cfg并使用工具如copier或cookiecutter生成项目模板。这样新的微服务可以直接从模板创建天生符合规范。8. 常见问题与排查思路在实践 SDD 工作流时你可能会遇到以下典型问题问题现象可能原因排查方式解决方案AI 生成的代码不符合预期架构提示词中上下文引用不清晰或规范文档未被 AI 正确读取。1. 检查 Chat 中是否明确引用了规范文件路径。2. 将关键规范直接粘贴到提示词中而非仅引用。优化提示词采用“角色-上下文-任务-输出要求”的模板并将核心规范作为输入的一部分。代码运行时报导入错误AI 生成的导入语句路径错误或文件实际位置与架构规范不符。1. 检查报错信息中的文件路径。2. 核对src/app/下的__init__.py文件是否存在且正确。在架构规范中明确定义模块导入方式如使用相对导入from . import models并确保__init__.py文件存在。数据库操作失败如表不存在AI 生成了模型代码但未生成或未运行数据库创建/迁移脚本。1. 检查database.py中是否调用了Base.metadata.create_all。2. 检查数据库文件是否生成。在main.py启动时调用建表逻辑仅限开发或编写并运行 Alembic 迁移脚本。生成的代码风格不一致未在提示词中强调格式化要求或未配置预提交钩子。检查代码是否符合 PEP 8。在coding_standards.md中明确格式化工具并立即在生成代码后运行black .和isort .。API 响应格式与设计不符Pydantic 响应模型定义错误或 ORM 到 Pydantic 的转换有问题。1. 使用 FastAPI 的/docs页面测试。2. 检查response_model和from_orm或model_dump的使用。确保 Pydantic 模型的Config中设置了from_attributes True并在返回前正确转换模型。9. 最佳实践与工程建议规范文档版本化将docs/specs/目录也纳入 Git 管理。规范的变更应该通过 Pull Request 进行评审就像代码变更一样。分层提示词库建立你自己的提示词库。将通用规范如代码风格、架构规范如 FastAPI 项目结构、业务域规范如“如何编写支付模块”分层管理。新项目可以直接组合使用。从小处着手逐步推广不要试图一次性为整个团队制定完美的规范。从一个小的、具体的项目如一个工具脚本或一个微服务开始实践 SDD验证其效果然后逐步完善规范并推广到更复杂的项目。人是规范的最终负责人AI 是强大的执行者但规范的制定、审查和演进必须由人来主导。定期组织代码评审不仅要评审代码逻辑也要评审代码是否遵循了既定规范。平衡规范与灵活性规范不是铁律。当遇到规范无法覆盖的特殊场景时应记录下决策原因并考虑是否要更新规范。规范本身也应该是可演进、可改进的。通过这套规范驱动开发的工作流你将不再是与一个“黑盒”AI 进行低效的、重复的对话。你是在扮演“架构师”和“产品经理”的角色通过编写精确的规范来“编程”AI 这个“超级执行者”。这不仅能极大提升代码生成的质量和一致性更能将你的时间从繁琐的、重复的编码中解放出来投入到更高层次的设计、规划和问题解决中去。本文的完整课件代码包括所有规范文档和生成的示例代码你可以在我们的示例仓库中找到。现在就尝试为你下一个项目起草第一份规范文档开启你的标准化 AI 编程之旅吧。
规范驱动开发：告别AI盲盒编程，打造标准化代码生成工作流
你是不是也遇到过这样的场景用 AI 编程工具生成了几百行代码看着功能都实现了但一运行就报错或者代码风格混乱得像“缝合怪”后期维护无从下手又或者你精心设计的提示词AI 却总是“跑偏”生成的结果和你预想的南辕北辙这背后的问题不是 AI 不够强而是我们与 AI 协作的方式还停留在“盲盒式编程”的原始阶段。你输入一个模糊的需求AI 输出一个不确定的结果反复调试效率低下。最近吴恩达教授在 2026 年最新分享中系统性地提出了“规范驱动开发”的理念。这并非一个全新的编程语言或框架而是一套将 AI 编程从“随机探索”升级为“标准化生产”的方法论和工作流。它要解决的正是如何让 AI 成为你团队里那个“懂规矩、守纪律、可预期”的资深工程师而不是一个充满惊喜或惊吓的“魔法黑盒”。本文将带你从零开始实战这套SDD工作流。我们不会空谈理论而是手把手教你如何建立标准化的 AI 编程流程告别“盲盒式编程”真正将 AI 的潜力转化为稳定、可交付的生产力。文章末尾我们也会提供完整的课件代码供你直接实践。1. 规范驱动开发告别“盲盒式编程”的核心方法论“盲盒式编程”是很多开发者使用 AI 辅助编码时的共同痛点。你给 AI 一个任务比如“写一个用户登录的 API”AI 可能会用 Flask 写也可能用 FastAPI可能用 JWT 认证也可能用 Session代码风格可能遵循 PEP 8也可能随心所欲。每次生成的结果都像开盲盒充满了不确定性。规范驱动开发的核心思想就是通过预先定义一套清晰、明确、可执行的“规范”来约束和引导 AI 的代码生成行为确保输出结果的一致性、可维护性和高质量。这听起来有点像“契约测试”或“API 设计先行”但 SDD 将其扩展到了整个开发工作流并与 AI 工具深度集成。它的关键转变在于从“描述问题”到“定义规范”你不再只是告诉 AI“做什么”而是清晰地告诉它“按照什么标准来做”。从“一次性交互”到“结构化工作流”将一次性的、模糊的提示拆解为一系列标准化的、可复用的步骤。从“结果验收”到“过程可控”在代码生成之前规范就已经定义了成功的标准。一个典型的 SDD 工作流包含几个核心环节需求规约 - 架构与接口设计 - 代码生成规范 - 测试与验证规范。AI 在整个流程中是严格遵循这些既定规范的执行者。2. 环境准备打造你的 SDD 实战工作台在开始构建工作流之前我们需要准备好“战场”。SDD 不依赖于某个特定的 IDE但高效的工具体系能让你事半功倍。我们将围绕Cursor和VSCode这两大主流 AI 编程环境进行配置。2.1 核心工具选择与安装AI 编程 IDE二选一或组合使用Cursor内置了强大的 AI 模型如 Claude 3.5 Sonnet深度集成了聊天、编辑、自动完成功能对 SDD 工作流支持非常友好。它是我们本次实战的首选。VSCode 插件如果你更习惯 VSCode可以通过安装Cursor插件或Claude、Codeium、GitHub Copilot等 AI 编程插件来实现类似功能。版本控制Git是必须的。SDD 强调过程的可追溯性每一次规范的变更、AI 生成的代码都需要通过 Git 进行管理。项目管理与文档建议使用Markdown文件在项目根目录管理你的规范文档。例如SPECIFICATION.md、ARCHITECTURE.md、API_DESIGN.md。2.2 Cursor 基础配置与项目初始化假设我们选择 Cursor 作为主战场。首先为我们的 SDD 实战项目创建一个干净的环境。# 1. 创建项目目录 mkdir sdd-practical-tutorial cd sdd-practical-tutorial # 2. 初始化 Git 仓库至关重要 git init # 3. 创建规范文档目录 mkdir -p docs/specs # 4. 创建示例项目源码目录我们以一个简单的 Python Web 服务为例 mkdir -p src/app接下来在 Cursor 中打开这个项目文件夹。你需要熟悉 Cursor 的几个核心功能区域Chat 面板与 AI 进行结构化对话输入规范的地方。编辑器查看和编辑代码。终端运行命令。版本控制查看 Git 变更。3. 第一步从模糊需求到精确规约我们以一个具体的例子贯穿全文构建一个简单的“待办事项Todo管理 API 服务”。传统的 AI 提示可能是“用 FastAPI 写一个 Todo API。” 这太模糊了。在 SDD 中我们的第一步是创建需求规约文档。在docs/specs/requirements.md中我们这样写# 待办事项TodoAPI 服务需求规约 ## 1. 概述 本项目旨在提供一个 RESTful API 服务用于管理个人待办事项Todo Items。核心功能包括创建、读取、更新、删除和查询待办事项。 ## 2. 功能需求 ### 2.1 待办事项模型 一个待办事项应包含以下字段 - id: 唯一标识符整数自增 - title: 标题字符串必填最大长度100字符 - description: 详细描述字符串可选最大长度500字符 - completed: 完成状态布尔值默认 false - created_at: 创建时间时间戳自动生成 - updated_at: 更新时间时间戳自动更新 ### 2.2 API 端点 1. **POST /todos**: 创建新的待办事项。 2. **GET /todos**: 获取所有待办事项列表支持分页和按完成状态过滤。 3. **GET /todos/{id}**: 根据 ID 获取单个待办事项详情。 4. **PUT /todos/{id}**: 更新指定待办事项的全部信息。 5. **PATCH /todos/{id}**: 部分更新指定待办事项如标记完成。 6. **DELETE /todos/{id}**: 删除指定待办事项。 ## 3. 非功能需求 - **框架**: 使用 FastAPI。 - **数据库**: 使用 SQLite 进行本地开发方便演示但代码结构应易于切换至 PostgreSQL 或 MySQL。 - **数据验证**: 使用 Pydantic 模型进行请求/响应数据的严格验证。 - **错误处理**: 统一的错误响应格式JSON包含 HTTP 状态码和错误信息。 - **代码风格**: 遵循 PEP 8使用 black 和 isort 进行格式化。这份文档就是我们的第一层规范。它清晰、无歧义地定义了“做什么”。接下来我们要把这个文档“喂”给 AI。在 Cursor 的 Chat 面板中我们可以这样输入**上下文**请阅读项目根目录下 docs/specs/requirements.md 文件中的需求规约。 **任务**基于此规约为我们设计初步的项目架构并列出需要创建的核心 Python 模块文件及其职责。请以 Markdown 列表形式输出。AI 会根据规约输出类似如下的架构建议这就进入了下一阶段。4. 第二步定义架构与接口规范AI 给出的架构建议可能比较泛。我们需要将其具体化为第二层规范架构与接口设计文档。在docs/specs/architecture.md中定义# 项目架构与接口设计规范 ## 1. 项目结构sdd-practical-tutorial/ ├── src/ │ └── app/ │ ├──init.py │ ├── main.py # FastAPI 应用实例和路由总入口 │ ├── models.py # Pydantic 模型定义请求/响应 │ ├── schemas.py # SQLAlchemy 数据模型定义可选如果不用ORM可省略 │ ├── crud.py # 数据库增删改查操作函数 │ ├── database.py # 数据库连接与会话管理 │ └── routers/ │ └── todos.py # 待办事项相关的路由 ├── docs/ │ └── specs/ # 规范文档 ├── tests/ # 测试文件 ├── requirements.txt # Python 依赖 └── .env.example # 环境变量示例## 2. API 接口详细规范OpenAPI 风格 ### 端点POST /todos - **描述**: 创建新待办事项。 - **请求体**: json { title: string, required, maxLength100, description: string, optional, maxLength500, completed: boolean, optional, defaultfalse }成功响应 (201 Created):{ id: integer, title: string, description: string, completed: boolean, created_at: string (ISO 8601), updated_at: string (ISO 8601) }错误响应:400 Bad Request: 请求体验证失败。500 Internal Server Error: 服务器内部错误。其他端点类似此处省略以节省篇幅实际项目中需完整定义3. 数据库规范使用SQLAlchemy作为 ORM对象关系映射工具。使用Alembic进行数据库迁移管理。表名todos。所有时间字段使用 UTC 时间。现在我们有了更具体的蓝图。接下来我们可以指令 AI 根据这份架构规范生成基础的项目骨架代码。注意我们不是让它直接写业务逻辑而是先搭建符合规范的结构。 在 Cursor Chat 中输入上下文已阅读requirements.md和architecture.md。当前任务请严格按照architecture.md中定义的项目结构在src/app/目录下创建所有指定的空 Python 文件__init__.py,main.py,models.py等。然后在main.py中初始化一个最基本的 FastAPI 应用实例并创建一个健康检查端点GET /health用于验证服务是否启动。请输出具体的代码。## 5. 第三步编写代码生成规范与提示词模板 这是 SDD 最核心的一环。我们不能每次都对 AI 说“写一个创建 Todo 的端点”。我们需要一个可复用的 **提示词模板**这个模板本身也是规范的一部分。 我们在 docs/specs/coding_standards.md 中定义代码规范 markdown # 代码生成与质量标准 ## 1. 通用编程规范 - **语言**: Python 3.9。 - **格式化**: 使用 black 和 isort。生成代码后必须运行 black . 和 isort . 进行格式化。 - **导入排序**: 标准库 - 第三方库 - 本地模块每组之间空一行。 - **类型提示**: 必须为所有函数参数和返回值添加类型提示Type Hints。 - **错误处理**: 使用明确的 try...except 块捕获特定异常并记录日志。 - **日志记录**: 使用 Python 内置的 logging 模块级别设置为 INFO。 ## 2. FastAPI 特定规范 - **依赖注入**: 对于数据库会话等资源使用 FastAPI 的 Depends。 - **响应模型**: 必须使用 response_model 参数确保响应数据结构符合 Pydantic 模型。 - **状态码**: 严格使用正确的 HTTP 状态码如 201 用于创建成功。 - **路径操作函数命名**: 使用 create_item, read_item, update_item, delete_item 等清晰动词。 ## 3. 提示词模板用于生成 CRUD 端点 当需要生成一个新的 API 端点时请遵循以下模板填充信息角色你是一名资深后端工程师严格遵守项目规范。上下文项目使用 FastAPI SQLAlchemy SQLite。项目结构见architecture.md代码规范见本文件。任务为[实体名]实现[HTTP方法] [端点路径]端点。输入Pydantic 模型此处粘贴或描述请求和响应模型定义数据库模型此处粘贴或描述 SQLAlchemy 模型定义业务逻辑描述简要说明这个端点要做什么任何特殊规则输出要求在正确的文件通常是src/app/routers/[实体名].py中实现路径操作函数。函数必须包含完整的类型提示、文档字符串docstring。必须包含错误处理如查找不到资源返回404。必须使用依赖注入获取数据库会话。代码生成后请说明需要如何将其注册到主应用main.py中。有了这个模板当我们接下来需要实现POST /todos时我们的提示词就变得极其规范和高效。我们不再进行开放式聊天而是“填充模板”。6. 完整实战生成符合规范的 Todo 创建端点现在让我们运用以上所有规范生成第一个完整的业务端点。步骤 1定义数据模型首先我们指令 AI 创建 Pydantic 和 SQLAlchemy 模型。在 Cursor Chat 中我们可以引用规范文件并给出精确指令。**上下文**项目规范见 requirements.md 和 coding_standards.md。 **任务**请在 src/app/models.py 中定义用于 Todo 的 Pydantic 模型TodoCreate, TodoUpdate, TodoInDB。然后在 src/app/schemas.py 中定义 SQLAlchemy 的 Todo 模型类。请确保字段类型、约束与需求规约完全一致并添加类型提示。AI 生成的models.py可能如下# src/app/models.py from datetime import datetime from typing import Optional from pydantic import BaseModel, Field class TodoBase(BaseModel): title: str Field(..., max_length100, description待办事项标题) description: Optional[str] Field(None, max_length500, description详细描述) completed: bool Field(False, description是否已完成) class TodoCreate(TodoBase): pass class TodoUpdate(BaseModel): title: Optional[str] Field(None, max_length100) description: Optional[str] Field(None, max_length500) completed: Optional[bool] None class TodoInDB(TodoBase): id: int created_at: datetime updated_at: datetime class Config: from_attributes True # 替代旧的 orm_mode TrueAI 生成的schemas.py可能如下# src/app/schemas.py from sqlalchemy import Boolean, Column, DateTime, Integer, String, Text from sqlalchemy.sql import func from src.app.database import Base # 假设我们已经有了 Base class Todo(Base): __tablename__ todos id Column(Integer, primary_keyTrue, indexTrue) title Column(String(100), nullableFalse) description Column(Text, nullableTrue) completed Column(Boolean, defaultFalse) created_at Column(DateTime(timezoneTrue), server_defaultfunc.now()) updated_at Column(DateTime(timezoneTrue), onupdatefunc.now())步骤 2生成数据库连接和 CRUD 基础接着生成数据库配置和基础的 CRUD 操作函数。**上下文**已有 schemas.py 中的 Todo 模型。 **任务**请创建 src/app/database.py 文件配置 SQLAlchemy 引擎和会话本地化。然后创建 src/app/crud.py 文件实现针对 Todo 模型的创建、读取单个和多个、更新、删除等基础函数。请严格遵循 coding_standards.md 中的错误处理和日志规范。步骤 3应用代码生成模板实现端点现在使用我们定义的提示词模板来生成POST /todos端点。在 Cursor Chat 中我们这样输入**角色**你是一名资深后端工程师严格遵守项目规范。 **上下文**项目使用 FastAPI SQLAlchemy SQLite。项目结构见 architecture.md代码规范见 coding_standards.md。已存在 models.py 和 crud.py。 **任务**为 Todo 实现 POST /todos 端点。 **输入** 1. **Pydantic 模型**请求体使用 TodoCreate成功响应201使用 TodoInDB。 2. **数据库模型**使用 schemas.Todo。 3. **业务逻辑描述**接收 JSON 请求体验证数据通过 CRUD 函数创建新的 Todo 记录到数据库返回创建成功的 Todo 信息包含生成的 id 和时间戳。 **输出要求** 1. 在 src/app/routers/todos.py 中实现路径操作函数 create_todo。 2. 函数必须包含完整的类型提示、文档字符串。 3. 必须包含错误处理如数据库异常返回500。 4. 必须使用依赖注入获取数据库会话。 5. 代码生成后请说明需要如何将其注册到主应用main.py中。AI 将生成类似以下的代码# src/app/routers/todos.py from fastapi import APIRouter, Depends, HTTPException, status from sqlalchemy.orm import Session from typing import List from src.app import crud, models from src.app.database import get_db router APIRouter(prefix/todos, tags[todos]) router.post( /, response_modelmodels.TodoInDB, status_codestatus.HTTP_201_CREATED, summary创建新的待办事项, ) def create_todo( todo_in: models.TodoCreate, db: Session Depends(get_db), ) - models.TodoInDB: 创建一个新的待办事项。 - **title**: 必填最大长度100字符 - **description**: 可选最大长度500字符 - **completed**: 可选默认为 False try: # 调用 CRUD 层函数创建 Todo db_todo crud.create_todo(dbdb, todo_intodo_in) # 将 SQLAlchemy 模型实例转换为 Pydantic 模型实例 return models.TodoInDB.from_orm(db_todo) except Exception as e: # 记录错误日志此处应使用配置好的 logger # logger.error(f创建待办事项失败: {e}) raise HTTPException( status_codestatus.HTTP_500_INTERNAL_SERVER_ERROR, detail内部服务器错误创建待办事项失败。 )同时AI 会说明需要在src/app/main.py中导入并包含这个路由# src/app/main.py from fastapi import FastAPI from src.app.routers import todos # 导入路由模块 from src.app.database import engine, Base # 创建数据库表生产环境应使用 Alembic 迁移 Base.metadata.create_all(bindengine) app FastAPI(titleTodo API Service, version1.0.0) app.include_router(todos.router) # 注册路由 app.get(/health) def health_check(): return {status: healthy}步骤 4运行与验证创建requirements.txt并安装依赖然后运行服务。# requirements.txt fastapi0.104.0 uvicorn[standard]0.24.0 sqlalchemy2.0.0 pydantic2.0.0 # 安装依赖 pip install -r requirements.txt # 运行开发服务器 cd src uvicorn app.main:app --reload --host 0.0.0.0 --port 8000访问http://localhost:8000/docs你应该能看到自动生成的 Swagger UI 文档并且可以测试POST /todos端点。这是对你和 AI 协作成果的第一次验证。7. 将规范固化从文档到自动化检查规范如果只停留在文档很容易被遗忘。SDD 的最终目标是让规范“活”起来融入开发流程。预提交钩子使用pre-commit工具在代码提交前自动运行black、isort、mypy类型检查和pytest。# .pre-commit-config.yaml repos: - repo: https://github.com/psf/black rev: 23.11.0 hooks: - id: black - repo: https://github.com/PyCQA/isort rev: 5.12.0 hooks: - id: isortCI/CD 集成在 GitHub Actions 或 GitLab CI 中加入代码风格检查、类型检查和单元测试的步骤确保合并到主分支的代码都符合规范。规范即代码将最重要的架构决策如项目结构、依赖关系写入pyproject.toml或setup.cfg并使用工具如copier或cookiecutter生成项目模板。这样新的微服务可以直接从模板创建天生符合规范。8. 常见问题与排查思路在实践 SDD 工作流时你可能会遇到以下典型问题问题现象可能原因排查方式解决方案AI 生成的代码不符合预期架构提示词中上下文引用不清晰或规范文档未被 AI 正确读取。1. 检查 Chat 中是否明确引用了规范文件路径。2. 将关键规范直接粘贴到提示词中而非仅引用。优化提示词采用“角色-上下文-任务-输出要求”的模板并将核心规范作为输入的一部分。代码运行时报导入错误AI 生成的导入语句路径错误或文件实际位置与架构规范不符。1. 检查报错信息中的文件路径。2. 核对src/app/下的__init__.py文件是否存在且正确。在架构规范中明确定义模块导入方式如使用相对导入from . import models并确保__init__.py文件存在。数据库操作失败如表不存在AI 生成了模型代码但未生成或未运行数据库创建/迁移脚本。1. 检查database.py中是否调用了Base.metadata.create_all。2. 检查数据库文件是否生成。在main.py启动时调用建表逻辑仅限开发或编写并运行 Alembic 迁移脚本。生成的代码风格不一致未在提示词中强调格式化要求或未配置预提交钩子。检查代码是否符合 PEP 8。在coding_standards.md中明确格式化工具并立即在生成代码后运行black .和isort .。API 响应格式与设计不符Pydantic 响应模型定义错误或 ORM 到 Pydantic 的转换有问题。1. 使用 FastAPI 的/docs页面测试。2. 检查response_model和from_orm或model_dump的使用。确保 Pydantic 模型的Config中设置了from_attributes True并在返回前正确转换模型。9. 最佳实践与工程建议规范文档版本化将docs/specs/目录也纳入 Git 管理。规范的变更应该通过 Pull Request 进行评审就像代码变更一样。分层提示词库建立你自己的提示词库。将通用规范如代码风格、架构规范如 FastAPI 项目结构、业务域规范如“如何编写支付模块”分层管理。新项目可以直接组合使用。从小处着手逐步推广不要试图一次性为整个团队制定完美的规范。从一个小的、具体的项目如一个工具脚本或一个微服务开始实践 SDD验证其效果然后逐步完善规范并推广到更复杂的项目。人是规范的最终负责人AI 是强大的执行者但规范的制定、审查和演进必须由人来主导。定期组织代码评审不仅要评审代码逻辑也要评审代码是否遵循了既定规范。平衡规范与灵活性规范不是铁律。当遇到规范无法覆盖的特殊场景时应记录下决策原因并考虑是否要更新规范。规范本身也应该是可演进、可改进的。通过这套规范驱动开发的工作流你将不再是与一个“黑盒”AI 进行低效的、重复的对话。你是在扮演“架构师”和“产品经理”的角色通过编写精确的规范来“编程”AI 这个“超级执行者”。这不仅能极大提升代码生成的质量和一致性更能将你的时间从繁琐的、重复的编码中解放出来投入到更高层次的设计、规划和问题解决中去。本文的完整课件代码包括所有规范文档和生成的示例代码你可以在我们的示例仓库中找到。现在就尝试为你下一个项目起草第一份规范文档开启你的标准化 AI 编程之旅吧。
