1.2 KCL язык

KCL (Kusion Configuration Language) — это встроенный язык конфигурации для домена, разработанный Kusion. KCL был изначально вдохновлён Python3 и включает в себя концепции декларативного и объектно-ориентированного программирования. Это динамически типизированный язык, предназначенный для определения конфигурации и проверки, который особенно подходит для конфигураций и стратегий. В этом разделе мы рассмотрим основные характеристики языка KCL.

1.2.1 Hello KCL

Лучший способ изучить новый язык — написать несколько небольших программ самостоятельно. Как и в случае с другими языками конфигурации, мы можем писать программы на KCL, как если бы мы писали конфигурацию.

Вот простой пример программы hello.k:

hello = "KCL"

Здесь мы присваиваем значение "KCL" атрибуту hello. Затем сохраняем код в файл hello.k.

Способ выполнения этой программы зависит от конкретной среды разработки. Предположим, что локальная среда macOS или Linux уже установила команду kcl (или вы можете использовать docker run --rm -it kusionstack/kusion bash для тестирования в среде Docker). Затем в командной строке каталога файла введите следующую команду:

$ kcl hello.k 
hello: KCL

Результат выполнения команды будет выглядеть следующим образом:

Вывод представляет собой данные конфигурации в формате YAML. Хотя эта программа проста, она позволяет нам проверить базовое использование среды разработки и команды kcl.

1.2.2 Более сложная конфигурация

Помимо обычных пар ключ-значение, в распространённых данных конфигурации также используются вложенные словари и списки. Кроме строк, базовые типы значений включают логические значения и числа. Вот более сложный пример конфигурации server.k:

# This is a KCL document

title = "KCL Example"

owner = {
	name = "The KCL Authors"
	data = "2020-01-02T03:04:05"
}

database = {
	enabled = True
	ports = [ 8000, 8001, 8002 ]
	data = [ ["delta", "phi"], [3.14] ]
	temp_targets = { cpu = 79.5, case = 72.0 }
}

servers = [
	{ip = "10.0.0.1", role = "frontend"}
	{ip = "10.0.0.2", role = "backend"}
]

Строки, начинающиеся с #, являются комментариями. Значение owner — это словарь, содержимое которого заключено в фигурные скобки {...}. Значение словаря database включает логическое значение True, список [] и другой словарь. Список и словарь также могут содержать числовые значения. Атрибут servers представляет собой список, внутри которого вложен словарь (словари и списки, а также schema, о которой будет рассказано позже, могут быть вложены друг в друга).

YAML-представление вывода выглядит следующим образом:

$ kcl server.k 
title: KCL Example
owner:
  name: The KCL Authors
  data: '2020-01-02T03:04:05'
database:
  enabled: true
  ports:
  - 8000
  - 8001
  - 8002
  data:
  - - delta
    - phi
  - - 3.14
  temp_targets:
    cpu: 79.5
    case: 72.0
servers:
- ip: 10.0.0.1
  role: frontend
- ip: 10.0.0.2
  role: backend

1.2.3 Определение структуры конфигурации с помощью schema

KCL предоставляет абстракцию для свойств с фиксированной структурой и поведением по умолчанию через синтаксис schema.

Например, конфигурация базы данных в предыдущем примере обычно использует значения по умолчанию. Мы можем определить структуру для конфигурации базы данных по умолчанию:

schema DatabaseConfig:
    enabled: bool = True
    ports: [int] = [ 8000, 8001, 8002 ]
    data: [[str|float]] = [ ["delta", "phi"], [3.14] ]
    temp_targets: {str:float} = { cpu = 79.5, case = 72.0 }

Атрибут enabled имеет тип bool, ports — список целых чисел, data — вложенный список, элементы которого могут быть строками или числами с плавающей точкой, а temp_targets — словарь, где значения имеют тип float. Каждый атрибут в DatabaseConfig также имеет значение по умолчанию.

Мы можем создать структуру с теми же свойствами, используя database = DatabaseConfig{}. Пользователи также могут переопределить значения по умолчанию:

database = DatabaseConfig{
    ports = [2020, 2021]
}

schema DatabaseConfig не только предоставляет значения по умолчанию для атрибутов, но и добавляет информацию о типе. Если пользователь случайно укажет неправильный тип значения атрибута, KCL выдаст дружественное сообщение об ошибке, например:

$ kcl server.k 
KCL Compile Error[E2G22] : The type got is inconsistent with the type expected
    ---> File /path/to/server.k:8:2
    8 |    ports = [1.2, 1.3]
      5    ^  -> got [float(1.2)|float(1.3)]
    ---> File /path/to/server.k:3:2
    3 |    ports: [int] = [ 8000, 8001, 8002 ]
      5    ~  -> expect [int]
expect [int], got [float(1.2)|float(1.3)]

Аналогично, мы можем использовать следующий код для инкапсуляции атрибутов части servers:

schema ServerConfig:
	ip: str
	role: "frontend" | "backend"

servers = [
	ServerConfig{ip = "10.0.0.1", role = "frontend"}
	ServerConfig{ip = "10.0.0.2", роль = "бэкенд"}
]

В ServerConfig атрибут ip имеет строковый тип и не имеет значения по умолчанию. При создании свойства типа ServerConfig пользователь должен вручную указать значение атрибута ip, иначе KCL сообщит об отсутствии обязательного атрибута. Тип атрибута role — строка "frontend" | "backend".

Кроме того, schema может использоваться в сочетании с необязательными атрибутами, check, mixin, наследованием и расширением модулей для реализации более сложных абстракций конфигурации и стратегии данных. Подробные сведения можно найти в документации.

1.2.4 Playground

Если у вас установлена KCL, вы можете запустить Playground с помощью команды kcl-go play:

$ kcl-go play
listen at http://127.0.0.1:2021
...

Эта команда автоматически откроет страницу Playground в браузере, как показано ниже:

Код демонстрирует, как импортировать расширенный модуль, и показывает базовое использование schema.

Playground предоставляет основные функции выполнения и обеспечивает подсветку синтаксиса и форматирование кода.