Compare commits

..
3 Commits
Author SHA1 Message Date
xrain 39626de073 修复了退出登录 TOKEN没清空的问题
Publish to npm / publish (push) Failing after 14s
2026-05-04 00:15:23 +08:00
xrain 13c836b4ab 修改退出登录没带TOKEn
Publish to npm / publish (push) Failing after 14s
2026-05-03 23:11:55 +08:00
xrain 88be4210aa 修正文档 2026-04-26 10:44:40 +08:00
3 changed files with 944 additions and 752 deletions
-166
View File
@@ -1,166 +0,0 @@
# @simcu/simapi — AI 开发指南
> 面向 AI Agent 的代码结构说明,帮助理解、修改和扩展本库。
---
## 项目结构
```
simapi-vue/
├── src/
│ ├── types.ts # 类型定义,全部导出
│ ├── simapi.core.ts # 核心类 SimApiCore,零框架依赖
│ └── simapi.pinia.ts # Pinia StoreVue3 适配层
├── 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'
```
---
## SimApiCoresimapi.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 Storesimapi.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**:所有请求不发送 CookieToken 通过请求头传递
- **零依赖**:不需要安装 axios,使用原生 fetch
- 删除了 Angular 支持,如需恢复参考 git 历史
- **版本号管理**:使用 `declare const` + Vite `define` 注入
- **AppVersion** 不注入,留给调用方自己管理
+671 -317
View File
File diff suppressed because it is too large Load Diff
+21 -17
View File
@@ -28,6 +28,7 @@ export type {
declare const SimApiVersion: string; declare const SimApiVersion: string;
declare const AppVersion: string; declare const AppVersion: string;
// ── Helper: Fetch with Timeout ──────────────────────────────────────── // ── Helper: Fetch with Timeout ────────────────────────────────────────
function fetchWithTimeout( function fetchWithTimeout(
@@ -85,15 +86,17 @@ export class SimApiCore {
} }
api: SimApiApiConfig = { api: SimApiApiConfig = {
endpoints: { default: '' }, endpoints: {default: ''},
defaultEndpoint: 'default', defaultEndpoint: 'default',
businessCallback: { businessCallback: {
401: () => localStorage.removeItem(this.auth.token_name), 401: () => localStorage.removeItem(this.auth.token_name),
common: () => {}, common: () => {
},
}, },
responseCallback: { responseCallback: {
success: (response: any) => response, success: (response: any) => response,
error: (_err: any) => {}, error: (_err: any) => {
},
}, },
timeout: 10000, timeout: 10000,
} }
@@ -118,7 +121,7 @@ export class SimApiCore {
this.debug = config.debug this.debug = config.debug
} }
if (config.endpoints) { if (config.endpoints) {
this.api.endpoints = { ...this.api.endpoints, ...config.endpoints } this.api.endpoints = {...this.api.endpoints, ...config.endpoints}
} }
if (config.defaultEndpoint) { if (config.defaultEndpoint) {
this.api.defaultEndpoint = config.defaultEndpoint this.api.defaultEndpoint = config.defaultEndpoint
@@ -130,21 +133,21 @@ export class SimApiCore {
this.debug = options.debug this.debug = options.debug
} }
if (options.auth) { if (options.auth) {
this.auth = { ...this.auth, ...options.auth } this.auth = {...this.auth, ...options.auth}
} }
if (options.api) { if (options.api) {
this.api = { this.api = {
...this.api, ...this.api,
...options.api, ...options.api,
endpoints: { ...this.api.endpoints, ...(options.api.endpoints ?? {}) }, endpoints: {...this.api.endpoints, ...(options.api.endpoints ?? {})},
businessCallback: { ...this.api.businessCallback, ...(options.api.businessCallback ?? {}) }, businessCallback: {...this.api.businessCallback, ...(options.api.businessCallback ?? {})},
responseCallback: { ...this.api.responseCallback, ...(options.api.responseCallback ?? {}) }, responseCallback: {...this.api.responseCallback, ...(options.api.responseCallback ?? {})},
} }
} }
} }
setEndpoints(endpoints: { [name: string]: string }): void { setEndpoints(endpoints: { [name: string]: string }): void {
this.api.endpoints = { ...this.api.endpoints, ...endpoints } this.api.endpoints = {...this.api.endpoints, ...endpoints}
} }
getEndpoint(name?: string): string { getEndpoint(name?: string): string {
@@ -215,10 +218,10 @@ export class SimApiCore {
const resp = await this.query<any>('/versions', {}, endpointName) const resp = await this.query<any>('/versions', {}, endpointName)
if (resp?.data) { if (resp?.data) {
const d = resp.data const d = resp.data
versions.apiApp= d.App?.split('+')[0] ?? '0.0.0'; versions.apiApp = d.App?.split('+')[0] ?? '0.0.0';
versions.apiSimApi= d.SimApi?.split('+')[0] ?? '0.0.0'; versions.apiSimApi = d.SimApi?.split('+')[0] ?? '0.0.0';
versions.apiAppFull= d.App ?? '0.0.0'; versions.apiAppFull = d.App ?? '0.0.0';
versions.apiSimApiFull= d.SimApi ?? '0.0.0'; versions.apiSimApiFull = d.SimApi ?? '0.0.0';
if (this.debug) { if (this.debug) {
console.log(`UI主应用版本: ${versions.uiApp}\nUISimApi版本: ${versions.uiSimApi}\nAPI主应用版本: ${versions.apiApp}\nAPISimApi版本: ${versions.apiSimApi}`) console.log(`UI主应用版本: ${versions.uiApp}\nUISimApi版本: ${versions.uiSimApi}\nAPI主应用版本: ${versions.apiApp}\nAPISimApi版本: ${versions.apiSimApi}`)
} }
@@ -236,7 +239,7 @@ export class SimApiCore {
endpointKey?: string, endpointKey?: string,
extraHeaders?: Record<string, string> extraHeaders?: Record<string, string>
): Promise<SimApiBaseResponse<T>> { ): Promise<SimApiBaseResponse<T>> {
const headers: Record<string, string> = { ...extraHeaders, ...{} } const headers: Record<string, string> = {...extraHeaders, ...{}}
const queryId = this.genS4() const queryId = this.genS4()
if (!(params instanceof FormData)) { if (!(params instanceof FormData)) {
@@ -307,16 +310,17 @@ export class SimApiCore {
} }
async logout(url?: string | null): Promise<any> { async logout(url?: string | null): Promise<any> {
this.removeToken()
if (url !== null) { 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 return true
} }
async checkLogin(url?: string | null): Promise<void> { async checkLogin(url?: string | null): Promise<void> {
if (url !== null) { 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()) { } else if (this.getToken()) {
this.api.businessCallback[401]?.(null) this.api.businessCallback[401]?.(null)
} }