Scala 2→3 迁移与重构实战：迁移工具链、兼容策略与渐进式改造

迁移收益：
□ 长期维护：Scala 2 进入维护模式，新特性只在 Scala 3
□ 编译器改进：更快的编译、更好的错误信息
□ 现代化语法：缩进语法、enum、given/using 更简洁
□ 生态重心：主流库逐渐要求 Scala 3

迁移成本：
□ 宏/元编程：Scala 2 宏（黑盒/白盒）与 Scala 3 宏 API 不兼容
□ 隐式 → given：大量隐式参数/隐式转换要迁移
□ 依赖：第三方库需要 Scala 3 版本（部分滞后）
□ 反射/工具链：某些框架依赖 Scala 2 编译器细节

评估信号：
□ 代码库大小、宏数量、依赖的 Scala 3 支持度
□ 团队对 Scala 3 的熟悉度
□ 收益集中在「长期」，成本集中在「前期」

四大风险区：
□ 宏（Macro）：Scala 2 宏（def macro）→ Scala 3 完全不同
□ 隐式（Implicit）：implicit 参数/隐式转换 → given/using
□ 反射（Reflection）：scala.reflect API → Scala 3 减少依赖
□ 依赖：Java/Scala 2 库 vs Scala 3 交叉版本

自动迁移能覆盖：
□ 语法变化（多数）
□ 标准库小改动
□ 隐式的大多数（scalafix 迁移规则）

手动迁移必须：
□ 宏实现（重写）
□ 反射代码（重新设计或改 scala 3 方式）
□ 特殊类型级技巧（TypeTag/Manifest → TypeTest 等）

扫描工具：
□ 用 Scala 3 编译器跑「迁移模式」（-source:3.0-migration）
□ scalafix 迁移规则报告无法自动处理的点
□ 静态扫描隐式/宏/反射的分布

交叉编译（Cross Compilation）：
□ 一套源码，发布 Scala 2.13 与 Scala 3 两个版本
□ 用「差异层」处理语法/库差异：
  source.binary 或 %% 版本矩阵
□ sbt：crossScalaVersions := Seq("2.13.x", "3.x.y")
□ Mill：支持 cross 配置

差异处理技巧：
□ 公共代码：写两版都兼容的子集
□ 差异代码：分开在 scala-2.13/ 与 scala-3/ 目录（sbt srcMain）
□ 库依赖：%%% 自动选对应 Scala 版本

收益：
□ 不必「一刀切」迁：库/模块逐步切到 Scala 3
□ 新代码可直接用 Scala 3，旧代码保持 2.13
□ 生态兼容：给使用方的依赖保持双版本

// build.sbt 交叉编译
crossScalaVersions := Seq("2.13.12", "3.3.1")
scalaVersion := "3.3.1"
libraryDependencies += "org.typelevel" %% "cats-effect" % "3.5.4"
// %%% 自动选择对应 Scala 版本

迁移工具链：
□ scalafix：语义化代码改写工具（规则系统）
□ Scala 3 迁移规则：scala-3-migration / ExplicitResultTypes
□ sbt 插件：scalafix + scalafmt 协同
□ 官方迁移指南：scala 3-migration-guide

自动迁移能做的：
□ 隐式 → given/using（多数）
□ 语法调整：auto-application、后缀操作符、下划线用法
□ 类型推断补全（ExplicitResultTypes 规则）
□ 关键字冲突：enum/extension/given 作为标识符加反引号

迁移流程：
1. 编译基线：先让 Scala 2.13 全绿（迁移前的测试基线）
2. 跑 scalafix 迁移规则 → 生成 diff
3. review diff（自动改的也要人审）
4. 切到 Scala 3 编译器跑迁移模式 → 修残余

# sbt 里跑 scalafix 迁移规则
sbt "scalafixAll dependency:scala3-migration"
sbt "scalafixAll ExplicitResultTypes"

渐进式迁移策略：
1. 先迁「叶子模块」：依赖少、无宏、无复杂隐式
   → 风险最小，建立信心
2. 后迁「根模块」：被大量依赖（最后切，等依赖都就绪）
3. 中间模块：依赖被迁移的叶子，逐个跟上

双编译器并行：
□ 库/模块层：交叉编译双版本（见第 3 节）
□ 应用层：切 Scala 3 编译，2.13 分支保留回滚

每步门禁：
□ 该模块测试全绿
□ 依赖它的模块不受影响
□ 性能/行为无明显回归

迁移顺序示例：
core（无宏）→ domain → repository → service → api
最后迁「含宏的模块」与「被全部依赖的根」

Scala 3 现代化语法：
□ 缩进语法：去掉大括号（可读性，团队要适应）
□ enum：替代 sealed trait + case object（更简洁）
□ given/using：替代 implicit（更显式）
□ 可选参数的类型标注、通配符 _

现代化 vs 迁移分开：
□ 迁移 = 语义兼容的自动改写（先做，无风险）
□ 现代化 = 风格重构（后做，有行为风险）

现代化建议：
□ 新代码直接用 Scala 3 风格
□ 旧代码迁移后「不强制现代化」（保持可用，降低风险）
□ enum/given 重构走独立 PR + 测试

enum 示例（迁移后的现代化可选项）：
enum Direction:
  case North, South, East, West
// vs Scala 2：sealed trait + case object（仍可用）

依赖检查：
□ 库是否有 Scala 3 版本（%sbt 查询 / 官方支持矩阵）
□ 大库基本已支持（Cats/ZIO/Akka 等），小众库可能滞后
□ Java 库：Java 依赖通常直接可用（Scala 3 兼容 JVM 字节码）

编译器插件：
□ Kind Projector：Scala 2 类型 lambda 插件 → Scala 3 用原生
□ better-monadic-for：Scala 2 → Scala 3 不再需要（for 已优化）
□ 其他插件：需找 Scala 3 版本或找替代

处理滞后依赖：
□ 把「依赖滞后」的模块留到交叉编译阶段（2.13 继续）
□ 用 Java interop / 本地适配桥接
□ 或等待/参与库的迁移

Scala 2 宏（def macro）：黑盒/白盒
  → 基于 scala.reflect.macros（编译器内部 API）
Scala 3 宏：
  → 基于 quotes.reflect（显式 Quotes 上下文）
  → inline 与宏分工：inline 做常量折叠，宏做复杂生成

迁移路径：
□ 简单「编译期生成」→ 用 inline + 内联表达式
□ 类型级/元编程 → 用 Match Types（很多 Scala 2 宏可替代）
□ 复杂代码生成宏 → 用 quotes.reflect 重写

依赖宏的库：
□ 用宏的库（如一些 DSL/derive 库）→ 需等其 Scala 3 版本
□ 自己的宏 → 属「必须手动」的重写项

Migration 模式：
□ 编译器 -source:3.0-migration 能给出宏相关的迁移提示
□ 先让「无宏模块」迁移，宏模块单独攻关

// Scala 3 简单宏形态（示意）
import scala.quotes.*
inline def debug(inline expr: Any): String =
  ${ debugImpl('expr) }
def debugImpl(expr: Expr[Any])(using Quotes): Expr[String] =
  '{ ${ Expr(expr.show) } }

回归测试：
□ 迁移前建立测试基线（2.13 全绿）
□ 迁移后同一套测试跑 Scala 3
□ 重点：隐式解析差异、枚举/ADT 行为、边界类型

性能验证：
□ 编译时间对比（Scala 3 编译更快，但首次会慢）
□ 运行时性能：核心路径 benchmark（不应有回归）
□ 启动时间/内存：对比迁移前后

兼容回归：
□ 交叉编译的 2.13 版本仍可用（库的消费者）
□ 对外 API 行为一致（字节码/Scala 2 消费者）

发布策略：
□ 库：发布双版本（2.13 + 3），消费者各自验证
□ 应用：灰度发布，观察线上指标