Freemarker遍历对象ArrayList无法访问属性问题排查

嘿，这个问题我在项目里碰到过好几次！能遍历集合但拿不到对象属性，核心问题基本都和Freemarker访问Java对象的规则、你的POJO类写法有关。咱们逐一排查：

最常见原因：POJO缺少规范的Getter方法 #

Freemarker不会直接访问Java对象的私有字段，它完全依赖标准的JavaBean Getter方法。举个例子：

• 如果模板里写的是row.hash，那你的Item类必须有public String getHash()（对应字段类型的Getter），而不能只定义private String hash;字段。
• 注意Getter的命名规则：字段名hash对应getHash()，字段userName对应getUserName()——首字母大写加get前缀，大小写错了Freemarker就认不出来。比如你把Getter写成getHASH()，模板里的row.hash就会返回null。

第二可能：属性名称拼写/大小写不匹配 #

仔细核对模板里的属性名和POJO里的字段/Getter是否完全一致：

• 比如POJO里字段是hashCode，模板里写成了hash；或者POJO里是Hash，模板里写成hash，这种大小写或拼写差异都会导致Freemarker认为属性不存在。

容易忽略的点：POJO类或Getter的访问权限问题 #

确保你的Item类是public修饰的，并且所有需要访问的Getter方法也是public的。如果类是包私有（没有public修饰），或者Getter是private/protected，Freemarker的反射机制无法访问这些属性，就会报“missing”错误。

排查小细节：集合中是否混入null元素 #

虽然你说能按元素数量遍历，但如果ArrayList<Item>里某个位置是null，遍历到这个元素时row本身就是null，访问row.hash自然会报错。可以在模板里临时加个判断排查：

<#list items as row>
  <#if row??>
    ${row.hash}
  <#else>
    发现null元素！
  </#if>
</#list>

极端情况：Freemarker对象包装配置错误 #

极少数情况下，是因为项目自定义了Freemarker的ObjectWrapper，导致没有启用对标准JavaBean的支持。默认的DefaultObjectWrapper是支持JavaBean的，但如果配置被修改，比如禁用了Bean属性访问，就会出现这种问题。可以检查你的Freemarker配置代码，确保使用默认包装器或者正确配置了Bean支持。

快速验证步骤 #

1. 先检查Item类的Getter方法，确保符合规范且权限正确；
2. 在模板里输出${row?api}，查看Freemarker能识别的属性列表，确认hash是否在其中；
3. 打印ArrayList的内容，排查是否有null或类型错误的元素。

内容的提问来源于stack exchange，提问作者Gábor DANI