网络请求工具

Transport 是对浏览器 Fetch API 与 XMLHttpRequest 的轻量封装。使用它时，只需按“配置请求 → 注册回调 → 发送请求”的顺序编写，即可用统一方式处理数据、Cookie、上传和异常。

先了解一次请求的流程

1. GB.Transport()创建一条独立请求，并开始链式配置。

2. setUrl / setParam设置接口地址与需要提交的参数。

3. success / error / catch分别处理成功、HTTP 状态错误和网络异常。

4. get / post / put / delete最后调用请求方法，配置才会真正发送。

每次请求建议重新调用 GB.Transport() 创建实例，避免不同接口之间的参数、请求头或回调相互影响。

安装与引入

浏览器直接引入

在业务脚本之前引入文件，引入后可直接使用全局的 GB.Transport()。

<script src="https://cloud.m775.net/js/transport.js"></script>

npm 项目

npm i @gentbo/transport

import '@gentbo/transport';

最快可用的示例

下面的代码向登录接口发送 JSON 数据，并在成功、失败和完成时分别处理结果。可以直接复制后替换 URL 与参数。

GB.Transport()
  .setUrl('/api/login')
  .setRequestType('JSON')
  .setParam({
    username: 'admin',
    password: '123456'
  })
  .success(response => {
    console.log('登录结果：', response.body);
  })
  .error((code, response) => {
    console.warn('接口返回错误状态：', code, response);
  })
  .catch(error => {
    console.error('网络或超时异常：', error);
  })
  .complete(() => {
    console.log('本次请求已结束');
  })
  .post();

选择请求方式

.get()读取数据。通常只需设置地址；需要传参时可先使用 .setParam()。

.post()创建或提交数据，是表单提交最常用的方式。

.put()更新已有数据，例如修改用户信息。

.delete()删除数据，例如按 ID 删除一条记录。

// 查询用户列表
GB.Transport().setUrl('/user/list').get();

// 删除指定用户
GB.Transport()
  .setUrl('/user/delete')
  .setParam({ id: 1 })
  .delete();

提交参数与数据格式

.setParam(object) 用于整体设置参数；如果只是补充一个字段，使用 .addParam(key, value) 更方便。

JSONapplication/json。适合大多数前后端接口，也是 API 请求的常用格式。

QUERYapplication/x-www-form-urlencoded。适合普通键值对表单数据。

FORMmultipart/form-data。上传文件时使用。

XMLtext/xml。用于需要 XML 协议的旧系统或特定接口。

GB.Transport()
  .setUrl('/user/create')
  .setRequestType('JSON')
  .setParam({ username: 'admin', age: 18 })
  .addParam('role', 'editor')
  .post();

响应格式可通过 .setResponseType('JSON') 指定。未设置时，响应格式默认跟随请求格式。

请求头、Cookie 与超时

.setHeader(object)一次设置多个请求头，例如鉴权 Token。Header 名称会自动转为大写。

.addHeader(key, value)添加一个请求头。

.autoCookie(mode)0 不发送、1 同源发送、2 跨域发送 Cookie。

.setCookie(object)设置 Cookie；也可用 .addCookie(key, value) 添加一个字段。

.setTimeout(seconds)设置超时时间，单位为秒；默认值为 30 秒。

GB.Transport()
  .setUrl('/api/profile')
  .setHeader({ Authorization: 'Bearer token' })
  .autoCookie(1)
  .setTimeout(15)
  .get();

文件上传

上传文件时，设置请求格式为 FORM，然后通过 .setFile() 传入文件对象。多个文件字段可使用 .addFile(name, file) 追加。

const image = document.querySelector('[name="image"]').files[0];

GB.Transport()
  .setUrl('/upload')
  .setRequestType('FORM')
  .setFile({ image })
  .success(response => {
    console.log('文件地址：', response.body);
  })
  .post();

如何处理返回结果

.before(data)请求发送前执行，适合显示加载状态或检查发送数据。

.success(response)服务端正常响应时执行，应从 response.body 读取业务数据。

.error(code, response)服务器返回 HTTP 错误状态时执行，例如 403、404、500。

.catch(error)网络不可用、请求超时等异常时执行。

.complete(response)无论成功或失败都会执行，适合关闭加载状态。

成功响应使用统一结构，因此业务代码通常只需要读取 body：

{
  header: {}, // 服务端响应头
  cookie: {}, // 解析后的 Cookie
  body: null  // 服务端返回的业务数据
}

Fetch 与 XHR 的选择

默认 type: 'auto'：异步请求自动使用 Fetch，同步请求自动使用 XMLHttpRequest。绝大多数业务保持默认即可；只有兼容旧接口或需要明确控制实现时才指定类型。

// 强制使用 Fetch
.type('fetch')

// 强制使用 XMLHttpRequest
.type('xhr')

// 同步请求仅支持 XMLHttpRequest
.async(false)