swpp-backends 3.1.0-beta1 → 3.1.0

package/README.md

@@ -4,55 +4,55 @@
 
 ## 什么是 swpp
 
-  swpp 是一个用于为网站快速生成一个高度可用的 [Service Worker](https://developer.mozilla.org/zh-CN/docs/Web/API/ServiceWorker) 的工具，旨在提高网站的可靠性、优化二次访问性能、提供离线浏览功能……
+swpp（Service Worker Plus Plus）是一个现代化的 Service Worker 生成工具，专注于为静态网站提供精准、高效的缓存控制和离线访问能力。
 
-  常用 SW 构建工具的对比：
+与传统的 Service Worker 工具相比，swpp 提供了更细粒度的控制能力和更灵活的配置选项，让开发者能够精确管理网站资源的缓存策略。
 
-|            | swpp@3 | swpp@2 | hexo-offline |
-|:----------:|:------:|:------:|:------------:|
-|    本地缓存    |   ✔️   |   ✔️   |      ✔️      |
-|   缓存增量更新   |   ✔️   |   ✔️   |      ❌       |
-|   缓存过期时间   |   ✔️   |   ❌    |      ✔️      |
-|   缓存大小限制   |   ❌    |   ❌    |      ✔️      |
-|    预缓存     |   ❌    |   ❌    |      ✔️      |
-| Request 篡改 |   ✔️   |   ✔️   |      ❌       |
-|   URL 竞速   |   ✔️   |   ✔️   |      ❌       |
-|   备用 URL   |   ✔️   |   ✔️   |      ❌       |
-|  204 阻塞响应  |   ✔️   |   ✔️   |      ❌       |
-|    逃生门     |   ✔️   |   ✔️   |      ❌       |
-|    请求合并    |   ❌    |   ✔️   |      ❌       |
-|    高度自由    |   ✔️   |   ✔️   |      ❌       |
-|     更新     |   活跃   |  停止维护  |   超过两年没有更新   |
+## 核心特性
 
-## swpp v2 与 v3 的区别
+### 精准缓存控制
+- **智能缓存规则匹配**：基于 URL 模式的精细化缓存策略配置
+- **缓存过期时间管理**：可为不同类型的资源设置独立的过期时间
+- **增量更新机制**：只更新发生变化的资源，避免全量刷新
 
-  swpp v3 对 swpp 的所有代码进行了完全的重构，现在代码逻辑更加的清晰。除了后台代码的差异，v3 还有以下一系列的改进：
+### 性能优化
+- **URL 竞速加载**：同时请求多个 CDN 源，使用最快响应的资源
+- **备用 URL 机制**：主资源加载失败时自动切换到备用地址
 
-- 完全定制化<br/>
-  现在您对 swpp 生成的 sw 拥有完全的控制权。在 v2 中，如果需要修改插件生成的 sw 的逻辑，您需要自行编写整个 sw 文件。<br/>
-  v3 中将 sw 文件的各个部分拆分到了环境变量中，这使得您可以通过配置文件覆盖 sw 文件中的任意一个部分，或者追加任意内容。
+### 高度可定制
+- **模块化配置**：将 Service Worker 功能拆分为独立的配置模块
+- **TypeScript 支持**：完整的类型定义，提供更好的开发体验
+- **全面开放**：允许用户修改生成的 Service Worker 文件中任意一处代码
 
-- 现代化配置<br/>
-  现在您可以使用 `ts` 语言编写配置文件，同时还可以选择使用 `ESM`。在 v2 中您必须使用 `CommonJS`。<br/>
-  同时使用内置的一系列 `define` 函数可以让您对配置的颗粒度进行更加完美的掌控。
+## swpp 与 hexo-offline 对比
 
-- 完善的类型<br/>
-  现在 swpp 提供了更加优雅的数据类型，以优化编写配置项、二次开发时的体验。
+> hexo-offline 是基于 Workbox 构建的 Hexo 插件，采用预缓存（precaching）的工作方式，与 swpp 的设计理念存在本质区别：
+> 
+> swpp 设计目标是在提供一系列内置的常用操作的前提下，尽可能地允许用户自定义 Service Worker 的行为，离线访问只是缓存控制产生的“副作用”；
+> hexo-offline 的设计目标是实现网站的离线访问。
 
-## 版本号
+| 特性       | swpp                 | hexo-offline      |
+|----------|----------------------|-------------------|
+| **核心技术** | 自研 Service Worker 框架 | 基于 Google Workbox |
+| **配置方式** | 可编程配置，支持 TypeScript  | JSON/CJS 配置文件     |
+| **缓存策略** | 细粒度 URL 规则匹配         | 文件扩展名模式匹配         |
+| **更新机制** | 智能增量更新               | 全量预缓存更新           |
+| **性能特性** | URL 竞速、备用地址          | 基础缓存策略            |
+| **定制能力** | 高度可定制，完全控制           | 零配置开箱即用           |
+| **适用场景** | 复杂网站、高性能要求           | 简单博客、快速部署         |
 
-&emsp;&emsp;目前 swpp v3 还在测试阶段，版本号全部采用 `3.0.0-alpha.<a><b><c>` 的格式：
+### 选择建议
 
-- `3.0.0` - 大版本号
-- `alpha` - 测试版本
-- `a` - 一级子版本号，变动时表明 API 或配置文件等内容发生了不向前兼容的变动
-- `b` - 二级子版本号，变动时表明添加了新的功能
-- `c` - 三级子版本号，变动时表明进行了漏洞修复
+如果你：
 
-&emsp;&emsp;当 `a` `b` `c` 的某一位达到两位数时，会在其中添加 `x` 表示分割。
+- 希望对动态资源（如 API 响应、用户内容）的缓存进行精细策略控制；
+- 重视代码的透明度和可审计性，希望完全理解底层逻辑；
+- 享受深入技术细节、亲手构建网络层控制逻辑的过程；
+- 在个人项目或技术实验中探索 Service Worker 的潜力
 
-## QQ 群
+那么 swpp 是一个非常值得一试的选择。
 
-&emsp;&emsp;注意：swpp 有且仅有下面的群是官方的：
+## 社区支持
 
-![QQ 群：545028909](/qrcode.jpg)
+- **GitHub Issues**：报告问题和功能请求
+- **QQ 群**：545028909（官方技术支持群）

package/dist/swpp/BasicActions.d.ts

@@ -7,7 +7,6 @@ export declare class BasicActions {
     private readonly isBuildServiceWorker;
     private readonly domJsPath;
     private readonly diffJsonPath;
-    private readonly disableTrack;
     /**
      * 构建一个基础的 swpp 行为封装器
      */
@@ -67,8 +66,6 @@ export interface BasicActionOptions {
     domJsPath?: string;
     /** diff.json 文件路径（相对于网站根目录，留空表示不生成） */
     diffJsonPath?: string;
-    /** 是否进行引用的静态分析，留空表示不进行（禁用静态分析后不能使用无限期缓存） */
-    trackLink?: boolean;
 }
 interface BuildFileInfo {
     key: BasicActionKey;

package/dist/swpp/BasicActions.js

@@ -12,7 +12,7 @@ class BasicActions {
      * 构建一个基础的 swpp 行为封装器
      */
     static async build(optional) {
-        const actions = new BasicActions(optional.context, optional.isServiceWorker, optional.domJsPath, optional.diffJsonPath, optional.trackLink !== true);
+        const actions = new BasicActions(optional.context, optional.isServiceWorker, optional.domJsPath, optional.diffJsonPath);
         await actions.configLoader.loadFromCode({
             compilationEnv: {
                 PUBLIC_PATH: (0, ConfigCluster_1.defineLazyInitConfig)((_, compilation) => {
@@ -22,12 +22,11 @@ class BasicActions {
         });
         return actions;
     }
-    constructor(context, isBuildServiceWorker, domJsPath, diffJsonPath, disableTrack) {
+    constructor(context, isBuildServiceWorker, domJsPath, diffJsonPath) {
         this.context = context;
         this.isBuildServiceWorker = isBuildServiceWorker;
         this.domJsPath = domJsPath;
         this.diffJsonPath = diffJsonPath;
-        this.disableTrack = disableTrack;
         this.configLoader = new ConfigLoader_1.ConfigLoader(this.context);
         /**
          * 各个文件的生成路径，为空则表示不生成（或配置未初始化）
@@ -40,12 +39,6 @@ class BasicActions {
             diffJson: null
         };
         this.buildCaches = {};
-        if (disableTrack) {
-            untils_1.utils.printInfo('Track', '链接追踪（静态分析）已被关闭，缓存主动更新已自动禁用，请勿使用永久缓存');
-        }
-        else {
-            untils_1.utils.printInfo('Track', '链接追踪（静态分析）已开启，如果发现行为异常请及时反馈');
-        }
     }
     /**
      * 加载一个配置文件或配置
@@ -82,57 +75,6 @@ class BasicActions {
         this.runtimeData = runtime;
         this.compilationData = compilation;
         this.configLoader = undefined;
-        if (this.disableTrack) {
-            const matcher = runtime.crossDep.read('matchCacheRule');
-            const checker = (text) => {
-                if (!text.includes('INFINITE_CACHE'))
-                    return true;
-                const list = text.replaceAll('\r', '').split('\n');
-                let inStr = '';
-                let inComment = false;
-                o: for (let string of list) {
-                    for (let i = 0; i < string.length; i++) {
-                        if (inStr) {
-                            if (string[i] == inStr)
-                                inStr = '';
-                        }
-                        else if (inComment) {
-                            if (string[i] == '*' && string[i + 1] === '/') {
-                                inComment = false;
-                                ++i;
-                            }
-                        }
-                        else {
-                            switch (string[i]) {
-                                case '"':
-                                case '`':
-                                case `"`:
-                                    inStr = string[i];
-                                    continue;
-                                case '/':
-                                    if (string[i + 1] === '*') {
-                                        inComment = true;
-                                    }
-                                    else if (string[i + 1] === '/') {
-                                        continue o;
-                                    }
-                                    break;
-                                default:
-                                    if (string.startsWith('INFINITE_CACHE', i)) {
-                                        return false;
-                                    }
-                                    break;
-                            }
-                        }
-                    }
-                }
-                return true;
-            };
-            if (!checker(matcher.runOnBrowser.toString())) {
-                throw new untils_1.RuntimeException(untils_1.exceptionNames.unsupportedOperate, '禁用引用链分析时禁止在 matchCacheRule 返回 INFINITE_CACHE。' +
-                    '如果您没有返回该值，可能是由于存在与该字段同名的变量或其它内容，从而导致 SWPP 误判，请您修改与 INFINITE_CACHE 重复的名称。');
-            }
-        }
         const compilationEnv = compilation.compilationEnv;
         const publicRoot = compilationEnv.read('PUBLIC_PATH');
         const jsonInfo = compilationEnv.read('SWPP_JSON_FILE');
@@ -220,17 +162,6 @@ class BasicActions {
      * @param excludeFilter 需排除的文件
      */
     async saveFiles(excludeFilter = []) {
-        if (this.disableTrack) {
-            if (!excludeFilter.includes('tracker')) {
-                excludeFilter.push('tracker');
-            }
-            if (!excludeFilter.includes('version')) {
-                excludeFilter.push('version');
-            }
-            if (!excludeFilter.includes('diffJson')) {
-                excludeFilter.push('diffJson');
-            }
-        }
         const fileList = await this.buildFiles(excludeFilter);
         for (let item of fileList) {
             if (await item.path.exists()) {

package/dist/swpp/FilePath.d.ts

@@ -39,6 +39,10 @@ export declare class FilePath {
      * @param consumer
      */
     walkAllFile(consumer: (filePath: FilePath) => Promise<void> | void): Promise<void>;
+    /**
+     * 获取文件名
+     */
+    fileName(): string;
     /**
      * 获取上一级目录
      */

package/dist/swpp/FilePath.js

@@ -91,6 +91,12 @@ class FilePath {
             }
         } while (queue.length);
     }
+    /**
+     * 获取文件名
+     */
+    fileName() {
+        return path_1.default.posix.basename(this.absPath);
+    }
     /**
      * 获取上一级目录
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swpp-backends",
-  "version": "3.1.0-beta1",
+  "version": "3.1.0",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
   "description": "Generate a powerful ServiceWorker for your website.",