cats-effect-resource

Cats Effect Resource（Scala）

快速入门

• 使用 Resource.make、Resource.makeCase 或 Resource.fromAutoCloseable 为每个需要自行管理、可释放的值建模。
• 切勿从 .use 返回已获取的句柄；.use 完成时会释放该句柄。只返回作用域内计算出的值。
• 类不得在构造函数、字段或顶层 val 中分配需要自行管理的资源。使用返回 Resource[F, Service] 的伴生对象／工厂方法，然后将已获取的私有依赖项传入构造函数。
• 使用 Resource.fromAutoCloseable(Sync[F].blocking(...)) 或 IO.blocking(...) 包装 Java AutoCloseable 值。
• 使用 flatMap、mapN、parMapN 或辅助构造函数组合资源；负责管理生命周期的 API 应公开 Resource[F, A]。
• 请阅读 references/resource.md，了解模式、最佳实践和经过类型检查的示例。

工作流

1. 确定每个需要释放或关闭生命周期的值。
2. 将获取和释放操作移入 Resource[F, A]；在 F 中延迟副作用（Sync[F].delay/blocking、IO.blocking 等）。
3. 使用已获取的构造函数参数构建类；将构造逻辑放入返回 Resource 的 resource/create 工厂方法中。
4. 在调用 .use 之前，将较低层级的资源组合成较高层级的资源。
5. 在生命周期边界（IOApp、服务启动、测试夹具）使用 .use 运行，并将原始句柄保留在 use 作用域内。
6. 仅在确实需要分开获取和释放的互操作场景中使用 allocated，并确保最终化器恰好调用一次。

使用指南

• 当组合和取消安全性很重要时，优先使用 Resource，而不是 try/finally 或 bracket。
• 调用会阻塞的 JVM API 进行获取和释放时，使用 IO.blocking（或 Sync[F].blocking）。
• 在 .use 内部的使用阶段调用可能阻塞的操作时，优先使用 IO.interruptible/Sync[F].interruptible。
• 仅对不拥有最终化器的效果使用 Resource.eval；它不能替代资源获取。
• 每次使用 use 都会获取一个新的资源。如果需要共享同一个句柄以执行多个操作，请在一次 .use 中完成这些操作。
• 对于后台 fiber，使用 Resource、.background 或 Supervisor，以确保取消时进行清理。
• 添加或更改 Scala 示例时，请更新并编译打包的 scripts/verify-examples.scala 脚本。

参考资料

• 加载 references/resource.md，了解 API 详情、模式和示例；代表性检查脚本为 scripts/verify-examples.scala。
• Kotlin/Arrow 对应内容请参阅 arrow-resource 技能。
• 使用 npx skills add https://github.com/alexandru/skills --skill cats-effect-resource 安装此技能。