本文详解如何通过 JSON Schema 的 pattern 关键字严格校验字符串字段，确保 "name": " " 等仅含空白字符的非法输入被准确拒绝，而非仅依赖 minLength: 1 导致校验失效。
本文详解如何通过 json schema 的 `pattern` 关键字严格校验字符串字段，确保 `"name": " "` 等仅含空白字符的非法输入被准确拒绝，而非仅依赖 `minlength: 1` 导致校验失效。
在实际 API 开发与数据契约治理中，minLength: 1 常被误认为能有效阻止空字符串或纯空格字符串——但事实并非如此。JSON Schema 规范明确指出：minLength 仅统计 Unicode 码点数量，而 " "（三个空格）长度为 3，完全满足 minLength: 1，因此校验通过。这导致大量“逻辑性空值”悄然入库，引发下游业务逻辑异常（如用户名显示为空白、搜索匹配失败、权限校验绕过等）。
要真正实现「语义级非空」——即字段必须包含至少一个可见、非空白字符——必须结合正则表达式约束。推荐使用 pattern 关键字配合 S+ 正则模式：
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"pattern": "^\S+$"
}
},
"required": ["name"]
}
✅ 关键说明：
- ^\S+$ 含义：^（行首）、\S+（一个或多个非空白字符）、$（行尾），强制整个字符串不能包含任何空格、制表符、换行符等空白字符；
- 双反斜杠 \ 是 JSON 字符串转义要求（实际正则为 S+）；
- minLength: 1 保留作为基础长度兜底，提升可读性与兼容性；
- 若需允许中间空格但禁止首尾空白（如 "John Doe" 合法，" John " 非法），可改用 "pattern": "^\S.*\S$|^\S$"。
⚠️ 注意事项：
- pattern 校验在所有主流验证器（如 jsonschema Python 库、ajv TypeScript 库、gojsonschema）中均原生支持，无需额外插件；
- 避免使用 ^[^\s]+$ ——虽语义等价，但 \S 更简洁且跨引擎兼容性更佳；
- 不建议依赖 trim 后再校验：Schema 层应做防御性契约约束，而非将清洗逻辑下沉至业务代码，否则易产生校验与存储不一致；
- 在 OpenAPI 3.1+ 中，可结合 nullable: false 与 pattern 构建更严格的字段契约。
? 进阶建议：统一定义可复用的字符串约束
为避免重复编写正则，可在 Schema 中利用 $defs 提炼通用规则：
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"nonEmptyTrimmedString": {
"type": "string",
"minLength": 1,
"pattern": "^\S+$",
"errorMessage": "字段必须为非空且不含首尾及内部空白字符"
}
},
"properties": {
"name": { "$ref": "#/$defs/nonEmptyTrimmedString" },
"username": { "$ref": "#/$defs/nonEmptyTrimmedString" }
}
}
通过此方案，你不仅能精准拦截 " "、" " 等无效输入，还能在错误响应中返回清晰的 errorMessage（需验证器支持），大幅提升调试效率与接口健壮性。真正的数据契约，始于对「空白」的零容忍。
