AI编程 实战案例分享｜附完整命令

在过去一年里，“AI 编程”已经从一个新鲜概念，逐渐变成了很多开发者日常工作流的一部分。无论是写脚本、搭建接口、重构老项目，还是生成测试用例、排查报错，AI 都可以在其中承担“辅助工程师”的角色。

但很多人真正上手时会遇到一个问题：
AI 到底该怎么用于真实项目？是让它直接写代码，还是只用来查资料？命令怎么写？项目怎么跑起来？

本文将通过一个完整的实战案例，演示如何借助 AI 从 0 到 1 完成一个小型 Web 项目：AI 编程实战：构建一个“任务管理 API 服务”。
案例包含需求分析、项目初始化、接口设计、代码生成、运行调试、测试验证、文档整理等完整流程，并附带可直接执行的命令。

一、案例目标：构建一个任务管理 API 服务

本次实战项目是一个轻量级的任务管理后端服务，功能类似一个简化版 Todo List。

我们希望实现以下能力：

1. 创建任务
2. 查询任务列表
3. 查询单个任务详情
4. 更新任务状态
5. 删除任务
6. 提供基础接口文档
7. 支持本地运行和接口测试

为了降低复杂度，本文使用以下技术栈：

选择 FastAPI 的原因很简单：它语法简洁、开发效率高、自动生成接口文档，非常适合演示 AI 编程的完整流程。

二、AI 编程不是“让 AI 代替你写代码”

在开始之前，需要先澄清一个常见误区：
AI 编程并不是把需求丢给 AI，然后完全不管。

更高效的方式应该是：

1. 人负责定义目标和约束
2. AI 辅助拆解任务
3. AI 生成初版代码
4. 人审查代码结构和关键逻辑
5. AI 辅助修复报错和补充测试
6. 人最终验证功能是否符合预期

也就是说，AI 更像是一个“高效率编程搭档”，而不是完全自治的工程师。

如果你直接输入：

帮我写一个任务管理系统

AI 可能会返回一大段看似完整、但无法直接运行的代码。
更好的提示词应该包含：

• 使用什么语言
• 使用什么框架
• 需要哪些功能
• 项目结构如何组织
• 是否需要完整命令
• 是否需要测试方式
• 是否需要异常处理

例如：

请使用 Python + FastAPI + SQLite + SQLAlchemy 实现一个任务管理 API 服务。
要求：
1. 提供创建任务、查询列表、查询详情、更新任务、删除任务接口；
2. 使用 Pydantic 做请求和响应模型；
3. 使用 SQLAlchemy 操作 SQLite；
4. 给出完整项目结构；
5. 给出所有文件代码；
6. 给出本地运行命令和 curl 测试命令；
7. 代码要可以直接运行。

这种提示词就比一句“帮我写系统”要清晰得多。

三、项目最终目录结构

我们最终要得到的项目结构如下：

ai-task-api/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── database.py
│   ├── models.py
│   ├── schemas.py
│   └── crud.py
├── requirements.txt
└── README.md

每个文件的作用如下：

这种结构适合小型项目，也便于后续扩展。如果项目变大，可以继续拆分为 routers/、services/、repositories/ 等目录。

四、第一步：创建项目目录

首先在本地创建项目目录。

mkdir ai-task-api
cd ai-task-api

创建应用目录：

mkdir app
touch app/__init__.py

如果你使用的是 Windows PowerShell，可以使用：

mkdir ai-task-api
cd ai-task-api
mkdir app
New-Item app/__init__.py

五、第二步：创建 Python 虚拟环境

建议为每个项目单独创建虚拟环境，避免不同项目之间的依赖冲突。

macOS / Linux 命令如下：

python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell 命令如下：

python -m venv .venv
.venv\Scripts\Activate.ps1

如果激活成功，终端前面通常会出现：

(.venv)

这表示当前命令行已经进入虚拟环境。

六、第三步：安装项目依赖

创建 requirements.txt 文件：

touch requirements.txt

写入以下内容：

fastapi==0.115.0
uvicorn==0.30.6
SQLAlchemy==2.0.35
pydantic==2.9.2

安装依赖：

pip install -r requirements.txt

如果你希望使用国内镜像源，可以执行：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

七、第四步：让 AI 帮我们生成代码

接下来我们可以让 AI 按照项目结构生成代码。

推荐提示词如下：

请基于以下项目结构生成完整代码：

ai-task-api/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── database.py
│   ├── models.py
│   ├── schemas.py
│   └── crud.py
├── requirements.txt
└── README.md

技术要求：
1. Python + FastAPI；
2. SQLite 作为数据库；
3. SQLAlchemy 2.x；
4. Pydantic 2.x；
5. 实现任务管理 API，包括：
   - 创建任务
   - 查询任务列表
   - 查询任务详情
   - 更新任务
   - 删除任务
6. Task 字段包括：
   - id：整数，自增主键
   - title：字符串，必填
   - description：字符串，可选
   - completed：布尔值，默认 false
7. 请分别输出每个文件的完整代码；
8. 代码必须能直接运行；
9. 给出启动命令和 curl 测试命令。

通过这个提示词，AI 一般可以生成比较完整的代码。
下面是整理后的可运行版本。

八、核心代码实现

1. app/database.py

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, DeclarativeBase

SQLALCHEMY_DATABASE_URL = "sqlite:///./tasks.db"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    connect_args={"check_same_thread": False}
)

SessionLocal = sessionmaker(
    autocommit=False,
    autoflush=False,
    bind=engine
)


class Base(DeclarativeBase):
    pass


def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

这个文件主要负责数据库连接。
由于使用 SQLite，本地会自动生成一个 tasks.db 文件。

2. app/models.py

from sqlalchemy import Boolean, Integer, String
from sqlalchemy.orm import Mapped, mapped_column

from app.database import Base


class Task(Base):
    __tablename__ = "tasks"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
    title: Mapped[str] = mapped_column(String(100), nullable=False)
    description: Mapped[str | None] = mapped_column(String(500), nullable=True)
    completed: Mapped[bool] = mapped_column(Boolean, default=False)

这里定义了 tasks 数据表。
字段设计比较简单，适合用来演示基础 CRUD。

3. app/schemas.py

from pydantic import BaseModel, Field


class TaskBase(BaseModel):
    title: str = Field(..., min_length=1, max_length=100)
    description: str | None = Field(default=None, max_length=500)


class TaskCreate(TaskBase):
    pass


class TaskUpdate(BaseModel):
    title: str | None = Field(default=None, min_length=1, max_length=100)
    description: str | None = Field(default=None, max_length=500)
    completed: bool | None = None


class TaskResponse(TaskBase):
    id: int
    completed: bool

    model_config = {
        "from_attributes": True
    }

schemas.py 使用 Pydantic 定义接口输入输出模型。
这样做的好处是：

1. 自动校验请求参数
2. 自动生成接口文档
3. 避免直接暴露数据库模型
4. 提高接口的可维护性

4. app/crud.py

from sqlalchemy.orm import Session

from app.models import Task
from app.schemas import TaskCreate, TaskUpdate


def create_task(db: Session, task: TaskCreate):
    db_task = Task(
        title=task.title,
        description=task.description,
        completed=False
    )
    db.add(db_task)
    db.commit()
    db.refresh(db_task)
    return db_task


def get_tasks(db: Session, skip: int = 0, limit: int = 20):
    return db.query(Task).offset(skip).limit(limit).all()


def get_task(db: Session, task_id: int):
    return db.query(Task).filter(Task.id == task_id).first()


def update_task(db: Session, task_id: int, task_update: TaskUpdate):
    db_task = get_task(db, task_id)

    if not db_task:
        return None

    update_data = task_update.model_dump(exclude_unset=True)

    for key, value in update_data.items():
        setattr(db_task, key, value)

    db.commit()
    db.refresh(db_task)
    return db_task


def delete_task(db: Session, task_id: int):
    db_task = get_task(db, task_id)

    if not db_task:
        return None

    db.delete(db_task)
    db.commit()
    return db_task

这个文件把数据库操作从路由中抽离出来。
这样可以让 main.py 更清晰，也方便后续编写单元测试。

5. app/main.py

from fastapi import Depends, FastAPI, HTTPException, status
from sqlalchemy.orm import Session

from app import crud, models, schemas
from app.database import engine, get_db

models.Base.metadata.create_all(bind=engine)

app = FastAPI(
    title="AI Task API",
    description="一个使用 AI 辅助开发的任务管理 API 服务",
    version="1.0.0"
)


@app.get("/")
def root():
    return {
        "message": "AI Task API is running",
        "docs": "/docs"
    }


@app.post(
    "/tasks",
    response_model=schemas.TaskResponse,
    status_code=status.HTTP_201_CREATED
)
def create_task(
    task: schemas.TaskCreate,
    db: Session = Depends(get_db)
):
    return crud.create_task(db=db, task=task)


@app.get(
    "/tasks",
    response_model=list[schemas.TaskResponse]
)
def list_tasks(
    skip: int = 0,
    limit: int = 20,
    db: Session = Depends(get_db)
):
    return crud.get_tasks(db=db, skip=skip, limit=limit)


@app.get(
    "/tasks/{task_id}",
    response_model=schemas.TaskResponse
)
def get_task(
    task_id: int,
    db: Session = Depends(get_db)
):
    db_task = crud.get_task(db=db, task_id=task_id)

    if not db_task:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Task not found"
        )

    return db_task


@app.patch(
    "/tasks/{task_id}",
    response_model=schemas.TaskResponse
)
def update_task(
    task_id: int,
    task_update: schemas.TaskUpdate,
    db: Session = Depends(get_db)
):
    db_task = crud.update_task(
        db=db,
        task_id=task_id,
        task_update=task_update
    )

    if not db_task:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Task not found"
        )

    return db_task


@app.delete("/tasks/{task_id}")
def delete_task(
    task_id: int,
    db: Session = Depends(get_db)
):
    db_task = crud.delete_task(db=db, task_id=task_id)

    if not db_task:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Task not found"
        )

    return {
        "message": "Task deleted successfully",
        "task_id": task_id
    }

至此，一个基础的任务管理 API 已经完成。

九、第五步：启动项目

在项目根目录执行：

uvicorn app.main:app --reload

如果运行成功，终端会看到类似输出：

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete.

访问首页：

curl http://127.0.0.1:8000/

预期返回：

{
  "message": "AI Task API is running",
  "docs": "/docs"
}

也可以在浏览器打开：

http://127.0.0.1:8000/docs

FastAPI 会自动生成 Swagger UI 文档，你可以直接在页面上测试接口。

十、第六步：使用 curl 测试接口

1. 创建任务

curl -X POST "http://127.0.0.1:8000/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "学习 AI 编程",
    "description": "使用 FastAPI 构建一个任务管理 API"
  }'

预期返回：

{
  "title": "学习 AI 编程",
  "description": "使用 FastAPI 构建一个任务管理 API",
  "id": 1,
  "completed": false
}

2. 查询任务列表

curl "http://127.0.0.1:8000/tasks"

预期返回：

[
  {
    "title": "学习 AI 编程",
    "description": "使用 FastAPI 构建一个任务管理 API",
    "id": 1,
    "completed": false
  }
]

3. 查询单个任务

curl "http://127.0.0.1:8000/tasks/1"

预期返回：

{
  "title": "学习 AI 编程",
  "description": "使用 FastAPI 构建一个任务管理 API",
  "id": 1,
  "completed": false
}

4. 更新任务状态

curl -X PATCH "http://127.0.0.1:8000/tasks/1" \
  -H "Content-Type: application/json" \
  -d '{
    "completed": true
  }'

预期返回：

{
  "title": "学习 AI 编程",
  "description": "使用 FastAPI 构建一个任务管理 API",
  "id": 1,
  "completed": true
}

5. 修改任务标题和描述

curl -X PATCH "http://127.0.0.1:8000/tasks/1" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "完成 AI 编程实战案例",
    "description": "整理完整命令、代码和测试流程"
  }'

6. 删除任务

curl -X DELETE "http://127.0.0.1:8000/tasks/1"

预期返回：

{
  "message": "Task deleted successfully",
  "task_id": 1
}

十一、用 AI 排查常见问题

AI 编程过程中，不可避免会遇到报错。关键不是不报错，而是要会把报错信息有效地交给 AI。

问题 1：ModuleNotFoundError: No module named 'app'

可能原因是你不在项目根目录执行命令。

错误示例：

cd app
uvicorn main:app --reload

正确方式是在项目根目录执行：

uvicorn app.main:app --reload

可以向 AI 提问：

我运行 FastAPI 项目时报错：
ModuleNotFoundError: No module named 'app'

我的项目结构是：
ai-task-api/
├── app/
│   ├── main.py
│   └── ...

我执行的命令是：
uvicorn main:app --reload

请分析原因并给出正确运行命令。

问题 2：ImportError 或相对导入错误

如果你写成：

from .database import Base

在某些执行方式下可能会遇到导入问题。
本文统一使用：

from app.database import Base

并要求从项目根目录启动：

uvicorn app.main:app --reload

这样更适合初学者理解。

问题 3：数据库表没有创建

如果没有执行：

models.Base.metadata.create_all(bind=engine)

数据库文件可能生成了，但表没有创建。
本文将其放在 main.py 中，应用启动时会自动创建表。

如果你后续做正式项目，更推荐使用 Alembic 做数据库迁移。

十二、AI 编程的高效提示词模板

很多人使用 AI 编程效果不好，不是 AI 不会写代码，而是需求描述不够清楚。

下面给出几个实用模板。

1. 生成项目模板

请使用【技术栈】实现一个【项目名称】。
功能包括：
1. ...
2. ...
3. ...

要求：
- 给出项目目录结构；
- 给出每个文件的完整代码；
- 代码可以直接运行；
- 给出安装依赖命令；
- 给出启动命令；
- 给出测试命令；
- 使用清晰的注释解释关键逻辑。

2. 排查报错模板

我在运行项目时遇到以下报错：

【粘贴完整报错】

我的项目结构是：

【粘贴目录结构】

相关代码如下：

【粘贴相关代码】

我执行的命令是：

【粘贴命令】

请你：
1. 判断最可能的原因；
2. 给出修改方案；
3. 给出修改后的完整代码；
4. 告诉我如何验证问题已经解决。

3. 代码重构模板

请帮我重构以下代码，要求：
1. 不改变现有功能；
2. 提高可读性；
3. 拆分过长函数；
4. 增加必要类型注解；
5. 保留原有接口兼容性；
6. 说明你做了哪些修改以及原因。

代码如下：
【粘贴代码】

4. 生成测试用例模板

请为以下 FastAPI 接口生成 pytest 测试用例。
要求：
1. 覆盖创建、查询、更新、删除任务；
2. 覆盖任务不存在的 404 场景；
3. 使用 TestClient；
4. 给出测试文件完整代码；
5. 给出运行测试的命令。

接口代码如下：
【粘贴 main.py 代码】

十三、进一步优化：增加 pytest 测试

如果想让项目更接近真实开发，可以继续让 AI 添加自动化测试。

安装 pytest：

pip install pytest httpx

也可以更新 requirements.txt：

fastapi==0.115.0
uvicorn==0.30.6
SQLAlchemy==2.0.35
pydantic==2.9.2
pytest==8.3.3
httpx==0.27.2

创建测试目录：

mkdir tests
touch tests/test_tasks.py

可以让 AI 生成测试代码：

请基于当前 FastAPI 任务管理 API 生成 pytest 测试代码。
要求：
1. 使用 fastapi.testclient.TestClient；
2. 测试创建任务；
3. 测试查询任务列表；
4. 测试查询不存在任务返回 404；
5. 测试更新任务；
6. 测试删除任务；
7. 给出 tests/test_tasks.py 完整代码。

一个简单测试示例如下：

from fastapi.testclient import TestClient

from app.main import app

client = TestClient(app)


def test_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json()["message"] == "AI Task API is running"


def test_create_task():
    response = client.post(
        "/tasks",
        json={
            "title": "测试任务",
            "description": "这是一个测试任务"
        }
    )

    assert response.status_code == 201
    data = response.json()
    assert data["title"] == "测试任务"
    assert data["completed"] is False
    assert "id" in data

运行测试：

pytest

如果通过，会看到类似输出：

2 passed in 0.80s

十四、进一步优化：生成 README 文档

一个完整项目最好包含 README。我们可以让 AI 根据代码生成文档。

提示词：

请根据以下 FastAPI 项目代码，生成一份 README.md。
要求包括：
1. 项目简介；
2. 技术栈；
3. 项目结构；
4. 安装依赖；
5. 启动服务；
6. API 接口说明；
7. curl 测试命令；
8. 常见问题。

README 示例结构：

# AI Task API

一个使用 FastAPI 构建的任务管理 API 服务。

## 技术栈

- Python
- FastAPI
- SQLite
- SQLAlchemy
- Pydantic

## 启动项目

```bash
pip install -r requirements.txt
uvicorn app.main:app --reload

接口文档

启动后访问：

http://127.0.0.1:8000/docs

注意：README 不只是给别人看的，也是给未来的自己看的。  
很多项目过几周再打开，如果没有说明文档，重新理解会非常费时间。

---

## 十五、这个案例中 AI 真正帮了什么？

通过这个案例可以看到，AI 并不只是“生成几行代码”，它在多个环节都能提升效率。

### 1. 需求拆解

当你只有一个模糊想法时，可以让 AI 帮你拆成接口、数据模型、目录结构和开发步骤。

### 2. 代码生成

对于常规 CRUD、配置文件、测试样例、README 等内容，AI 生成速度非常快。

### 3. 报错分析

把完整报错、执行命令、目录结构、相关代码发给 AI，通常能很快定位问题。

### 4. 代码审查

可以让 AI 检查代码中是否存在：

- 安全风险
- 命名混乱
- 重复逻辑
- 异常处理不足
- 不符合框架最佳实践的写法

### 5. 文档补全

项目文档、接口说明、部署说明、测试说明都可以交给 AI 生成初稿，再由开发者审核修改。

---

## 十六、AI 编程的注意事项

虽然 AI 很强，但在实际开发中仍然需要保持谨慎。

### 1. 不要盲目信任生成代码

AI 可能会写出看似合理但无法运行的代码，也可能使用过时 API。  
例如 Pydantic v1 和 v2 的配置方式不同：

Pydantic v1 常见写法：

```python
class Config:
    orm_mode = True

Pydantic v2 推荐写法：

model_config = {
    "from_attributes": True
}

如果你不检查版本，可能会遇到奇怪的问题。

2. 一次不要让 AI 做太多事

不要一上来就让 AI 写完整大型系统。
更好的方式是分阶段：

1. 先生成目录结构
2. 再生成数据库模型
3. 再生成接口
4. 再补测试
5. 再优化文档
6. 最后做代码审查

3. 报错要提供完整上下文

只说“报错了怎么办”效果很差。
应该提供：

• 完整报错
• 操作系统
• Python 版本
• 依赖版本
• 执行命令
• 项目结构
• 相关代码

上下文越完整，AI 越容易给出准确答案。

4. 关键业务逻辑必须人工审核

如果涉及支付、权限、资金、隐私数据、生产数据库等关键业务，不能直接复制 AI 代码上线。
AI 可以提高效率，但最终责任仍然在开发者。

十七、完整命令汇总

下面整理本案例从创建项目到运行测试的完整命令。

macOS / Linux

mkdir ai-task-api
cd ai-task-api

mkdir app
touch app/__init__.py
touch app/main.py app/database.py app/models.py app/schemas.py app/crud.py
touch requirements.txt README.md

python3 -m venv .venv
source .venv/bin/activate

cat > requirements.txt << 'EOF'
fastapi==0.115.0
uvicorn==0.30.6
SQLAlchemy==2.0.35
pydantic==2.9.2
EOF

pip install -r requirements.txt

uvicorn app.main:app --reload

Windows PowerShell

mkdir ai-task-api
cd ai-task-api

mkdir app
New-Item app/__init__.py
New-Item app/main.py
New-Item app/database.py
New-Item app/models.py
New-Item app/schemas.py
New-Item app/crud.py
New-Item requirements.txt
New-Item README.md

python -m venv .venv
.venv\Scripts\Activate.ps1

@"
fastapi==0.115.0
uvicorn==0.30.6
SQLAlchemy==2.0.35
pydantic==2.9.2
"@ | Set-Content requirements.txt

pip install -r requirements.txt

uvicorn app.main:app --reload

接口测试命令

curl http://127.0.0.1:8000/

curl -X POST "http://127.0.0.1:8000/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "学习 AI 编程",
    "description": "完成 FastAPI 任务管理 API"
  }'

curl "http://127.0.0.1:8000/tasks"

curl "http://127.0.0.1:8000/tasks/1"

curl -X PATCH "http://127.0.0.1:8000/tasks/1" \
  -H "Content-Type: application/json" \
  -d '{
    "completed": true
  }'

curl -X DELETE "http://127.0.0.1:8000/tasks/1"

十八、总结

本文通过一个“任务管理 API 服务”的完整案例，演示了 AI 编程在真实开发流程中的使用方式。

我们完成了：

• 使用 AI 拆解项目需求
• 设计项目目录结构
• 编写 FastAPI 接口
• 使用 SQLite 和 SQLAlchemy 存储数据
• 使用 Pydantic 校验数据
• 本地启动服务
• 使用 curl 测试接口
• 总结 AI 提示词模板
• 整理完整命令

AI 编程的核心并不是“让 AI 一次性生成完美项目”，而是把 AI 放进开发流程里，让它参与需求拆解、代码生成、报错排查、测试补充和文档整理。

对于开发者来说，未来真正重要的能力不仅是“会写代码”，还包括：

1. 能清楚描述需求；
2. 能设计合理架构；
3. 能判断 AI 代码质量；
4. 能定位和修复问题；
5. 能把 AI 融入自己的工程化流程。

当你掌握了这些方法，AI 就不再只是一个聊天工具，而会成为你开发过程中的高效协作者。