MarkLogic Data Hub自定义步骤执行触发NullPointerException

问题背景 #

在MarkLogic Data Hub中实现了自定义步骤，用于从源数据库test读取XML文档并插入到目标数据库emeraldtest-STAGING。步骤逻辑单独运行正常，但执行Flow时触发NullPointerException，错误返回中stepName和stepDefinitionName字段为null。

排查方向 #

1. Flow与Step的关联配置

   • 检查Flow中步骤配置是否明确关联到已注册的Step Definition，是否存在名称拼写或配置项缺失导致Data Hub无法识别步骤信息。
   • 确认Step、Step Definition的名称在Data Hub注册表中完全匹配，无大小写、空格等差异。

2. 参数格式与传递问题

   • 检查自定义步骤的options配置格式是否符合Data Hub规范，比如permissions字段是否使用正确的数据结构。
   • 验证Flow执行时options参数是否正确传递到自定义模块，是否存在空值导致内部解析异常。

3. 权限与上下文问题

   • 确认执行Flow的用户拥有跨数据库操作的权限：包括读取源库文档、写入目标库文档的权限，以及xdmp:database权限访问对应数据库。
   • 检查跨数据库调用xdmp.invokeFunction的上下文是否完整，是否遗漏必要参数导致执行异常。

4. 代码空值处理

   • 检查自定义模块中对options、sourceQuery等参数的空值处理是否完善，避免因参数为空触发底层NPE。

解决建议 #

1. 修正Flow配置，明确关联Step Definition #

在Flow的步骤配置中添加stepDefinitionName，确保Data Hub能正确识别对应的步骤定义：

{
  "name": "emerald-db-flow",
  "description": "Flow to read from test DB and write to STAGING",
  "steps": {
    "1": {
      "stepName": "emerald-db-step",
      "stepDefinitionType": "custom",
      "stepDefinitionName": "emerald-db-reader"
    }
  }
}

2. 修正permissions配置格式 #

Data Hub要求permissions为数组结构，替换原字符串格式：
在Step和Step Definition的options中修改：

"permissions": [
  {"role": "data-hub-common", "capability": "read"},
  {"role": "data-hub-common", "capability": "update"}
]

3. 增强代码空值处理与异常捕获 #

在自定义模块main.mjs中添加参数校验和异常处理：

function main(content, options) {
  let sourceQuery = cts.trueQuery();
  // 校验并安全解析sourceQuery
  if (options?.sourceQuery) {
    try {
      sourceQuery = cts.query(options.sourceQuery);
    } catch (e) {
      xdmp.log(`Invalid source query: ${options.sourceQuery}, error: ${e.message}`);
    }
  }

  let uris = xdmp.invokeFunction(() => {
    return cts.uris(null, null, sourceQuery);
  }, { database: xdmp.database("test") });

  // 空URIs处理
  if (uris.length === 0) {
    xdmp.log("No URIs found matching the source query");
    return { uri: null, value: null, context: null };
  }

  for (let uri of uris) {
    let docContent = xdmp.invokeFunction(() => {
      return fn.doc(uri);
    }, { database: xdmp.database("test") });

    if (docContent) {
      xdmp.documentInsert(uri, docContent);
    } else {
      xdmp.log(`Document not found for URI: ${uri}`);
    }
  }

  return {
    uri: null,
    value: null,
    context: null
  };
}

module.exports = {
  main
};

4. 验证权限与日志排查 #

• 确认执行Flow的用户拥有data-hub-operator角色或对应数据库的读写权限。
• 开启MarkLogic服务器详细日志，查看NPE的完整堆栈跟踪，定位具体异常触发点。

内容的提问来源于stack exchange，提问作者Dharmendra Kumar Singh