跳到主要内容

调用 API 接口

callApi​

通过 client.callApi 来调用 API 接口：

let ret = await client.callApi('接口名', {
    // 请求参数
})
提示

包括 callApi 在内，TSRPC 的所有方法都 不会 抛出异常，所以你总是 无需 catch() 或 try...catch... 。

ApiReturn​

callApi 是异步的，它的返回类型是 Promise<ApiReturn>，包含了成功和错误 2 种情况：

export interface ApiReturnSucc<Res> {
    isSucc: true;
    res: Res;
    err?: undefined;
}

export interface ApiReturnError {
    isSucc: false;
    res?: undefined;
    err: TsrpcError;
}

export type ApiReturn<Res> = ApiReturnSucc<Res> | ApiReturnError;

错误处理​

在 TSRPC 中：

  1. 所有方法都 不会抛出异常
    • 因此总是 无需 catch() 或 try...catch... ，规避了新手陷阱。
  2. 所有错误都 只需在一处处理
    • 根据 ret.isSucc 判断成功与否，成功则取响应 ret.res，失败则取错误 ret.err（包含了错误类型和详情信息）。
let ret = await client.callApi('Hello', {
    name: 'World'
});

// 处理错误，异常分支
if (!ret.isSucc) {
    alert('Error: ' + ret.err.message);
    return;
}

// 成功
alert('Success: ' + ret.res.reply);

取消请求​

在一些场景下你可能会需要中途取消 API 请求。例如使用 React、Vue 开发的单页面应用，希望在组件 unmount 后取消尚未返回的 API 请求。

TSRPC 有 3 种方式来处理取消，取消之后的请求，其调用方收到的 Promise 既不会 resolve 也不会 reject。

通过 SN 取消单个请求​

每次 callApi 后都会为本次请求生成一个唯一的请求序号 SN，通过 client.abort(SN) 即可取消指定序号的请求。 通过 client.lastSN 可以获得最后发出的请求序号，例如：

client.callApi('XXX', { ... }).then(ret => {
    // 如果请求被取消，则无论服务端是否返回，客户端都不会处理
    console.log('请求完成', ret)
});

// 调用 callApi 后立即记录 SN
let sn = client.lastSN;

// 1 秒后，如果请求仍未完成，则会被取消
setTimeout(()=>{
    client.abort(sn);
}, 1000)

通过 abortKey 取消多个请求​

callApi 可以的第 3 个参数是可选的配置项，其中包含 abortKey。 你可以在请求之初就事先指定一个 abortKey，然后调用 client.abortByKey(key) 来取消所有为指定 abortKey 且尚未结束的请求。（已完成的请求不受影响）

这对于前端组件化开发很有帮助，例如在组件内部 callApi 时总是指定 abortKey: 组件ID，然后在组件销毁时 client.abortByKey(组件ID)，即可实现组件销毁时自动取消内部未完成的请求，例如：

// 同一个 abortKey 可以影响多个请求
client.callApi('XXX', { ... }, { abortKey: 'MyAbortKey' }).then(ret => { ... });
client.callApi('XXX', { ... }, { abortKey: 'MyAbortKey' }).then(ret => { ... });
client.callApi('XXX', { ... }, { abortKey: 'MyAbortKey' }).then(ret => { ... });

// 1 秒后，取消那些尚未完成的请求
setTimeout(()=>{
    client.abortByKey('MyAbortKey');
}, 1000)

取消所有未完成的请求​

通过 abortAll() 来取消客户端下所有未完成的请求：

client.abortAll();

自定义工作流​

你可以通过 Flow 来自定义客户端工作流程，实现诸如 Session 和 Cookie、登录态和鉴权、Mock 等特性。