企业官网建设流程全解析

为数据质量装上门禁：hucre Schema校验9种规则实战指南

【免费下载链接】hucreZero-dependency spreadsheet engine. Read & write XLSX, CSV, ODS. Pure TypeScript, works everywhere.项目地址: https://gitcode.com/gh_mirrors/hu/hucre

hucre 是一个零依赖的纯 TypeScript 电子表格引擎，支持读取和写入 XLSX、CSV、ODS 三种格式。除了读写，它还内置了 Schema 校验能力——validateWithSchema函数可以让你的数据在进入系统之前先过一道"门禁"：必填检查、类型转换、正则匹配、枚举白名单……一套 Schema 定义搞定。本文带你用 9 种规则给数据质量装上完整的门禁，从新手示例到生产级配置一次讲清。

为什么需要给数据装"门禁"

想象一下常见的场景：业务方发来一份 Excel 报表，价格列里混进了 "9.99元"，状态列里写着 "启用" / "active" / 1 各种写法，必填的姓名偶尔留空……如果这些数据直接入库，后面每一个环节都要为脏数据擦屁股。

hucre 的 Schema 校验就是那道门禁：数据先声明"应该长什么样"，引擎逐行逐列检查，不合格的直接报出行号、列名、原始值和错误原因。

快速上手：一行命令装上门禁

hucre 的 Schema 校验函数在包主入口直接导出（见 src/index.ts）：

import { readFile, validateWithSchema } from "hucre" const workbook = await readFile("products.xlsx") const schema = { name: { column: "Name", type: "string", required: true, min: 1 }, price: { column: "Price", type: "number", required: true, min: 0 }, sku: { column: "SKU", type: "string", pattern: /^[A-Z]{2,4}-\d+$/ }, active: { column: "Active", type: "boolean", default: true }, } const { data, errors } = validateWithSchema(workbook.sheets[0].rows, schema)

返回值是两个数组：data是校验通过并转换好的对象数组，errors是每条问题的详细报告。核心实现位于 src/_schema.ts，类型定义见 src/_types.ts。

9 种 Schema 校验规则完整清单

hucre 的每个字段（SchemaField）支持以下 9 种规则，按需组合即可：

💡 引擎内部按固定流水线依次执行：必填 → 默认值 → 类型转换 → 正则 → 边界 → 枚举 → 自定义 → 变换（见 src/_schema.ts），某一步失败该字段即置为null并记录错误，不影响其他字段继续检查。

逐条规则实战要点

1️⃣ 列定位：表头名 or 列序号

column按表头匹配，忽略大小写和首尾空格（" Name "也能匹配"Name"），表头行由选项headerRow指定，默认第一行。如果表头不固定或干脆没有表头，就用columnIndex（0 起始）按位置取列，并将headerRow设为-1。

2️⃣ 必填检查：小心"0 和 false 也是有效值"

required: true时，空值（null、空字符串、纯空格）会报错；但0、false被视为合法值不会误报——这是很多自研校验容易踩的坑，hucre 已经帮你处理好了（见 src/_schema.ts 的空值判定）。

3️⃣ 类型转换：五种类型都有"宽容模式"

类型转换是隐藏的重头戏，每种类型都内置了实用的宽容逻辑：

• number："1,234.56"自动去掉千分位逗号变成1234.56；true/false转成1/0
• integer：42.0可接受，3.14会被拒绝
• boolean："yes"、"no"、"1"、"0"、"true"（大小写不敏感）都能正确转换
• date：Excel 序列号自动转Date对象，ISO 字符串"2024-01-15"直接解析
• string：数字、布尔、日期都能安全转字符串，并顺手 trim

这些行为都有对应测试覆盖，见 test/schema.test.ts。

4️⃣ 正则匹配：只作用于字符串

pattern只对类型为string（或转换后是字符串）的字段生效，适合校验邮箱、SKU 编码、手机号格式等：

email: { column: "Email", type: "string", pattern: /^[^@]+@[^@]+\.[^@]+$/ }

5️⃣ 边界值：数字管范围，字符串管长度

min/max会智能识别字段类型：对数字比较大小（min: 0拦截负价格），对字符串比较长度（min: 2, max: 10约束编码长度），一个字段配置覆盖两种场景。

6️⃣ 枚举白名单：状态字段的救星

status: { column: "Status", type: "string", enum: ["active", "inactive", "archived"] }

超出白名单会报错，且错误信息会列出全部允许值（'Status' must be one of: active, inactive, archived），排查起来非常直观。

7️⃣ 自定义函数：业务逻辑想怎么写就怎么写

validate返回true通过；返回false用通用错误；返回字符串则作为自定义错误文案，可以直接告诉用户"SKU 必须以 'SKU-' 开头"。跨字段、查库等复杂逻辑都能塞进来。

8️⃣ 数据变换：校验通过后顺手清洗

transform在所有校验通过后执行，适合做统一大写、去空格、9.99变分单位999这类标准化处理——注意它不影响校验，只影响最终输出。

9️⃣ 默认值：空单元格的兜底方案

active: { column: "Active", type: "boolean", default: true }

空值（含整列缺失）自动填充默认值，避免下游到处写?? "active"。

生产级配置：3 个选项让它稳起来

validateWithSchema的第三个参数提供 3 个选项（完整定义见 src/_schema.ts）：

💡 批量导入场景建议"collect"，一次把所有问题反馈给业务方；实时写入管道建议"throw"，快速失败。

读懂校验报告：每条错误自带"案发现场"

每条错误都是一个SchemaValidationIssue记录，包含 5 个字段（见 src/_types.ts）：

• row：1 起始的行号，直接定位到表格那一行
• column：列名或列序号
• message：人类可读的错误描述
• value：出问题的原始值，方便回查
• field：Schema 中的字段名，方便程序化处理

不想写代码？CLI 一条命令完成校验

hucre 自带命令行validate子命令（实现见 src/cli/commands.ts），用 JSON 文件描述 Schema，即可直接校验文件：

hucre validate products.xlsx --schema products.schema.json

全部通过输出Valid! N row(s) passed validation.；有问题则逐条列出前 20 条错误并以非零码退出，非常适合塞进 CI 流水线当数据门禁。

实战组合示例：员工信息导入

把 9 种规则组合起来，就是一份生产级导入 Schema（摘自 test/schema.test.ts 的真实用例）：

const schema = { id: { column: "ID", type: "integer", required: true }, name: { column: "Full Name", type: "string", required: true, min: 2 }, email: { column: "Email", type: "string", required: true, pattern: /^[^@]+@[^@]+\.[^@]+$/ }, salary: { column: "Salary", type: "number", min: 0, max: 1_000_000 }, department: { column: "Dept", type: "string", enum: ["Engineering", "Sales", "HR", "Marketing"], transform: (v) => String(v).trim() }, startDate: { column: "Start Date",type: "date" }, isManager: { column: "Manager", type: "boolean", default: false }, }

这份 Schema 一行数据能同时接住："85,000" 带逗号薪资、"yes" 写成经理标记、Excel 序列号日期、部门名带空格、Manager 列整列缺失……校验完得到的data就是干净的、类型正确的对象数组，可直接入库或导出 JSON。

深入阅读清单 📚

hucre 零依赖、纯 TypeScript、支持 Tree-shaking，Schema 校验只是它给电子表格数据加上的第一道防线。下一站，可以去看看它的流式读取能力，把"门禁"直接装进大文件管道里。

【免费下载链接】hucreZero-dependency spreadsheet engine. Read & write XLSX, CSV, ODS. Pure TypeScript, works everywhere.项目地址: https://gitcode.com/gh_mirrors/hu/hucre