Adobe AEM下载组件基于HTL与Java获取DAM资产dc:title、dc:description失效问题排查

问题背景 #

在AEM站点开发中，页面属性配置了用于选择DAM中PDF文件的路径字段，配套下载组件需要在选中PDF存在时，展示对应PDF的标题与描述信息。参考早年CQ/AEM的实现逻辑编写的代码运行后，始终无法正常获取PDF的标题、描述值。

原有实现代码 #

HTL模板逻辑

<div data-sly-test="${pageProperties.pdfFileReference}" class="download-container ${properties['backgroundColor']}">
    <sly data-sly-use.pdfInfo="${'xx.xxx.PDFInfoDataProvider @ pdfPath=pageProperties['pdfFileReference']}">
        <a class="download-title" href="${pageProperties.pdfFileReference}" data-analytics-cta-text="${pdfInfo.fileTitle}">
            <span class="download-title">${pdfInfo.fileTitle}</span>
        </a>
        <div class="download-description">${pdfInfo.fileDescription}</div>
    </sly>
</div>

后端Java实现

package xx.xxx;

public class PDFInfoDataProvider extends WCMUsePojo {
    private String fileTitle;
    private String fileDescription;
    private String pdfPath;

    @Override
    public void activate() throws Exception {
        pdfPath = get("pdfPath", String.class);
        resolve();
    }

    private void resolve() {
        Resource resource = getResourceResolver().getResource(pdfPath);
        Asset asset = resource.adaptTo(Asset.class);
        String title = asset.getMetadataValue("dc:title");
        String description = asset.getMetadataValue("dc:description");
        fileTitle = title;
        fileDescription = description;
    }

    public String getTitle() { return  fileTitle; }
    public String getFileDescription() { return fileDescription; }
}

核心问题根源排查 #

• JavaBean Getter方法与HTL取值不匹配
  HTL读取对象属性时，严格按照JavaBean规范匹配对应Getter方法。HTL中通过pdfInfo.fileTitle取值时，会查找类中getFileTitle()方法作为值来源；但原代码中标题对应的Getter是getTitle()，两者不匹配，最终读取结果为null。
• 全链路无空值保护，易触发空指针异常
  代码未对资源查询结果、资产转换结果做判空：当传入路径不存在、当前运行权限不足、路径格式异常时，getResource()会返回null，直接调用adaptTo(Asset.class)会抛出NPE，导致组件渲染中断，前端无法拿到任何元数据。
• 框架API版本适配问题
  目前AEM 6.3+版本已官方废弃WCMUsePojo实现，部分新版本环境下，WCMUsePojo通过get()方法接收HTL传参的逻辑存在兼容问题，会导致pdfPath注入值为null，后续资源查询无有效结果。
• 元数据读取异常
  如果DAM中对应PDF资产未触发元数据提取工作流，dc:title、dc:description字段没有实际值，getMetadataValue()会返回null，直接赋值后前端展示为空白。
• 路径格式不兼容
  部分路径选择器组件存储的值包含Rendition路径后缀（如/content/dam/xxx.pdf/_jcr_content/renditions/original），直接传给ResourceResolver查询Asset时会匹配失败。

可落地修正实现 #

• 替换废弃的WCMUsePojo为标准Sling模型实现，适配HTL传参规范，增加全链路空值保护与默认值兜底：

package xx.xxx;

import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.models.annotations.DefaultInjectionStrategy;
import org.apache.sling.models.annotations.Model;
import org.apache.sling.models.annotations.injectorspecific.InjectionStrategy;
import org.apache.sling.models.annotations.injectorspecific.ValueMapValue;
import org.apache.sling.models.annotations.injectorspecific.Inject;
import com.day.cq.dam.api.Asset;
import org.apache.commons.lang3.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;

@Model(
    adaptables = Resource.class,
    defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)
public class PDFInfoModel {
    private static final Logger log = LoggerFactory.getLogger(PDFInfoModel.class);
    private static final String DEFAULT_DOWNLOAD_TITLE = "PDF文件下载";

    @ValueMapValue(name = "pdfPath", injectionStrategy = InjectionStrategy.REQUIRED)
    private String pdfPath;

    @Inject
    private Resource resource;

    private String fileTitle;
    private String fileDescription;

    @PostConstruct
    public void init() {
        // 清洗路径，截掉Rendition相关后缀
        String cleanPdfPath = StringUtils.substringBefore(pdfPath, "/_jcr_content");
        ResourceResolver resolver = resource.getResourceResolver();
        Resource pdfResource = resolver.getResource(cleanPdfPath);

        // 资源不存在时走默认值逻辑
        if (pdfResource == null) {
            log.warn("未查询到对应PDF资源，路径: {}", cleanPdfPath);
            fileTitle = DEFAULT_DOWNLOAD_TITLE;
            fileDescription = StringUtils.EMPTY;
            return;
        }

        Asset pdfAsset = pdfResource.adaptTo(Asset.class);
        // 资源不是合法DAM资产时走默认值逻辑
        if (pdfAsset == null) {
            log.warn("路径对应资源不是DAM资产，路径: {}", cleanPdfPath);
            fileTitle = DEFAULT_DOWNLOAD_TITLE;
            fileDescription = StringUtils.EMPTY;
            return;
        }

        // 读取元数据，空值兜底
        fileTitle = StringUtils.defaultIfBlank(
            pdfAsset.getMetadataValue("dc:title"),
            pdfAsset.getName()
        );
        fileDescription = StringUtils.defaultString(pdfAsset.getMetadataValue("dc:description"));
    }

    // 严格匹配HTL取值的Getter方法
    public String getFileTitle() {
        return fileTitle;
    }

    public String getFileDescription() {
        return fileDescription;
    }
}

• 修正HTL模板的调用语法，适配Sling模型的传参规则：

<div data-sly-test="${pageProperties.pdfFileReference}" class="download-container ${properties['backgroundColor']}">
    <sly data-sly-use.pdfInfo="${'xx.xxx.PDFInfoModel @ pdfPath=pageProperties.pdfFileReference'}">
        <a class="download-link" href="${pageProperties.pdfFileReference}" data-analytics-cta-text="${pdfInfo.fileTitle}">
            <span class="download-title">${pdfInfo.fileTitle}</span>
        </a>
        <div class="download-description">${pdfInfo.fileDescription}</div>
    </sly>
</div>

• 配套校验项
  • 确认DAM中对应PDF资产已触发「资产元数据提取」工作流，确保元数据字段有真实值
  • 检查组件绑定的服务用户权限，确保拥有DAM路径的读取权限，避免因权限问题无法查询资源
  • 本地调试时打断点确认传入的pdfPath值格式、资源查询结果是否符合预期

内容的提问来源于stack exchange，提问作者user15496195