Vibe Coding Prompt 最佳实践指南:实战项目解析
目录
- 引言
- 项目背景
- Prompt最佳实践原则
- 实战案例:TaskFlow待办事项管理系统
- 阶段一:需求分析与架构设计
- 阶段二:数据模型设计
- 阶段三:API接口开发
- 阶段四:前端组件开发
- 阶段五:测试代码生成
- 阶段六:文档与部署
- Prompt优化技巧
- 常见错误与解决方案
- Prompt模板库
- 总结
引言
在Vibe Coding中,Prompt(提示词)是开发者与AI交互的核心媒介。一个优秀的Prompt不仅能让AI准确理解你的意图,还能显著提升代码质量和开发效率。本文通过一个完整的实战项目——TaskFlow待办事项管理系统,深入剖析在不同开发阶段如何编写高质量的Prompt,总结出一套可复用的最佳实践。
本文目标:
– 掌握Prompt的核心编写原则
– 学习不同场景下的Prompt编写技巧
– 通过实际案例理解Prompt的迭代优化过程
– 建立个人Prompt模板库
项目背景
项目概述
TaskFlow 是一个功能完善的待办事项管理系统,支持任务管理、分类、标签、提醒、协作等功能。
技术栈:
– 后端:Python + FastAPI + SQLAlchemy + PostgreSQL
– 前端:Vue 3 + TypeScript + Element Plus
– 部署:Docker + Nginx
核心功能:
1. 任务的增删改查(CRUD)
2. 任务分类和标签管理
3. 任务优先级和截止日期
4. 用户认证和授权
5. 团队协作和任务分配
6. 任务统计和报表
开发周期:2周(使用Vibe Coding)
Prompt最佳实践原则
1. 清晰性(Clarity)
原则:意图表达清晰明确,避免歧义。
示例:
❌ 不好:
"帮我写个用户登录"
✅ 好:
"请帮我实现一个用户登录功能,要求:
1. 支持邮箱和手机号登录
2. 使用JWT进行身份验证
3. 密码使用bcrypt加密存储
4. 登录失败5次后锁定账户30分钟
5. 返回用户基本信息和JWT token
技术栈:Python + FastAPI + SQLAlchemy"
2. 具体性(Specificity)
原则:提供足够的细节和上下文,减少AI的猜测。
示例:
❌ 不好:
"生成一个API接口"
✅ 好:
"请生成一个创建任务的API接口:
- 路径:POST /api/tasks
- 请求体:{title, description, priority, due_date, category_id, tag_ids}
- 验证:title必填,priority只能是low/medium/high
- 返回:创建成功的任务对象,包含自动生成的id和created_at
- 权限:需要用户登录
- 数据库:使用SQLAlchemy ORM"
3. 结构化(Structure)
原则:使用清晰的结构组织Prompt,便于AI理解。
推荐结构:
## 背景
[项目背景和上下文信息]
## 任务
[具体要完成的任务]
## 要求
[功能要求、技术要求、质量要求]
## 约束
[必须遵守的约束条件]
## 输出格式
[期望的输出格式]
## 示例
[如果有,提供示例]
4. 上下文(Context)
原则:提供充分的上下文信息,帮助AI做出正确的决策。
示例:
"项目背景:TaskFlow是一个待办事项管理系统,采用FastAPI开发。
现有数据模型:
- Task模型:id, title, description, status, priority, created_at
- User模型:id, email, password_hash, created_at
请基于现有模型,实现以下功能:
[具体任务]..."
5. 迭代性(Iteration)
原则:通过多次迭代逐步完善Prompt和代码。
示例:
第一轮:
"帮我写一个任务列表查询接口"
第二轮(基于第一轮结果):
"在之前的代码基础上,增加以下功能:
1. 支持按状态筛选
2. 支持按优先级排序
3. 支持分页,每页20条
4. 只返回当前用户的任务"
实战案例:TaskFlow待办事项管理系统
阶段一:需求分析与架构设计
Prompt 1.1:需求分析
项目名称:TaskFlow待办事项管理系统
项目背景:
我需要开发一个功能完善的待办事项管理系统,帮助个人和团队高效管理任务。
核心功能需求:
1. 用户可以创建、查看、编辑、删除任务
2. 任务可以设置优先级(低、中、高)
3. 任务可以设置截止日期
4. 任务可以分类管理
5. 任务可以添加标签
6. 用户可以设置任务提醒
7. 支持团队协作,任务可以分配给其他用户
8. 提供任务统计和报表功能
技术要求:
- 后端:Python + FastAPI
- 数据库:PostgreSQL
- ORM:SQLAlchemy
- 认证:JWT
请帮我:
1. 分析这些需求,识别核心功能模块
2. 设计系统架构
3. 列出需要的数据模型
4. 列出主要的API接口
5. 给出开发优先级建议
AI输出:
## 需求分析
### 核心功能模块
1. 用户管理模块(用户注册、登录、个人信息)
2. 认证授权模块(JWT token、权限控制)
3. 任务管理模块(CRUD、状态管理)
4. 分类管理模块(分类的增删改查)
5. 标签管理模块(标签的增删改查)
6. 提醒管理模块(任务提醒)
7. 团队协作模块(任务分配、共享)
8. 统计报表模块(数据统计、可视化)
### 系统架构
- 采用前后端分离架构
- 后端提供RESTful API
- 前端单页应用(SPA)
- 使用JWT进行无状态认证
### 数据模型
见下一节详细设计
### API接口
见下一节详细设计
### 开发优先级
Phase 1(核心功能):用户认证、任务CRUD
Phase 2(基础功能):分类、标签、优先级
Phase 3(高级功能):提醒、协作
Phase 4(增值功能):统计、报表
Prompt 1.2:数据模型设计
基于上面的需求分析,请帮我设计SQLAlchemy数据模型。
要求:
1. 使用Python类型注解
2. 包含所有必要的字段
3. 建立正确的表关系
4. 添加索引以提高查询性能
5. 包含created_at和updated_at字段
6. 使用字符串id而不是自增id(便于分布式)
需要的模型:
- User(用户)
- Task(任务)
- Category(分类)
- Tag(标签)
- TaskTag(任务-标签关联表)
- Team(团队)
- TeamMember(团队成员)
- Reminder(提醒)
请提供完整的模型代码,包括:
- 模型定义
- 字段类型和约束
- 表关系(relationship)
- 索引
- 字符串id生成方法
AI输出:
from sqlalchemy import Column, String, DateTime, Integer, ForeignKey, Text, Enum, Boolean
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import relationship
from datetime import datetime
import enum
import uuid
Base = declarative_base()
def generate_uuid():
return str(uuid.uuid4())
class Priority(enum.Enum):
LOW = "low"
MEDIUM = "medium"
HIGH = "high"
class TaskStatus(enum.Enum):
PENDING = "pending"
IN_PROGRESS = "in_progress"
COMPLETED = "completed"
CANCELLED = "cancelled"
class User(Base):
__tablename__ = "users"
id = Column(String, primary_key=True, default=generate_uuid)
email = Column(String, unique=True, index=True, nullable=False)
password_hash = Column(String, nullable=False)
name = Column(String)
avatar_url = Column(String)
is_active = Column(Boolean, default=True)
created_at = Column(DateTime, default=datetime.utcnow)
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
# 关系
created_tasks = relationship("Task", back_populates="creator", foreign_keys="Task.creator_id")
assigned_tasks = relationship("Task", back_populates="assignee", foreign_keys="Task.assignee_id")
categories = relationship("Category", back_populates="user")
teams_owned = relationship("Team", back_populates="owner")
team_memberships = relationship("TeamMember", back_populates="user")
class Task(Base):
__tablename__ = "tasks"
id = Column(String, primary_key=True, default=generate_uuid)
title = Column(String, nullable=False)
description = Column(Text)
status = Column(Enum(TaskStatus), default=TaskStatus.PENDING)
priority = Column(Enum(Priority), default=Priority.MEDIUM)
due_date = Column(DateTime)
completed_at = Column(DateTime)
# 外键
creator_id = Column(String, ForeignKey("users.id"))
assignee_id = Column(String, ForeignKey("users.id"), nullable=True)
category_id = Column(String, ForeignKey("categories.id"), nullable=True)
# 关系
creator = relationship("User", back_populates="created_tasks", foreign_keys=[creator_id])
assignee = relationship("User", back_populates="assigned_tasks", foreign_keys=[assignee_id])
category = relationship("Category", back_populates="tasks")
tags = relationship("Tag", secondary="task_tags", back_populates="tasks")
reminders = relationship("Reminder", back_populates="task")
created_at = Column(DateTime, default=datetime.utcnow)
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
class Category(Base):
__tablename__ = "categories"
id = Column(String, primary_key=True, default=generate_uuid)
name = Column(String, nullable=False)
color = Column(String, default="#3498db")
icon = Column(String)
user_id = Column(String, ForeignKey("users.id"), nullable=False)
# 关系
user = relationship("User", back_populates="categories")
tasks = relationship("Task", back_populates="category")
created_at = Column(DateTime, default=datetime.utcnow)
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
class Tag(Base):
__tablename__ = "tags"
id = Column(String, primary_key=True, default=generate_uuid)
name = Column(String, nullable=False)
color = Column(String, default="#2ecc71")
# 关系
tasks = relationship("Task", secondary="task_tags", back_populates="tags")
created_at = Column(DateTime, default=datetime.utcnow)
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
# 任务-标签关联表
class TaskTag(Base):
__tablename__ = "task_tags"
task_id = Column(String, ForeignKey("tasks.id"), primary_key=True)
tag_id = Column(String, ForeignKey("tags.id"), primary_key=True)
class Team(Base):
__tablename__ = "teams"
id = Column(String, primary_key=True, default=generate_uuid)
name = Column(String, nullable=False)
description = Column(Text)
owner_id = Column(String, ForeignKey("users.id"), nullable=False)
# 关系
owner = relationship("User", back_populates="teams_owned")
members = relationship("TeamMember", back_populates="team")
created_at = Column(DateTime, default=datetime.utcnow)
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
class TeamMember(Base):
__tablename__ = "team_members"
id = Column(String, primary_key=True, default=generate_uuid)
team_id = Column(String, ForeignKey("teams.id"), nullable=False)
user_id = Column(String, ForeignKey("users.id"), nullable=False)
role = Column(String, default="member") # owner, admin, member
# 关系
team = relationship("Team", back_populates="members")
user = relationship("User", back_populates="team_memberships")
created_at = Column(DateTime, default=datetime.utcnow)
class Reminder(Base):
__tablename__ = "reminders"
id = Column(String, primary_key=True, default=generate_uuid)
task_id = Column(String, ForeignKey("tasks.id"), nullable=False)
remind_at = Column(DateTime, nullable=False)
is_sent = Column(Boolean, default=False)
# 关系
task = relationship("Task", back_populates="reminders")
created_at = Column(DateTime, default=datetime.utcnow)
点评:这个Prompt提供了充分的上下文、明确的要求和结构化的输出,AI生成的代码质量很高,包含了所有必要的关系和约束。
阶段二:数据模型设计
Prompt 2.1:Pydantic模型
基于之前设计的SQLAlchemy模型,请生成对应的Pydantic模型。
要求:
1. 包含所有CRUD操作需要的Schema
2. 使用BaseModel作为基类
3. 添加必要的验证规则
4. 区分输入和输出模型
5. 使用Python 3.9+的类型注解
需要的Schema:
- UserBase, UserCreate, UserResponse, UserLogin
- TaskBase, TaskCreate, TaskUpdate, TaskResponse, TaskListResponse
- CategoryBase, CategoryCreate, CategoryResponse
- TagBase, TagCreate, TagResponse
- TeamBase, TeamCreate, TeamResponse
- ReminderBase, ReminderCreate, ReminderResponse
请提供完整的Pydantic模型代码。
AI输出:
from pydantic import BaseModel, EmailStr, Field, validator
from typing import Optional, List
from datetime import datetime
from enum import Enum
# 枚举类型
class Priority(str, Enum):
LOW = "low"
MEDIUM = "medium"
HIGH = "high"
class TaskStatus(str, Enum):
PENDING = "pending"
IN_PROGRESS = "in_progress"
COMPLETED = "completed"
CANCELLED = "cancelled"
# User Schemas
class UserBase(BaseModel):
email: EmailStr
name: Optional[str] = None
avatar_url: Optional[str] = None
class UserCreate(UserBase):
password: str = Field(..., min_length=6)
@validator('password')
def validate_password(cls, v):
if len(v) < 6:
raise ValueError('密码至少6个字符')
return v
class UserLogin(BaseModel):
email: EmailStr
password: str
class UserResponse(UserBase):
id: str
is_active: bool
created_at: datetime
class Config:
from_attributes = True
# Task Schemas
class TaskBase(BaseModel):
title: str = Field(..., min_length=1, max_length=200)
description: Optional[str] = None
priority: Priority = Priority.MEDIUM
due_date: Optional[datetime] = None
class TaskCreate(TaskBase):
assignee_id: Optional[str] = None
category_id: Optional[str] = None
tag_ids: Optional[List[str]] = []
class TaskUpdate(BaseModel):
title: Optional[str] = Field(None, min_length=1, max_length=200)
description: Optional[str] = None
status: Optional[TaskStatus] = None
priority: Optional[Priority] = None
due_date: Optional[datetime] = None
assignee_id: Optional[str] = None
category_id: Optional[str] = None
tag_ids: Optional[List[str]] = None
class TaskResponse(TaskBase):
id: str
status: TaskStatus
creator_id: str
assignee_id: Optional[str]
category_id: Optional[str]
tags: List['TagResponse'] = []
created_at: datetime
updated_at: datetime
completed_at: Optional[datetime] = None
class Config:
from_attributes = True
class TaskListResponse(BaseModel):
total: int
page: int
page_size: int
tasks: List[TaskResponse]
# Category Schemas
class CategoryBase(BaseModel):
name: str = Field(..., min_length=1, max_length=50)
color: str = "#3498db"
icon: Optional[str] = None
class CategoryCreate(CategoryBase):
pass
class CategoryResponse(CategoryBase):
id: str
user_id: str
created_at: datetime
updated_at: datetime
class Config:
from_attributes = True
# Tag Schemas
class TagBase(BaseModel):
name: str = Field(..., min_length=1, max_length=30)
color: str = "#2ecc71"
class TagCreate(TagBase):
pass
class TagResponse(TagBase):
id: str
created_at: datetime
updated_at: datetime
class Config:
from_attributes = True
# Team Schemas
class TeamBase(BaseModel):
name: str = Field(..., min_length=1, max_length=100)
description: Optional[str] = None
class TeamCreate(TeamBase):
pass
class TeamResponse(TeamBase):
id: str
owner_id: str
created_at: datetime
updated_at: datetime
class Config:
from_attributes = True
# Reminder Schemas
class ReminderBase(BaseModel):
task_id: str
remind_at: datetime
class ReminderCreate(ReminderBase):
pass
class ReminderResponse(ReminderBase):
id: str
is_sent: bool
created_at: datetime
class Config:
from_attributes = True
阶段三:API接口开发
Prompt 3.1:任务创建接口
请帮我实现任务创建的API接口。
技术栈:FastAPI
ORM:SQLAlchemy
认证:JWT
已有资源:
- Task模型(如前所示)
- TaskCreate和TaskResponse Pydantic模型
- 当前用户信息通过依赖注入获取
接口要求:
1. 路径:POST /api/tasks
2. 需要认证(使用JWT)
3. 请求体:TaskCreate
4. 验证:
- title必填
- priority只能是low/medium/high
- category_id必须属于当前用户
- assignee_id必须是有效的用户
5. 业务逻辑:
- creator_id自动设为当前用户
- status默认为pending
- 如果提供了tag_ids,需要创建关联
- 如果提供了due_date,自动创建提醒(提醒时间:due_date前1小时)
6. 返回:TaskResponse
7. 错误处理:
- category_id不存在返回404
- assignee_id不存在返回404
- 验证失败返回422
请提供完整的路由代码,包括:
- 路由定义
- 依赖注入
- 业务逻辑
- 错误处理
- 数据验证
AI输出:
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from typing import List
from datetime import datetime, timedelta
from ..models import Task, Category, User, Tag, TaskTag, Reminder
from ..schemas import TaskCreate, TaskResponse
from ..database import get_db
from ..auth import get_current_user
router = APIRouter(prefix="/api/tasks", tags=["tasks"])
@router.post("", response_model=TaskResponse, status_code=status.HTTP_201_CREATED)
def create_task(
task_data: TaskCreate,
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user)
):
"""
创建新任务
参数:
- task_data: 任务创建数据
- db: 数据库会话
- current_user: 当前登录用户
返回:
- TaskResponse: 创建的任务信息
异常:
- 404: category_id或assignee_id不存在
- 422: 数据验证失败
"""
# 验证category_id
if task_data.category_id:
category = db.query(Category).filter(
Category.id == task_data.category_id,
Category.user_id == current_user.id
).first()
if not category:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"分类 {task_data.category_id} 不存在"
)
# 验证assignee_id
if task_data.assignee_id:
assignee = db.query(User).filter(
User.id == task_data.assignee_id
).first()
if not assignee:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"用户 {task_data.assignee_id} 不存在"
)
# 创建任务
task = Task(
title=task_data.title,
description=task_data.description,
priority=task_data.priority,
due_date=task_data.due_date,
creator_id=current_user.id,
assignee_id=task_data.assignee_id,
category_id=task_data.category_id,
status=TaskStatus.PENDING
)
db.add(task)
db.flush() # 获取task.id
# 处理标签关联
if task_data.tag_ids:
for tag_id in task_data.tag_ids:
tag = db.query(Tag).filter(Tag.id == tag_id).first()
if tag:
task_tag = TaskTag(task_id=task.id, tag_id=tag_id)
db.add(task_tag)
# 如果有截止日期,创建提醒
if task_data.due_date:
remind_at = task_data.due_date - timedelta(hours=1)
if remind_at > datetime.utcnow():
reminder = Reminder(
task_id=task.id,
remind_at=remind_at
)
db.add(reminder)
db.commit()
db.refresh(task)
# 加载关联数据
return task
Prompt 3.2:任务列表查询接口(多参数)
请帮我实现任务列表查询的API接口。
功能要求:
1. 路径:GET /api/tasks
2. 支持以下查询参数:
- page: 页码(默认1)
- page_size: 每页数量(默认20,最大100)
- status: 状态筛选(pending/in_progress/completed/cancelled)
- priority: 优先级筛选(low/medium/high)
- category_id: 分类筛选
- tag_id: 标签筛选
- assignee_id: 执行人筛选
- search: 关键词搜索(搜索title和description)
- sort_by: 排序字段(created_at/due_date/priority)
- order: 排序方向(asc/desc)
3. 只返回当前用户的任务(包括作为创建者或执行者的任务)
4. 返回格式:TaskListResponse(包含total、page、page_size、tasks)
5. 性能要求:
- 使用索引优化查询
- 避免N+1查询问题
- 预加载关联数据
请提供完整的路由代码,包含所有参数的处理逻辑。
AI输出:
from fastapi import APIRouter, Depends, Query
from sqlalchemy.orm import Session, joinedload
from sqlalchemy import or_, and_
from typing import Optional
from enum import Enum
from ..models import Task, TaskTag, Tag
from ..schemas import TaskListResponse, TaskResponse, TaskStatus, Priority
from ..database import get_db
from ..auth import get_current_user
from ..models import User
router = APIRouter(prefix="/api/tasks", tags=["tasks"])
class SortBy(str, Enum):
CREATED_AT = "created_at"
DUE_DATE = "due_date"
PRIORITY = "priority"
class Order(str, Enum):
ASC = "asc"
DESC = "desc"
@router.get("", response_model=TaskListResponse)
def get_tasks(
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=100),
status: Optional[TaskStatus] = None,
priority: Optional[Priority] = None,
category_id: Optional[str] = None,
tag_id: Optional[str] = None,
assignee_id: Optional[str] = None,
search: Optional[str] = None,
sort_by: SortBy = SortBy.CREATED_AT,
order: Order = Order.DESC,
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user)
):
"""
获取任务列表
支持多维度筛选、搜索和排序
"""
# 构建基础查询
query = db.query(Task).filter(
or_(
Task.creator_id == current_user.id,
Task.assignee_id == current_user.id
)
)
# 状态筛选
if status:
query = query.filter(Task.status == status)
# 优先级筛选
if priority:
query = query.filter(Task.priority == priority)
# 分类筛选
if category_id:
query = query.filter(Task.category_id == category_id)
# 执行人筛选
if assignee_id:
query = query.filter(Task.assignee_id == assignee_id)
# 标签筛选(需要join)
if tag_id:
query = query.join(TaskTag).filter(TaskTag.tag_id == tag_id)
# 关键词搜索
if search:
search_pattern = f"%{search}%"
query = query.filter(
or_(
Task.title.ilike(search_pattern),
Task.description.ilike(search_pattern)
)
)
# 排序
sort_column = {
SortBy.CREATED_AT: Task.created_at,
SortBy.DUE_DATE: Task.due_date,
SortBy.PRIORITY: Task.priority,
}[sort_by]
if order == Order.DESC:
query = query.order_by(sort_column.desc())
else:
query = query.order_by(sort_column.asc())
# 计算总数
total = query.count()
# 分页
offset = (page - 1) * page_size
tasks = query.offset(offset).limit(page_size).all()
# 预加载关联数据(避免N+1)
tasks = db.query(Task).options(
joinedload(Task.tags),
joinedload(Task.category),
joinedload(Task.creator),
joinedload(Task.assignee)
).filter(
Task.id.in_([task.id for task in tasks])
).all()
return TaskListResponse(
total=total,
page=page,
page_size=page_size,
tasks=tasks
)
Prompt 3.3:任务更新接口(复杂逻辑)
请帮我实现任务更新的API接口。
业务逻辑要求:
1. 路径:PUT /api/tasks/{task_id}
2. 只有任务的创建者可以更新任务
3. 更新逻辑:
- 如果status变为completed,自动设置completed_at
- 如果status从completed变为其他状态,清空completed_at
- 如果category_id改变,验证新分类属于当前用户
- 如果assignee_id改变,验证新用户存在
- 如果tag_ids改变:
* 删除旧的标签关联
* 创建新的标签关联
- 如果due_date改变:
* 删除旧的提醒
* 如果有新的due_date,创建新的提醒(due_date前1小时)
4. 返回:TaskResponse
5. 错误处理:
- 403: 没有权限
- 404: 任务不存在
请提供完整的路由代码。
AI输出:
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from datetime import datetime, timedelta
from typing import Optional
from ..models import Task, Category, User, Tag, TaskTag, Reminder, TaskStatus
from ..schemas import TaskUpdate, TaskResponse
from ..database import get_db
from ..auth import get_current_user
router = APIRouter(prefix="/api/tasks", tags=["tasks"])
@router.put("/{task_id}", response_model=TaskResponse)
def update_task(
task_id: str,
task_update: TaskUpdate,
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user)
):
"""
更新任务
只有任务的创建者可以更新
"""
# 获取任务
task = db.query(Task).filter(Task.id == task_id).first()
if not task:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"任务 {task_id} 不存在"
)
# 权限检查
if task.creator_id != current_user.id:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="只有任务的创建者可以更新任务"
)
# 更新基本字段
if task_update.title is not None:
task.title = task_update.title
if task_update.description is not None:
task.description = task_update.description
if task_update.priority is not None:
task.priority = task_update.priority
if task_update.due_date is not None:
task.due_date = task_update.due_date
# 处理status变化
if task_update.status is not None:
old_status = task.status
task.status = task_update.status
# 如果变为completed,设置completed_at
if task_update.status == TaskStatus.COMPLETED and old_status != TaskStatus.COMPLETED:
task.completed_at = datetime.utcnow()
# 如果从completed变为其他状态,清空completed_at
elif task_update.status != TaskStatus.COMPLETED and old_status == TaskStatus.COMPLETED:
task.completed_at = None
# 更新category_id
if task_update.category_id is not None:
if task_update.category_id != task.category_id:
# 验证新分类
if task_update.category_id:
category = db.query(Category).filter(
Category.id == task_update.category_id,
Category.user_id == current_user.id
).first()
if not category:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"分类 {task_update.category_id} 不存在"
)
task.category_id = task_update.category_id
# 更新assignee_id
if task_update.assignee_id is not None:
if task_update.assignee_id != task.assignee_id:
# 验证新用户
if task_update.assignee_id:
assignee = db.query(User).filter(
User.id == task_update.assignee_id
).first()
if not assignee:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"用户 {task_update.assignee_id} 不存在"
)
task.assignee_id = task_update.assignee_id
# 更新tag_ids
if task_update.tag_ids is not None:
# 删除旧的标签关联
db.query(TaskTag).filter(TaskTag.task_id == task_id).delete()
# 创建新的标签关联
if task_update.tag_ids:
for tag_id in task_update.tag_ids:
tag = db.query(Tag).filter(Tag.id == tag_id).first()
if tag:
task_tag = TaskTag(task_id=task_id, tag_id=tag_id)
db.add(task_tag)
# 处理due_date变化,更新提醒
if task_update.due_date is not None and task_update.due_date != task.due_date:
# 删除旧的提醒
db.query(Reminder).filter(Reminder.task_id == task_id).delete()
# 创建新的提醒
new_remind_at = task_update.due_date - timedelta(hours=1)
if new_remind_at > datetime.utcnow():
reminder = Reminder(
task_id=task_id,
remind_at=new_remind_at
)
db.add(reminder)
task.updated_at = datetime.utcnow()
db.commit()
db.refresh(task)
return task
阶段四:前端组件开发
Prompt 4.1:任务列表组件
请帮我开发一个任务列表组件。
技术栈:
- Vue 3 + TypeScript
- Element Plus UI框架
- Composition API
组件要求:
1. 组件名:TaskList
2. Props:
- tasks: Task[] - 任务列表
- loading: boolean - 加载状态
3. Features:
- 显示任务列表,每行显示:标题、状态、优先级、截止日期、创建者
- 状态用不同颜色的标签显示
- 优先级用不同颜色的徽章显示
- 支持点击任务行查看详情
- 支持行内编辑状态
- 支持删除任务
4. Events:
- @task-click: 点击任务时触发
- @status-change: 状态改变时触发
- @delete: 删除任务时触发
5. UI要求:
- 使用Element Plus的Table组件
- 响应式布局
- 空状态提示
- 加载状态提示
请提供完整的组件代码,包括:
- Template
- Script(TypeScript)
- Style
AI输出:
<template>
<div class="task-list">
<el-table
:data="tasks"
v-loading="loading"
empty-text="暂无任务"
@row-click="handleTaskClick"
class="task-table"
>
<!-- 标题列 -->
<el-table-column prop="title" label="标题" min-width="200">
<template #default="{ row }">
<div class="task-title">
<span>{{ row.title }}</span>
<el-tag
v-if="row.tags.length > 0"
size="small"
type="info"
class="task-tags"
>
{{ row.tags.length }}个标签
</el-tag>
</div>
</template>
</el-table-column>
<!-- 状态列 -->
<el-table-column prop="status" label="状态" width="120">
<template #default="{ row }">
<el-select
:model-value="row.status"
@change="handleStatusChange(row, $event)"
size="small"
@click.stop
>
<el-option label="待处理" value="pending" />
<el-option label="进行中" value="in_progress" />
<el-option label="已完成" value="completed" />
<el-option label="已取消" value="cancelled" />
</el-select>
</template>
</el-table-column>
<!-- 优先级列 -->
<el-table-column prop="priority" label="优先级" width="100">
<template #default="{ row }">
<el-tag
:type="getPriorityType(row.priority)"
size="small"
>
{{ getPriorityLabel(row.priority) }}
</el-tag>
</template>
</el-table-column>
<!-- 截止日期列 -->
<el-table-column prop="due_date" label="截止日期" width="150">
<template #default="{ row }">
<span v-if="row.due_date" :class="getDueDateClass(row.due_date)">
{{ formatDate(row.due_date) }}
</span>
<span v-else class="no-date">-</span>
</template>
</el-table-column>
<!-- 创建者列 -->
<el-table-column prop="creator.name" label="创建者" width="120">
<template #default="{ row }">
<div class="creator">
<el-avatar :size="24" :src="row.creator?.avatar_url">
{{ row.creator?.name?.[0] }}
</el-avatar>
<span>{{ row.creator?.name }}</span>
</div>
</template>
</el-table-column>
<!-- 操作列 -->
<el-table-column label="操作" width="100" fixed="right">
<template #default="{ row }">
<el-button
type="danger"
size="small"
link
@click.stop="handleDelete(row)"
>
删除
</el-button>
</template>
</el-table-column>
</el-table>
</div>
</template>
<script setup lang="ts">
import { defineProps, defineEmits } from 'vue'
import type { Task } from '@/types/task'
// Props
interface Props {
tasks: Task[]
loading: boolean
}
const props = withDefaults(defineProps<Props>(), {
tasks: () => [],
loading: false
})
// Emits
const emit = defineEmits<{
taskClick: [task: Task]
statusChange: [task: Task, status: string]
delete: [task: Task]
}>()
// 优先级类型映射
const getPriorityType = (priority: string) => {
const typeMap: Record<string, any> = {
low: '',
medium: 'warning',
high: 'danger'
}
return typeMap[priority] || ''
}
// 优先级标签映射
const getPriorityLabel = (priority: string) => {
const labelMap: Record<string, string> = {
low: '低',
medium: '中',
high: '高'
}
return labelMap[priority] || priority
}
// 截止日期样式
const getDueDateClass = (dueDate: string) => {
const now = new Date()
const due = new Date(dueDate)
const diff = due.getTime() - now.getTime()
const days = diff / (1000 * 60 * 60 * 24)
if (days < 0) return 'overdue'
if (days <= 1) return 'urgent'
if (days <= 3) return 'warning'
return ''
}
// 格式化日期
const formatDate = (date: string) => {
const d = new Date(date)
return d.toLocaleDateString('zh-CN', {
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit'
})
}
// 事件处理
const handleTaskClick = (task: Task) => {
emit('taskClick', task)
}
const handleStatusChange = (task: Task, status: string) => {
emit('statusChange', task, status)
}
const handleDelete = (task: Task) => {
emit('delete', task)
}
</script>
<style scoped lang="scss">
.task-list {
width: 100%;
}
.task-table {
cursor: pointer;
:deep(.el-table__row:hover) {
background-color: #f5f7fa;
}
}
.task-title {
display: flex;
align-items: center;
gap: 8px;
}
.task-tags {
margin-left: auto;
}
.creator {
display: flex;
align-items: center;
gap: 8px;
}
.overdue {
color: #f56c6c;
font-weight: bold;
}
.urgent {
color: #e6a23c;
font-weight: bold;
}
.warning {
color: #409eff;
}
.no-date {
color: #909399;
}
</style>
阶段五:测试代码生成
Prompt 5.1:API测试
请为任务API生成完整的测试用例。
测试框架:pytest
测试库:pytest-asyncio, httpx
需要测试的接口:
1. POST /api/tasks - 创建任务
2. GET /api/tasks - 获取任务列表
3. GET /api/tasks/{task_id} - 获取任务详情
4. PUT /api/tasks/{task_id} - 更新任务
5. DELETE /api/tasks/{task_id} - 删除任务
测试要求:
1. 测试正常流程
2. 测试各种参数组合
3. 测试错误情况(404、403、422)
4. 测试权限控制
5. 测试数据验证
6. 使用fixture复用测试数据
7. 测试覆盖率 > 80%
请提供完整的测试代码。
AI输出:
import pytest
from fastapi.testclient import TestClient
from sqlalchemy.orm import Session
from datetime import datetime, timedelta
import json
from app.main import app
from app.database import get_db, engine, Base
from app.models import User, Task, Category, Tag
from app.auth import create_access_token
client = TestClient(app)
# 测试数据库fixture
@pytest.fixture
def db_session():
Base.metadata.create_all(bind=engine)
db = next(get_db())
try:
yield db
finally:
db.close()
Base.metadata.drop_all(bind=engine)
# 测试用户fixture
@pytest.fixture
def test_user(db_session: Session):
user = User(
email="test@example.com",
password_hash="hashed_password",
name="Test User"
)
db_session.add(user)
db_session.commit()
db_session.refresh(user)
return user
# 测试用户2 fixture
@pytest.fixture
def test_user2(db_session: Session):
user = User(
email="test2@example.com",
password_hash="hashed_password",
name="Test User 2"
)
db_session.add(user)
db_session.commit()
db_session.refresh(user)
return user
# 认证token fixture
@pytest.fixture
def auth_headers(test_user: User):
token = create_access_token(data={"sub": test_user.id})
return {"Authorization": f"Bearer {token}"}
# 测试任务fixture
@pytest.fixture
def test_task(db_session: Session, test_user: User):
task = Task(
title="Test Task",
description="Test Description",
priority="medium",
creator_id=test_user.id,
status="pending"
)
db_session.add(task)
db_session.commit()
db_session.refresh(task)
return task
# 测试分类fixture
@pytest.fixture
def test_category(db_session: Session, test_user: User):
category = Category(
name="Work",
user_id=test_user.id,
color="#3498db"
)
db_session.add(category)
db_session.commit()
db_session.refresh(category)
return category
# 测试标签fixture
@pytest.fixture
def test_tag(db_session: Session):
tag = Tag(name="urgent", color="#e74c3c")
db_session.add(tag)
db_session.commit()
db_session.refresh(tag)
return tag
class TestCreateTask:
def test_create_task_success(self, auth_headers):
"""测试成功创建任务"""
response = client.post(
"/api/tasks",
json={
"title": "New Task",
"description": "Task Description",
"priority": "high"
},
headers=auth_headers
)
assert response.status_code == 201
data = response.json()
assert data["title"] == "New Task"
assert data["description"] == "Task Description"
assert data["priority"] == "high"
assert data["status"] == "pending"
assert "id" in data
def test_create_task_missing_title(self, auth_headers):
"""测试缺少标题"""
response = client.post(
"/api/tasks",
json={"description": "Task Description"},
headers=auth_headers
)
assert response.status_code == 422
def test_create_task_invalid_priority(self, auth_headers):
"""测试无效的优先级"""
response = client.post(
"/api/tasks",
json={
"title": "New Task",
"priority": "invalid"
},
headers=auth_headers
)
assert response.status_code == 422
def test_create_task_with_category(
self, auth_headers, test_category
):
"""测试带分类创建任务"""
response = client.post(
"/api/tasks",
json={
"title": "New Task",
"category_id": test_category.id
},
headers=auth_headers
)
assert response.status_code == 201
data = response.json()
assert data["category_id"] == test_category.id
def test_create_task_with_due_date_reminder(self, auth_headers):
"""测试创建带截止日期的任务自动创建提醒"""
due_date = (datetime.utcnow() + timedelta(hours=3)).isoformat()
response = client.post(
"/api/tasks",
json={
"title": "New Task",
"due_date": due_date
},
headers=auth_headers
)
assert response.status_code == 201
class TestGetTasks:
def test_get_tasks_success(self, auth_headers, test_task):
"""测试成功获取任务列表"""
response = client.get("/api/tasks", headers=auth_headers)
assert response.status_code == 200
data = response.json()
assert "tasks" in data
assert "total" in data
assert len(data["tasks"]) >= 1
def test_get_tasks_with_filter(
self, auth_headers, db_session, test_user
):
"""测试带筛选条件获取任务"""
# 创建不同状态的任务
task1 = Task(
title="Pending Task",
status="pending",
creator_id=test_user.id
)
task2 = Task(
title="Completed Task",
status="completed",
creator_id=test_user.id
)
db_session.add_all([task1, task2])
db_session.commit()
# 筛选pending任务
response = client.get(
"/api/tasks?status=pending",
headers=auth_headers
)
assert response.status_code == 200
data = response.json()
assert all(t["status"] == "pending" for t in data["tasks"])
def test_get_tasks_with_pagination(self, auth_headers, db_session, test_user):
"""测试分页"""
# 创建25个任务
tasks = [
Task(
title=f"Task {i}",
creator_id=test_user.id
)
for i in range(25)
]
db_session.add_all(tasks)
db_session.commit()
# 获取第一页
response = client.get(
"/api/tasks?page=1&page_size=10",
headers=auth_headers
)
assert response.status_code == 200
data = response.json()
assert data["page"] == 1
assert data["page_size"] == 10
assert len(data["tasks"]) == 10
assert data["total"] == 25
def test_get_tasks_unauthorized(self):
"""测试未授权访问"""
response = client.get("/api/tasks")
assert response.status_code == 401
class TestUpdateTask:
def test_update_task_success(
self, auth_headers, test_task
):
"""测试成功更新任务"""
response = client.put(
f"/api/tasks/{test_task.id}",
json={
"title": "Updated Task",
"status": "completed"
},
headers=auth_headers
)
assert response.status_code == 200
data = response.json()
assert data["title"] == "Updated Task"
assert data["status"] == "completed"
assert data["completed_at"] is not None
def test_update_task_unauthorized(
self, auth_headers, test_task, test_user2
):
"""测试无权限更新"""
response = client.put(
f"/api/tasks/{test_task.id}",
json={"title": "Hacked"},
headers={"Authorization": f"Bearer {create_access_token(data={'sub': test_user2.id})}"}
)
assert response.status_code == 403
def test_update_task_not_found(self, auth_headers):
"""测试任务不存在"""
response = client.put(
"/api/tasks/nonexistent",
json={"title": "Updated"},
headers=auth_headers
)
assert response.status_code == 404
def test_update_task_status_to_completed(
self, auth_headers, test_task
):
"""测试状态变为completed自动设置completed_at"""
response = client.put(
f"/api/tasks/{test_task.id}",
json={"status": "completed"},
headers=auth_headers
)
assert response.status_code == 200
data = response.json()
assert data["completed_at"] is not None
def test_update_task_status_from_completed(
self, db_session, auth_headers, test_task
):
"""测试状态从completed变为其他"""
test_task.status = "completed"
test_task.completed_at = datetime.utcnow()
db_session.commit()
response = client.put(
f"/api/tasks/{test_task.id}",
json={"status": "pending"},
headers=auth_headers
)
assert response.status_code == 200
data = response.json()
assert data["completed_at"] is None
class TestDeleteTask:
def test_delete_task_success(
self, auth_headers, test_task
):
"""测试成功删除任务"""
response = client.delete(
f"/api/tasks/{test_task.id}",
headers=auth_headers
)
assert response.status_code == 200
def test_delete_task_unauthorized(
self, auth_headers, test_task, test_user2
):
"""测试无权限删除"""
response = client.delete(
f"/api/tasks/{test_task.id}",
headers={"Authorization": f"Bearer {create_access_token(data={'sub': test_user2.id})}"}
)
assert response.status_code == 403
阶段六:文档与部署
Prompt 6.1:API文档
请为TaskFlow API生成完整的API文档。
文档格式:Markdown
文档内容:
1. 项目简介
2. 技术栈
3. 认证方式(JWT)
4. API端点列表
5. 每个端点的详细说明:
- 端点路径
- 请求方法
- 请求参数
- 请求体
- 响应体
- 错误码
- 示例请求和响应
6. 数据模型说明
请生成完整的API文档。
AI输出:
# TaskFlow API 文档
## 项目简介
TaskFlow是一个功能完善的待办事项管理系统,支持任务管理、分类、标签、提醒、协作等功能。
## 技术栈
- 后端框架:FastAPI
- ORM:SQLAlchemy
- 数据库:PostgreSQL
- 认证:JWT (JSON Web Token)
- API文档:Swagger UI / ReDoc
## 认证方式
TaskFlow使用JWT进行身份验证。
### 获取Token
**端点**:`POST /api/auth/login`
**请求体**:
```json
{
"email": "user@example.com",
"password": "password123"
}
响应:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"user": {
"id": "user-id",
"email": "user@example.com",
"name": "User Name"
}
}
使用Token
在请求头中添加:
Authorization: Bearer {access_token}
API端点列表
用户管理
POST /api/auth/register– 用户注册POST /api/auth/login– 用户登录GET /api/users/me– 获取当前用户信息PUT /api/users/me– 更新当前用户信息
任务管理
GET /api/tasks– 获取任务列表POST /api/tasks– 创建任务GET /api/tasks/{task_id}– 获取任务详情PUT /api/tasks/{task_id}– 更新任务DELETE /api/tasks/{task_id}– 删除任务
分类管理
GET /api/categories– 获取分类列表POST /api/categories– 创建分类GET /api/categories/{category_id}– 获取分类详情PUT /api/categories/{category_id}– 更新分类DELETE /api/categories/{category_id}– 删除分类
标签管理
GET /api/tags– 获取标签列表POST /api/tags– 创建标签GET /api/tags/{tag_id}– 获取标签详情PUT /api/tags/{tag_id}– 更新标签DELETE /api/tags/{tag_id}– 删除标签
详细端点说明
GET /api/tasks – 获取任务列表
获取当前用户的任务列表,支持筛选、搜索、排序和分页。
请求方法:GET
请求参数:
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| page | integer | 否 | 页码,默认1 | 1 |
| page_size | integer | 否 | 每页数量,默认20,最大100 | 20 |
| status | string | 否 | 任务状态筛选 | pending |
| priority | string | 否 | 优先级筛选 | high |
| category_id | string | 否 | 分类ID筛选 | cat-id |
| tag_id | string | 否 | 标签ID筛选 | tag-id |
| assignee_id | string | 否 | 执行人ID筛选 | user-id |
| search | string | 否 | 关键词搜索 | 关键词 |
| sort_by | string | 否 | 排序字段 | created_at |
| order | string | 否 | 排序方向 | desc |
状态枚举:
– pending – 待处理
– in_progress – 进行中
– completed – 已完成
– cancelled – 已取消
优先级枚举:
– low – 低
– medium – 中
– high – 高
排序字段:
– created_at – 创建时间
– due_date – 截止日期
– priority – 优先级
响应:
{
"total": 50,
"page": 1,
"page_size": 20,
"tasks": [
{
"id": "task-id-1",
"title": "完成项目文档",
"description": "编写API文档和用户手册",
"status": "in_progress",
"priority": "high",
"due_date": "2026-03-25T18:00:00",
"creator_id": "user-id",
"assignee_id": "assignee-id",
"category_id": "cat-id",
"tags": [
{
"id": "tag-id",
"name": "urgent",
"color": "#e74c3c"
}
],
"created_at": "2026-03-21T10:00:00",
"updated_at": "2026-03-21T14:00:00",
"completed_at": null
}
]
}
错误码:
– 401 – 未认证
– 500 – 服务器错误
POST /api/tasks – 创建任务
创建一个新的任务。
请求方法:POST
请求头:
Authorization: Bearer {access_token}
Content-Type: application/json
请求体:
{
"title": "任务标题",
"description": "任务描述",
"priority": "high",
"due_date": "2026-03-25T18:00:00",
"assignee_id": "user-id",
"category_id": "cat-id",
"tag_ids": ["tag-id-1", "tag-id-2"]
}
请求体参数:
| 参数 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
| title | string | 是 | 任务标题 | 1-200字符 |
| description | string | 否 | 任务描述 | – |
| priority | string | 否 | 优先级 | low/medium/high |
| due_date | string | 否 | 截止日期 | ISO 8601格式 |
| assignee_id | string | 否 | 执行人ID | 有效的用户ID |
| category_id | string | 否 | 分类ID | 属于当前用户的分类 |
| tag_ids | array | 否 | 标签ID列表 | 有效的标签ID数组 |
响应:201 Created
{
"id": "new-task-id",
"title": "任务标题",
"description": "任务描述",
"status": "pending",
"priority": "high",
"due_date": "2026-03-25T18:00:00",
"creator_id": "user-id",
"assignee_id": "assignee-id",
"category_id": "cat-id",
"tags": [],
"created_at": "2026-03-21T15:00:00",
"updated_at": "2026-03-21T15:00:00",
"completed_at": null
}
错误码:
– 401 – 未认证
– 404 – 分类或用户不存在
– 422 – 数据验证失败
PUT /api/tasks/{task_id} – 更新任务
更新指定的任务。只有任务的创建者可以更新。
请求方法:PUT
请求头:
Authorization: Bearer {access_token}
Content-Type: application/json
路径参数:
– task_id – 任务ID
请求体(所有字段可选):
{
"title": "更新后的标题",
"description": "更新后的描述",
"status": "completed",
"priority": "medium",
"due_date": "2026-03-26T18:00:00",
"assignee_id": "new-user-id",
"category_id": "new-cat-id",
"tag_ids": ["tag-id-3"]
}
响应:200 OK
返回更新后的任务详情,格式同创建任务响应。
错误码:
– 401 – 未认证
– 403 – 无权限(非任务创建者)
– 404 – 任务不存在
– 422 – 数据验证失败
DELETE /api/tasks/{task_id} – 删除任务
删除指定的任务。只有任务的创建者可以删除。
请求方法:DELETE
请求头:
Authorization: Bearer {access_token}
路径参数:
– task_id – 任务ID
响应:200 OK
{
"message": "任务已删除"
}
错误码:
– 401 – 未认证
– 403 – 无权限(非任务创建者)
– 404 – 任务不存在
数据模型
Task(任务)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 任务ID(UUID) |
| title | string | 任务标题 |
| description | string | 任务描述 |
| status | string | 任务状态 |
| priority | string | 优先级 |
| due_date | datetime | 截止日期 |
| creator_id | string | 创建者ID |
| assignee_id | string | 执行人ID |
| category_id | string | 分类ID |
| tags | array | 标签列表 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
| completed_at | datetime | 完成时间 |
User(用户)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 用户ID(UUID) |
| string | 邮箱 | |
| name | string | 姓名 |
| avatar_url | string | 头像URL |
| is_active | boolean | 是否激活 |
| created_at | datetime | 创建时间 |
Category(分类)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 分类ID(UUID) |
| name | string | 分类名称 |
| color | string | 分类颜色 |
| icon | string | 分类图标 |
| user_id | string | 所属用户ID |
| created_at | datetime | 创建时间 |
Tag(标签)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 标签ID(UUID) |
| name | string | 标签名称 |
| color | string | 标签颜色 |
| created_at | datetime | 创建时间 |
错误响应格式
所有错误响应遵循以下格式:
{
"detail": "错误描述信息"
}
常见错误码:
– 400 – 请求错误
– 401 – 未认证
– 403 – 无权限
– 404 – 资源不存在
– 422 – 数据验证失败
– 500 – 服务器错误
---
## Prompt优化技巧
### 技巧1:使用示例驱动
**原则**:提供具体的输入输出示例,帮助AI理解期望。
**示例**:
请帮我编写一个函数,计算任务列表的完成率。
要求:
– 输入:Task对象列表
– 输出:完成率(0-1之间的浮点数)
– 完成率 = 已完成任务数 / 总任务数
示例:
输入:[
Task(status=”completed”),
Task(status=”pending”),
Task(status=”completed”)
]
输出:0.6667(2/3)
请提供Python代码实现。
### 技巧2:分步引导
**原则**:将复杂任务分解为多个步骤,逐步引导AI完成。
**示例**:
第一步:请帮我设计一个任务的SQLAlchemy模型,包含id、title、status、created_at字段。
第二步:基于上面的模型,创建对应的Pydantic Schema。
第三步:实现创建任务的API接口。
### 技巧3:明确约束条件
**原则**:明确说明必须遵守的约束和不能做的事情。
**示例**:
请生成一个用户注册的API接口。
要求:
– 使用FastAPI框架
– 密码必须使用bcrypt加密
– 邮箱必须验证格式
– 返回用户信息时不要包含密码
– 不要使用第三方认证库
约束:
– 必须验证密码长度(至少6位)
– 必须验证邮箱唯一性
– 必须处理重复注册的错误
### 技巧4:提供上下文
**原则**:提供充分的背景信息,帮助AI做出正确的决策。
**示例**:
项目背景:TaskFlow是一个待办事项管理系统,采用微服务架构。
当前情况:
– 用户服务已经完成,提供了用户认证API
– 任务服务正在开发中
– 需要调用用户服务验证用户ID
请实现任务创建接口,要求:
1. 验证用户ID是否有效(调用用户服务API)
2. 如果用户不存在,返回404错误
3. 如果用户存在,创建任务
用户服务API:GET http://user-service/api/users/{user_id}
### 技巧5:使用角色设定
**原则**:为AI设定角色,让AI以特定视角思考问题。
**示例**:
你是一个资深的FastAPI专家,专注于代码质量和最佳实践。
请帮我审查以下代码,指出潜在的问题:
[代码内容]
重点关注:
1. 安全性
2. 性能
3. 错误处理
4. 代码风格
5. 最佳实践
请提供详细的改进建议。
---
## 常见错误与解决方案
### 错误1:意图不明确
**问题**:
“帮我写个API”
**解决方案**:
“请帮我实现一个用户登录的API接口:
– 路径:POST /api/auth/login
– 请求体:{email, password}
– 验证:使用bcrypt验证密码
– 返回:JWT token和用户信息
– 错误:认证失败返回401”
### 错误2:缺少上下文
**问题**:
“生成一个Task模型”
**解决方案**:
“基于FastAPI和SQLAlchemy,生成一个Task模型:
– 包含id、title、status、priority字段
– 使用UUID作为id
– status使用枚举类型
– 添加created_at和updated_at时间戳
– 与User模型建立多对一关系”
### 错误3:缺少约束条件
**问题**:
“创建一个用户注册接口”
**解决方案**:
“创建一个用户注册接口:
– 验证邮箱格式
– 验证密码长度(至少6位)
– 检查邮箱是否已存在
– 密码使用bcrypt加密
– 不要返回密码哈希
– 处理所有可能的错误情况”
### 错误4:Prompt过长
**问题**:Prompt包含过多细节,导致AI理解困难。
**解决方案**:
- 将长Prompt拆分为多个短Prompt
- 使用结构化格式(列表、表格)
- 使用"参见"引用之前的上下文
- 分阶段完成任务
### 错误5:缺少迭代
**问题**:一次性生成,不进行优化。
**解决方案**:
第一轮:生成初始代码
第二轮:优化代码性能
第三轮:添加错误处理
第四轮:编写测试用例
---
## Prompt模板库
### 模板1:API接口生成
```markdown
请帮我实现一个[功能名称]的API接口。
技术栈:[FastAPI/Flask/Django]
ORM:[SQLAlchemy/Django ORM]
接口要求:
- 路径:[HTTP方法] /api/path
- 需要认证:[是/否]
- 请求参数:[参数列表]
- 请求体:[请求体结构]
- 验证规则:[验证规则]
- 业务逻辑:[业务逻辑描述]
- 返回:[返回数据结构]
- 错误处理:[错误码和错误信息]
请提供完整的路由代码,包括:
- 路由定义
- 依赖注入
- 业务逻辑
- 错误处理
- 数据验证
模板2:数据模型生成
请帮我生成一个[模型名称]的SQLAlchemy模型。
要求:
- 使用Python类型注解
- 包含字段:[字段列表]
- 建立表关系:[关系描述]
- 添加索引:[索引列表]
- 包含时间戳:created_at, updated_at
- 使用字符串id
请提供完整的模型代码。
模板3:测试用例生成
请为[功能名称]生成完整的测试用例。
测试框架:pytest
需要测试的场景:
1. [场景1]
2. [场景2]
3. [场景3]
测试要求:
- 测试正常流程
- 测试边界情况
- 测试错误情况
- 使用fixture复用测试数据
- 测试覆盖率 > 80%
请提供完整的测试代码。
模板4:代码审查
请帮我审查以下代码,指出潜在的问题。
代码背景:[背景信息]
[代码内容]
重点关注:
1. 安全性
2. 性能
3. 错误处理
4. 代码风格
5. 最佳实践
请提供:
- 问题列表
- 严重程度评估
- 改进建议
- 优化后的代码(如有必要)
模板5:文档生成
请为[功能/模块]生成完整的文档。
文档格式:Markdown
文档内容:
1. 简介
2. 功能说明
3. 使用方法
4. API文档(如有)
5. 示例代码
6. 注意事项
请生成完整的文档。
总结
本文通过TaskFlow待办事项管理系统的完整开发过程,展示了Vibe Coding中Prompt编写的最佳实践。关键要点包括:
核心原则
- 清晰性:意图表达清晰明确,避免歧义
- 具体性:提供足够的细节和上下文
- 结构化:使用清晰的结构组织Prompt
- 上下文:提供充分的背景信息
- 迭代性:通过多次迭代逐步完善
实践技巧
- 示例驱动:提供具体的输入输出示例
- 分步引导:将复杂任务分解为多个步骤
- 明确约束:说明必须遵守的约束条件
- 提供上下文:帮助AI做出正确决策
- 角色设定:为AI设定特定角色
避免错误
- 避免意图不明确
- 避免缺少上下文
- 避免缺少约束条件
- 避免Prompt过长
- 避免缺少迭代优化
通过遵循这些原则和技巧,你可以编写出高质量的Prompt,显著提升Vibe Coding的效率和代码质量。记住,Prompt工程是一个持续改进的过程,需要不断实践和优化。
文档版本:v1.0
最后更新:2026年3月21日
作者:iFlow CLI
项目示例:TaskFlow待办事项管理系统