feat: add stop_if / stop_unless tags for cross-field rules with a sentinel target

[molon]

跨字段比较的右手边取「哨兵值」时，ltefield 这类 tag 会拒掉完全合法的配置。本 PR 加一对能中止校验的条件 tag，并顺带修正了既有 tag 的一个命名错误。

问题

最典型的是「0 表示不限制」：

MaxIdleConns int `validate:"ltefield=MaxOpenConns"`
MaxOpenConns int // 0 = unlimited

配 (20, 0) —— 不限制连接数、保留 20 条空闲 —— 会因为 20 <= 0 为 false 而校验失败，服务起不来。

根因是位置错了：「0 = 不限制」这个语义是消费方代码里 if conf.X > 0 那几行定义的，tag 层看不见它。 让一个不知道语义的层去执行依赖语义的规则，必然出这种事。

内置的 skip_unless 为什么用不了

先说清楚，免得被名字骗到：validator 内置的 skip_unless 根本不跳过任何东西。

func skipUnless(fl FieldLevel) bool {
	for i := 0; i < len(params); i += 2 {
		if !requireCheckFieldValue(fl, params[i], params[i+1], false) {
			return true          // 条件不满足 → 通过，后面照跑
		}
	}
	return hasValue(fl)          // 条件满足 → 要求本字段非空
}

它 return hasValue(fl)，是个存在性检查，属于 required_* 家族（官方注释也写着 "must be present and not empty"）。实测四种组合，它后面的 gte=100 一次都没被跳过。

上游 183 个内置 tag 里，skip_* 家族只有 skip_unless 一个，没有任何一个能中止后续校验。

解法：一对只差极性的 tag

MaxIdleConns int `validate:"stop_if=MaxOpenConns 0,ltefield=MaxOpenConns"`
MaxOpenConns int // 0 = unlimited

tag	语义
stop_if=<F> <v> ...	任一对命中就停止校验本字段
stop_unless=<F> <v> ...	必须全部命中才继续

一个实测推翻的假设：nested 和 rest 的区分不存在

我最初按「跳过嵌套结构」vs「跳过后续 tag」加了两个不同名字。交叉验证后发现它们是同一个机制：

贴在	skip_nested_unless	新 tag
标量字段	✅ 跳过后续 tag	✅ 跳过后续 tag
嵌套结构	✅ 阻止进入	✅ 阻止进入

两者都靠返回 false —— validator 在首个失败的 tag 处放弃该字段，对标量表现为「后面的 tag 不跑」，对嵌套结构表现为「不往里钻」。同一个行为的两种表现。

也就是说 skip_nested_unless 早就具备「stop_unless 用在标量上」的能力，只是从没被文档化过。唯一真实的轴是极性，nested 这个词只说对了一半用法。

所以最终是 stop_if / stop_unless 这一对，skip_nested_unless 注册到同一个实现上、标为 Deprecated，既有 struct tag 零改动。

为什么是 stop 不是 skip

1. 它同时说得通两种情形 ——「在这里停止校验」。skip 容易被读成「跳过这个字段」，而实际跳过的是从这里往下的一切。
2. 彻底离开上游的 skip_* 命名空间。 RegisterValidationCtx 同名注册会静默替换内置实现并返回 nil —— 撞名的后果是所有消费方行为无声改变，且检测不到。上游 183 个 tag 里 stop_* 一个都没有。

顺带一提，restrictedTags（同名注册会 panic）只保护 dive / keys / endkeys / structonly / omitzero / omitempty / omitnil 等几个，skip_* 不在其中。

一个刻意的选择

字段名写错时不跳过（requireCheckFieldValue 的 defaultNotFoundValue 传 false）。一个 typo 静默关掉一条规则，比报错难查得多 —— 有测试钉住。

真实动机

qor5/x#625 里同一个坑有三处，三条都实测复现过：

字段	原 tag	被拒的合法配置
gormx.MaxIdleConns	ltefield=MaxOpenConns	(20, 0) 不限制连接数
gormx.ConnMaxIdleTime	ltefield=ConnMaxLifetime	(10m, 0) 连接永不回收
httpx.ReadHeaderTimeout	ltefield=ReadTimeout	(10s, 0) 只设 header 超时

httpx 那条最容易踩：它没有默认值文件，而「只设一个 header 超时」是很自然的最小加固。

那边目前的权宜之计是把配对检查挪进构造函数。本 PR 合并发版后就能改回 tag 写法 —— 回到配置校验阶段、拿回结构化的错误、三处写法统一。

测试

go test ./... 全绿。新增：

• TestStopIf —— 主场景五种组合（有上限且合规 / 相等 / 越界 / 无上限 / 全零）
• TestStopIfDoesNotLeakItsOwnError —— stop_if 自身的「失败」不得外泄
• TestStopIfMatchesAnyPair —— 多对时任一命中即停
• TestStopIfUnknownFieldDoesNotDisableTheRule —— 字段名写错不静默失效
• TestStopTagsAreNotScopedToNestedOrScalar —— 四种组合钉住「没有 nested/rest 之分」，这正是改名的依据
• TestSkipNestedUnlessIsAnAliasOfStopUnless —— 别名与新名行为逐一等价
• TestBuiltinSkipUnlessDoesNotActuallySkip —— 把上游 skip_unless「不跳过」这个行为钉下来。哪天上游改了，这条会红，届时可重新评估这对 tag 还有没有必要

[Copilot]

Pull request overview

This PR adds a new skip_if validation tag to ConfX’s Go validator wrapper to support cross-field validation rules where the comparison target can take on a sentinel value (e.g., 0 meaning “unlimited”), which would otherwise cause valid configs to be rejected.

Changes:

• Introduces the skip_if tag implementation (skipIfImpl) to short-circuit remaining validations for a field when a target field matches any (field, value) sentinel pair.
• Generalizes the existing “skip tag” registration and error filtering so both skip_nested_unless and skip_if internal “failures” are filtered out of returned validation errors.
• Adds unit tests covering the main scenarios, error filtering behavior, multi-pair matching, and unknown-field safety behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
validator.go	Adds skip_if, centralizes skip-tag registration, and filters out skip-tag errors from validator output.
validator_test.go	Adds new test cases validating skip_if behavior and non-leakage of the internal skip error.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (1)

validator_test.go:364

• This test can panic with index out of range if assert.ErrorAs fails (e.g., if upstream changes skip_unless behavior and err becomes nil, or the error type changes). Because testify assertions don't stop execution, verr[0] is unsafe without checking the assertion result and slice length.

	// B == 0 matches the condition. If skip_unless skipped, A = 1 would pass.
	err := v.Struct(S{A: 1, B: 0})
	var verr validator.ValidationErrors
	assert.ErrorAs(t, err, &verr)
	assert.Equal(t, "gte", verr[0].Tag(), "built-in skip_unless is documented as a presence check, not a skip")
}