Add zomListMap method for creating zero/one/many element List MapCodec 添加零一多元素列表 MapCodec

[QiuShui1012]

No description provided.

[Gugle2308]

代码审查摘要 — PR #81

仓库： Anvil-Dev/AnvilLib · PR #81 codec/26.1 → dev/26.1
状态： opened · 作者： QiuShui1012

结论：评论（1 个关键问题，1 个范围纯度警告，1 条建议）

---

🔴 关键

新增了未使用的 import DamageSourcePredicate（第 9 行）

+import net.minecraft.advancements.criterion.DamageSourcePredicate;

这个 import 在整个 diff 中仅出现一次，且新方法 zomListMap 中完全没有使用它。应该是 IDE 自动补全或复制粘贴时混入的遗留无关导入。会导致编译警告（unused import），建议删除。

---

⚠️ 警告

范围纯度问题：Javadoc 风格变更波及了无关方法

PR 将两个已有方法 blockStatePropertiesCodec（行 25-31）和 appendBlockStatePropertyCodec（行 44-54）的 /** ... */ Javadoc 改为了 /// 行注释。这些方法与本次添加 zomListMap 的特性完全无关，属于范围外的噪音变更。

建议：如果这是有意统一代码库注释风格，应使用单独的 PR 完成；否则建议撤销这两处变更，保持 diff 干净聚焦于新功能。

---

💡 建议

建议添加单元测试

zomListMap 作为一个通用的编解码工具方法，建议添加 round-trip 序列化测试覆盖三种情况：

场景	编码预期	解码预期
空列表 []	字段缺失（field absent）	List.of()
单元素 [x]	直接为值 x（非数组）	singletonList(x)
多元素 [a, b, c]	JSON 数组 [a, b, c]	List.of(a, b, c)

示例测试框架（使用 Mojang 的 JsonOps）：

var codec = CodecUtil.zomListMap(Codec.STRING, "items");
var data = List.of("a", "b");
JsonElement json = codec.codec().encodeStart(JsonOps.INSTANCE, data).getOrThrow();
// 验证 json 为数组 ["a", "b"]
var decoded = codec.codec().parse(JsonOps.INSTANCE, json).getOrThrow();
assertEquals(data, decoded);

---

✅ 看起来不错

zomListMap 核心逻辑正确。 使用 Codec.mapEither 结合 optionalFieldOf（零/一元素）与 listOf().fieldOf（多元素），配合 xmap 双向转换，三态分支处理清晰：

• 编码： size ≤ 1 → Either.left(Optional.of/empty)，size > 1 → Either.right(list)
• 解码： left(Optional.empty) → 空列表，left(Optional.of(v)) → 单元素列表，right(list) → 保持原样

边界情况均正确，没有 NPE 或无限递归风险。

---

由 Hermes Agent 审查

[Gugle2308]

代码审查摘要 — PR #81

结论：评论（无阻塞性问题，2条建议）

操作： synchronize — 执行标准审查
更改： 1个文件，+22行，−0行 — 新增 CodecUtil.zomListMap() 方法

---

✅ 正确性

反序列化/序列化对称性正确：

存储形态	序列化输出	反序列化结果
[]（零）	字段不存在	List.of() ✅
[x]（一）	单值字段	Collections.singletonList(x) ✅
[a,b,c]（多）	JSON 数组	原 List 透传 ✅

list.getFirst() 仅在 size() == 1 分支调用，无空列表 NPE 风险。Java 21 的 SequencedCollection.getFirst() 兼容性确认 ✅。

💡 建议

1. 返回不可变列表的文档警告 — 反序列化路径中，零元素分支返回 List.of()（不可变），单元素分支返回 Collections.singletonList()（不可变），多元素分支返回的 List 可变性取决于 codec.listOf() 的默认行为（通常是 ArrayList，可变）。三者的可变性不一致，且不可变列表若被下游调用 add()/remove() 会抛出 UnsupportedOperationException。建议：

   • 在 Javadoc 中注明「返回值在零/单元素时不可变，多元素时可变的」的一致性警告
   • 或统一包装为 new ArrayList<>(...) 保证一致性

2. List.of(element) 替代 Collections.singletonList(element)（可选） — List.of(element) 和 Collections.singletonList() 都返回不可变单元素列表，但 List.of() 已被 JDK 9+ 推荐为首选方式，与上文的 List.of()（空列表）保持风格一致。当前写法无功能问题，仅风格建议。

✅ 看起来不错

• Javadoc 清晰说明了 ZOM 模式（零/一/多元素列表）的用途
• 参数命名规范（codec, name）
• 新增 import java.util.Collections 仅用于 singletonList，导入精确
• 与文件已有的 Function.identity() 等模式一致
• 无安全风险，无性能问题，无线程安全问题（方法纯函数式，无状态存储）
• Java 21 API 使用正确（List.getFirst(), Optional.orElse() 等）

---

由 Hermes Agent 审查

[Gugle2308]

🌿 Roseau API Breaking Change Report

Module	Status	Breaking Changes
codec	✅ Compatible	0
collision	✅ Compatible	0
config	✅ Compatible	0
integration	✅ Compatible	0
moveable-entity-block	✅ Compatible	0
network	✅ Compatible	0
rendering	✅ Compatible	0
space-select	✅ Compatible	0
font	✅ Compatible	0
util	✅ Compatible	0
explosion	✅ Compatible	0
rpc	✅ Compatible	0
multiblock	✅ Compatible	0
recipe	✅ Compatible	0
registrum	✅ Compatible	0
sync	✅ Compatible	0
wheel	✅ Compatible	0
main	✅ Compatible	0

Full CSVs: see the Artifacts section of this workflow run.

[Gugle2308]

🌿 Roseau API Breaking Change Report

Module	Status	Breaking Changes
codec	✅ Compatible	0
collision	✅ Compatible	0
config	✅ Compatible	0
integration	✅ Compatible	0
moveable-entity-block	✅ Compatible	0
network	✅ Compatible	0
rendering	✅ Compatible	0
space-select	✅ Compatible	0
font	✅ Compatible	0
util	✅ Compatible	0
explosion	✅ Compatible	0
rpc	✅ Compatible	0
multiblock	✅ Compatible	0
recipe	✅ Compatible	0
registrum	✅ Compatible	0
sync	✅ Compatible	0
wheel	✅ Compatible	0
main	✅ Compatible	0

Full CSVs: see the Artifacts section of this workflow run.

[Gugle2308]

PR #81 的动作为 closed（已关闭），按审查协议要求：

如果操作是 "closed" 或 "labeled"，stop here，不要发布评论。

因此本次不进行代码审查，也不发布任何评论。PR 已合并/关闭，无需进一步操作。