这是一份来自 maxrave-dev/kotlin-footguns 的 Kotlin 编码实践文档，关注的是一类难以察觉的缺陷：把分节 API 响应按位置映射成具名固定字段。
用途与适用场景 文档面向需要把服务端返回的“多个分节”响应（例如商品目录的多个货架）转换为领域模型的 Kotlin 开发者。它强调，响应本身就是分节列表，领域模型也应是分节列表。
主要能力与核心主张 文档主张模型定义为带 sections 列表的结构：Catalog 含 List<CatalogSection>，CatalogSection 含标题 title 与条目 items 列表。这样映射就是逐项 map，不存在隐藏的位置假设；消费者通过遍历分节来渲染，而不是按索引读取。
它指出，若模型是带固定具名字段的记录，就只能靠挑选索引来填充，位置读取不是个人失误，而是满足该类型的唯一方式；只改映射代码不改模型，同一问题会在下个版本回归。
文档列出的陷阱包括：按位置映射出错时只会错标而不会抛异常——响应新增前置分节后，每个映射整体偏移，所有访问都在范围内，不抛错、不记日志、界面看似正常，只收到“分类不对”的不可复现反馈，且可能只在登录账户、特定语言或地区出现。解构、require(size == 2)、与固定名称列表 zip、when(index) 等数量假设属于同一类问题，同样会在相同事件下出错。标题若随账户或地区本地化，则只是展示文本，不能用作代码中查找分节的键；需要特殊处理时，应寻找载荷中的稳定判别字段（如 endpoint 参数、渲染类型），没有就一律同样处理、由服务端决定顺序。消费者中的 forEachIndexed 若用索引决定某个货架是什么（例如首个使用特殊布局、在“类型分节”前加分隔线），会把位置假设重新引入 UI，更难发现。空分节会原样保留并渲染为只有标题没有内容，这可以是有意选择，但应由可指出的 filter 显式实现。若映射列表被缓存，缓存顺序是写入时的顺序，服务端移动后的分节在刷新前仍保持旧位置。
验证方式 文档认为，按位置映射在开发所用响应上总是正确的，因此能通过评审。有效测试应对比仅在生产变化维度上不同的两份响应：分别抓取未登录与登录、两种语言环境下的同一请求，对比分节标题与数量，任一变化即说明位置映射对部分用户已出错；再加入一个在首位插入分节的测试样本，断言 mapped.sections.size == response.size，只在原始顺序上有分节的样本反而会通过有缺陷的版本。文档还提醒，不要仅凭模型注释或单个保存的响应体下结论。
限制 文档未提供任何具体 API、价格、平台或安装方式信息。