bricks/aidocs/jsoncall.md

Bricks HTTP 模块技术文档

本模块为 bricks 前端框架提供了一套完整的 HTTP 请求处理工具集，支持多种响应类型（文本、JSON、二进制流等），并封装了自动参数注入、错误处理、会话管理与登录重定向等功能。

---

目录

• 概述
• 核心功能
• 公共函数
• 基类：HttpText
• 派生类
  • HttpArrayBuffer
  • HttpBin
  • HttpResponse
  • HttpResponseStream
  • HttpRaw
  • HttpJson
• 快捷方法
• 使用示例

---

概述

bricks.Http* 系列类基于 fetch API 构建，旨在统一前端网络请求行为。主要特性包括：

• 自动附加设备信息和会话参数
• 支持 GET/POST 请求及 FormData 或 JSON 数据格式
• 统一的错误提示机制（401、403、其他错误）
• 可扩展的响应处理器（文本、JSON、流式解析等）
• 登录拦截与跳转支持（待完善）

该模块适用于 Web 应用中需要与后端服务交互的所有场景。

---

核心功能

功能	描述
参数合并	自动注入 _webbricks_, 屏幕宽高, 移动端标识等参数
会话管理	从响应头读取 Set-Cookie 并保存会话；发送时自动携带
错误处理	对 401、403 和非 OK 状态码进行统一 UI 提示
登录重定向	当返回 401 且存在 login_url 时触发登录流程（目前未完全实现）
流式响应处理	支持逐行处理 chunked 响应数据（如 Server-Sent Events）

---

公共函数

url_params(data)

将对象转换为 URL 查询字符串。

参数

• data: {[key: string]: any} — 要编码的对象

返回值

• string — 格式化后的查询字符串（例如 "a=1&b=2"）

示例

url_params({a: 1, b: 'hello'}) // → "a=1&b=hello"

⚠️ 所有值都会通过 encodeURIComponent 编码。

---

基类：HttpText

所有 HTTP 客户端类的基类。

构造函数 constructor(headers?)

参数

• headers?: {[key: string]: string} — 自定义请求头，默认为 { Accept: "text/html" }

行为说明

• 若未传入 headers，默认使用：

  { "Accept": "text/html" }
  

• 使用 bricks.extend() 合并默认头与用户头。
• 自动收集以下上下文参数作为请求参数：
  • _webbricks_: 固定值 1
  • width: 屏幕宽度（来自 bricks.app.screenWidth()）
  • height: 屏幕高度（来自 bricks.app.screenHeight()）
  • _is_mobile: 是否为移动端（'1' 或 '0'）

✅ 这些参数会在每次请求中自动附加。

方法

url_parse(url)

解析 URL 中的查询参数，并将其合并到内部 this.params 中。

参数

• url: string — 原始 URL（含 query）

返回值

• string — 清除 query 的基础 URL

示例

const client = new bricks.HttpText();
client.url_parse("/api/data?a=1&b=2");
// 结果：client.params 包含 a=1, b=2
// 返回 "/api/data"

add_own_params(params)

合并用户参数与内部参数（包括 session）。

参数

• params: Object | FormData | null

返回值

• Object | FormData — 合并后的参数对象

行为逻辑

• 如果是 FormData，直接追加键值对
• 否则创建新对象，合并 this.params 和 params
• 若存在 bricks.app.get_session()，额外添加 session 字段

add_own_headers(headers)

合并自定义请求头与实例默认头。

参数

• headers: {[key: string]: string} | null

返回值

• Object — 合并后的 headers

使用 Object.assign(this.headers, headers) 实现浅合并。

async bricks_fetch(url, {method, headers, params})

底层 fetch 封装，负责构建最终请求选项。

参数

• url: string — 请求地址
• method: 'GET'|'POST'|'HEAD'|... — HTTP 方法（默认 'GET'）
• headers: Object — 请求头
• params: Object|FormData — 请求参数

处理逻辑

条件	行为
params instanceof FormData	强制设为 POST，body = params
GET/HEAD 请求	将 params 转为 query string 拼接到 URL
其他方法（如 POST）	body = JSON.stringify(params)

返回值

• Response — fetch 返回的原生响应对象

async httpcall(url, opts)

高层封装，包含状态码判断与错误处理。

参数

• url: string
• opts: {method, headers, params}

流程

1. 调用 bricks_fetch 发起请求
2. 检查响应状态：
   • 401 且配置了 bricks.app.login_url → 触发 withLoginInfo
   • 403 → 显示“禁止访问”弹窗
   • 非 ok → 显示通用错误弹窗
3. 成功则调用 get_result_data() 获取结果
4. 解析 Set-Cookie 并调用 bricks.app.save_session(session) 保存会话

返回值

• string | null — 成功返回响应内容，失败返回 null

async withLoginInfo(url, params)

处理 401 时尝试重新登录（当前仅为占位实现）。

❗ 当前仅创建一个 urlwidget 加载登录页，未完成回调或重试逻辑。

async get_result_data(resp)

提取响应体数据的方法（可被子类覆盖）。

默认实现（HttpText）

return await resp.text();

---

派生类

HttpArrayBuffer

继承自 HttpText，用于下载二进制文件（如字体、模型等）。

重写方法

async get_result_data(resp) {
  return await resp.arrayBuffer();
}

---

HttpBin

继承自 HttpText，以 Blob 形式获取响应（适合图片、音频等）。

重写方法

async get_result_data(resp) {
  return await resp.blob();
}

---

HttpResponse

继承自 HttpText，直接返回原始 Response 对象。

重写方法

async get_result_data(resp) {
  return resp;
}

✅ 适用于需手动处理 header 或 stream 的高级场景。

---

HttpResponseStream

继承自 HttpResponse，专用于处理流式响应（如 SSE）。

方法：async handle_chunk(resp, handler)

逐行解析 chunked 文本流，并调用 handler(line)。

参数

• resp: Response — fetch 返回的响应对象
• handler: (line: string) => void — 每一行数据的处理器

实现细节

• 使用 ReadableStream.getReader() + TextDecoder
• 按 \n 分割缓冲区，确保跨 chunk 边界正确切分
• 最终剩余内容也会传递给 handler

示例用法

const streamClient = new bricks.HttpResponseStream();
const resp = await streamClient.get('/stream-endpoint');
await streamClient.handle_chunk(resp, (line) => {
  console.log('Received:', line);
});

---

HttpRaw

与 HttpBin 相同，返回 Blob。

⚠️ 注释中可能表示未来用途不同，但当前实现与 HttpBin 完全一致。

---

HttpJson

专用于 JSON 接口通信，设置默认 Accept 头并解析 JSON 响应。

构造函数增强

this.headers = { "Accept": "application/json" };
bricks.extend(this.headers, headers); // 用户头可覆盖

重写方法

async get_result_data(resp) {
  return await resp.json();
}

✅ 推荐用于 RESTful API 调用。

---

快捷方法

模块末尾导出多个常用快捷函数，绑定到全局命名空间：

变量名	类型	说明
bricks.hc	new HttpText()	文本客户端实例
bricks.tget	Function	hc.get 的绑定方法（GET 文本）
bricks.tpost	Function	hc.post 的绑定方法（POST 文本）
bricks.jc	new HttpJson()	JSON 客户端实例
bricks.jcall	Function	jc.httpcall 的绑定方法（调用 JSON 接口）
bricks.jget	Function	jc.get 的绑定方法（GET JSON）
bricks.jpost	Function	jc.post 的绑定方法（POST JSON）

示例

// 获取 HTML 内容
const html = await bricks.tget('/page', { params: { id: 123 } });

// 调用 JSON 接口
const data = await bricks.jpost('/api/user', {
  headers: { 'X-Token': 'abc' },
  params: { name: 'Alice' }
});

---

使用示例

1. 发送普通 GET 请求

const client = new bricks.HttpText();
const result = await client.get('/api/hello', {
  params: { q: 'test' }
});
console.log(result); // 输出服务器返回的文本

2. 发送 JSON POST 请求

const jsonClient = new bricks.HttpJson();
const user = await jsonClient.post('/api/users', {
  params: { name: 'Bob', age: 30 }
});
// 自动设置 Content-Type 和 Accept，并解析 JSON

3. 下载文件为 ArrayBuffer

const bufferClient = new bricks.HttpArrayBuffer();
const resp = await bufferClient.get('/model.bin');
const arrayBuf = await resp; // 已是 arrayBuffer

4. 处理实时日志流

const streamClient = new bricks.HttpResponseStream();
const resp = await streamClient.get('/logs/stream');
await streamClient.handle_chunk(resp, (line) => {
  console.log('[LOG]', line);
});

---

注意事项

• 依赖 bricks.app 提供 screenWidth(), screenHeight(), get_session(), save_session() 等方法
• 依赖 bricks.extend(obj, src) 实现对象合并（类似 jQuery.extend）
• objget(headers, 'Set-Cookie') 用于安全获取响应头（需外部定义）
• 登录流程尚未完整实现，withLoginInfo 仅为原型

---

待优化建议

问题	建议改进
bufffer 拼写错误	修复 if (buffer != ''){ yield bufffer; } 中的拼写
withLoginInfo 无实际登录能力	应支持模态框输入并回调重试请求
handle_chunk 正则 /\\r?\\n/gm 不必要	可简化为 .split('\n')
bricks_fetch 中 method = 'POST' 修改外层变量风险	应使用局部变量

---

版本信息

• 创建时间：未知
• 框架版本：Bricks Framework v1.x+
• 作者：Bricks Team

文档最后更新：2025年4月5日