PHP服务端模式DataTables不显示数据行 始终提示无匹配记录故障

基础说明 #

• 开发场景：参照DataTables官方ColReorder服务端集成规范开发，因未使用MySQL数据库，未引入官方标准服务端处理脚本（SPP），自行将地址列表数据集整理为数组结构，经JSON编码作为接口返回内容
• 故障表现：无论如何调整组件配置，表格始终无法加载数据行，页面固定提示「未找到匹配记录」；数据库实际存储超4000条地址记录，接口已按标准DataTables服务端格式组装返回内容

前端组件初始化代码 #

$(document).ready(function() {
    $('#table').DataTable({
        "serverSide": true,
        "processing": true,
        "ajax": {
            "url": "<?=url('database/addresses');?>",
            "dataSrc": "",
        },
      'columnDefs': [{
          'targets': 1,
          'checkboxes': {
             'selectRow': true
          }
      }],
      'select': {
          'style':    'multi',
          'selector': 'td:first-child'
      },
      'order': [[5, 'desc']],
        "columns": [
            { "data": "id" },
            { "data": "id" },
            { "data": "input_address" },
            { "data": "destination_address" },
            { "data": "callback_url" },
            { "data": "dateCreated.date" },
            { "data": "id" }
        ],
        'colReorder': true
    });
} );

页面表格结构代码 #

<form method="post" id="deleteMulti" class="ajax-multi" action="<?=url('XhPCrvFtQuE7gPP6/addresses/delete/selected');?>">
    <?= csrf() ?>
        <div class="row">
            <div class="col-xxl-12">
                <div class="card">
                    <div class="card-header">
                        <h4 class="card-title">Addresses [ <?=$count;?> ]</h4>
                        <div class="right fr">
                            <button class="btn tooltip" style="display: inline;" name="deleteSelected" title="Delete Selected Addresses"><i class="fa fa-trash" style="color: black;"></i></button>
                        </div>
                    </div>
                    <div class="card-body">
                        <div class="table-responsive">
                            <table id="table" class="display">
                               <thead>
                                  <tr>
                                    <th>#</th>
                                    <th><input type="checkbox" class="" id="checkAl"></th>
                                    <th>Input Address</th>
                                    <th>Output Address</th>
                                    <th>Callback Url</th>
                                    <th>Created</th>
                                    <th><i class="bi bi-archive-fill"></i></th>
                                  </tr>
                               </thead>
                               <tfoot>
                                  <tr>
                                     <th></th>
                                     <th></th>
                                     <th></th>
                                     <th></th>
                                     <th></th>
                                     <th></th>
                                     <th></th>
                                  </tr>
                               </tfoot>
                            </table>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </form>
</div>

后端接口返回逻辑代码 #

// 用于管理员地址页加载地址数据
public function getAddresses() {
    define('PAGE_NAME', 'Admin Addresses');

    // 硬编码跳过前100行，单页加载100条数据
    $addresses = \r\table('addresses')->orderBy(array('index' => \r\desc('dateCreated')))->skip(100)->limit(100)->run($this->conn);
    $addresses = $addresses->toArray();

    $count = count($addresses);

    $theArr = array();

    foreach ($addresses as $address) {
        $theArr[] = $address;
    }

    $final = array(
        'draw' => 1,
        'recordsTotal' => $count,
        'recordsFiltered' => $count,
        'data' => array_values($theArr)
    );

    if($count > 0) {
        echo json_encode($final, JSON_FORCE_OBJECT);
    } else {
        return false;
    }
}

故障根因说明 #

1. dataSrc配置与返回结构不匹配
   前端配置"dataSrc": ""时，组件会从接口返回内容的根级索引数组中读取表格行数据。但实际后端返回的是标准服务端对象结构，行数据嵌套在data字段下，配置错位导致组件无法读取到行集合，直接触发无数据提示。
2. draw参数未按规范回传
   服务端模式下，DataTables会在每次请求中携带递增的draw参数，用于匹配请求与响应的对应关系、完成安全校验。当前后端硬编码draw=1，未读取前端请求携带的draw值原样返回，会触发组件的响应校验失败，直接终止数据渲染流程。
3. JSON编码参数使用错误
   后端编码时使用JSON_FORCE_OBJECT参数，会强制将索引数组结构的data字段转换为普通对象结构，破坏DataTables对data字段必须为索引数组的解析要求，即便修正路径配置也会出现解析失败。
4. 分页逻辑未适配服务端模式规范
   当前查询逻辑硬编码skip(100)、limit(100)，未读取前端请求中携带的start、length分页参数，也未实现服务端搜索、排序的参数解析逻辑，返回内容不符合服务端模式的交互要求。
5. 统计值计算错误
   硬编码recordsTotal、recordsFiltered为当前分页返回的100条数量，未传入全表总记录数、过滤后总记录数，会导致分页组件计算逻辑错误，进一步触发无匹配记录的提示。

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