# 迁移规划与设计

<cite>
**本文引用的文件**
- [composer.json](file://composer.json)
- [README.md](file://README.md)
- [.example.env](file://.example.env)
- [vendor/xia/migration/composer.json](file://vendor/xia/migration/composer.json)
- [vendor/xia/migration/src/Service.php](file://vendor/xia/migration/src/Service.php)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php)
- [vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php)
- [vendor/xia/migration/phinx/src/Phinx/Migration/MigrationInterface.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/MigrationInterface.php)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php)
- [vendor/xia/migration/phinx/src/Phinx/Migration/IrreversibleMigrationException.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/IrreversibleMigrationException.php)
- [vendor/xia/migration/phinx/src/Phinx/Migration/CreationInterface.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/CreationInterface.php)
- [vendor/xia/migration/phinx/src/Phinx/Migration/AbstractTemplateCreation.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/AbstractTemplateCreation.php)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 ThinkCMF 的数据库迁移规划与设计，结合项目中集成的迁移组件，系统化阐述迁移需求分析、版本规划策略、数据库变更评估与影响分析、迁移文件命名规范与组织结构、迁移设计最佳实践（事务处理、回滚策略、数据一致性保障）、迁移文件编写规范（表结构变更、索引优化、约束设置），以及迁移设计检查清单与质量保证措施。目标是帮助团队在 ThinkCMF 生态中建立标准化、可追溯、可回滚的数据库演进流程。

## 项目结构
- ThinkCMF 在根目录通过 Composer 集成迁移能力，核心由 xia/migration 包提供，其内部封装了 Phinx 的迁移与环境管理能力。
- 迁移命令在 ThinkPHP 服务发现后自动注册，配合 Composer 的 post-autoload-dump 钩子，在安装或更新依赖后自动执行迁移。
- 数据库连接等环境参数可通过 .env 示例文件进行配置，便于不同环境的迁移执行。

```mermaid
graph TB
A["ThinkCMF 根目录<br/>composer.json"] --> B["迁移包 xia/migration<br/>vendor/xia/migration/composer.json"]
B --> C["迁移服务注册<br/>vendor/xia/migration/src/Service.php"]
C --> D["迁移管理器<br/>vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php"]
D --> E["环境管理<br/>vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php"]
D --> F["抽象迁移基类<br/>vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php"]
D --> G["迁移接口<br/>vendor/xia/migration/phinx/src/Phinx/Migration/MigrationInterface.php"]
A --> H[".example.env<br/>数据库配置示例"]
```

图表来源
- [composer.json:1-77](file://composer.json#L1-L77)
- [vendor/xia/migration/composer.json:1-28](file://vendor/xia/migration/composer.json#L1-L28)
- [vendor/xia/migration/src/Service.php:25-50](file://vendor/xia/migration/src/Service.php#L25-L50)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:25-82](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L25-L82)
- [.example.env:1-1](file://.example.env#L1-L1)

章节来源
- [composer.json:1-77](file://composer.json#L1-L77)
- [README.md:17-44](file://README.md#L17-L44)
- [.example.env:1-1](file://.example.env#L1-L1)

## 核心组件
- 迁移服务注册：通过 ThinkPHP 服务提供者绑定迁移工厂与命令，完成迁移命令的自动注册与可用性。
- 迁移管理器：负责扫描迁移文件、解析版本号、按方向执行迁移与回滚、打印状态、处理断点与种子数据。
- 环境管理：封装数据库连接、版本记录、执行上下文，确保迁移在指定环境中安全执行。
- 抽象迁移基类与接口：定义迁移的生命周期（up/down）、版本号、名称等契约，保证迁移的一致性与可测试性。
- 不可逆迁移异常：当迁移被标记为不可逆时，抛出异常以阻止危险操作。

章节来源
- [vendor/xia/migration/src/Service.php:25-50](file://vendor/xia/migration/src/Service.php#L25-L50)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:25-82](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L25-L82)
- [vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php#L1-L200)
- [vendor/xia/migration/phinx/src/Phinx/Migration/MigrationInterface.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/MigrationInterface.php#L1-L200)
- [vendor/xia/migration/phinx/src/Phinx/Migration/IrreversibleMigrationException.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/IrreversibleMigrationException.php#L1-L200)

## 架构总览
迁移在 ThinkCMF 中的执行路径如下：Composer 安装后触发迁移命令；迁移服务注册迁移命令；迁移管理器根据配置扫描迁移文件并按版本顺序执行；环境管理器负责数据库连接与版本记录；迁移文件通过抽象基类实现 up/down 变更。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Composer as "Composer"
participant TP as "ThinkPHP 服务发现"
participant Service as "迁移服务"
participant Manager as "迁移管理器"
participant Env as "环境管理"
participant DB as "数据库"
Dev->>Composer : 执行安装/更新
Composer-->>TP : 触发 post-autoload-dump
TP-->>Service : 注册迁移命令
Dev->>Service : 执行迁移命令
Service->>Manager : 初始化管理器
Manager->>Env : 获取环境配置
Manager->>Manager : 扫描并解析迁移文件
Manager->>Env : 执行 up/down 变更
Env->>DB : 写入/回滚变更
DB-->>Env : 返回结果
Env-->>Manager : 记录版本日志
Manager-->>Dev : 输出执行状态
```

图表来源
- [composer.json:67-72](file://composer.json#L67-L72)
- [vendor/xia/migration/src/Service.php:34-49](file://vendor/xia/migration/src/Service.php#L34-L49)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:311-362](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L311-L362)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php#L1-L200)

## 详细组件分析

### 组件一：迁移服务与命令注册
- 作用：在 ThinkPHP 应用启动阶段绑定迁移工厂与命令，使迁移命令在 CLI 下可用。
- 关键点：仅注册迁移相关命令，其他命令（如回滚、断点、状态、种子）当前处于注释状态，便于按需启用。

```mermaid
classDiagram
class Service {
+boot()
+binds
+commands
}
class Manager {
+printStatus()
+migrate()
+rollback()
+seed()
}
Service --> Manager : "引导并注册命令"
```

图表来源
- [vendor/xia/migration/src/Service.php:25-50](file://vendor/xia/migration/src/Service.php#L25-L50)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:25-82](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L25-L82)

章节来源
- [vendor/xia/migration/src/Service.php:25-50](file://vendor/xia/migration/src/Service.php#L25-L50)

### 组件二：迁移管理器与执行流程
- 版本解析：从迁移文件名提取版本号，校验唯一性与类存在性，实例化迁移类。
- 执行方向：根据目标版本与当前版本决定向上（up）或向下（down）执行。
- 断点与回滚：支持断点控制、按名称或版本回滚、目标必须匹配版本的策略。
- 状态输出：支持文本与 JSON 格式输出，便于 CI/CD 集成。

```mermaid
flowchart TD
Start(["开始"]) --> Scan["扫描迁移文件"]
Scan --> Parse["解析版本号与类名"]
Parse --> Validate{"校验唯一性与类存在"}
Validate --> |失败| Error["抛出异常"]
Validate --> |成功| Decide["计算执行方向"]
Decide --> Up["向上迁移"]
Decide --> Down["向下迁移"]
Up --> ExecUp["执行迁移并记录版本"]
Down --> ExecDown["执行回滚并记录版本"]
ExecUp --> Done(["结束"])
ExecDown --> Done
Error --> Done
```

图表来源
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:695-791](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L695-L791)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:311-362](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L311-L362)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:438-539](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L438-L539)

章节来源
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:91-254](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L91-L254)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:287-362](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L287-L362)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:438-539](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L438-L539)

### 组件三：抽象迁移基类与接口契约
- 抽象基类：提供 up/down 生命周期方法、版本号与名称约定、不可逆迁移异常支持。
- 接口契约：定义迁移类必须实现的方法与行为，确保一致性与可测试性。
- 模板创建：提供迁移文件生成模板接口与抽象实现，便于规范化生成迁移文件。

```mermaid
classDiagram
class MigrationInterface {
<<interface>>
+up()
+down()
+getVersion()
+getName()
}
class AbstractMigration {
+up()
+down()
+getVersion()
+getName()
}
class CreationInterface {
<<interface>>
+getMigrationObject()
}
class AbstractTemplateCreation {
+getMigrationObject()
}
MigrationInterface <|.. AbstractMigration : "实现"
CreationInterface <|.. AbstractTemplateCreation : "实现"
```

图表来源
- [vendor/xia/migration/phinx/src/Phinx/Migration/MigrationInterface.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/MigrationInterface.php#L1-L200)
- [vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php#L1-L200)
- [vendor/xia/migration/phinx/src/Phinx/Migration/CreationInterface.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/CreationInterface.php#L1-L200)
- [vendor/xia/migration/phinx/src/Phinx/Migration/AbstractTemplateCreation.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/AbstractTemplateCreation.php#L1-L200)

章节来源
- [vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php#L1-L200)
- [vendor/xia/migration/phinx/src/Phinx/Migration/MigrationInterface.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/MigrationInterface.php#L1-L200)
- [vendor/xia/migration/phinx/src/Phinx/Migration/CreationInterface.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/CreationInterface.php#L1-L200)
- [vendor/xia/migration/phinx/src/Phinx/Migration/AbstractTemplateCreation.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/AbstractTemplateCreation.php#L1-L200)

### 组件四：环境管理与数据库交互
- 环境初始化：读取配置中的环境选项（如版本顺序、数据域），构建环境实例。
- 版本记录：维护已执行版本的日志，支持断点、起止时间等元数据。
- 执行上下文：在迁移执行前后输出状态，便于调试与审计。

```mermaid
sequenceDiagram
participant Manager as "迁移管理器"
participant Env as "环境管理"
participant DB as "数据库"
Manager->>Env : getEnvironment(name)
Env->>Env : 初始化配置与版本日志
Manager->>Env : executeMigration(migration, direction)
Env->>DB : 执行 SQL 并记录版本
DB-->>Env : 返回执行结果
Env-->>Manager : 返回状态
```

图表来源
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:590-615](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L590-L615)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php#L1-L200)

章节来源
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:590-615](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L590-L615)

## 依赖关系分析
- ThinkCMF 通过 composer.json 的 extra.think 字段声明迁移服务，确保 ThinkPHP 服务发现机制正确加载迁移包。
- 迁移包内部通过 PSR-4 自动加载映射，将 think\migration 命名空间指向 src 目录，Phinx 命名空间指向 phinx/src/Phinx。
- 迁移命令在 autoload 钩子后自动注册，简化了迁移的使用成本。

```mermaid
graph LR
Root["ThinkCMF 根目录<br/>composer.json"] --> Extra["extra.think.services<br/>think\\migration\\Service"]
Extra --> Service["think\\migration\\Service"]
Service --> PSR4["PSR-4 映射"]
PSR4 --> TNS["think\\migration\\* -> src/*"]
PSR4 --> PNS["Phinx\\* -> phinx/src/Phinx/*"]
```

图表来源
- [composer.json:57-66](file://composer.json#L57-L66)
- [vendor/xia/migration/composer.json:13-27](file://vendor/xia/migration/composer.json#L13-L27)
- [vendor/xia/migration/src/Service.php:25-50](file://vendor/xia/migration/src/Service.php#L25-L50)

章节来源
- [composer.json:57-66](file://composer.json#L57-L66)
- [vendor/xia/migration/composer.json:13-27](file://vendor/xia/migration/composer.json#L13-L27)

## 性能考量
- 批量变更与事务：建议将多个相关变更合并到单个迁移中，利用数据库事务减少锁竞争与回滚成本。
- 索引与约束：大表变更应避免长时间持有排他锁，优先考虑在线索引、分批处理与异步任务。
- 执行顺序：通过版本号严格控制执行顺序，避免并发冲突；在 CI/CD 中串行执行迁移，确保一致性。
- 日志与可观测性：利用迁移管理器的状态输出与 JSON 格式，便于监控与告警。

## 故障排查指南
- 迁移文件缺失：状态输出会提示“缺少迁移文件”，需检查迁移文件是否存在且命名规范正确。
- 版本冲突：若出现重复版本号，需调整文件名版本号或删除重复文件。
- 不可逆迁移：迁移被标记为不可逆时会抛出异常，需确认是否需要回滚路径或重构迁移。
- 断点限制：到达断点后禁止继续回滚，需先清除断点或手动干预。

章节来源
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:91-135](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L91-L135)
- [vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php:717-741](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L717-L741)
- [vendor/xia/migration/phinx/src/Phinx/Migration/IrreversibleMigrationException.php:1-200](file://vendor/xia/migration/phinx/src/Phinx/Migration/IrreversibleMigrationException.php#L1-L200)

## 结论
ThinkCMF 的迁移体系基于 ThinkPHP 服务发现与 xia/migration 包，结合 Phinx 的成熟机制，提供了可扩展、可追踪、可回滚的数据库演进能力。通过规范化的命名与版本管理、严格的事务与断点控制、完善的日志与状态输出，团队可以在多环境下稳定地推进数据库变更。

## 附录

### 迁移需求分析与设计原则
- 需求驱动：每次迁移围绕明确业务需求，最小化变更面，避免无关改动。
- 版本规划：采用时间戳前缀版本号，确保自然排序与可读性；重大变更使用语义化版本号。
- 影响评估：评估变更对性能、兼容性、数据一致性的影响，必要时制定灰度与回滚预案。
- 变更隔离：将破坏性变更拆分为多个迁移，逐步上线并验证。

### 数据库变更评估与影响分析
- 性能影响：大表变更需评估锁等待、慢查询与索引重建成本。
- 兼容性：检查字段长度、字符集、默认值变更对现有业务的影响。
- 一致性：确保外键、唯一约束、触发器等在迁移过程中保持一致。

### 迁移文件命名规范与组织结构
- 命名规范：使用时间戳前缀与描述性名称，例如 YYYYMMDDHHMMSS_描述.php。
- 组织结构：集中放置于迁移目录，按模块或功能分组，便于检索与审查。
- 模板生成：通过迁移命令生成标准模板，统一 up/down 结构与注释规范。

### 迁移设计最佳实践
- 事务处理：将相关变更放入同一迁移，利用数据库事务保证原子性。
- 回滚策略：优先支持 down 方法；对不可逆变更提供替代方案或数据备份。
- 数据一致性：在迁移中显式处理默认值、空值、索引与约束，避免隐式变更。
- 并发控制：在 CI/CD 中串行执行迁移，避免多节点同时写入导致冲突。

### 迁移文件编写规范
- 表结构变更：新增/删除列、修改类型与默认值需谨慎；优先使用在线 ALTER。
- 索引优化：避免重复索引，定期清理冗余索引；复合索引遵循最左前缀原则。
- 约束设置：外键、唯一键、检查约束需在迁移中显式声明，确保一致性。

### 迁移设计检查清单
- 是否有明确的需求背景与验收标准？
- 版本号是否唯一且符合命名规范？
- 是否包含 up/down 实现？不可逆变更是否有替代方案？
- 是否考虑性能与兼容性风险？
- 是否具备回滚路径与数据备份？
- 是否通过本地与预生产验证？