跳到正文
Code Review
← 规则库/工程与配置

评审检查清单

Jsonnet

工程与配置23 个检查项5 个章节
**/*.{jsonnet,libsonnet}
宁缺毋滥:只在确信是真缺陷时才提出问题,上下文不清晰时保持沉默——误报比漏报一个次要问题更损耗评审者的信任。只评审待审 Jsonnet 中可观察到的内容;不要推断 diff 之外导入的库的内容、为外部变量或顶层参数提供的值,以及渲染输出在下游的消费方式。不要报告 jsonnetfmt 能静默修复的格式问题。
01

晚绑定:self、$ 与 super

4 项
  • 在本应引用外层对象之处使用了 $。$ 绑定到*它所在文件*的最外层对象,因此当对象被合并进他人的配置时,引用 $._config 的库字段会解析到库自身的根,而不是调用方的树
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 在嵌套对象内部读取 self.x,而 self 已重新绑定到该嵌套对象而非持有 x 的对象。既定的修复方式是在对象顶部一次性捕获预期作用域——local this = self, / local defaults = self,——然后引用 this.x;当同一对象中已存在这样的捕获且显然意在使用它时,报告嵌套的 self 引用
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 在任何可达组合中都不是 + 右操作数的对象里引用 super.f,这是运行时错误而非静默默认值
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • local 遮蔽了某个字段名,而后面的代码不加限定地引用该名称,导致对该字段的修改不再影响这个引用
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

02

对象组合与覆盖

4 项
  • 两个对象之间的 + 只合并顶层:两边都有的字段整体取自右操作数,其嵌套内容是被替换而非合并。当周边覆盖使用 +: 且意图显然是在继承值上追加而非丢弃时,报告用 : 书写的嵌套字段
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • f+: v 求值为 super.f + v,因此运算符的含义随类型而定:对象合并一层,数组拼接,字符串按文本拼接。本意是“替换此列表”的覆盖写成 +: 会静默变为追加,产生重复的容器、卷或参数
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • f+: 中的 f 在继承对象中不存在——字段被重命名或拼错——会静默定义一个新字段而非覆盖任何内容,且没有任何代码读取它
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 覆盖作用于一个并不位于其预期组合右侧的对象,于是更靠后的操作数胜出,该覆盖被从输出中丢弃
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

03

隐藏字段与渲染输出

5 项
  • 渲染后的清单本应包含的 :: 字段。隐藏字段不会出现在输出中且没有任何报错,因此缺失只会在应用该产物的位置暴露
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • : 字段持有内部辅助内容、半成品模板、原始函数参数或凭据,被原样泄漏进渲染出的 YAML/JSON
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 在库刻意隐藏的字段上用 ::: 强制其可见,且没有说明理由
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 必填参数惯用法 x:: error 'must provide x':错误只在有代码读取 x 时才触发,因此拼错字段名的覆盖会让默认值留在原处,失败出现在远离其根源之处,若无人读取则根本不出现
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 目标是 Kubernetes 清单时的 null 与省略之别:显式的 field: null 在 strategic-merge patch 中表示删除/重置,而省略的字段继承服务端默认值。std.prune 与显式 null 是不同的请求,不是风格变体——报告二者被相互替换的情形
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

04

导入与外部输入

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']),未设置或为假值时会改变输出中到底存在哪些键
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

05

终止性与输出物化

5 项
  • 递归函数或自引用对象,没有任何一个可证明地向基准情形收缩的参数。求值是惰性的,因此无限结构会被无声构建,只在消费方强制求值时才耗尽栈
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • std.manifestYamlDoc 默认给键加引号;quote_keys=false 才会产出不带引号的 YAML 键。当其输出被喂给要求裸键的消费方时予以报告;同时报告其结果——一个字符串——被当作结构化数据重新解析或索引
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 物化出的字符串被插入 CLI 参数、ConfigMap 条目或注解中,而缩进、多文档 --- 分隔符或非字符串标量会改变接收方的解析方式
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • std.toString 或 std.manifestJson 被用作哈希、校验和注解或相等性检查的输入,而字段顺序或数字的表示形式并不保证在不同求值器版本间稳定
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • assert 被放在一个永不会被强制求值的位置来校验输入,于是该检查静默地从不运行
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

返回本页顶部 ↑继续浏览规则库

手动复制规则链接

浏览器未允许自动复制,请选中下方链接复制。