联调收口
本合集目录
本章目录
单册说明:本文件是卷 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,并第一次引入"用户"这个概念:每个人只看自己的摘录。