错误、空结果与重试

把不可用、无内容和无权限区分开，保留用户输入。

公开读取错误

ArticleSDK详情仅404返回null；列表故障抛错。SiteSDK校验业务信封与公开形状，不把错误响应当作配置。I18nSDK故障由应用显示内置文案和重试。

TypeScript

import type { Shell } from '@mosaic-base/shell';
import type { ArticleSDK, SiteSDK, I18nSDK } from '@mosaic-base/client-sdk';
import type { AuthClient, ServerAuthClient } from '@mosaic-base/auth-sdk';
// Declare once in your application's type contract, never import SDK implementations.
declare module '@mosaic-base/shell/contracts' {
  interface SdkRegistry {
    'site.config': Pick<SiteSDK, 'getConfig'>;
    'content.articles': Pick<ArticleSDK, 'list' | 'getBySlug' | 'getPreview' | 'search'>;
    'i18n.messages': Pick<I18nSDK, 'load' | 't' | 'clearCache' | 'refresh'>;
    'auth.client': AuthClient | ServerAuthClient;
  }
}

export async function loadWithFeedback(shell: Shell) {
  try {
    const articles = await shell.getSdk('content.articles');
    const result = await articles.list({ language: 'en-US' });
    return { state: result.items.length ? 'ready' : 'empty', articles: result.items };
  } catch { return { state: 'unavailable', message: 'Reload to try again.' }; }
}

身份与权限错误

401需要重新确认或恢复登录；403说明当前身份不满足资源策略或权限，不要通过放宽Guard修复。AuthSDK返回data/error，对失败先检查error再使用data。

写入重试与诊断

失败时保留表单，显示明确状态并释放提交按钮。写请求是否成功不确定时先重新读取状态；自动重试必须有幂等设计。记录请求阶段、HTTP/业务码和requestId，不记录令牌、Cookie或密钥。

Mosaic Base / 开发者文档

错误、空结果与重试

把不可用、无内容和无权限区分开，保留用户输入。

公开读取错误

ArticleSDK详情仅404返回null；列表故障抛错。SiteSDK校验业务信封与公开形状，不把错误响应当作配置。I18nSDK故障由应用显示内置文案和重试。

TypeScript

import type { Shell } from '@mosaic-base/shell';
import type { ArticleSDK, SiteSDK, I18nSDK } from '@mosaic-base/client-sdk';
import type { AuthClient, ServerAuthClient } from '@mosaic-base/auth-sdk';
// Declare once in your application's type contract, never import SDK implementations.
declare module '@mosaic-base/shell/contracts' {
  interface SdkRegistry {
    'site.config': Pick<SiteSDK, 'getConfig'>;
    'content.articles': Pick<ArticleSDK, 'list' | 'getBySlug' | 'getPreview' | 'search'>;
    'i18n.messages': Pick<I18nSDK, 'load' | 't' | 'clearCache' | 'refresh'>;
    'auth.client': AuthClient | ServerAuthClient;
  }
}

export async function loadWithFeedback(shell: Shell) {
  try {
    const articles = await shell.getSdk('content.articles');
    const result = await articles.list({ language: 'en-US' });
    return { state: result.items.length ? 'ready' : 'empty', articles: result.items };
  } catch { return { state: 'unavailable', message: 'Reload to try again.' }; }
}

身份与权限错误

401需要重新确认或恢复登录；403说明当前身份不满足资源策略或权限，不要通过放宽Guard修复。AuthSDK返回data/error，对失败先检查error再使用data。