宁缺毋滥:只在确信是真缺陷时才提出问题,上下文不清晰时保持沉默——误报比漏报一个次要问题更损耗评审者的信任。只评审待审 Jsonnet 中可观察到的内容;不要推断 diff 之外导入的库的内容、为外部变量或顶层参数提供的值,以及渲染输出在下游的消费方式。不要报告 jsonnetfmt 能静默修复的格式问题。晚绑定:self、$ 与 super
4 项- 在本应引用外层对象之处使用了
$。$绑定到*它所在文件*的最外层对象,因此当对象被合并进他人的配置时,引用$._config的库字段会解析到库自身的根,而不是调用方的树内置来源与改动说明
- 在嵌套对象内部读取
self.x,而self已重新绑定到该嵌套对象而非持有x的对象。既定的修复方式是在对象顶部一次性捕获预期作用域——local this = self,/local defaults = self,——然后引用this.x;当同一对象中已存在这样的捕获且显然意在使用它时,报告嵌套的self引用内置来源与改动说明
- 在任何可达组合中都不是
+右操作数的对象里引用super.f,这是运行时错误而非静默默认值内置来源与改动说明
local遮蔽了某个字段名,而后面的代码不加限定地引用该名称,导致对该字段的修改不再影响这个引用内置来源与改动说明
对象组合与覆盖
4 项- 两个对象之间的
+只合并顶层:两边都有的字段整体取自右操作数,其嵌套内容是被替换而非合并。当周边覆盖使用+:且意图显然是在继承值上追加而非丢弃时,报告用:书写的嵌套字段内置来源与改动说明
f+: v求值为super.f + v,因此运算符的含义随类型而定:对象合并一层,数组拼接,字符串按文本拼接。本意是“替换此列表”的覆盖写成+:会静默变为追加,产生重复的容器、卷或参数内置来源与改动说明
f+:中的f在继承对象中不存在——字段被重命名或拼错——会静默定义一个新字段而非覆盖任何内容,且没有任何代码读取它内置来源与改动说明
- 覆盖作用于一个并不位于其预期组合右侧的对象,于是更靠后的操作数胜出,该覆盖被从输出中丢弃内置
来源与改动说明
隐藏字段与渲染输出
5 项- 渲染后的清单本应包含的
::字段。隐藏字段不会出现在输出中且没有任何报错,因此缺失只会在应用该产物的位置暴露内置来源与改动说明
:字段持有内部辅助内容、半成品模板、原始函数参数或凭据,被原样泄漏进渲染出的 YAML/JSON内置来源与改动说明
- 在库刻意隐藏的字段上用
:::强制其可见,且没有说明理由内置来源与改动说明
- 必填参数惯用法
x:: error 'must provide x':错误只在有代码读取x时才触发,因此拼错字段名的覆盖会让默认值留在原处,失败出现在远离其根源之处,若无人读取则根本不出现内置来源与改动说明
- 目标是 Kubernetes 清单时的 null 与省略之别:显式的
field: null在 strategic-merge patch 中表示删除/重置,而省略的字段继承服务端默认值。std.prune与显式null是不同的请求,不是风格变体——报告二者被相互替换的情形内置来源与改动说明
导入与外部输入
5 项- 对非 Jsonnet 文件使用
import,而本意是importstr(原始文本)或importbin(原始字节);以及反向情形:对 Jsonnet 文件使用importstr,得到源码文本而非值内置来源与改动说明
- 导入在编译期依据
-J/jpath 搜索路径解析,因此在该路径中更早添加的文件会遮蔽预期文件,并在无任何诊断的情况下改变输出。当导入的相对路径直接伸入 vendored 树、而非经由库文档声明的入口时,予以报告内置来源与改动说明
- 读取
std.extVar('name')或顶层参数时既没有文档化的默认值也没有任何校验——输出于是依赖文件中不可见的状态内置来源与改动说明
- 外部变量的值以字符串到达;当其被与数字比较、用于算术运算,或未经
std.parseInt/std.parseJson/std.parseYaml就被当作对象使用时,予以报告内置来源与改动说明
std.extVar出现在计算字段名中([if std.extVar('x') then 'k']),未设置或为假值时会改变输出中到底存在哪些键内置来源与改动说明
终止性与输出物化
5 项- 递归函数或自引用对象,没有任何一个可证明地向基准情形收缩的参数。求值是惰性的,因此无限结构会被无声构建,只在消费方强制求值时才耗尽栈内置
来源与改动说明
std.manifestYamlDoc默认给键加引号;quote_keys=false才会产出不带引号的 YAML 键。当其输出被喂给要求裸键的消费方时予以报告;同时报告其结果——一个字符串——被当作结构化数据重新解析或索引内置来源与改动说明
- 物化出的字符串被插入 CLI 参数、ConfigMap 条目或注解中,而缩进、多文档
---分隔符或非字符串标量会改变接收方的解析方式内置来源与改动说明
std.toString或std.manifestJson被用作哈希、校验和注解或相等性检查的输入,而字段顺序或数字的表示形式并不保证在不同求值器版本间稳定内置来源与改动说明
assert被放在一个永不会被强制求值的位置来校验输入,于是该检查静默地从不运行内置来源与改动说明