# 摘要
版本格式：`主版本号.次版本号.修订号`，版本号递增规则如下：

1. 主版本号：当你做了不兼容的 API 修改，
2. 次版本号：当你做了向下兼容的功能性新增，
3. 修订号：当你做了向下兼容的问题修正。
4. 先行版本号及版本编译信息可以加到“`主版本号.次版本号.修订号`”的后面，作为延伸。





# 简介

在软件管理的领域里存在着被称作“依赖地狱”的死亡之谷，系统规模越大，加入的包越多，你就越有可能在未来的某一天发现自己已深陷绝望之中。

在依赖高的系统中发布新版本包可能很快会成为噩梦。如果依赖关系过高，可能面临版本控制被锁死的风险（必须对每一个依赖包改版才能完成某次升级）。而如果依赖关系过于松散，又将无法避免版本的混乱（假设兼容于未来的多个版本已超出了合理数量）。当你项目的进展因为版本依赖被锁死或版本混乱变得不够简便和可靠，就意味着你正处于依赖地狱之中。

作为这个问题的解决方案之一，我提议用一组简单的规则及条件来约束版本号的配置和增长。这些规则是根据（但不局限于）已经被各种封闭、开放源码软件所广泛使用的惯例所设计。为了让这套理论运作，你必须先有定义好的公共 API。这可能包括文档或代码的强制要求。无论如何，这套 API 的清楚明了是十分重要的。一旦你定义了公共 API，你就可以透过修改相应的版本号来向大家说明你的修改。考虑使用这样的版本号格式：`X.Y.Z`（`主版本号.次版本号.修订号`）**修复问题但不影响 API 时，递增修订号；API 保持向下兼容的新增及修改时，递增次版本号；进行不向下兼容的修改时，递增主版本号**。

我称这套系统为“**语义化的版本控制**”，在这套约定下，版本号及其更新方式包含了相邻版本间的底层代码和修改内容的信息。

# 语义化版本控制规范（`SemVer`）

以下关键词 `MUST`、`MUST NOT`、`REQUIRED`、`SHALL`、`SHALL NOT`、`SHOULD`、`SHOULD NOT`、 `RECOMMENDED`、`MAY`、`OPTIONAL` 依照 [RFC 2119](https://www.rfc-editor.org/info/rfc2119) 的叙述解读。

1. 使用语义化版本控制的软件必须（MUST）定义公共 API。该 API 可以在代码中被定义或出现于严谨的文档内。无论何种形式都应该力求精确且完整。
2. 标准的版本号必须（MUST）采用 `X.Y.Z` 的格式，其中 `X`、`Y` 和 `Z` 为**非负的整数**，且禁止（MUST NOT）在**数字前方补零**。`X` 是主版本号、`Y` 是次版本号、而 `Z` 为修订号。**每个元素必须（MUST）以数值来递增**。例如：`1.9.1` -> `1.10.0` -> `1.11.0`。
3. 标记版本号的软件发行后，禁止（MUST NOT）改变该版本软件的内容。任何修改都必须（MUST）以新版本发行。
4. 主版本号为零（`0.y.z`）的软件处于开发初始阶段，一切都可能随时被改变。这样的公共 API **不应该被视为稳定版**。
5. `1.0.0` 的版本号用于界定公共 API 的形成。这一版本之后所有的版本号更新都基于公共 API 及其修改内容。
6. 修订号 `Z`（`x.y.Z | x > 0`）必须（MUST）在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果而进行的内部修改。
7. 次版本号 `Y`（`x.Y.z | x > 0`）必须（MUST）在有向下兼容的新功能出现时递增。在任何公共 API 的功能被标记为弃用时也必须（MUST）递增。也可以（MAY）在内部程序有大量新功能或改进被加入时递增，其中可以（MAY）包括修订级别的改变。每当次版本号递增时，修订号必须（MUST）归零。
8. 主版本号 `X`（`X.y.z | X > 0`）必须（MUST）在有任何不兼容的修改被加入公共 API 时递增。其中可以（MAY）包括次版本号及修订级别的改变。每当主版本号递增时，次版本号和修订号必须（MUST）归零。
9. 先行版本号可以（MAY）被标注在修订版之后，先加上一个**连接号**再加上一连串**以句点分隔的标识符**来修饰。标识符必须（MUST）由 `ASCII` 字母数字和连接号 `[0-9A-Za-z-]` 组成，且禁止（MUST NOT）留白。**数字型的标识符禁止（MUST NOT）在前方补零**。先行版的优先级低于相关联的标准版本。被标上先行版本号则表示这个版本并非稳定而且可能无法满足预期的兼容性需求。范例：`1.0.0-alpha`、`1.0.0-alpha.1`、`1.0.0-0.3.7`、`1.0.0-x.7.z.92`。
10. 版本编译信息可以（MAY）被标注在修订版或先行版本号之后，先加上一个**加号**再加上一连串**以句点分隔的标识符**来修饰。标识符必须（MUST）由 `ASCII` 字母数字和连接号 `[0-9A-Za-z-]` 组成，且禁止（MUST NOT）留白。当**判断版本的优先层级时，版本编译信息可（SHOULD）被忽略**。因此当两个版本只有在版本编译信息有差别时，属于相同的优先层级。范例：`1.0.0-alpha+001`、`1.0.0+20130313144700`、`1.0.0-beta+exp.sha.5114f85`。
11. 版本的优先层级指的是不同版本在排序时如何比较。
    1. 判断优先层级时，必须（MUST）把版本依序拆分为`主版本号`、`次版本号`、`修订号`及`先行版本号`后进行比较（版本编译信息不在这份比较的列表中）。
    2. 由左到右依序比较每个标识符，第一个差异值用来决定优先层级：`主版本号`、`次版本号`及`修订号`以**数值比较**。例如：`1.0.0` < `2.0.0` < `2.1.0` < `2.1.1`。
    3. 当`主版本号`、`次版本号`及`修订号`都相同时，改以**优先层级比较低的先行版本号决定**。例如：`1.0.0-alpha` < `1.0.0`。
    4. 有相同`主版本号`、`次版本号`及`修订号`的两个先行版本号，其优先层级必须（MUST）透过**由左到右的每个被句点分隔的标识符来比较，直到找到一个差异值后决定**：
        1. 只有数字的标识符以数值高低比较。
        2. 有字母或连接号时则逐字以 `ASCII` 的排序来比较。
        3. 数字的标识符比非数字的标识符优先层级低。
        4. 若开头的标识符都相同时，栏位比较多的先行版本号优先层级比较高。
    
    例如：`1.0.0-alpha` < `1.0.0-alpha.1` < `1.0.0-alpha.beta` < `1.0.0-beta` < `1.0.0-beta.2` < `1.0.0-beta.11` < `1.0.0-rc.1` < `1.0.0`。

# 合法语义化版本的巴科斯范式语法

```
<valid semver> ::= <version core>
                 | <version core> "-" <pre-release>
                 | <version core> "+" <build>
                 | <version core> "-" <pre-release> "+" <build>

<version core> ::= <major> "." <minor> "." <patch>

<major> ::= <numeric identifier>

<minor> ::= <numeric identifier>

<patch> ::= <numeric identifier>

<pre-release> ::= <dot-separated pre-release identifiers>

<dot-separated pre-release identifiers> ::= <pre-release identifier>
                                          | <pre-release identifier> "." <dot-separated pre-release identifiers>

<build> ::= <dot-separated build identifiers>

<dot-separated build identifiers> ::= <build identifier>
                                    | <build identifier> "." <dot-separated build identifiers>

<pre-release identifier> ::= <alphanumeric identifier>
                           | <numeric identifier>

<build identifier> ::= <alphanumeric identifier>
                     | <digits>

<alphanumeric identifier> ::= <non-digit>
                            | <non-digit> <identifier characters>
                            | <identifier characters> <non-digit>
                            | <identifier characters> <non-digit> <identifier characters>

<numeric identifier> ::= "0"
                       | <positive digit>
                       | <positive digit> <digits>

<identifier characters> ::= <identifier character>
                          | <identifier character> <identifier characters>

<identifier character> ::= <digit>
                         | <non-digit>

<non-digit> ::= <letter>
              | "-"

<digits> ::= <digit>
           | <digit> <digits>

<digit> ::= "0"
          | <positive digit>

<positive digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

<letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J"
           | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T"
           | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d"
           | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n"
           | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"
           | "y" | "z"
```

# 为什么要使用语义化的版本控制？

这并不是一个新的或者革命性的想法。实际上，你可能已经在做一些近似的事情了。问题在于只是“近似”还不够。如果没有某个正式的规范可循，版本号对于依赖的管理并无实质意义。将上述的想法命名并给予清楚的定义，让你对软件使用者传达意向变得容易。一旦这些意向变得清楚，弹性（但又不会太弹性）的依赖规范就能达成。

举个简单的例子就可以展示语义化的版本控制如何让依赖地狱成为过去。假设有个名为“救火车”的函数库，它需要另一个名为“梯子”并已经有使用语义化版本控制的包。当救火车创建时，梯子的版本号为 `3.1.0`。因为救火车使用了一些版本 `3.1.0` 所新增的功能，你可以放心地指定依赖于梯子的版本号大于等于 `3.1.0` 但小于 `4.0.0`。这样，当梯子版本 `3.1.1` 和 `3.2.0` 发布时，你可以将直接它们纳入你的包管理系统，因为它们能与原有依赖的软件兼容。

作为一位负责任的开发者，你理当确保每次包升级的运作与版本号的表述一致。现实世界是复杂的，我们除了提高警觉外能做的不多。你所能做的就是让语义化的版本控制为你提供一个健全的方式来发行以及升级包，而无需推出新的依赖包，节省你的时间及烦恼。

如果你对此认同，希望立即开始使用语义化版本控制，你只需声明你的函数库正在使用它并遵循这些规则就可以了。请在你的 `README` 文件中保留此页链接，让别人也知道这些规则并从中受益。

# FAQ

## 在 0.y.z 初始开发阶段，我该如何进行版本控制？

最简单的做法是以 `0.1.0` 作为你的初始化开发版本，并在后续的每次发行时递增次版本号。

## 如何判断发布 1.0.0 版本的时机？

当你的软件被用于正式环境，它应该已经达到了 `1.0.0` 版。如果你已经有个稳定的 API 被使用者依赖，也会是 `1.0.0` 版。如果你很担心向下兼容的问题，也应该算是 `1.0.0` 版了。

## 这不会阻碍快速开发和迭代吗？

主版本号为零的时候就是为了做快速开发。如果你每天都在改变 API，那么你应该仍在主版本号为零的阶段（`0.y.z`），或是正在下个主版本的独立开发分支中。

## 对于公共 API，若即使是最小但不向下兼容的改变都需要产生新的主版本号，岂不是很快就达到 42.0.0 版？

这是开发的责任感和前瞻性的问题。不兼容的改变不应该轻易被加入到有许多依赖代码的软件中。升级所付出的代价可能是巨大的。要递增主版本号来发行不兼容的改版，意味着你必须为这些改变所带来的影响深思熟虑，并且评估所涉及的成本及效益比。

## 为整个公共 API 写文档太费事了！

为供他人使用的软件编写适当的文档，是你作为一名专业开发者应尽的职责。保持项目高效的一个非常重要的部分是掌控软件的复杂度，如果没有人知道如何使用你的软件或不知道哪些函数的调用是可靠的，要掌控复杂度会是困难的。长远来看，使用语义化版本控制以及对于公共 API 有良好规范的坚持，可以让每个人及每件事都运行顺畅。

## 万一不小心把一个不兼容的改版当成了次版本号发行了该怎么办？

一旦发现自己破坏了语义化版本控制的规范，就要修正这个问题，并发行一个新的次版本号来更正这个问题并且恢复向下兼容。即使是这种情况，也不能去修改已发行的版本。可以的话，将有问题的版本号记录到文档中，告诉使用者问题所在，让他们能够意识到这是有问题的版本。

## 如果我更新了自己的依赖但没有改变公共 API 该怎么办？

由于没有影响到公共 API，这可以被认定是兼容的。若某个软件和你的包有共同依赖，则它会有自己的依赖规范，作者也会告知可能的冲突。要判断改版是属于修订等级或是次版等级，是依据你更新的依赖关系是为了修复问题或是加入新功能。对于后者，我经常会预期伴随着更多的代码，这显然会是一个次版本号级别的递增。

## 如果我变更了公共 API 但无意中未遵循版本号的改动怎么办呢？（意即在修订等级的发布中，误将重大且不兼容的改变加到代码之中）

自行做最佳的判断。如果你有庞大的使用者群在依照公共 API 的意图而变更行为后会大受影响，那么最好做一次主版本的发布，即使严格来说这个修复仅是修订等级的发布。记住， 语义化的版本控制就是透过版本号的改变来传达意义。若这些改变对你的使用者是重要的，那就透过版本号来向他们说明。

## 我该如何处理即将弃用的功能？

弃用现存的功能是软件开发中的家常便饭，也通常是向前发展所必须的。当你弃用部分公共 API 时，你应该做两件事：
1. 更新你的文档让使用者知道这个改变
2. 在适当的时机将弃用的功能透过新的次版本号发布。
在新的主版本完全移除弃用功能前，至少要有一个次版本包含这个弃用信息，这样使用者才能平顺地转移到新版 API。

## 语义化版本对于版本的字符串长度是否有限制呢？

没有，请自行做适当的判断。举例来说，长到 `255` 个字符的版本已过度夸张。再者，特定的系统对于字符串长度可能会有他们自己的限制。

## “v1.2.3” 是一个语义化版本号吗？

“`v1.2.3`” 并不是一个语义化的版本号。但是，在语义化版本号之前增加前缀 “v” 是用来表示版本号的常用做法。在版本控制系统中，将 “`version`” 缩写为 “`v`” 是很常见的。比如：`git tag v1.2.3 -m "Release version 1.2.3"` 中，“`v1.2.3`” 表示标签名称，而 “`1.2.3`” 是语义化版本号。

## 是否有推荐的正则表达式用以检查语义化版本号的正确性？

有两个推荐的正则表达式。第一个用于支持按组名称提取的语言（`PCRE`[Perl 兼容正则表达式，比如 `Perl`、`PHP` 和 `R`]、`Python` 和 `Go`）。

参见：[https://regex101.com/r/Ly7O1x/3/](https://regex101.com/r/Ly7O1x/3/)

```
^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
```

第二个用于支持按编号提取的语言（与第一个对应的提取项按顺序分别为：`major`、`minor`、`patch`、`prerelease`、`buildmetadata`）。主要包括 `ECMA Script（JavaScript）`、`PCRE`（`Perl` 兼容正则表达式，比如 `Perl`、`PHP` 和 `R`）、`Python` 和 `Go`。 参见：[https://regex101.com/r/vkijKf/1/](https://regex101.com/r/vkijKf/1/)

```
^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
```

# 关于

语义化版本控制的规范是由 `Gravatars` 创办者兼 `GitHub` 共同创办者 [Tom Preston-Werner](http://tom.preston-werner.com/) 所建立。

如果您有任何建议，请到 [GitHub 上提出您的问题](https://github.com/semver/semver/issues)。

# 许可证

[知识共享 署名 3.0 (CC BY 3.0)](http://creativecommons.org/licenses/by/3.0/)

原文地址：[https://semver.org/lang/zh-CN/](https://semver.org/lang/zh-CN/)

【转】语义化版本 2.0.0

# 第一部分 概述

`validator` 是 Go 语言中的一个库，用于对结构体进行数据验证，常用于 Web 开发和表单数据的校验。它提供了灵活且易于扩展的功能，可以帮助开发者轻松地验证用户输入的数据是否符合预定的规则。该库遵循声明式验证的方式，能够通过标签（tag）来指定每个字段的验证规则。`validator` 可以广泛应用于表单验证、API 参数验证、用户输入验证等场景。




项目地址：[https://github.com/go-playground/validator](https://github.com/go-playground/validator)

## 1.1 主要功能和作用：
- **字段验证**：可以为结构体中的字段添加验证规则（通过标签），例如，验证是否为空、是否为有效的电子邮件地址、是否符合特定的最小或最大长度等。
- **自定义验证**：支持自定义验证规则，可以通过注册自定义函数来扩展验证逻辑。
- **多种常见验证器**：提供了多种内置的常见验证器，如 `required`、`min`、`max`、`email`、`len` 等，满足大多数验证需求。
- **链式验证**：支持多个验证规则叠加使用，允许开发者为字段指定多个验证条件，验证规则之间通过 `,` 进行分隔。
- **嵌套验证**：支持结构体嵌套，可以对嵌套结构体中的字段进行验证，并且能够递归地进行验证。
- **错误信息**：当验证失败时，`validator` 会返回具体的错误信息，帮助开发者快速定位问题。

## 1.2 常见使用场景
-  **Web 表单验证**：在 Web 开发中，用户提交的表单数据需要验证是否合法，`validator` 可以帮助开发者轻松实现表单字段验证（如用户名、密码、电子邮件等）。
-  **API 参数验证**：对于接收到的请求参数，`validator` 可以用于验证 API 请求的数据是否符合预期的格式和要求。
-  **用户输入验证**：用于验证用户在注册、登录或修改个人信息时提交的数据，确保数据的有效性和安全性。
-  **数据库字段验证**：可以对数据库模型的字段进行验证，确保数据符合要求再进行数据库操作。

# 第二部分 常用操作

## 2.1 安装 `validator` 库

```bash
go get github.com/go-playground/validator/v10
```

## 2.2 简单的字段验证

使用 `validator` 库最常见的方式是给结构体字段添加标签，并使用 `Validate` 方法进行验证：

```go
package main

import (
    "fmt"
    "github.com/go-playground/validator/v10"
)

type User struct {
    Name  string `json:"name" validate:"required,min=3,max=100"`
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"gte=18"`
}

func main() {
    user := &User{
        Name:  "John",
        Email: "john.doe@example.com",
        Age:   25,
    }

    validate := validator.New()

    // 验证结构体
    err := validate.Struct(user)
    if err != nil {
        // 如果验证失败，打印错误信息
        for _, err := range err.(validator.ValidationErrors) {
            fmt.Println("验证失败:", err)
        }
    } else {
        fmt.Println("验证通过")
    }
}
```

在上述代码中，`User` 结构体的 `Name`、`Email` 和 `Age` 字段上都添加了验证标签。
- `validate:"required"` 表示该字段为必填
- `min=3` 和 `max=100` 分别表示字符串的最小和最大长度
- `gte=18` 表示年龄必须大于或等于 18

## 2.3 常见验证标签

`validator` 提供了许多常用的验证标签，用于验证字段是否符合特定要求。以下是一些常见的验证标签：
- `required`：字段不能为空
- `min=X`：验证字段的最小值（适用于数字、字符串等）
- `max=X`：验证字段的最大值
- `len=X`：验证字段的长度
- `gte=X`：验证字段是否大于等于 X
- `lte=X`：验证字段是否小于等于 X
- `url`：验证字段是否为有效的 URL
- `uuid`：验证字段是否为有效的 UUID

例如，验证邮箱字段和年龄字段：

```go
type User struct {
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"gte=18,lte=100"`
}
```

## 2.4 自定义验证函数

`validator` 允许开发者注册自定义的验证规则，可以通过 `RegisterValidation` 方法来实现：

```go
package main

import (
    "fmt"
    "github.com/go-playground/validator/v10"
)

func main() {
    validate := validator.New()

    // 注册自定义验证函数
    validate.RegisterValidation("even", func(fl validator.FieldLevel) bool {
        return fl.Field().Int()%2 == 0
    })

    type Product struct {
        Code int `json:"code" validate:"even"`
    }

    product := Product{
        Code: 123,
    }

    err := validate.Struct(product)
    if err != nil {
        fmt.Println("验证失败:", err)
    } else {
        fmt.Println("验证通过")
    }
}
```

在这个例子中，我们自定义了一个验证函数 `even`，它检查一个字段值是否为偶数。我们将其应用到 `Product` 结构体的 `Code` 字段上。

## 2.5 验证嵌套结构体

`validator` 支持对嵌套结构体进行递归验证。如果结构体字段本身是一个结构体，也会进行验证：

```go
package main

import (
    "fmt"
    "github.com/go-playground/validator/v10"
)

type Address struct {
    Street string `validate:"required"`
    City   string `validate:"required"`
}

type User struct {
    Name    string  `validate:"required"`
    Address Address `validate:"required"`
}

func main() {
    validate := validator.New()

    user := &User{
        Name: "John",
        Address: Address{
            Street: "",
            City:   "New York",
        },
    }

    err := validate.Struct(user)
    if err != nil {
        fmt.Println("验证失败:", err)
    } else {
        fmt.Println("验证通过")
    }
}
```

在这个例子中，`User` 结构体嵌套了 `Address` 结构体，并且我们为 `Address` 和 `User` 字段都设置了验证规则。当 `Street` 字段为空时，验证会失败。

## 2.6 错误信息处理

`validator` 会返回详细的验证错误信息，可以通过 `ValidationErrors` 类型获取验证失败的字段和错误信息：

```go
err := validate.Struct(user)
if err != nil {
    for _, err := range err.(validator.ValidationErrors) {
        fmt.Printf("字段 %s 验证失败: %s\n", err.StructField(), err.Tag())
    }
}
```

## 2.7 批量验证

可以一次性验证多个结构体或多个字段，`validator` 会返回一个包含所有错误的列表：

```go
err := validate.StructMany([]interface{}{user1, user2, user3})
```

[GO每日一库]validator

# 第一部分 概述

`cron` 是 Go 语言中一个非常流行的定时任务库，提供了一种类似于 Linux 系统 `cron` 定时任务的方式来定期执行任务。它允许开发者设定特定的时间规则（如每小时、每天、每周等）来自动执行代码。`cron` 库为 Go 提供了定时调度的功能，广泛应用于任务自动化、定时报告生成、周期性数据抓取等场景。



项目地址：[https://github.com/robfig/cron](https://github.com/robfig/cron)

## 1.1 主要功能和作用

 - **定时任务调度**: `cron` 库允许在 Go 应用中设定周期性任务，任务按照指定的时间表自动触发和执行。
 - **Cron 表达式支持**: 支持类似 Unix/Linux 系统中的 `cron` 表达式，可以方便地设置任务执行的时间和频率（如每分钟、每小时、每天等）。
 - **高精度和可靠性**：定时任务的执行非常精确，可以处理高精度的定时任务，确保任务按照预期执行。
 - **支持后台执行任务**：可以在后台运行定时任务，而不会阻塞主程序的执行，支持并发执行多个定时任务。
 - **支持多任务调度**：可以同时调度多个任务，灵活管理不同的定时任务。
 - **错误处理和日志管理**：支持任务执行中的错误处理和日志记录，方便监控和调试。

## 1.2 常见使用场景

 - **定时数据抓取**：定期从网站或 API 获取数据，比如定时爬取网页、获取天气信息、金融数据等。
 - **定时报告生成**：自动生成并发送报告（如统计报告、日志分析报告等），通常按天、按周、按月执行。
 - **定时清理任务**：定时清理缓存、删除过期文件、清理数据库中的过期数据等。
 - **定时备份**：定期备份数据库或重要文件，确保数据安全。
 - **定时任务通知**：例如定时发送通知或提醒（如提醒用户每天的待办事项、活动等）。
 - **定时系统监控**：定时检查系统状态或执行健康检查，确保系统的稳定性。

# 第二部分 常用操作

## 2.1 创建和启动 Cron 调度器

创建一个 `cron` 调度器，并启动它：

```go
import (
   "fmt"
   "github.com/robfig/cron/v3"
)

func main() {
   c := cron.New()  // 创建一个新的调度器
   c.Start()  // 启动调度器
}
```

## 2.2 添加定时任务

使用 `AddFunc` 方法向调度器中添加定时任务

```go
c.AddFunc("@hourly", func() {
    fmt.Println("每小时执行一次的任务")
})

c.AddFunc("@daily", func() {
    fmt.Println("每天执行一次的任务")
})
```

## 2.3 使用 Cron 表达式添加定时任务

`cron` 库支持标准的 Cron 表达式，可以指定复杂的时间规则。下面是一个每分钟执行一次的任务

```go
c.AddFunc("* * * * *", func() {
    fmt.Println("每分钟执行一次的任务")
})
```


:::info{title="相关信息"}
表达式的格式是：`分 时 日 月 星期`，其中：`*` 表示任意值，例如：`"0 12 * * *"` 表示每天中午12点执行一次任务。
:::


## 2.4 任务管理

通过返回的 ID 来管理任务，比如删除任务或暂停任务：

 ```go
id, err := c.AddFunc("@every 5s", func() {
    fmt.Println("每 5 秒执行一次")
})

// 删除指定 ID 的任务
c.Remove(id)
```

[GO每日一库]cron

# 第一部分 概述

本文主要介绍使用`openssl`生成自签名证书的步骤，留作备忘，便于以后查看。




# 第二部分 生成步骤

## 2.1 创建 CA 私钥

```bash
openssl genrsa -out ca.key 4096
```

## 2.2 创建 CA 证书（自签）

```bash
openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt -subj "/C=CN/ST=Beijing/L=Beijing/O=MyCompany/OU=IT/CN=MyRootCA"
```


:::info{title="相关信息"}

在生成证书时 `-subj` 用于指定证书的 **主题信息 (Distinguished Name, DN)**。常见格式：

```bash
-subj "/C=CN/ST=Beijing/L=Beijing/O=MyCompany/OU=IT/CN=zabbix-server"
```

其中各字段含义如下：

| 字段   | 含义                                   | 示例                                 |
| :----: | :------------------------------------: | :----------------------------------: |
| `C`  | Country，国家代码（ISO 3166 两位字母）          | `CN`（中国）、`US`（美国）                  |
| `ST` | State，州或省                            | `Beijing`                          |
| `L`  | Locality，城市                          | `Beijing`                          |
| `O`  | Organization，组织名称                    | `MyCompany`                        |
| `OU` | Organizational Unit，组织单位             | `IT`                               |
| `CN` | Common Name，常用名 | `server` |

:::


## 2.3 创建私钥

```bash
openssl genrsa -out server.key 2048
```

## 2.4 创建证书请求（CSR）

```bash
openssl req -new -key server.key -out server.csr -subj "/C=CN/ST=Beijing/L=Beijing/O=MyCompany/OU=Zabbix/CN=zabbix-server"
```

## 2.5 用 CA 签发

```bash
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -sha256
```

## 2.6 常用转换

### 2.6.1 转换为p12格式

```bash
openssl pkcs12 -export -out agent.p12 -inkey agent.key -in agent.crt -certfile ca.crt -name "agent" -password pass:agentpass
```

### 2.6.2 导入JKS

```bash
keytool -import -trustcacerts -alias myca -file ca.crt -keystore truststore.jks -storepass trustpass
```

使用openssl生成自签名证书

# 第一部分 概述
## 1.1 WinRM 是什么？能干什么？
- **`WinRM`**（Windows Remote Management） 是微软实现的一套远程管理协议，基于 WS-Management（WS-MAN） 标准，采用 SOAP/HTTP(S) 作为传输载体。
- **主要用途**：在远程 Windows 主机上执行命令、运行脚本、收集信息、管理配置、以及作为 PowerShell Remoting（PowerShell 远程） 的底层传输通道。
- **优点**：与 Windows 生态深度集成、支持多种认证（Kerberos/NTLM/证书/Basic 等）、可以用于脚本化与编程调用。
- **常见场景**：自动化运维、批量执行命令、远程故障诊断、配置管理与监控集成。





## 1.2 基本概念与术语
- **WS-Management / WS-MAN**：一个基于 Web 服务（SOAP/XML）的标准，定义了发现、枚举、读取/写入资源、执行远程命令等操作。
- **Listener（监听器）**：服务器端绑定的端点，常见有 HTTP（默认端口 5985）和 HTTPS（默认端口 5986）两类监听器。
- **Shell / Session**：WinRM 提供“远程 Shell”模型，客户端可以创建一个 shell/session 在服务器上，后续在该 session 中执行多个命令（避免每次建立握手）。
- **Resource URI**：通过 URI 指定要操作的资源（例如 shell、操作系统信息等），WS-MAN 操作通常对资源 URI 发起 SOAP 请求。
- **操作类型**：Identify、Enumerate、Pull、Create（如创建 shell）、Invoke（执行操作/命令）等。
- **认证/委派**：Kerberos（域内最佳）、NTLM（常见本地认证）、证书（HTTPS）、Basic（仅在 HTTPS 下使用或测试）。

## 1.3 工作原理
- **建立连接**：客户端向目标主机的 `WinRM` 监听器发送 `HTTP/HTTPS` 的 `SOAP` 请求（Identify/Authenticate）。
- **认证与授权**：服务器根据请求的认证信息（Kerberos/NTLM/证书等）进行验证，决定是否允许后续操作。
- **创建 Session/Shell**：若需要执行多个命令，可先 `Creat`e 一个 `shell/session`（持久化上下文），随后通过该 `session Invoke` 命令。
- **执行与返回**：服务器在 `shell` 中执行命令，将标准输出/错误通过 `SOAP` 消息分片返回（可能会有流式或分块）。
- **结束/清理**：执行完成后可以 `Delete shell`，释放资源。

## 1.4 常见的交互方式与工具

### 1.4.1 Windows 自带工具
- **Enable-PSRemoting -Force（PowerShell）**：启用 PowerShell 远程和 WinRM 的常用配置（创建 listener、打开防火墙规则等）。
- **winrm quickconfig**：快速配置 WinRM 服务（创建 listener、启用服务、打开防火墙规则）。
- **Test-WSMan -ComputerName `<host>`**：测试目标主机 WinRM 服务是否可达并查看返回信息。
- **Enter-PSSession -ComputerName `<host>` -Credential `<cred>`**：交互式远程会话（像 SSH 的 shell）。
- **Invoke-Command -ComputerName `<host>` -ScriptBlock { ... }**：在远程主机执行命令或脚本（可在多主机上并行）。
- **New-PSSession / Invoke-Command -Session**：创建持久会话并复用，提高性能。

### 1.4.2 命令行 WinRM 客户端

- **winrs**：Windows 的 WinRM 命令行工具（可执行远程命令；功能相对简单）。
- **winrm**：配置与查询 WinRM 服务的命令行工具（例如 winrm e winrm/config/listener 列出监听器）。

### 1.4.3 编程库与第三方（常用于自动化/集成）
这些库一般封装了 WS-MAN 的 SOAP 细节，使用更方便。

- **Python**：pywinrm。
- **Java**：winrm4j 等开源库（用于在 Java 应用中远程执行命令）。
- **.NET / PowerShell SDK**：用于深度集成与管理

## 1.5 WinRM 支持的认证方式

|认证方式|特点|安全性|使用场景|
|:--:|:--:|:--:|:--:|
|Basic|用户名和密码以明文 Base64 发送|低（必须配合 HTTPS，否则等于明文传输）|简单快速，测试环境、自签名证书场景|
|Digest|使用质询-响应机制，密码不会明文传输|中（比 Basic 安全，但已过时）|很少使用，兼容性差|
|NTLM|Windows 内置的挑战/响应协议，不需要明文密码|中（比 Basic 强，但存在中继攻击风险）|域外或工作组环境常用|
|Kerberos|基于票据的认证（需 KDC/AD 域环境），无需发送密码|高（企业常用，强安全性）|企业域环境，大规模管理|
|CredSSP|支持凭据委派（客户端凭据转发到远端执行）|高（可做二次跳转），但存在凭据泄露风险|需要跨跳远程执行时|
|Negotiate|Windows 自动选择 Kerberos 或 NTLM|取决于底层选择|一般推荐（兼容性好）|

### 1.5.1 详细说明
- **Basic**
    - 优点：实现简单，跨平台容易（Linux/Java/非域环境也能用）。
    - 缺点：在 HTTP 下几乎等于明文传输，必须配合 HTTPS 才安全。
    - 适用：临时、测试、非域环境。
- **Digest**
    - 优点：不会直接传输密码。
    - 缺点：协议复杂、很少启用，微软也不再推荐。
    - 适用：基本淘汰。
- **NTLM**
    - 优点：不需明文密码，支持挑战-响应。
    - 缺点：存在安全漏洞（如 NTLM Relay 攻击），且只适合单跳访问。
    - 适用：非域环境（工作组）常用。
- **Kerberos**
    - 优点：最安全（不传输密码，基于票据机制），可防止中间人攻击。
    - 缺点：需要域控制器（AD/KDC），配置较复杂。
    - 适用：企业 AD 域环境。
- **CredSSP**
    - 优点：支持“凭据委派”，即在远程主机上再远程（第二跳）。
    - 缺点：凭据会传到远端内存，存在泄露风险。
    - 适用：需要跳板机的场景（例如 Win → Win → SQL）。
- **Negotiate**
    - 优点：自动选择 Kerberos（优先）或 NTLM（备用），对用户透明。
    - 缺点：如果 Kerberos 环境没配置好，可能会回退到 NTLM。
    - 适用：推荐默认选择，适合企业和普通环境。

### 1.5.2 总结推荐
- **测试/快速接入**：Basic + HTTPS（最简单，跨平台无脑可用）。
- **工作组环境**：NTLM（不用配置域）。
- **企业域环境**：Negotiate（自动 Kerberos/NTLM，推荐）。

## 1.6 启用WinRM
以 **管理员身份** 打开 PowerShell，执行：

```bash
# 1. 启用 WinRM 服务
winrm quickconfig -force
 
# 2. 启用 Basic 认证（方便跨平台调用，例如 Java、Python 客户端）
winrm set winrm/config/service/auth '@{Basic="true"}'
 
# 3. 允许未加密会话（仅测试用，生产环境建议配置 HTTPS）
winrm set winrm/config/service '@{AllowUnencrypted="true"}'
 
# 4. 放行防火墙 5985 端口（HTTP）
netsh advfirewall firewall add rule name="WinRM HTTP" dir=in action=allow protocol=TCP localport=5985
```

# 第二部分 操作示例

## 2.1 引入winrm4j库

```xml

<dependency>
   <groupId>io.cloudsoft.windows</groupId>
   <artifactId>winrm4j</artifactId>
   <version>0.12.3</version>
</dependency>
```

## 2.2 测试代码

```java
import io.cloudsoft.winrm4j.winrm.WinRmTool;
import io.cloudsoft.winrm4j.winrm.WinRmToolResponse;
import org.apache.http.client.config.AuthSchemes;
import org.junit.jupiter.api.Test;
 
public class WinRMTest {
    private String host = "xxx"; // 目标主机名或IP
    private String user = "Administrator";
    private String password = "xxx";
 
    @Test
    public void testWinRM() throws Exception {
        WinRmTool tool = WinRmTool.Builder.builder(host, user, password)
                .port(5985) // WinRM 默认端口: HTTP 5985 / HTTPS 5986
                .useHttps(false).authenticationScheme(AuthSchemes.NTLM).disableCertificateChecks(true).build();
        // 获取系统信息
        String[] commands = { "wmic os get Caption,OSArchitecture",
                "wmic cpu get Name,NumberOfCores,NumberOfLogicalProcessors",
                "wmic memorychip get Capacity,Manufacturer" };
 
        for (String cmd : commands) {
            WinRmToolResponse response = tool.executeCommand(cmd);
            System.out.println("命令: " + cmd);
            System.out.println(response.getStdOut());
        }
    }
}
```

:::tip{title="提示"}
实际使用中若涉及到中文需要注意中文乱码
:::

摘要

第一部分概述

第一部分概述

第一部分概述

第一部分概述

1.1 WinRM 是什么？能干什么？

摘要

第一部分 概述

第一部分 概述

第一部分 概述

第一部分 概述

1.1 WinRM 是什么？能干什么？

第一部分概述

第一部分概述

第一部分概述

第一部分概述