xxf_react 0.7.4 → 0.7.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/http/api/ApiBuilder.d.ts +10 -1
- package/dist/http/api/ApiBuilder.d.ts.map +1 -1
- package/dist/http/api/ApiBuilder.js +3 -1
- package/dist/http/api/index.d.ts +1 -1
- package/dist/http/api/index.d.ts.map +1 -1
- package/dist/http/api/index.js +1 -1
- package/dist/http/demo/api-builder.demo.d.ts +59 -10
- package/dist/http/demo/api-builder.demo.d.ts.map +1 -1
- package/dist/http/demo/api-builder.demo.js +190 -10
- package/dist/http/index.d.ts +1 -1
- package/dist/http/index.d.ts.map +1 -1
- package/dist/http/index.js +1 -1
- package/package.json +1 -1
|
@@ -38,6 +38,13 @@ import type { RequestConfig, ApiOptions, CacheConfig, HttpClientConfig } from '.
|
|
|
38
38
|
* 基础 API 调用选项（不含 body）
|
|
39
39
|
*/
|
|
40
40
|
type BaseApiOptions = Omit<ApiOptions, 'body'>;
|
|
41
|
+
/**
|
|
42
|
+
* 强制 TypeScript 展开交叉类型为单一对象类型
|
|
43
|
+
* 用于用户自定义接口类型时使用
|
|
44
|
+
*/
|
|
45
|
+
export type Simplify<T> = {
|
|
46
|
+
[K in keyof T]: T[K];
|
|
47
|
+
} & {};
|
|
41
48
|
/**
|
|
42
49
|
* 带 body 的 API 调用选项（body 必需）
|
|
43
50
|
*/
|
|
@@ -133,8 +140,10 @@ type EmptyApi = {};
|
|
|
133
140
|
* 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
|
|
134
141
|
*
|
|
135
142
|
* 建议：
|
|
136
|
-
* - 保持单个 builder 的端点数量在 4
|
|
143
|
+
* - 保持单个 builder 的端点数量在 4 个以内以获得最佳类型推断
|
|
137
144
|
* - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
|
|
145
|
+
* - 可以使用导出的 `ApiEndpointWithBody`、`ApiEndpointWithoutBody` 等类型
|
|
146
|
+
* 来定义自己的接口类型，获得更精确的类型检查
|
|
138
147
|
*
|
|
139
148
|
* @example
|
|
140
149
|
* ```ts
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,EAAE,EAAE,KAAK,OAAO,IAAI,SAAS,EAAE,MAAM,IAAI,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAMxF;;GAEG;AACH,KAAK,cAAc,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;
|
|
1
|
+
{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"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"}
|
|
@@ -43,8 +43,10 @@ import { HttpClient } from '../client/HttpClient';
|
|
|
43
43
|
* 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
|
|
44
44
|
*
|
|
45
45
|
* 建议：
|
|
46
|
-
* - 保持单个 builder 的端点数量在 4
|
|
46
|
+
* - 保持单个 builder 的端点数量在 4 个以内以获得最佳类型推断
|
|
47
47
|
* - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
|
|
48
|
+
* - 可以使用导出的 `ApiEndpointWithBody`、`ApiEndpointWithoutBody` 等类型
|
|
49
|
+
* 来定义自己的接口类型，获得更精确的类型检查
|
|
48
50
|
*
|
|
49
51
|
* @example
|
|
50
52
|
* ```ts
|
package/dist/http/api/index.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export { ApiBuilder, type ApiEndpoint, type ApiDefinition } from './ApiBuilder';
|
|
1
|
+
export { ApiBuilder, type ApiEndpoint, type ApiDefinition, type ApiEndpointWithBody, type ApiEndpointWithoutBody, type ApiEndpointWithBodyRequired, type ApiEndpointWithBodyOptional, type Simplify, } from './ApiBuilder';
|
|
2
2
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,QAAQ,GAChB,MAAM,cAAc,CAAA"}
|
package/dist/http/api/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { ApiBuilder } from './ApiBuilder';
|
|
1
|
+
export { ApiBuilder, } from './ApiBuilder';
|
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* ApiBuilder 使用示例
|
|
3
3
|
*
|
|
4
|
-
* 此文件演示 ApiBuilder
|
|
4
|
+
* 此文件演示 ApiBuilder 的核心特性：
|
|
5
5
|
* 1. 泛型累积 - 链式调用自动累积端点类型
|
|
6
6
|
* 2. Body 类型约束 - POST/PUT/PATCH 请求体类型检查
|
|
7
7
|
* 3. 端点名称字面量 - 调用不存在的端点会编译报错
|
|
8
|
+
* 4. 缓存策略 - CacheMode 控制缓存行为
|
|
9
|
+
* 5. 多次响应 - 支持缓存优先场景下的两次数据返回
|
|
8
10
|
*/
|
|
9
11
|
/** 用户实体 */
|
|
10
12
|
interface User {
|
|
@@ -31,23 +33,70 @@ interface PaginatedResponse<T> {
|
|
|
31
33
|
pageSize: number;
|
|
32
34
|
}
|
|
33
35
|
export declare const userApi: object & {
|
|
34
|
-
[x: string]:
|
|
36
|
+
[x: string]: ApiEndpointWithoutBody<User[]>;
|
|
35
37
|
} & {
|
|
36
|
-
[x: string]:
|
|
38
|
+
[x: string]: ApiEndpointWithoutBody<User>;
|
|
37
39
|
} & {
|
|
38
|
-
[x: string]:
|
|
40
|
+
[x: string]: ApiEndpointWithoutBody<PaginatedResponse<User>>;
|
|
39
41
|
} & {
|
|
40
|
-
[x: string]: import("
|
|
42
|
+
[x: string]: import("..").ApiEndpointWithBodyRequired<User, CreateUserDTO>;
|
|
41
43
|
} & {
|
|
42
|
-
[x: string]: import("
|
|
44
|
+
[x: string]: import("..").ApiEndpointWithBodyOptional<void>;
|
|
43
45
|
} & {
|
|
44
|
-
[x: string]: import("
|
|
46
|
+
[x: string]: import("..").ApiEndpointWithBodyRequired<User, UpdateUserDTO>;
|
|
45
47
|
} & {
|
|
46
|
-
[x: string]: import("
|
|
48
|
+
[x: string]: import("..").ApiEndpointWithBodyRequired<User, Partial<UpdateUserDTO>>;
|
|
47
49
|
} & {
|
|
48
|
-
[x: string]:
|
|
50
|
+
[x: string]: ApiEndpointWithoutBody<void>;
|
|
49
51
|
};
|
|
50
52
|
declare function demo(): Promise<void>;
|
|
53
|
+
/**
|
|
54
|
+
* CacheMode 枚举值说明：
|
|
55
|
+
*
|
|
56
|
+
* - OnlyRemote: 只请求网络，不使用缓存（适用于实时性要求高的数据）
|
|
57
|
+
* - OnlyCache: 只读取缓存，不请求网络（适用于离线场景）
|
|
58
|
+
* - FirstCache: 先返回缓存，再请求网络更新（可能返回两次数据）
|
|
59
|
+
* - FirstRemote: 先请求网络，失败时回退到缓存（网络优先）
|
|
60
|
+
* - IfCache: 有缓存则用缓存，无缓存则请求网络（只返回一次）
|
|
61
|
+
*/
|
|
62
|
+
/**
|
|
63
|
+
* 缓存模式使用示例
|
|
64
|
+
*/
|
|
65
|
+
declare function cacheModeDemo(): Promise<void>;
|
|
66
|
+
/**
|
|
67
|
+
* FirstCache 模式会返回两次数据：
|
|
68
|
+
* 1. 第一次：从缓存返回（如果有缓存），fromCache = true
|
|
69
|
+
* 2. 第二次：从网络返回最新数据，fromCache = false
|
|
70
|
+
*
|
|
71
|
+
* 这种模式非常适合：
|
|
72
|
+
* - 列表页快速展示 + 后台刷新
|
|
73
|
+
* - 详情页先显示旧数据，再更新为最新数据
|
|
74
|
+
* - 提升用户体验，减少白屏时间
|
|
75
|
+
*/
|
|
76
|
+
/**
|
|
77
|
+
* 方式一：使用 for await 处理多次响应
|
|
78
|
+
* 推荐用于需要处理每次响应的场景
|
|
79
|
+
*/
|
|
80
|
+
declare function multiResponseWithForAwait(): Promise<void>;
|
|
81
|
+
/**
|
|
82
|
+
* 方式二：使用 subscribe 处理多次响应
|
|
83
|
+
* 推荐用于 React/Vue 等框架中的响应式更新
|
|
84
|
+
*/
|
|
85
|
+
declare function multiResponseWithSubscribe(): Promise<void>;
|
|
86
|
+
/**
|
|
87
|
+
* 方式三：只需要最终结果时使用 await
|
|
88
|
+
* 注意：await 只返回最后一次响应（网络数据）
|
|
89
|
+
*/
|
|
90
|
+
declare function singleResponseWithAwait(): Promise<void>;
|
|
91
|
+
/**
|
|
92
|
+
* React 组件中的典型用法示例（伪代码）
|
|
93
|
+
*/
|
|
94
|
+
declare function reactUsageExample(): void;
|
|
51
95
|
declare function typeErrors(): void;
|
|
52
|
-
|
|
96
|
+
import type { ApiEndpointWithoutBody } from '../api/ApiBuilder';
|
|
97
|
+
/**
|
|
98
|
+
* 类型兼容性验证示例
|
|
99
|
+
*/
|
|
100
|
+
declare function verifyTypeCompatibility(): void;
|
|
101
|
+
export { demo, typeErrors, verifyTypeCompatibility, cacheModeDemo, multiResponseWithForAwait, multiResponseWithSubscribe, singleResponseWithAwait, reactUsageExample, };
|
|
53
102
|
//# sourceMappingURL=api-builder.demo.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"api-builder.demo.d.ts","sourceRoot":"","sources":["../../../src/http/demo/api-builder.demo.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"api-builder.demo.d.ts","sourceRoot":"","sources":["../../../src/http/demo/api-builder.demo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,WAAW;AACX,UAAU,IAAI;IACV,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CACpB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,WAAW;AACX,UAAU,iBAAiB,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACnB;AAMD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;CA8DR,CAAA;AAMZ,iBAAe,IAAI,kBAqDlB;AAMD;;;;;;;;GAQG;AAEH;;GAEG;AACH,iBAAe,aAAa,kBAmC3B;AAMD;;;;;;;;;GASG;AAEH;;;GAGG;AACH,iBAAe,yBAAyB,kBAiBvC;AAED;;;GAGG;AACH,iBAAe,0BAA0B,kBA0BxC;AAED;;;GAGG;AACH,iBAAe,uBAAuB,kBAUrC;AAED;;GAEG;AACH,iBAAS,iBAAiB,SA4CzB;AAoBD,iBAAS,UAAU,SAYlB;AAMD,OAAO,KAAK,EAAuB,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAcpF;;GAEG;AACH,iBAAS,uBAAuB,SAkB/B;AAMD,OAAO,EACH,IAAI,EACJ,UAAU,EACV,uBAAuB,EACvB,aAAa,EACb,yBAAyB,EACzB,0BAA0B,EAC1B,uBAAuB,EACvB,iBAAiB,GACpB,CAAA"}
|
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* ApiBuilder 使用示例
|
|
3
3
|
*
|
|
4
|
-
* 此文件演示 ApiBuilder
|
|
4
|
+
* 此文件演示 ApiBuilder 的核心特性：
|
|
5
5
|
* 1. 泛型累积 - 链式调用自动累积端点类型
|
|
6
6
|
* 2. Body 类型约束 - POST/PUT/PATCH 请求体类型检查
|
|
7
7
|
* 3. 端点名称字面量 - 调用不存在的端点会编译报错
|
|
8
|
+
* 4. 缓存策略 - CacheMode 控制缓存行为
|
|
9
|
+
* 5. 多次响应 - 支持缓存优先场景下的两次数据返回
|
|
8
10
|
*/
|
|
9
11
|
import { ApiBuilder } from '../api/ApiBuilder';
|
|
10
12
|
import { CacheMode } from '../models/CacheMode';
|
|
@@ -113,23 +115,182 @@ async function demo() {
|
|
|
113
115
|
cache: { mode: CacheMode.OnlyRemote },
|
|
114
116
|
});
|
|
115
117
|
console.log('Fresh:', freshUser);
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
118
|
+
}
|
|
119
|
+
// ============================================================================
|
|
120
|
+
// CacheMode 缓存模式详解
|
|
121
|
+
// ============================================================================
|
|
122
|
+
/**
|
|
123
|
+
* CacheMode 枚举值说明：
|
|
124
|
+
*
|
|
125
|
+
* - OnlyRemote: 只请求网络，不使用缓存（适用于实时性要求高的数据）
|
|
126
|
+
* - OnlyCache: 只读取缓存，不请求网络（适用于离线场景）
|
|
127
|
+
* - FirstCache: 先返回缓存，再请求网络更新（可能返回两次数据）
|
|
128
|
+
* - FirstRemote: 先请求网络，失败时回退到缓存（网络优先）
|
|
129
|
+
* - IfCache: 有缓存则用缓存，无缓存则请求网络（只返回一次）
|
|
130
|
+
*/
|
|
131
|
+
/**
|
|
132
|
+
* 缓存模式使用示例
|
|
133
|
+
*/
|
|
134
|
+
async function cacheModeDemo() {
|
|
135
|
+
// 1. OnlyRemote - 始终请求网络，忽略缓存
|
|
136
|
+
// 适用场景：提交表单、实时数据
|
|
137
|
+
const realTimeData = await userApi.getUser({
|
|
138
|
+
pathParams: { id: '123' },
|
|
139
|
+
cache: { mode: CacheMode.OnlyRemote },
|
|
140
|
+
});
|
|
141
|
+
console.log('实时数据:', realTimeData);
|
|
142
|
+
// 2. OnlyCache - 只读缓存，不请求网络
|
|
143
|
+
// 适用场景：离线模式、快速展示历史数据
|
|
144
|
+
try {
|
|
145
|
+
const cachedData = await userApi.getUser({
|
|
146
|
+
pathParams: { id: '123' },
|
|
147
|
+
cache: { mode: CacheMode.OnlyCache },
|
|
148
|
+
});
|
|
149
|
+
console.log('缓存数据:', cachedData);
|
|
150
|
+
}
|
|
151
|
+
catch (error) {
|
|
152
|
+
console.log('无缓存数据');
|
|
153
|
+
}
|
|
154
|
+
// 3. IfCache - 有缓存用缓存，无缓存请求网络（只返回一次）
|
|
155
|
+
// 适用场景：静态资源、不常变化的配置
|
|
156
|
+
const configData = await userApi.getUsers({
|
|
157
|
+
cache: { mode: CacheMode.IfCache, ttl: 60 * 60 * 1000 }, // 1小时
|
|
158
|
+
});
|
|
159
|
+
console.log('配置数据:', configData);
|
|
160
|
+
// 4. FirstRemote - 优先网络，失败回退缓存（只返回一次）
|
|
161
|
+
// 适用场景：希望获取最新数据，但网络不稳定时有兜底
|
|
162
|
+
const freshData = await userApi.getUser({
|
|
163
|
+
pathParams: { id: '123' },
|
|
164
|
+
cache: { mode: CacheMode.FirstRemote },
|
|
165
|
+
});
|
|
166
|
+
console.log('最新数据:', freshData);
|
|
167
|
+
}
|
|
168
|
+
// ============================================================================
|
|
169
|
+
// 多次响应处理 - FirstCache 模式的核心特性
|
|
170
|
+
// ============================================================================
|
|
171
|
+
/**
|
|
172
|
+
* FirstCache 模式会返回两次数据：
|
|
173
|
+
* 1. 第一次：从缓存返回（如果有缓存），fromCache = true
|
|
174
|
+
* 2. 第二次：从网络返回最新数据，fromCache = false
|
|
175
|
+
*
|
|
176
|
+
* 这种模式非常适合：
|
|
177
|
+
* - 列表页快速展示 + 后台刷新
|
|
178
|
+
* - 详情页先显示旧数据，再更新为最新数据
|
|
179
|
+
* - 提升用户体验，减少白屏时间
|
|
180
|
+
*/
|
|
181
|
+
/**
|
|
182
|
+
* 方式一：使用 for await 处理多次响应
|
|
183
|
+
* 推荐用于需要处理每次响应的场景
|
|
184
|
+
*/
|
|
185
|
+
async function multiResponseWithForAwait() {
|
|
186
|
+
console.log('=== for await 方式 ===');
|
|
187
|
+
for await (const { data, fromCache } of userApi.getUser({
|
|
188
|
+
pathParams: { id: '123' },
|
|
189
|
+
cache: { mode: CacheMode.FirstCache },
|
|
190
|
+
})) {
|
|
191
|
+
if (fromCache) {
|
|
192
|
+
console.log('📦 缓存数据（快速展示）:', data);
|
|
193
|
+
// 可以先用缓存数据渲染 UI
|
|
194
|
+
}
|
|
195
|
+
else {
|
|
196
|
+
console.log('🌐 网络数据（最新）:', data);
|
|
197
|
+
// 用最新数据更新 UI
|
|
198
|
+
}
|
|
119
199
|
}
|
|
120
|
-
|
|
121
|
-
|
|
200
|
+
console.log('✅ 请求完成');
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* 方式二：使用 subscribe 处理多次响应
|
|
204
|
+
* 推荐用于 React/Vue 等框架中的响应式更新
|
|
205
|
+
*/
|
|
206
|
+
async function multiResponseWithSubscribe() {
|
|
207
|
+
console.log('=== subscribe 方式 ===');
|
|
208
|
+
await userApi
|
|
209
|
+
.getUser({
|
|
210
|
+
pathParams: { id: '123' },
|
|
211
|
+
cache: { mode: CacheMode.FirstCache },
|
|
212
|
+
})
|
|
213
|
+
.subscribe({
|
|
122
214
|
onData: (data, fromCache) => {
|
|
123
|
-
|
|
215
|
+
if (fromCache) {
|
|
216
|
+
console.log('📦 缓存数据:', data);
|
|
217
|
+
// setState({ user: data, loading: false })
|
|
218
|
+
}
|
|
219
|
+
else {
|
|
220
|
+
console.log('🌐 网络数据:', data);
|
|
221
|
+
// setState({ user: data, loading: false, isStale: false })
|
|
222
|
+
}
|
|
124
223
|
},
|
|
125
224
|
onError: (error) => {
|
|
126
|
-
console.error('
|
|
225
|
+
console.error('❌ 请求失败:', error);
|
|
226
|
+
// setState({ error, loading: false })
|
|
127
227
|
},
|
|
128
228
|
onComplete: () => {
|
|
129
|
-
console.log('
|
|
229
|
+
console.log('✅ 请求完成');
|
|
130
230
|
},
|
|
131
231
|
});
|
|
132
232
|
}
|
|
233
|
+
/**
|
|
234
|
+
* 方式三：只需要最终结果时使用 await
|
|
235
|
+
* 注意：await 只返回最后一次响应（网络数据）
|
|
236
|
+
*/
|
|
237
|
+
async function singleResponseWithAwait() {
|
|
238
|
+
console.log('=== await 方式（只获取最终结果）===');
|
|
239
|
+
// 直接 await 只会返回最终的网络数据
|
|
240
|
+
const user = await userApi.getUser({
|
|
241
|
+
pathParams: { id: '123' },
|
|
242
|
+
cache: { mode: CacheMode.FirstCache },
|
|
243
|
+
});
|
|
244
|
+
console.log('最终数据:', user);
|
|
245
|
+
}
|
|
246
|
+
/**
|
|
247
|
+
* React 组件中的典型用法示例（伪代码）
|
|
248
|
+
*/
|
|
249
|
+
function reactUsageExample() {
|
|
250
|
+
/*
|
|
251
|
+
// React 组件示例
|
|
252
|
+
function UserProfile({ userId }: { userId: string }) {
|
|
253
|
+
const [user, setUser] = useState<User | null>(null)
|
|
254
|
+
const [isStale, setIsStale] = useState(false)
|
|
255
|
+
const [loading, setLoading] = useState(true)
|
|
256
|
+
|
|
257
|
+
useEffect(() => {
|
|
258
|
+
let cancelled = false
|
|
259
|
+
|
|
260
|
+
// 使用 subscribe 处理多次响应
|
|
261
|
+
userApi.getUser({
|
|
262
|
+
pathParams: { id: userId },
|
|
263
|
+
cache: { mode: CacheMode.FirstCache }
|
|
264
|
+
}).subscribe({
|
|
265
|
+
onData: (data, fromCache) => {
|
|
266
|
+
if (cancelled) return
|
|
267
|
+
setUser(data)
|
|
268
|
+
setIsStale(fromCache) // 标记是否为陈旧数据
|
|
269
|
+
setLoading(false)
|
|
270
|
+
},
|
|
271
|
+
onError: (error) => {
|
|
272
|
+
if (cancelled) return
|
|
273
|
+
console.error(error)
|
|
274
|
+
setLoading(false)
|
|
275
|
+
}
|
|
276
|
+
})
|
|
277
|
+
|
|
278
|
+
return () => { cancelled = true }
|
|
279
|
+
}, [userId])
|
|
280
|
+
|
|
281
|
+
if (loading) return <div>加载中...</div>
|
|
282
|
+
if (!user) return <div>用户不存在</div>
|
|
283
|
+
|
|
284
|
+
return (
|
|
285
|
+
<div>
|
|
286
|
+
{isStale && <span className="badge">数据更新中...</span>}
|
|
287
|
+
<h1>{user.name}</h1>
|
|
288
|
+
<p>{user.email}</p>
|
|
289
|
+
</div>
|
|
290
|
+
)
|
|
291
|
+
}
|
|
292
|
+
*/
|
|
293
|
+
}
|
|
133
294
|
// ============================================================================
|
|
134
295
|
// 类型错误示例
|
|
135
296
|
// ============================================================================
|
|
@@ -157,7 +318,26 @@ function typeErrors() {
|
|
|
157
318
|
// @ts-expect-error body not allowed for GET
|
|
158
319
|
simpleApi.getUser({ pathParams: { id: '1' }, body: {} });
|
|
159
320
|
}
|
|
321
|
+
/**
|
|
322
|
+
* 类型兼容性验证示例
|
|
323
|
+
*/
|
|
324
|
+
function verifyTypeCompatibility() {
|
|
325
|
+
const api = ApiBuilder.create({ baseUrl: 'http://test' })
|
|
326
|
+
.get('getUser', { path: '/users/{id}' })
|
|
327
|
+
.get('getUsers', { path: '/users' })
|
|
328
|
+
.post('createUser', { path: '/users' })
|
|
329
|
+
.put('updateUser', { path: '/users/{id}' })
|
|
330
|
+
.delete('deleteUser', { path: '/users/{id}' })
|
|
331
|
+
.build();
|
|
332
|
+
// ✅ 使用类型断言确保 API 符合定义
|
|
333
|
+
// 注意：由于 TypeScript 深层交叉类型限制，需要通过 unknown 进行断言
|
|
334
|
+
const typedApi = api;
|
|
335
|
+
// 现在可以获得精确的类型检查
|
|
336
|
+
typedApi.createUser({ body: { name: 'John', email: 'john@test.com' } });
|
|
337
|
+
typedApi.getUser({ pathParams: { id: '1' } });
|
|
338
|
+
console.log('Typed API:', typedApi);
|
|
339
|
+
}
|
|
160
340
|
// ============================================================================
|
|
161
341
|
// 导出
|
|
162
342
|
// ============================================================================
|
|
163
|
-
export { demo, typeErrors };
|
|
343
|
+
export { demo, typeErrors, verifyTypeCompatibility, cacheModeDemo, multiResponseWithForAwait, multiResponseWithSubscribe, singleResponseWithAwait, reactUsageExample, };
|
package/dist/http/index.d.ts
CHANGED
|
@@ -38,5 +38,5 @@
|
|
|
38
38
|
export { CacheMode, type CacheEntry, type ApiResult, type ApiCallback, type CacheConfig, type CacheKeyRequest, type HttpClientConfig, type RequestConfig, type ApiOptions, type DiskLruCacheConfig, type HttpCacheConfig, type CacheInterceptor, type CacheInterceptorContext, type CacheInterceptorResult, } from './types';
|
|
39
39
|
export { DiskLruCache, HttpCache } from './cache';
|
|
40
40
|
export { HttpClient, ApiStream } from './client';
|
|
41
|
-
export { ApiBuilder, type ApiEndpoint, type ApiDefinition } from './api';
|
|
41
|
+
export { ApiBuilder, type ApiEndpoint, type ApiDefinition, type ApiEndpointWithBody, type ApiEndpointWithoutBody, type ApiEndpointWithBodyRequired, type ApiEndpointWithBodyOptional, type Simplify, } from './api';
|
|
42
42
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/http/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EACH,SAAS,EACT,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,eAAe,EAEpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC9B,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAGjD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGhD,OAAO,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EACH,SAAS,EACT,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,eAAe,EAEpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC9B,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAGjD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGhD,OAAO,EACH,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,QAAQ,GAChB,MAAM,OAAO,CAAA"}
|
package/dist/http/index.js
CHANGED