Skip to main content
版本: 0.4.5

简介

KCL 语言提供 C/Rust/Go/Python/Java 等通用编程语言接口,相关语言正在开发完整中。

C/Rust 语言

KCL 核心采用 Rust 语言开发,对外导出 C 语言 API 供 Go/Python/Java 等高级语言包装和集成。

Go 语言

Go 语言是通过 CGO 包装 KCL 提供的 C-API,同时提供更深度的定制特性以满足上层工具的需求。

API 抽象模型

Go 语言 API 的抽象模型如下图:

┌─────────────────┐         ┌─────────────────┐           ┌─────────────────┐
│ kcl files │ │ KCL-Go-API │ │ KCLResultList │
│ ┌───────────┐ │ │ │ │ │
│ │ 1.k │ │ │ │ │ │
│ └───────────┘ │ │ │ │ ┌───────────┐ │ ┌───────────────┐
│ ┌───────────┐ │ │ ┌───────────┐ │ │ │ KCLResult │──┼────────▶│x.Get("a.b.c") │
│ │ 2.k │ │ │ │ Run(path) │ │ │ └───────────┘ │ └───────────────┘
│ └───────────┘ │────┐ │ └───────────┘ │ │ │
│ ┌───────────┐ │ │ │ │ │ ┌───────────┐ │ ┌───────────────┐
│ │ 3.k │ │ │ │ │ │ │ KCLResult │──┼────────▶│x.Get("k", &v) │
│ └───────────┘ │ │ │ │ │ └───────────┘ │ └───────────────┘
│ ┌───────────┐ │ ├───▶│ ┌───────────┐ │──────────▶│ │
│ │setting.yml│ │ │ │ │RunFiles() │ │ │ ┌───────────┐ │ ┌───────────────┐
│ └───────────┘ │ │ │ └───────────┘ │ │ │ KCLResult │──┼────────▶│x.JSONString() │
└─────────────────┘ │ │ │ │ └───────────┘ │ └───────────────┘
│ │ │ │ │
┌─────────────────┐ │ │ │ │ ┌───────────┐ │ ┌───────────────┐
│ Options │ │ │ ┌───────────┐ │ │ │ KCLResult │──┼────────▶│x.YAMLString() │
│WithOptions │ │ │ │MustRun() │ │ │ └───────────┘ │ └───────────────┘
│WithOverrides │────┘ │ └───────────┘ │ │ │
│WithWorkDir │ │ │ │ │
│WithDisableNone │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘

其中输入的文件包含 KCL 文件和 setting.yml 配置文件,Options 可以用于指定额外的参数和工作目录等信息。“KCL-Go-API”部分是提供的 KCL 执行函数,执行函数根据输入文件和额外的参数执行 KCL 程序,最终输出 KCLResultList 结果。KCLResultList 是一个 KCLResult 构成的列表,每个 KCLResult 对应一个生成的配置文件或 map[string]interface{}

例子

package main

import (
"fmt"

"kusionstack.io/kclvm-go/api/kcl"
)


func main() {
const k_code = `
import kcl_plugin.hello

name = "kcl"
age = 1

two = hello.add(1, 1)

schema Person:
name: str = "kcl"
age: int = 1

x0 = Person{}
x1 = Person{age:101}
`

result := kcl.MustRun("hello.k", kcl.WithCode(k_code)).First()
fmt.Println(result.YAMLString())

fmt.Println("----")
fmt.Println("x0.name:", result.Get("x0.name"))
fmt.Println("x1.age:", result.Get("x1.age"))

fmt.Println("----")

var person struct {
Name string
Age int
}
fmt.Printf("person: %+v\n", result.Get("x1", &person))
}

输出结果:

age: 1
name: kcl
two: 2
x0:
age: 1
name: kcl
x1:
age: 101
name: kcl

----
x0.name: kcl
x1.age: 101
----
person: &{Name:kcl Age:101}

REST-API

KCL 提供的 C-API 并没有 REST-API,REST-API 是通过 Protobuf 定义,最终由上层的 Go-SDK 提供实现。

启动 REST 服务

通过以下方式可以启动 RestAPI 服务:

kclvm -m gunicorn "kclvm.program.rpc-server.__main__:create_app()" -t 120 -w 4 -k uvicorn.workers.UvicornWorker -b :2021

然后可以通过 POST 协议请求服务:

$ curl -X POST http://127.0.0.1:2021/api:protorpc/BuiltinService.Ping --data '{}'
{
"error": "",
"result": {}
}

其中 POST 请求和返回的 JSON 数据和 Protobuf 定义的结构保持一致。

BuiltinService 服务

其中 /api:protorpc/BuiltinService.Ping 路径表示 BuiltinService 服务的 Ping 方法。

完整的 BuiltinService 由 Protobuf 定义:

service BuiltinService {
rpc Ping(Ping_Args) returns(Ping_Result);
rpc ListMethod(ListMethod_Args) returns(ListMethod_Result);
}

message Ping_Args {
string value = 1;
}
message Ping_Result {
string value = 1;
}

message ListMethod_Args {
// empty
}
message ListMethod_Result {
repeated string method_name_list = 1;
}

其中 Ping 方法可以验证服务是否正常,ListMethod 方法可以查询提供的全部服务和函数列表。

KclvmService 服务

KclvmService 服务是和 KCL 功能相关的服务。用法和 BuiltinService 服务一样。

比如有以下的 Person 结构定义:

schema Person:
key: str

check:
"value" in key # 'key' is required and 'key' must contain "value"

然后希望通过 Person 来校验以下的 JSON 数据:

{"key": "value"}

可以通过 KclvmService 服务的 ValidateCode 方法完成。参考 ValidateCode 方法的 ValidateCode_Args 参数结构:

message ValidateCode_Args {
string data = 1;
string code = 2;
string schema = 3;
string attribute_name = 4;
string format = 5;
}

根据 ValidateCode_Args 参数结构构造 POST 请求需要的 JSON 数据,其中包含 Person 定义和要校验的 JSON 数据:

{
"code": "\nschema Person:\n key: str\n\n check:\n \"value\" in key # 'key' is required and 'key' must contain \"value\"\n",
"data": "{\"attr_name\": {\"key\": \"value\"}}"
}

将该 JSON 数据保存到 vet-hello.json 文件,然后通过以下命令进行校验:

$ curl -X POST \
http://127.0.0.1:2021/api:protorpc/KclvmService.ValidateCode \
-H "accept: application/json" \
--data @./vet-hello.json
{
"error": "",
"result": {
"success": true
}
}

说明校验成功。

Python 语言

使用 Python SDK 要求您本地具备高于 3.7.3 的 Python 版本和 pip 包管理工具,可以通过如下命令进行安装并获得帮助信息

python3 -m pip install kclvm --user && python3 -m kclvm --help

命令行工具

编写名为 main.k 的 KCL 文件:

name = "kcl"
age = 1

schema Person:
name: str = "kcl"
age: int = 1

x0 = Person {}
x1 = Person {
age = 101
}

执行如下命令并获得输出:

$ python3 -m kclvm hello.k
name: kcl
age: 1
x0:
name: kcl
age: 1
x1:
name: kcl
age: 101

API

此外,我们还可以通过 Python 代码实现对 KCL 文件的执行

编写名为 main.py 的 python 文件:

import kclvm.program.exec as kclvm_exec
import kclvm.vm.planner as planner

print(planner.plan(kclvm_exec.Run(["hello.k"]).filter_by_path_selector()))

执行如下命令并获得输出:

$ python3 main.py
name: kcl
age: 1
x0:
name: kcl
age: 1
x1:
name: kcl
age: 101

可以看出通过命令行工具和 API 可以获得同样的输出。

目前 KCL Python SDK 还处于早期预览版本,后续 KCL 团队会持续更新并提供更丰富的功能,更多信息请参阅:https://github.com/kcl-lang/kcl-py

其它语言

用户也可以基于 C-API 和 RestAPI 包装其它语言的 SDK。