项目初始化与代码生成

项目初始化与代码生成

本节摘要:架构方案确定后,进入「动手」阶段。本节演示如何用 Agent 模式搭建项目脚手架:生成目录结构、配置文件、数据模型、基础 API,以及前端页面骨架。核心技巧是「分步生成 + 每步验证」——不要一口气让 AI 生成整个项目,而是按模块逐步推进,每步跑通再继续。

一、后端脚手架:一步步来

第一步:项目结构 + 依赖

创建一个 FastAPI 项目,结构如下:

backend/
├── src/
│   ├── api/        (路由)
│   ├── services/   (业务逻辑)
│   ├── models/     (SQLAlchemy 模型)
│   ├── schemas/    (Pydantic 模型)
│   ├── core/       (配置、数据库、安全)
│   └── main.py     (入口)
├── tests/
├── alembic/        (数据库迁移)
├── requirements.txt
└── .env.example

requirements.txt 包含:
fastapi, uvicorn, sqlalchemy[asyncio], asyncpg,
pydantic-settings, python-jose, passlib, alembic, pytest, httpx
​

Agent 会创建目录和文件。验证:pip install -r requirements.txt 能成功安装。

第二步:数据库连接 + 配置

在 src/core/ 中创建:
- config.py: 用 pydantic-settings 读取 .env(DATABASE_URL, SECRET_KEY)
- database.py: 创建 async engine 和 session factory
- 在 main.py 中配置 lifespan 事件(启动时测试连接)

参考 .env.example 的格式创建 .env(本地开发用)。
创建完成后运行 uvicorn src.main:app --reload 验证能启动。
​

验证:服务启动无报错,访问 /docs 能看到 Swagger 页面。

第三步:数据模型

创建三个核心模型(src/models/):

User: id, email, password_hash, name, created_at
Project: id, name, description, owner_id(FK→User), created_at
Task: id, title, description, status(enum: todo/in_progress/done),
      order(int), project_id(FK→Project), assignee_id(FK→User, nullable),
      created_at, updated_at

用 SQLAlchemy 2.0 声明式映射(Mapped, mapped_column)。
创建对应的 Pydantic schemas(请求/响应分离)。
配置 Alembic 并生成初始迁移。
​

验证:alembic upgrade head 成功建表。

💡 技巧:每完成一步就验证。如果第三步报错(比如模型定义有语法问题),在小范围内修复比「生成了 20 个文件后才发现第一步就有问题」容易 10 倍。

二、基础 API:认证 + CRUD

第四步:认证模块

实现 JWT 认证:
- src/core/security.py: hash_password, verify_password, create_token, decode_token
- src/api/auth.py: POST /auth/register, POST /auth/login
- src/api/deps.py: get_current_user 依赖(从 Bearer token 解析用户)

注册时校验邮箱格式和密码长度(≥8)。
登录成功返回 {access_token, token_type: "bearer"}。
​

验证:用 Swagger 测试注册 → 登录 → 拿到 token。

第五步:Task CRUD

实现任务的 CRUD API(src/api/tasks.py):
- GET /projects/{id}/tasks — 列表(按 order 排序)
- POST /projects/{id}/tasks — 创建
- PUT /tasks/{id} — 更新(标题/描述/状态/分配)
- PATCH /tasks/{id}/status — 单独改状态(拖拽用)
- DELETE /tasks/{id} — 删除

所有接口需要认证(Depends(get_current_user))。
Service 层实现逻辑,路由层只做参数校验和调用。
​

验证:用 Swagger 或 httpie 跑通全部接口。

三、前端脚手架

第六步:Next.js 初始化

在 frontend/ 目录创建 Next.js 14 项目:
- 用 App Router + TypeScript + Tailwind
- 配置 src/ 目录结构(app/, components/, lib/, stores/, types/)
- 创建基础的 API 请求封装(src/lib/api.ts):
  - 基于 fetch,自动带 Authorization header
  - 统一错误处理
- 创建登录页面(src/app/login/page.tsx):
  - 邮箱 + 密码表单
  - 调用后端 /auth/login
  - 成功后存 token 到 localStorage,跳转首页
​

验证:npm run dev 启动,登录页面能渲染,登录请求能到达后端。

第七步:看板页面骨架

创建看板页面(src/app/projects/[id]/page.tsx):
- 三列布局:Todo / In Progress / Done
- 每列显示对应状态的 Task 卡片
- Task 卡片组件(src/components/TaskCard.tsx):
  - 显示标题、分配人头像、创建时间
- 暂时不做拖拽,先用按钮切换状态

用 useFetch hook 从后端获取任务列表。
​

验证:页面能显示从后端获取的任务数据。

四、分步生成的核心原则

回顾整个过程,关键原则是:

1. 每步只做一件事:不要「把整个后端都写了」,而是「先写模型」「再写认证」「再写 CRUD」
2. 每步都验证:跑命令确认能运行,再进入下一步
3. 出错在小范围修:第三步出错只需要改模型文件,不需要在 50 个文件里找问题
4. 先骨架后血肉:先让项目能跑起来(哪怕功能很简陋),再逐步添加功能

⚠️ 注意:Agent 模式生成代码时,一定要审查 requirements.txt / package.json 中的依赖——AI 可能引入你不想用的库,或者用了不兼容的版本。

本节要点回顾

1. 分步生成:结构 → 配置 → 模型 → API → 前端,每步验证后再继续
2. 验证驱动:每步结束跑一个命令确认(pip install / uvicorn / alembic / npm run dev)
3. 后端顺序:core(配置/数据库)→ models → auth → CRUD
4. 前端顺序:初始化 → API 封装 → 登录页 → 核心页面
5. 审查重点:依赖列表、版本兼容性、目录结构是否符合约定
6. 核心心态:先让它跑起来,再让它变完美

项目骨架搭好了。接下来是持续迭代:添加功能、处理依赖冲突、管理跨模块修改。