言验：数据验证

言验（yanxu-validate）1.0.0 用中文链式 API 描述不可信输入边界。它可以在一次解析中收集路径化问题，并提供外部验证执行器、言据 Schema、ORM 模型和 HTTP 请求适配器；验证本身不替代授权、事务或传输层限制。

版本与安装

yanbao add 言验 \
  --git https://github.com/yanxulang/yanxu-validate.git \
  --rev v1.0.0 \
  --version '^1.0'

[依赖]
言验 = { git = "https://github.com/yanxulang/yanxu-validate.git", 修订 = "v1.0.0", 版 = "^1.0" }

应提交生成的 言序.lock，固定公开标签解析出的提交和内容校验。

核心能力：对象规则与安全解析

引「包:言验」为 言验；

定 用户规则 为 言验.对象型（{
    「姓名」：言验.文本（）.至少（2）.至多（50），
    「年龄」：言验.整数（）.至少（0），
    「邮箱」：言验.文本（）.是邮件（）.可选（），
    「角色」：言验.枚举（【「读者」，「作者」】）.默认（「读者」）
}）.拒绝未知（）；

定 结果 为 用户规则.安全解析（{
    「姓名」：「子衿」，
    「年龄」：18
}）；

若 结果.成功 则
    言 结果.值；
否则
    逐 问题 于 结果.问题列 则
        言 问题【「路径」】；
        言 问题【「代码」】；
        言 问题【「消息」】；
    终
终

对象默认移除未知键，可显式选择 保留未知或拒绝未知。每项问题包含稳定代码、完整对象/列表路径、消息、期望和实际类型；错误记录实际类型而不复制原始敏感值。

规则与转换

多个预处理和转换按登记顺序执行。预处理在空值和基础类型检查前运行，转换在基础规则与同步约束成功后运行。列和典默认值会在每次使用时深复制，不会因调用方修改一次结果而污染后续解析。

定 端口规则 为 言验.数字自文（）
    .至少（1）
    .至多（65535）；

定 端口结果 为 端口规则.安全解析（「8080」）；

需要失败即中断时使用 规则.解析(值)或言验.断验(规则, 值)。抛出错误使用 YANYAN_前缀；捕获后用 错误详情取稳定代码，不要匹配完整消息。

外部验证执行器

数据库唯一性、远程策略或批量权限检查可以登记为外部验证任务：

定 用户名 为 言验.文本（）
    .异步自定义（未被占用，「TAKEN」，「用户名已占用」）；

定 结果 为 用户名.异步安全解析（
    「子衿」，
    言验.顺序验证执行器（）
）；

同步入口遇到任何嵌套的外部验证器时返回 ASYNC_REQUIRED，不会静默跳过检查。1.0 内建执行器按顺序确定性执行；并行、取消和超时由调用方注入的执行器负责。执行器必须为每个任务返回同位置的问题典或空，否则失败关闭。

言据、ORM 与 HTTP 适配

言据 Schema

定 模式 为 {
    「类型」：「据」，
    「必需」：【「姓名」】，
    「允许额外」：假，
    「属性」：{
        「姓名」：{「类型」：「文」，「最短」：2}
    }
}；

定 结果 为 言验.验证言据（{「姓名」：「子衿」}，模式）；

言据模式(Schema典)把言据 1.2 Schema 编译为普通规则。它只处理已经解析的值和 Schema 典，不读取 .yj文件，也不解析言据源文本。

ORM 模型

模型规则(字段规则典)提供 验证创建、验证更新、验证字段、登记场景和验证场景，并有接受执行器的对应入口。预检查不能消除竞争条件：唯一性、外键和引用完整性最终仍须由事务与数据库约束保证。

HTTP 请求

定 请求规则 为 言验.HTTP请求规则（）
    .查询参数（查询规则）
    .正文（言验.言据模式（正文模式））；

定 结果 为 请求规则.验证请求（请求典）；

适配器可组合路径参数、查询参数、首部、Cookie 和正文规则。它验证的是已解析请求典，不读取网络流，不协商内容类型，也不执行身份认证；传输层必须先限制原始首部和正文大小。

权限与安全边界

言验无第三方依赖，清单拒绝文件、网络、监听、环境、进程和原生扩展权限。外部验证器需要网络或数据库时，其能力、凭据、超时和取消均由顶层应用与注入执行器承担。

默认资源预算包括：

• 文字、列或典最多 4096 个字符或项目；
• 单次最多返回 256 个问题，Schema 最多 256 项；
• 联合或交叉最多 64 个分支；
• 每条规则最多 128 个同步约束和 128 个外部约束；
• Schema 与深复制值最多嵌套 8 层。

限制项数只能把单条规则收紧到库硬上限以内。正则模式、自定义验证器与执行器都应来自受信任应用代码；库会结构化其异常，但不会隔离其 CPU、内存或宿主权限。

已知限制

• 异步安全解析会等待执行器返回完整结果列；核心库不提供内建并行调度、取消或超时。
• HTTP 适配器不是正文读取器、认证器或限流器，Schema 适配器不是文件解析器。
• 验证成功只说明值符合规则；授权、唯一性、外键、事务一致性和业务状态仍需在各自边界检查。
• 未知言据 Schema 注解会被忽略以容纳上层元数据；已知字段的类型错误会返回 YANYAN_YANJU_SCHEMA。
• 问题消息可本地化和改进，机器分支只能依赖代码与结构字段。

项目链接

• GitHub 仓库
• 言验 1.0.0 Release