---
url: /docs/api/context.md
---
# 请求上下文与中间件

## 请求上下文

定义位于 `apps/api/lib/context.ts`，业务接口每次请求获得独立上下文。

| 字段                | 用途                                   |
| ------------------- | -------------------------------------- |
| `req`、`info`       | 原始请求与接口调用元信息               |
| `db`                | 实时数据库连接，默认选用               |
| `dbCached`          | 有查询缓存的连接，仅在允许旧数据时使用 |
| `user`、`session`   | 解析后的身份，未登录时为空             |
| `env`               | 已校验的环境配置                       |
| `res`、`resHeaders` | 特定响应处理所需的可选字段             |

Hono 上下文保存数据库和认证实例，并不提前声明一个没有赋值的用户。会话由 tRPC 上下文构造过程解析。

## 中间件顺序

线上入口先安装错误处理，再启用安全响应头、请求标识和日志，然后解析环境并创建数据库与认证实例，最后挂载业务路由。入口代码在 `apps/api/worker.ts`。

`protectedProcedure` 在执行业务逻辑前检查用户和会话，成功后提供非空类型。资源级权限检查仍在具体业务操作内执行。

## 请求标识与日志

请求标识由 `apps/api/lib/middleware.ts` 生成，排查时将客户端看到的标识与服务端日志对应。记录路径、耗时和错误类型即可；不记录认证 token、密码、完整支付凭据或用户文件正文。

## 缓存连接的限制

认证、成员权限、订阅、积分以及写入后立即读取统一用 `db`。Hyperdrive 查询缓存不会因为业务写入自动失效，前端重新请求也可能得到旧结果。只有明确允许短期旧数据的读取才选 `dbCached`。

本地数据库实现与线上驱动不同，业务层通过 `@repo/db` 的 `Database` 类型约束，避免依赖驱动私有字段。