第 6 章 · 前端、后端与数据库怎么协作

 浏览器（前端）                        服务器（后端）           数据库
┌─────────────────┐              ┌──────────────────┐   ┌─────────────┐
│ ① 表单收集输入    │              │                  │   │             │
│ ② 发送请求 ──────┼──────────────▶ ③ 验明身份        │   │             │
│                  │   HTTP       │    （会话→user_id）│   │             │
│                  │              │ ④ 校验内容        │   │             │
│                  │              │    （空？太长？）   │   │             │
│                  │              │ ⑤ 写入 ───────────┼──▶ │ ⑥ INSERT    │
│                  │              │                  │   │   存一行     │
│ ⑦ 收到响应，      │◀─────────────┼── 返回结果 ───────┼─── │             │
│   刷新列表        │              │                  │   │             │
└─────────────────┘              └──────────────────┘   └─────────────┘

create table words (
  id          bigint generated always as identity primary key,
  user_id     uuid not null,          -- 这行词归哪个账号（登录服务提供）
  word        text not null,          -- 单词，如 resume
  meaning     text not null,          -- 释义（必填：强迫第一次加工）
  example     text,                   -- 例句，选填
  source      text,                   -- 在哪遇到的，选填
  status      text not null default 'learning',  -- learning / mastered
  created_at  timestamptz not null default now(),
  updated_at  timestamptz not null default now(),
  unique (user_id, word)              -- 同一账号不重复（AC6 的数据库层兜底）
);

sqlite3 /tmp/vocab-sandbox.db

-- 建表（SQLite 方言；与上面 Postgres 版的差异只在自增主键和时间的写法）
create table words (
  id         integer primary key autoincrement,
  user_id    text not null,
  word       text not null,
  meaning    text not null,
  status     text not null default 'learning',
  unique (user_id, word)
);

-- 两个账号各录一条
insert into words (user_id, word, meaning) values
  ('user-A', 'resume', 'v. 重新开始；n. 简历'),
  ('user-B', 'negotiate', 'v. 谈判');

-- ① 账号 A 的词表（权限查询的雏形：永远带 user_id 条件）
select word, status from words where user_id = 'user-A';

resume|learning

-- ② 账号 A 重复录入 resume（AC6 会发生什么）
insert into words (user_id, word, meaning) values ('user-A', 'resume', '重复的释义');

Error: stepping, UNIQUE constraint failed: words.user_id, words.word (19)

-- ③ 标记已掌握（AC4 的本质是 update）
update words set status = 'mastered' where user_id = 'user-A' and word = 'resume';
select word, status from words where user_id = 'user-A';

-- ④ 筛选未掌握（AC5 的本质是带条件的 select）
select word from words where user_id = 'user-A' and status = 'learning';

-- ⑤ 权限反例：如果查询忘了带 user_id 条件，会发生什么？
select user_id, word from words;

// 校验录入内容：通过返回干净的数据，不通过返回中文错误
export function validateWord(input: unknown): { ok: true; value: WordInput } | { ok: false; error: string } {
  const { word, meaning, example } = (input ?? {}) as Partial<WordInput>;

  if (typeof word !== 'string' || word.trim().length === 0) {
    return { ok: false, error: '单词不能为空' };
  }
  if (word.trim().length > 100) {
    return { ok: false, error: '单词最长 100 个字符' };
  }
  if (typeof meaning !== 'string' || meaning.trim().length === 0) {
    return { ok: false, error: '释义不能为空——用你自己的话写' };
  }
  // ……长度上限检查同型，略
  return {
    ok: true,
    value: { word: word.trim(), meaning: meaning.trim() },
  };
}

// POST /api/words —— 「添加一个单词」的服务端（节选，讲解用）
export async function POST(request: Request) {
  // ③ 验明身份：从会话里取当前用户（见下节「登录身份」）
  const user = await getUserFromSession();
  if (!user) {
    return Response.json({ error: '未登录' }, { status: 401 });
  }

  // ④ 校验内容
  const body = await request.json();
  const check = validateWord(body);
  if (!check.ok) {
    return Response.json({ error: check.error }, { status: 400 });
  }

  // ⑤ 写入数据库（user_id 来自会话，不由请求提供——防伪造）
  await db.insert(words).values({
    user_id: user.id,
    word: check.value.word,
    meaning: check.value.meaning,
  });

  // ⑦ 告诉前端成了
  return Response.json({ ok: true }, { status: 201 });
}