企业官网建设流程全解析

Hugo 模板函数 or：返回第一个真值与短路求值机制详解

【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo

Hugo 内置函数or用于在多个模板参数中选取第一个“真值”（truthy）参数，若所有参数均为“假值”（falsy）则返回最后一个参数，是编写默认值回退、条件判断与内容选择逻辑的核心工具。本文以 Hugo 官方函数文档为主体，结合仓库中or的底层实现源码与测试用例，完整讲解其求值规则、短路机制与实战用法。

函数签名与基本行为

根据官方文档，or的签名与返回类型如下：

• 签名：or VALUE...（至少接收一个参数）
• 返回类型：any
• 功能：返回第一个真值参数；若所有参数均为假值，返回最后一个参数

{{ or 0 1 2 }} → 1 (int) {{ or false "a" 1 }} → a (string) {{ or 0 true "a" }} → true (bool)

关键行为是从左到右依次评估：or逐个检查参数，一旦遇到第一个真值立即返回，不再评估后续参数。文档明确描述了这一过程：

Theorfunction evaluates the arguments from left to right, and returns when the result is determined.

这个“结果确定即返回”的特性就是短路求值（short-circuit evaluation），它在参数中包含昂贵或有副作用的计算时尤为重要：

{{ or true (math.Div 1 0) }} → true (bool)

示例中math.Div 1 0会引发除零错误，但由于第一个参数true已经是真值，or直接返回true，根本不会执行除法运算。这是or区别于普通条件表达式的重要实战价值。

真值与假值的判定标准

or的判定依赖于 Hugo 对“真值/假值”的定义。以下判定规则来自仓库公共文档片段 _common/functions/truthy-falsy.md，同样适用于or、and、if等相关函数：

假值（falsy）包括：

• false
• 0
• 任何nil指针或接口值
• 长度为 0 的数组、切片、map 或字符串
• 零值time.Time

除此之外的所有值均为真值（truthy）。

因此or在“全是假值”时会返回最后一个参数，注意返回的是参数本身（保持其原始类型），而不是布尔值：

{{ or false "" 0 }} → 0 (int) {{ or 0 "" false }} → false (bool)

第一个示例中false和""都是假值，函数返回最后一个参数0（int 类型）；第二个示例中所有参数均为假值，返回最后一个false（bool 类型）。这意味着可以把or用作“取值优先级链”：把期望的首选值放前面，兜底默认值放最后。

源码实现：为什么 or 能短路？

文档描述的“从左到右、结果确定即返回”并非普通函数调用可以实现的——在 Go 的常规函数调用中，所有实参在调用前就会被求值。Hugo 在模板执行引擎中为and/or做了专门的短路分支。

首先，or与其他内置函数一样注册在文本模板的内置函数表中，见 tpl/internal/go_templates/texttemplate/funcs.go：

func builtins() FuncMap { return FuncMap{ "and": and, "call": emptyCall, ... "or": or, ... } }

值得注意的是，or的函数体本身是一个占位符，真正的求值逻辑被移到执行引擎中（参见 funcs.go）：

// or computes the Boolean OR of its arguments, returning // the first true argument it encounters, or the last argument. func or(arg0 reflect.Value, args ...reflect.Value) reflect.Value { panic("unreachable") // implemented as a special case in evalCall }

短路循环位于执行引擎的函数调用路径中，见 tpl/internal/go_templates/texttemplate/exec.go：

// Special case for builtin and/or, which short-circuit. if isBuiltin && (name == "and" || name == "or") { argType := typ.In(0) var v reflect.Value for _, arg := range args { v = s.evalArg(dot, argType, arg).Interface().(reflect.Value) if truth(v) == (name == "or") { // This value was already unwrapped // by the .Interface().(reflect.Value). return v } } ... }

从这段源码可以读出or的完整求值语义：

1. 参数在循环内逐个通过s.evalArg求值，而不是一次性全部求值；
2. 每求值一个参数就检查其真值，对or而言一旦truth(v)为真（truth(v) == (name == "or")），立即return v——这就是短路所在，也是文档示例{{ or true (math.Div 1 0) }}能安全返回true的原因；
3. 循环结束后若未命中真值，返回最后求值的那个参数（即“全部为假时返回最后一个参数”）。

真值判断的底层逻辑：hreflect.IsTruthfulValue

or内部调用的truth函数是对isTrue的封装（funcs.go），而isTrue直接委托给 Hugo 的反射工具包（见 hugo_template.go）：

func isTrue(val reflect.Value) (truth, ok bool) { return hreflect.IsTruthfulValue(val), true }

该入口位于 common/hreflect/helpers.go，其实现的“false、0、nil、零长度容器/字符串、零值时间均为假值”的规则，与上文公共文档片段中的文字描述完全一致。也就是说，文档中的判定标准与引擎实际执行的真值逻辑出自同一套实现，行为是可验证的。

测试用例对行为边界的印证

Hugo 的模板执行测试直接覆盖了or的核心分支，见 tpl/internal/go_templates/texttemplate/exec_test.go：

{"or", "{{or 0 0}} {{or 1 0}} {{or 0 true}} {{or 1 1}}", "0 1 true 1", nil, true},

该用例断言了四种典型场景：

HTML 模板执行器中存在完全相同的用例（tpl/internal/go_templates/htmltemplate/exec_test.go），说明or在 Go 文本模板与 HTML 模板两套执行引擎中的语义一致。

典型应用：默认值回退

利用“返回第一个真值、兜底返回最后一个参数”的特性，or是模板中做默认值回退的惯用写法：

{{ .Params.description | default "No description" }}

等价的or写法：

{{ $desc := or .Params.description "No description" }}

若.Params.description是空字符串或未设置（nil），两者都会输出"No description"；否则输出实际描述。由于or短路，前面的表达式若已确定真值，后面的表达式不会执行，因此在模板中组织“候选值列表”时可以安全地放置较昂贵的调用（如math.Div、资源加载类函数）在链的后段。

与 and 函数对照理解

or的镜像函数是and：返回第一个假值参数，若全部为真值则返回最后一个参数，同样从左到右短路求值（官方文档 functions/go-template/and.md）：

{{ and 1 0 "" }} → 0 (int) {{ and 1 2 3 }} → 3 (int) {{ and false (math.Div 1 0) }} → false (bool)

在源码层面，两者共用exec.go中同一段短路特判分支，仅以truth(v) == (name == "or")区分命中条件。对照使用这两个函数，可以覆盖模板中绝大多数“多候选取一”的逻辑需求。

小结

• or VALUE...返回第一个真值参数；全部为假时返回最后一个参数，返回值的类型与参数原始类型保持一致。
• 假值集合为：false、0、nil指针/接口值、零长度数组/切片/map/字符串、零值time.Time；其余均为真值。
• 求值从左到右且支持短路：一旦命中真值立即返回，后续参数（包括可能报错的表达式）不会被执行。
• 实现上，or在 tpl/internal/go_templates/texttemplate/funcs.go 注册、在 tpl/internal/go_templates/texttemplate/exec.go 中短路求值，真值判定由 common/hreflect/helpers.go 的IsTruthfulValue提供，行为有 exec_test.go 的测试用例覆盖。

如需了解更多模板语法细节，or与其他内置函数一样基于 Go 的text/template包扩展而来，可参考 text/template 文档说明。

【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo