# web 请求上下文

## 功能

Web 服务运行时会向脚本注入 web 对象。web 对象由请求数据字段和响应控制函数组成，具体结构见下方表格及对应 API 页面。

如何开启 Web 服务请阅读： [Web 服务](/docs/net/web)

## 请求数据

| API | 说明 |
| ------ | ------ |
| [web.get](/docs/web/get) | 读取 URL 查询参数对象。 |
| [web.post](/docs/web/post) | 读取表单 POST 字段对象。 |
| [web.cookie](/docs/web/cookie) | 读取请求 Cookie 对象，也用于请求结束后写回 Cookie 状态。 |
| [web.session](/docs/web/session) | 读取并保存当前请求 Session 对象。 |
| [web.files](/docs/web/files) | 读取上传文件对象。 |
| [web.server](/docs/web/server) | 读取请求和服务器信息。 |
| [web.url](/docs/web/url) | 读取当前请求路径。 |
| [web.method](/docs/web/method) | 读取当前 HTTP 请求方法。 |

## 请求对象概览

| API | 类型 | 结构 |
| ------ | ------ | ------ |
| web.get | Object | 查询参数名 -> String。 |
| web.post | Object | 表单字段名 -> String/Array。 |
| web.cookie | Object | Cookie 名称 -> String，并在请求结束时写回响应 Cookie。 |
| web.session | Object | Session 键名 -> JSON 可序列化值。 |
| web.files | Object | 上传字段名 -> 文件信息对象数组；文件信息字段见 [web.files](/docs/web/files)。 |
| web.server | Object | method、version、scheme、headers、local_addr、remote_addr、ip、port。 |

## 响应控制

| API | 说明 |
| ------ | ------ |
| [web.header](/docs/web/header) | 设置一个或一组响应头。 |
| [web.status_code](/docs/web/status_code) | 设置 HTTP 响应状态码。 |
| [web.redirect](/docs/web/redirect) | 设置 HTTP 重定向地址。 |
| [web.send_file](/docs/web/send_file) | 直接发送本地文件，适合大响应下载。 |

## 阻塞 API 策略

Web 请求脚本会整体进入 BT 进程级 blocking pool 执行，避免阻塞 Tokio Web worker。`sleep`、`fs`、`process`、`reqwest`、`mysql`、`task`、`device` 在 Web 请求中的允许和拒绝规则见：[Web 阻塞 API 策略](/docs/web/io-policy)。

## 资源边界

动态 Web 请求会检查请求体、Header、上传文件和动态响应体大小。请求或上传超限时返回 HTTP 413，并输出中文错误；动态响应体超限会中止本次响应写回。静态文件和 `web.send_file()` 文件直出由 Web 服务分块发送，不受 `BT_WEB_RESPONSE_BODY_LIMIT` 限制。

| 环境变量 | 默认值 | 说明 |
| ------ | ------ | ------ |
| BT_WEB_REQUEST_BODY_LIMIT | 16777216 | 请求体上限，单位字节，包含表单和 multipart 上传。 |
| BT_WEB_RESPONSE_BODY_LIMIT | 67108864 | BT 脚本动态响应体上限，单位字节。 |
| BT_WEB_HEADER_COUNT_LIMIT | 128 | 请求 Header 数量上限。 |
| BT_WEB_HEADER_BYTES_LIMIT | 65536 | 请求 Header 名和值累计字节上限。 |
| BT_WEB_UPLOAD_FILE_LIMIT | 33554432 | 单个上传文件大小上限，单位字节。 |

## 示例

```bt
name = web.get.name
web.header('Content-Type', 'text/plain; charset=utf-8')

// 输出：BT
echo(name)
```

## 注意事项

- web 对象只在 Web 请求执行期间存在。
- 响应控制状态会在脚本执行结束后统一写入 HTTP 响应。
- 上传文件会先经过请求体总上限，再经过单文件上限；大文件下载应优先使用静态文件或 `web.send_file()` 文件直出。
- 静态文件支持 ETag、Last-Modified、条件请求和 Range；静态缓存策略在 [net.listen Web 服务](/docs/net/web) 的 `static.cache_control` 中配置。
- `web.send_file()` 复用同一套文件响应能力，支持 ETag、Last-Modified、条件请求和 Range。