17 KiB

Raw Permalink Blame History

Vite插件开发需求文档：Turborepo工作区编译部署自动化工具

一、项目概述

项目名称：vite-plugin-turborepo-deploy
目标：开发一个Vite插件，实现Turborepo工作区编译后的自动化部署流程，涵盖本地文件同步、Git项目管理（包含可选的智能化自动提交功能，并支持提交信息在项目间共享）。

二、功能需求

1. 本地文件同步功能

配置方式：支持在插件配置中定义多个本地文件/目录同步任务
同步模式：
- copy：简单复制，不处理目标目录已存在文件
- mirror：镜像同步，删除目标目录中不存在于源的文件
- incremental：增量更新，仅覆盖已变更文件
清空目标目录：支持通过clearTarget字段在同步前清空目标目录
全新添加模式：支持addOnly字段，仅新增源中存在而目标中不存在的文件/目录
过滤规则：
- exclude：支持通过正则表达式排除特定文件/目录
- excludeDirs：指定排除的目录（支持glob或正则）
- excludeFiles：指定排除的文件（支持glob或正则）
路径解析：所有相对路径自动基于项目根目录解析

2. Git项目管理与自动提交功能

多项目支持：可配置多个Git项目的拉取/更新任务。
分支管理：支持指定拉取分支，自动切换到目标分支。
目录管理：
- 支持自定义项目存放目录。
- 支持重命名项目目录（通过projectName字段）。
自动操作：
- 检测项目是否存在：存在则执行git pull更新，不存在则执行git clone。
- 拉取前自动切换到指定分支。
- 支持私有仓库（通过SSH密钥或HTTPS认证）。
可选的自动提交 (Per-Project Auto Commit)：
- 启用方式：在每个Git项目配置中，通过autoCommit对象启用和配置。
- 智能提交检测机制（用于填充共享缓冲区或单个项目扫描）：
  - 开发者监听：通过配置指定需要监听的开发者用户名（对应Git配置中的user.name）。
  - 提交记录扫描：
    - 默认扫描最近50条提交记录（可通过配置调整）。
    - 按时间倒序扫描，优先获取最新提交。
  - 提交分隔符：使用特殊标记（默认/** 提交分隔符 **/）识别分段点。
  - 双模式处理：
    - 模式1：存在分隔符时，获取分隔符之后的所有提交。
    - 模式2：不存在分隔符时，获取最近一条指定开发者的提交。
- 共享提交信息机制 (Shared Commit Buffer):
  - 目的：当多个Git项目基于同一组源变更（如主仓库的特定开发者提交）进行自动提交时，允许一次获取提交信息并复用。
  - 信息来源：在gitProjects任务执行期间，第一个成功通过"智能提交检测机制"获取到提交信息的项目，其结果将被缓存为"共享提交信息"。
  - 信息使用：后续的Git项目若在其autoCommit配置中设置了useSharedCommits: true，则会尝试使用此共享信息。若共享信息为空，或项目未配置使用，则回退到独立扫描其自身仓库。
  - 生命周期：共享提交信息在每次updateGitProjects任务开始时清空。
- 提交信息生成：
  - 若项目配置为使用共享提交信息且缓冲区存在内容，则直接使用。
  - 否则，使用从当前项目独立扫描获取的提交信息。
  - 合并多条提交时，采用特定格式：
```
[自动合并] 包含N次提交:

1. [commitHash1] commitMessage1
2. [commitHash2] commitMessage2
...

/** 提交分隔符 **/
```
- 提交后操作：无论是否使用共享信息，自动提交成功后，都在当前Git项目的当前分支插入一条新的、空的提交分隔符记录。
- 错误处理（针对单个项目的自动提交过程）：
  - 无匹配提交：若独立扫描未找到指定开发者的任何提交，在该项目中抛出警告但继续执行后续任务。
  - 重复分隔符：若检测到连续两条分隔符提交，自动清理冗余记录。
  - 提交冲突：在提交前检查工作区状态，存在未提交变更时抛出错误并跳过该项目的自动提交。
- 推送：支持配置是否在自动提交后推送到远程仓库的对应分支。

3. 任务编排系统

顺序执行：支持按数组顺序依次执行配置的任务。
内置任务：
- localSync：执行本地文件同步。
- updateGitProjects：更新所有Git项目（如果项目配置了自动提交，则在此阶段执行，包括处理共享提交信息逻辑）。
扩展机制：支持自定义任务（通过插件钩子）。

4. 日志记录系统

日志文件：
- 自动在项目根目录下创建.sync-log目录。
- 按日期生成日志文件（如2023-05-15_deploy.log）。
日志级别：
- error：仅记录错误信息。
- info：记录关键步骤信息。
- verbose：记录详细执行过程（默认）。
控制台输出：
- 彩色日志显示。
- 关键步骤进度提示。

三、技术实现要求

1. 基础架构

开发语言：TypeScript，所有源码必须为.ts或.tsx文件，禁止使用any类型。
Node.js 版本：要求 Node.js 16 及以上，推荐 LTS 版本，需兼容 ESM。
Vite 版本：兼容 Vite 3.x 及以上，插件需遵循 Vite 官方插件开发规范。
插件类型：构建后插件（在buildEnd钩子触发），需支持异步任务。
依赖管理：使用 pnpm/yarn/npm，推荐 pnpm，所有依赖需锁定版本。

2. 代码规范与最佳实践

类型安全：全量使用 TypeScript 接口，避免类型推断不明确。
函数式编程：优先使用函数式、声明式风格，避免类和全局变量。
模块化：每个功能模块单独文件，导出命名函数，禁止默认导出。
注释规范：所有导出函数、接口、类型需使用 JSDoc 注释，描述参数、返回值和用途。
错误处理：所有异步操作需捕获异常，关键错误需中断流程并输出详细日志。
日志系统：日志输出需支持彩色（chalk），并写入.sync-log目录下的日志文件，日志内容需结构化，便于后续分析。

3. 性能与兼容性

异步并发：文件同步、Git 操作等 IO 密集型任务需支持并发，合理控制并发数，避免资源争用。
跨平台：需兼容 Windows、Linux、macOS，路径处理需使用 Node.js path 模块。
配置热重载：插件配置变更后，支持自动重载，无需重启 Vite 服务。
资源优化：插件自身体积需控制在合理范围，避免引入过大依赖。

4. 插件接口与类型定义

类型导出：所有配置接口需导出，便于用户类型推断和 IDE 智能提示。
配置校验：插件初始化时需校验用户配置，发现错误需抛出详细异常。
Vite 插件约定：导出标准 Vite 插件对象，支持链式调用和多插件组合。

5. 依赖与工具

fs-extra：文件操作
simple-git：Git 命令封装
chalk：控制台彩色输出
ora：进度指示器
zod 或 joi：配置校验（推荐 zod）

6. 测试与质量保障

单元测试：使用 Vitest 或 Jest，覆盖率需达 80% 以上。
集成测试：模拟完整部署流程，验证各功能模块协作。
CI/CD：集成 GitHub Actions，自动化测试、构建和发布。

四、交互与输出

1. 控制台输出示例

🚀 [Turborepo Deploy] 开始执行部署流程...

🔄 正在同步本地文件...
   ✅ 已同步 dist → ../deploy/public (mirror模式)
   ✅ 已同步 src/assets → ../deploy/assets (incremental模式)

🔄 正在更新Git项目...
   ⏳ 正在处理 api-gateway (分支: develop)...
      ✅ 已更新至最新版本 (commit: abc123)
      ✨ 开始执行 api-gateway 的自动提交 (作为共享信息源)...
         ✅ 已扫描最近50条提交记录, 找到提交分隔符（位于 commit: abc123）
         ✅ 识别到3条待同步提交, 已存入共享缓冲区。
            - [def456] 修复登录验证问题
            - [ghi789] 优化API响应格式
            - [jkl012] 添加用户头像上传功能
         ✅ 已合并提交 (commit: mno345) 并推送到远程 (develop)
         ✅ 已在 api-gateway (develop) 插入新的提交分隔符 (commit: pqr678)
   ⏳ 正在处理 user-service (分支: feature/new-endpoint)...
      ✅ 已更新至最新版本 (commit: stu789)
      ✨ 开始执行 user-service 的自动提交 (使用共享信息)...
         ✅ 使用了来自 api-gateway 的3条共享提交信息。
         ✅ 已合并提交 (commit: vwx123) 并推送到远程 (feature/new-endpoint)
         ✅ 已在 user-service (feature/new-endpoint) 插入新的提交分隔符 (commit: yz034)
   ⏳ 正在处理 another-service (分支: main)...
      ✅ 已更新至最新版本 (commit: bcd234)
      ✨ 开始执行 another-service 的自动提交 (独立扫描)...
         ✅ 未找到指定开发者或分隔符的提交，未执行自动提交。

✅ [Turborepo Deploy] 部署完成！

2. 日志文件格式

[2023-05-15T14:30:21.123Z] [INFO] 开始执行部署流程...
[2023-05-15T14:30:21.456Z] [INFO] 正在同步本地文件...
[2023-05-15T14:30:23.789Z] [INFO] 已同步 dist → ../deploy/public (mirror模式)
[2023-05-15T14:30:25.012Z] [INFO] 已同步 src/assets → ../deploy/assets (incremental模式)
[2023-05-15T14:30:25.345Z] [INFO] 正在更新Git项目...
[2023-05-15T14:30:25.678Z] [INFO] [api-gateway] 正在处理项目 (分支: develop)...
[2023-05-15T14:30:30.234Z] [INFO] [api-gateway] 已更新至最新版本 (commit: abc123)
[2023-05-15T14:30:30.500Z] [INFO] [api-gateway] 开始执行自动提交 (作为共享信息源)...
[2023-05-15T14:30:31.890Z] [INFO] [api-gateway] 已扫描最近50条提交记录, 找到提交分隔符（位于 commit: abc123）
[2023-05-15T14:30:32.123Z] [INFO] [api-gateway] 识别到3条待同步提交, 已存入共享缓冲区。
[2023-05-15T14:30:32.456Z] [INFO] [api-gateway]    - [def456] 修复登录验证问题
[2023-05-15T14:30:32.789Z] [INFO] [api-gateway]    - [ghi789] 优化API响应格式
[2023-05-15T14:30:33.012Z] [INFO] [api-gateway]    - [jkl012] 添加用户头像上传功能
[2023-05-15T14:30:35.678Z] [INFO] [api-gateway] 已合并提交 (commit: mno345) 并推送到远程 (develop)
[2023-05-15T14:30:36.901Z] [INFO] [api-gateway] 已插入新的提交分隔符 (commit: pqr678)
[2023-05-15T14:30:37.100Z] [INFO] [user-service] 正在处理项目 (分支: feature/new-endpoint)...
[2023-05-15T14:30:40.234Z] [INFO] [user-service] 已更新至最新版本 (commit: stu789)
[2023-05-15T14:30:40.500Z] [INFO] [user-service] 开始执行自动提交 (使用共享信息)...
[2023-05-15T14:30:40.501Z] [INFO] [user-service] 使用了来自 api-gateway 的3条共享提交信息。
[2023-05-15T14:30:43.678Z] [INFO] [user-service] 已合并提交 (commit: vwx123) 并推送到远程 (feature/new-endpoint)
[2023-05-15T14:30:44.901Z] [INFO] [user-service] 已插入新的提交分隔符 (commit: yz034)
[2023-05-15T14:30:45.000Z] [INFO] [another-service] 正在处理项目 (分支: main)...
[2023-05-15T14:30:50.000Z] [INFO] 部署完成！

五、使用示例

// vite.config.ts
import { defineConfig } from 'vite';
import turborepoDeploy from 'vite-plugin-turborepo-deploy';

export default defineConfig({
  plugins: [
    turborepoDeploy({
      localSync: [
        { source: 'dist', target: '../deploy/public', mode: 'mirror', clearTarget: true },
        { source: 'src/assets', target: '../deploy/assets', excludeDirs: ['**/tmp'], excludeFiles: ['**/*.psd'] }
      ],
      gitProjects: [
        {
          repo: 'git@github.com:example-org/api-gateway.git',
          branch: 'develop',
          targetDir: 'services/api-gateway',
          projectName: 'api-gateway', // 用于日志中清晰标识源
          autoCommit: { // 此项目将作为共享提交信息的来源
            enabled: true,
            watchAuthor: '张三',
            maxScanCount: 100,
            commitSeparator: '/** AUTO MERGE MARK **/',
            message: 'chore(api-gateway): auto merge [skip ci]',
            push: true
            // useSharedCommits: false, // 或不设置，默认为false，它会尝试填充共享区
          }
        },
        {
          repo: 'git@github.com:example-org/user-service.git',
          branch: 'feature/new-endpoint',
          targetDir: 'services/user-service',
          projectName: 'user-service',
          autoCommit: { // 此项目将使用共享的提交信息
            enabled: true,
            useSharedCommits: true, // 明确指定使用共享信息
            // watchAuthor, maxScanCount, commitSeparator 在此模式下可不填，若填写了则在共享区为空时作为回退
            message: 'chore(user-service): auto sync from upstream [skip ci]',
            push: true
          }
        },
        {
          repo: 'git@github.com:example-org/another-service.git',
          branch: 'main',
          targetDir: 'services/another-service',
          projectName: 'another-service',
          autoCommit: { // 此项目独立进行提交检测
            enabled: true,
            watchAuthor: '李四', // 不同的开发者或标准
            message: 'chore(another-service): auto merge [skip ci]',
            push: false // 可能只提交不推送
          }
        }
      ],
      taskOrder: ['localSync', 'updateGitProjects']
    })
  ]
});

六、测试要求

1. 单元测试

验证文件同步逻辑（包括清空、仅新增、过滤规则）。
验证Git项目管理核心操作（克隆、拉取、分支切换）。
验证针对单个Git项目的自动提交智能检测逻辑（包括开发者监听、分隔符处理、提交信息生成、提交后操作）。
验证共享提交信息缓冲机制：
- 源项目成功获取并缓存提交信息。
- 后续项目配置useSharedCommits: true时能正确使用缓存信息。
- 当共享缓冲为空时，配置了useSharedCommits: true的项目能正确回退到独立扫描（或按配置跳过）。
- 未配置useSharedCommits: true的项目不受共享缓冲影响。
验证任务编排顺序。

2. 集成测试

模拟完整部署流程，包含多个Git项目，组合使用独立提交、共享提交源、共享提交消费者等场景。
验证日志记录功能，清晰反映各项目的提交方式（独立、共享、来源）。
测试不同场景下单个Git项目的自动提交（有分隔符、无分隔符、无匹配提交、提交冲突、推送成功/失败），包括作为共享源和消费者的不同行为。

3. 边缘情况测试

文件冲突处理。
Git项目不存在或认证失败。
网络异常处理。
单个Git项目中重复提交分隔符处理。
共享提交信息在任务开始时被正确清空。

七、交付物

源代码：完整的TypeScript源码
文档：
- 使用说明
- 配置参数文档
- 开发指南
测试用例：单元测试和集成测试代码
示例项目：演示插件功能的示例配置

3. 配置接口定义

interface GitProjectAutoCommitConfig {
  enabled?: boolean;              // 是否启用，默认false
  watchAuthor?: string;           // 监听的开发者用户名 (当useSharedCommits为false或作为共享提交源时建议填写)
  maxScanCount?: number;          // 最大扫描提交记录数，默认50
  commitSeparator?: string;       // 提交分隔符，默认'/** 提交分隔符 **/'
  message?: string;               // 自动提交消息模板 (可选, 有默认值)
  push?: boolean;                 // 是否推送到远程，默认false
  useSharedCommits?: boolean;     // 可选，是否尝试使用共享的提交信息，默认false
}

interface GitProjectConfig {
  repo: string;             // 仓库地址（SSH或HTTPS）
  branch: string;           // 目标分支
  targetDir: string;        // 存放目录（相对项目根目录）
  projectName?: string;     // 可选：重命名项目目录
  updateIfExists?: boolean; // 存在时是否更新，默认true
  autoCommit?: GitProjectAutoCommitConfig; // 可选的自动提交配置
}

interface LocalSyncConfig {
  source: string;           // 源目录/文件（相对项目根目录）
  target: string;           // 目标目录/文件（相对项目根目录）
  mode?: 'copy' | 'mirror' | 'incremental'; // 同步模式，默认'incremental'
  clearTarget?: boolean;    // 是否同步前清空目标目录，默认false
  addOnly?: boolean;        // 是否仅新增（目标不存在的文件/目录），默认false
  exclude?: string[];       // 排除文件/目录的正则表达式数组
  excludeDirs?: string[];   // 排除目录（glob或正则表达式）
  excludeFiles?: string[];  // 排除文件（glob或正则表达式）
}

interface TurborepoDeployConfig {
  localSync?: Array<LocalSyncConfig>;
  gitProjects?: Array<GitProjectConfig>;
  taskOrder?: Array<'localSync' | 'updateGitProjects'>; // 任务执行顺序
}

17 KiB Raw Permalink Blame History Unescape Escape

Vite插件开发需求文档：Turborepo工作区编译部署自动化工具

一、项目概述

二、功能需求

1. 本地文件同步功能

2. Git项目管理与自动提交功能

3. 任务编排系统

4. 日志记录系统

三、技术实现要求

1. 基础架构

2. 代码规范与最佳实践

3. 性能与兼容性

4. 插件接口与类型定义

5. 依赖与工具

6. 测试与质量保障

四、交互与输出

1. 控制台输出示例

2. 日志文件格式

五、使用示例

六、测试要求

1. 单元测试

2. 集成测试

3. 边缘情况测试

七、交付物

3. 配置接口定义

17 KiB

Raw Permalink Blame History