# OOP + Composition API 组合使用方案

**日期**: 2026-01-31
**核心理念**: 取长补短，渐进式迁移

---

## 🎯 设计原则

### OOP 负责什么
- ✅ **核心业务逻辑**（复杂的状态管理）
- ✅ **需要严格初始化顺序的功能**（如 ZIP 浏览）
- ✅ **可复用的服务**（文件操作、预览等）
- ✅ **需要依赖注入和测试的模块**

### Composition API 负责什么
- ✅ **Vue 组件的响应式状态**
- ✅ **简单的 UI 逻辑**
- ✅ **生命周期钩子**
- ✅ **DOM 事件处理**

### 分层架构

```
┌─────────────────────────────────────┐
│      Vue 组件层 (Composition)       │  ← UI 交互、生命周期
│  index.vue | 组件 <script setup>    │
└──────────────┬──────────────────────┘
               │ 使用
┌──────────────▼──────────────────────┐
│    适配器层 (Composables)           │  ← 轻量桥接、响应式转换
│  useFileSystem() | useZipBrowser()  │
└──────────────┬──────────────────────┘
               │ 调用
┌──────────────▼──────────────────────┐
│      服务层 (OOP Classes)           │  ← 核心逻辑、初始化保证
│  FileSystemService | ZipService     │
└─────────────────────────────────────┘
```

---

## 📝 实际代码示例

### 1. 服务层（OOP）- 解决初始化问题

```typescript
// services/ZipBrowserService.ts
import { ref, computed, type Ref } from 'vue'
import { Message } from '@arco-design/web-vue'
import type { FileApiService } from './FileApiService'
import type { FilePreviewService } from './FilePreviewService'
import type { FileItem } from '@/types/file-system'

/**
 * ZIP 浏览服务
 * 使用 OOP 封装，构造函数保证初始化顺序
 */
export class ZipBrowserService {
  // ========== 状态（私有 ref） ==========
  private readonly _isBrowsingZip = ref<boolean>(false)
  private readonly _currentZipPath = ref<string>('')
  private readonly _currentZipDirectory = ref<string>('')
  private readonly _pathBeforeZip = ref<string>('')

  // ========== 依赖注入（构造时确保初始化） ==========
  constructor(
    private readonly fileApi: FileApiService,
    private readonly previewService: FilePreviewService,  // ✅ 保证已初始化
    private readonly fileList: Ref<FileItem[]>,
    private readonly filePath: Ref<string>
  ) {
    console.log('[ZipBrowserService] 初始化完成')
  }

  // ========== 公共接口（访问器） ==========

  /** 是否正在浏览 ZIP（返回 ref） */
  get isBrowsingZip(): Ref<boolean> {
    return this._isBrowsingZip
  }

  /** 当前 ZIP 路径（返回 ref） */
  get currentZipPath(): Ref<string> {
    return this._currentZipPath
  }

  /** 当前 ZIP 目录（返回 ref） */
  get currentZipDirectory(): Ref<string> {
    return this._currentZipDirectory
  }

  /** 显示路径（计算属性） */
  get displayPath(): Ref<string> {
    return computed(() => {
      if (this._currentZipDirectory.value) {
        return `📦 ${this._currentZipPath.value} [${this._currentZipDirectory.value}]`
      }
      return `📦 ${this._currentZipPath.value}`
    })
  }

  // ========== 公共方法 ==========

  /**
   * 进入 ZIP 浏览模式
   */
  async enterZipMode(zipPath: string): Promise<void> {
    this._pathBeforeZip.value = this.filePath.value
    this._currentZipPath.value = zipPath
    this._isBrowsingZip.value = true
    this._currentZipDirectory.value = ''

    await this.loadZipDirectory()
    Message.success('进入 ZIP 浏览模式')
  }

  /**
   * 退出 ZIP 浏览模式
   */
  exitZipMode(): void {
    this._isBrowsingZip.value = false
    this._currentZipPath.value = ''
    this._currentZipDirectory.value = ''
    this.filePath.value = this._pathBeforeZip.value
    Message.info('退出 ZIP 浏览模式')
  }

  /**
   * 获取 ZIP 文件名
   */
  getZipFileName(zipPath: string): string {
    const parts = zipPath.split(/[/\\]/)
    return parts[parts.length - 1] || zipPath
  }

  /**
   * 获取面包屑导航
   */
  getZipBreadcrumbs(): ZipBreadcrumbItem[] {
    const crumbs: ZipBreadcrumbItem[] = [
      { name: this.getZipFileName(this._currentZipPath.value), path: '' }
    ]

    if (this._currentZipDirectory.value) {
      const parts = this._currentZipDirectory.value.split('/')
      let currentPath = ''
      for (const part of parts) {
        currentPath += (currentPath ? '/' : '') + part
        crumbs.push({ name: part, path: currentPath })
      }
    }

    return crumbs
  }

  /**
   * 导航到指定目录
   */
  async navigateToZipDirectory(path: string): Promise<void> {
    this._currentZipDirectory.value = path
    await this.loadZipDirectory()
  }

  // ========== 私有方法 ==========

  private async loadZipDirectory(): Promise<void> {
    // 加载目录逻辑
  }
}
```

### 2. 适配器层（Composable）- 桥接服务

```typescript
// composables/useZipBrowser.ts
import { useRef } from '@/utils/singleton'
import { ZipBrowserService } from '@/services/ZipBrowserService'
import type { UseZipBrowserOptions } from './types'

/**
 * ZIP 浏览 Composable
 * 轻量级适配器，桥接 Vue 和服务层
 */
export function useZipBrowser(options: UseZipBrowserOptions) {
  // 使用单例模式，确保服务只创建一次
  const service = useRef(() => {
    console.log('[useZipBrowser] 创建 ZipBrowserService 实例')

    return new ZipBrowserService(
      options.fileApi,        // 依赖注入
      options.previewService, // ✅ 保证预览服务已初始化
      options.fileList,
      options.filePath
    )
  }, 'zipBrowserService')

  // 返回响应式接口（Composition API 风格）
  return {
    // 状态（直接返回 ref）
    isBrowsingZip: service.isBrowsingZip,
    currentZipPath: service.currentZipPath,
    currentZipDirectory: service.currentZipDirectory,
    displayPath: service.displayPath,

    // 方法（绑定到服务实例）
    enterZipMode: (path: string) => service.enterZipMode(path),
    exitZipMode: () => service.exitZipMode(),
    navigateToZipDirectory: (path: string) => service.navigateToZipDirectory(path),
    getZipFileName: (path: string) => service.getZipFileName(path),
    getZipBreadcrumbs: () => service.getZipBreadcrumbs(),

    // 服务实例（可选，用于高级用法）
    $service: service
  }
}
```

### 3. 单例工具（避免重复创建）

```typescript
// utils/singleton.ts
const singletons = new Map<string, any>()

/**
 * 创建或获取单例
 * @param factory 工厂函数
 * @param key 单例键名
 */
export function useRef<T>(factory: () => T, key: string): T {
  if (!singletons.has(key)) {
    const instance = factory()
    singletons.set(key, instance)
    console.log(`[Singleton] 创建 ${key}`)
  } else {
    console.log(`[Singleton] 复用 ${key}`)
  }
  return singletons.get(key) as T
}

/**
 * 清除单例（测试用）
 */
export function clearRef(key?: string): void {
  if (key) {
    singletons.delete(key)
  } else {
    singletons.clear()
  }
}
```

### 4. 在组件中使用（Composition API）

```typescript
// components/FileSystem/index.vue
<script setup lang="ts">
import { ref, computed } from 'vue'
import { useFileOperations } from './composables/useFileOperations'
import { useZipBrowser } from './composables/useZipBrowser'

// ========== 1. 初始化基础服务 ==========
const { listDirectory, extractZipFile, getFileServerURL, fileApi } =
  useFileOperations()

// ========== 2. 初始化依赖服务 ==========
const { previewService } = useFilePreview({ filePath })

// ========== 3. 初始化 ZIP 浏览（依赖预览服务） ==========
const zipBrowser = useZipBrowser({
  fileApi,
  previewService,  // ✅ 依赖注入，保证顺序
  fileList,
  filePath
})

// ========== 4. 使用（和之前一样） ==========
const toolbarConfig = computed(() => ({
  isBrowsingZip: zipBrowser.isBrowsingZip.value,  // ✅ ref
  displayPath: zipBrowser.displayPath.value,       // ✅ ref
  zipFileName: zipBrowser.getZipFileName(zipBrowser.currentZipPath.value),
  zipBreadcrumbs: zipBrowser.getZipBreadcrumbs()
}))

// ========== 5. 事件处理 ==========
const handleEnterZipMode = async (zipPath: string) => {
  await zipBrowser.enterZipMode(zipPath)  // ✅ 简单调用
}

const handleExitZip = () => {
  zipBrowser.exitZipMode()  // ✅ 简单调用
}

// ========== 6. 高级用法（可选） ==========
// 直接访问服务实例
const zipService = zipBrowser.$service
console.log(zipService.currentZipPath.value)
</script>

<template>
  <!-- 使用方式不变 -->
  <Toolbar
    :isBrowsingZip="zipBrowser.isBrowsingZip"
    :zipFileName="zipBrowser.getZipFileName(zipBrowser.currentZipPath)"
    @enter-zip="handleEnterZipMode"
    @exit-zip="handleExitZip"
  />
</template>
```

---

## 🔄 渐进式迁移策略

### 阶段 1：新功能使用组合方案（立即开始）

```typescript
// ✅ 新功能：使用 OOP 服务
const newFeature = useNewFeature({
  service: new NewFeatureService()
})
```

### 阶段 2：问题模块优先迁移（本周）

```typescript
// ❌ 旧代码（有问题）
const zipBrowser = useZipBrowser({ ... })

// ✅ 新代码（使用服务）
const zipBrowser = useZipBrowser({
  fileApi,
  previewService,  // 依赖注入
  fileList,
  filePath
})
```

**优先迁移：**
1. `useZipBrowser` - 初始化顺序问题最多
2. `useFilePreview` - 返回值过多
3. `useFileEdit` - 状态管理复杂

### 阶段 3：其他功能逐步迁移（1-2周）

```typescript
// 老代码保持不变，新代码用新方案
const oldFeature = useOldFeature()  // 保持原样
const newFeature = useNewFeature({  // 新方案
  service: new NewFeatureService()
})
```

### 阶段 4：完全迁移后（1个月后）

```typescript
// 全部使用组合方案
const { fileSystem, preview, zip, edit } = useServices({
  services: {
    fileSystem: new FileSystemService(),
    preview: new FilePreviewService(),
    zip: new ZipBrowserService()
  }
})
```

---

## 💡 使用场景对比

### 场景 1：简单 UI 逻辑（用 Composition API）

```typescript
// ✅ 简单的响应式状态
const showDialog = ref(false)
const dialogMessage = ref('')

const openDialog = (msg: string) => {
  dialogMessage.value = msg
  showDialog.value = true
}
```

### 场景 2：复杂业务逻辑（用 OOP 服务）

```typescript
// ✅ 复杂的状态管理
class ZipBrowserService {
  constructor(
    private preview: FilePreviewService,  // 依赖注入
    private fileApi: FileApiService
  ) {}

  async enterZipMode(path: string) {
    // 复杂的初始化逻辑
    await this.preview.cleanup()
    this._isBrowsingZip.value = true
    await this.loadZipContents()
  }
}
```

### 场景 3：需要组合两者（组合使用）

```typescript
// 服务层（OOP）- 核心逻辑
class FilePreviewService {
  async previewImage(path: string) {
    const url = await this.fileApi.getImageUrl(path)
    this._previewUrl.value = url
  }
}

// Composable - 桥接到 Vue
function useFilePreview() {
  const service = new FilePreviewService(...)

  return {
    // 响应式状态（Composition API）
    previewUrl: service.previewUrl,

    // 方法（委托给服务）
    previewImage: (path: string) => service.previewImage(path),

    // 服务实例（可选）
    $service: service
  }
}

// 组件 - 使用
const { previewUrl, previewImage } = useFilePreview()
```

---

## 🎓 最佳实践

### 1. 服务类设计原则

```typescript
class GoodService {
  // ✅ 状态用 ref
  private readonly _state = ref<State>(initialState)

  // ✅ 构造函数注入依赖
  constructor(
    private readonly dependency: OtherService
  ) {}

  // ✅ 提供访问器
  get state(): Ref<State> {
    return this._state
  }

  // ✅ 方法返回值（不返回 ref）
  doSomething(): void {
    this._state.value = { ... }
  }
}
```

### 2. Composable 设计原则

```typescript
function useGoodService(options: Options) {
  // ✅ 创建服务实例
  const service = new GoodService(options.dependency)

  return {
    // ✅ 返回 ref（响应式）
    state: service.state,

    // ✅ 绑定方法
    doSomething: () => service.doSomething(),

    // ✅ 可选：暴露服务
    $service: service
  }
}
```

### 3. 组件使用原则

```typescript
// ✅ 简单场景：只用返回值
const { state, doSomething } = useGoodService()

// ✅ 复杂场景：访问服务实例
const { $service } = useGoodService()
$service.advancedMethod()

// ✅ 生命周期钩子（Composition API）
onMounted(() => {
  $service.initialize()
})
```

---

## 📊 对比总结

| 维度 | OOP 服务 | Composable | 组件使用 |
|-----|---------|-----------|---------|
| **适用场景** | 复杂逻辑、初始化顺序 | 简单逻辑、UI 状态 | 组合使用 |
| **状态管理** | ref 私有字段 | ref 变量 | ref 变量 |
| **依赖注入** | 构造函数 | 函数参数 | 函数参数 |
| **测试性** | ✅ 容易 | ⚠️ 中等 | ⚠️ 中等 |
| **Vue 兼容** | ⚠️ 需要适配 | ✅ 完美 | ✅ 完美 |
| **初始化保证** | ✅ 构造函数 | ❌ 手动保证 | - |

---

## 🚀 快速开始模板

### 创建服务类

```bash
# 1. 创建服务文件
services/MyFeatureService.ts

# 2. 创建 composable 适配器
composables/useMyFeature.ts

# 3. 在组件中使用
components/MyComponent.vue
```

### 模板代码

```typescript
// 1. 服务类
export class MyFeatureService {
  constructor(private dep: DependencyService) {}
  get state() { return this._state }
  doSomething() { ... }
}

// 2. Composable
export function useMyFeature() {
  const service = new MyFeatureService(dep)
  return {
    state: service.state,
    doSomething: () => service.doSomething(),
    $service: service
  }
}

// 3. 组件
const { state, doSomething } = useMyFeature()
```

---

## ✅ 总结

### 组合方案的优势

1. **✅ 解决初始化问题** - OOP 构造函数保证顺序
2. **✅ 保持开发体验** - Composition API 风格
3. **✅ 渐进式迁移** - 不需要大规模重构
4. **✅ 高内聚低耦合** - 服务封装，适配器桥接
5. **✅ 易于测试** - 服务层独立测试

### 核心理念

> **OOP 负责复杂逻辑，Composition 负责 UI 交互**

---

**生成时间**: 2026-01-31
**下一步**: 创建第一个 OOP 服务示例（ZipBrowserService）？