Prometheus 的大粉丝。 我在家庭和工作中都使用了很多,并且非常喜欢深入" />
062017
 

我是 Prometheus 的大粉丝。 我在家庭和工作中都使用了很多,并且非常喜欢深入了解我的系统在任何时刻的工作情况。 最广泛使用的 Prometheus 商家之一是 node_exporter:可以从类 UNIX 机器中提取各种指标的守护进程。

在我浏览仓库时,我注意到 open issue,要求向 node_exporter 添加 WiFi 指标。 这个想法吸引了我,我意识到我一定会在我的 Linux 笔记本电脑上使用这样一个功能。 我开始探索在 Linux 上检索WiFi 设备信息的选项。

经过几周的实验(包括旧版 ioctl() 无线扩展 API),我创作了两个 Go 包,它们可以共同工作,在 Linux 上与 WiFi 设备进行交互:

* netlink:提供对 Linux netlink 套接字的底层访问。
* wifi:提供对 IEEE 802.11 WiFi 设备操作和统计信息的访问。

这一系列的文章将描述在 Go 中实现这些包时学到的一些经验教训,希望能够为选择这两个库进行试验的人提供一个很好的参考。

本系列的伪代码将使用 Go 的 x/sys/unix 包和我的 netlink 和 wifi 包的类型。 我打算把这个系列分解如下(链接来自更多的文章):

* 第 1 部分:netlink(这篇文章):netlink 的介绍。
* 第 2 部分:通用 netlink:通用 netlink 简介,一个 netlink 家族,旨在简化新家庭的创建。
* 第 3 部分:包 netlink,genetlink 和 wifi:使用 Go 驱动与 netlink,通用 netlink 和 nl80211 的交互。

什么是 netlink?

Netlink 是一个 Linux 内核进程间通信机制,可实现用户空间进程与内核之间的通信,或多个用户空间进程通讯。 Netlink 套接字是启用此通信的原语。

这篇文章将提供关于 netlink 套接字,消息,多播组和属性的基本知识。 此外,这篇文章将重点介绍用户空间和内核之间的通信,而不是两个用户空间进程之间的通信。

创建 netlink 套接字

Netlink 使用标准 BSD 套接字 API。 对于在 C 中进行网络编程的人来说,这应该是非常熟悉的。如果您不熟悉 BSD 套接字,我建议您阅读优秀的“Beej 网络编程指南”来了解本主题。

重要的是要注意,netlink 通信永远不会遍历本地主机(local host)。 记住这一点,让我们开始深入了解 netlink 套接字的工作原理!

要与 netlink 进行通信,必须打开 netlink 套接字。 这是使用 socket() 系统调用完成的:

fd, err := unix.Socket(
    // Always used when opening netlink sockets.
    // 打开 netlink 套接字时始终使用。
    unix.AF_NETLINK,
    // Seemingly used interchangeably with SOCK_DGRAM,
    // but it appears not to matter which is used.
    // 似乎与 SOCK_DGRAM 可互换使用,使用哪个并不重要。
    unix.SOCK_RAW,
    // The netlink family that the socket will communicate
    // with, such as NETLINK_ROUTE or NETLINK_GENERIC.
    // 套接字与之通信的 netlink 系列,如 NETLINK_ROUTE 或 NETLINK_GENERIC。
    family,
)

family 参数指定一个特定的 netlink 系列:本质上是可以使用 netlink 套接字进行通信的内核子系统。 这些系列可能会提供诸如此类的功能。

* NETLINK_ROUTE:操纵 Linux 的网络接口,路由,IP地址等
* NETLINK_GENERIC:简化添加新的 netlink 系列的构建块,如 nl80211,Open vSwitch 等。

一旦创建套接字,必须调用 bind() 来准备发送和接收消息。

err := unix.Bind(fd, &unix.SockaddrNetlink{
    // Always used when binding netlink sockets.
    // 绑定 netlink 套接字时始终使用。
    Family: unix.AF_NETLINK,
    // A bitmask of multicast groups to join on bind.
    // Typically set to zero.
    // 绑定的多播组加入的位掩码。通常设置为零。
    Groups: 0,
    // If you'd like, you can assign a PID for this socket
    // here, but in my experience, it's easier to leave
    // this set to zero and let netlink assign and manage
    // PIDs on its own.
    // 如果你愿意,你可以在这里给这个套接字分配一个PID,但是根据我的经验,将这个设置保留为零是很容易的,让 netlink 自己分配和管理 PID。
    Pid: 0,
})

此时,netlink 套接字现在可以发送和接收来自内核的消息。

Netlink 消息格式

Netlink 消息遵循非常特殊的格式。 所有消息必须与 4 字节边界对齐。 例如,16 字节的消息必须按原样发送,但是 17 字节的消息必须被填充到 20 个字节。

非常重要的是要注意,与典型的网络通信不同,netlink 使用主机字节顺序来编码和解码整数,而不是普通的网络字节顺序(大端)。 因此,必须在数据的字节和整数表示之间转换的代码必须牢记这一点。

Netlink 消息头使用以下格式:(来自 RFC 3549 的图):

0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sequence Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Process ID (PID) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

这些字段包含以下信息:

* 长度(32位):整个消息的长度,包括报头和有效载荷(消息体)。
* 类型(16位):消息包含什么样的信息,如错误,multi-part 消息的结束等。
* 标志(16位):指示消息是请求的位标志,如 multi-part ,请求确认等。
* 序列号(32位):用于关联请求和响应的数字;每个请求递增。
* 进程ID(PID)(32位):有时称为端口号;用于唯一标识特定 netlink 套接字的数字; 可能是也可能不是进程的ID。

最后,有效载荷可能会立即跟随 netlink 消息头。 再次注意,有效载荷必须填充到 4 字节的边界。

向内核发送请求的示例 netlink 消息可能类似于 Go 中的以下内容:

msg := netlink.Message{
    Header: netlink.Header{
        // Length of header, plus payload.
        Length: 16 + 4,
        // Set to zero on requests.
        Type: 0,
        // Indicate that message is a request to the kernel.
        Flags: netlink.HeaderFlagsRequest,
        // Sequence number selected at random.
        Sequence: 1,
        // PID set to process's ID.
        PID: uint32(os.Getpid()),
    },
    // An arbitrary byte payload. May be in a variety of formats.
    Data: []byte{0x01, 0x02, 0x03, 0x04},
}

发送和接收 netlink 消息

现在我们熟悉了netlink 套接字的一些基础知识,我们可以使用套接字发送和接收数据。

一旦一个消息已经准备好,它可以使用 sendto() 发送到内核:

// Assume messageBytes produces a netlink request message (like the
// one shown above) with the specified payload.
b := messageBytes([]byte{0x01, 0x02, 0x03, 0x04})
err := unix.Sendto(b, 0, &unix.SockaddrNetlink{
    // Always used when sending on netlink sockets.
    Family: unix.AF_NETLINK,
})

对 netlink 的只读请求通常不需要任何特殊权限。 使用 netlink 修改子系统状态或需要锁定其内部状态的操作通常需要提升权限。 这可能意味着以 root 身份运行该程序或使用 CAP_NET_ADMIN 来执行以下操作:

* 发送写请求,使用 netlink 更改子系统。
* 使用 NLM_F_ATOMIC 标志发送读取请求,来从 netlink 接收数据的原子快照。

使用 recvfrom() 从 netlink socket 接收消息可能会稍微复杂一些,具体取决于各种因素。Netlink 可能如下回复:

* 非常小或非常大的消息。
* Mulit-part 消息,分为多个部分。
* 显示错误号,当消息头类型为“error”时。

此外,每个消息的序列号和 PID 也应该被验证。使用原始系统调用时,由套接字的用户处理这些情况。

大消息

为了处理大消息,我采用了一种分配单页内存的技术:窥探缓冲区(读取数据但不清除),然后将缓冲区的大小加倍,如果太小,无法读取整个消息。 谢谢 Dominik Honnef 你对这个问题的见解。

为了简便起见,我们省略了错误处理。实际中,请检查你的错误!

b := make([]byte, os.Getpagesize())
for {
    // Peek at the buffer to see how many bytes are available.
    n, _, _ := unix.Recvfrom(fd, b, unix.MSG_PEEK)
    // Break when we can read all messages.
    if n < len(b) {
        break
    }
    // Double in size if not enough bytes.
    b = make([]byte, len(b)*2)
}
// Read out all available messages.
n, _, _ := unix.Recvfrom(fd, b, 0)

理论上说,一个 netlink 消息的大小可能高达~4GiB(32位无符号整数的最大值),但实践中消息要小得多。

Multi-part 消息

对于某些类型的消息,netlink 可以使用“Multi-part 消息”来回复。在这种情况下,最后一条之前的每条消息都将设置“multi”标志。 最后的消息将有一个“done”的类型。

返回 Multi-part 消息时,第一个 recvfrom() 将返回所有设置了“multi”标志的消息。 接下来,必须再次调用 recvfrom() 来检索头文件类型为“done”的最终消息。 这是非常重要的,否则 netlink 将会直接 hang 在后续的请求上,等待调用者取出最后的头部类型为“done”的消息。

Netlink 错误号

如果 netlink 由于任何原因不能满足请求,它将在包含消息头类型为“error”的消息的有效载荷中返回明确的错误号。 这些错误号与 Linux 的经典错误号相同,例如“不存在这样的文件或目录”的ENOENT,“被拒绝的权限”的 EPERM。

如果消息的报头类型指示错误,则错误编号将被编码为消息有效载荷的前4个字节中的带符号的32位整数(注意:也使用系统字节顺序)。

const name = "foo0"
_, err := rtnetlink.InterfaceByName(name)
if err != nil && os.IsNotExist(err) {
    // Error is result of a netlink error number, and can be
    // checked in the usual Go fashion.
    log.Printf("no such device: %q", name)
    return
}

序列号和 PID 验证

为了确保内核的 netlink 回复是响应我们的某个请求,我们还必须在每个接收的消息上验证序列号和 PID。在大多数情况下,这些都应该与发送到内核的请求完全一致。后续请求应该在向 netlink 发送另一个消息之前增加序列号。

PID 验证可能会有所不同,具体取决于几个条件。

* 如果在用户空间中代表组播组接收到消息,则它的 PID 为0,表示消息始发于内核。
* 如果请求被发送到 PID 为 0 的内核,netlink 将在第一个响应中为给定的套接字分配一个PID。该PID应在随后的通信中使用(并被验证)。

假设您没有在 bind() 中指定 PID,则在单个应用程序中打开多个 netlink 套接字时,将该进程的 ID 作为第一个 netlink 套接字的 PID。后续的将由 netlink 从随机数选择。根据我的经验,只要让 netlink 分配所有自身的 PID,并确保跟踪每个套接字分配的数字,这一点要容易得多。

多播组

除了传统的请求/响应套接字范例之外,netlink 套接字还提供多播组,以便在发生某些事件时启用订阅。

可以使用两种不同的方法来连接多播组:

* 在 bind() 期间指定组位掩码。这被认为是 “legacy” 的方法。
* 使用 setsockopt() 连接和断开组。 这是首选,现代的方法。

使用 setsockopt() 连接和断开组是交换单个常量的问题。在Go中,这是使用 uint32 “group” 值完成的。

// Can also specify unix.NETLINK_DROP_MEMBERSHIP to leave
// a group.
const joinLeave = unix.NETLINK_ADD_MEMBERSHIP
// Multicast group ID. Typically assigned using predefined
// constants for various netlink families.
const group = 1
err := syscall.SetSockoptInt(
    fd,
    unix.SOL_NETLINK,
    joinLeave,
    group,
)

一旦加入了一个组,你可以像往常一样使用 recvfrom() 来收听消息。断开组将不会给出给定多播组的更多消息。

Netlink 属性

要在 netlink 套接字上包含我们的引用,我们将讨论 netlink 消息有效载荷的一个非常常见的数据格式:属性。

Netlink 属性是不寻常的,因为它们是LTV(长度,类型,值)格式,而不是典型的TLV(类型,长度,值)。 与 netlink 套接字中的其他整数一样,类型和长度值也以主机字节编码。 最后,netlink 属性也必须填充到 4 字节边界,就像 netlink 消息一样。

每个字段包含以下信息:

* 长度(16位):整个属性的长度,包括长度,类型和值字段。不能设置为4字节边界。 例如,如果长度为17字节,则该属性将被填充到20个字节,但是不应该将3个字节的填充解释为有意义的。
* 类型(16位):属性的类型,通常定义为某些 netlink 系列或标题中的常量。
* 值(可变字节):属性的原始有效负载。可能包含以相同格式存储的嵌套属性。这些嵌套属性可能包含更多的嵌套属性!

netlink 属性中可能有两个特殊的标志,虽然我还没有在我的工作中遇到他们。

* NLA_F_NESTED:指定嵌套属性;用作解析的提示。即使存在嵌套属性,似乎并不总是被使用。
* NLA_F_NET_BYTEORDER:属性数据以网络字节顺序(大端)存储,而不是主机字节顺序。

请参阅给定的 netlink 系列的文档,以确定是否应检查其中一个标志。

概要

现在我们熟悉使用 netlink 套接字和消息,系列中的下一篇文章将基于这些知识来深入通用 netlink。
希望你喜欢这篇文章! 如果您有任何疑问或意见,请随时通过评论,Twitter或Gophers Slack(用户名:mdlayher)进行联系。

更新

2/22/2017:将有关BSD套接字API的背景信息移动到“创建netlink套接字”部分。
2/22/2017:注意到需要root或CAP_NET_ADMIN用于许多netlink写操作,以及使用NLM_F_ATOMIC时。
2/23/2017:注意到在 bind() 中为套接字指定 PID 的能力。
2/27/2017:由于 syscall 被冻结,因此将伪代码更改为使用x/sys/unix而不是syscall。

参考

以下链接经常用作参考,因为我建立了包 netlink,并撰写了这篇文章:
维基百科:Netlink:https://en.wikipedia.org/wiki/Netlink
使用Netlink套接字在Linux内核和用户空间之间进行通信:https://pdfs.semanticscholar.org/6efd/e161a2582ba5846e4b8fea5a53bc305a64f3.pdf
使用Netlink套接字了解和编程:https://people.redhat.com/nhorman/papers/netlink.pdf
Netlink [C] 库(libnl):https://www.infradead.org/~tgr/libnl/doc/core.html

062015
 

做过 Web 开发的,应该都用过或听过 jQuery,它提供了方便的操作 DOM 的 API。使用 Go 语言做服务器端开发,有时候需要解析 HTML 文件,比如抓取网站内容、写一个爬虫等。这时候如果有一个类似 jQuery 的库可以使用,操作 DOM 会很方便,而且,上手也会很快。github.com/PuerkitoBio/goquery 这个库就实现了类似 jQuery 的功能,让你能方便的使用 Go 语言操作 HTML 文档。

1 概述

Go 实现了类似 jQuery 的功能,包括链式操作语法、操作和查询 HTML 文档。它基于 Go net/html 包和 CSS 选择器库 cascadia。由于 net/html 解析器返回的是 DOM 节点,而不是完整的 DOM 树,因此,jQuery 的状态操作函数没有实现(像 height(),css(),detach())。

由于 net/html 解析器要求文档必须是 UTF-8 编码,因此 goquery 库也有此要求。如果文档不是 UTF-8 编码,使用者需要自己转换。进行编码转换,可以使用如下库:
iconv 的 Go 封装,如:github.com/djimenez/iconv-go
官方提供的 text 子仓库,text/encoding,用于其他编码和 UTF-8 之间进行转换

除了实现和 jQuery 类似的功能外,在函数名方面,也尽量和 jQuery 保持一致,也支持链式语法。

2 goquery 提供的主要类型和方法

2.1 Document

Document 代表一个将要被操作的 HTML 文档,不过,和 jQuery 不同,它装载的是 DOM 文档的一部分。

type Document struct {
	*Selection
	Url *url.URL
	rootNode *html.Node // 文档的根节点
}

因为 Document 中内嵌了一个 Selection 类型,因此,Document 可以直接使用 Selection 类型的方法。

有五种方法获取一个 Document 实例,分别是从一个 URL 创建、从一个 *html.Node 创建、从一个 io.Reader 创建、从一个 *http.Response 创建和从一个已有的 Document Clone 一个。

2.2 Selection

Selection 代表符合特定条件的节点集合。

type Selection struct {
	Nodes []*html.Node
	document *Document
	prevSel *Selection
}

一般地,得到了 Document 实例后,通过 Dcoument.Find 方法获取一个 Selection 实例,然后像 jQuery 一样使用链式语法和方法操作它。

Selection 类型提供的方法可以分为如下几大类(注意,3个点(…)表示有重载的方法):

1)类似函数的位置操作

- Eq()
- First()
- Get()
- Index…()
- Last()
- Slice()

2)扩大 Selection 集合(增加选择的节点)

- Add…()
- AndSelf()
- Union(), which is an alias for AddSelection()

3)过滤方法,减少节点集合

- End()
- Filter…()
- Has…()
- Intersection(), which is an alias of FilterSelection()
- Not…()

4)循环遍历选择的节点

- Each()
- EachWithBreak()
- Map()

5)修改文档

- After…()
- Append…()
- Before…()
- Clone()
- Empty()
- Prepend…()
- Remove…()
- ReplaceWith…()
- Unwrap()
- Wrap…()
- WrapAll…()
- WrapInner…()

6)检测或获取节点属性值

- Attr(), RemoveAttr(), SetAttr()
- AddClass(), HasClass(), RemoveClass(), ToggleClass()
- Html()
- Length()
- Size(), which is an alias for Length()
- Text()

7)查询或显示一个节点的身份

- Contains()
- Is…()

8)在文档树之间来回跳转(常用的查找节点方法)

- Children…()
- Contents()
- Find…()
- Next…()
- Parent[s]…()
- Prev…()
- Siblings…()

2.3 Matcher 接口

该接口定义了一些方法,用于匹配 HTML 节点和编译过的选择器字符串。Cascadia’s Selector 实现了该接口。

type Matcher interface {
	Match(*html.Node) bool
	MatchAll(*html.Node) []*html.Node
	Filter([]*html.Node) []*html.Node
}

3 实战演练

该库提供的类型很少,但方法却很多,我们不可能一个个方法讲解。这里通过模拟几个使用场景来讲解该库的使用。

3.1 抓取 Go语言中文网 社区主题 — http://studygolang.com/topics

查看页面 HTML 结构后,就跟使用 jQuery 操作页面一样。这个例子,我们获取社区主题的标题列表。

主要代码如下(为了节省篇幅,包导入等语句省略,完整代码,参见文章最后说明):

func main() {
	doc, err := goquery.NewDocument("http://studygolang.com/topics")
	if err != nil {
		log.Fatal(err)
	}

	doc.Find(".topics .topic").Each(func(i int, contentSelection *goquery.Selection) {
		title := contentSelection.Find(".title a").Text()
		log.Println("第", i+1, "个帖子的标题:", title)
	})
}

编译、运行输出如下(你看到的内容和当时社区的主题列表一致):

2015/04/06 22:15:24 第 1 个帖子的标题: 问个加载包的问题
2015/04/06 22:15:24 第 2 个帖子的标题: Tango v0.4版本发布,带来统一高性能的新路由
2015/04/06 22:15:24 第 3 个帖子的标题: 创业团队缺后端开发
2015/04/06 22:15:24 第 4 个帖子的标题: 自由是创造力和灵感的催化剂,需要golang后端开发人员
2015/04/06 22:15:24 第 5 个帖子的标题: cgo编译出来的文件怎么用?
2015/04/06 22:15:24 第 6 个帖子的标题: cgo编译问题,Undefined symbols
2015/04/06 22:15:24 第 7 个帖子的标题: 北京 GO 研发程序员,全职,20K+
2015/04/06 22:15:24 第 8 个帖子的标题: Go 1.5 计划启动,使用 Go 来编译 Go
2015/04/06 22:15:24 第 9 个帖子的标题: beego.Error 原理
2015/04/06 22:15:24 第 10 个帖子的标题: 插入数据库操作测试 1分钟一百万条数据 这数据怎么样?
2015/04/06 22:15:24 第 11 个帖子的标题: Go最新资料汇总(十一)
2015/04/06 22:15:24 第 12 个帖子的标题: Azul3D_Go开发的3D游戏引擎简介
2015/04/06 22:15:24 第 13 个帖子的标题: Golang中goroutine线程何时终止问题
2015/04/06 22:15:24 第 14 个帖子的标题: 标准库中文版的testing是不是打不开了?
2015/04/06 22:15:24 第 15 个帖子的标题: 如何使用cgo编译出来的文件

是不是很简单?

这里我们使用了 Each 这个方法。在 jQuery 中,each 迭代时,如果返回 false,可以终止迭代。比如,我们希望遇到标题中包含 cgo 的主题时,停止迭代,可以使用 EachWithBreak(之所以没有使用 Each,是因为迭代终止的功能是后来加入的,为了不改变 Each 的行为,保持兼容性,引入了该方法):

doc.Find(".topics .topic").EachWithBreak(func(i int, contentSelection *goquery.Selection) bool {
	title := contentSelection.Find(".title a").Text()
	log.Println("第", i+1, "个帖子的标题:", title)
	if strings.Contains(title, "cgo") {
		return false
	}
	return true
})

从上面的输出可以看到,Each 遍历是按照页面节点的顺序的。如果我们希望反着处理,也就是先处理页面最底下的节点。查看文档,发现没有直接提供这样的方法。那么该怎么实现呢?

topicsSelection := doc.Find(".topics .topic")

for i := topicsSelection.Length() - 1; i >= 0; i-- {
	// 返回的是 *html.Node
	topicNode := topicsSelection.Get(i)
	title := goquery.NewDocumentFromNode(topicNode).Find(".title a").Text()
	log.Println("第", i+1, "个帖子的标题:", title)
}

这里用到了 NewDocumentFromNode,把其中某一块 HTML 当做文档,对其进行操作。

输出如下:

2015/04/06 22:50:28 第 15 个帖子的标题: 如何使用cgo编译出来的文件
2015/04/06 22:50:28 第 14 个帖子的标题: 标准库中文版的testing是不是打不开了?
2015/04/06 22:50:28 第 13 个帖子的标题: Golang中goroutine线程何时终止问题
2015/04/06 22:50:28 第 12 个帖子的标题: Azul3D_Go开发的3D游戏引擎简介
2015/04/06 22:50:28 第 11 个帖子的标题: Go最新资料汇总(十一)
2015/04/06 22:50:28 第 10 个帖子的标题: 插入数据库操作测试 1分钟一百万条数据 这数据怎么样?
2015/04/06 22:50:28 第 9 个帖子的标题: beego.Error 原理
2015/04/06 22:50:28 第 8 个帖子的标题: Go 1.5 计划启动,使用 Go 来编译 Go
2015/04/06 22:50:28 第 7 个帖子的标题: 北京 GO 研发程序员,全职,20K+
2015/04/06 22:50:28 第 6 个帖子的标题: cgo编译问题,Undefined symbols
2015/04/06 22:50:28 第 5 个帖子的标题: cgo编译出来的文件怎么用?
2015/04/06 22:50:28 第 4 个帖子的标题: 自由是创造力和灵感的催化剂,需要golang后端开发人员
2015/04/06 22:50:28 第 3 个帖子的标题: 创业团队缺后端开发
2015/04/06 22:50:28 第 2 个帖子的标题: Tango v0.4版本发布,带来统一高性能的新路由
2015/04/06 22:50:28 第 1 个帖子的标题: 问个加载包的问题

除了获取节点的文本内容,还可以获取节点的属性值、判断是否有某个 class 等,gopher 们可以自己试验。

【未完待续。。。】

222014
 

1、cron 表达式的基本格式

用过 linux 的应该对 cron 有所了解。linux 中可以通过 crontab -e 来配置定时任务。不过,linux 中的 cron 只能精确到分钟。而我们这里要讨论的 Go 实现的 cron 可以精确到秒,除了这点比较大的区别外,cron 表达式的基本语法是类似的。(如果使用过 Java 中的 Quartz,对 cron 表达式应该比较了解,而且它和这里我们将要讨论的 Go 版 cron 很像,也都精确到秒)

cron(计划任务),顾名思义,按照约定的时间,定时的执行特定的任务(job)。cron 表达式 表达了这种约定。

cron 表达式代表了一个时间集合,使用 6 个空格分隔的字段表示。

字段名 是否必须 允许的值 允许的特定字符
秒(Seconds) 0-59
* / , -
分(Minutes) 0-59
* / , -
时(Hours) 0-23
* / , -
日(Day of month) 1-31
* / , – ?
月(Month) 1-12 or JAN-DEC
* / , -
星期(Day of week) 0-6 or SUM-SAT
* / , – ?

注:
1)月(Month)和星期(Day of week)字段的值不区分大小写,如:SUN、Sun 和 sun 是一样的。
2)星期
(Day of week)字段如果没提供,相当于是 *

2、特殊字符说明

1)星号(*)

表示 cron 表达式能匹配该字段的所有值。如在第5个字段使用星号(month),表示每个月

2)斜线(/)

表示增长间隔,如第1个字段(minutes) 值是 3-59/15,表示每小时的第3分钟开始执行一次,之后每隔 15 分钟执行一次(即 3、18、33、48 这些时间点执行),这里也可以表示为:3/15

3)逗号(,)

用于枚举值,如第6个字段值是 MON,WED,FRI,表示 星期一、三、五 执行

4)连字号(-)

表示一个范围,如第3个字段的值为 9-17 表示 9am 到 5pm 直接每个小时(包括9和17)

5)问号(?)

只用于 日(Day of month) 和 星期(Day of week),表示不指定值,可以用于代替 *

3、主要类型或接口说明

1)Cron:包含一系列要执行的实体;支持暂停【stop】;添加实体等

type Cron struct {
    entries  []*Entry
    stop     chan struct{}   // 控制 Cron 实例暂停
    add      chan *Entry     // 当 Cron 已经运行了,增加新的 Entity 是通过 add 这个 channel 实现的
    snapshot chan []*Entry   // 获取当前所有 entity 的快照
    running  bool            // 当已经运行时为true;否则为false
}

注意,Cron 结构没有导出任何成员。

注意:有一个成员 stop,类型是 struct{},即空结构体。

2)Entry:调度实体

type Entry struct {
    // The schedule on which this job should be run.
    // 负责调度当前 Entity 中的 Job 执行
    Schedule Schedule

    // The next time the job will run. This is the zero time if Cron has not been
    // started or this entry's schedule is unsatisfiable
    // Job 下一次执行的时间
    Next time.Time

    // The last time this job was run. This is the zero time if the job has never
    // been run.
    // 上一次执行时间
    Prev time.Time

    // The Job to run.
    // 要执行的 Job
    Job Job
}

3)Job:每一个实体包含一个需要运行的Job

这是一个接口,只有一个方法:run

type Job interface {
    Run()
}

由于 Entity 中需要 Job 类型,因此,我们希望定期运行的任务,就需要实现 Job 接口。同时,由于 Job 接口只有一个无参数无返回值的方法,为了使用方便,作者提供了一个类型:

type FuncJob func()

它通过简单的实现 Run() 方法来实现 Job 接口:

func (f FuncJob) Run() { f() }

这样,任何无参数无返回值的函数,通过强制类型转换为 FuncJob,就可以当作 Job 来使用了,AddFunc 方法 就是这么做的。

4)Schedule:每个实体包含一个调度器(Schedule)

负责调度 Job 的执行。它也是一个接口。

type Schedule interface {
    // Return the next activation time, later than the given time.
    // Next is invoked initially, and then each time the job is run.
    // 返回同一 Entity 中的 Job 下一次执行的时间
    Next(time.Time) time.Time
}

Schedule 的具体实现通过解析 Cron 表达式得到。

库中提供了 Schedule 的两个具体实现,分别是 SpecSchedule 和 ConstantDelaySchedule。

① SpecSchedule

type SpecSchedule struct {
    Second, Minute, Hour, Dom, Month, Dow uint64
}

从开始介绍的 Cron 表达式可以容易得知各个字段的意思,同时,对各种表达式的解析也会最终得到一个 SpecSchedule 的实例。库中的 Parse 返回的其实就是 SpecSchedule 的实例(当然也就实现了 Schedule 接口)。

② ConstantDelaySchedule

type ConstantDelaySchedule struct {
    Delay time.Duration // 循环的时间间隔
}

这是一个简单的循环调度器,如:每 5 分钟。注意,最小单位是秒,不能比秒还小,比如 毫秒。

通过 Every 函数可以获取该类型的实例,如:

constDelaySchedule := Every(5e9)

得到的是一个每 5 秒执行一次的调度器。

4、主要实例化方法

1) 函数

① 实例化 Cron

func New() *Cron {
    return &Cron{
        entries:  nil,
        add:      make(chan *Entry),
        stop:     make(chan struct{}),
        snapshot: make(chan []*Entry),
        running:  false,
    }
}

可见实例化时,成员使用的基本是默认值;

② 解析 Cron 表达式

func Parse(spec string) (_ Schedule, err error)

spec 可以是:

  • Full crontab specs, e.g. “* * * * * ?”
  • Descriptors, e.g. “@midnight”, “@every 1h30m”

② 成员方法

// 将 job 加入 Cron 中
// 如上所述,该方法只是简单的通过 FuncJob 类型强制转换 cmd,然后调用 AddJob 方法
func (c *Cron) AddFunc(spec string, cmd func()) error

// 将 job 加入 Cron 中
// 通过 Parse 函数解析 cron 表达式 spec 的到调度器实例(Schedule),之后调用 c.Schedule 方法
func (c *Cron) AddJob(spec string, cmd Job) error

// 获取当前 Cron 总所有 Entities 的快照
func (c *Cron) Entries() []*Entry

// 通过两个参数实例化一个 Entity,然后加入当前 Cron 中
// 注意:如果当前 Cron 未运行,则直接将该 entity 加入 Cron 中;
// 否则,通过 add 这个成员 channel 将 entity 加入正在运行的 Cron 中
func (c *Cron) Schedule(schedule Schedule, cmd Job)

// 新启动一个 goroutine 运行当前 Cron
func (c *Cron) Start()

// 通过给 stop 成员发送一个 struct{}{} 来停止当前 Cron,同时将 running 置为 false
// 从这里知道,stop 只是通知 Cron 停止,因此往 channel 发一个值即可,而不关心值是多少
// 所以,成员 stop 定义为空 struct
func (c *Cron) Stop()

5、使用示例

package main

import (
    "github.com/robfig/cron"
    "log"
)

func main() {
    i := 0
    c := cron.New()
    spec := "*/5 * * * * ?"
    c.AddFunc(spec, func() {
        i++
        log.Println("cron running:", i)
    })
    c.Start()

    select{}
}

这是一个简单示例。

输出类似这样:

2014/02/22 21:23:40 cron running: 1
2014/02/22 21:23:45 cron running: 2
2014/02/22 21:23:50 cron running: 3
2014/02/22 21:23:55 cron running: 4
2014/02/22 21:24:00 cron running: 5

可见 cron 的使用还是挺简单的。

6、Go 版 cron 源码地址

查看源码