错误与会话过期
处理请求失败、发送失败、令牌过期和渲染错误。
错误与会话过期
错误提示
操作失败时,聊天通过宿主的 attention 能力上报错误。默认实现不显示任何内容,需要接到你的 toast 组件上:
import { createChatHost } from "@openmaxai/chat-openmax/react";
const host = createChatHost({
baseUrl: "https://openmax.com",
wsUrl: "wss://openmax.com/ws",
auth: { mode: "token", getToken },
ports: {
attention: {
notify: (level, message) => toast[level](message), // 你的 toast 库
setUnreadSignal: (count) => setTitleBadge(count),
},
},
});
上面是接 OpenMax 的一行写法,连接那几项见接入 OpenMax。接自己的后台时用 @openmaxai/chat-sdk/react 的 createChatHost({ adapter, ports }),ports 写法相同。自定义宿主则把同样的对象传给 createLocalPorts 的 ports。
发送失败
失败的消息留在消息区,标记「发送失败」:
- 重试:用相同的 id 和内容重发;失败在上传环节时,先重新上传同一批文件。
- 删除:只在本地移除。
服务端内容过滤拦下消息时,发送能力应返回 { blocked: { refusalText } } 而不是抛错。消息会保留并附带说明和删除按钮,不提供重试。
卡片按钮的错误显示在卡片里,见交互卡片。
SDK 错误类型
| 错误 | 何时出现 | 从哪引入 |
|---|---|---|
ChatSdkConfigError |
createChatHost 的构造参数不合法时同步抛出(例如接 OpenMax 时缺 baseUrl、既没有 wsUrl 也没有 realtime: "off"、auth.mode 不支持) |
@openmaxai/chat-sdk |
ChatSdkError |
适配器的调用失败,带种类 kind、retryable,以及后端的 status、code |
@openmaxai/chat-sdk |
ChatSdkRequestError |
OpenMax 的 REST 请求失败;ChatSdkError 的子类,kind 由 HTTP 状态推出 |
@openmaxai/chat-openmax |
种类、字段和判别函数 isChatSdkError 见 @openmaxai/chat-sdk · 错误;OpenMax 的状态码怎么推出种类、getToken() 失败时的 code("token_unavailable")、还不是 ChatSdkRequestError 的两种情况,见 @openmaxai/chat-openmax · 错误。message 是给用户看的一句话:组件原样提示非空的 message;为空串时用组件自己的文案(建群等群管理写操作按 kind 取,其余用这次操作的兜底句)。@openmaxai/chat-openmax 只在认得后端 code 时给出这句话,后端原文只在 cause 里。
useChatSdkConversationList() 返回最近一次的 error 和 refetch,可用来给会话列表加提示和重试。这个 error、以及 host.openConversation 失败时的 error 一定是 ChatSdkError:适配器抛的不是它时,SDK 经 toChatSdkError 换成它(断网的 TypeError 为 network,AbortError 为 cancelled,TimeoutError 为 timeout,其余为 unknown),原错误在 cause。只有这两处;MessageThreadNext 内部读消息的错误仍是原样的。换法见 @openmaxai/chat-sdk · 错误 · toChatSdkError。
统一错误
按种类给自己的界面分支时,用 isChatSdkError 判,不要用 instanceof;别处接到的错误也想按种类处理,先用 toChatSdkError 换一下:
import { isChatSdkError } from "@openmaxai/chat-sdk";
function describe(error: unknown) {
if (isChatSdkError(error) && error.kind === "network") return "网络连接失败";
return "出错了";
}
会话过期
SDK 不会自行刷新令牌,流程如下:
- 第一个需要令牌的请求调用
getToken(),结果缓存。 - 遇到
401再调一次getToken({ refresh: true })(这时要真去续期),用新令牌重发一次。同时(或先后)被拒的多个请求只续一次。getToken回{ token, expiresAt }时,令牌在到期前就续,且只有code为AUTH_TOKEN_EXPIRED的401才续;其它401不续,直接走第 3 步(见接入 OpenMax · 令牌与过期)。 - 重试后仍是
401,请求以ChatSdkRequestError(status: 401)失败。 - WebSocket 用同一令牌换一次性票据,换票遇
401同样先续期、再换一次。续期后仍被拒或getToken()以凭据失效失败,就不再重连;连接被服务端以凭据失效关闭(如个人 API Key 被吊销)也不再重连,同样算会话过期。用户重新登录后请新建 host。换票遇403(凭据有效但不许换票,如个人 API Key 没勾对应权限)也不再重连,但不续期、不算会话过期。 - 续期接口断网、超时时凭据可能还好:
getToken()抛kind为network的ChatSdkError,请求就以network失败,不算会话过期,实时照常退避重连,下一次401再续。抛普通Error或返回空串才是unauthorized。
所以续期和跳转登录都放在 getToken() 里:
import { ChatSdkError } from "@openmaxai/chat-sdk";
import { createChatHost } from "@openmaxai/chat-openmax/react";
const host = createChatHost({
baseUrl: "https://openmax.com",
wsUrl: "wss://openmax.com/ws",
auth: {
mode: "token",
getToken: async ({ refresh } = {}) => {
// refresh 为 true:手上那张刚被 401 拒了,要真去续期
let token;
try {
token = refresh ? await session.renew() : await session.getFreshToken();
} catch (e) {
// 续期接口不可达:凭据可能还好,报 network(不算会话过期,下一次 401 再续)
if (isNetworkFailure(e)) throw new ChatSdkError("network", "renew failed", { cause: e });
throw e;
}
if (!token) {
redirectToLogin();
throw new Error("signed out");
}
return token;
},
},
});
续期失败(续不出令牌、或重发仍是 401)、或换票续期后仍被拒时(续期因网络没成不算,见第 5 条),SDK 经 attention.notify("error", …) 提示一次「登录已过期」,同时失败的几个请求只提示一次。上面的一行配置不收 onUnauthorized(已知缺口);要在这时跳转登录,改用 createChatHost({ adapter: createOpenMaxAdapter(config), onUnauthorized }),回调同样只调一次,见错误模型 · onUnauthorized。
身份相关请求(个人信息、会话成员)失败后 5 秒内不重试。个人信息加载前,自己发的消息会显示成别人的,加载后自动纠正。
渲染错误
规划中
聊天的每个区域自带一层错误边界:一个区域渲染时抛错,只有它换成兜底界面,其余区域照常,页面不会白屏。你不用自己包。
区域(ChatRenderErrorArea) |
包住什么 | 兜底界面 | 自动复位 |
|---|---|---|---|
conversation-list |
ConversationList |
「这部分暂时无法显示」和「重试」 | — |
header |
ChatHeader |
同上 | 换会话时 |
message-thread |
消息列表,不含输入框 | 同上 | 换会话时 |
message |
一条消息 | 气泡的位置显示「这条消息无法显示」,没有重试;同一会话的其他消息照常 | 这条消息的 content_version 变了时 |
composer |
输入框 | 「这部分暂时无法显示」和「重试」;草稿已经存进 drafts,重试后恢复 |
换会话时 |
info-panel |
ChatInfoPanel |
同 conversation-list |
换会话时 |
agent-runs |
AgentRunList、AgentRunPanel |
同 conversation-list |
换 Agent 时 |
- 重试是把这个区域重新挂载一次,仓库里已有的数据不重新请求。
- 只接住渲染时的错误。 点击、发送等操作的失败不经错误边界,照常走错误提示和各操作自己的回滚。
- 缺能力的抛错也接住(下一节),兜底界面相同;开发构建里另在控制台说明缺了哪项能力。
- 焦点: 出错时焦点在这个区域里的,移到「重试」按钮上;不在的,焦点不动。
- 你在外面再包一层自己的错误边界也可以,内置的先接住。
上报和自定义
src/app.tsx
<ChatProvider
host={host}
onRenderError={(error, { area, conversationId }) => {
reportError(error, { tags: { chatArea: area, conversationId } });
}}
renderErrorFallback={({ area, retry }) =>
area === "conversation-list" ? <MyListFallback onRetry={retry} /> : null
}
>
{children}
</ChatProvider>
ChatProvider 属性 |
类型 | 说明 |
|---|---|---|
onRenderError |
(error: unknown, info: { area: ChatRenderErrorArea; conversationId?: string }) => void |
任一区域接住错误时调用一次,用来上报。不要在里面抛错 |
renderErrorFallback |
(props: { area: ChatRenderErrorArea; error: unknown; retry: () => void }) => ReactNode |
换掉默认兜底界面。返回 null 用默认的。message 区域没有 retry,调用无效 |
兜底文案在 chat 命名空间:renderError.area(「这部分暂时无法显示」)、renderError.retry(「重试」)、renderError.message(「这条消息无法显示」)。
一定会抛的情况
下面这些是用法错误,渲染时直接抛,由上面的错误边界接住(错误信息指明缺什么):
- 渲染
ConversationList但没有conversations能力。 - 渲染
CreateGroupModal/ChatInfoPanel但没有groupManagement能力。 - 聊天组件不在
ChatProvider里。这一条错误边界接不住:边界本身在ChatProvider里,所以会冒到你的应用。
先修原因,见能力。
