3.0
Publish to npm / publish (push) Failing after 29s
Publish to npm / publish (push) Failing after 29s
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# SimApi - 轻量 API 请求库
|
||||
# @simcu/simapi
|
||||
|
||||
基于 Axios 的 Vue 3 + Pinia HTTP 客户端库。
|
||||
> 轻量级 HTTP 请求库，基于原生 fetch，支持任意 JS/TS 环境及 Vue3。
|
||||
|
||||
## 安装
|
||||
|
||||
@@ -8,130 +8,344 @@
|
||||
npm install @simcu/simapi
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
## 架构
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
npm install @simcu/simapi pinia
|
||||
```
|
||||
src/
|
||||
├── types.ts # 类型定义（SimApiBaseResponse、SimApiOptions 等）
|
||||
├── simapi.core.ts # 纯 TS 核心，无框架依赖
|
||||
└── simapi.pinia.ts # Vue3 Pinia Store 封装
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
## 核心层（框架无关）
|
||||
|
||||
### 1. 初始化配置
|
||||
|
||||
在 Vue 应用入口（如 `main.ts` 或 `App.vue`）中配置端点和调试模式：
|
||||
适用于浏览器、Node.js、小程序等任意环境。
|
||||
|
||||
```typescript
|
||||
import { useSimApi } from 'simapi'
|
||||
import { SimApiCore } from '@simcu/simapi'
|
||||
|
||||
const api = useSimApi()
|
||||
const api = new SimApiCore()
|
||||
|
||||
// 设置 API 端点
|
||||
api.setEndpoints({
|
||||
default: 'https://api.example.com'
|
||||
// 从 window.simapi 读取配置（可选）
|
||||
api.autoInit()
|
||||
|
||||
// 或手动配置
|
||||
api.configure({
|
||||
api: { endpoints: { default: 'https://api.example.com' } },
|
||||
debug: true,
|
||||
})
|
||||
|
||||
// 设置调试模式（默认 true）
|
||||
api.setDebug(true)
|
||||
```
|
||||
// 发起请求
|
||||
const res = await api.query('/users/list', { page: 1 })
|
||||
// res.code === 200，res.data 为业务数据
|
||||
|
||||
### 2. 发起请求
|
||||
|
||||
```typescript
|
||||
import { useSimApi } from 'simapi'
|
||||
|
||||
const api = useSimApi()
|
||||
|
||||
// 简单请求
|
||||
const result = await api.query('/users/list', { page: 1 })
|
||||
|
||||
// 带 Token 认证的请求
|
||||
const result = await api.query('/protected/resource', { id: 123 })
|
||||
```
|
||||
|
||||
### 3. 登录/登出
|
||||
|
||||
```typescript
|
||||
// 登录
|
||||
const result = await api.login({
|
||||
phone: '13800138000',
|
||||
code: '123456'
|
||||
})
|
||||
await api.login({ phone: '13800138000', code: '123456' })
|
||||
|
||||
// 登出
|
||||
await api.logout()
|
||||
|
||||
// 注册业务错误码回调
|
||||
api.setBusinessCallback(401, () => router.push('/login'))
|
||||
api.setBusinessCallback('common', (data) => alert(data.message))
|
||||
```
|
||||
|
||||
## Vue3
|
||||
|
||||
安装 Pinia：
|
||||
|
||||
```bash
|
||||
npm install pinia
|
||||
```
|
||||
|
||||
```typescript
|
||||
// main.ts
|
||||
import { createApp } from 'vue'
|
||||
import { createPinia } from 'pinia'
|
||||
import App from './App.vue'
|
||||
|
||||
const app = createApp(App)
|
||||
app.use(createPinia())
|
||||
app.mount('#app')
|
||||
```
|
||||
|
||||
```typescript
|
||||
// 任意组件
|
||||
import { useSimApi } from '@simcu/simapi'
|
||||
|
||||
const api = useSimApi()
|
||||
|
||||
// 响应式
|
||||
console.log(api.token) // 当前 Token
|
||||
console.log(api.isLoggedIn) // 是否已登录
|
||||
|
||||
// 发起请求
|
||||
const res = await api.query('/users/list', { page: 1 })
|
||||
console.log(res.data)
|
||||
|
||||
// 登录 / 登出
|
||||
await api.login({ phone: '13800138000', code: '123456' })
|
||||
await api.logout()
|
||||
|
||||
// 调试模式
|
||||
api.setDebug(true)
|
||||
```
|
||||
|
||||
### 多端点
|
||||
|
||||
```typescript
|
||||
api.setEndpoints({
|
||||
default: 'https://api.example.com',
|
||||
admin: 'https://admin.example.com',
|
||||
})
|
||||
|
||||
// 指定端点发请求
|
||||
await api.query('/stats', {}, 'admin')
|
||||
```
|
||||
|
||||
## autoInit — 从 window 读取配置
|
||||
|
||||
仅支持三个字段：`endpoints`、`defaultEndpoint`、`debug`。业务回调需在代码中通过 `setBusinessCallback` 处理。
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.simapi = {
|
||||
endpoints: {
|
||||
default: 'https://api.example.com',
|
||||
admin: 'https://admin.example.com',
|
||||
},
|
||||
defaultEndpoint: 'default',
|
||||
debug: false,
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
初始化时手动调用：
|
||||
|
||||
```typescript
|
||||
// 方式一：从 window.simapi 读取
|
||||
const api = useSimApi()
|
||||
api.autoInit()
|
||||
|
||||
// 方式二：直接传入配置
|
||||
const api = useSimApi()
|
||||
api.configure({
|
||||
api: { endpoints: { default: 'https://api.example.com' } },
|
||||
})
|
||||
```
|
||||
|
||||
## SimApiBaseResponse 响应格式
|
||||
|
||||
```typescript
|
||||
interface SimApiBaseResponse<T = any> {
|
||||
code: number // 200 = 成功，其他为业务错误码
|
||||
message: string // 提示信息
|
||||
data?: T // 业务数据
|
||||
}
|
||||
```
|
||||
|
||||
## 完整配置参考
|
||||
|
||||
### SimApiOptions — 完整配置结构
|
||||
|
||||
```typescript
|
||||
interface SimApiOptions {
|
||||
/** 调试模式，默认 true */
|
||||
debug?: boolean
|
||||
|
||||
/** 认证相关配置 */
|
||||
auth?: Partial<SimApiAuthConfig>
|
||||
|
||||
/** API 相关配置 */
|
||||
api?: Partial<SimApiApiConfig>
|
||||
}
|
||||
```
|
||||
|
||||
### SimApiAuthConfig — 认证配置
|
||||
|
||||
```typescript
|
||||
interface SimApiAuthConfig {
|
||||
/** localStorage 中存储 Token 的 key */
|
||||
token_name: string // 默认 'simapi-auth-token'
|
||||
|
||||
/** 检查登录状态的接口路径 */
|
||||
check_url: string // 默认 '/auth/check'
|
||||
|
||||
/** 登出接口路径 */
|
||||
logout_url: string // 默认 '/auth/logout'
|
||||
|
||||
/** 登录接口路径 */
|
||||
login_url: string // 默认 '/auth/login'
|
||||
}
|
||||
```
|
||||
|
||||
### SimApiApiConfig — API 配置
|
||||
|
||||
```typescript
|
||||
interface SimApiApiConfig {
|
||||
/** 多端点映射，key 为端点名，value 为 baseURL */
|
||||
endpoints: { [name: string]: string }
|
||||
|
||||
/** 默认端点名，默认 'default' */
|
||||
defaultEndpoint: string
|
||||
|
||||
/** 业务错误码回调，key 为错误码或 'common' */
|
||||
businessCallback: SimApiBusinessCallback
|
||||
|
||||
/** 响应拦截回调 */
|
||||
responseCallback: SimApiResponseCallback
|
||||
|
||||
/** 请求超时时间（毫秒），默认 10000 */
|
||||
timeout?: number
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ CORS 说明**
|
||||
|
||||
- 本库使用原生 fetch API，默认不发送 Cookie（`credentials: 'omit'`）
|
||||
- Token 通过请求头 `Token` 传递，无需依赖 Cookie
|
||||
- 服务器返回 `Access-Control-Allow-Origin: *` 不会有问题
|
||||
|
||||
### SimApiBusinessCallback — 业务回调
|
||||
|
||||
key 支持数字错误码或 `'common'`（通用兜底回调）：
|
||||
|
||||
```typescript
|
||||
type SimApiBusinessCallback = {
|
||||
[code: number | string]: (data: SimApiBaseResponse) => void
|
||||
}
|
||||
|
||||
// 示例
|
||||
{
|
||||
401: (data) => router.push('/login'), // 未授权
|
||||
403: (data) => ElMessage.error('无权限'), // 无权限
|
||||
500: (data) => console.error(data), // 服务器错误
|
||||
'common': (data) => ElMessage.error(data.message) // 其他错误码兜底
|
||||
}
|
||||
```
|
||||
|
||||
### SimApiResponseCallback — 响应拦截
|
||||
|
||||
```typescript
|
||||
interface SimApiResponseCallback {
|
||||
/** 成功响应拦截，可在此统一处理数据结构 */
|
||||
success: (response: any) => any
|
||||
|
||||
/** 网络/HTTP 错误拦截 */
|
||||
error: (err: any) => void
|
||||
}
|
||||
|
||||
// 示例：统一脱敏处理
|
||||
{
|
||||
success: (res) => {
|
||||
// fetch 返回 { code, message, data }
|
||||
return res
|
||||
},
|
||||
error: (err) => {
|
||||
console.error('请求失败', err)
|
||||
throw err
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SimApiVersions — 版本信息
|
||||
|
||||
```typescript
|
||||
interface SimApiVersions {
|
||||
uiApp: string // 前端应用版本
|
||||
uiSimApi: string // 前端 SimApi 版本
|
||||
apiApp: string // 后端应用版本（简化版，如 "1.2.3"）
|
||||
apiSimApi: string // 后端 SimApi 版本（简化版）
|
||||
apiAppFull: string // 后端应用版本（完整版，如 "1.2.3+20240101"）
|
||||
apiSimApiFull: string // 后端 SimApi 版本（完整版）
|
||||
}
|
||||
```
|
||||
|
||||
### 完整配置示例
|
||||
|
||||
```typescript
|
||||
api.configure({
|
||||
debug: false,
|
||||
|
||||
auth: {
|
||||
token_name: 'my-app-token',
|
||||
check_url: '/api/auth/check',
|
||||
logout_url: '/api/auth/logout',
|
||||
login_url: '/api/auth/login',
|
||||
},
|
||||
|
||||
api: {
|
||||
endpoints: {
|
||||
default: 'https://api.example.com',
|
||||
admin: 'https://admin.example.com',
|
||||
},
|
||||
defaultEndpoint: 'default',
|
||||
|
||||
businessCallback: {
|
||||
401: () => router.push('/login'),
|
||||
403: () => ElMessage.error('无权限访问'),
|
||||
500: (data) => console.error('服务器错误:', data.message),
|
||||
'common': (data) => ElMessage.error(data.message || '请求失败'),
|
||||
},
|
||||
|
||||
responseCallback: {
|
||||
success: (res) => res.data ?? res,
|
||||
error: (err) => {
|
||||
console.error('网络错误', err)
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## API 参考
|
||||
|
||||
### 配置方法
|
||||
### SimApiCore（核心类）
|
||||
|
||||
| 方法 | 说明 |
|
||||
| ------------------------------------- | ---------------------------------------------------------- |
|
||||
| `setEndpoints(endpoints)` | 设置 API 端点，如 `{ default: 'https://api.example.com' }` |
|
||||
| `setDebug(debug: boolean)` | 开启/关闭调试模式 |
|
||||
| `setBusinessCallback(code, callback)` | 设置业务错误码回调 |
|
||||
| 方法/属性 | 说明 |
|
||||
|-----------|------|
|
||||
| `configure(options)` | 批量配置（深合并） |
|
||||
| `autoInit()` | 从 `window.simapi` 读取配置（endpoints、defaultEndpoint、debug） |
|
||||
| `setEndpoints(map)` | 设置端点，自动触发版本检查 |
|
||||
| `setBusinessCallback(code, fn)` | 注册业务错误码回调 |
|
||||
| `setDebug(debug)` | 设置调试模式 |
|
||||
| `query(uri, params?, endpointKey?, headers?)` | POST 请求，返回 `Promise<SimApiBaseResponse<T>>` |
|
||||
| `login(request)` | 登录，自动存 Token |
|
||||
| `logout(url?)` | 登出，清除 Token |
|
||||
| `checkLogin(url?)` | 主动检查登录状态 |
|
||||
| `getToken()` | 获取 Token |
|
||||
| `setToken(token)` | 手动设置 Token |
|
||||
| `removeToken()` | 清除 Token |
|
||||
| `isLoggedIn` | getter，是否已登录 |
|
||||
| `token` | getter，获取当前 Token |
|
||||
| `debug` | boolean，调试模式 |
|
||||
| `versions` | 版本信息对象 |
|
||||
|
||||
### 请求方法
|
||||
## 构建
|
||||
|
||||
| 方法 | 说明 |
|
||||
| ------------------------ | -------------- |
|
||||
| `api.query(uri, params)` | 发起 POST 请求 |
|
||||
| `api.login(data)` | 登录 |
|
||||
| `api.logout()` | 登出 |
|
||||
|
||||
### 工具方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
| ------------------------ | -------------- |
|
||||
| `api.getEndpoint(name?)` | 获取端点地址 |
|
||||
| `api.getToken()` | 获取当前 Token |
|
||||
|
||||
### Getters
|
||||
|
||||
| 属性 | 说明 |
|
||||
| ---------------- | -------------------- |
|
||||
| `api.token` | 当前 Token（响应式） |
|
||||
| `api.isLoggedIn` | 是否已登录（响应式） |
|
||||
|
||||
## 调试日志
|
||||
|
||||
启用调试模式后，控制台会输出：
|
||||
|
||||
```
|
||||
[REQUEST*] queryId -> /uri AUTH: token
|
||||
[RESPONSE] queryId -> {data: {...}, code: 200}
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
npm link # 本地调试
|
||||
```
|
||||
|
||||
设置端点后会自动打印版本信息：
|
||||
---
|
||||
|
||||
```
|
||||
UI主应用版本: 1.0.0
|
||||
UISimApi版本: 1.0.0
|
||||
API主应用版本: x.x.x
|
||||
APISimApi版本: x.x.x
|
||||
## 从旧版迁移
|
||||
|
||||
如果你之前使用的是带 axios 的版本，迁移非常简单：
|
||||
|
||||
```diff
|
||||
- import axios from 'axios'
|
||||
+ import { SimApiCore } from '@simcu/simapi'
|
||||
- // ... 你的 axios 配置
|
||||
|
||||
+ const api = new SimApiCore()
|
||||
+ api.setEndpoints({ default: 'https://api.example.com' })
|
||||
+ const res = await api.query('/users/list', { page: 1 })
|
||||
```
|
||||
|
||||
## 业务错误处理
|
||||
|
||||
```typescript
|
||||
const api = useSimApi()
|
||||
|
||||
// 处理 401 未授权
|
||||
api.setBusinessCallback(401, (data) => {
|
||||
console.log('Token 过期', data)
|
||||
localStorage.removeItem('token')
|
||||
router.push('/login')
|
||||
})
|
||||
|
||||
// 处理 403 禁止访问
|
||||
api.setBusinessCallback(403, (data) => {
|
||||
ElMessage.error('没有权限')
|
||||
})
|
||||
|
||||
// 处理所有非 200 错误
|
||||
api.setBusinessCallback('common', (data) => {
|
||||
ElMessage.error(data.message)
|
||||
})
|
||||
```
|
||||
API 完全兼容，无需其他改动。主要变化：
|
||||
- 使用原生 fetch 替代 axios
|
||||
- Token 通过请求头 `Token` 传递（不是 `Authorization: Bearer`）
|
||||
- 默认不发送 Cookie，避免 CORS 问题
|
||||
|
||||
Reference in New Issue
Block a user