OPA

OPA进阶-函数与虚拟文档要分清

本文来讲讲OPA常用的函数（function）和虚拟文档（virtual document），以及他们使用的场景。

我们将以实现判断配置文件为例展开。

用到的输入(配置文件列表)为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// input.json
// posix为常见路径格式
// traditional-mac为mac的一种文件路径格式
{
  "files": [
  {
    "type": "posix",
    "path": "/Users/newbmiao/Documents/1.yaml"
  },
  {
    "type": "posix",
    "path": "/Users/newbmiao/Documents/2.yaml"
  },
  {
    "type": "traditional-mac",
    "path": "Macintosh HD:Users:newbmiao:Documents:3.yml"
  },
  {
    "type": "traditional-mac",
    "path": "Macintosh HD:Users:newbmiao:Documents:3.json"
  }
  ]
}

函数

函数基本每个语言都会有，要说OPA里有啥特别的地方，那就是他也实现同名函数，类似“函数重载”，但简化了许多。

他的特点是：

  • 默认函数返回值为 true/false
  • 可以指定函数返回值
  • 可以存在同名函数, 但参数数目不能变
  • 相同输入（参数）必须获得相同输出（返回值）

举例来说，如果实现判断文件是否是配置文件后缀：

下边is_config_file就是不指定返回值

条件满足则返回true，三个实现只要满足一个就为true

1
2
3
4
5
6
7
8
9
10
11
is_config_file(str) {
  contains(str, ".yaml")
}

is_config_file(str) {
  contains(str, ".yml")
}

is_config_file(str) {
  contains(str, ".json")
}

当然也可以使用else关键字合并到一个函数：

1
2
3
4
5
6
7
8
9
10
11
is_config_file2(str) {
  contains(str, ".yaml")
}

else {
  contains(str, ".yml")
}

else {
  contains(str, ".json")
}

那如果指定返回值怎么重载呢？

以实现不同路径格式的文件名为例：

1
2
3
4
5
6
7
8
9
10
11
12
13
getFileName(type, str) = x {
  type = "posix"
  str = trim(str)
  tmp := split(str, "/")
  x := tmp[minus(count(tmp), 1)]
}

getFileName(type, str) = x {
  type = "traditional-mac"
  str = trim(str)
  tmp := split(str, ":")
  x := tmp[minus(count(tmp), 1)]
}

你会发现两个函数输入和返回不是相同的么？

其实不是，仔细看他们内都做了 type = {"traditional-mac"|"posix"} 的判断

这实际类似函数声明为 getFileName("posix", str) = x {}, 所以输入是不同的

如果你省略了type的判断，会报错的：

eval_conflict_error: functions must not produce multiple outputs for same inputs

到此，将函数组合一下就可以实现判定是否为配置：

1
2
3
4
5
6
7
import input.files

is_config {
  file := files[_]
  x := getFileName(file.type, file.path)
  is_config_file(x)
}

Tips: 关于OPA的内置函数可以查看文档:built-in-functions

虚拟文档

虚拟文档是生成的文档（或者称为集合）

他的特点是：

  • 作为集合，输入和输出必须是有限的
  • 可以遍历
  • 可以查询

举例来说，同样是获取文件名：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import input.files

getFileNames[x] {
  file := files[_]
  file.type = "posix"
  file.path = trim(file.path)
  tmp := split(file.path, "/")
  x := tmp[minus(count(tmp), 1)]
}

getFileNames[x] {
  file := files[_]
  file.type = "traditional-mac"
  file.path = trim(file.path)
  tmp := split(file.path, ":")
  x := tmp[minus(count(tmp), 1)]
}

这里 getFileNames[x] {} 等价于 getFileNames[x] = x {}

就是x作为了集合的一个结果，填充到getFileNames这个虚拟文档中，其key也是x的值。

有点抽象是不？

别怕，他可以查询，我们查询看下他的结果就好理解了

1
2
3
4
5
6
7
8
9
10
cd syntax
opa eval -f values -i input.json -d . "data.example_virtual_doc.getFileNames"
[
  [
    "1.yaml",
    "2.yaml",
    "3.yml",
    "3.json"
  ]
]

然后遍历虚拟文档，结合判定is_config_file就可实现判定：

1
2
3
4
5
6
import data.example_func.is_config_file
import input.files

is_config {
  is_config_file(getFileNames[_])
}

这里遍历getFileNames[_],随即作为每一个输入参数传给is_config_file进行判断，是不是很方便！

适用场景

具体到他们的适用场景，其实比较好区分，重点只要关注两点：

  • 是否需要遍历？
  • 输入输出是否是有限的？

如果有一个答案是肯定的，那么虚拟文档就更适合。

OPA的函数和虚拟文档很简单、很清秀是不是？

今天就到这里，下一篇我们看看他更优雅的推导式（Comprehensions）。

本文代码详见:NewbMiao/opa-koans

如有疑问，请文末留言交流或邮件：newbvirgil@gmail.com 本文链接 : https://newbmiao.github.io/2020/03/18/opa-func-and-virtual-doc.html