@skyroc/service

┌─────────────────────────────────────────────────────────┐
│  业务层 (React 组件 / hooks)                              │
│  useQuery / useMutation / request(...)                   │
└──────────────────────┬──────────────────────────────────┘
                       │
         ┌─────────────▼────────────────┐
         │      @skyroc/service         │
         │                              │
         │  createAppRequest            │
         │    ├─ normalizeCodes         │
         │    ├─ isBackendSuccess       │
         │    ├─ onRequest              │
         │    │    ├─ 注入 Authorization │
         │    │    └─ sealRequest (加密) │
         │    ├─ onBackendFail          │
         │    │    ├─ logout 码 → 登出   │
         │    │    ├─ modalLogout → 弹窗 │
         │    │    └─ expiredToken → 刷新│
         │    └─ onError (去重展示)      │
         │                              │
         │  createQueryClient           │
         │    ├─ DEFAULT_QUERY_CONFIG   │
         │    └─ DEFAULT_MUTATION_CONFIG│
         └──────────────┬───────────────┘
                        │
         ┌──────────────▼───────────────┐
         │      @skyroc/axios           │
         │  createRequest / Axios       │
         └──────────────────────────────┘

import type { RequestAdapter } from '@skyroc/service';

const adapter: RequestAdapter = {
  // 必填：用来识别「拿到过期码的是续签请求自己」，必须和 fetchRefreshToken 实际请求的 url 一致
  refreshTokenUrl: '/auth/refreshToken',
  getToken: () => localStorage.getItem('token'),
  getRefreshToken: () => localStorage.getItem('refreshToken'),
  setAuth: ({ token, refreshToken }) => {
    localStorage.setItem('token', token);
    localStorage.setItem('refreshToken', refreshToken);
  },
  resetAuth: () => {
    localStorage.removeItem('token');
    localStorage.removeItem('refreshToken');
  },
  getCurrentPath: () => window.location.pathname,
  redirectToLogin: redirectPath => {
    window.location.href = `/login?redirect=${redirectPath}`;
  },
  showErrorMessage: (msg, onClose) => {
    message.error({ content: msg, onClose });
  },
  showErrorModal: ({ title, content, onConfirm, maskClosable }) => {
    Modal.error({ title, content, onOk: onConfirm, maskClosable });
  },
  t: key => i18n.t(key),
  fetchRefreshToken: async refreshToken => {
    const res = await fetch('/api/auth/refreshToken', {
      method: 'POST',
      body: JSON.stringify({ refreshToken }),
      headers: { 'Content-Type': 'application/json' }
    });
    return res.json();
  }
};

import { createAppRequest } from '@skyroc/service';

export const request = createAppRequest({
  adapter,
  codes: {
    success: '0000',
    logout: ['8888'],
    modalLogout: ['7777'],
    expiredToken: ['9999']
  },
  axiosConfig: {
    baseURL: import.meta.env.VITE_API_BASE_URL
  },
  // 可选：只有标了 encrypt: true 的接口才会用到
  crypto: {
    header: 'X-Api-Key',
    publicKey: import.meta.env.VITE_API_CRYPTO_PUBLIC_KEY
  }
});

import { createQueryClient } from '@skyroc/service/query';

export const queryClient = createQueryClient({
  queryCache: {
    onError: error => console.error('Query error:', error)
  }
});

import { QueryClientProvider } from '@tanstack/react-query';

const App = () => (
  <QueryClientProvider client={queryClient}>
    <Router />
  </QueryClientProvider>
);

// API 定义
function fetchUsers(params: Api.UserListParams) {
  return request<Api.UserList>({ url: '/api/users', params });
}

// Hook
function useUsers(params: Api.UserListParams) {
  return useQuery({
    queryKey: ['users', params],
    queryFn: () => fetchUsers(params)
  });
}

function createAppRequest(options: CreateRequestOptions): RequestInstance;

interface CreateRequestOptions {
  /** 平台适配器 */
  adapter: RequestAdapter;
  /** Axios 基础配置 */
  axiosConfig?: CreateAxiosDefaults;
  /** 后端业务状态码 */
  codes: ServiceCodes;
  /** 接口传输加密。不配也能跑，但标了 `encrypt: true` 的请求会直接抛错 */
  crypto?: ApiCryptoOptions;
  /** 自定义后端成功判断（默认：String(response.data.code) === codes.success） */
  isBackendSuccess?: (response: { data: { code: string | number } }) => boolean;
  /** 自定义响应数据转换（默认：response.data.data） */
  transform?: (response: any) => any;
}

function createQueryClient(options?: CreateQueryClientOptions): QueryClient;

interface CreateQueryClientOptions {
  /** 覆盖默认 defaultOptions（会与内置默认值浅合并） */
  defaultOptions?: DefaultOptions;
  /** MutationCache 配置（onError / onSuccess / onSettled / onMutate） */
  mutationCache?: MutationCacheConfig;
  /** QueryCache 配置（onError / onSuccess / onSettled） */
  queryCache?: QueryCacheConfig;
}

interface ServiceCodes {
  /** 请求成功的状态码 */
  success: string;
  /** 需要登出的状态码 */
  logout: string[];
  /** 需要弹窗确认后登出的状态码 */
  modalLogout: string[];
  /** Token 过期需要刷新的状态码 */
  expiredToken: string[];
}

后端返回 response
    │
    ▼
isBackendSuccess? ──── Yes ──► transform(response) → 返回数据
    │
    No
    ▼
┌─ onBackendFail ──────────────────────────────────────────────┐
│                                                               │
│  logout 码?       → showErrorMessage + resetAuth + 跳登录页    │
│  modalLogout 码?  → showErrorModal → onConfirm → 登出         │
│  expiredToken 码? → 刷新 Token → 重试原请求（两道防重入闸门）   │
│  其他             → 返回 null → 进入 onError                  │
│                                                               │
└───────────────────────────────────────────────────────────────┘
    │
    ▼
onError → 登出 / 弹窗登出 / 过期码 → 静默（提示已由上一步给过或正在重试）
       → 其他 → showErrorMsg（去重展示）

codes: {
  logout: ['8888'];
}
// 后端返回 code: '8888' → adapter.showErrorMessage → adapter.resetAuth → adapter.redirectToLogin

codes: {
  modalLogout: ['7777'];
}
// 后端返回 code: '7777' → 调用 adapter.showErrorModal → 用户确认 → 登出

codes: {
  expiredToken: ['9999'];
}
// 后端返回 code: '9999' → fetchRefreshToken → setAuth → 带新 Token 重试

请求 A ─┐                      ┌─ 带新 Token 重试 A
请求 B ─┤  共享同一个            ├─ 带新 Token 重试 B
请求 C ─┤  模块级 inFlight       ├─ 带新 Token 重试 C
        └──────────────────────┘
                  │
     1 秒复用窗口过后清空，下次过期重新刷新

showErrorMsg("网络异常")  → 展示 ✅
showErrorMsg("网络异常")  → 跳过（栈中已存在）
       ↓ 用户关闭消息（adapter 回调 onClose）
showErrorMsg("网络异常")  → 展示 ✅（已从栈移除）

await request({ url: '/auth/login', method: 'post', data: { userName, password }, encrypt: true });

密钥头  base64( RSA-OAEP-SHA256(服务端公钥, aesKey) )
body    base64( nonce(12B) ‖ AES-256-GCM(aesKey, 明文) ‖ tag(16B) )

import { importPublicKey, seal } from '@skyroc/service';

const key = importPublicKey(pem); // PEM 可以是多行原文，也可以是 env 里的单行 \n 形式
const { body, sealedKey } = seal(plaintext, key); // 每次都换新的 AES 密钥和 nonce

const queryClient = createQueryClient({
  defaultOptions: {
    queries: { staleTime: 60_000, retry: 3 },
    mutations: { retry: 2 }
  }
});

# 从 monorepo 根目录
npx vitest run packages/@core/service/__tests__

# 或在包目录内
cd packages/@core/service && pnpm test

# 含覆盖率报告
pnpm test --coverage