Google Jsonnet 入门指南：从零开始掌握配置语言

Google Jsonnet 入门指南：从零开始掌握配置语言

jsonnet Jsonnet - The data templating language 项目地址: https://gitcode.com/gh_mirrors/js/jsonnet

什么是 Jsonnet

Jsonnet 是一种数据模板语言，它扩展了 JSON 的语法，添加了变量、条件、函数等编程特性，同时保持了 JSON 的兼容性。它由 Google 开发，主要用于生成复杂的 JSON 配置文件。

安装与运行 Jsonnet

Jsonnet 提供了两种官方实现：C++ 和 Go 版本。对于初学者，建议从 C++ 版本开始，因为它更成熟且功能更全面。

基本执行方式

Jsonnet 代码可以通过两种方式执行：

1. 直接执行代码片段：

jsonnet -e '{ x: 1, y: self.x + 1 } { x: 10 }'

2. 执行文件：

jsonnet example.jsonnet

这两种方式都会将结果以 JSON 格式输出到标准输出。

核心功能演示

基础示例

让我们看一个简单的 Jsonnet 文件示例 landingpage.jsonnet：

{
  "person1": {
    "name": "Alice",
    "welcome": "Hello Alice!"
  },
  "person2": {
    "name": "Bob",
    "welcome": "Hello Bob!"
  }
}

执行后会输出：

{
  "person1": {
    "name": "Alice",
    "welcome": "Hello Alice!"
  },
  "person2": {
    "name": "Bob",
    "welcome": "Hello Bob!"
  }
}

动态计算示例

Jsonnet 支持表达式和自引用（self）：

jsonnet -e '{ x: 1, y: self.x + 1 } { x: 10 }'

输出：

{
  "x": 10,
  "y": 11
}

高级输出格式

非 JSON 格式输出

Jsonnet 不仅可以生成 JSON，还能生成其他格式的文本。使用 -S 或 --string 参数可以直接输出纯文本而非 JSON 字符串。

例如，生成 INI 格式文件：

// ini_output.jsonnet
std.manifestIni({
  sections: {
    main: {
      host: "127.0.0.1",
      port: "9000",
    },
    database: {
      path: "/var/data",
    },
  },
})

执行：

jsonnet -S ini_output.jsonnet

输出：

[database]
path = /var/data
[main]
host = 127.0.0.1
port = 9000

多文件输出

Jsonnet 支持从单个文件生成多个 JSON 文件，使用 -m 参数：

// multiple_output.jsonnet
{
  "a.json": {
    x: 1,
    y: $["b.json"].y,
  },
  "b.json": {
    x: $["a.json"].x,
    y: 2,
  },
}

执行：

jsonnet -m . multiple_output.jsonnet

这会在当前目录生成 a.json 和 b.json 两个文件。

YAML 流输出

使用 -y 参数可以生成 YAML 流格式：

// yaml_stream.jsonnet
local
  a = {
    x: 1,
    y: b.y,
  },
  b = {
    x: a.x,
    y: 2,
  };

[a, b]

执行：

jsonnet -y yaml_stream.jsonnet

输出：

---
{
  "x": 1,
  "y": 2
}
---
{
  "x": 1,
  "y": 2
}
...

实现版本选择

Jsonnet 有两个官方实现：

1. C++ 实现：

   • 更成熟稳定
   • 性能更好
   • 包含格式化工具

2. Go 实现：

   • 代码更简洁
   • 包含 lint 工具
   • 是未来的发展方向

对于大多数用户，C++ 版本是更好的起点。但随着 Go 版本的不断完善，它将成为推荐选择。

JavaScript 支持

Jsonnet 可以通过 Emscripten 编译为 JavaScript，这使得它可以在浏览器中运行。虽然性能不如原生实现，但对于演示和小型应用已经足够。

最佳实践建议

1. 从简单开始：先掌握基本语法，再逐步学习高级特性
2. 模块化设计：将复杂配置分解为多个文件或函数
3. 利用标准库：Jsonnet 提供了丰富的标准库函数
4. 版本控制：像管理代码一样管理你的 Jsonnet 配置
5. 文档注释：使用注释说明配置项的用途和约束

Jsonnet 的强大之处在于它能够将复杂的配置逻辑抽象化，同时保持输出的可读性和一致性。通过本指南，你应该已经掌握了 Jsonnet 的基本使用方法，可以开始在实际项目中应用了。

jsonnet Jsonnet - The data templating language 项目地址: https://gitcode.com/gh_mirrors/js/jsonnet