NOTE数据校验：脏数据来源、批量导入与多端同步实践

上个月帮一个做笔记类产品的朋友看线上问题，现象挺怪：列表页里那几条笔记显示得好好的，点进去直接白屏，控制台在渲染阶段取某个字段时抛了异常。翻后端日志才发现，这条记录的正文存的是个对象，不是字符串，来源是一次批量导入。这件事让我再一次确认了一个判断——NOTE数据校验这件事，越是看起来"没什么可校验"的数据模型，越容易在真正的边界上翻车。笔记这种结构，标题、正文、标签、时间戳，一眼扫过去干净得像张白纸，很多团队在早期为了赶进度，校验基本靠前端一个required加上数据库的非空约束，剩下的交给"应该不会出问题"。等真出了问题，定位成本比当初写校验高出十几倍。

这篇内容想聊的就是 NOTE 数据校验这件事本身：它到底该校验什么、在哪些位置校验、批量导入和多端同步这类脏数据高发场景怎么处理、校验失败之后错误该怎么给出去、以及规则越加越多之后怎么让它不至于变成一团乱麻。适合正在做笔记类功能的后端、前端，也适合负责数据管道的同学参考。我不打算讲什么高大上的校验框架，主要是我自己在几个项目里踩出来的经验和一些可以直接抄的做法。

1. 先搞清楚NOTE到底"脏"在哪：一次渲染异常带来的反思

1.1 数据结构简单，不等于校验简单

很多人对 NOTE 的第一印象是"这就是个富文本加几个元字段"，于是下意识地认为校验成本很低。但我实际统计过一个跑了两年多的笔记项目，线上真正引发用户可见故障的脏数据，八成以上都来自那几个被认定为"不可能出问题"的字段。

问题在于 NOTE 这个结构有一个特殊性：它的字段数量少，但每个字段的形态都很活。标题看起来就是个字符串，可它可能是空串、可能是纯空白、可能是两百个字符、可能带一堆控制字符；正文看起来是字符串，可它实际上是序列化后的富文本结构，里面嵌套了图片引用、附件 ID、表格；标签看起来是个数组，可数组里可能是重复项、可能是空字符串、可能是超长字符串。字段少不等于约束少，只是约束被藏起来了。

我现在的习惯是，拿到一个 NOTE 模型，第一件事不是写代码，而是把它摊开在纸上，对每个字段问三个问题：它的合法形态有几种？它的非法形态最容易从哪个入口进来？它非法之后会在哪个环节炸？这三个问题答完，校验清单基本就出来了。

1.2 五类高频脏数据来源

把几个项目的问题汇总一下，NOTE 脏数据的来源高度集中，基本逃不出下面这几类：

这里最需要警惕的是批量导入和历史迁移。实时写入的脏数据一次只污染一条，导入类操作一次能污染一整批，而且往往是用户发现得比监控早。我在一个项目里就吃过这个亏：导入脚本对正文做了长度截断，但截断位置正好落在富文本的某个节点标签中间，结果几百条笔记打开就崩，修复脚本写了整整两天。从那以后，导入链路的校验我一律按最严的那一档来做。

提示：如果你手上正有一个 NOTE 相关的批量导入需求，先别急着写解析逻辑，把"这批数据里最坏的一条长什么样"列出来，校验规则照着这个最坏情况去设计。

1.3 校验的目标不是"拒绝"，而是"可控"

这一点我觉得挺重要，值得单独拎出来说。新手做校验容易走两个极端：要么什么都不校验，要么校验严到用户正常操作都被拦。前者养脏数据，后者伤体验。

我的理解是，NOTE 数据校验的真正目标是让系统在任何输入下都处于可控状态。什么叫可控？就是最坏情况下也能给出明确的结果——要么正常落库，要么带着清晰的错误码被拒绝，要么被降级处理后存下来。最怕的是第三种情况的反面：数据不明不白地进了库，然后在某个不确定的时刻、以某种不确定的方式炸掉。不可控才是真问题，脏数据只是不可控的一种表现形式。

2. 把NOTE拆成可校验的最小单元：字段语义与约束边界

2.1 字段分级：硬约束、软约束与展示层约束

我习惯把 NOTE 的字段约束分成三层，这个分层直接决定了校验逻辑放在哪里、失败了怎么处理。

硬约束是那些"违反就一定不能存"的规则，比如标题和正文不能同时为空、正文字节数不能超过存储上限、标签项不能是空字符串。这类规则通常放在服务层的写入入口，违反直接拒绝。

软约束是"违反可以存但要处理"的规则，比如标题超过 80 字、标签数量超过 20 个。这类我一般不在写入时拒绝，而是做截断或标记，同时在返回体里告诉调用方"我动过你的数据了"。

展示层约束是纯粹的 UI 规则，比如列表页最多显示两行标题。这类规则绝对不能写进服务端校验，否则以后改个前端样式还得动后端。

分层的价值在于，它逼着你在写代码前想清楚：这条规则违反了，业务上到底能不能接受？能接受的就别做成硬拒绝，不能接受的就别心存侥幸。

2.2 约束边界怎么定：以标题长度和正文体积为例

长度类的边界最容易拍脑袋。我见过直接写max_length=255的，问他为什么是 255，答曰"数据库字段就这么长"。这其实把存储实现当成了业务约束，顺序反了。

正确的做法是先确定业务上合理的值，再让存储去适配。标题我一般定在 100 到 120 个字符之间，理由是移动端列表页三行展示大概就这个量级，再长也没有展示价值；正文我用字节数而不是字符数来限制，因为存储和传输的成本跟字节强相关，中文一个字三字节，限制 200 万字节大约对应六七十万字，对绝大多数笔记场景够用了。

这里有个细节值得说：字符数和字节数一定要分清楚。前端length拿到的是字符数（更准确地说是 UTF-16 码元数），后端限制的是字节数，两边如果不统一，就会出现前端放行、后端拒绝的尴尬。我的做法是前后端都用字节数做限制，前端用new TextEncoder().encode(str).length算一遍，提示语也直接说"正文不能超过 2MB"，比说"不能超过 60 万字"更准确。

2.3 默认值与空值必须区分开

这个坑我踩过不止一次。NOTE 里的title字段，用户没填的时候到底是null、空字符串、还是根本不存在这个 key？如果代码里三种情况混着处理，早晚出问题。

我的约定是：写入时统一归一化，读取时统一按归一化后的形态处理。具体就是，标题不填存空字符串，不存null；可选字段（比如folder_id）没值就不出现在 payload 里，或者显式给null，二选一但全局统一；布尔字段永远有明确值，不给null。

归一化这一步放在校验函数里一起做，比分散在各处判断要省心得多。下面这个 Python 片段是我一个项目里简化过的版本，核心是校验和归一化合并成一次遍历：

NOTE_LIMITS = { "title": {"max_bytes": 360, "default": ""}, "content": {"max_bytes": 2 * 1024 * 1024, "default": ""}, "tags": {"max_items": 32, "item_max_bytes": 72}, } def normalize_and_validate(payload: dict, mode: str = "create"): errors, data = [], {} title = payload.get("title") if title is None: title = NOTE_LIMITS["title"]["default"] if not isinstance(title, str): errors.append(("E_NOTE_TITLE_TYPE", "标题必须是字符串")) else: title = title.strip() if len(title.encode("utf-8")) > NOTE_LIMITS["title"]["max_bytes"]: errors.append(("E_NOTE_TITLE_TOO_LONG", "标题超出长度限制")) data["title"] = title content = payload.get("content") if content is None: content = NOTE_LIMITS["content"]["default"] if not isinstance(content, str): errors.append(("E_NOTE_CONTENT_TYPE", "正文必须是字符串")) else: if len(content.encode("utf-8")) > NOTE_LIMITS["content"]["max_bytes"]: errors.append(("E_NOTE_CONTENT_TOO_LARGE", "正文体积超出限制")) data["content"] = content if mode == "create" and not data.get("title") and not data.get("content"): errors.append(("E_NOTE_EMPTY", "标题和正文不能同时为空")) return data, errors

这个函数的两个关键点：一是先归一化再判断，避免"空格标题"这种边界漏过去；二是mode参数区分创建和更新，因为更新场景下"标题正文都为空"可能是合法的中间态（用户正在编辑），而创建场景基本上不允许。

2.4 富文本正文字段要额外加一层结构校验

如果正文不是纯文本而是富文本，光校验类型和长度是不够的。我的做法是在长度校验之后加一步轻量的结构探测——不解析整棵树，只检查几个特征：能否被 JSON 解析、顶层是不是预期的结构、节点深度有没有超过上限、有没有超长的一级节点。

这层探测主要是防两类问题：一是导入的数据结构完全不对（比如把纯文本塞进了富文本字段），二是恶意构造成无限嵌套的节点导致渲染卡死。深度限制我一般设在 20 层左右，正常笔记用不到这么深，一旦触发大概率是数据有问题而不是用户真的写了这么深的嵌套。

3. 三道闸门的分工：前端即时校验、网关校验与落库前校验

3.1 只做前端校验等于没做

这句听起来像老生常谈，但实际项目里"前端校验了所以后端不用管"的想法依然很常见，尤其是在内部工具和数据导入这类场景。

前端校验的定位应该是体验优化，不是安全边界。它的价值是让用户在输入的时候就知道哪里不对，少走一次网络往返；它的局限是，任何能直接调接口的人都能绕过它。所以前端校验要做得及时、友好，但绝不能指望它兜底。

第二道是核心，第三道是兜底。第三道的存在意义是：万一前面有逻辑漏了，存储层不至于被写崩。我在项目里会在存储适配层加一道硬上限检查，超限就拒绝并打一条告警日志——这条日志如果频繁出现，说明前面的校验有漏洞，值得回头查。

3.2 服务层校验怎么组织才不至于写成一锅粥

NOTE 字段不多，校验逻辑写在一个函数里也就几十行，问题不大。但我见过字段涨到二十几个之后依然全塞在一个函数里的代码，改一条规则要在两百行里找位置，非常痛苦。

我的组织方式是按"字段校验器 + 组合器"拆。每个字段一个独立的小函数，只负责自己的归一化和校验，返回处理后的值或者错误；外层组合器负责决定哪些字段在什么场景下必须校验。这种做法在字段少的时候显得有点啰嗦，但一旦要支持"草稿保存只校验标题""导入校验更严"这类差异，优势就出来了。

另一个经验是：把规则做成数据，而不是散在代码里。长度上限、标签数量上限这类数字，全部集中到一个配置字典或者配置表里，代码只引用不硬编码。好处是产品说"标题上限从 100 改成 150"的时候，你改一个数字就行，不用全局搜索。

3.3 并发写入下的校验位置很关键

这个点比较容易被忽略。NOTE 的更新接口通常有两种实现：一种是读-改-写，先查出整条记录，改几个字段，整体写回；另一种是只更新传入的字段。

前一种方式如果校验放在"写回"之前，中间存在一个时间窗口——A 请求读取的时候记录是合法的，等它写回的时候 B 请求已经把某个字段改成了别的值，A 的写回可能把 B 的修改覆盖掉，也可能基于旧值做出错误的校验判断。

我的处理是：校验尽量基于本次请求传入的字段做局部判断，不要依赖"读出来的整条记录一定还是那个样子"。对于强依赖整条记录一致性的规则（比如"标题不能和另一条笔记重复"），要么加版本号做乐观锁，要么把这条规则放到单独的事务里做。这不是 NOTE 特有的问题，但 NOTE 因为更新频繁、字段少，反而更容易在早期被忽略。

4. 批量导入与跨端同步场景，校验一致性怎么守住

4.1 批量导入不能"全有或全无"

导入是 NOTE 数据校验里最容易失控的场景。一条条校验太慢，整批校验又不好定位问题。我现在的标准做法是逐条校验、部分成功。

具体流程是：先把文件整体读进来做一次格式检查（编码、列数、必填列是否存在），这一步不通过就整批拒绝，因为格式错了后面全是无用功；格式没问题之后逐条走和实时写入完全相同的校验函数，通过的入待写队列，不通过的收集到错误清单里，带上行号和具体原因；最后批量写入，返回"成功 N 条、失败 M 条"以及失败明细。

这里必须强调一点：导入链路一定要复用同一套校验函数，不要另写一套。我见过为了性能给导入单独写一份简化校验的实现，结果两套规则渐渐不一致，导入能进来的数据手工提交反而报错，排查起来极其难受。如果确实有性能顾虑，正确的做法是优化校验函数本身，或者做批量化处理，而不是复制一份规则出来。

4.2 多端字段版本不一致的兼容校验

老版本客户端不认识新字段，会把它们原样带回来或者干脆丢掉，这是同步场景的经典问题。我的处理原则是未知字段透传，已知字段严格校验。

也就是说，服务端收到一个 payload，认识的字段按规则校验，不认识的字段原样存到扩展区，不做校验也不丢弃。这样老客户端提交时不会把新字段弄丢，新客户端读回来还能拿到完整数据。

有一个坑要提前防：老客户端可能用旧格式提交一个语义已经变化的字段。比如以前tags是逗号分隔的字符串，后来改成了数组。这种情况光靠"类型不符就拒绝"会导致老客户端彻底不能用，需要做一个兼容转换层——识别到字符串形态就按逗号拆成数组，同时记一条兼容日志。等日志量降到足够低，再把这个兼容层下掉。

4.3 校验规则本身也需要版本

这个思路是从数据迁移那次事故之后建立起来的。规则会变，规则变了之后历史数据就变成了"按老规则合法、按新规则非法"的状态。

我的做法是给校验规则集编个版本号，写入时把规则版本一起记到记录上（可以是扩展字段里的一小段元信息）。这样以后要批量修复历史数据的时候，可以按规则版本筛出"需要重新校验"的那一批，而不是全表扫。代价很小，收益在数据治理阶段非常大。

5. 校验失败之后：错误码、提示语与可观测性

5.1 错误码要有稳定的结构

校验失败返回什么，很多项目是随手写个字符串就返回了。等到前端要按错误类型做不同处理的时候，发现只能靠字符串匹配，改一个字就全崩。

我的约定是错误码带前缀和具体原因，形如E_NOTE_<FIELD>_<REASON>。这样做的好处是前端可以按前缀做粗粒度处理（比如所有E_NOTE_TITLE_开头的错误都聚焦到标题输入框），也可以按完整码做精细处理。下面这张表是我一个项目里实际在用的错误码，可以直接拿去改：

统一的错误结构至少包含三段：错误码、面向用户的提示语、面向排查的上下文字段。别把这三样揉成一个字符串，排查的时候你会感谢自己拆开了。

5.2 提示语要能让用户动手改

"数据校验失败"这六个字大约是最没用的提示。好的提示语应该告诉用户三件事：哪里错了、错成什么样、怎么改。

以标题超长为例，我一般写成"标题超出 120 字，当前 168 字，请精简后再保存"。这句话里包含了位置、当前状态、上限、动作，用户看完可以直接动手。对于批量导入这种场景，提示语还要带行号，因为用户面对的是一整个文件，没有行号根本定位不到。

面向开发者的上下文就完全是另一套了，字段名、实际值摘要、规则版本、请求 ID，该有的都得有。两套信息分开存放，不要混在同一个 message 里。

5.3 校验失败本身也是数据

这一点是我最近一年才真正重视起来的。校验失败不只是一个需要返回的错误，它是一份非常有价值的观测数据。

我在项目里会对校验失败做聚合统计：按错误码统计次数、按来源渠道统计分布（实时写入、导入、同步各占多少）、按时间看趋势。这几个数字非常能说明问题。如果E_NOTE_CONTENT_TOO_LARGE突然暴涨，可能是前端编辑器出了问题导致内容重复粘贴；如果导入渠道的错误率特别高，说明导入模板或者文档需要更新；如果某个老版本客户端的兼容错误持续存在，说明该推动升级了。

采集的时候要注意脱敏，只记错误码、字段名、长度这类结构性信息，不要把用户的正文内容打进日志。

6. 性能与回归：让校验规则能长期活下去

6.1 大字段校验的开销要算清楚

NOTE 的正文可能很大，对正文做全量校验是存在性能成本的。但我实测下来，纯字符串的长度计算本身非常快，主要开销集中在两处：一是 UTF-8 编码转换，二是富文本的结构探测。

编码转换这块，我的经验是尽量只做一次。很多实现里会先算一次长度做限制，再编码一次存库，等于白算一遍。把编码后的结果直接传给存储层，能省掉一次转换。

结构探测是真正的大头。如果正文是一棵很大的富文本树，完整解析一遍的成本可能比存库还高。所以我前面说的是"轻量探测"，不做完整解析，只做深度的浅层遍历，遇到超深就提前返回。这个策略在实践中效果不错，正常内容几乎感觉不到开销，异常内容能在很早期被拦住。

6.2 校验规则一定要有回归用例

规则是会改的，改规则最大的风险不是新规则写错，而是把老规则弄坏了。NOTE 的字段虽然少，但组合起来的场景不少：创建、更新、草稿、导入、同步、迁移，每种场景对同一批规则的要求都可能不一样。

我的做法是维护一个用例集，每条用例写成"输入 payload + 场景 + 期望结果"，不追求覆盖率多高，但要求每一条线上出过的脏数据问题都对应至少一条用例。这套用例跑起来很快，改规则的时候跑一遍，能挡掉大部分低级错误。

用例的形态我倾向于用最朴素的数据文件，比如一份 JSON 或者一段表格，而不是写死在测试代码里。这样产品、测试也能看懂，发现了新的边界情况可以直接往里加。

6.3 规则膨胀了怎么治理

项目跑久了，校验规则一定会膨胀。我见过一个 NOTE 的校验函数里堆了四十多条规则，其中有些是历史遗留、有些是重复的、有些针对的场景早就不存在了。

治理这件事我建议定期做，比如每个季度过一遍。判断标准很简单：这条规则如果去掉，会有什么后果？答不上来的就删掉或者降级成日志告警，观察一段时间确认没问题再彻底移除。

另一个治理手段是把规则按场景分组，而不是平铺。实时写入一组、导入一组、迁移一组，每组只包含该场景真正需要的规则。这样每组的规则数量都能控制在可维护的范围内，也能一眼看出某条规则到底服务于哪个场景。

最后再分享一个我在实际项目里的习惯：每次新增一条校验规则，我会在代码注释里写清楚"这条规则是为了防哪个具体问题"，并附上一个简短的场景描述。半年后回头看，这条注释比规则本身更有价值——它让你判断出这条规则还有没有必要存在。