web 请求上下文

web 请求上下文

AI 原文

web 请求上下文

功能

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

如何开启 Web 服务请阅读： Web 服务

请求数据

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

请求对象概览

API类型结构
web.getObject查询参数名 -> String。
web.postObject表单字段名 -> String/Array。
web.cookieObjectCookie 名称 -> String，并在请求结束时写回响应 Cookie。
web.sessionObjectSession 键名 -> JSON 可序列化值。
web.filesObject上传字段名 -> 文件信息对象数组；文件信息字段见 web.files。
web.serverObjectmethod、version、scheme、headers、local_addr、remote_addr、ip、port。

响应控制

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

阻塞 API 策略

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

资源边界

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

环境变量默认值说明
BT_WEB_REQUEST_BODY_LIMIT16777216请求体上限，单位字节，包含表单和 multipart 上传。
BT_WEB_RESPONSE_BODY_LIMIT67108864BT 脚本动态响应体上限，单位字节。
BT_WEB_HEADER_COUNT_LIMIT128请求 Header 数量上限。
BT_WEB_HEADER_BYTES_LIMIT65536请求 Header 名和值累计字节上限。
BT_WEB_UPLOAD_FILE_LIMIT33554432单个上传文件大小上限，单位字节。

示例

注意事项

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