JSON 编解码与性能：circe 派生、jsoniter-scala 代码生成与选型

选型决策的关键问题：
1. 边界吞吐是否已经接近瓶颈？（先用 jmh 实测，别凭感觉）
2. 数据契约是否由你控制？（能控制就优先编译期检查）
3. 是否需要在纯函数层面对 JSON 做变换？（circe 的 ADT 更顺手）
4. 是否已有大量 Java 生态的 DTO？（Jackson 兼容性更好）
5. 是否需要流式解析超大文档？（两者的流式支持差异明显）

import io.circe.*
import io.circe.parser.*
import io.circe.syntax.*

// Json ADT 的六个构造子
val j1: Json = Json.Null
val j2: Json = Json.fromInt(42)
val j3: Json = Json.obj("name" -> Json.fromString("ada"), "age" -> Json.fromInt(36))
val j4: Json = Json.arr(Json.fromInt(1), Json.fromInt(2))

// 解析：字符串 → Either[ParsingFailure, Json]
val parsed: Either[ParsingFailure, Json] = parse("""{"a":1}""")

// 编码：任意类型 → Json（需要隐式 Encoder）
final case class User(name: String, age: Int)
given Encoder[User] = u => Json.obj("name" -> u.name.asJson, "age" -> u.age.asJson)
val encoded: Json = User("ada", 36).asJson

// 游标：在不解码成 case class 的前提下导航与取值
val cursor: ACursor = j3.hcursor.downField("name")
val name: Decoder.Result[String] = cursor.as[String]

circe 的层次：
□ Json            纯数据 ADT，不含类型类
□ Decoder[A]      Json → Either[DecodingFailure, A]
□ Encoder[A]      A → Json
□ Codec[A]        二者的组合（extends Decoder with Encoder）
□ HCursor/ACursor 导航与局部解码，无需完整 case class
□ Printer         控制输出（缩进、排序、转义、最大深度）

import io.circe.*
import io.circe.generic.semiauto.*
import io.circe.generic.extras.Configuration
import io.circe.generic.extras.semiauto.*

final case class Address(street: String, city: String, zip: String)
final case class User(id: String, name: String, address: Address, tags: List[String])

object User:
  given Decoder[Address] = deriveDecoder
  given Encoder[Address] = deriveEncoder
  given Decoder[User] = deriveDecoder
  given Encoder[User] = deriveEncoder

// 字段重命名与默认值（extras 模块）
given Configuration = Configuration.default
  .withSnakeCaseMemberNames              // userName → user_name
  .withDefaults                          // 缺失字段用默认值

// 密封特质的派生：判别字段 + 子类型注册
import io.circe.generic.extras.ConfiguredJsonCodec

@ConfiguredJsonCodec sealed trait Event
object Event:
  final case class Created(id: String) extends Event
  final case class Deleted(id: String, reason: Option[String]) extends Event

// 等价于：
// { "type": "Created", "id": "..." }
// { "type": "Deleted", "id": "...", "reason": null }

// 手写 Decoder：需要跨字段校验、自定义解析逻辑时
given Decoder[User] = (c: HCursor) =>
  for
    id   <- c.downField("id").as[String]
    name <- c.downField("name").as[String]
    addr <- c.downField("address").as[Address]
    tags <- c.downField("tags").as[Option[List[String]]].map(_.getOrElse(Nil))
    _    <- Either.cond(id.nonEmpty, (), DecodingFailure("id 不能为空", c.history))
  yield User(id, name, addr, tags)

import io.circe.*
import io.circe.parser.decode

val bad = """{"id":"1","name":42,"address":{"city":"SH"}}"""

decode[User](bad) match
  case Right(u)  => println(s"ok: $u")
  case Left(err) =>
    // 打印人类可读的路径
    println(s"失败: ${err.message}")
    println(s"位置: ${err.history.reverse.mkString(".")}")

// 累积错误：默认 fail-fast，需要全部错误时手工收集
def decodeAll(c: HCursor): Decoder.Result[(String, Int)] =
  val a = c.downField("a").as[String]
  val b = c.downField("b").as[Int]
  (a, b) match
    case (Right(x), Right(y)) => Right((x, y))
    case (Left(e1), Left(e2)) =>
      Left(DecodingFailure(s"${e1.message}; ${e2.message}", c.history))
    case (Left(e), _) => Left(e)
    case (_, Left(e)) => Left(e)

错误诊断的实践：
□ 对外：只回 400 + 简短消息，绝不把 DecodingFailure 原文暴露给客户端
□ 对内：日志里打印完整 history 与原始 payload（脱敏后）
□ 契约：把「缺字段」「类型不符」「越界」区分为不同的错误码
□ 测试：为每个可空/可选字段写「缺失」「null」「错误类型」三类用例
□ 监控：按字段统计解码失败率，定位上游契约漂移

import com.github.plokhotnyuk.jsoniter_scala.core.*
import com.github.plokhotnyuk.jsoniter_scala.macros.*

final case class Address(street: String, city: String, zip: String)
final case class User(id: String, name: String, address: Address, tags: List[String])

// 编译期生成 codec：给定配置后展开为字节级读写循环
given JsonValueCodec[Address] = JsonCodecMaker.make
given JsonValueCodec[User] = JsonCodecMaker.make(
  CodecMakerConfig
    .withFieldNameMapper(JsonCodecMaker.enforce_snake_case)
    .withDiscriminatorFieldName(Some("type"))
    .withRequireCollectionFields(true)      // 集合字段必须存在
)

// 使用：字节数组直接进出，无中间 JSON 树
val addr = Address("Main St 1", "SH", "200000")
val bytes: Array[Byte] = writeToArray(User("u1", "ada", addr, List("vip")))
val user: User = readFromArray[User](bytes)

// 解析失败抛 JsonReaderException（可被捕获，含 offset 与路径）
try readFromArray[User](Array[Byte]('{', '}'))
catch case e: JsonReaderException => println(s"offset=${e.offset} ${e.getMessage}")

jsoniter-scala 的配置要点：
□ CodecMakerConfig 在编译期生效，改动即全量重编译
□ withDiscriminatorFieldName：密封特质的判别字段名
□ withFieldNameMapper：snake_case / kebab-case 等命名策略
□ withRequireCollectionFields：缺失集合字段是报错还是空集合
□ withTransientEmpty：空集合/空字符串是否省略（影响输出体积）
□ withBigDecimalScaleLimit：限制小数位数，防解析爆炸
□ 不支持运行时反射 → 第三方 DTO 需要手写 codec

import org.openjdk.jmh.annotations.*
import java.util.concurrent.TimeUnit

@State(Scope.Benchmark)
@BenchmarkMode(Array(Mode.Throughput, Mode.AverageTime))
@OutputTimeUnit(TimeUnit.MILLISECONDS)
@Warmup(iterations = 5, time = 1)
@Measurement(iterations = 10, time = 1)
@Fork(2)
class JsonBench:
  @Param(Array("small", "medium", "large"))
  var size: String = _

  var payload: Array[Byte] = _
  var circePayload: String = _

  @Setup(Level.Trial)
  def setup(): Unit =
    val u = BenchData.user(size)
    payload = writeToArray(u)
    circePayload = u.asJson.noSpaces

  @Benchmark def jsoniterDecode: User = readFromArray[User](payload)
  @Benchmark def circeDecode: Either[io.circe.Error, User] =
    io.circe.parser.decode[User](circePayload)

# 跑基准（sbt-jmh 插件）
sbt "Jmh/run -i 10 -wi 5 -f 2 -t 1 .*JsonBench.*"

# 关键指标
# Throughput (ops/ms)    吞吐：每秒能处理多少次
# AverageTime (ms/op)    延迟：单次平均耗时
# GC profiler            分配率：-prof gc 看 B/op
sbt "Jmh/run -prof gc .*JsonBench.jsoniterDecode"

实测时最容易犯的错：
□ 用玩具 payload（3 个字段）测出「十倍差距」，真实数据只有 1.2 倍
□ 没有预热（JIT 未编译），第一次迭代的数字毫无意义
□ 在同一个 JVM 里混测两个库（互相干扰内联决策）
□ 忽略分配率：吞吐相近但分配率差 5 倍，GC 压力完全不同
□ 只测解码不测编码：生产上写入往往更频繁
□ 忘记关掉日志/断言等干扰

import io.circe.*
import com.github.plokhotnyuk.jsoniter_scala.core.*

// 混合：jsoniter 负责边界的高吞吐，circe 负责灵活的中间变换
def handle(raw: Array[Byte]): Either[String, Json] =
  try
    val user = readFromArray[User](raw)           // 快：字节 → 对象
    val enriched = user.copy(tags = user.tags :+ "processed")
    Right(enriched.asJson)                        // 灵活：对象 → 任意 JSON
  catch
    case e: JsonReaderException => Left(s"bad payload at ${e.offset}")

// 反向：circe 拼出的 JSON 交给 jsoniter 快速写出
def emit(j: Json): Array[Byte] =
  writeToArray(j.noSpaces, WriterConfig.withIndentionStep(0))

分场景建议：
场景                         推荐            理由
公开 API 入参/出参            circe           生态集成好、错误可诊断
内部高 QPS RPC                jsoniter        吞吐与分配优势明显
Kafka 大消息                  jsoniter        避免中间 Json 树的内存峰值
配置文件/脚本                 circe           灵活、可部分解码
日志与调试输出                circe           Printer 控制能力强
第三方契约（形状不定）        circe 游标       不需要完整模型
已有大量 Java DTO             Jackson         兼容性成本最低

import cats.effect.*
import org.http4s.*
import org.http4s.dsl.io.*
import org.http4s.circe.CirceEntityCodec.*

val routes: HttpRoutes[IO] = HttpRoutes.of[IO] {
  case req @ POST -> Root / "users" =>
    req.decode[User] { u =>                 // 自动反序列化，失败即 400
      Ok(u.copy(tags = u.tags :+ "created"))
    }
  // 直接读原始字节，交给 jsoniter 解析（避免中间 Json 树）
  case req @ POST -> Root / "fast" =>
    req.as[Array[Byte]].flatMap { raw =>
      IO(readFromArray[User](raw)).attempt.flatMap {
        case Right(u) => Ok(u.name)
        case Left(e: JsonReaderException) => BadRequest(e.getMessage)
        case Left(e)  => InternalServerError(e.getMessage)
      }
    }
}

集成的几个坑：
□ http4s 默认对超大 body 无限制 → 用 EntityLimiter 设上限
□ 内容类型不符时返回 415 而不是 400，别让客户端困惑
□ 空 body 与 "null" 的处理不同：前者 400，后者要显式建模 Option
□ 流式解析超大数组：circe 需要 fs2 + jawn 的流式解析器
□ Kafka 侧：反序列化失败不可重试，直接进死信队列

import io.circe.*
import io.circe.generic.semiauto.*

// 演进策略一：新字段给默认值（向后兼容，老客户端不发也能解）
final case class Order(id: String, amount: BigDecimal, currency: String = "CNY")
given Decoder[Order] = deriveDecoder
given Encoder[Order] = deriveEncoder

// 演进策略二：用 Option 建模「可能缺失」（兼容 null 与缺失两种形态）
final case class Profile(name: String, nickname: Option[String])
// 注意：circe 默认把 None 编码为 null；要省略需自定义 Encoder
given Encoder[Profile] = p => Json.obj(
  "name" -> p.name.asJson,
  "nickname" -> p.nickname.fold(Json.Null)(_.asJson)   // 显式控制输出形态
)

// 演进策略三：判别字段 + 版本号，支持多版本共存
final case class Envelope(v: Int, payload: Json)

兼容性检查清单：
□ 新增字段：给默认值 → 兼容；不给默认值 → 破坏（老数据解不出）
□ 删除字段：老客户端仍在发 → 用 extras 的 withDefaults 忽略未知字段
□ 类型变更（int → string）：破坏，需并行发新字段再下线旧字段
□ 枚举新增取值：消费方必须有 unknown 兜底，否则整体失败
□ 命名策略变更：破坏，等价于全字段重命名
□ null 与缺失：语义不同，明确约定并写测试
□ 时间格式：统一用 ISO-8601 带时区，别用本地时间戳