跳到正文
零到全栈 · 卷 5 · 后端与 API

联调收口

本合集目录
本章目录

单册说明:本文件是卷 5 的第 8 章,可独立阅读。前置:第 1–7 章(接口、报文、环境、服务、校验、错误、跨域)。本章把前端的 data 层接到真接口上,并给出一张"出问题先看哪"的分诊表。

项 内容
所属卷 卷 5 · 后端与 API(第 8 / 8 章)
前置章节 5.7 CORS 与预检
本章产出 lib/api.js 数据层 + 两套环境变量 + 一张联调分诊表 + 一份上线前检查表
对应代码 frontend/lib/api.js、frontend/app/page.js、frontend/app/notes/new/page.js、.env.local / .env.production / .env.example
配图 无(后续统一制图)
读完的判定 新增一条摘录后刷新页面还在,重启后端后刷新还在;遇到 404/422/500 能直接说出先查哪里

5.8.1 一句话结论:联调不是"调通一次",是"换台机器也能通"

先看一个必然会发生的场景。

你在自己电脑上跑通了:前端 npm run dev,后端 uvicorn,点新增,列表出来了。你把代码推到仓库,同事拉下来,跑起来——列表空白,控制台写着:

GET http://127.0.0.1:8000/api/notes net::ERR_CONNECTION_REFUSED

他没启动后端,这很正常。但即使他启动了,还有第二个问题:如果他要在自己手机上预览,127.0.0.1 指的是手机自己。

所以这一章做的不是"接上接口",而是三件让联调可复制的事:

事情 不做会怎样
一个数据层出口 接口地址散落在八个组件里,换环境要改八处
环境变量分两套 开发和生产共用一个地址,上线必错
一张分诊表 每次报错都从零开始猜

5.8.2 原理与方法

数据层的价值:所有 URL 与字段名只出现一次

卷 4 的 lib/notes.js 读本地文件。现在它要换成调接口,但页面不该知道这件事。判断标准很简单:

页面里出现 fetch 或 http://,就说明数据层漏了。

改造后的分工:

层 只关心 不知道什么
页面(app/**/page.js) 我要一个数组、我要提交一个对象 数据从哪来、用什么协议
数据层(lib/api.js) 路径、方法、错误码、字段名 页面怎么渲染
后端 存储、校验、状态码 谁在调用

这条线一旦划清,卷 6 换数据库、卷 7 换域名,页面一行都不用改。

服务端取数与客户端取数:CORS 只在其中一边出现

维度 服务端组件里 fetch 客户端组件里 fetch
谁发请求 Node 进程(Next 服务器) 用户的浏览器
受同源策略约束 不受 受
需要配 CORS 不需要 需要
能读服务端密钥 能 不能
首屏 HTML 自带内容 先空壳,后填充
缓存 可按 revalidate 控制 由浏览器管

这就解释了一个经典困惑:"我在服务端组件里取数,从来没配过 CORS,也好好的"——因为浏览器压根没参与。等你加一个"提交表单"的客户端组件,CORS 立刻找上门。

本书的分配:

页面 取数方式 原因
/ 列表 服务端组件 首屏就要有内容,且不需要 CORS
/notes/[id] 详情 服务端组件 同上
/notes/new 表单提交 客户端组件 需要即时反馈、按钮禁用、字段级错误

两边都用同一个 lib/api.js——取数方式变了,数据层不变。

两套环境变量,一次构建

文件 什么时候生效 提交到 Git 内容
.env.local 本机开发(优先级最高) 否 NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000
.env.production npm run build + npm start 可以(不含密钥) NEXT_PUBLIC_API_BASE_URL=(空,表示同源)
.env.example 不生效,只给人看 是 键名 + 注释

NEXT_PUBLIC_ 的规则卷 4 讲过:构建时被替换成字面量。所以它有一个必须记住的后果:

改了 NEXT_PUBLIC_ 的值,必须重新构建;只重启进程没用。

生产那行填空字符串是有意的:

const BASE_URL = (process.env.NEXT_PUBLIC_API_BASE_URL ?? '').replace(/\/+$/, '');

空字符串时,fetch('/api/notes') 是相对路径,请求打到当前域名——正好是同源部署的形态。这就是卷 7 的方案:Nginx 把 / 交给 Next,把 /api/ 转给 FastAPI,浏览器眼里只有一个站。

⚠️ 注意 ?? 与 || 的区别:?? 只在 null/undefined 时兜底,空字符串会保留。这里必须用 ??,否则"生产留空"会被兜底成开发地址。

契约对齐:四件必须逐项对的事

项 后端 前端容易写成 后果
字段名 source_url(下划线) sourceUrl(驼峰,卷 4 的老写法) undefined,页面显示空
时间 2026-11-16T18:24:15Z(UTC,Z 结尾) 直接 new Date() 显示 时区偏移 8 小时
空值 null "" 或 undefined 提交时把 "" 存进库,校验通过但数据脏
id 整数 1 当成字符串拼 URL 拼出来一样能通,但比较时 "1" !== 1

时间这一项最阴。后端给的是 UTC,浏览器 new Date("...Z") 会自动转成本地时区,所以展示没问题;但如果你自己截字符串 created_at.slice(0, 10),拿到的就是 UTC 的日期——北京时间早上 7 点前保存的摘录,会显示成"昨天"。

联调分诊表:先看哪,再看哪

这张表是本章最该贴在显示器边上的东西:

症状 第一眼看 常见成因 对应章节
控制台 ERR_CONNECTION_REFUSED 后端在不在跑 忘了启动 / 端口不对 5.3
404,URL 里有两个斜杠 请求 URL baseURL 末尾 / 拼上 /api 本章坑一
404,URL 缺 /api 请求 URL 前缀 数据层路径写漏 5.1
422 Payload 字段名驼峰、类型不对、空字符串 本章坑二
列表有数据但页面空白 响应体字段名 source_url vs sourceUrl 本章坑二
500 后端日志(用 request_id 搜) 代码 bug / 数据文件坏了 5.6
blocked by CORS policy Console + Network 的 OPTIONS 客户端组件跨源,未配 allow_origins 5.7
请求一直 pending Network 的 Timing 后端卡住 / 端口被占 5.4
新增成功但列表不更新 页面是否有动态渲染 静态缓存 / 没 router.refresh() 4.7
上线后所有接口 502 Nginx 与后端进程 后端没起 / 只监听 127.0.0.1 卷 7

用这张表的方式是从上往下排除,不要跳。跳步的典型表现是:明明是 404,却去改 CORS 配置,改了两小时。

上线前检查表

这份表在卷 7 会再出现一次,现在先建立习惯:

# 检查项 怎么验
1 五个端点全部可用 curl 各发一次,看状态码
2 错误体形状统一 故意发一个空标题,看是不是 {"error":{...}}
3 日志有 request_id 制造一次 500,grep 那个 id
4 /docs 是否要关 生产环境默认不该公开(卷 7)
5 数据文件在版本控制之外 git check-ignore -v backend/data/notes.json
6 .env.local 没提交 `git ls-files
7 前端没有硬编码接口地址 grep -rn "127.0.0.1" app/ lib/ 只应命中 .env
8 生产 baseURL 是相对路径 构建产物里搜 127.0.0.1,搜不到才对

第 8 条有个手边的验证方法(卷 4 用过同款思路):

grep -rl "127.0.0.1" .next/static | head

有输出就说明开发地址被打进了浏览器包,生产环境会去连用户自己的电脑。

5.8.3 动手:把前端接到真接口

第一步:数据层

新建 frontend/lib/api.js(删掉或保留 lib/notes.js 都行,页面不再引用它):

const RAW_BASE = process.env.NEXT_PUBLIC_API_BASE_URL ?? 'http://127.0.0.1:8000';
const BASE_URL = RAW_BASE.replace(/\/+$/, '');

export class ApiError extends Error {
  constructor(status, code, message, fields = []) {
    super(message);
    this.name = 'ApiError';
    this.status = status;
    this.code = code;
    this.fields = fields;
  }
}

async function request(path, options = {}) {
  const res = await fetch(`${BASE_URL}${path}`, {
    cache: 'no-store',
    ...options,
    headers: { 'Content-Type': 'application/json', ...(options.headers ?? {}) },
  });

  if (res.status === 204) return null;

  const type = res.headers.get('content-type') ?? '';
  if (!type.includes('application/json')) {
    throw new ApiError(res.status, 'bad_response', `期望 JSON,实际收到 ${type || '未知类型'}`);
  }

  const data = await res.json();
  if (!res.ok) {
    const body = data?.error ?? {};
    throw new ApiError(
      res.status,
      body.code ?? 'unknown',
      body.message ?? `HTTP ${res.status}`,
      body.fields ?? [],
    );
  }
  return data;
}

export function getNotes() {
  return request('/api/notes');
}

export function getNote(id) {
  return request(`/api/notes/${id}`);
}

export function createNote(input) {
  return request('/api/notes', { method: 'POST', body: JSON.stringify(input) });
}

export function updateNote(id, input) {
  return request(`/api/notes/${id}`, { method: 'PATCH', body: JSON.stringify(input) });
}

export function deleteNote(id) {
  return request(`/api/notes/${id}`, { method: 'DELETE' });
}

五个设计点,每个都对应一个真实的坑:

写法 解决什么
RAW_BASE.replace(/\/+$/, '') baseURL 末尾带 / 时拼出 //api/notes(坑一)
res.status === 204 先返回 204 没有体,res.json() 会抛 Unexpected end of JSON input
检查 content-type 返回 HTML 时给一句人话,而不是 Unexpected token '<'(5.2)
body.error.code 统一错误体(5.6),前端只写一套分支
导出的是函数不是常量 调用时才发请求,服务端渲染时不会被模块加载顺序坑到

第二步:列表页

app/page.js:

import Link from 'next/link';
import { getNotes } from '@/lib/api';

export const dynamic = 'force-dynamic';

export default async function HomePage() {
  const notes = await getNotes();

  return (
    <main className="page">
      <h1>读到</h1>
      <p className="meta">共 {notes.length} 条摘录</p>
      <ul className="note-list">
        {notes.map((note) => (
          <li key={note.id}>
            <Link href={`/notes/${note.id}`}>{note.title}</Link>
            <time dateTime={note.created_at}>{note.created_at.slice(0, 10)}</time>
          </li>
        ))}
      </ul>
      <p>
        <Link href="/notes/new">新增一条</Link>
      </p>
    </main>
  );
}

export const dynamic = 'force-dynamic' 是必需的:不加的话,首页可能在构建时就被渲染成静态 HTML,之后新增的摘录永远不出现(卷 4 踩过的坑,这里换成了接口,问题一模一样)。

notes.length 而不是 notes.total——因为契约里返回的是数组,不是 {items, total}。这就是契约的价值:写页面时不用猜。

第三步:新增页

app/notes/new/page.js:

'use client';

import { useState } from 'react';
import { useRouter } from 'next/navigation';
import { createNote } from '@/lib/api';

export default function NewNotePage() {
  const router = useRouter();
  const [form, setForm] = useState({ title: '', content: '', source_url: '' });
  const [fields, setFields] = useState([]);
  const [error, setError] = useState('');
  const [saving, setSaving] = useState(false);

  function update(key) {
    return (event) => setForm({ ...form, [key]: event.target.value });
  }

  async function onSubmit(event) {
    event.preventDefault();
    setSaving(true);
    setError('');
    setFields([]);
    try {
      await createNote({ ...form, source_url: form.source_url || null });
      router.push('/');
      router.refresh();
    } catch (err) {
      setError(err.message);
      setFields(err.fields ?? []);
    } finally {
      setSaving(false);
    }
  }

  function fieldError(name) {
    return fields.find((item) => item.field === name)?.message ?? '';
  }

  return (
    <form className="note-form" onSubmit={onSubmit}>
      <label>
        标题
        <input value={form.title} onChange={update('title')} maxLength={120} />
        {fieldError('title') && <span className="err">{fieldError('title')}</span>}
      </label>

      <label>
        正文
        <textarea value={form.content} onChange={update('content')} rows={6} />
        {fieldError('content') && <span className="err">{fieldError('content')}</span>}
      </label>

      <label>
        来源链接(可空)
        <input value={form.source_url} onChange={update('source_url')} />
      </label>

      {error && <p className="err">{error}</p>}

      <button type="submit" disabled={saving}>
        {saving ? '保存中…' : '保存'}
      </button>
    </form>
  );
}

三个细节:

细节 为什么
source_url: form.source_url || null 空字符串转 null,契约里 source_url 可为 null(5.8.2 的空值对齐)
disabled={saving} 防重复提交(5.1 讲过的"POST 不幂等",这里用最省事的解法)
router.refresh() 让首页重新走一次服务端渲染,否则返回后还是旧列表

fieldError 用的是后端返回的 fields 数组——错误提示的字段名由后端给,前端只负责显示。这样加一个字段时,前端不用改校验逻辑。

第四步:环境变量

.env.local:

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000

.env.production:

# 生产走同源部署:/api 由 Nginx 转给后端,前端用相对路径
NEXT_PUBLIC_API_BASE_URL=

.env.example:

# 本地开发指向本机后端;生产留空,表示与前端同源
NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000

确认它没被提交:

git check-ignore -v .env.local
git ls-files | grep env

第一行有输出(匹配到忽略规则)、第二行只看到 .env.example,才算对。

第五步:跑通,然后验持久化

# 终端 A
cd backend && source .venv/Scripts/activate && python -m uvicorn app.main:app --reload

# 终端 B
cd frontend && npm run dev

打开 http://localhost:3000,新增一条,回到首页——出现了。然后做两个验证:

验证 操作 期望
刷新不丢 按 F5 那条还在(说明它不是只存在 React state 里)
重启不丢 Ctrl+C 停掉后端,再启动,刷新 那条还在(说明落到了 data/notes.json)

第二条是这一卷的"存住"验证。顺手打开 backend/data/notes.json 看一眼——你会看到中文是明文,created_at 带 Z,id 是整数。这就是你亲手写出来的第一条数据。

还有一个不启前端也能验证数据层的技巧(我实测时就用它):

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000 node --input-type=module -e "
import('./lib/api.js').then(async (m) => {
  console.log(JSON.stringify(await m.getNotes()));
  try { await m.getNote(999); } catch (e) { console.log(e.status, e.code, e.message); }
});
"

形如:

[{"id":1,"title":"闭包","content":"函数记住词法环境","source_url":null,"created_at":"2026-11-16T18:27:53Z"}]
404 not_found id=999 的摘录不存在

页面还没写好的时候,数据层就能先验收——这就是分层的实际好处。

5.8.4 三个坑

坑一:baseURL 末尾一个斜杠,拼出两个

症状:列表页 404,Network 里 URL 是 http://127.0.0.1:8000//api/notes;点开响应:

{"error":{"code":"not_found","message":"Not Found"}}

成因:.env.local 写成了 http://127.0.0.1:8000/,数据层再拼 /api/notes,就成了 //api/notes。多数服务器不会把双斜杠归一化,FastAPI 会直接当未知路径。实测确认://api/notes 返回 404,/api/notes 返回 200。

修法:数据层统一做一次归一化(replace(/\/+$/, '')),而不是要求所有人"注意别写斜杠"。凡是"要求人记住"的规范,早晚会破;能写进代码的规范才可靠。

坑二:字段名驼峰与下划线混用

症状:表单能提交成功,但刷新后列表里那条显示"无标题";或者提交直接 422,fields 里写着 source_url。

成因:卷 4 的本地 JSON 用的是 sourceUrl、createdAt(驼峰),这一卷开始统一成 source_url、created_at(下划线,与数据库列名一致)。页面里残留一处老写法,就是这个结果。

修法:三步。① 全仓库搜一遍老字段名,逐个改;② 提交时确认 source_url 拼写(少个下划线就是另一个字段,后端会当"没传");③ 在 lib/api.js 里加一层映射,把后端的下划线转成前端习惯的驼峰——但这只适合字段多、且团队强约定驼峰的场景,本书不这么做:统一用后端名字,少一层转换就少一处错。

坑三:服务端组件里 fetch('http://127.0.0.1:8000'),上线后取不到

症状:本地一切正常;部署到服务器后,页面直接 500,日志里是 fetch failed 或 ECONNREFUSED 127.0.0.1:8000。

成因:服务端组件的 fetch 由 Next 进程发起。这句话在本地成立(后端也在本机),但在生产上有两种翻车:① 后端监听在 127.0.0.1 而 Next 跑在容器/另一台机器,回环地址指向的是 Next 自己;② 就算同机,端口也可能被 Nginx 占着对外,后端在内网另一个端口。

修法:把"服务端用哪个地址"和"浏览器用哪个地址"分开。浏览器走 /api(相对路径,同源),服务端走环境变量里的内网地址(比如 http://127.0.0.1:8000,仅在确认同机时成立)。本书卷 7 的方案是"同机 + 同源反代",所以两条路都通;一旦前后端分机器,这个变量必须单独配,不能指望 NEXT_PUBLIC_ 那一个值同时服务两个世界。

本章验收

  • 首页的列表来自 http://127.0.0.1:8000/api/notes(Network 里能看到)
  • 新增一条后回到首页能看到,按 F5 刷新还在
  • 停掉后端再启动,刷新页面那条仍在(证明落到了文件)
  • 故意提交空标题,页面显示"标题不能为空"这类字段级提示
  • 全仓库搜 127.0.0.1,只命中 .env 文件,不命中 app/ 与 lib/
  • 能背出分诊表里"404 / 422 / 500 / CORS"四行分别先看哪里

自测

Q1:为什么服务端组件取数不需要 CORS,而客户端组件需要?

看答案 CORS 是浏览器执行的安全策略,出发点是"防止 A 网站用用户的身份去读 B 网站的数据"。服务端组件的 fetch 由 Node 进程发出,没有"源"这个概念,也没有用户的浏览器上下文,所以不存在同源限制——它能读任何地址,也不带用户的 Cookie(除非你手动传)。客户端组件的 fetch 由浏览器发出,浏览器必须确认目标服务器"同意被这个源读",才会把响应交给 JS。这也解释了为什么同一份 lib/api.js,在两种组件里表现不同。

Q2:新增成功后你 router.push('/'),列表里却没有新数据。三个可能原因?

看答案 ① 首页是静态渲染的(没有 force-dynamic 或 revalidate 太长),返回的是构建时的 HTML;② 没有调用 router.refresh(),客户端路由复用了缓存中的 RSC 结果;③ 后端确实写成功了,但列表接口读的是另一个数据源(比如进程内缓存没失效,或者两个进程各写各的 JSON 文件)。排查顺序:先看 Network 里首页请求的响应体有没有新数据(有 → 前端缓存问题;没有 → 后端存储问题)。

Q3:分诊表里为什么把 500 的"第一眼看"定成后端日志,而不是 Network 的响应体?

看答案 因为 500 的响应体是给人看的摘要,真正的信息(异常类型、堆栈、出错的代码行)只在日志里,而且响应体里的 request_id 就是用来换日志的钥匙。Network 面板只能告诉你"这个请求 500 了",再往下就没有线索;日志能告诉你"第 47 行,json.load 读到一个坏的 JSON 文件"。注意顺序不能反:先用 request_id 在日志里定位到那一次请求,再看堆栈,最后才回去改代码。

下一步

卷 5 到此收口:前端能读能写,后端能跑能查,错误体统一,跨域可控。但你的数据还躺在一个 JSON 文件里——它能存,不能扛。下一卷换 SQLite,并第一次引入"用户"这个概念:每个人只看自己的摘录。

→ 卷6-01-数据存在哪儿.md