query 增加了自处理异常

AICONTEXT.md

@@ -1,166 +0,0 @@
-# @simcu/simapi — AI 开发指南
-
-> 面向 AI Agent 的代码结构说明，帮助理解、修改和扩展本库。
-
----
-
-## 项目结构
-
-```
-simapi-vue/
-├── src/
-│   ├── types.ts          # 类型定义，全部导出
-│   ├── simapi.core.ts    # 核心类 SimApiCore，零框架依赖
-│   └── simapi.pinia.ts   # Pinia Store，Vue3 适配层
-├── dist/                  # 构建产物
-├── package.json           # exports: "." → core, "/pinia" → vue
-├── vite.config.ts         # 统一构建配置，生成 .mjs 和 .cjs
-└── tsconfig.build.json    # tsc 生成类型声明
-```
-
----
-
-## 核心类型（types.ts）
-
-```typescript
-SimApiBaseResponse<T>     // 标准响应 { code, message, data? }
-SimApiOptions             // configure() 入参 { debug?, auth?, api? }
-SimApiAuthConfig          // auth: { token_name, check_url, logout_url, login_url }
-SimApiApiConfig           // api: { endpoints, defaultEndpoint, businessCallback, responseCallback, timeout? }
-SimApiBusinessCallback    // { [code]: (data) => void }，支持数字码或 'common'
-```
-
----
-
-## SimApiCore（simapi.core.ts）
-
-**职责**：纯 TS HTTP 客户端，基于原生 fetch API，不依赖任何框架。
-
-**关键设计**：
-
-- **零依赖**：使用原生 fetch，无 axios 或其他 HTTP 库
-- **无 Cookie**：所有请求使用 `credentials: 'omit'`，避免 CORS 问题
-- **Token 传递**：通过请求头 `Token` 传递认证信息
-- **超时控制**：通过 `fetchWithTimeout` 辅助函数实现
-- `query()` 抛出异常的只有网络/HTTP 错误，业务错误码通过回调处理
-- `isLoggedIn` 是 getter，基于 localStorage 中的 token 判断
-- **版本号**：`getVersion()` 返回的版本信息中，`uiSimApi` 由构建时注入的 `SimApiVersion` 填充，`uiApp` 由调用方的 `AppVersion` 填充（未注入时为 `0.0.0-develop`）
-
-**修改建议**：
-
-- 改请求方法（GET/PUT/DELETE）：在 `fetchPost()` 内新增 `method` 参数分支，或新增 `fetchGet()`/`fetchPut()` 方法
-- 改 Token 存储：替换 `localStorage` 为 `sessionStorage` 或内存变量，修改 `getToken()`/`setToken()`/`removeToken()`
-- 改登录/登出逻辑：修改 `login()`/`logout()` 方法
-- 改超时处理：修改 `fetchWithTimeout()` 函数
-- **版本管理**：版本号通过 `declare const` 声明常量，构建时通过 Vite 的 `define` 注入。未指定时默认为 `0.0.0-develop`
-
-**autoInit 设计约束**：
-
-- 仅读取 `window.simapi` 的顶级字段：`endpoints`、`defaultEndpoint`、`debug`
-- 业务回调（`businessCallback`/`responseCallback`）不支持从 window 读取，必须在代码中通过 `setBusinessCallback` 注册
-
----
-
-## Pinia Store（simapi.pinia.ts）
-
-**职责**：Vue3 适配层，SimApiCore 的纯代理，不维护任何独立状态。
-
-**关键设计**：
-
-- **无独立状态**：state 中只有一个 `_core` 实例，不维护 `debug`、`token` 等独立数据
-- **单例 Core**：在 store state 中实例化 `SimApiCore`，整个应用共享一个实例
-- **纯代理映射**：所有 getters 直接映射到 `this._core` 的属性，所有 actions 直接调用 `this._core` 的方法
-- **响应式**：通过 Pinia 的响应式系统，当 core 状态变化时自动更新
-
-**使用方式**：
-
-```typescript
-// 任意组件
-import { useSimApi } from '@simcu/simapi'
-
-const api = useSimApi()
-
-// 初始化（二选一）
-// 方式一：从 window.simapi 读取
-api.autoInit()
-
-// 方式二：直接传入配置
-api.configure({
-  api: { endpoints: { default: 'https://api.example.com' } },
-})
-
-// 所有方法与 SimApiCore 完全一致
-await api.query('/users/list', { page: 1 })
-```
-
----
-
-## 构建流程
-
-```
-npm run build
-  → vite build                          输出 dist/index.mjs / index.cjs / pinia.mjs / pinia.cjs
-  → tsc -p tsconfig.build.json         输出 *.d.ts 类型声明
-```
-
-**版本号注入：**
-
-版本号通过 `vite.config.ts` 的 `define` 配置注入，从 npm config 读取：
-
-```typescript
-define: {
-  'SimApiVersion': JSON.stringify(process.env.npm_config_SimApiVersion || '0.0.0-develop'),
-}
-```
-
-**本地构建示例：**
-```bash
-# 通过环境变量
-# Windows PowerShell
-$env:npm_config_SimApiVersion='1.0.0'; npm run build
-
-# Linux/Mac
-npm_config_SimApiVersion=1.0.0 npm run build
-```
-
-**GitHub Actions 自动发布：**
-```yaml
-env:
-  SimApiVersion: ${{ github.ref_name }}
-run: npm run build
-```
-
-**dist 输出是平铺的**，core 和 pinia 的编译产物全部在同一目录：
-
-```
-dist/
-├── index.mjs       # core ESM
-├── index.cjs       # core CJS
-├── pinia.mjs       # pinia ESM
-├── pinia.cjs       # pinia CJS
-├── simapi.core.d.ts
-├── simapi.pinia.d.ts
-└── types.d.ts
-```
-
----
-
-## package.json exports
-
-```json
-".":         { "import": "./dist/index.mjs", "types": "./dist/simapi.core.d.ts" }
-"./pinia":   { "import": "./dist/pinia.mjs", "types": "./dist/simapi.pinia.d.ts" }
-```
-
----
-
-## 注意事项
-
-- Core 默认 `debug: true`，生产环境需手动 `configure({ debug: false })`
-- `query()` 返回 `Promise<SimApiBaseResponse<T>>`，code !== 200 时不 reject，通过 `businessCallback` 处理
-- `login()` 成功后将 `result.data` 存入 localStorage
-- **无 Cookie**：所有请求不发送 Cookie，Token 通过请求头传递
-- **零依赖**：不需要安装 axios，使用原生 fetch
-- 删除了 Angular 支持，如需恢复参考 git 历史
-- **版本号管理**：使用 `declare const` + Vite `define` 注入
-- **AppVersion** 不注入，留给调用方自己管理

src/simapi.core.ts

@@ -28,6 +28,7 @@ export type {
 
 declare const SimApiVersion: string;
 declare const AppVersion: string;
+
 // ── Helper: Fetch with Timeout ────────────────────────────────────────
 
 function fetchWithTimeout(
@@ -85,15 +86,17 @@ export class SimApiCore {
     }
 
     api: SimApiApiConfig = {
-    endpoints: { default: '' },
+        endpoints: {default: ''},
         defaultEndpoint: 'default',
         businessCallback: {
             401: () => localStorage.removeItem(this.auth.token_name),
-      common: () => {},
+            common: () => {
+            },
         },
         responseCallback: {
             success: (response: any) => response,
-      error: (_err: any) => {},
+            error: (_err: any) => {
+            },
         },
         timeout: 10000,
     }
@@ -118,7 +121,7 @@ export class SimApiCore {
             this.debug = config.debug
         }
         if (config.endpoints) {
-      this.api.endpoints = { ...this.api.endpoints, ...config.endpoints }
+            this.api.endpoints = {...this.api.endpoints, ...config.endpoints}
         }
         if (config.defaultEndpoint) {
             this.api.defaultEndpoint = config.defaultEndpoint
@@ -130,21 +133,21 @@ export class SimApiCore {
             this.debug = options.debug
         }
         if (options.auth) {
-      this.auth = { ...this.auth, ...options.auth }
+            this.auth = {...this.auth, ...options.auth}
         }
         if (options.api) {
             this.api = {
                 ...this.api,
                 ...options.api,
-        endpoints: { ...this.api.endpoints, ...(options.api.endpoints ?? {}) },
-        businessCallback: { ...this.api.businessCallback, ...(options.api.businessCallback ?? {}) },
-        responseCallback: { ...this.api.responseCallback, ...(options.api.responseCallback ?? {}) },
+                endpoints: {...this.api.endpoints, ...(options.api.endpoints ?? {})},
+                businessCallback: {...this.api.businessCallback, ...(options.api.businessCallback ?? {})},
+                responseCallback: {...this.api.responseCallback, ...(options.api.responseCallback ?? {})},
             }
         }
     }
 
     setEndpoints(endpoints: { [name: string]: string }): void {
-    this.api.endpoints = { ...this.api.endpoints, ...endpoints }
+        this.api.endpoints = {...this.api.endpoints, ...endpoints}
     }
 
     getEndpoint(name?: string): string {
@@ -215,10 +218,10 @@ export class SimApiCore {
             const resp = await this.query<any>('/versions', {}, endpointName)
             if (resp?.data) {
                 const d = resp.data
-        versions.apiApp= d.App?.split('+')[0] ?? '0.0.0';
-        versions.apiSimApi= d.SimApi?.split('+')[0] ?? '0.0.0';
-        versions.apiAppFull= d.App ?? '0.0.0';
-        versions.apiSimApiFull= d.SimApi ?? '0.0.0';
+                versions.apiApp = d.App?.split('+')[0] ?? '0.0.0';
+                versions.apiSimApi = d.SimApi?.split('+')[0] ?? '0.0.0';
+                versions.apiAppFull = d.App ?? '0.0.0';
+                versions.apiSimApiFull = d.SimApi ?? '0.0.0';
                 if (this.debug) {
                     console.log(`UI主应用版本: ${versions.uiApp}\nUISimApi版本: ${versions.uiSimApi}\nAPI主应用版本: ${versions.apiApp}\nAPISimApi版本: ${versions.apiSimApi}`)
                 }
@@ -234,9 +237,10 @@ export class SimApiCore {
         uri: string,
         params: any = {},
         endpointKey?: string,
-    extraHeaders?: Record<string, string>
+        extraHeaders?: Record<string, string>,
+        selfHandleError: boolean = false
     ): Promise<SimApiBaseResponse<T>> {
-    const headers: Record<string, string> = { ...extraHeaders, ...{} }
+        const headers: Record<string, string> = {...extraHeaders, ...{}}
         const queryId = this.genS4()
 
         if (!(params instanceof FormData)) {
@@ -268,11 +272,13 @@ export class SimApiCore {
             const processedData = this.api.responseCallback.success(respData) as SimApiBaseResponse<T>
 
             // 业务回调处理
+            if (!selfHandleError) {
                 if (this.api.businessCallback.hasOwnProperty(processedData.code)) {
                     this.api.businessCallback[processedData.code](processedData)
                 } else if (this.api.businessCallback['common'] && processedData.code !== 200) {
                     this.api.businessCallback['common'](processedData)
                 }
+            }
 
             // code != 200 时抛出业务错误
             if (processedData.code !== 200) {
@@ -307,16 +313,17 @@ export class SimApiCore {
     }
 
     async logout(url?: string | null): Promise<any> {
-    this.removeToken()
         if (url !== null) {
-      return this.query(url ?? this.auth.logout_url).catch(() => true)
+            this.query(url ?? this.auth.logout_url).catch(() => true)
         }
+        this.removeToken()
         return true
     }
 
     async checkLogin(url?: string | null): Promise<void> {
         if (url !== null) {
-      await this.query(url ?? this.auth.check_url).catch(() => {})
+            await this.query(url ?? this.auth.check_url).catch(() => {
+            })
         } else if (this.getToken()) {
             this.api.businessCallback[401]?.(null)
         }

src/simapi.pinia.ts

@@ -1,6 +1,6 @@
-import { defineStore } from 'pinia'
-import { SimApiCore } from './simapi.core'
-import type { SimApiBaseResponse, SimApiOptions, SimApiVersions } from './types'
+import {defineStore} from 'pinia'
+import {SimApiCore} from './simapi.core'
+import type {SimApiBaseResponse, SimApiOptions, SimApiVersions} from './types'
 
 // ============ Pinia Store ============
 // 仅作为 core 的代理映射，不维护任何独立状态
@@ -73,9 +73,10 @@ export const useSimApi = defineStore('simapi', {
             uri: string,
             params?: any,
             endpointKey?: string,
-      extraHeaders?: Record<string, string>
+            extraHeaders?: Record<string, string>,
+            selfHandleError: boolean = false
         ): Promise<SimApiBaseResponse<T>> {
-      return this._core.query<T>(uri, params, endpointKey, extraHeaders)
+            return this._core.query<T>(uri, params, endpointKey, extraHeaders, selfHandleError)
         },
 
         getEndpoint(name?: string): string {