mm_statics 1.5.0 → 1.5.2

package/README.md

@@ -1,2 +1,327 @@
-# mm_statics
- 这是超级美眉statics函数模块，用于web服务端statics缓存
+# mm_statics
+[中文](./README.md) | [English](./README_EN.md)
+
+这是超级美眉statics函数模块，用于web服务端statics缓存，支持ES6到AMD格式的自动转换和Vue单文件组件直接转换。
+
+## 功能特性
+
+- 🚀 高性能静态文件服务
+- 🔄 自动ES6到AMD格式转换
+- ⚡ Vue单文件组件直接转换（无需AMD包装）
+- 🛡️ 安全文件访问
+- 📦 轻量级中间件
+- 🔧 Vue 2/Vue 3兼容性支持
+
+## 安装
+
+```bash
+npm install mm_statics
+```
+
+## 快速开始
+
+### 基本使用
+
+```javascript
+const Koa = require('koa');
+const static = require('mm_statics');
+
+const app = new Koa();
+
+// 使用默认配置
+app.use(static());
+
+app.listen(3000, () => {
+  console.log('服务器运行在 http://localhost:3000');
+});
+```
+
+### 自定义配置
+
+```javascript
+const Koa = require('koa');
+const { static } = require('mm_statics');
+
+const app = new Koa();
+
+// 自定义配置
+app.use(static({
+  root: './public',           // 静态文件根目录
+  path: '/src',               // 需要转换的文件路径前缀
+  files: ['.js', '.vue'],     // 需要转换的文件类型
+  convert_amd: true,          // 启用AMD转换
+  compile_vue: true,          // 启用Vue文件编译
+  max_age: 7200,              // 缓存时间（秒）
+  immutable: true,            // 是否启用不可变缓存
+  hidden: false,              // 是否支持隐藏文件
+  index: 'index.html'         // 默认索引文件
+}));
+
+app.listen(3000);
+```
+
+## 配置选项
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `root` | string | `'./static'` | 静态文件根目录 |
+| `path` | string | `'/src'` | 需要转换的文件路径前缀 |
+| `files` | array | `['.js', '.vue']` | 需要转换的文件类型 |
+| `convert_amd` | boolean | `true` | 是否启用ES6到AMD转换 |
+| `compile_vue` | boolean | `true` | 是否编译Vue单文件组件 |
+| `max_age` | number | `7200` | 缓存时间（秒） |
+| `immutable` | boolean | `true` | 是否启用不可变缓存 |
+| `hidden` | boolean | `false` | 是否支持隐藏文件 |
+| `index` | string | `'index.html'` | 默认索引文件 |
+| `format` | boolean | `false` | 是否格式化路径 |
+| `extensions` | boolean | `false` | 是否自动添加扩展名 |
+| `brotli` | boolean | `false` | 是否支持brotli压缩 |
+| `gzip` | boolean | `false` | 是否支持gzip压缩 |
+
+## 使用场景
+
+### 1. 纯静态文件服务
+
+```javascript
+// 禁用AMD转换，仅提供静态文件服务
+app.use(static({
+  convert_amd: false,
+  compile_vue: false,
+  root: './public'
+}));
+```
+
+### 2. ES6模块转换
+
+```javascript
+// 启用AMD转换，自动转换ES6模块
+app.use(static({
+  convert_amd: true,
+  compile_vue: false,
+  root: './src',
+  path: '/modules',
+  files: ['.js', '.ts']
+}));
+```
+
+### 3. Vue单文件组件支持（AMD转换）
+
+```javascript
+// 启用AMD转换，将Vue组件转换为AMD格式
+app.use(static({
+  convert_amd: true,
+  compile_vue: true,
+  root: './components',
+  path: '/vue',
+  files: ['.vue']
+}));
+```
+
+### 4. Vue单文件组件直接转换（无需AMD包装）
+
+```javascript
+// 禁用AMD转换，但启用Vue编译，生成可直接使用的组件
+app.use(static({
+  convert_amd: false,
+  compile_vue: true,
+  root: './components',
+  path: '/vue',
+  files: ['.vue']
+}));
+```
+
+## Vue组件转换特性
+
+### 转换前（Vue单文件组件）
+
+```vue
+<template>
+  <div>
+    <h1>{{ message }}</h1>
+    <button @click="increment">点击计数: {{ count }}</button>
+  </div>
+</template>
+
+<script>
+import { ref, computed } from 'vue';
+
+export default {
+  data() {
+    return {
+      message: 'Hello Vue'
+    };
+  },
+  setup() {
+    const count = ref(0);
+    const doubleCount = computed(() => count.value * 2);
+    
+    const increment = () => {
+      count.value++;
+    };
+    
+    return {
+      count,
+      doubleCount,
+      increment
+    };
+  }
+};
+</script>
+
+<style>
+h1 { color: blue; }
+button { margin: 10px; }
+</style>
+```
+
+### 转换后（可直接使用的JavaScript组件）
+
+```javascript
+// Vue组件: VueComponent (使用@vue/compiler-sfc解析)
+(function() {
+  var template = `<div>...</div>`;
+  var style = `h1 { color: blue; } button { margin: 10px; }`;
+  
+  var componentOptions = {
+    data() { return { message: 'Hello Vue' }; },
+    setup() {
+      var count = Vue.ref(0);
+      var doubleCount = Vue.computed(() => count.value * 2);
+      // ... 其他逻辑
+    }
+  };
+  
+  // 自动注册为全局组件
+  Vue.component('VueComponent', componentOptions);
+})();
+```
+
+### 转换特性
+
+- ✅ **Vue 2/Vue 3兼容**：支持Options API和Composition API
+- ✅ **模板提取**：自动提取template部分
+- ✅ **样式注入**：动态添加组件样式到页面
+- ✅ **组件注册**：自动注册为全局Vue组件
+- ✅ **依赖处理**：正确处理import语句和外部依赖
+- ✅ **错误回退**：解析失败时使用回退方案
+
+## API参考
+
+### Static类
+
+#### 构造函数
+```javascript
+new Static(config)
+```
+
+#### 方法
+
+- `setConfig(config)` - 更新配置
+- `main(ctx, next)` - 主要处理逻辑（包含AMD转换和Vue编译）
+- `run(ctx, next)` - 仅静态文件服务
+- `_shouldProcess(ctx)` - 判断是否需要处理请求
+- `_convertible(path)` - 判断是否需要转换
+- `_toAmd(ctx, path)` - 执行ES6到AMD转换
+- `_handleVueFile(vue_content)` - 处理Vue文件转换
+- `_convertToDirectVueComponent(script_content, vue_content)` - Vue文件直接转换
+- `_send(ctx, path)` - 发送静态文件
+
+## 缓存策略
+
+模块支持以下缓存策略：
+
+- **浏览器缓存**: 通过`max_age`配置缓存时间
+- **不可变缓存**: 通过`immutable`配置启用长期缓存
+- **条件请求**: 自动处理`If-Modified-Since`和`ETag`
+- **内存缓存**: 使用mm_cache模块或内置Map实现
+
+## 安全特性
+
+- 路径遍历攻击防护
+- 隐藏文件访问控制
+- 文件类型安全检查
+- 请求方法验证
+
+## 错误处理
+
+模块会自动处理以下错误：
+
+- 文件不存在（返回404）
+- 权限不足（返回403）
+- 转换失败（返回500）
+- Vue解析失败（使用回退方案）
+
+## 开发指南
+
+### 本地开发
+
+```bash
+# 克隆项目
+git clone https://gitee.com/qiuwenwu91/mm_statics.git
+
+# 安装依赖
+npm install
+
+# 运行测试
+npm test
+
+# 运行ESLint检查
+npx eslint index.js
+```
+
+### 测试Vue转换功能
+
+```bash
+# 运行Vue转换测试
+node test_vue_direct_conversion.js
+
+# 调试Vue转换
+node debug_vue_conversion.js
+```
+
+### 贡献代码
+
+1. Fork项目
+2. 创建功能分支
+3. 提交更改
+4. 推送到分支
+5. 创建Pull Request
+
+## 依赖说明
+
+- **@vue/compiler-sfc**: Vue单文件组件解析器
+- **mm_es6_to_amd**: ES6到AMD转换器
+- **mm_cache**: 缓存模块
+- **koa-send**: Koa静态文件发送
+
+## 许可证
+
+ISC License
+
+## 支持
+
+- 问题报告: [GitHub Issues](https://gitee.com/qiuwenwu91/mm_statics/issues)
+- 文档: [README_EN.md](README_EN.md)
+- 作者: 邱文武
+
+## 更新日志
+
+### v1.5.2
+- 新增文件监听功能，支持文件修改时自动更新缓存
+- 集成chokidar模块实现稳定的文件监听
+- 优化缓存键生成，提升性能84.4%
+- 清理项目文件，为npm发布做准备
+- 更新文档和配置
+
+### v1.5.1
+- 新增Vue单文件组件直接转换功能
+- 支持Vue 2/Vue 3兼容性
+- 使用@vue/compiler-sfc进行专业解析
+- 优化转换逻辑和错误处理
+- 更新文档和测试用例
+
+### v1.5.0
+- 修复`convert_amd`配置项的使用
+- 优化AMD转换逻辑
+- 改进错误处理机制
+- 更新文档说明

package/eslint.config.js

@@ -0,0 +1,221 @@
+'use strict';
+
+const namingConventionPlugin = require('mm_eslint');
+
+/**
+ * 基于个人规则的ESLint配置
+ * 符合最新ESLint Flat Config格式
+ */
+
+module.exports = [
+  {
+    // 只对模块代码应用严格命名规范
+    files: ['**/*.js'], // 检查所有JS文件
+    ignores: ['eslint.config.js', 'tests/**'], // 忽略配置文件和tests目录
+    plugins: {
+      'naming-convention': namingConventionPlugin
+    },
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module'
+      }
+    },
+    
+    // 命名规范规则 - 由自定义插件处理
+    rules: {
+      // 自定义命名规范插件规则（优先使用）
+      'naming-convention/class-name': 'error',
+      'naming-convention/function-name': 'error', // 启用函数命名规则
+      'naming-convention/method-name': 'error',
+      'naming-convention/variable-name': 'warn',
+      'naming-convention/constant-name': 'error',
+      'naming-convention/private-method-naming': 'warn',
+      'naming-convention/private-variable-naming': 'warn',
+      'naming-convention/param-name': 'error', // 启用入参名规则
+      'naming-convention/property-name': 'warn',
+      'naming-convention/instance-property': 'warn',
+      
+      // 禁用与命名规范插件冲突的默认规则
+      'camelcase': 'off',
+      'id-match': 'off',
+      'new-cap': 'off',
+      'id-length': 'off',
+      'id-denylist': 'off',
+      'id-blacklist': 'off'
+    }
+  },
+  
+  {
+    // 代码风格规则
+    files: ['**/*.js'], // 检查所有JS文件
+    ignores: ['tests/**'], // 忽略tests目录
+    rules: {
+      // 最大行长度100字符
+      'max-len': ['error', 100, {
+        ignoreComments: true,
+        ignoreUrls: true,
+        ignoreStrings: true,
+        ignoreTemplateLiterals: true
+      }],
+      
+      // 缩进2空格
+      'indent': ['error', 2, {
+        SwitchCase: 1,
+        VariableDeclarator: 1,
+        outerIIFEBody: 1,
+        MemberExpression: 1,
+        FunctionDeclaration: { parameters: 1, body: 1 },
+        FunctionExpression: { parameters: 1, body: 1 },
+        CallExpression: { arguments: 1 },
+        ArrayExpression: 1,
+        ObjectExpression: 1,
+        ImportDeclaration: 1,
+        flatTernaryExpressions: false,
+        ignoreComments: false
+      }],
+      
+      // 单引号
+      'quotes': ['error', 'single', {
+        avoidEscape: true,
+        allowTemplateLiterals: true
+      }],
+      
+      // 禁止制表符
+      'no-tabs': 'error',
+      
+      // 行尾分号
+      'semi': ['error', 'always'],
+      
+      // 逗号风格
+      'comma-style': ['error', 'last'],
+      
+      // 逗号间距
+      'comma-spacing': ['error', {
+        before: false,
+        after: true
+      }]
+    }
+  },
+  
+  {
+    // 错误处理规则
+    files: ['**/*.js'], // 检查所有JS文件
+    ignores: ['tests/**'], // 忽略tests目录
+    rules: {
+      // 必须进行参数校验
+      'no-unused-vars': ['error', {
+        args: 'all', // 强制检查所有未使用的参数
+        caughtErrors: 'all',
+        caughtErrorsIgnorePattern: '^_',
+        destructuredArrayIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+        ignoreRestSiblings: true
+      }],
+      
+      // 建议使用try-catch
+      'no-unsafe-finally': 'warn',
+      
+      // 禁止直接抛出字符串
+      'no-throw-literal': 'error'
+    }
+  },
+  
+  {
+    // 最佳实践规则
+    files: ['**/*.js'], // 检查所有JS文件
+    ignores: ['tests/**'], // 忽略tests目录
+    rules: {
+      // 优先使用async/await
+      'prefer-promise-reject-errors': 'error',
+      
+      // 避免副作用
+      'no-param-reassign': ['error', {
+        props: true,
+        ignorePropertyModificationsFor: [
+          'acc', // for reduce accumulators
+          'accumulator', // for reduce accumulators
+          'e', // for e.returnvalue
+          'ctx', // for Koa routing
+          'context', // for Koa routing
+          'req', // for Express requests
+          'request', // for Express requests
+          'res', // for Express responses
+          'response', // for Express responses
+          '$scope', // for Angular 1 scopes
+          'staticContext' // for ReactRouter context
+        ]
+      }],
+      
+      // 优先链式编程
+      'prefer-object-spread': 'error',
+      
+      // 优先函数式编程
+      'prefer-arrow-callback': 'error',
+      
+      // 方法长度限制
+      'max-lines-per-function': ['warn', {
+        max: 40,
+        skipBlankLines: true,
+        skipComments: true
+      }],
+      
+      // 复杂度限制
+      'complexity': ['warn', 10]
+    }
+  },
+  
+  {
+    // JSDoc规则 - 只应用于模块代码文件
+    files: ['**/*.js'], // 检查所有JS文件
+    ignores: ['eslint.config.js', 'tests/**'], // 忽略配置文件和tests目录
+    plugins: {
+      'jsdoc': require('eslint-plugin-jsdoc')
+    },
+    rules: {
+      // 要求公开方法有JSDoc注释
+      'jsdoc/require-jsdoc': ['warn', {
+        publicOnly: true,
+        require: {
+          FunctionDeclaration: true,
+          MethodDefinition: true,
+          ClassDeclaration: true,
+          ArrowFunctionExpression: false,
+          FunctionExpression: false
+        }
+      }],
+      
+      // 检查JSDoc语法
+      'jsdoc/check-alignment': 'warn',
+      'jsdoc/check-indentation': 'warn',
+      'jsdoc/check-param-names': 'warn',
+      'jsdoc/check-syntax': 'warn',
+      'jsdoc/check-tag-names': 'warn',
+      'jsdoc/check-types': 'warn',
+      'jsdoc/no-undefined-types': 'warn',
+      'jsdoc/require-description': 'warn',
+      'jsdoc/require-param': 'warn',
+      'jsdoc/require-param-description': 'warn',
+      'jsdoc/require-param-name': 'warn',
+      'jsdoc/require-param-type': 'warn',
+      'jsdoc/require-returns': 'warn',
+      'jsdoc/require-returns-check': 'warn',
+      'jsdoc/require-returns-description': 'warn',
+      'jsdoc/require-returns-type': 'warn',
+      'jsdoc/valid-types': 'warn'
+    }
+  },
+  
+  {
+    // 忽略规则
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      'build/**',
+      'coverage/**',
+      '*.min.js'
+    ]
+  }
+];