导入 JSON 前先校验：把问题定位到第几条记录

recordCount 是顶层数组长度；语法失败或顶层非数组时是 null。validRecordCount 是完全无错误的记录数量，仅供诊断，不能据此把整批失败改成“先导入合格部分”。

二、复制完整示例，在本地运行

保存下面整段为 json-check.cjs，在安装了 Node.js 的本机运行 node json-check.cjs。本文实际使用 Node.js v22.22.0。脚本无第三方依赖，不读真实文件、不联网、不写数据库；每组输入打印一行报告。所有 17 组输入都在代码中，可直接修改其中一组练习。

'use strict';

function validateRecords(records) {
  if (!Array.isArray(records)) {
    return { stage: 'contract', valid: false, recordCount: null,
      validRecordCount: 0,
      errors: [{ record: null, path: [], code: 'TOP_LEVEL_ARRAY' }] };
  }
  const fields = ['id', 'title', 'status', 'minutes'];
  const firstIds = new Map();
  const errors = [];
  let validRecordCount = 0;
  records.forEach((item, index) => {
    const start = errors.length;
    const add = (field, code, extra = {}) => errors.push({
      record: index + 1, path: field === null ? [index] : [index, field],
      code, ...extra
    });
    if (item === null || typeof item !== 'object' || Array.isArray(item)) {
      add(null, 'RECORD_OBJECT');
      return;
    }
    for (const field of fields) {
      if (!Object.hasOwn(item, field)) {
        add(field, 'REQUIRED');
        continue;
      }
      const value = item[field];
      if (field === 'id') {
        if (typeof value !== 'string' || !/^[a-z][a-z0-9-]{0,15}$/.test(value)) {
          add(field, 'ID_FORMAT');
        } else if (firstIds.has(value)) {
          add(field, 'DUPLICATE_ID', { firstRecord: firstIds.get(value) });
        } else {
          firstIds.set(value, index + 1);
        }
      } else if (field === 'title') {
        if (typeof value !== 'string' || value.trim().length === 0) {
          add(field, 'TITLE_TEXT');
        }
      } else if (field === 'status') {
        if (value !== 'draft' && value !== 'ready') add(field, 'STATUS_VALUE');
      } else if (!Number.isSafeInteger(value) || value < 0 || value > 480) {
        add(field, 'MINUTES_RANGE');
      }
    }
    for (const field of Object.keys(item).filter(key => !fields.includes(key)).sort()) {
      add(field, 'EXTRA_FIELD');
    }
    if (errors.length === start) validRecordCount++;
  });
  return { stage: 'contract', valid: errors.length === 0,
    recordCount: records.length, validRecordCount, errors };
}

function validateJson(text) {
  if (typeof text !== 'string') throw new TypeError('Expected JSON text');
  let parsed;
  try {
    parsed = JSON.parse(text);
  } catch (error) {
    if (!(error instanceof SyntaxError)) throw error;
    return { stage: 'syntax', valid: false, recordCount: null,
      validRecordCount: 0,
      errors: [{ record: null, path: [], code: 'JSON_SYNTAX' }] };
  }
  return validateRecords(parsed);
}

// All fixtures are fictional. No import, database or network operation.
const fixtures = [
  {
    "name": "valid",
    "text": "[{\"id\":\"a\",\"title\":\"  演示甲  \",\"status\":\"draft\",\"minutes\":0},{\"id\":\"b\",\"title\":\"演示乙\",\"status\":\"ready\",\"minutes\":480}]"
  },
  {
    "name": "empty",
    "text": "[]"
  },
  {
    "name": "non_array",
    "text": "{\"id\":\"a\"}"
  },
  {
    "name": "missing_id",
    "text": "[{\"title\":\"演示\",\"status\":\"draft\",\"minutes\":10}]"
  },
  {
    "name": "blank_title",
    "text": "[{\"id\":\"a\",\"title\":\"   \",\"status\":\"draft\",\"minutes\":10}]"
  },
  {
    "name": "string_minutes",
    "text": "[{\"id\":\"a\",\"title\":\"演示\",\"status\":\"draft\",\"minutes\":\"10\"}]"
  },
  {
    "name": "invalid_status",
    "text": "[{\"id\":\"a\",\"title\":\"演示\",\"status\":\"done\",\"minutes\":10}]"
  },
  {
    "name": "duplicate_id",
    "text": "[{\"id\":\"a\",\"title\":\"甲\",\"status\":\"draft\",\"minutes\":10},{\"id\":\"a\",\"title\":\"乙\",\"status\":\"ready\",\"minutes\":20}]"
  },
  {
    "name": "multi_error_invalid_first",
    "text": "[{\"id\":\"a\",\"title\":\" \",\"status\":\"done\",\"minutes\":\"5\",\"zeta\":true,\"alpha\":true},{\"id\":\"a\",\"title\":\"乙\",\"status\":\"ready\",\"minutes\":10},null]"
  },
  {
    "name": "malformed_json",
    "text": "[{\"id\":\"a\",}]"
  },
  {
    "name": "invalid_id",
    "text": "[{\"id\":\" A \",\"title\":\"演示\",\"status\":\"draft\",\"minutes\":10}]"
  },
  {
    "name": "invalid_minutes",
    "text": "[{\"id\":\"a\",\"title\":\"甲\",\"status\":\"draft\",\"minutes\":-1},{\"id\":\"b\",\"title\":\"乙\",\"status\":\"draft\",\"minutes\":481},{\"id\":\"c\",\"title\":\"丙\",\"status\":\"draft\",\"minutes\":1.5},{\"id\":\"d\",\"title\":\"丁\",\"status\":\"draft\",\"minutes\":9007199254740992}]"
  },
  {
    "name": "missing_all_fields",
    "text": "[{}]"
  },
  {
    "name": "non_object_records",
    "text": "[null,[],5]"
  },
  {
    "name": "id_length_16",
    "text": "[{\"id\":\"abcdefghijklmnop\",\"title\":\"demo\",\"status\":\"draft\",\"minutes\":1}]"
  },
  {
    "name": "id_length_17",
    "text": "[{\"id\":\"abcdefghijklmnopq\",\"title\":\"demo\",\"status\":\"draft\",\"minutes\":1}]"
  },
  {
    "name": "id_trailing_newline",
    "text": "[{\"id\":\"a\\n\",\"title\":\"demo\",\"status\":\"draft\",\"minutes\":1}]"
  }
];

if (require.main === module) {
  for (const { name, text } of fixtures) {
    console.log(JSON.stringify({ name, result: validateJson(text) }));
  }
}
module.exports = { validateJson, validateRecords, fixtures };

validateJson() 的入口只接受字符串，非字符串属于调用方式错误，会抛出 TypeError。只有 JSON 语法错误进入 stage: "syntax"；代码中的字段校验在解析之后单独执行，避免把校验器自身的程序错误误报成坏 JSON。JSON.parse() 可以解析出数组以外的值，遇到不符合 JSON 语法的文本会抛出 SyntaxError，因此“解析成功”和“符合这份字段规则”需要分别判断。MDN：JSON.parse

三、先写期望，再看实际报告

在实现前，我先独立写下前 14 组完整期望；随后补充冻结 16 位、17 位和末尾换行三个 ID 边界，再验收最终脚本。检查的不只是错误数量，还包括全部错误位置、错误码、顺序、重复项指向和有效记录数量。

读者运行后，可以依次核对这些结果：

1. valid：有效 2 条，错误 0；0 和 480 均通过，标题空格保留。
2. empty：有效，记录 0、有效记录 0。
3. non_array：TOP_LEVEL_ARRAY，记录总量为 null。
4. missing_id：第 1 条 id 报 REQUIRED。
5. blank_title：第 1 条 title 报 TITLE_TEXT。
6. string_minutes：第 1 条 minutes 报 MINUTES_RANGE。
7. invalid_status：第 1 条 status 报 STATUS_VALUE。
8. duplicate_id：第 2 条 id 报 DUPLICATE_ID，firstRecord: 1；有效记录为 1。
9. multi_error_invalid_first：3 条记录均不合格，共 7 个错误，完整报告见下方。
10. malformed_json：尾随逗号导致 JSON_SYNTAX，没有可定位的记录序号。
11. invalid_id：含空格和大写字符的 ID 报 ID_FORMAT。
12. invalid_minutes：-1、481、1.5、9007199254740992 所在的四条均报 MINUTES_RANGE。
13. missing_all_fields：按字段顺序报告四个 REQUIRED。
14. non_object_records：null、数组、数字三条各报 RECORD_OBJECT。
15. id_length_16：合法，有效记录为 1。
16. id_length_17：第 1 条 id 报 ID_FORMAT。
17. id_trailing_newline：第 1 条 id 报 ID_FORMAT，不静默去掉换行。

除三组有效输入（valid、empty、id_length_16）外，整体 valid 均为 false；除 duplicate_id 外，其他不合格组的有效记录数均为 0。除了 malformed_json，其余组的 stage 都是 contract。

多错误样本的第 1 条虽然标题等字段不合格，但其 ID 格式正确，因此第 2 条仍被判为重复。额外字段在输入中先写 zeta、后写 alpha，报告则按既定规则先 alpha、后 zeta：

{
  "stage": "contract",
  "valid": false,
  "recordCount": 3,
  "validRecordCount": 0,
  "errors": [
    {
      "record": 1,
      "path": [
        0,
        "title"
      ],
      "code": "TITLE_TEXT"
    },
    {
      "record": 1,
      "path": [
        0,
        "status"
      ],
      "code": "STATUS_VALUE"
    },
    {
      "record": 1,
      "path": [
        0,
        "minutes"
      ],
      "code": "MINUTES_RANGE"
    },
    {
      "record": 1,
      "path": [
        0,
        "alpha"
      ],
      "code": "EXTRA_FIELD"
    },
    {
      "record": 1,
      "path": [
        0,
        "zeta"
      ],
      "code": "EXTRA_FIELD"
    },
    {
      "record": 2,
      "path": [
        1,
        "id"
      ],
      "code": "DUPLICATE_ID",
      "firstRecord": 1
    },
    {
      "record": 3,
      "path": [
        2
      ],
      "code": "RECORD_OBJECT"
    }
  ]
}

错误码分两类：JSON_SYNTAX 表示文本无法解析；其余说明本例契约不满足。TOP_LEVEL_ARRAY 与 RECORD_OBJECT 检查容器形状，REQUIRED 检查缺字段，ID_FORMAT、TITLE_TEXT、STATUS_VALUE、MINUTES_RANGE 对应四个字段规则，DUPLICATE_ID 指向首次 ID，EXTRA_FIELD 指出不允许的字段名。界面可以另把错误码映射为中文，但不要丢掉位置。

四、这次实际验证到了哪里

2026 年 9 月 27 日北京时间 09:31，在 macOS 的 Node.js v22.22.0 运行最终脚本：17 组完整报告均与事先冻结的期望一致，独立启动脚本打印的 17 行结果也逐行吻合。16 组可解析输入的对象序列化前后哈希一致，对深度冻结的相同输入再次校验也通过；语法错误那组没有解析对象可比较。全部输入文本的 UTF-8 字节哈希和输入文件哈希前后未变。这些结果支持本例报告与不改写输入的结论。

本次没有验收浏览器上传、生产接口或数据库导入，也不证明所有业务规则已覆盖。规则只检查解析后的数值，不检查数字在源文本中的写法；不检测同一 JSON 对象内重复的键，不处理大文件资源上限、编码错误、权限或并发。若业务需要这些能力，应另写独立规则和期望后验收。局部校验通过不能替代最终业务验收。

你可以先把一个错误样本改成符合规则的数据，再检查错误是否消失；接着故意加回一个问题，确认位置和错误码再次出现。这样得到的是可复核的校验练习，而不是一句无法定位的“导入失败”。