Tagless Final 与代数式设计：类型类、DSL 与多解释器

演进三步：
① 具体实现：硬编码某个实现（如 List 模拟库存、真实 DB）
② 抽象接口：trait + 多态方法（仍是「一层接口」）
③ 代数化：trait 泛型化（带 F[_]），方法签名也带 F
   → 这就是 Tagless Final：操作是「约束」，不是「指令」
对比举例——库存查询：
具体版：def inStock(sku: String): Boolean          // 就一种解释
接口版：trait Inventory { def inStock(sku: String): Boolean }
代数版：trait Inventory[F[_]] { def inStock(sku: String): F[Boolean] }
   → F 可以是 Id（纯算）、IO（真实查询）、测试替身……

// 抽象代数：一个带类型参数 F 的 trait
trait Inventory[F[_]]:
  def inStock(sku: String): F[Boolean]
  def reserve(sku: String, qty: Int): F[Either[StockError, Unit]]
// 一个解释器：用 Id 做纯内存解释（测试用）
given inventoryInMemory: Inventory[Id] = new Inventory[Id]:
  def inStock(sku: String): Id[Boolean] = sku.startsWith("A")
  def reserve(sku: String, qty: Int): Id[Either[StockError, Unit]] =
    Right(())

F 代数的本质：
□ 一组操作（代数）：返回类型都是 F[...]
□ 组合规则：flatMap/map（Monad）允许顺序与分支
□ 约束 = 类型类：不只是自己的代数 trait，还要 Monad 能力
类型类约束的作用：
□ 约束「能做什么」而非「怎么做」
□ 需要错误 → [F[_]: MonadError]
□ 需要并发 → [F[_]: Concurrent]
□ 需要时间  → [F[_]: Temporal]
□ 约束越多，程序能力越强，可解释范围越窄（权衡）
Monad 边界：
□ 程序写法：def program[F[_]: Monad](i: Inventory[F]): F[Unit]
□ 组合器：for 推导需要 flatMap/map → Monad 约束
□ 换更强的约束（Concurrent）才可以用 par/race

import cats.*
import cats.syntax.all.*
// 程序在多态 F 上编写，仅要求 Monad + 代数
def checkout[F[_]: Monad](
    inv: Inventory[F]
)(items: List[String]): F[Either[StockError, Order]] =
  items.traverse(inv.reserve(_, 1)).map { results =>
    results.traverse(identity).map(Order(_))   // Either 累积/短路
  }

DSL 建模原则：
□ 操作粒度：一个方法 = 一个原子领域动作（不要「大杂烩」）
□ 返回类型：尽量语义化（F[Either[Err, A]] / F[Unit]）
□ 错误类型：每个操作返回自己的领域错误（ADT）
□ 无泄漏：代数里不出现实现概念（SQL、HTTP 字眼）
□ 组合：多个代数用「隐含参数聚合」传入
语法层 vs 语义层：
□ 语法层（Syntax）：扩展方法让 DSL 更好读
  （如 sku inStock 而不是 inv.inStock(sku)）
□ 语义层（Algebra）：就是 trait 本身
□ 读者观感：语法糖提升可读性，语义不变

// 三个代数组合成一门「下单 DSL」
trait Inventory[F[_]]:
  def reserve(sku: String, qty: Int): F[Either[StockError, Unit]]
trait Pricing[F[_]]:
  def priceOf(sku: String): F[Either[PricingError, Money]]
trait Notifier[F[_]]:
  def notifyOrder(order: Order): F[Unit]
// 程序只需三个代数「都满足」，用上下文参数聚合
def placeOrder[F[_]: Monad](
    inv: Inventory[F],
    pricing: Pricing[F],
    notify: Notifier[F],
)(items: List[String]): F[Unit] =
  for
    _   <- items.traverse_(inv.reserve(_, 1).map(_.liftTo[F]))
    ...
  yield ()

解释器清单：
□ 生产解释器：F = IO（真实 DB/HTTP/消息）
□ 测试解释器：F = Id 或 State（纯内存、确定性）
□ 日志解释器：F = Writer/WriterT（记录调用序列）
□ 追踪解释器：F = 带副作用日志的 IO 包装
□ 模拟解释器：F = State（可断言状态演进）
实现解释器的姿势：
□ given Inventory[IO]：把每个方法实现为 IO 效果
□ 可组合：一个解释器可包裹另一个（装饰器模式）
□ 测试用 State：F[S, A] 或 StateT[F, S, A]
验证技巧：
□ 用「日志解释器」做行为验证：断言调用序列
□ 用「内存解释器」做业务验证：断言结果与状态
□ 生产解释器与测试解释器用同一套程序 → 语义一致

import cats.*
import cats.data.State
import cats.effect.IO
// 内存测试解释器：用 State 维护库存
type Sim[A] = State[Map[String, Int], A]
given Inventory[Sim] = new Inventory[Sim]:
  def inStock(sku: String): Sim[Boolean] = State.gets(_.get(sku).exists(_ > 0))
  def reserve(sku: String, qty: Int): Sim[Either[StockError, Unit]] =
    State.modify(_.updatedWith(sku)(_.map(_ - qty).orElse(Some(-qty)))).as(Right(()))
// 生产解释器：F = IO
given Inventory[IO] = new Inventory[IO]:
  def inStock(sku: String): IO[Boolean] = DB.query(sku)
  def reserve(sku: String, qty: Int): IO[Either[StockError, Unit]] =
    DB.update(sku, qty)

组合技巧：
□ 程序库（Programs）：把常用流程写成多态函数
  → def orderFlow[F[_]: Monad](...): F[Unit]
  → 换 F 即换解释器，程序本身可复用
□ 代数组合：多个 trait 作为上下文参数传入
□ 功能组合：一个解释器调用另一个解释器
  → 如 Inventory[IO] 内部复用 Pricing[IO]
□ 提升（Lifting）：把纯函数 lift 进 F
复用陷阱：
□ 不要为「每个方法」都建一个 trait（粒度过细）
□ 约束爆炸：约束太多则解释器难写
□ 抽象泄漏：程序里出现具体 F（如直接 IO）破坏多态

import cats.*
import cats.syntax.all.*
// 通用程序：库存充足才下单
def orderIfAvailable[F[_]: Monad](
    inv: Inventory[F]
)(items: List[String]): F[Either[StockError, Order]] =
  items.traverse(inv.reserve(_, 1))       // List[F[Either[...]]]
    .map(_.traverse(identity))            // F[Either[...List]]
// 在 IO 与 Sim 上都能跑（解释器 given 决定）
// val r1: IO[Either[StockError, Order]] = orderIfAvailable(invIO)(items)
// val r2: Sim[Either[StockError, Order]] = orderIfAvailable(invSim)(items)

Free Monad：
□ 把操作建模成 AST（指令树），运行解释器再 fold
□ 语法可检查、可遍历、可持久化（把程序当数据）
□ 代价：解释器要 match 指令、间接层、性能开销
□ 适合：程序需要被「分析/序列化/重放」的场景
Tagless Final：
□ 把操作建模成类型类约束，程序就是普通多态函数
□ 无 AST、无 match，解释器直接实现方法
□ 性能更好、类型推断更自然
□ 代价：程序本身不可「当数据检查」
取舍速判：
□ 要 inspect 程序（日志回放/DSL 校验）→ Free Monad
□ 只要多解释器 + 性能 → Tagless Final
□ 两者可互转（编码等价），实践中 Tagless Final 更常用
□ 复杂度：Free 易上「语法糖」陷阱，Tagless 约束更清晰

一图对比：
Free Monad  =  AST + fold 解释器    （程序是数据）
Tagless     =  类型类 + 多态函数    （程序是函数）

配合方式：
□ 约束即 Cats 类型类：Monad/Concurrent/Temporal/Parallel
□ 效果即 Cats Effect：F = IO 是「生产解释器」最常用实现
□ MTL 风格：更细粒度约束（MonadError/Ask/Local）
  → 比「一整个 IO」更可测试（约束即依赖声明）
□ 组合器即语法：traverse/mapN/parTraverse 在代数上直接用
MTL 补充：
□ MonadError[F, E]：类型化错误约束（不用把 E 写死在签名里）
□ Ask/Local：环境（配置）注入的代数化
□ ReaderT：让 F 带上配置依赖的另一种编码
模块化建议：
□ 约束用「上下文参数」汇总（[F[_]: Monad: Concurrent]）
□ 别让业务代码直接依赖 IO —— 依赖约束
□ 只在「入口」把 F 固定成 IO

import cats.effect.IO
import cats.effect.kernel.Concurrent
import cats.syntax.all.*
// 业务代码只依赖约束，入口才固定 IO
def background[F[_]: Concurrent](
    fa: F[Unit]
)(using inventory: Inventory[F]): F[Unit] =
  fa.start.flatMap(_.join)                    // par/race 需 Concurrent
def mainProgram: IO[Unit] =
  background[IO](inventoryIO.reserve("A1", 1).void)(using invIO)

错误表达：
□ 类型化错误：方法返回 F[Either[DomainError, A]]
  → 调用方用 traverse(identity)/liftTo 折叠
□ MonadError：约束带 E，用 raiseError/recoverWith
  → 好处：错误处理语法统一
□ 基础设施错误（超时/连接）：外层解释器兜底
  → 代数里不声明，由效果系统处理
副作用表达：
□ 代数方法签名：F[A] 表示「会发生领域副作用」
□ 副作用类型由 F 决定（IO = 真副作用，State = 模拟）
□ 不要在代数里偷偷 println/Thread.sleep
  → 否则测试解释器也带副作用
□ 时间/随机：抽象成代数（Clock/Random）以便测试

import cats.*
import cats.syntax.all.*
// 类型化错误的两种表达
trait Repo[F[_]]:
  def save(x: User): F[Either[RepoError, Unit]]      // 显式 Either
  def load(id: Long): F[User]                        // 隐含 MonadError
def saveFlow[F[_]: Monad](repo: Repo[F])(u: User): F[Unit] =
  repo.save(u).flatMap {
    case Left(e)  => Monad[F].pure(println(e))       // 显式处理
    case Right(_) => Monad[F].unit
  }

何时用：
□ 有「多解释器」需求：生产/测试/模拟/回放
□ 有「领域 DSL」：业务语言值得内嵌
□ 有「架构边界」：核心不依赖实现
□ 不需要：简单 CRUD、一次性脚本（加抽象反而贵）
引入路线（渐进）：
① 先写具体实现，跑通业务
② 提炼 trait 接口（F = 具体效果，如 IO）
③ 泛型化：trait Inventory[F[_]] + 解释器 given
④ 程序多态化：业务函数加 [F[_]: Monad]
⑤ 测试解释器就位 → 获得测试性红利
反面模式：
□ 为抽象而抽象：一个接口一个实现也上 Tagless
□ 约束爆炸：方法里挂 6 个类型类约束
□ F 泄漏：业务代码直接 new IO / 用具体 IO 类型
□ 解释器难写：每个约束都要满足导致实现成本高

成本收益：
收益 = 可测试性 + 可替换性 + 边界清晰
成本 = 泛型样板 + 约束推断 + 心智负担
小项目收益 < 成本，核心领域收益 > 成本