Skip to content

Commit 4589afd

Browse files
cklwblovecklwblove
committed
feat: 更新 package.json 和 README.md，添加静态资源重试功能
1 parent 2300afa commit 4589afd

File tree

6 files changed

+9111
-51
lines changed

6 files changed

+9111
-51
lines changed

‎README.md‎

Lines changed: 141 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,165 @@
1-
# winjs-plugin-example
1+
# winjs-plugin-assets-retry
22

3-
Example plugin for WinJS.
3+
一个用于静态资源加载失败自动重试的 Winjs 插件，基于 [assets-retry](https://github.com/BetaSu/assets-retry) 库实现。
44

55
<p>
6-
<a href="https://npmjs.com/package/winjs-plugin-example">
7-
<img src="https://img.shields.io/npm/v/winjs-plugin-example?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" />
6+
<a href="https://npmjs.com/package/@winner-fed/plugin-assets-retry">
7+
<img src="https://img.shields.io/npm/v/@winner-fed/plugin-assets-retry?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" />
88
</a>
99
<img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="license" />
10-
<a href="https://npmcharts.com/compare/winjs-plugin-example?minimal=true"><img src="https://img.shields.io/npm/dm/winjs-plugin-example.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="downloads" /></a>
10+
<a href="https://npmcharts.com/compare/@winner-fed/plugin-assets-retry?minimal=true"><img src="https://img.shields.io/npm/dm/@winner-fed/plugin-assets-retry.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="downloads" /></a>
1111
</p>
1212

13-
## Usage
1413

15-
Install:
14+
## 功能特性
15+
16+
- 🔄 **自动重试**: 当 JS、CSS 等静态资源加载失败时自动重试
17+
- 🎯 **域名白名单**: 支持配置域名白名单，只对指定域名的资源进行重试
18+
- ⚙️ **可配置**: 支持自定义重试次数、重试逻辑和回调函数
19+
- 🚀 **开箱即用**: 零配置即可使用，提供合理的默认配置
20+
- 📊 **监控支持**: 提供成功/失败回调，便于监控和统计
21+
22+
## 安装
1623

1724
```bash
18-
npm add winjs-plugin-example -D
25+
npm install @winner-fed/plugin-assets-retry assets-retry
1926
```
2027

21-
Add plugin to your `.winrc.ts`:
28+
## 使用方法
29+
30+
### 1. 启用插件
31+
32+
在 `.winrc.ts` 文件中添加插件：
2233

23-
```ts
24-
// .winrc.ts
25-
export default {
26-
plugins: ['winjs-plugin-example'],
27-
// 开启配置
28-
example: {}
29-
};
34+
```typescript
35+
import { defineConfig } from 'win';
36+
37+
export default defineConfig({
38+
plugins: [require.resolve('@winner-fed/plugin-assets-retry')],
39+
assetsRetry: {
40+
// 配置选项
41+
}
42+
});
3043
```
3144

32-
## Options
45+
### 2. 配置选项
3346

34-
### foo
47+
```typescript
48+
export default defineConfig({
49+
plugins: [require.resolve('@winner-fed/plugin-assets-retry')],
50+
assetsRetry: {
51+
// 域名白名单，只有在此列表中的资源才会重试
52+
domain: [
53+
'https://cdn.example.com',
54+
'https://static.example.com'
55+
],
56+
57+
// 最大重试次数，默认为 3
58+
maxRetryCount: 3,
59+
60+
// 自定义重试逻辑
61+
onRetry: (currentUrl, originalUrl, retryCollector) => {
62+
console.log('重试中:', currentUrl);
63+
// 返回新的 URL 或 null
64+
return currentUrl;
65+
},
66+
67+
// 资源加载成功回调
68+
onSuccess: (currentUrl) => {
69+
console.log('加载成功:', currentUrl);
70+
},
71+
72+
// 资源加载失败回调
73+
onFail: (currentUrl) => {
74+
console.log('加载失败:', currentUrl);
75+
}
76+
}
77+
});
78+
```
79+
80+
## 配置项说明
81+
82+
| 参数 | 类型 | 默认值 | 描述 |
83+
|------|------|--------|------|
84+
| `domain` | `string[]` | `[]` | 域名白名单，只有在此列表中的资源才会重试 |
85+
| `maxRetryCount` | `number` | `3` | 每个资源的最大重试次数 |
86+
| `onRetry` | `function` | - | 自定义重试逻辑的回调函数 |
87+
| `onSuccess` | `function` | - | 资源加载成功的回调函数 |
88+
| `onFail` | `function` | - | 资源加载失败的回调函数 |
3589

36-
Some description.
90+
### 回调函数参数说明
91+
92+
#### onRetry 函数
93+
94+
```typescript
95+
type RetryFunction = (
96+
currentUrl: string, // 当前尝试的 URL
97+
originalUrl: string, // 原始 URL
98+
retryCollector: RetryStatistics | null // 重试统计信息
99+
) => string | null
100+
```
37101
38-
- Type: `string`
39-
- Default: `undefined`
40-
- Example:
102+
#### RetryStatistics 接口
41103
42-
```js
43-
export default {
44-
plugins: ['winjs-plugin-example'],
45-
// 开启配置
46-
example: {
47-
foo: 'bar'
104+
```typescript
105+
interface RetryStatistics {
106+
retryTimes: number; // 已重试次数
107+
succeeded: string[]; // 成功的 URL 列表
108+
failed: string[]; // 失败的 URL 列表
109+
}
110+
```
111+
112+
## 使用场景
113+
114+
1. **CDN 容灾**: 当主 CDN 服务出现问题时，自动切换到备用 CDN
115+
2. **网络波动**: 在网络不稳定环境下提升资源加载成功率
116+
3. **用户体验**: 减少因资源加载失败导致的白屏或功能异常
117+
4. **监控统计**: 通过回调函数收集资源加载失败的统计数据
118+
119+
## 高级用法
120+
121+
### 多域名容灾
122+
123+
```typescript
124+
export default defineConfig({
125+
assetsRetry: {
126+
domain: ['https://cdn1.example.com', 'https://cdn2.example.com'],
127+
onRetry: (currentUrl, originalUrl, retryCollector) => {
128+
// 切换到备用域名
129+
if (currentUrl.includes('cdn1.example.com')) {
130+
return currentUrl.replace('cdn1.example.com', 'cdn2.example.com');
131+
}
132+
return currentUrl;
133+
}
48134
}
49-
};
135+
});
50136
```
51137

52-
## License
138+
### 结合监控系统
139+
140+
```typescript
141+
export default defineConfig({
142+
assetsRetry: {
143+
domain: ['https://cdn.example.com'],
144+
onSuccess: (currentUrl) => {
145+
// 发送成功日志到监控系统
146+
monitor.success('assets-retry', { url: currentUrl });
147+
},
148+
onFail: (currentUrl) => {
149+
// 发送失败日志到监控系统
150+
monitor.error('assets-retry', { url: currentUrl });
151+
}
152+
}
153+
});
154+
```
155+
156+
## 注意事项
157+
158+
1. 本插件依赖 `assets-retry` 库，需要同时安装
159+
2. 只有在配置的域名白名单中的资源才会被重试
160+
3. CSS 中的背景图片目前不支持重试
161+
4. 重试逻辑在页面加载时自动注入，无需额外代码
162+
163+
## 许可证
53164

54165
[MIT](./LICENSE).

‎package.json‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,25 @@
11
{
2-
"name": "winjs-plugin-template",
2+
"name": "@winner-fed/plugin-assets-retry",
33
"keywords": [
44
"winjs",
55
"plugin",
6-
"template",
6+
"assets-retry",
7+
"static-assets",
8+
"retry",
9+
"cdn",
10+
"failover",
11+
"error-handling",
12+
"resource-loading",
713
"winner-fed",
8-
"winjs-dev",
9-
"rslib",
10-
"rsbuild",
1114
"typescript",
12-
"biome"
15+
"javascript",
16+
"css",
17+
"frontend"
1318
],
14-
"version": "0.0.0",
19+
"version": "1.0.0",
1520
"repository": {
1621
"type": "git",
17-
"url": "git+https://github.com/winjs-dev/winjs-plugin-template.git"
22+
"url": "git+https://github.com/winjs-dev/winjs-plugin-assets-retry.git"
1823
},
1924
"license": "MIT",
2025
"type": "module",
@@ -43,13 +48,17 @@
4348
"simple-git-hooks": {
4449
"pre-commit": "npm run lint:write"
4550
},
51+
"dependencies": {
52+
"serialize-javascript": "6.0.2"
53+
},
4654
"devDependencies": {
4755
"@biomejs/biome": "^2.1.1",
4856
"@playwright/test": "^1.53.2",
4957
"@rsbuild/core": "^1.4.2",
5058
"@rslib/core": "^0.10.4",
5159
"@types/node": "^22.15.34",
5260
"@winner-fed/winjs": "*",
61+
"@types/serialize-javascript": "5.0.4",
5362
"playwright": "^1.53.2",
5463
"simple-git-hooks": "^2.13.0",
5564
"typescript": "^5.8.3"
@@ -58,7 +67,8 @@
5867
"@winner-fed/winjs": "*"
5968
},
6069
"peerDependencies": {
61-
"@winner-fed/utils": "*"
70+
"@winner-fed/utils": "*",
71+
"assets-retry": "0.3.5"
6272
},
6373
"peerDependenciesMeta": {
6474
"@rsbuild/core": {

‎playground/.winrc.ts‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,23 @@ import { defineConfig } from 'win';
22

33
export default defineConfig({
44
plugins: ['../src'],
5-
example: {
6-
foo: 'bar',
7-
},
5+
assetsRetry: {
6+
// domain list, only resources in the domain list will be retried.
7+
domain: ['https://www.xxxx.cn', 'https://www.xxx.cn/namespace'],
8+
// maximum retry count for each asset, default is 3
9+
maxRetryCount: 3,
10+
// onRetry hook is how you can customize retry logic with, default is x => x
11+
onRetry (currentUrl) {
12+
return currentUrl
13+
},
14+
// for a given resource (except background-images in css),
15+
// either onSuccess or onFail will be eventually called to
16+
// indicate whether the resource has been successfully loaded
17+
onSuccess (currentUrl) {
18+
console.log('currentUrl', currentUrl)
19+
},
20+
onFail (currentUrl) {
21+
console.log(currentUrl)
22+
}
23+
}
824
});

‎playground/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@
1111
"preview": "win preview"
1212
},
1313
"dependencies": {
14-
"@winner-fed/winjs": "*"
14+
"@winner-fed/winjs": "*",
15+
"assets-retry": "0.3.5"
1516
},
1617
"devDependencies": {
1718
"typescript": "^5.0.3"

0 commit comments

Comments
 (0)