🏠 总目录📚 本教程 03 · 后端骨架 ← →

AI全栈 / 03

后端最小骨架,要先立住哪几条边界?

从输入输出模型和路由出发,逐步接上等待、依赖和错误处理。

能区分请求校验、异步等待与对外错误的职责。

核对异步与阻塞

📑 本页目录(点开跳转)

03 · 后端骨架

⏱ 40 分钟 | ⭐ 这一章的每个零件,都是后面几章往上挂东西的挂载点


🎯 一句话

后端不是「给模型调用套一层 HTTP」,而是立四根柱子:边界在哪、等待怎么处理、每个请求都要做的事挂在哪、出错时对外长什么样。 柱子立歪了,第 8 章的认证、第 12 章的限流、第 15 章的可观测性就没地方生根,只能一路 if 补下去。


🧩 一、为什么中间必须有个后端

「浏览器直接调模型 API」在 Demo 里能跑。上不了线的理由有四条,每条都足够致命:

没有后端 后果
密钥在前端 打开开发者工具就能看见,别人拿去烧你的账单,你连是谁烧的都不知道
没有配额边界 一个用户循环发一万次,你按 token 付钱
没有审计 故障时无法关联请求编号、操作类型和结果。正文是否保留需要单独审查
业务逻辑摊在前端 提示词、检索策略白盒暴露;改一次要等所有客户端更新

⭐ 模型 API 是「谁拿到密钥谁就是老板」的接口,产品需要的是「谁是谁、能做什么、做过什么」。这两者之间的翻译层就是你的后端。


🧱 二、最小骨架:两个模型和一个路由

第 02 章沿一次请求看了浏览器、后端和模型各做什么。现在只打开后端这一格。收到“你好”时,后端要知道从哪个入口读、什么输入可用、最后回哪些字段。这个练习用独立的 POST /chat,一次返回完整 JSON,便于先检查合同。第 01 章的流式页面不需要改动。

请求模型(Request Model)约定可接受的字段、类型和范围。响应模型(Response Model)约定成功时交给调用方的数据。路由(Route)用 HTTP 方法和路径选择处理函数。把三处放在一起,读者看到接口就能预测成功结果。

以下两段示例需要 Python 3.11+、FastAPI、Pydantic 2、Uvicorn 和 HTTPX。可在自己的练习环境安装 python -m pip install fastapi "pydantic>=2,<3" uvicorn httpx。把下面保存成 mini_chat.py,运行 python mini_chat.py 后可在 http://127.0.0.1:8000/docs 试 POST /chat。第五节还会用测试客户端做自动验收。

from fastapi import FastAPI
from pydantic import BaseModel, Field, StringConstraints
from typing import Annotated

app = FastAPI()


class ChatIn(BaseModel):
    message: Annotated[
        str, StringConstraints(strip_whitespace=True, min_length=1, max_length=4000)
    ]
    max_tokens: int = Field(default=512, ge=1, le=4096)
    temperature: float = Field(default=0.0, ge=0.0, le=2.0)


class ChatOut(BaseModel):
    reply: str
    reply_chars: int


@app.post("/chat", response_model=ChatOut)
def chat(body: ChatIn) -> ChatOut:
    reply = "你说的是:" + body.message
    return ChatOut(reply=reply, reply_chars=len(reply))


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app)

请求体用 {"message":"你好"},省略的 max_tokens、temperature 分别取 512、0.0。响应为 200 OK,正文是 {"reply":"你说的是:你好","reply_chars":7}。前缀五个字符、消息两个字符,len 得到七。这里数的是 Python 字符,模型 token 数和费用要由实际调用层统计。

message 去掉首尾空白后要有 1 到 4000 个字符。全空白会变成空字符串,默认得到 422。生成参数也要处于允许范围,但回显模型不会使用它们。输入字符上限能挡住过长文本,生产调用还要按模型的 token 口径核算完整上下文。输出上限、用量和单价见 第 04 章与第 12 章。

成功路由返回模型或普通数据时,FastAPI 按 response_model 验证和筛选输出。手动返回 JSONResponse 会直接交付对应正文,需要单独约定字段。FastAPI 响应模型 · Pydantic 字符串约束。


⚡ 三、async 到底在解什么

假设一次远端模型调用要 3 秒。大部分时间可能在等网络或上游生成。等待期间,这个请求占用的事件循环线程能否处理别的请求,取决于等待方式。

⭐ 大量请求同时等待网络时,可以用异步 I/O 交错推进。 是否能提高吞吐量,还要看本机资源和下游的承载能力。

下面比较的是在一个事件循环线程里同步阻塞等待与可挂起等待:前者占住该线程,后者在真正挂起时允许其他任务推进;并发容量还受连接、内存和下游配额约束。

协程是可挂起、再恢复的执行过程。Python 的 async def 定义协程函数,调用它得到协程对象;仅构造对象不执行其函数体,await 可推进它,Task 则负责调度协程。

极小轨迹固定默认非 eager Task 工厂:设 f(name) 先记“始”,await asyncio.sleep(0) 后记“终”;只造 c=f('A') 时记录为空,不使用就 c.close()。顺序 await f('A')、再 await f('B') 得到 A始→A终→B始→B终;先为 A、B 创建 Task 再等待两者,本例得到 A始→B始→A终→B终。await 已完成对象未必让出控制,eager 工厂可在 Task 构造时运行协程;这里不保证多核并行或固定耗时(协程、Task 与 eager 工厂)。

⚠️ 但 async 函数里一个同步阻塞调用,会阻塞当前事件循环

# 一段能自己跑出结论的对照:async 里写同步阻塞调用,会在调用返回前阻塞当前事件循环。
import asyncio
import time

N, WAIT = 8, 0.5          # 8 个并发请求,每个"等模型"0.5 秒


async def good(i):
    await asyncio.sleep(WAIT)     # ⭐ 等的时候把控制权交回事件循环,别人能跑
    return i


async def bad(i):
    time.sleep(WAIT)              # 💀 同步阻塞:这 0.5 秒里当前事件循环线程无法推进其他任务
    return i


async def main():
    for name, fn in (("await asyncio.sleep", good), ("time.sleep", bad)):
        t0 = time.perf_counter()
        await asyncio.gather(*(fn(i) for i in range(N)))
        print("%-22s %d 个请求耗时 %.2f 秒" % (name, N, time.perf_counter() - t0))


asyncio.run(main())

实跑结果:await asyncio.sleep 版 0.51 秒,time.sleep 版 4.01 秒——8 个请求被排成了一队。⚠️ bad() 长得完全像个正常协程,没有语法错误、没有任何警告,而且本地单人开发时一切正常,上线并发一起来才一起爆炸。

真实代码里的 time.sleep 伪装成:requests.post(...)(换 httpx.AsyncClient)、同步数据库 / Redis 驱动(换 async 驱动或走线程池)、只有同步版的 SDK(当阻塞处理)。另有一类是真 CPU 活——解析 50 MB JSON、本地算 embedding——可考虑线程池、独立进程或任务队列,按计算类型和负载实测。

⭐ FastAPI 的逃生舱:路由写成普通 def(不是 async def)时,它会自动把这个函数扔进线程池。本章示例用的都是 def。🗓️ 线程数有限且随版本变,按官方文档核对。

⭐ 看等待有没有占住事件循环。 异步路由中要避免长时间同步阻塞。普通同步路由可以把阻塞工作交给线程池,线程池用满时请求仍会排队。FastAPI 并发文档。

可跳过:一次读操作,怎样从“等网络”回到事件循环?

阻塞/非阻塞描述调用是否等待,语言的 async 不直接规定内核模型。阻塞读在没有数据时可挂起调用线程;非阻塞读在当前无法完成时返回 EAGAIN/EWOULDBLOCK,应用稍后再试,而不是不断空转重试。就绪通知说“现在可以尝试读”,处理器仍要执行读;完成通知则报告已提交的异步操作结束及结果。同步阻塞、非阻塞轮询、就绪多路复用和异步完成是不同组织方式,不能把非阻塞等同CPU永不等待。在 Linux 已设置 socket 的 O_ASYNC、通知目标及 SIGIO 处理方式时,还可用 SIGIO 接收 I/O 事件通知;收到后仍需实际读写,并处理就绪条件可能已变化的情况,通知本身不是读已完成的结果。

Linux的选择器:select每次给出描述符集合、返回后再检查并准备下一次集合;常见fd_set有FD_SETSIZE限制。poll传入pollfd数组并读revents,不使用同样的位集合上限,但仍需处理所提交的数组。epoll把关注集合持久注册到内核,epoll_wait取就绪事件,避免每轮从用户态重传/检查同样的完整集合。处理返回的k个事件至少仍要做与k相关的工作;注册/移除、复制、回调与真实读写也有成本,所以“epoll是O(1)”不能解释成无限连接或吞吐。

LT/ET只在上述就绪通知层比较。水平触发LT在条件仍成立时可再次通知;边缘触发ET关注状态变化。假设一次来了2KiB,处理器只读1KiB就回去等待,新边缘未出现时,剩下1KiB可能一直等不到下一次通知。ET通常配合非阻塞描述符,把当次可处理数据读到EAGAIN;遇到EOF或错误要结束相应路径。若为公平性设置单轮预算,预算用完但尚未排空的连接要由应用继续调度,不能指望新边缘来叫醒它。

Reactor围绕就绪事件调度处理器,处理器执行非阻塞I/O;Proactor先提交异步操作,再分派完成结果。上层库可以在就绪机制上组合出异步完成接口,不能只看函数名就断言内核实现。比如Python3.13文档中Windows默认ProactorEventLoop,与Unix选择器路径及支持范围不同;具体框架/版本仍要核对。async函数里仍能执行短的同步计算,关键是别让阻塞等待或长CPU工作占住事件循环。本段只补一次读操作的理解,不写服务器或内核源码,也未执行Linux I/O压测。

依据:epoll LT/ET、select / poll、Boost.Asio1.85的Proactor说明、Python3.13平台支持。


🔌 四、依赖注入不是花架子

同一个 POST /chat 在开发时需要回显,测试时还要能稳定制造“模型暂不可用”。如果路由自己创建客户端,每次换实现就得改路由。依赖注入(Dependency Injection)把“提供可用的实现”交给独立的函数。这个函数叫 get_model,路由用 Depends(get_model) 声明需要它。

① 路由与合同接收请求,使用请求模型检查输入,按响应模型交付成功结果。
② 业务服务拿到合规输入后,make_reply 组织一次回复。
③ 模型依赖由 get_model 提供。测试替换实现,路由与业务接口照常运行。

下面的 Model 约定模型实现接收一个 ChatIn,返回一段字符串。回显、暂不可用和意外报错都是本地实现。只替换 get_model,测试仍走同一个路由、模型校验和错误处理。第 08 章和第 12 章会把同一种挂载方式用到 current_user(身份)和 quota(额度)。第 15 章继续讲请求编号怎样关联日志。FastAPI 测试依赖替换。


🚨 五、错误处理:对外一种形状,对内保留细节

相同的路由会遇到三种失败。输入不合规时,应告诉调用方改参数。模型暂不可用时,应说明依赖故障。意外异常则需要兜底并留下排查线索。三个分支共用 error 对象,调用方按稳定的 code 做判断,显示 message,需要排查时带上 trace_id。

沿同一个路由验收四条路径

200 · 处理完成

消息“你好”通过校验。服务调用回显依赖,成功合同只返回 reply 与 reply_chars。

422 · 输入被拒绝

纯空白消息返回 invalid_input。路由的业务处理未执行,模型调用数不增加。

503 · 依赖暂不可用

合法消息通过校验。替换的模型依赖报告暂时故障,应用返回 model_unavailable。

500 · 意外异常

同一合法消息触发本地意外错误。返回 internal_error 与查询编号,固定文案省略内部细节。

把下面保存成 backend_demo.py,与 mini_chat.py 放在同一目录。运行 python backend_demo.py。ASGITransport 把 HTTPX 的请求在进程内交给 FastAPI,无需启动监听端口、访问模型供应商或提供凭证。测试中的 http://testserver 只用于组成请求地址。raise_app_exceptions=False 让测试能检查 500 响应。

import asyncio
import logging
from typing import Annotated, Callable
from unittest import TestCase
from uuid import uuid4

from fastapi import Depends, FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from httpx import ASGITransport, AsyncClient

from mini_chat import ChatIn, ChatOut

app = FastAPI()
log = logging.getLogger("chat_demo")
Model = Callable[[ChatIn], str]


class ModelUnavailable(Exception):
    pass


def echo(body: ChatIn) -> str:
    return "你说的是:" + body.message


def get_model() -> Model:
    return echo


def make_reply(body: ChatIn, model: Model) -> dict:
    reply = model(body)
    return {"reply": reply, "reply_chars": len(reply), "internal_note": "demo-only"}


@app.middleware("http")
async def set_trace_id(request: Request, call_next):
    request.state.trace_id = uuid4().hex
    return await call_next(request)


@app.post("/chat", response_model=ChatOut)
def chat(body: ChatIn, model: Annotated[Model, Depends(get_model)]):
    return make_reply(body, model)


def error_response(request: Request, status: int, code: str, message: str):
    trace_id = request.state.trace_id
    log.warning("request_failed code=%s trace_id=%s", code, trace_id)
    return JSONResponse(
        status_code=status,
        content={"error": {"code": code, "message": message, "trace_id": trace_id}},
    )


@app.exception_handler(RequestValidationError)
async def bad_input(request: Request, exc: RequestValidationError):
    return error_response(request, 422, "invalid_input", "请检查消息和生成参数")


@app.exception_handler(ModelUnavailable)
async def unavailable(request: Request, exc: ModelUnavailable):
    return error_response(request, 503, "model_unavailable", "模型服务暂不可用")


@app.exception_handler(Exception)
async def unknown(request: Request, exc: Exception):
    return error_response(request, 500, "internal_error", "服务暂时出错")


async def verify_contract():
    calls = []

    def counted_echo(body):
        calls.append(body)
        return echo(body)

    def busy_model(body):
        raise ModelUnavailable("demo-private-marker")

    def broken_model(body):
        raise RuntimeError("demo-private-marker")

    with TestCase().assertLogs(log, level="WARNING") as captured:
        transport = ASGITransport(app=app, raise_app_exceptions=False)
        async with AsyncClient(transport=transport, base_url="http://testserver") as client:
            try:
                app.dependency_overrides[get_model] = lambda: counted_echo
                ok = await client.post("/chat", json={"message": "你好"})
                assert ok.status_code == 200
                assert ok.json() == {"reply": "你说的是:你好", "reply_chars": 7}

                invalid = await client.post("/chat", json={"message": "   "})
                assert len(calls) == 1  # 422 时业务没有调用模型

                app.dependency_overrides[get_model] = lambda: busy_model
                busy = await client.post("/chat", json={"message": "你好"})

                app.dependency_overrides[get_model] = lambda: broken_model
                broken = await client.post("/chat", json={"message": "你好"})
            finally:
                app.dependency_overrides.pop(get_model, None)

    trace_ids = set()
    for response, status, code in (
        (invalid, 422, "invalid_input"),
        (busy, 503, "model_unavailable"),
        (broken, 500, "internal_error"),
    ):
        assert response.status_code == status
        error = response.json()["error"]
        assert set(error) == {"code", "message", "trace_id"}
        assert error["code"] == code and error["message"]
        trace_id = error["trace_id"]
        assert trace_id and trace_id not in trace_ids
        trace_ids.add(trace_id)
        assert any(f"code={code} trace_id={trace_id}" in line for line in captured.output)
        assert "demo-private-marker" not in response.text

    assert "demo-private-marker" not in "\n".join(captured.output)
    print("通过:200、422、503、500,响应字段与日志编号一致")


if __name__ == "__main__":
    asyncio.run(verify_contract())

先看 chat 如何把输入和依赖交给 make_reply,再从 verify_contract 读四次请求。internal_note 是合成字段,用来验证成功响应真的按 ChatOut 筛选。空白请求的断言检查模型没有再次调用,依赖解析本身仍可能先发生,因此 get_model 只提供实现,把业务动作留给服务。最后恢复替换,避免影响后续请求。

四个状态通过后会输出 通过:200、422、503、500,响应字段与日志编号一致。入口为每次请求生成 trace_id,错误处理读取同一个编号,并把它和错误类别写进应用日志。这里的编号用来查一次请求。第 15 章会区分它与跨服务追踪的标识。生产环境还应核对服务运行器和日志采集端,确认不会记录原始异常、请求正文或凭证。

这里的统一形状覆盖练习中的三类失败。扩展到整个应用时,还要为框架错误、认证失败等入口定义合同。用户触发本服务限流可用 429,本例的依赖暂不可用用 503。能否重试还取决于操作与故障类型,继续看 03b 状态码、03c 安全重试。FastAPI 异常处理 · HTTPX 进程内测试。


📁 六、什么时候从单文件拆出来

别一上来就建八个目录。 判据只有一条:当你为了改一件事必须在同一个文件里上下反复横跳时就该拆,通常在 300~500 行、第三个路由出现时。按「变化的理由」分,不要按「技术种类」分:

这是文件组织关系,不是一次请求的执行链。目录与职责app/ 项目目录main.py:应用装配api/:HTTP 路由与模型deps.py:依赖services/:业务编排llm/:调用层store/:数据库与向量库settings.py:配置
这是文件组织关系,不是一次请求的执行链。

图下说明

⭐ 唯一强制的一条:api/ 里不许直接出现模型 SDK 的名字。为什么,下一章第一节整节都在讲。


🔄 七、换个栈怎么对应

概念 Python / FastAPI Node(Express / Hono) Go
路由 + 请求校验 装饰器 + Pydantic 模型 app.post + Zod schema http.HandleFunc + struct tag
等待不占线程 async def + 事件循环 天生单线程事件循环,IO 默认异步 goroutine,运行时自动挪走阻塞的
对应的坑 async def 里写同步调用 处理函数里跑 CPU 密集活,同样卡死 忘了把 context 传下去,取消传不到
每请求要做的事 Depends(...) 中间件 + ctx 上挂对象 中间件 + context.Context
统一错误 @app.exception_handler 错误中间件(放最后) 包一层 handler 返回 error

⭐ 这张表真正想说的:三个栈里只有「依赖注入」是 FastAPI 的叫法,另两个栈用中间件做同一件事。 「每请求要做的事得有统一的地方挂」这个概念不会过期,Depends 这个名字会。


🔗 这一章连到哪里

去哪 为什么
04 · 调用层 本章 chat() 里那行假回复,下一章换成真客户端——以及为什么不能直接写 SDK
05 · 流式输出 本章返回一整个 JSON;用户要边看边等时,返回方式整个变了
⭐ 03b · 接口的形状 本章给了错误响应的形状(code / message / trace_id),并跑通了四条接口路径。那一章继续讲资源怎么划、方法怎么选、状态码怎样帮助判断下一步。第 11 章会再处理队列里的退避与死信。
⭐ 03c · 幂等与条件请求 本章的错误形状告诉客户端失败类别。那一章讲重试怎么才是安全的:Idempotency-Key 的服务端协议、ETag 省流量、If-Match 防丢更新
模型上线之后 05 · 该监控什么 本章埋 trace_id 就是为了它。⚠️ 分界:本板块管「服务健不健康」,那边管「模型准不准」
AI基础设施 20 · 推理服务化 你调的那个模型服务自己也是个后端。那边讲推理引擎怎么选,这里讲应用怎么调它

✅ 检查点

  1. 前端直接调模型 API 会踩到哪四类问题?
  2. 单独定义请求/响应模型带来的三个好处是什么?
  3. 请求同时在等上游时,异步等待可以改善什么?
  4. async def 里调一个同步阻塞的库会怎样?对照代码跑出了什么结果?这个 bug 为什么本地开发时发现不了?
  5. FastAPI 的「逃生舱」是什么?什么时候不该靠它?
  6. 怎样在不改路由的情况下复现模型暂不可用?
  7. 把“你好”换成三个空格,再把模型替换成暂不可用实现,两次分别返回什么?怎么知道失败发生在哪一层?
  8. 什么时候该拆文件?api/ 层唯一强制的规矩是什么?
👀 答案
  1. 密钥在前端可见(被烧账单且查不到是谁)、没有配额边界、没有审计记录、业务逻辑白盒暴露且改一次要等客户端更新。
  2. ① 把输入规则集中在请求模型,便于复用和检查。② 不合规输入在业务处理前得到 422。③ 普通成功返回按响应模型筛选,演示中的 internal_note 不会进入成功正文。
  3. 等待网络或模型响应时,可以让出事件循环继续服务其他请求。连接、线程、内存和上游配额仍会限制并发。
  4. 阻塞当前事件循环线程,该循环上的其他任务也会等待。8 个各等 0.5 秒的任务:await asyncio.sleep 版 0.51 秒,time.sleep 版 4.01 秒。本地发现不了是因为只有你一个人用,没有并发就看不出排队;语法也完全正确、不报警。
  5. 路由写成普通 def,FastAPI 自动扔进线程池。适合「偶尔有个同步库」,不适合「所有请求都走同步」——线程数有限,量一大照样排队。
  6. 用 app.dependency_overrides[get_model] 临时提供一个会报告暂不可用的实现,核对 503 后恢复。current_user 留给第 08 章,quota 留给第 12 章。
  7. 空白请求得到 422 / invalid_input,模型调用数不增加。换回合法消息再测试暂不可用实现,得到 503 / model_unavailable。用 trace_id 可把错误响应和应用日志对上。
  8. 当改一件事需要在同一文件里反复横跳时(约 300~500 行、第三个路由);api/ 里不许出现模型 SDK 的名字。

本节回顾

⚡ 走神救援

⭐ 后端不是给模型调用套层 HTTP,是立四根柱子。 为什么要有它:密钥在前端等于公开、没有配额边界、没有审计——模型 API 是「谁拿到密钥谁是老板」,而产品需要「谁是谁、能做什么、做过什么」。

边界。请求模型校验输入,响应模型定义成功正文,路由把合规输入交给业务服务。字符长度与生成上限都应检查,实际用量在调用层核算。

⭐ async 在解什么。当请求在等网络时,异步等待让事件循环可以推进其他任务。

⚠️ 最贵的坑:async def 里一个同步阻塞调用会阻塞当前事件循环。本章那组对照差了将近八倍,而错误写法语法完全正确、不报警、本地单人开发一切正常,上线并发一起来才一起爆炸。伪装形态是同步 HTTP 库、同步数据库驱动、只有同步版的 SDK。⭐ 逃生舱是把路由写成普通函数,框架会自动扔线程池——但线程数有限。

⭐ 依赖可以被替换。路由调用业务服务,模型实现由独立入口提供。替换模型后,仍可通过同一路由验证输入、成功与失败响应。

错误处理:对外一种形状(错误码 + 消息 + 追踪 id),⚠️ 未知异常绝不原样透出。

下一节 👉 03b-接口的形状.md

打卡记录保存在你的浏览器里,首页能看到总进度