MarkLogic：无需等待后台进程完成即可返回HTTP响应

问题背景 #

已创建一个REST API，接收UI的HTTP POST JSON请求数组，触发XQuery代码执行功能，耗时10-30分钟。需求是：请求进入MarkLogic后立即返回「上传已成功触发」响应，后台任务持续运行并插入报告文档、更新完成计数。

原代码大纲：

declare function local:upload-record($req-xml, $chunk-size,$upload-uri){
    if (exists($req-xml))
    then (
    let $log := xdmp:log("Upload started")
    <!-- some code to execute functionalities-->

                     ,
                      xdmp:spawn-function(function(){ 
                        local:upload-record(subsequence($req-xml, $chunk-size+1), $chunk-size,$upload-uri) 
                          }, 
                        <options xmlns="xdmp:eval">
                        <result>true</result>
                        
                        <update>true</update>
                        <commit>auto</commit>
                        </options>))
                    
     return $response)
     else xdmp:log("Job completed successfully")
};

let $req := xdmp:get-request-body("json")/node()

let $config := json:config("custom")
let $req-xml := json:transform-from-json($req,$config)
let $chunk-size := 10

let $resp := local:upload-record($req-xml, $chunk-size,$upload-uri)
  
return <response>Upload triggered successfully</response>

解决方案 #

问题1：实现即时响应与后台异步处理 #

原代码的核心问题是初始调用local:upload-record为同步执行，导致主线程无法立即返回响应。调整方案如下：

1. 将整个任务逻辑放入后台线程执行，主线程仅触发任务后直接返回响应
2. 优化xdmp:spawn-function选项，关闭结果返回以减少开销
3. 调整递归逻辑，确保所有chunk处理都在异步线程中完成

修改后的核心代码：

declare function local:upload-record($req-xml, $chunk-size, $upload-uri){
  if (exists($req-xml)) then (
    let $current-chunk := subsequence($req-xml, 1, $chunk-size)
    let $_ := xdmp:log("Processing chunk of size " || $chunk-size)
    <!-- 替换为实际业务逻辑：插入报告、更新完成计数 -->
    let $_ := (
      xdmp:log("Chunk processing completed"),
      xdmp:document-insert("/report/upload-progress.json", 
        json:object() || {"completed-count": xdmp:counter-increment("upload-counter")}
      )
    )
    <!-- 异步递归处理剩余请求 -->
    let $_ := xdmp:spawn-function(
      function(){ 
        local:upload-record(subsequence($req-xml, $chunk-size+1), $chunk-size, $upload-uri) 
      }, 
      <options xmlns="xdmp:eval">
        <update>true</update>
        <commit>auto</commit>
        <result>false</result>
      </options>
    )
    return ()
  ) else (
    xdmp:log("Job completed successfully"),
    xdmp:document-insert("/report/upload-progress.json", 
      json:object() || {"status": "completed", "total-count": xdmp:counter-get("upload-counter")}
    )
  )
};

let $req := xdmp:get-request-body("json")/node()
let $config := json:config("custom")
let $req-xml := json:transform-from-json($req, $config)
let $total-requests := count($req-xml)
let $max-threads := 32
let $chunk-size := 
  if ($total-requests <= $max-threads) then 1
  else ceiling($total-requests div $max-threads)

<!-- 直接触发后台任务，主线程立即返回 -->
let $_ := xdmp:spawn-function(
  function(){ local:upload-record($req-xml, $chunk-size, $upload-uri) },
  <options xmlns="xdmp:eval">
    <update>true</update>
    <commit>auto</commit>
    <result>false</result>
  </options>
)

return <response>Upload triggered successfully</response>

关键说明：

• 主线程不执行任何业务逻辑，触发后台任务后直接返回响应
• 使用xdmp:counter高效跟踪完成计数，避免频繁文档更新的性能损耗
• 设置<result>false</result>，减少不必要的结果传递开销

问题2：合理设置Chunk Size（基于最大线程数32） #

Chunk Size需平衡并发数与任务粒度，避免线程耗尽或过度细碎。

计算逻辑：

1. 总请求数N范围：1 ≤ N ≤ 1000
2. 最大可用线程数：32
3. 目标：chunk数量不超过32，同时保证每个chunk大小合理

实现规则：

• 当N ≤ 32：chunk-size设为1，每个请求单独用线程处理，最大化并发
• 当32 < N ≤ 1000：chunk-size = ceil(N / 32)，确保chunk数量不超过32

代码实现：

let $total-requests := count($req-xml)
let $max-threads := 32
let $chunk-size := 
  if ($total-requests <= $max-threads) then 1
  else ceiling($total-requests div $max-threads)

示例：

• 总请求数=1000 → chunk-size=32（31个chunk含32条，最后1个含28条，并发数32）
• 总请求数=50 → chunk-size=2（25个chunk，并发数25，未超线程上限）
• 总请求数=10 → chunk-size=1（10个线程并发，充分利用资源）

关键说明：

• 避免请求数远大于32时设过小的chunk-size，防止线程上下文切换开销激增
• 严格控制chunk数量不超过32，防止MarkLogic线程池耗尽影响其他业务

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