API on Snow

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

Tue, 15 Sep 2026 22:10:00 +0800

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

如果你已经会 Python 函数、类型提示、虚拟环境和一点 HTTP 基础，FastAPI 会给你一种很顺手的体验：你写普通函数和 Pydantic 模型，它负责把请求解析、参数校验、JSON 序列化和 OpenAPI 文档串起来。

这篇文章不从“什么是 Web 框架”讲起，而是面向已经有 Python 基础的开发者，直接搭一个可运行的小 API，再逐步补上工程里绕不开的几件事：数据校验、错误处理、依赖注入、异步选择、项目拆分、测试和部署。

你已有的 Python 能力	在 FastAPI 中会怎样复用
函数与装饰器	一个路径函数就是一个接口处理函数
类型提示	自动解析路径参数、查询参数和请求体
类与数据模型	用 Pydantic 定义请求和响应契约
异常处理	用 `HTTPException` 表达 HTTP 错误
模块拆分	用 `APIRouter` 管理多组接口
测试习惯	用 `TestClient` 写接口级单元测试

一、FastAPI 解决的核心问题

FastAPI 的价值不是“少写几行 Flask 代码”，而是把现代 API 后端中高频出现的一组能力整合在一起：

基于类型提示的参数解析；
基于 Pydantic 的请求体和响应体校验；
自动生成 OpenAPI、Swagger UI 和 ReDoc；
支持同步函数和异步函数；
通过依赖注入组织鉴权、数据库会话、配置读取等横切逻辑；
基于 ASGI，天然适合高并发 I/O 场景。

一次请求进入 FastAPI 后，通常会经过这样的链路：

Uvicorn 这类 ASGI Server 接收 HTTP 请求；
FastAPI 根据 method 和 path 找到路径函数；
解析 path、query、header、cookie、body 等输入；
用 Pydantic 做类型转换和约束校验；
执行业务函数；
根据 response_model 输出稳定 JSON 结构；
同步更新 OpenAPI 文档。

也就是说，FastAPI 希望你把“接口契约”尽量写进 Python 类型和模型里，而不是散落在注释、Wiki 和前端口头约定中。

二、环境准备

截至本文写作时，FastAPI 官方文档推荐安装标准依赖包：

`1`	`pip install "fastapi[standard]"`

建议从一个干净虚拟环境开始：

mkdir fastapi-shop
cd fastapi-shop

python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

pip install "fastapi[standard]"

其中 fastapi[standard] 会带上常用运行和开发能力，比如 ASGI Server、交互式文档相关依赖等。如果你在生产项目中追求更小依赖面，也可以研究 fastapi-slim，但入门和多数业务项目建议先用标准安装。

三、第一个可运行 API

先写一个单文件版本，文件名为 main.py：

from typing import Annotated
from uuid import UUID, uuid4

from fastapi import Depends, FastAPI, Header, HTTPException, Query, status
from pydantic import BaseModel, Field


app = FastAPI(
    title="FastAPI Shop",
    version="0.1.0",
    description="A tiny shop API built with FastAPI.",
)


class ItemCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=80, examples=["Keyboard"])
    price: float = Field(..., gt=0, examples=[299.0])
    tags: list[str] = Field(default_factory=list, max_length=10)


class ItemUpdate(BaseModel):
    name: str | None = Field(default=None, min_length=1, max_length=80)
    price: float | None = Field(default=None, gt=0)
    tags: list[str] | None = Field(default=None, max_length=10)


class ItemRead(BaseModel):
    id: UUID
    name: str
    price: float
    tags: list[str]


items: dict[UUID, ItemRead] = {}


def require_token(
    x_token: Annotated[str | None, Header(alias="X-Token")] = None,
) -> str:
    if x_token != "dev-token":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token",
        )
    return x_token


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/items", response_model=list[ItemRead])
def list_items(
    token: Annotated[str, Depends(require_token)],
    q: Annotated[str | None, Query(min_length=1, max_length=30)] = None,
) -> list[ItemRead]:
    result = list(items.values())

    if q is None:
        return result

    keyword = q.lower()
    return [item for item in result if keyword in item.name.lower()]


@app.post("/items", response_model=ItemRead, status_code=status.HTTP_201_CREATED)
def create_item(
    data: ItemCreate,
    token: Annotated[str, Depends(require_token)],
) -> ItemRead:
    item = ItemRead(id=uuid4(), **data.model_dump())
    items[item.id] = item
    return item


@app.get("/items/{item_id}", response_model=ItemRead)
def read_item(
    item_id: UUID,
    token: Annotated[str, Depends(require_token)],
) -> ItemRead:
    try:
        return items[item_id]
    except KeyError:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )


@app.patch("/items/{item_id}", response_model=ItemRead)
def update_item(
    item_id: UUID,
    data: ItemUpdate,
    token: Annotated[str, Depends(require_token)],
) -> ItemRead:
    item = read_item(item_id, token)
    updates = data.model_dump(exclude_unset=True)
    updates = {key: value for key, value in updates.items() if value is not None}
    updated = item.model_copy(update=updates)
    items[item_id] = updated
    return updated


@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_item(
    item_id: UUID,
    token: Annotated[str, Depends(require_token)],
) -> None:
    if item_id not in items:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )
    del items[item_id]

启动开发服务器：

`1`	`fastapi dev main.py`

如果你的环境没有 FastAPI CLI，也可以用 Uvicorn：

`1`	`uvicorn main:app --reload`

打开：

http://127.0.0.1:8000/health
http://127.0.0.1:8000/docs
http://127.0.0.1:8000/redoc
http://127.0.0.1:8000/openapi.json

试着创建一个商品：

curl -X POST "http://127.0.0.1:8000/items" \
  -H "Content-Type: application/json" \
  -H "X-Token: dev-token" \
  -d '{"name":"Keyboard","price":299,"tags":["peripheral"]}'

如果你把 price 改成负数，FastAPI 会直接返回 422 Unprocessable Entity，并告诉你哪个字段不符合约束。你不需要在业务函数里手写一堆 if price <= 0。

四、类型提示如何变成接口契约

FastAPI 里有三类输入最常见：

输入位置	示例	FastAPI 如何识别
路径参数	`/items/{item_id}`	函数参数名与路径模板一致
查询参数	`/items?q=key`	函数参数不在路径里，且不是 Pydantic body
请求体	JSON body	参数类型继承自 `BaseModel`

例如：

@app.get("/items/{item_id}")
def read_item(
    item_id: UUID,
    q: Annotated[str | None, Query(min_length=1)] = None,
) -> dict[str, str]:
    return {"item_id": str(item_id), "q": q or ""}

这里 item_id: UUID 会让 FastAPI 自动把字符串转换为 UUID 对象；如果传入的路径不是合法 UUID，请求会在进入函数前失败。

Annotated 的好处是把“类型”和“接口约束”分开：

`1`	`q: Annotated[str \| None, Query(min_length=1, max_length=30)] = None`

读作：q 的业务类型是 str | None，同时它作为查询参数时必须满足长度约束。这样写比把校验逻辑塞进函数体更清晰，也能同步生成文档。

五、Pydantic：把边界数据变可信

Pydantic 是 FastAPI 的数据契约核心。请求进入系统时，外部世界给你的都是“不可信字符串或 JSON”；经过 Pydantic 模型之后，业务函数拿到的是已经转换和校验过的 Python 对象。

请求模型和响应模型建议分开写：

class UserCreate(BaseModel):
    email: str
    password: str


class UserRead(BaseModel):
    id: UUID
    email: str

这样做有两个直接收益：

password 可以出现在创建请求里，但不会从响应里泄漏出去；
数据库模型、请求模型、响应模型不再互相污染。

response_model 还有一个经常被低估的价值：它能过滤掉你不想暴露的字段。

@app.post("/users", response_model=UserRead)
def create_user(data: UserCreate) -> dict[str, object]:
    return {
        "id": uuid4(),
        "email": data.email,
        "password_hash": "internal-only",
    }

即使函数返回值里有 password_hash，最终响应也只会保留 UserRead 声明的字段。对于 API 稳定性和安全边界，这一点很重要。

六、依赖注入：把横切逻辑拿出接口函数

开发业务 API 时，很多逻辑并不属于某一个接口：

读取当前登录用户；
校验 Token；
创建数据库 Session；
读取配置；
记录审计日志；
检查权限。

FastAPI 用 Depends 处理这类逻辑。前面的 require_token 就是一个最小例子：

def require_token(
    x_token: Annotated[str | None, Header(alias="X-Token")] = None,
) -> str:
    if x_token != "dev-token":
        raise HTTPException(status_code=401, detail="Invalid token")
    return x_token

在接口中声明依赖：

1
2
3

@app.get("/items")
def list_items(token: Annotated[str, Depends(require_token)]) -> list[ItemRead]:
    return list(items.values())

这样接口函数会在执行前先运行 require_token。如果依赖抛出异常，业务函数不会继续执行。

依赖也可以继续依赖其他依赖：

def get_settings() -> Settings:
    return Settings()


def get_repository(
    settings: Annotated[Settings, Depends(get_settings)],
) -> ItemRepository:
    return ItemRepository(settings.database_url)

这种组合方式让 FastAPI 项目很适合做“薄接口层 + 明确业务层”的结构。

七、项目变大后怎么拆

单文件很适合入门，但真实项目通常会快速长出用户、订单、支付、后台管理、文件上传等资源。推荐按职责拆分，而不是按“今天写了哪个接口”随手堆文件。

一个常见结构是：

fastapi-shop/
├── app/
│   ├── main.py
│   ├── api/
│   │   └── routers/
│   │       ├── items.py
│   │       └── users.py
│   ├── core/
│   │   └── config.py
│   ├── schemas.py
│   ├── models.py
│   ├── services.py
│   └── db.py
├── tests/
│   └── test_items.py
└── requirements.txt

app/api/routers/items.py 可以这样写：

from typing import Annotated
from uuid import UUID

from fastapi import APIRouter, Depends

from app.schemas import ItemCreate, ItemRead
from app.services import ItemService, get_item_service


router = APIRouter(prefix="/items", tags=["items"])


@router.post("", response_model=ItemRead, status_code=201)
def create_item(
    data: ItemCreate,
    service: Annotated[ItemService, Depends(get_item_service)],
) -> ItemRead:
    return service.create(data)


@router.get("/{item_id}", response_model=ItemRead)
def read_item(
    item_id: UUID,
    service: Annotated[ItemService, Depends(get_item_service)],
) -> ItemRead:
    return service.get(item_id)

app/main.py 只负责组装：

from fastapi import FastAPI

from app.api.routers import items


app = FastAPI(title="FastAPI Shop")
app.include_router(items.router)

这里有一个判断标准：如果路由函数开始出现复杂分支、数据库查询细节、外部 API 调用和权限规则，说明它已经不只是“HTTP 编排”了，应该把逻辑移到 service 或 repository 层。

八、`async def` 不等于自动更快

FastAPI 支持两种路径函数：

@app.get("/sync")
def sync_handler() -> dict[str, str]:
    return {"mode": "sync"}


@app.get("/async")
async def async_handler() -> dict[str, str]:
    return {"mode": "async"}

什么时候用 async def？先看函数内部在做什么。

可以用这张表快速判断：

场景	建议
调用 async 数据库驱动，如 async SQLAlchemy、asyncpg	用 `async def`
调用 async HTTP 客户端，如 httpx.AsyncClient	用 `async def`
调用普通同步库，如 requests、同步数据库驱动	用 `def`，或放到线程池/任务队列
做大量 CPU 计算，如图像处理、模型推理	不要指望 `async` 提速，考虑进程池或后台任务
不确定库是否异步	先按同步写，确认后再改

最常见的坑是：写了 async def，但函数内部直接调用 requests.get() 或同步数据库驱动。这会阻塞事件循环，让其他请求也跟着等待。

如果需要在接口中调用外部 HTTP 服务，可以这样：

import httpx


@app.get("/exchange-rate")
async def get_exchange_rate() -> dict[str, float]:
    async with httpx.AsyncClient(timeout=5) as client:
        response = await client.get("https://api.example.com/rate")
        response.raise_for_status()
    return response.json()

注意：异步不是语法装饰，它是一种 I/O 调度模型。只有你的数据库、HTTP 客户端、缓存客户端等调用链也支持 async，收益才会明显。

九、错误处理与状态码

HTTP API 不应该只返回 200，然后把错误塞进 JSON 里的 code 字段。状态码本身就是协议的一部分。

常用状态码可以这样理解：

状态码	适用场景
`200 OK`	查询、更新成功并返回内容
`201 Created`	创建资源成功
`204 No Content`	删除成功且不返回 body
`400 Bad Request`	请求语义不合法
`401 Unauthorized`	没有有效身份凭证
`403 Forbidden`	已登录但没有权限
`404 Not Found`	资源不存在
`409 Conflict`	资源状态冲突，如重复创建
`422 Unprocessable Entity`	参数类型或字段约束不通过

FastAPI 中可以用 HTTPException 表达业务错误：

from fastapi import HTTPException, status


def get_item_or_404(item_id: UUID) -> ItemRead:
    item = items.get(item_id)
    if item is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )
    return item

如果项目中错误结构需要统一，比如都返回 {"code": "...", "message": "..."}，可以再引入全局异常处理器。但在入门阶段，先把正确状态码用好，比过早设计复杂错误体系更重要。

十、测试：用接口行为保护重构

FastAPI 提供 TestClient，可以像调用普通 HTTP 接口一样测试你的应用。

安装测试依赖：

`1`	`pip install pytest`

tests/test_items.py：

from fastapi.testclient import TestClient

from main import app


client = TestClient(app)


def test_create_item() -> None:
    response = client.post(
        "/items",
        headers={"X-Token": "dev-token"},
        json={"name": "Mouse", "price": 99.0, "tags": ["peripheral"]},
    )

    assert response.status_code == 201
    body = response.json()
    assert body["name"] == "Mouse"
    assert body["price"] == 99.0
    assert "id" in body


def test_reject_invalid_price() -> None:
    response = client.post(
        "/items",
        headers={"X-Token": "dev-token"},
        json={"name": "Mouse", "price": -1},
    )

    assert response.status_code == 422


def test_reject_missing_token() -> None:
    response = client.get("/items")

    assert response.status_code == 401

运行：

pytest

接口测试的重点不是追求行覆盖率，而是锁住 API 行为：状态码、响应字段、错误场景和鉴权路径。只要这些行为被测试保护，后面把内存字典替换成数据库时就安心很多。

十一、部署前需要想清楚的事

本地开发时可以用：

`1`	`fastapi dev main.py`

生产环境不要直接用开发命令。你可以使用 FastAPI CLI 的生产命令：

`1`	`fastapi run app/main.py --host 0.0.0.0 --port 8000`

也可以显式使用 Uvicorn：

`1`	`uvicorn app.main:app --host 0.0.0.0 --port 8000`

一个最小 Dockerfile 可以长这样：

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

EXPOSE 8000
CMD ["fastapi", "run", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]

生产环境至少要补齐这些点：

项目	为什么重要
固定依赖版本	避免一次重新构建引入不可预期变更
环境变量管理	数据库地址、密钥、第三方 Token 不要写死在代码里
健康检查	让负载均衡和容器平台知道服务是否可用
结构化日志	方便按 request_id、user_id、status_code 排查问题
数据库迁移	用 Alembic 等工具管理 schema 变化
超时与重试	防止外部服务拖垮自己的接口
限流与鉴权	公开 API 必须考虑滥用和越权
HTTPS 与反向代理	生产入口通常交给 Nginx、Traefik、云负载均衡等

十二、常见坑

坑	更稳的做法
把所有代码写进 `main.py`	入门可以，变大后用 `APIRouter`、service、db 分层
路由函数里写大量业务分支	路由层只处理 HTTP，业务规则移到 service
不写 `response_model`	为公开 API 写响应模型，保护字段边界
`async def` 里调用同步阻塞库	同步库用 `def`，异步链路才用 `async def`
返回 `200` 表示所有结果	正确使用 `201`、`204`、`401`、`404`、`409`、`422`
把密钥写进代码	用环境变量或 Secret 管理
不写测试就接数据库	先用行为测试保护接口，再替换持久化实现

十三、学习路线

到这里，你已经掌握了 FastAPI 最重要的主干。接下来可以按这个顺序继续：

SQLAlchemy 2.x 或 SQLModel：把内存字典换成数据库；
Alembic：管理数据库迁移；
OAuth2 / JWT：实现真实登录鉴权；
BackgroundTasks / Celery / RQ：处理慢任务；
中间件：统一日志、request_id、CORS、耗时统计；
OpenTelemetry：接入链路追踪；
Docker Compose / Kubernetes：把 API、数据库、缓存组成可部署系统。

FastAPI 的学习曲线很友好，但它不是“玩具框架”。当你把类型契约、依赖注入、测试和部署纪律一起用起来，它完全可以支撑严肃的生产 API。

参考资料

Token 是怎么计算的：AI 厂商和中转站如何统计用量

Fri, 04 Sep 2026 21:43:19 +0800

Token 是怎么计算的：AI 厂商和中转站如何统计用量

用大模型 API 时，经常会看到 prompt_tokens、completion_tokens、total_tokens 这些字段。很多人第一反应是：“Token 是不是就是字数？”不是。Token 是模型真正处理文本时使用的基本编号单元，厂商和中转站的用量统计，本质上就是围绕这些编号单元做输入、输出、缓存、工具调用和账单记录。

先给出一句话版本：

问题	简短答案
Token 是什么	模型 tokenizer 把文本切分后得到的编号单元
Token 等于字数吗	不等于。中文、英文、标点、空格、代码都会有不同切法
厂商怎么统计	请求进入模型前统计输入 token，生成时统计输出 token，结束后返回 usage
中转站怎么统计	优先读取上游厂商返回的 usage，同时自己预估、限额、落库、扣费
为什么我本地算的不一样	tokenizer 不同、隐藏模板、工具 schema、RAG 上下文、多模态、重试和缓存都会带来差异

一、Token 到底是什么

大模型并不是直接理解“字”或“词”。在进入模型前，文本会先经过一个叫 Tokenizer 的组件，被切成一串 token，然后每个 token 再映射成数字 ID。

flowchart LR A[原始文本] --> B[Tokenizer 切分] B --> C[Token 序列] C --> D[Token ID] D --> E[模型推理]

比如用户输入：

`1`	`帮我写一个 Dockerfile`

在 tokenizer 看来，它可能会被切成类似这样的片段：

`1`	`["帮", "我", "写", "一个", " Docker", "file"]`

这只是示意，不同模型的 tokenizer 结果可能完全不同。有的模型会把常见词切成一个 token，有的会把生僻字、特殊符号、空格、换行或代码符号切得更碎。

因此：

hello 可能是 1 个 token；
hello world 可能是 2 到 3 个 token；
一个中文词可能是 1 个 token，也可能被拆成多个 token；
代码、JSON、Base64、日志堆栈通常比较费 token；
空格、换行、标点也可能被计入 token。

更准确地说，Token 是 “模型词表里的最小可识别片段”。模型每次生成回答，本质上也是一个 token 一个 token 地往外吐。

二、为什么大模型要按 Token 计费

因为大模型的主要成本和 token 数强相关：

输入越长，模型要读的上下文越多；
输出越长，模型要生成的步骤越多；
上下文越长，显存、缓存和注意力计算压力越大；
如果启用工具调用、多模态、长上下文、推理增强，成本结构还会更复杂。

所以厂商通常不会简单按“请求次数”计费，而是按 token 计量。

常见账单可以抽象成：

1
2
3

费用 = 输入 token 数 * 输入单价
     + 输出 token 数 * 输出单价
     + 缓存 / 推理 / 图片 / 音频 / 工具等附加 token 成本

为什么输出 token 往往更贵？因为输出不是一次性算出来的，而是模型逐步生成。每生成一个新 token，都要基于已有上下文继续推理一次。输入阶段可以有缓存和批处理优化，输出阶段通常更受实时生成过程约束。

三、一次请求里哪些内容会被计入 Token

很多人只会数用户输入的那句话，但真实 API 请求里远不止这些内容。

内容	是否通常计入	说明
用户消息	是	用户真正输入的问题
系统提示词	是	`system` 或平台预置角色设定
开发者提示词	是	一些平台会额外注入规则或安全策略
历史对话	是	多轮聊天时，前面的上下文也会重新进入模型
RAG 检索片段	是	从知识库召回后拼进 prompt 的内容
工具定义	是	Function calling / tool schema 往往很占 token
工具调用结果	是	工具返回的 JSON、表格、日志也会进入后续上下文
输出文本	是	模型生成的回答
图片、音频、视频	视模型而定	通常会折算成专门的输入或输出计量单位
缓存命中内容	视厂商而定	有的平台会单独返回 cached tokens，并按更低价格计费

所以你看到的一次“简单提问”，在服务端可能是这样的：

系统提示词
+ 平台安全规则
+ 历史对话
+ 用户当前问题
+ RAG 检索内容
+ 工具 schema
+ 输出格式约束
= 实际输入给模型的 prompt

这也是为什么同样一句“帮我总结一下”，在不同应用里消耗 token 差异很大。聊天框、知识库问答、Agent、代码助手、联网搜索，它们背后拼进去的上下文不一样。

四、厂商是怎么统计 Token 的

AI 厂商统计 token，通常发生在模型服务的几个关键节点。

sequenceDiagram participant C as Client participant G as API Gateway participant T as Tokenizer participant M as Model Server participant B as Billing C->>G: 发送请求 G->>G: 鉴权、限流、检查上下文长度 G->>T: 对输入消息做 tokenization T-->>G: input token count G->>M: 输入 token ID M-->>G: 逐 token 生成输出 G->>G: 统计 output token count G->>B: 写入 usage 和账单事件 G-->>C: 返回 response + usage

大致流程是：

请求进入网关：先鉴权，确认 API Key、组织、项目、余额、限速策略；
规范化请求：把 messages、tools、response format、多模态内容等转成模型内部格式；
输入计数：用该模型对应的 tokenizer 计算输入 token；
上下文检查：判断输入 token + 允许输出 token 是否超过模型上下文窗口；
模型生成：模型每生成一个 token，服务端就能记录输出 token；
结束汇总：生成完成、被 stop 截断、达到最大输出长度或发生错误后，汇总 usage；
账单落库：把模型、用户、请求 ID、token 数、价格、状态写入计费系统；
返回结果：API 响应里通常会带 usage 字段，供调用方记录。

一个典型 usage 结构可能长这样：

{
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 350,
    "total_tokens": 1550
  }
}

更复杂的平台还可能拆得更细：

{
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 350,
    "cached_input_tokens": 800,
    "reasoning_tokens": 120,
    "image_input_tokens": 240
  }
}

字段名和含义会随厂商变化，但底层逻辑类似：把模型实际处理过的输入和实际生成过的输出，折算成可计费单位。

五、流式输出怎么统计

流式输出看起来像模型一边想一边发，其实服务端仍然知道自己生成了多少 token。

普通非流式响应：

`1`	`模型生成完整回答 → 统计输出 token → 一次性返回 response + usage`

流式响应：

模型生成 token 1 → 发一个 chunk
模型生成 token 2 → 发一个 chunk
模型生成 token 3 → 发一个 chunk
...
模型结束 → 返回最终 usage 或由服务端内部记录

中转站处理流式请求时通常会做两件事：

边转发 chunk 给客户端，保证用户体验；
同时缓存或累积输出文本，等上游结束后记录用量。

如果上游在最后一个 chunk 里返回 usage，中转站就直接使用它。如果上游不返回 usage，中转站可能会用 tokenizer 对完整输出再算一次，作为估算值。

流式计费最容易出问题的地方是断连：

场景	通常怎么处理
用户主动停止生成	已经生成的输出 token 仍可能计费
客户端网络断开	上游可能还生成了一小段，取决于中转站是否及时取消请求
中转站转发失败	要看上游是否已经成功处理，以及中转站的计费策略
请求超时	可能只有输入被处理，也可能已有部分输出

因此严谨的中转站不会只根据“客户端收到了多少字”扣费，而会尽量以 上游 usage 或服务端实际生成记录 为准。

六、中转站是怎么统计用户用量的

中转站可以理解成站在用户和上游模型厂商之间的 API 网关。它要做的不只是转发请求，还要做鉴权、限流、余额、计费、渠道选择和审计。

flowchart TD A[用户请求] --> B[中转站鉴权] B --> C[余额和额度检查] C --> D[预估输入 token] D --> E[选择上游渠道] E --> F[转发给模型厂商] F --> G[读取上游 usage] G --> H[按价格表计算成本] H --> I[扣用户余额或额度] I --> J[写入用量流水] J --> K[返回结果给用户]

中转站一般会有三层统计：

层级	作用	准确性
请求前预估	判断是否超上下文、余额是否足够、是否限流	估算
请求后结算	根据上游 usage 或本地 tokenizer 计算真实消耗	更接近真实
离线对账	和上游账单、渠道日志、用户流水做一致性校验	最终核对

1. 请求前：预估 Token

请求还没发给上游时，中转站通常已经要做判断：

这个请求会不会超过模型上下文窗口？
用户余额够不够？
是否超过每分钟 token 限额？
是否命中某个模型或渠道的风控限制？

这时它会用对应模型的 tokenizer 先估算输入 token：

model = request.model
tokenizer = tokenizer_registry.get(model)

normalized_prompt = render_messages(
    system=request.system,
    messages=request.messages,
    tools=request.tools,
    response_format=request.response_format
)

input_tokens_estimated = tokenizer.count(normalized_prompt)

if input_tokens_estimated + request.max_output_tokens > model.context_window:
    reject("context length exceeded")

if user.remaining_quota < estimate_cost(input_tokens_estimated, request.max_output_tokens):
    reject("insufficient quota")

这里的 render_messages 很关键。真实模型不是只看用户输入的字符串，而是看消息角色、分隔符、工具定义、输出格式等拼接后的内部 prompt。中转站如果只数 messages[-1].content，一定会低估。

2. 请求后：读取 usage 并扣费

请求完成后，中转站会优先使用上游厂商返回的 usage：

response = upstream.call(request)
usage = normalize_usage(response.usage, provider, model)

cost = usage.input_tokens * price.input
     + usage.output_tokens * price.output
     + usage.cached_tokens * price.cached_input
     + usage.reasoning_tokens * price.reasoning

ledger.insert({
    request_id,
    user_id,
    provider,
    model,
    usage,
    cost,
    status: "success"
})

user.balance -= cost

为什么要优先用上游 usage？因为上游最清楚模型内部到底拼了什么、缓存命中了多少、输出生成了多少、特殊模态如何折算。中转站自己的 tokenizer 只能尽量接近，不能保证完全一致。

3. 落库：为什么要有用量流水

一个成熟中转站不会只在用户表里减余额，还会写不可随意改动的流水记录。否则一旦用户质疑扣费，平台很难解释。

一个简化的用量表可以这样设计：

CREATE TABLE ai_usage_ledger (
    id BIGINT PRIMARY KEY,
    request_id VARCHAR(64) NOT NULL,
    user_id BIGINT NOT NULL,
    provider VARCHAR(32) NOT NULL,
    model VARCHAR(128) NOT NULL,
    prompt_tokens INT DEFAULT 0,
    completion_tokens INT DEFAULT 0,
    cached_tokens INT DEFAULT 0,
    reasoning_tokens INT DEFAULT 0,
    total_tokens INT DEFAULT 0,
    upstream_cost DECIMAL(18, 8) DEFAULT 0,
    user_cost DECIMAL(18, 8) DEFAULT 0,
    status VARCHAR(32) NOT NULL,
    created_at TIMESTAMP NOT NULL
);

关键字段：

字段	用途
`request_id`	幂等和排查，避免重试导致重复扣费
`provider`	区分不同上游厂商
`model`	不同模型价格和 tokenizer 不同
`prompt_tokens`	输入 token
`completion_tokens`	输出 token
`cached_tokens`	缓存命中的输入 token
`reasoning_tokens`	推理类模型可能单独统计的内部输出
`upstream_cost`	中转站实际付给厂商的成本
`user_cost`	中转站按自己价格表向用户收取的费用
`status`	成功、失败、取消、超时、部分输出等状态

如果平台有余额系统，扣费还要做事务处理：

begin transaction
  insert usage_ledger
  update user_balance set balance = balance - user_cost
  insert balance_change_log
commit

这样才能保证“用量流水、余额变化、账单记录”三者对得上。

七、中转站为什么会和官方统计不一致

如果你自己写一个 token 计算器，经常会发现结果和官方 usage 对不上。原因主要有这些：

原因	为什么会导致差异
tokenizer 版本不同	模型升级后词表或特殊 token 规则可能变了
消息模板不同	厂商内部会给 role、message、tool 加包装格式
系统提示词不可见	应用或中转站可能注入了用户看不到的 prompt
历史上下文被带入	多轮聊天会把旧消息一起计入输入
工具 schema 很大	一个复杂 JSON Schema 可能比用户问题还长
RAG 召回内容多	知识库片段会直接增加输入 token
输出格式约束	JSON mode、结构化输出、示例格式都会增加 prompt
多模态折算	图片、音频、视频通常不是按普通文本 token 简单计算
缓存命中	cached tokens 可能计入总量，但按不同价格结算
请求重试	上游失败重试可能产生额外成本，平台要定义是否转嫁

所以中转站的合理做法是：

请求前用本地 tokenizer 预估，用于限额和上下文判断；
请求后以上游 usage 为准结算，尽量减少争议；
没有上游 usage 时再本地估算，并在账单里标记来源；
定期离线对账，比较中转站记录和上游账单差异。

八、上下文窗口和最大输出 Token

Token 统计不只影响费用，也影响请求能不能成功。

每个模型都有上下文窗口，比如能处理 8K、32K、128K 或更长上下文。这个窗口通常要同时容纳输入和输出：

`1`	`输入 token + 最大输出 token <= 模型上下文窗口`

假设某模型上下文窗口是 8192：

输入 token	设置最大输出	是否安全
2000	1000	安全
7000	1000	接近上限
7900	1000	可能被拒绝
8200	500	输入本身已经超限

很多“上下文超长”错误，不是用户当前问题太长，而是应用把历史对话、系统 prompt、RAG 内容和工具 schema 全塞进去了。

中转站通常会在请求前做保护：

available_output = model.context_window - estimated_input_tokens

if available_output <= 0:
    reject("input too long")

max_output_tokens = min(request.max_output_tokens, available_output, platform_limit)

这也是为什么有些平台会提示“请开启上下文压缩”或“减少知识库引用数量”。本质是在帮你节省输入 token。

九、缓存 Token 是怎么回事

一些厂商会对重复前缀做上下文缓存。比如系统提示词、工具 schema、长文档前半部分每次都一样，那么服务端可以复用已经处理过的缓存，降低延迟和成本。

抽象来看：

请求 1:
长系统提示词 + 工具 schema + 用户问题 A
全部输入都需要正常处理

请求 2:
长系统提示词 + 工具 schema + 用户问题 B
前面相同部分可能命中缓存

这类 usage 可能拆成：

字段	含义
`input_tokens`	输入 token 总数
`cached_input_tokens`	输入中命中缓存的部分
`billable_input_tokens`	实际按普通输入价计费的部分，具体取决于厂商规则

对中转站来说，缓存会让计费更复杂。它不能只看 total_tokens 乘一个固定单价，而要按厂商返回的细分字段计算。

十、不同任务的 Token 消耗差异

同一个模型，不同应用形态的 token 消耗会差很多。

场景	Token 消耗特点
普通问答	用户输入短，输出长度决定主要成本
长文总结	输入很长，输出中等
代码生成	代码符号、缩进、上下文文件都比较费 token
RAG 问答	检索片段越多，输入 token 越高
Agent 调工具	工具定义和工具结果会反复进入上下文
JSON 结构化输出	schema、字段名、示例都会增加输入和输出
Embedding	通常只按输入文本 token 计量，没有 completion token
图片理解	图片会被折算成视觉输入 token 或类似单位
语音转写 / 语音生成	可能按音频时长、音频 token 或混合规则计费

如果你在开发 AI 应用，最容易低估的是三类开销：

历史对话：用户只发一句话，但你把前 30 轮都带上了；
工具 schema：函数参数定义复杂，每次请求都要传；
RAG 内容：Top-K 设得太大，召回片段太长。

优化 token 成本，通常不是把用户问题压短，而是控制这些“看不见的上下文”。

十一、如何自己估算 Token

如果你是应用开发者，至少要在请求前做一次本地估算，用来控制上下文和成本。

最简单但不精确的方法：

`1`	`estimated_tokens = text.length / 3`

这只能做非常粗的 UI 提示。更靠谱的方法是使用模型对应的 tokenizer：

1
2
3

tokenizer = get_tokenizer(model)
tokens = tokenizer.encode(rendered_prompt)
count = len(tokens)

但要记住：本地估算要尽量接近真实请求，而不是只数用户输入。

应该计入：

system prompt；
developer prompt；
历史 messages；
RAG context；
tool definitions；
response format；
当前用户问题。

不应该只计入：

`1`	`count_tokens(user_message)`

更合理的是：

rendered_prompt = render_chat_request(
    system_prompt,
    developer_prompt,
    history_messages,
    retrieved_context,
    tool_schemas,
    response_format,
    user_message
)

count_tokens(rendered_prompt, model)

本地估算的目标不是做到和厂商 100% 一样，而是提前发现明显超限和明显超预算。

十二、中转站计费系统的工程要点

如果从工程实现角度看，一个可靠的中转站至少要有这些模块：

模块	作用
模型路由	把用户请求路由到不同厂商、渠道或模型
Token 预估器	请求前计算输入 token 和最大可能成本
Usage 归一化	把不同厂商返回的 usage 统一成内部格式
价格表	维护模型输入、输出、缓存、多模态等单价
账单流水	记录每次请求的 token、费用、状态和 request_id
余额系统	做预扣、实扣、退款或额度扣减
重试策略	定义上游失败、超时、断流时是否继续扣费
对账任务	和上游账单做日级或小时级核对
风控限流	按用户、模型、IP、组织维度限制请求和 token

一个常见请求链路可以写成：

handle_request(req):
    user = authenticate(req.api_key)
    model = resolve_model(req.model)

    estimated = estimate_usage(req, model)
    reserve_quota(user, estimated.max_cost)

    try:
        upstream_resp = call_provider(req, model)
        actual_usage = normalize_usage(upstream_resp.usage)
        actual_cost = calculate_cost(actual_usage, model.price)

        settle_quota(user, actual_cost)
        write_ledger(req.id, user.id, model, actual_usage, actual_cost, "success")
        return upstream_resp

    except ProviderError as err:
        release_or_settle_by_policy(user, req.id, err)
        write_ledger(req.id, user.id, model, estimated, 0, "failed")
        raise

这里有两个细节很关键：

预扣不等于实扣：请求前按最大可能输出预扣，结束后按真实 usage 结算，多退少补；
幂等不等于不重试：同一个 request_id 重复上报时不能重复扣费，但上游真实重试产生的成本也要能解释清楚。

十三、怎么降低 Token 成本

方法	原理	风险
精简系统提示词	减少每次固定输入	规则太少可能影响输出稳定性
压缩历史对话	摘要替代完整历史	摘要可能丢细节
控制 RAG Top-K	少塞无关片段	召回不足会影响答案
缩短工具 schema	减少重复传入的结构定义	过度简化会降低工具调用准确性
设置合理最大输出	避免模型无限写长	可能截断答案
使用缓存	重复前缀命中缓存	依赖厂商支持和请求结构稳定
按任务选模型	简单任务用低成本模型	模型能力不足会带来返工
日志里记录 usage	找到最费 token 的链路	注意隐私和数据合规

实践中最有效的优化通常是这三个：

不要无脑带全量历史；
不要把过长的文档片段塞进 prompt；
不要给简单任务使用过强、过贵、上下文过大的模型。

总结

Token 计算可以拆成三层理解：

层级	关注点
模型层	tokenizer 如何把文本变成 token ID，模型如何逐 token 生成
API 层	输入、输出、工具、多模态、缓存如何汇总成 usage
平台层	中转站如何预估、限额、扣费、落库、对账和处理异常

如果只记住一句话：

Token 不是字数，而是模型实际处理的上下文单位；厂商按模型真实处理量统计 usage，中转站则围绕 usage 做预估、转发、结算和审计。

对开发者来说，真正要养成的习惯是：不要只看用户输入的长度，而要看完整上下文。系统提示词、历史消息、RAG 片段、工具 schema、结构化输出约束，都会变成模型要处理的 token，也都会最终影响成本、延迟和上下文上限。

Strapi 全解：从 Headless CMS 到可定制的 Node.js API 后端

Fri, 10 Jul 2026 22:50:00 +0800

Strapi 全解：从 Headless CMS 到可定制的 Node.js API 后端

如果一个项目既需要“让运营人员自己维护内容”，又需要“让网站、App、小程序共享同一套 API”，从零编写管理后台、权限、文件上传和 CRUD 往往很不划算。Strapi 的价值，就是把这些重复工作变成可配置的基础设施，同时保留继续写代码的出口。

本文以 Strapi 5 为基准。读完你会弄清四件事：Strapi 到底是什么、它用了哪些技术、内容模型如何变成后端 API，以及它与 Java、Go、Python 后端真正的区别。

一、Strapi 是什么？

Strapi 是一个开源、可自托管的 Headless CMS（无头内容管理系统），也是一个以内容为中心的 Node.js 后端框架。

这里的“无头”不是没有管理界面，而是不绑定面向访客的前端页面：

内容团队在 Strapi Admin 中录入文章、商品、活动和媒体；
Strapi 将内容保存到数据库，并通过 REST 或 GraphQL 提供；
React、Vue、Next.js、Nuxt、Flutter、小程序甚至 IoT 设备都可以消费同一份内容；
前端如何渲染、部署到哪里，与 CMS 后端彼此独立。

传统 CMS 通常把“内容管理”和“页面模板”绑在一起；Strapi 只负责内容与 API。它更像一个带可视化建模、管理后台和权限系统的后端工程脚手架。

先纠正一个比较口径： Strapi 不是和 Java、Go、Python 同一层级的东西。Strapi 是一套成品框架与 CMS；Java、Go、Python 是语言及其后端生态。更合理的比较对象是 Strapi vs Spring Boot、Go Web 框架、Django/DRF 或 FastAPI。

二、Strapi 的核心特点

特点	它解决了什么问题	需要注意什么
可视化内容建模	用 Content-Type Builder 定义字段、关系、组件和动态区域	复杂领域模型仍需代码设计，不能把建模完全交给运营
自动 REST API	创建内容类型后自动获得增删改查接口	内容类型默认私有，必须配置权限或 Token
GraphQL 支持	安装 GraphQL 插件后，根据模型生成查询与 Mutation	需要控制查询深度与复杂度，避免昂贵请求
完整管理后台	内容编辑、媒体库、草稿发布、国际化等开箱即用	深度定制 Admin 会进入 React 前端开发范畴
可扩展后端	可写 Route、Policy、Middleware、Controller、Service 和生命周期逻辑	自定义逻辑越多，越应补齐测试与分层
多数据库支持	支持 SQLite、PostgreSQL、MySQL、MariaDB	Strapi 5 不支持 MongoDB，也不适合直接接管既有数据库
API 安全能力	Public/Authenticated 角色、API Token、字段和操作权限	“有权限系统”不等于自动安全，仍要做限流、审计和密钥管理
自托管与云部署	代码和数据可掌握在自己手中，也可使用 Strapi Cloud	自托管时，升级、备份、监控与扩容由团队负责

它最突出的优势不是“某个接口跑得最快”，而是把一组常见需求一次交付：

数据库模型 + CRUD API + 内容后台 + 权限 + 媒体 + 发布工作流。

这正是内容型项目中最耗费重复劳动的部分。

三、Strapi 的技术栈

从外到内看，一套典型 Strapi 5 应用包含这些层次：

层次	主要技术	职责
运行时	Node.js	运行 JavaScript / TypeScript 后端，擅长 I/O 密集型请求
开发语言	TypeScript 或 JavaScript	编写配置、控制器、服务、策略与插件
HTTP 层	Koa 生态与 Strapi 路由层	接收请求、执行中间件并构造响应
管理后台	React + Strapi Design System	提供内容管理与系统配置界面
数据访问	Strapi Document Service / Query Engine	统一处理内容、文档、多语言与草稿发布语义
SQL 抽象	Knex	连接 SQLite、PostgreSQL、MySQL 等关系数据库
API	REST；可选 GraphQL 插件	向不同终端分发内容
扩展机制	Plugin、Provider、Middleware、Policy、Lifecycle	对接对象存储、邮件、鉴权和业务逻辑

Strapi 5 中的 Document 值得单独理解：同一篇内容可能同时有草稿版、发布版和多个语言版本，documentId 用来标识它们所属的逻辑文档。因此，单条 REST 接口使用的是：

`1`	`GET /api/articles/:documentId`

而不是旧教程中常见的数字 id。此外，Strapi 5 的响应已经扁平化，字段直接位于 data 对象中，不再放在 data.attributes 里。

四、它是怎么“生成”后端 API 的？

Strapi 的核心思路是 Content Model First：先描述内容结构，再由框架装配数据库结构、管理表单和 API。

假设我们创建一个 Collection Type：Article，并定义以下字段：

字段	类型	约束
`title`	Short text	必填
`slug`	UID	基于 title，唯一
`summary`	Long text	可选
`content`	Blocks / Rich text	正文
`cover`	Media	单张图片
`author`	Relation	多篇文章属于一个作者
`featured`	Boolean	默认 false

保存模型后，Strapi 会完成几件事：

把模型保存为项目中的 schema；
同步对应的数据库表、列和关系；
在 Admin 中生成文章编辑表单和列表；
注册核心 Controller 与 Service；
注册 /api/articles 的 REST CRUD 路由；
如果安装了 GraphQL 插件，再把模型加入 GraphQL Schema。

REST 接口随即具备下面这些约定：

动作	方法与路径
查询列表	`GET /api/articles`
查询单篇	`GET /api/articles/:documentId`
创建	`POST /api/articles`
更新	`PUT /api/articles/:documentId`
删除	`DELETE /api/articles/:documentId`

4.1 从零跑起一个 API

1
2
3

npx create-strapi@latest blog-api --quickstart
cd blog-api
npm run develop

打开 http://localhost:1337/admin 创建管理员，然后在 Content-Type Builder 中建立 Article。

新内容类型默认是私有的。你可以在 Settings → Users & Permissions 中仅开放 find、findOne，也可以给服务器端调用者创建 API Token。生产环境更推荐最小权限 Token，而不是把写接口设为 Public。

查询已发布文章：

1
2

curl 'http://localhost:1337/api/articles?sort=publishedAt:desc&pagination[pageSize]=10' \
  -H 'Authorization: Bearer <token>'

按条件过滤，并显式取回封面与作者：

1
2

curl 'http://localhost:1337/api/articles?filters[featured][$eq]=true&populate[cover]=true&populate[author]=true' \
  -H 'Authorization: Bearer <token>'

创建文章时，业务字段必须包在 data 中：

curl -X POST 'http://localhost:1337/api/articles' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "title": "Hello Strapi",
      "slug": "hello-strapi",
      "summary": "My first content API",
      "featured": true
    }
  }'

一个典型的 Strapi 5 列表响应如下：

{
  "data": [
    {
      "id": 17,
      "documentId": "n7m6d9p3k2x8...",
      "title": "Hello Strapi",
      "slug": "hello-strapi",
      "featured": true,
      "publishedAt": "2026-07-10T14:20:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "pageCount": 1,
      "total": 1
    }
  }
}

常见坑： 关系、媒体、组件和 Dynamic Zone 默认不会被填充。不要习惯性使用 populate=* 拉取一切；生产环境应明确选择字段和关联，控制响应体积与数据库查询成本。

4.2 自动 CRUD 不够时怎么办？

Strapi 并没有把你锁在自动生成代码里。比如要增加 GET /api/articles/featured，可以写自定义路由、控制器和服务：

// src/api/article/routes/01-featured.ts
export default {
  routes: [
    {
      method: 'GET',
      path: '/articles/featured',
      handler: 'article.featured',
      config: { auth: false },
    },
  ],
};

// src/api/article/controllers/article.ts
import { factories } from '@strapi/strapi';

export default factories.createCoreController(
  'api::article.article',
  ({ strapi }) => ({
    async featured(ctx) {
      const data = await strapi
        .service('api::article.article')
        .findFeatured();

      ctx.body = { data };
    },
  })
);

// src/api/article/services/article.ts
import { factories } from '@strapi/strapi';

export default factories.createCoreService(
  'api::article.article',
  ({ strapi }) => ({
    async findFeatured() {
      return strapi.documents('api::article.article').findMany({
        filters: { featured: true },
        status: 'published',
        sort: ['publishedAt:desc'],
        limit: 5,
      });
    },
  })
);

请求进入后，并不是 Controller 直接拼 SQL，而是沿着分层链路运行：

Route 决定方法、路径和处理器；
Middleware 处理日志、CORS、限流、请求改写等横切逻辑；
Policy 判断当前身份能否执行该动作；
Controller 读取 HTTP 上下文并组织响应；
Service 承载可复用业务逻辑；
Document Service 处理文档、语言、草稿/发布等 Strapi 语义；
Database / Knex 才最终访问关系数据库。

这种分层和 Spring Boot、Django 的 Controller/Service/Repository 思路并不陌生；区别在于 Strapi 已经替你实现了大量默认层。

五、与 Java、Go、Python 后端有什么区别？

先看一张定位图：

维度	Strapi（Node.js/TS）	Java（Spring Boot）	Go（Gin/Chi/Fiber 等）	Python（Django/DRF/FastAPI）
起步方式	内容模型优先，自动生成 CRUD 与 Admin	代码优先，显式设计实体、接口与分层	代码优先，组合库并显式实现	Django 偏全栈；DRF/FastAPI 以代码定义 API
首个内容 API	非常快，分钟级	较慢，但工程规范与能力完整	较快，但后台、权限、媒体需另配	Django + Admin 很快；FastAPI 仍需管理端
管理后台	一等公民，面向内容团队	通常另做或采购	通常另做	Django Admin 强；FastAPI 默认无
类型系统	TypeScript 静态检查，运行时仍是 JS	强静态类型，编译期约束成熟	简洁强类型，编译快	动态类型为主，可用 type hints / Pydantic
并发模型	事件循环，适合 I/O 密集型	线程池/虚拟线程，生态成熟	goroutine 轻量并发	async 可处理 I/O；CPU 密集受解释器模型影响
性能与资源	通常足够支撑内容 API，不以极限吞吐见长	吞吐稳定，但 JVM 启动与内存成本较高	吞吐高、内存低、单二进制部署	开发效率高，极限吞吐通常不是优势
事务与复杂领域	能做，但 CMS 抽象不适合所有复杂交易	强项：事务、DDD、消息与企业集成	显式、可控，但很多能力要自行组合	Django ORM 事务成熟；复杂系统仍需严谨分层
可定制性	默认能力多，越偏离内容 CRUD 定制成本越高	几乎不设上限，但样板和工程成本更高	控制力强、魔法少	从 Django 的“全家桶”到 FastAPI 的轻量均可选
部署形态	Node 应用 + 数据库 + 媒体存储	JVM/JAR/容器	单二进制或容器	Python 运行时 + WSGI/ASGI 服务器
最适合	CMS、官网、多渠道内容、产品目录	核心交易、复杂企业系统、大型团队	高性能服务、网关、云原生基础设施	数据/AI 服务、业务后台、快速 API 开发

5.1 Strapi vs Java：默认能力与领域控制力

Spring Boot 通常从领域模型、DTO、Repository、Service、Controller 一层层搭建。前期代码更多，但复杂事务、消息中间件、审计、强类型契约和大型团队治理都很成熟。

Strapi 则先送你一套能用的内容平台。对于“文章、作者、分类、媒体、国际化”这类模型，它能省掉大量工作；但如果系统核心是支付清算、库存扣减、复杂审批或跨服务事务，Java 的显式领域模型通常更稳妥。

5.2 Strapi vs Go：交付速度与运行效率

Go 服务倾向于少魔法、显式依赖和小体积部署。它能用更少内存提供很高吞吐，特别适合网关、基础设施和高并发微服务。

代价是 Go Web 框架很少直接送你内容后台、媒体库、草稿发布与细粒度内容权限。若项目主要是内容运营，Strapi 更快；若核心目标是极低延迟、资源效率或简单可靠的服务进程，Go 更合适。

5.3 Strapi vs Python：与 Django 最像，但重心不同

Django Admin 让 Python 阵营也能快速得到数据管理后台，Django REST Framework 再提供序列化、权限和 API。因此 Django/DRF 是这里与 Strapi 最接近的组合。

区别在于：Django 更像通用 Web 框架，Admin 主要服务内部数据管理；Strapi 从一开始就围绕“结构化内容、多渠道分发、编辑体验”设计。FastAPI 则更轻，特别适合类型清晰的 API、数据和 AI 服务，但不会自动给你完整 CMS。

六、什么时候该选 Strapi？

很适合

企业官网、营销站、新闻与博客；
多语言、多品牌、多终端共享内容；
App、小程序、网站共用文章、Banner、活动和配置；
产品目录、案例库、帮助中心；
前端团队需要快速获得可用后端，内容团队又必须独立编辑；
MVP 中大量需求属于标准 CRUD + 内容工作流。

谨慎选择

银行账务、支付、交易撮合、复杂库存等强事务核心；
需要直接接管庞大既有数据库的系统；
大量 CPU 密集计算、极端低延迟或极限吞吐服务；
API 主要是复杂动作和跨域编排，内容 CRUD 只占很小比例；
团队完全没有 Node.js/TypeScript 运维与升级经验。

一个很实用的组合是：

Strapi 管内容与运营配置
        +
Java / Go / Python 管核心业务
        +
API Gateway 或 BFF 统一对前端提供契约

不要强迫一项技术包办所有问题。Strapi 可以是系统中的“内容服务”，而不是整个后端。

七、生产落地的 8 条建议

生产使用 PostgreSQL 或 MySQL。 SQLite 适合本地体验和轻量场景，不适合多数多实例生产部署。
权限遵循最小化。 写接口不要设为 Public，给不同调用方发放不同作用域的 API Token。
显式 populate 与 fields。 只查需要的字段和关联，避免查询爆炸与巨大 JSON。
把业务逻辑放进 Service。 Controller 只处理 HTTP，Policy 做授权，Service 保持可测试。
模型随代码发布。 在开发环境修改内容模型，把 schema 与迁移纳入 Git 和发布流程。
媒体放对象存储。 多实例部署不要依赖单机磁盘，可接 S3 兼容存储与 CDN。
补齐缓存和可观测性。 热点内容可放 CDN/Redis，同时记录慢查询、错误率和事件循环延迟。
升级前阅读迁移说明。 插件与自定义 Admin 是升级风险最高的部分，先在预发布环境验证。

总结

理解 Strapi 的最好方式，不是把它叫作“低代码后端”，而是把它看成：

一个以结构化内容为核心、自动提供管理后台和 API、同时允许继续写 Node.js/TypeScript 代码的 Headless CMS 框架。

它用约定和自动化换取了极高的内容型项目交付速度；Java、Go、Python 通用后端则用更多显式代码换取更广的业务边界、性能特征或生态能力。

选择标准也因此很清楚：

核心问题是“怎样高效管理并分发内容”——优先考虑 Strapi；
核心问题是“怎样实现复杂交易、极限性能或专用计算”——优先考虑 Java、Go 或 Python；
两类问题同时存在——让 Strapi 做内容服务，与核心业务后端协作。

参考资料

本文基于 2026 年 7 月可用的 Strapi 5 官方资料撰写。版本升级可能改变命令、运行时要求和插件行为，落地时请以对应版本文档为准。

API on Snow

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

一、FastAPI 解决的核心问题

二、环境准备

三、第一个可运行 API

四、类型提示如何变成接口契约

五、Pydantic：把边界数据变可信

六、依赖注入：把横切逻辑拿出接口函数

七、项目变大后怎么拆

八、async def 不等于自动更快

九、错误处理与状态码

十、测试：用接口行为保护重构

十一、部署前需要想清楚的事

十二、常见坑

十三、学习路线

参考资料

Token 是怎么计算的：AI 厂商和中转站如何统计用量

Token 是怎么计算的：AI 厂商和中转站如何统计用量

一、Token 到底是什么

二、为什么大模型要按 Token 计费

三、一次请求里哪些内容会被计入 Token

四、厂商是怎么统计 Token 的

五、流式输出怎么统计

六、中转站是怎么统计用户用量的

1. 请求前：预估 Token

2. 请求后：读取 usage 并扣费

3. 落库：为什么要有用量流水

七、中转站为什么会和官方统计不一致

八、上下文窗口和最大输出 Token

九、缓存 Token 是怎么回事

十、不同任务的 Token 消耗差异

十一、如何自己估算 Token

十二、中转站计费系统的工程要点

十三、怎么降低 Token 成本

总结

Strapi 全解：从 Headless CMS 到可定制的 Node.js API 后端

Strapi 全解：从 Headless CMS 到可定制的 Node.js API 后端

一、Strapi 是什么？

二、Strapi 的核心特点

三、Strapi 的技术栈

四、它是怎么“生成”后端 API 的？

4.1 从零跑起一个 API

4.2 自动 CRUD 不够时怎么办？

五、与 Java、Go、Python 后端有什么区别？

5.1 Strapi vs Java：默认能力与领域控制力

5.2 Strapi vs Go：交付速度与运行效率

5.3 Strapi vs Python：与 Django 最像，但重心不同

六、什么时候该选 Strapi？

很适合

谨慎选择

七、生产落地的 8 条建议

总结

参考资料

八、`async def` 不等于自动更快