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。

参考资料

How Token Counting Works: How AI Providers and API Proxies Track Usage

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

How Token Counting Works: How AI Providers and API Proxies Track Usage

When using LLM APIs, you often see fields such as prompt_tokens, completion_tokens, and total_tokens. A token is not simply a word or character. It is the unit produced by the model’s tokenizer, and provider billing is built around counting input, output, cached, tool, and multimodal units.

The short version:

Question	Answer
What is a token	A unit produced when the tokenizer splits text
Is it the same as word count	No. Chinese, English, punctuation, whitespace, and code tokenize differently
How providers count it	They count input before inference, output during generation, then return usage
How API proxies count it	They estimate before forwarding, prefer upstream usage after completion, then settle billing
Why local counts differ	Tokenizer mismatch, hidden prompts, tool schemas, RAG context, multimodal inputs, retries, and caching

1. What a token is

LLMs do not process raw text directly. Before inference, text goes through a tokenizer, which splits it into tokens and maps each token to a numeric ID.

flowchart LR A[Raw text] --> B[Tokenizer] B --> C[Token sequence] C --> D[Token IDs] D --> E[Model inference]

For example:

`1`	`Write a Dockerfile for me`

may be split into pieces such as:

`1`	`["Write", " a", " Docker", "file", " for", " me"]`

This is only illustrative. Different models can tokenize the same text differently. Common words may be one token, rare characters may be split, and whitespace, punctuation, JSON, logs, and source code can all add tokens.

The practical definition is: a token is the smallest vocabulary unit the model actually reads or generates.

2. Why billing is token-based

LLM cost is strongly related to token count:

longer inputs require more context processing;
longer outputs require more generation steps;
larger context windows increase memory and attention cost;
tools, multimodal input, long context, caching, and reasoning models add more accounting dimensions.

A simplified formula:

1
2
3

cost = input_tokens * input_price
     + output_tokens * output_price
     + cached / reasoning / image / audio / tool-related token cost

Output tokens are often priced higher because they are generated step by step. Each new token depends on the current context and previous generated tokens.

3. What gets counted in a request

Real API requests usually contain more than the user’s latest message.

Content	Usually counted	Note
User message	Yes	The user’s visible input
System prompt	Yes	Role and behavior instructions
Developer prompt	Yes	Platform or application rules
Conversation history	Yes	Previous turns re-enter the context
RAG snippets	Yes	Retrieved context is added to the prompt
Tool definitions	Yes	Function schemas can be large
Tool results	Yes	JSON, tables, and logs may enter later turns
Output text	Yes	The model’s generated answer
Images, audio, video	Depends on model	Often converted into special billing units
Cached content	Depends on provider	May be reported and priced separately

A “simple” request may become:

system prompt
+ platform safety rules
+ conversation history
+ current user message
+ RAG context
+ tool schemas
+ output format instructions
= actual model input

This is why the same user message can cost very different amounts in a chat app, RAG app, coding assistant, agent, or search-enabled assistant.

4. How providers count tokens

Provider-side usage counting usually happens across the gateway, tokenizer, model server, and billing system.

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: Send request G->>G: Auth, rate limit, context check G->>T: Tokenize input T-->>G: Input token count G->>M: Send token IDs M-->>G: Generate output tokens G->>G: Count output tokens G->>B: Write usage and billing event G-->>C: Return response and usage

Typical steps:

authenticate API key, project, organization, quota, and rate limits;
normalize messages, tools, response format, and multimodal inputs;
count input tokens with the model’s tokenizer;
check context length;
generate output and count generated tokens;
summarize usage when generation stops, is truncated, or errors;
write model, user, request ID, tokens, cost, and status into billing;
return a response with usage metadata.

A simple usage object may look like:

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

More detailed platforms may expose:

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

Field names differ across providers, but the core idea is the same: bill the units the model actually processed and generated.

5. Streaming usage

For non-streaming calls:

`1`	`generate full answer -> count output tokens -> return response + usage`

For streaming calls:

generate token 1 -> send chunk
generate token 2 -> send chunk
generate token 3 -> send chunk
...
finish -> return final usage or record it internally

An API proxy usually relays chunks while also accumulating the response. If the upstream provider returns usage in the final chunk, the proxy uses it. If not, it may re-tokenize the final output and estimate usage locally.

Interrupted streams need careful handling:

Scenario	Typical treatment
User stops generation	Already generated output tokens may still be billed
Client disconnects	Depends on whether the proxy cancels upstream quickly
Proxy forwarding fails	Depends on whether upstream already processed the request
Timeout	May include only input or partial output

A serious proxy should not bill only by the characters received by the client. It should rely on upstream usage or server-side generation records when possible.

6. How API proxy platforms track usage

An API proxy sits between users and model providers. It forwards requests, but also manages authentication, quota, pricing, routing, retries, and audit records.

flowchart TD A[User request] --> B[Proxy auth] B --> C[Quota and balance check] C --> D[Estimate input tokens] D --> E[Choose upstream provider] E --> F[Forward request] F --> G[Read upstream usage] G --> H[Calculate cost] H --> I[Deduct balance or quota] I --> J[Write usage ledger] J --> K[Return response]

There are usually three accounting layers:

Layer	Purpose	Accuracy
Pre-request estimate	Context check, balance check, rate limiting	Estimate
Post-request settlement	Use upstream usage or local tokenizer result	Closer to real usage
Offline reconciliation	Compare proxy records with provider invoices	Final audit

Pre-request estimate

Before forwarding, the proxy needs to decide whether the request should be accepted.

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")

The render_messages step matters. Counting only the latest user message underestimates the request.

Post-request settlement

After completion, the proxy should prefer provider 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

Provider usage is more authoritative because the provider knows internal templates, cache hits, special modalities, and exact generated output.

Usage ledger

A mature proxy writes immutable usage records instead of only reducing a user balance.

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
);

The ledger makes billing explainable: request ID, user, provider, model, token counts, upstream cost, user-facing cost, and status can all be audited.

7. Why proxy counts can differ from official counts

Cause	Why it differs
Tokenizer version mismatch	Model tokenizer rules may differ or evolve
Message template mismatch	Providers wrap roles, tools, and messages internally
Hidden system prompt	Apps or proxies may inject invisible instructions
Conversation history	Old messages re-enter the input
Large tool schemas	JSON schemas can exceed the user prompt
RAG context	Retrieved chunks increase input tokens
Structured output	JSON schema and examples add prompt cost
Multimodal conversion	Images and audio are not simple text tokens
Cache hits	Cached tokens may have separate pricing
Retries	Failed upstream attempts may still create cost

Reasonable proxy behavior:

estimate locally before request;
settle with upstream usage after request;
estimate locally only when upstream usage is unavailable;
reconcile proxy logs with upstream bills regularly.

8. Context windows and maximum output

Token counting also determines whether a request can fit into the model context window:

`1`	`input tokens + maximum output tokens <= context window`

Example with an 8192-token context window:

Input tokens	Max output	Safe
2000	1000	Yes
7000	1000	Near the limit
7900	1000	Likely rejected
8200	500	Input already exceeds window

Many context length errors are not caused by the latest user message. They come from history, system prompts, RAG snippets, tool schemas, and output constraints.

9. Cached tokens

Some providers cache repeated prompt prefixes. If the system prompt, tool schema, or a long document prefix is identical across requests, the provider may reuse processed context.

Request 1:
long system prompt + tool schema + user question A
all input processed normally

Request 2:
long system prompt + tool schema + user question B
the repeated prefix may hit cache

Usage may include:

Field	Meaning
`input_tokens`	Total input tokens
`cached_input_tokens`	Input tokens served from cache
`billable_input_tokens`	Tokens charged at normal input price, depending on provider rules

For proxies, this means pricing cannot always be total_tokens * one_price. Detailed fields matter.

10. Where token cost grows

Scenario	Token pattern
Simple Q&A	Short input, output dominates
Long summarization	Long input, medium output
Code generation	Code symbols, indentation, and file context add tokens
RAG Q&A	More retrieved chunks means more input tokens
Agent tool use	Tool schemas and tool results repeatedly enter context
Structured JSON output	Schemas and field names add prompt and output tokens
Embeddings	Usually input-only usage
Image understanding	Images are converted to visual input units
Speech tasks	May use duration, audio tokens, or mixed billing

The most commonly underestimated costs are history, tool schemas, and retrieved context.

11. Estimating tokens yourself

A rough UI estimate may use:

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

But application-side controls should use a tokenizer compatible with the selected model:

1
2
3

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

Estimate the rendered prompt, not only the latest 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)

The goal is not perfect agreement with the provider. The goal is to catch obvious context overflows and cost spikes early.

12. Engineering notes for proxy billing

Module	Purpose
Model router	Select provider, channel, and model
Token estimator	Pre-check input tokens and maximum cost
Usage normalizer	Convert provider-specific usage into internal fields
Price table	Store input, output, cached, and multimodal prices
Usage ledger	Record tokens, cost, status, and request ID
Balance system	Reserve, settle, refund, or deduct quota
Retry policy	Decide how failed and interrupted calls are charged
Reconciliation job	Compare internal ledger with provider invoices
Rate limiting	Limit requests and token usage by user, model, IP, or org

Typical request handling:

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

Two details matter:

reservation is not settlement: reserve by worst-case output, settle by actual usage;
idempotency matters: repeated reporting for the same request_id must not double-charge the user.

13. Reducing token cost

Method	Why it works	Risk
Shorten system prompts	Reduces fixed input	Too little instruction can hurt stability
Compress history	Replaces full turns with summaries	Summaries may lose details
Control RAG Top-K	Adds fewer irrelevant chunks	Recall may suffer
Simplify tool schemas	Reduces repeated schema cost	Tool calls may become less precise
Set output limits	Prevents overly long completions	Answers may be truncated
Use caching	Reuses stable prefixes	Depends on provider support
Choose model by task	Simple tasks use cheaper models	Lower quality may require retries
Log usage	Finds the most expensive paths	Must respect privacy and compliance

Summary

Token counting has three layers:

Layer	Focus
Model layer	Tokenizer turns text into token IDs, then the model generates token by token
API layer	Input, output, tools, multimodal content, and cache are summarized as usage
Platform layer	Proxies estimate, limit, settle, audit, and reconcile usage

The key idea:

A token is not a character count. It is the unit the model actually processes. Providers count real model usage; proxies estimate before forwarding, settle after receiving usage, and keep ledger records for billing and audit.

For application developers, the main habit is to measure the full rendered context. System prompts, history, RAG snippets, tool schemas, and structured output constraints all become tokens, and therefore affect cost, latency, and context limits.

Strapi Explained: From Headless CMS to Customizable Node.js API Backend

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

Strapi Explained: From Headless CMS to Customizable Node.js API Backend

When a product needs both an editor-friendly content system and a shared API for websites, mobile apps and other clients, rebuilding CRUD endpoints, an admin UI, permissions and media handling is rarely the best use of engineering time. Strapi turns those recurring requirements into configurable infrastructure while preserving an escape hatch to code.

This article uses Strapi 5 as its baseline. We will answer four questions: What is Strapi? What is it built with? How does a content model become an API? And how does it really differ from Java, Go and Python backend stacks?

1. What is Strapi?

Strapi is an open-source, self-hostable headless CMS and a content-centered Node.js backend framework.

“Headless” does not mean there is no admin interface. It means the CMS does not own the visitor-facing presentation layer:

Editors create articles, products, campaigns and media in Strapi Admin.
Strapi stores that structured content and exposes it through REST or GraphQL.
React, Vue, Next.js, Nuxt, Flutter, mini apps and smart devices can consume the same source.
Frontend rendering and deployment evolve independently from the CMS.

A traditional CMS tends to couple content management with page templates. Strapi focuses on content and APIs. A useful mental model is: a backend starter with visual modeling, an admin application and content-aware permissions already included.

A comparison caveat: Strapi is not a peer of Java, Go or Python. It is a product and framework; the others are languages and ecosystems. The meaningful comparison is Strapi against Spring Boot, Go web frameworks, and Django/DRF or FastAPI.

2. Core characteristics

Capability	What it gives you	Caveat
Visual content modeling	Fields, relations, components and dynamic zones in Content-Type Builder	Complex domains still require deliberate engineering
Generated REST API	CRUD endpoints appear with the content type	New content types are private by default
GraphQL support	A plugin generates queries and mutations from the model	Query depth and cost must be controlled
Full admin application	Editing, media, draft/publish and localization workflows	Deep Admin customization is React development
Extensible backend	Routes, policies, middleware, controllers, services and lifecycle logic	More custom logic calls for more tests and layering
SQL database options	SQLite, PostgreSQL, MySQL and MariaDB	Strapi 5 does not support MongoDB or taking over arbitrary existing databases
API security	Public/authenticated roles, API tokens and action permissions	Rate limits, auditing and secret management remain your responsibility
Cloud or self-hosting	Keep control of code and data, or use Strapi Cloud	Self-hosting means owning upgrades, backups and observability

Strapi’s central advantage is not record-breaking throughput. It is delivering a recurring bundle in one system:

database model + CRUD API + content admin + permissions + media + publishing workflow.

3. The technology stack

Layer	Main technology	Responsibility
Runtime	Node.js	Runs the JavaScript/TypeScript backend; strong for I/O-heavy work
Application code	TypeScript or JavaScript	Configuration, controllers, services, policies and plugins
HTTP layer	Koa ecosystem and Strapi routing	Request handling and middleware execution
Admin	React + Strapi Design System	Content and system management UI
Content data access	Document Service / Query Engine	Documents, locales, draft/publish state and relations
SQL abstraction	Knex	SQLite, PostgreSQL and MySQL-family connections
Delivery API	REST; optional GraphQL plugin	Delivers content to consumers
Extensions	Plugins, providers, middleware, policies and lifecycle hooks	Storage, email, auth and business rules

The Document concept matters in Strapi 5. One logical article may have draft and published variants in several locales. A documentId groups those variants, so the single-document REST route is:

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

not the numeric-ID route shown in many Strapi v4 tutorials. Strapi 5 also flattened REST responses: content fields sit directly on data, rather than under data.attributes.

4. How does Strapi generate an API?

Strapi follows a Content Model First approach. Describe the content structure once, and the framework assembles the database representation, Admin forms and delivery APIs around it.

Suppose we create an Article collection type:

Field	Type	Constraint
`title`	Short text	Required
`slug`	UID	Unique, based on title
`summary`	Long text	Optional
`content`	Blocks / rich text	Body
`cover`	Media	Single image
`author`	Relation	Many articles to one author
`featured`	Boolean	Defaults to false

When the model is saved, Strapi:

persists the model as a project schema;
synchronizes tables, columns and relations;
creates Admin list and edit screens;
registers core controllers and services;
registers REST CRUD routes under /api/articles;
adds the model to GraphQL when the plugin is installed.

Operation	Method and path
List	`GET /api/articles`
Retrieve one	`GET /api/articles/:documentId`
Create	`POST /api/articles`
Update	`PUT /api/articles/:documentId`
Delete	`DELETE /api/articles/:documentId`

4.1 Build the first API

1
2
3

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

Open http://localhost:1337/admin, create the administrator account, then define Article in Content-Type Builder.

New content types are private by default. You may grant only find and findOne to the Public role, or create an API token for a trusted server. In production, scoped tokens are generally preferable to public write endpoints.

Fetch published articles:

1
2

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

Filter articles and explicitly populate their cover and author:

1
2

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

Create a document by wrapping business fields in 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
    }
  }'

A Strapi 5 list response has this shape:

{
  "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
    }
  }
}

Relations, media, components and dynamic zones are not populated by default. Avoid blindly using populate=* in production. Select fields and relations intentionally to control payload size and database cost.

4.2 When generated CRUD is not enough

Strapi does not lock you into generated behavior. A custom GET /api/articles/featured endpoint can be implemented with a route, controller and service:

// 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,
      });
    },
  })
);

The controller does not need to build SQL directly. Requests move through a layered pipeline:

Route selects the method, path and handler.
Middleware handles logging, CORS, rate limiting and request transformations.
Policy authorizes the current identity for the action.
Controller interprets the HTTP context and shapes the response.
Service owns reusable business logic.
Document Service applies Strapi’s document, locale and publication semantics.
Database / Knex finally accesses the relational database.

This resembles controller/service/repository layering in Spring or Django. The difference is how much default behavior Strapi has already supplied.

5. Strapi vs Java, Go and Python backends

Dimension	Strapi (Node.js/TS)	Java (Spring Boot)	Go (Gin/Chi/Fiber)	Python (Django/DRF/FastAPI)
Starting point	Content model first; generated CRUD and Admin	Code and domain first; explicit layers	Code first; compose focused libraries	Django is batteries-included; DRF/FastAPI define APIs in code
First content API	Extremely fast	Slower, but strong engineering foundations	Fast, but admin, permissions and media are separate	Django + Admin is fast; FastAPI has no content admin
Admin UI	A first-class feature for content teams	Usually separate or purchased	Usually separate	Django Admin is strong; FastAPI has none by default
Type model	TypeScript checks; JavaScript runtime	Mature strong static typing	Simple static typing and fast compilation	Dynamic by default; type hints and Pydantic add checks
Concurrency	Event loop, effective for I/O-heavy APIs	Threads or virtual threads, mature runtime	Lightweight goroutines	Async handles I/O; CPU-heavy work needs care
Runtime profile	Good for content APIs, not optimized for maximum throughput	Stable throughput; higher JVM startup and memory cost	High throughput, low memory, simple binaries	Excellent iteration speed; peak throughput is rarely the main advantage
Transactions/domain	Possible, but CMS abstractions do not fit every transaction	A strength: transactions, DDD, messaging and enterprise integration	Explicit and controllable; more pieces are assembled manually	Django ORM is mature; complex systems still need layering
Best fit	CMS, marketing sites, catalogs and omnichannel content	Core transactions and large enterprise systems	Gateways, cloud services and infrastructure	Data/AI services, business apps and rapid APIs

Strapi vs Spring Boot

Spring Boot commonly starts with domain entities, DTOs, repositories, services and controllers. That means more code upfront, but it offers excellent control over complex transactions, messaging, audit requirements, strong contracts and large-team governance.

Strapi starts by handing you a working content platform. It can remove weeks of work for articles, authors, categories, media and localization. For settlement, inventory reservation, complex approvals or distributed business workflows, an explicit Java domain model is usually the safer center.

Strapi vs Go

Go services favor explicit dependencies, low runtime overhead and minimal deployment artifacts. They are an excellent fit for gateways, infrastructure and high-concurrency services.

Most Go frameworks do not include an editorial Admin, media library, draft publishing or granular content permissions. Strapi wins when content operations dominate; Go wins when resource efficiency, low latency and an intentionally small service are the primary goals.

Strapi vs Python

Django Admin plus Django REST Framework is the closest Python equivalent. Django is a general web framework whose Admin is primarily an internal data-management interface. Strapi begins from structured content, editor experience and multichannel delivery.

FastAPI is lighter and excellent for typed APIs, data products and AI services, but it does not automatically become a complete CMS.

6. When should you choose Strapi?

Strong fits

Corporate, marketing, news and editorial websites
Multilingual or multi-brand content shared across channels
Websites, apps and mini programs sharing campaigns, banners and articles
Product catalogs, case studies, documentation and help centers
Frontend teams that need a usable backend while editors need autonomy
MVPs dominated by CRUD and content workflow requirements

Use caution

Ledgers, payments, matching engines and other transaction-heavy cores
Systems that must take over a large pre-existing database
CPU-heavy computation, extreme low latency or maximum-throughput services
APIs dominated by complex commands and cross-domain orchestration
Teams with no Node.js/TypeScript operational experience

A practical architecture is often:

Strapi for content and editorial configuration
        +
Java / Go / Python for core business capabilities
        +
an API Gateway or BFF for a stable client contract

Strapi can be the content service without becoming the entire backend.

7. Production checklist

Use PostgreSQL or MySQL for most production deployments; keep SQLite for local and genuinely small use cases.
Apply least privilege. Do not make write endpoints public; scope API tokens by consumer.
Select populate and fields explicitly to avoid query explosions and oversized JSON.
Put business rules in services, HTTP concerns in controllers, and authorization in policies.
Evolve models in development and ship schemas through Git and a controlled deployment process.
Use object storage and a CDN for media in multi-instance deployments.
Add caching and observability: measure slow queries, error rates and event-loop delay.
Read migration notes before upgrading, especially when using plugins or a customized Admin.

Conclusion

The most useful definition of Strapi is not “a low-code backend,” but:

A structured-content framework that generates an Admin and APIs while still letting you write ordinary Node.js/TypeScript backend code.

Its conventions and automation make content-centric delivery exceptionally fast. General Java, Go and Python stacks spend more explicit code to gain broader domain control, different performance profiles or specialized ecosystems.

If the central problem is managing and distributing content, consider Strapi first.
If it is complex transactions, extreme efficiency or specialized computation, start with Java, Go or Python.
If both problems exist, let Strapi own content and collaborate with the core business backend.

References

This article reflects the Strapi 5 documentation available in July 2026. Commands, runtime requirements and plugin behavior can change; check the documentation for the exact version you deploy.

API on Snow

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

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

一、FastAPI 解决的核心问题

二、环境准备

三、第一个可运行 API

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

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

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

七、项目变大后怎么拆

八、async def 不等于自动更快

九、错误处理与状态码

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

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

十二、常见坑

十三、学习路线

参考资料

How Token Counting Works: How AI Providers and API Proxies Track Usage

How Token Counting Works: How AI Providers and API Proxies Track Usage

1. What a token is

2. Why billing is token-based

3. What gets counted in a request

4. How providers count tokens

5. Streaming usage

6. How API proxy platforms track usage

Pre-request estimate

Post-request settlement

Usage ledger

7. Why proxy counts can differ from official counts

8. Context windows and maximum output

9. Cached tokens

10. Where token cost grows

11. Estimating tokens yourself

12. Engineering notes for proxy billing

13. Reducing token cost

Summary

Strapi Explained: From Headless CMS to Customizable Node.js API Backend

Strapi Explained: From Headless CMS to Customizable Node.js API Backend

1. What is Strapi?

2. Core characteristics

3. The technology stack

4. How does Strapi generate an API?

4.1 Build the first API

4.2 When generated CRUD is not enough

5. Strapi vs Java, Go and Python backends

Strapi vs Spring Boot

Strapi vs Go

Strapi vs Python

6. When should you choose Strapi?

Strong fits

Use caution

7. Production checklist

Conclusion

References

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