稍候片刻,月出文自明。
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{"detail": [{"type": "int_parsing", "loc": ["path", "user_id"], "msg": "Input should be a valid integer, unable to parse string as an integer"}]}HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 56
{"id": 1, "name": "小明", "email": "ming@example.com"}{
"id": 1,
"name": "小明",
"tags": ["前端", "后端"]
}import psycopg
# 建立连接:这里就是在做协议握手和认证
with psycopg.connect("host=localhost dbname=app user=postgres password=secret") as conn:
with conn.cursor() as cur:
# 执行 SQL(用参数占位符,避免 SQL 注入)
cur.execute("SELECT id, name, email FROM users WHERE id = %s;", (1,))
row = cur.fetchone()
print(row) # (1, '小明', 'ming@example.com')import psycopg
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
# 开发阶段允许前端跨域访问
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:5173"],
allow_methods=["*"],
allow_headers=["*"],
)
DSN = "host=localhost dbname=app user=postgres password=secret"
@app.get("/users/{user_id}")
def get_user(user_id: int):
with psycopg.connect(DSN) as conn:
with conn.cursor() as cur:
cur.execute(
"SELECT id, name, email FROM users WHERE id = %s;",
(user_id,),
)
row = cur.fetchone()
if row is None:
# 数据库没查到,这里主动翻译成 HTTP 层的 404
raise HTTPException(status_code=404, detail="用户不存在")
return {"id": row[0], "name": row[1], "email": row[2]}import { useState } from "react";
function UserCard() {
const [user, setUser] = useState(null);
const [error, setError] = useState("");
const [loading, setLoading] = useState(false);
async function loadUser() {
setLoading(true);
setError("");
try {
const res = await fetch("http://localhost:8000/users/1");
if (!res.ok) {
// 非 2xx 时 fetch 不会抛错,需要自己判断
throw new Error(`请求失败:${res.status}`);
}
const data = await res.json(); // 把响应的 JSON 文本解析成对象
setUser(data);
} catch (e) {
setUser(null); // 失败时清空旧数据,避免页面残留上一次查到的用户
setError(e.message);
} finally {
setLoading(false);
}
}
return (
<div>
<button onClick={loadUser}>查看个人信息</button>
{loading && <p>加载中…</p>}
{error && <p>{error}</p>}
{user && (
<ul>
<li>姓名:{user.name}</li>
<li>邮箱:{user.email}</li>
</ul>
)}
</div>
);
}
export default UserCard;
前后端基础入门:从 HTTP 请求到数据库交互
1. 前言:从一次网页操作说起
假设我们做了一个个人主页,页面上有个“查看个人信息”按钮。用户点下去之后,页面上出现了名字和邮箱。
作为使用者,这很理所当然。但作为开发者,我一开始脑子里冒出了一串问题:
这六个问题连起来,其实就是 Web 开发最基础的一条链路。本文用的技术栈是这样的:
位置
技术
职责
前端
React + JavaScript
渲染页面、处理用户交互、向后端发请求
后端
Python + FastAPI + Uvicorn
接收请求、跑业务逻辑、访问数据库、返回响应
数据库
PostgreSQL
持久化存储数据,执行 SQL 查询
数据库驱动
psycopg
让 Python 后端能和 PostgreSQL 通信
整体结构可以画成这样:
接下来就顺着这条线,一段一段看下去。
2. 前端、后端与数据库的基本概念
2.1 三者各管什么
Frontend(前端)是用户能看到、能点的部分。它负责页面展示和交互:按钮长什么样、点了之后有没有加载动画、数据来了怎么填到页面上。前端代码最终是在用户的浏览器里运行的。
Backend(后端)运行在服务器上,用户看不见。它对外开放一组 API 接口,负责业务逻辑(比如“只能查看自己的信息”)、数据处理,以及访问数据库。
Database(数据库)负责数据的持久化存储与管理。页面关掉、服务器重启,数据还在里面。它还负责按条件查找、排序、去重这些事,而不是把所有数据一股脑丢给后端自己筛。
三者的关系可以理解成:前端负责“说人话”,数据库负责“记事本”,后端是中间那个翻译兼跑腿的。
2.2 本文涉及的技术名词
初学者容易有一个误解,以为这三个东西一定跑在三台机器上。其实不是。浏览器是运行在用户设备上的客户端程序,而前端、后端、数据库完全可以部署在同一台电脑上——你本地开发时通常就是这样。它们之所以在概念上被区分开,是因为职责不同,而不是因为物理位置不同。
3. 前端与后端如何通信?
3.1 HTTP 基本概念
前端和后端需要一套共同语言才能对话,这套语言最常见的就是 HTTP(HyperText Transfer Protocol,超文本传输协议)。它规定了消息长什么样、怎么发、对方怎么回。
HTTP 采用的是请求—响应模型:客户端主动发一个 Request,服务端回一个 Response。服务端不会无缘无故主动给浏览器推消息,一定是有请求才有响应。一次请求对应一次响应,然后这次对话就结束了(HTTP/1.1 的长连接只是复用了 TCP 连接,模型上仍然是请求—响应)。
3.2 HTTP Request
一个 HTTP 请求主要由四部分组成:
部分
作用
例子
Method
说明想做什么操作
GET
URL
说明操作哪个资源
/users/1
Headers
附加元信息
Content-Type: application/json
Body
携带数据(GET 通常没有)
{"name": "小明"}
常见的 Method 有以下几种:
Method
典型用途
常对应的数据库操作
GET
获取资源
SELECT
POST
创建资源
INSERT
PUT
整体替换资源
UPDATE(覆盖式)
PATCH
局部更新资源
UPDATE(增量式)
DELETE
删除资源
DELETE
这张表很容易让人得出“HTTP Method 就是数据库 CRUD”的结论,但这是个需要小心的说法。Method 描述的是对资源的操作语义,至于后端内部到底执行什么 SQL、甚至根本不用 SQL(比如读缓存),是后端自己的事。一个 GET 请求背后可能查三张表再拼装,一个 PATCH 请求也可能只是往日志表里写一条记录。两者语义上常常对应,但不存在强制的一一映射。
再看两个具体例子:
这句话的意思是:请把 ID 为 1 的用户信息给我。
这句话的意思是:请用 Body 里的数据创建一个新用户。
3.3 HTTP Response
服务端处理的答案同样由三部分组成:
部分
作用
Status Code
用一个数字概括结果
Headers
响应的元信息,如内容类型、长度、缓存策略
Body
真正的数据,比如一段 JSON
状态码按百位分段:2xx 表示成功,4xx 表示请求方有问题,5xx 表示服务端出问题。常见的有:
状态码
含义
典型场景
200 OK
成功
查询成功
201 Created
创建成功
POST 新建用户成功
400 Bad Request
服务器认为客户端请求存在问题
由后端逻辑主动判定请求不合理,比如参数值超出允许范围
401 Unauthorized
未认证
没有登录或令牌失效
422 Unprocessable Entity
格式没问题,但字段无法通过校验(FastAPI 文档里也写作 Unprocessable Content)
FastAPI 用 Pydantic 校验参数或请求体失败,比如路径里的 ID 不是整数(/users/abc),由框架自动返回
403 Forbidden
已认证但无权限
登录了,但访问别人的资料
404 Not Found
资源不存在
查的用户 ID 不存在
500 Internal Server Error
服务端内部错误
代码异常或数据库连不上
表格里有几个点容易被混在一起,这里按“谁来判定”把它们分开:
一个 422 响应大概是这样。注意 /users/abc 只用来演示类型转换失败;本文第 5 节实际请求的是 GET /users/1,那个请求拿到的是 200 OK:
一个成功的响应大概长这样:
3.4 API 与 JSON
API(Application Programming Interface,应用程序编程接口)是“程序之间约定好的调用方式”。它本身是个很宽泛的概念:Python 里一个函数可以算 API,操作系统提供的系统调用也算 API。
在 Web 开发语境里,我们说的通常是 HTTP API:后端把一组 URL 和 HTTP Method 暴露出来,前端按照约定去调用。比如约定 GET /users/1 返回用户 1 的信息,这个约定本身就是 API。
JSON(JavaScript Object Notation)是一种文本格式,用来表示结构化的数据,长得像 JavaScript 的对象字面量:
前后端喜欢用 JSON,主要是因为它易读、结构灵活、几乎所有语言都有成熟的解析库,而且浏览器原生支持。
这里要特别区分三个容易混为一谈的东西:
名词
是什么
解决什么问题
HTTP
通信协议
消息怎么从一端送到另一端
API
接口约定
有哪些操作可以调用、参数和返回是什么
JSON
数据格式
数据写成什么样
它们不是同一层的东西:HTTP 可以传 JSON,也可以传 HTML、图片、纯文本;API 可以基于 HTTP,也可以用 gRPC;JSON 也可以用在 HTTP 之外的地方,比如写配置文件。API 不等于 HTTP,JSON 也不等于 HTTP。
4. 后端与数据库如何交互?
前端和后端用 HTTP 对话。那后端和数据库之间用什么?这里的答案不太一样:后端发的是 SQL,但它不是通过 HTTP 送过去的。
4.1 SQL 基础
SQL(Structured Query Language,结构化查询语言)是用来描述“我想对数据做什么”的语言。它不负责把语句送到数据库,只负责表达意图。四种最基本的操作:
语句
作用
例子
SELECT
查询
SELECT name FROM users WHERE id = 1;
INSERT
插入
INSERT INTO users (name, email) VALUES ('小明', 'ming@example.com');
UPDATE
修改
UPDATE users SET email = 'new@example.com' WHERE id = 1;
DELETE
删除
DELETE FROM users WHERE id = 1;
回到开头的问题“后端如何查询数据”,答案就是后端的程序构造 SQL 查询,并通过参数化方式把参数传给驱动执行:
数据库收到后,自己决定怎么找到这一行(走索引还是全表扫描),然后把结果给你。注意:SQL 是数据库操作语言,不是通信协议。它只是“要说的话”,至于“怎么送过去”,是下一节的事。
4.2 数据库协议
数据库协议(Database Protocol)是数据库客户端和数据库服务器之间交换消息的规则:握手时怎么认证,请求怎么编码,结果集怎么按行、按列传回来,出错时错误信息放在哪里。
为什么需要协议?因为一条 SQL 只是一段字符串,数据库没法靠它确认“你是谁、有没有权限、结果要怎么分批发给我”。这些都需要一套结构化的消息格式来约定。而且传输格式要足够高效——结果集可能有几十万行,用 JSON 逐行包裹会很浪费。
PostgreSQL 使用的是自己的 PostgreSQL 前端/后端协议(Frontend/Backend Protocol),默认跑在 5432 端口上。它的报文是二进制格式的,内容包括启动消息、口令认证、简单查询(Simple Query)、扩展查询(Extended Query)、RowDescription、DataRow、CommandComplete 等等。
所以 SQL 和数据库协议的关系是:SQL 是内容,协议是信封和邮递规则。你写 SQL,驱动把它按协议打包发出去,数据库按协议解包、执行,再按协议把结果打包回来。
4.3 数据库驱动
既然协议是二进制报文,总不能自己手动拼字节吧。数据库驱动(Database Driver)就是实现了这套协议的软件库,它把“拼包、发网络请求、解析返回”全部封装成普通的函数调用。
打个比方:SQL 是你要说的话,协议是打电话时的线路规则,驱动就是那部电话机。你不用懂信号怎么调制,拿起话筒说话就行。
驱动和协议的区别在于层级:协议是规范,驱动是规范的具体实现。同一个协议可以有多个驱动(Python 里就有 psycopg、asyncpg 等),它们对外的 API 不同,但底层都遵循相同的数据库协议;具体用哪些消息类型、先发什么后发什么,不一定完全相同。
在本文的技术栈里,psycopg 就是 Python 访问 PostgreSQL 的驱动。它负责建立连接、按协议发送 SQL、接收结果,并把结果转成 Python 的元组、字典等数据结构。
为什么开发者通常不需要自己实现数据库协议?一是没必要——标准已经很成熟,社区实现经过大量生产验证;二是风险高——认证、加密、编码、边界情况都很容易出错;三是这些细节和业务无关,自己写纯属浪费时间。
一个最简单的使用示例:
4.4 数据库如何返回结果
把上面的过程拆开看,一次查询大致是这样走的:
这里有个初学者常有的误解:数据库返回的不是 HTTP Response。数据库根本不理解 HTTP,它只按自己的协议返回结果数据。HTTP 是后端面对前端时才用的语言,数据库那条链路上完全没有 HTTP 参与。这也是为什么整篇文章要分开讲两段通信——它们是两套完全不同的规则。
5. 一次完整的前后端交互案例
现在把前面的零件拼起来,以“查询用户信息”为例走一遍完整流程。
5.1 整体流程
先准备好数据库表:
表建好之后,先插入一条示例数据,否则后端和前端查 ID 为 1 的用户时什么都查不到:
RETURNING id 会让这条 INSERT 顺便把新行的主键返回出来,结果是:
这条语句里的姓名和邮箱,正好对应后文 FastAPI 返回的 JSON、HTTP Response 里的 Body,以及前端页面上显示的姓名和邮箱。
这里要特别注意返回的 ID。id 是 SERIAL 类型,由数据库的序列自动生成,从 1 开始递增。在一个全新的、刚建好的表上,第一条插入的记录拿到的通常是 1;但如果这个表之前插入过数据又删掉了,或者表是用别的初始值建的,序列不会回退,返回的 ID 就可能不是 1。
所以不要假定“第一条数据一定是 1”。先看 INSERT 实际返回的 ID,如果它不等于 1,后面所有查询都改成使用这个真实 ID。具体来说需要跟着调整三处:
所以只要把这三处换成实际返回的 ID,响应体和页面上显示的字段值就仍然和本节插入的数据一致:name 是“小明”,email 是 ming@example.com,变的只有 id 这一个数字。如果请求了一个不存在的 ID,后端就会返回 404,前端进入 error 分支。
5.2 后端:FastAPI + psycopg
然后写一个最小可用的 FastAPI 应用:
这里的 user_id: int 是 FastAPI 的类型提示,它会自动把路径里的字符串转成整数。这个“转换 + 校验”发生在进入函数体之前:如果转不了,比如请求 GET /users/abc,FastAPI 会直接返回 422(文档里也写作 422 Unprocessable Content),响应体里写明是哪个参数、为什么不合格,函数根本不会被执行。最后 return 一个字典,FastAPI 会把它序列化成 JSON 作为响应体。
注意代码里 HTTPException 那一行:数据库只是告诉你“没查到”,把“没查到”变成 HTTP 的 404,是后端的工作。上面三种结果的分工可以对照第 3.3 节的状态码表:GET /users/abc 是参数不合格、由框架自动拦下,返回 422;GET /users/1 但库里没有这条记录,由这里主动抛出 404;而 400 在这段代码里不会出现——它留给“参数能解析、但业务上不允许”的情况,比如将来加一个创建用户的接口,参数合法但业务规则不通过时,由业务代码主动返回(而缺字段、类型不对这类请求体校验失败,FastAPI 会自动返回 422);如果是邮箱已经被占用这种和已有数据冲突的情况,用 409 Conflict 会比 400 更贴切。
需要说明的是,这个示例为了聚焦交互流程,没有做身份认证和权限校验:任何人只要改一下 URL 里的 user_id,就能读到其他用户的数据,也就是常说的越权访问。真实的生产环境必须加上身份认证,并在查到数据后做资源级权限校验,确认当前登录用户有权访问这条记录。另外,示例里的数据库密码是硬编码在代码中的,生产环境应改用环境变量或密钥管理服务来注入,并遵循最小权限原则,给这个账号只授予必要的权限。
代码写好之后,把三段东西按顺序跑起来。先是 PostgreSQL:本机装好并启动服务,建一个数据库(比如 app),然后用 psql -U postgres -d app 连进去,依次执行 5.1 节中的建表和插入语句。连接串里的 dbname、user、password 要和实际环境一致。
接着准备后端。把上面的 FastAPI 代码存成 main.py,在同一个目录下装依赖并启动服务,默认监听 http://localhost:8000:
最后是前端。需要 Node.js 和 npm,用 Vite 建一个 React 项目,装上依赖,把 5.3 的组件放进 src 并使用它,然后启动开发服务器:
Vite 的开发服务器默认跑在 http://localhost:5173,正好和上面 allow_origins 里写的地址对上——端口不同时前后端属于不同源:请求本身照样发得出去,是浏览器在读取响应时按 CORS 规则拦截,把结果藏起来不给页面用,这时要么改 allow_origins,要么改前端端口,两边保持一致。
5.3 前端:React + fetch
5.4 逐步对照
如果数据库里没有 ID 为 1 的用户,第 8 步就会变成 404,前端进入 error 分支,显示“请求失败:404”。因为 catch 里顺手调用了 setUser(null),即使之前成功查到过用户,失败后页面上也不会残留旧的信息。整条链路里,错误也是逐层翻译传递的。
6. 常见相关技术概念
下面这些名词时常和上面的内容一起出现,这里只做简单定位,不展开。
HTTP 的语义(方法、状态码、头字段)在 HTTPS 下保持不变,区别在于通信内容被放进 TLS 加密的通道里传输,防止被窃听和篡改。这里一致的是语义,不是报文格式:不同 HTTP 版本(如 HTTP/1.1 与 HTTP/2)的报文格式本来就不一样,HTTPS 也不是把某个版本的报文原样加密,而是在传输层给上层数据加上加密保护。
概念
作用
与本文的关系
JavaScript 与 React
JS 是语言,React 是构建界面的库
前端用 JS 写逻辑,用 React 组织页面和状态
FastAPI 与 Uvicorn
FastAPI 是 Web 框架,Uvicorn 是 ASGI 服务器
前者定义接口和处理逻辑,后者负责监听端口、收发 HTTP
HTTP 与 HTTPS
HTTPS 是 HTTP 加上 TLS 加密
ORM 与 SQLAlchemy
用 Python 对象操作表,代替手写 SQL
底层仍然生成 SQL、通过驱动访问数据库,只是多了一层抽象
Cookie / Session / Token
解决“如何识别是哪个用户”
认证信息通常放在 HTTP 请求头里随请求一起发送
浏览器刷新与普通 API 请求
刷新是导航请求,期待返回完整页面
fetch 是接口请求,期待返回 JSON,页面不跳转
其中 FastAPI 和 Uvicorn 的关系最容易被混淆。简单说:框架负责“你要做什么”,服务器负责“怎么把外面的请求送进来、把结果送出去”。所以你会写 uvicorn main:app——app 是 FastAPI 实例,uvicorn 是运行它的服务器。
7. 总结
把整条链路拉直来看,就是:
再完整一点:
回头看我开头那六个问题,现在都能用一句话回答了:前端用 HTTP 把请求发给后端;Request 和 Response 是这次对话的“问”和“答”;后端靠 Method 加 URL 决定执行哪个接口;后端通过驱动访问数据库;数据库按自己的协议返回结果;前端拿到 JSON 后更新组件状态,页面就变了。
最后再把一些核心的专业名词梳理一下: