背景介绍

技术演进背景

随着 DeepSeek 等开源 AI 工具的崛起，智能编程助手正在重塑软件开发流程。对于开发者而言，AI 辅助编码已为生产力工具。虽然目前 AI 尚无法直接根据需求文档和指定技术栈生成完整生产级项目，但在特定场景下已展现出惊人潜力：基于详细逻辑描述生成代码片段准确率可达 80%以上。目前AI 在项目的工程化能力方面仍显不足，而 Sponge 框架则在工程化能力表现出色，两者恰好形成互补。

Sponge 是一个强大的 Go 语言开发框架，目前提供40多个代码生成命令，其独特的逆向工程能力支持通过解析 SQL/Protobuf/JSON 生成模块化代码，模块化代码可灵活组合出 Web、gRPC、HTTP+gRPC、gRPC 网关等多种服务架构。开发者只需在生成的项目代码中填充业务逻辑，即可快速构建生产级后端服务。sponge生成代码框架图如下图所示：

黄金组合

当 Sponge 的工程化能力遇上 DeepSeek 的智能生成，形成了一套完整的高效开发解决方案：

• Sponge：负责基础设施代码生成（服务框架、CRUD API 接口、缺少业务逻辑实现的自定义 API 接口等）。
• DeepSeek：专注业务逻辑实现（表 DDL 设计、自定义 API 接口定义、业务逻辑实现代码）。

值得一提的是，Sponge 已集成了 DeepSeek 的 API，只需简单执行命令即可自动搜索项目代码中待补全业务逻辑的方法函数，让 DeepSeek 生成业务逻辑实现代码。

项目实战示例 —— 从零开始构建家电零售管理平台

下面以构建一个线下家电实体店的产品管理平台为例，说明如何利用 Sponge 与 DeepSeek 协同开发后端服务。本示例后端技术栈选择 Web 服务 (Gin + Gorm + Protobuf)。

注：这里把 API 接口的请求和返回数据结构定义在 Protobuf 文件中，充分利用 Protobuf 的优势——解析Protobuf来生成框架所需的代码和API接口文档。

1. 生成功能需求文档

首先，通过 DeepSeek R1 生成详细的功能需求文档。输入以下提示：

“现在需要实现线下家电实体店铺的产品管理平台的后台服务，请列出详细的功能需求。”

DeepSeek R1 会生成一个较为全面的需求文档，开发者可以根据实际需要删减不必要的功能，保留真正需要的功能模块，或额外添加补充功能模块。点击查看家电零售管理平台功能需求文档。

2. 生成 MySQL 表结构 DDL

接下来，根据功能需求文档生成所有 MySQL 表结构的 DDL。输入以下提示：

“根据功能需求文档，生成后台服务所需的所有 MySQL 表结构的 DDL，要求生成的 SQL 可直接导入 MySQL 创建表，表的每列均需附带中文注释。”

DeepSeek R1 会根据需求文档生成对应的 Mysql 表结构 DDL，开发者需要校验判断是否完全满足要求，如果不满足可以人工调整。点击查看家电零售管理平台表结构DDL。

把 Mysql 表结构 DDL 导入 MySQL 后，即可为后续代码生成提供数据结构支持。Sponge 可以根据这些表结构生成各种模块代码，如 CRUD API 代码 和 CRUD Protobuf 定义等。

3. API 接口定义

3.1 生成 CRUD API Protobuf

在 Sponge 的生成代码页面中，依次选择：【Public】→【生成 Protobuf CRUD 代码】，填写参数后点击【下载代码】按钮生成代码，如下图所示：

提示： 如果生成的 proto 文件较多，建议将它们合并到一个文件中，因为 DeepSeek R1 上传文件数量有限制。

3.2 生成自定义 API Protobuf

标准的 CRUD API 并不能涵盖所有业务需求，因此需要根据 CRUD API Protobuf 文件和功能需求文档生成自定义 API 的 Protobuf 定义。
在 DeepSeek R1 中上传 CRUD API 的 proto 文件和家电零售管理平台功能需求文档，并输入如下提示：

已确定所有 MySQL 表的标准 CRUD API 的 Protobuf 定义，这些 API 仅涵盖家电零售管理平台后台服务的一部分功能，为了涵盖所有的功能，请依据CRUD API 的 Protobuf 定义和家电零售管理平台的功能需求文档，进行补充自定义API Protobuf，要求如下：
1. 每个 rpc 方法必须包含 option (google.api.http)。
2. rpc 方法及其 message 字段需附带中文注释，rpc 方法需详细描述逻辑实现过程（作为 AI 生成业务逻辑代码的依据）。
3. 补充的 API 需要标识其所属的 Protobuf service。

注： 若生成结果中 Protobuf 描述里的 rpc 方法注释不够详细(例如逻辑实现过程、指定技术栈)，可以适当人工补充完善。

生成的自定义 API Protobuf 与 CRUD API Protobuf 共同构成了服务完整功能的API接口定义，为后续 Sponge 提供生成代码依据。

4. 创建服务代码

以 Web 服务为例（技术栈：Gin + Gorm + Protobuf）进行后续代码生成和集成。

4.1 生成服务基础代码

在 Sponge 代码生成的页面中，选择：【Protobuf】→【创建 Web 服务】，填写参数后点击【下载代码】按钮生成代码。如下图所示：

生成的代码包中包含服务的基本框架，解压后进入代码目录。

4.2 生成 CRUD API 代码

同样在 Sponge 代码生成的页面中，选择：【Public】→【生成 Handler CRUD 代码】，填写参数后点击【下载代码】按钮生成代码，如下图所示：

解压文件，将生成的 api 和 internal 目录移动至服务代码目录中。

使用 VS Code 或 Goland 打开项目代码，并将在前面由 DeepSeek R1 生成的自定义 API 的 Protobuf 文件人工合并到 api/store/v1 目录下对应的 proto 文件中。
接着，在项目根目录下执行以下命令生成代码：

make proto

注： 每当修改 proto 文件后，都需重新执行 make proto 命令，可通过指定 proto 文件名生成代码。

5. 业务逻辑代码补全

Sponge 集成了 DeepSeek API，可自动定位到需要补充业务逻辑的方法函数，让 AI 助手生成业务逻辑实现代码，执行如下命令：

sponge assistant generate --type=deepseek --model=deepseek-reasoner --api-key=xxxx --dir=.

生成的业务逻辑代码会以 .assistant 为后缀保存在相应目录下，开发者只需将其复制到对应方法函数中即可。这里不采用自动填充的方式，是因为 DeepSeek R1 输出可能包含 markdown 等非纯 Go 代码，故需人工校验复制。

6. 测试和验证 API 功能

至此，通过 Sponge 与 DeepSeek 的协同工作，绝大部分代码均已自动生成。如果AI助手根据详细的提示生成业务逻辑实现代码也无法满足要求，则需要人工编写代码。

接着开发者调试与验证 API 功能，启动服务：

make run

使用浏览器访问 Swagger 界面进行 API 调试：http://localhost:8080/apis/swagger/index.html

这是Sponge与DeepSeek协同生成的后端服务示例代码：后端服务示例代码。

总结

本文通过一个家电零售管理平台的案例，演示了如何利用 Sponge 与 DeepSeek R1 协同开发后端服务的全过程：

1. 需求分析：利用 DeepSeek R1 生成详细功能需求文档。
2. 数据库设计：依据需求生成 MySQL 表结构 DDL，并导入数据库。
3. 接口定义：先生成标准 CRUD API 的 Protobuf，再由 DeepSeek R1 生成自定义 API 的 Protobuf的定义信息。
4. 服务代码生成：利用 Sponge 分别生成基础服务代码、CRUD API 代码、自定义 API 的 Protobuf代码(只缺业务逻辑实现)。
5. 业务逻辑代码补全：通过 Sponge 内置 AI 工具自动生成业务逻辑代码，并由开发者进行整合与校验。
6. 调试验证：启动服务，借助 Swagger 等工具调试并验证 API 接口。

这种基于 Sponge 与 DeepSeek R1 协同开发可以快速构建出一个功能完善、逻辑清晰的后端服务项目，实现了“写较少代码完成大部分工作”的目标，让个人开发者也能轻松承担团队级别的任务。同时也正在重新定义软件开发的效率边界：

1. 开发角色转变：工程师更侧重架构设计和质量把控。
2. 敏捷度提升：原型开发周期从周级缩短至天级。
3. 知识沉淀：AI 生成的标准化代码更易维护和迭代。

本文链接：https://zhuyasen.com/post/ai-sponge.html，参与评论 »

kafka 基础

kafka 是一个开源的流处理平台，主要用于构建实时数据管道和流应用。它最初由LinkedIn开发，并在2011年成为Apache软件基金会的顶级项目。

kafka 架构

kafka 架构由存储层和计算层组成，如下图所示：

• 存储层旨在高效存储数据，并且是一个分布式系统，因此如果您的存储需求随着时间的推移而增长，您可以轻松扩展系统以适应增长。
• 计算层由生产者、消费者、流和连接器 API 四个核心组件组成，它们允许 kafka 跨分布式系统扩展应用程序。

kafka 集群中的功能分为数据平面和控制平面，控制平面负责管理集群中的所有元数据，数据平面负责处理我们写入 kafka 和从 kafka 读取的实际数据。

kafka框架图：

核心组件：

• Producer（生产者）

  • 负责发布消息到kafka的Topic中。
  • 可以选择将消息发送到特定的Partition中，或由kafka的分区策略自动分配。

• Consumer（消费者）

  • 订阅一个或多个Topic，从中消费消息。
  • 消费者通常会属于一个消费者组（Consumer Group），同一组中的消费者会共同分配并消费Topic的不同Partition中的消息，以实现负载均衡。

• Broker

  • kafka集群中的一个服务器称为Broker。
  • Broker负责接收和存储消息，然后为消费者服务。

• Topic

  • 一个Topic可以看作是一个消息队列的名字。
  • kafka中的数据流会被分类发布到不同的Topic中。

• Partition（分区）

  • 每个Topic可以分为多个Partition。
  • 分区是kafka数据存储的基本单元，所有的消息都会写入一个有序的分区中。

• Replica（副本）

  • 为了确保数据的高可用性和容错性，每个Partition可以有多个副本。
  • 副本分为Leader副本和Follower副本，Leader副本负责处理读写请求，Follower副本负责备份数据。

• Kraft

  • 替代传统的 ZooKeeper 作为元数据管理和分布式协调服务，简化运维、提高性能、增强安全性。
  • 使用 Raft 协议来实现分布式一致性和协调，并内置在kafka，简化了系统架构。

kafka 中的 topic 始终是多生产者和多订阅者的：一个主题可以有零个、一个或多个向其写入事件的生产者；一个主题可以有零个、一个或多个订阅这些事件的消费者。

主题中的事件可以根据需要随时读取，与传统消息传递系统不同，事件在使用后不会被删除。相反，您可以通过每个主题的配置设置来定义 kafka 应保留事件多长时间，超过该时间后将丢弃旧事件。kafka 的性能在数据大小方面实际上是恒定的，因此长时间存储数据是完全没问题的。

topic 是分区的，这意味着topic分布在位于不同 kafka 代理上的多个“存储桶”中。这种数据的分布式放置对于可扩展性非常重要，因为它允许客户端应用程序同时从多个代理读取数据或向多个代理写入数据。当新事件发布到topic时，它实际上被附加到主题的某个分区中。具有相同事件键（例如客户或车辆 ID）的事件被写入同一个分区，kafka保证给定主题分区的任何消费者将始终按照写入顺序读取该分区的事件。

通过将 Topic 分为多个 Partition，可以实现消息的并行处理和存储，提升系统的吞吐量和可靠性。Broker 提供了 Partition 的物理存储和管理，每个 Partition 又存在多个副本以确保数据的安全性和高可用性。这种设计使得 kafka 能够高效地处理大规模的实时数据流。

kafka 数据复制

一旦创建了 topic 中所有分区的副本，每个分区的一个副本将被指定为领导者副本，而持有该副本的代理将成为该分区的领导者，其余副本将成为追随者。生产者将写入领导者副本，追随者将获取数据与领导者保持同步。消费者默认从领导者副本获取数据，但可以配置为从追随者获取数据。

领导者则使用获取响应来通知追随者当前的偏移量。由于此过程是异步的，追随者的偏移量通常会落后于领导者所持有的实际偏移量。

所有追随者都已获取到特定偏移量，则该偏移量之前的记录将被视为已提交并可供消费者使用。这是由偏移量指定的。

领导者监控其追随者的进度，如果从追随者上次完全赶上以来经过了可配置的时间量，领导者将从同步副本集中删除该追随者。这允许领导者推进偏移量，以便消费者可以继续使用当前数据。如果追随者重新上线或以其他方式采取行动并赶上领导者，那么它将被重新添加到 ISR。

领导者副本的代理比追随者副本的工作量要多一些。因此，最好不要在单个代理上拥有过多的领导者副本。为了防止这种情况，kafka 有一个首选副本的概念。创建主题时，每个分区的第一个副本被指定为首选副本。由于 kafka 已经在努力在可用的代理之间均匀分布分区，因此这通常会导致领导者之间的良好平衡。

由于领导者选举会因各种原因而发生，领导者最终可能会出现在非首选副本上，这可能会导致不平衡。因此，kafka 将定期检查领导者副本是否存在不平衡。它使用可配置的阈值来做出此判断。如果确实发现不平衡，它将执行领导者重新平衡，以使领导者回到其首选副本上。

kafka 控制平面

 kafka 3.3.1 以后版本使用KRaft替代Zookeeper，KRaft 模式有很多优点。

• 部署和管理更简单：由于只需安装和管理一个应用程序，kafka 的运营占用空间现在大大减少。这也使得在边缘的小型设备中利用 kafka 变得更加容易。
• 提高可扩展性：如图所示，使用 KRaft 的恢复时间比使用 ZooKeeper 快一个数量级。这使我们能够高效地扩展到单个集群中的数百万个分区。使用 ZooKeeper 时，有效限制为数万个。
• 更高效的元数据传播：基于日志、事件驱动的元数据传播可提高 kafka 许多核心功能的性能。

在 KRaft 模式下，kafka 集群可以以专用或共享模式运行。在专用模式下，一些节点会将其process.roles配置设置为controller，其余节点会将其设置为broker。对于共享模式，一些节点会将process.roles设置为controller 和 broker，这些节点将承担双重职责。选择哪种方式取决于集群的大小。

在启动kafka集群时以及当前领导者停止（无论是滚动升级还是由于故障）时都需要进行控制器领导者选举，通过投票请求、投票回应、达成共识三个步骤，当旧领导者控制器重新上线时，它跟随新领导者，并将其自己的元数据日志与领导者保持同步。

消费者组协议

kafka 将存储与计算分开，存储由代理处理，计算主要由消费者或基于消费者构建的框架（kafka Streams、ksqlDB）处理。消费者组在 kafka 消费者的有效性和可扩展性方面发挥着关键作用。

1. 消费者组的定义

消费者组是 kafka 中的一种机制，用于实现消息的并行处理和负载均衡。一个消费者组包含多个消费者实例，这些实例共同消费一个或多个主题（topic）的消息。

2. 消费者组的工作原理

• 负载均衡：kafka 将一个主题的分区（partition）分配给消费者组中的不同消费者实例，每个分区只会被组内的一个消费者消费。这种机制保证了消息的并行处理和负载均衡。
• 容错性：如果组内的某个消费者实例宕机，kafka 会自动将其分配的分区重新分配给其他消费者实例，保证消息的连续消费。

3. kafka 使用消费者组的原因

• 高吞吐量：通过消费者组，kafka 可以实现高吞吐量的消息处理，因为多个消费者实例可以并行处理不同的分区。
• 扩展性：消费者组使得 kafka 可以轻松扩展，只需增加更多的消费者实例即可。
• 容错性和高可用性：消费者组提供了自动故障转移和重新分配机制，增强了系统的容错性和高可用性。

消费者组再平衡是消费者组的一个关键特性，可能触发重新平衡的事件：

• 实例未能在超时之前向协调器发送心跳，因此被从组中删除
• 实例已添加到组中
• 已将分区添加到组订阅中的主题
• 某个组有通配符订阅，并且创建了新的匹配主题
• 最初的团队启动

注：对于静态组成员身份，每个消费者实例都会被分配一个group.instance.id，不发生重新平衡。

为了解决重新平衡时需要暂停处理的问题，引入了 CooperativeStickyAssignor 。此分配器的工作过程分为两个步骤。 - 确定需要撤销哪些分区分配。这些分配将在第一个重新平衡步骤结束时撤销。未撤销的分区可以继续处理。 - 被撤销的分区，它被分配给新的消费者。

数据持久性和可用性保证

生产者请求成功或失败的确认设置

• 生产者配置acks直接影响持久性保证，它还提供了持久性和延迟之间的几个权衡点之一。设置acks=0（也称为“即发即弃”模式）可提供较低的延迟，因为生产者不会等待代理的响应。但是，此设置无法提供强大的持久性保证，因为分区领导者可能由于暂时的连接问题而永远无法收到数据，或者我们可能正在经历领导者选举。

• 使用acks=1时，持久性会稍微好一些，因为知道数据已写入领导者副本，但延迟会稍微高一些，因为正在等待发送请求过程中的所有步骤。

• 最高级别的持久性来自 acks=all（或acks=-1），这也是默认设置。使用此设置，在数据写入领导者副本和 ISR（同步副本）列表中的所有追随者副本之前，不会确认发送请求。由于正在等待复制过程完成，因此延迟会更高。

主题级别配置min.insync.replicas与acks配置配合使用

两者配合使用可以更有效地实施持久性保证，此设置告知代理，除非 ISR 中有 N 个副本，否则不允许将事件写入主题。与acks=all结合使用，可确保在确认事件发送之前，主题上收到的任何事件都将存储在 N 个副本中。

例如复制因子为 3，并且min.insync.replicas 设置为 2，那么我们可以容忍一次故障，并且仍然接收新事件。如果丢失了两个节点，那么生产者发送请求将收到异常，通知生产者副本不足。生产者可以重试，直到有足够的副本，或者将异常冒泡。无论哪种情况，都不会丢失数据。

生产者幂等性

要启用幂等性，我们在生产者上设置enable.idempotence = true，这是 kafka 3.0 的默认值。使用此设置，生产者会用生产者 ID 和序列号标记每个事件。这些值将与事件一起发送并存储在日志中。如果由于故障而再次发送事件，则将包含相同的标识符。如果发送了重复事件，代理将看到生产者 ID 和序列号已经存在，并将拒绝这些事件并向客户端返回DUP响应。

因为生产者幂等性，kafka 具有顺序保证， 会过滤掉重复的事件，事件按发送顺序写入特定分区，消费者按相同顺序读取这些事件。

kafka 多副本机制中的一些重要术语：

• AR(Assigned Replicas)：一个分区中的所有副本统称为 AR；
• ISR(In-Sync Replicas)：Leader 副本和所有保持一定程度同步的 Follower 副本（包括 Leader 本身）组成 ISR；
• OSR(Out-of-Sync Raplicas)：与 ISR 相反，没有与 Leader 副本保持一定程度同步的所有Follower 副本组成OSR；

一些 kafka 常见的应用场景

安装 kafka

安装单机版 kafka

安装kafaka集群有.env和docker-compose.yml两个文件。

.env文件内容如下：

# 把下面的 192.168.3.37 改为你的ip地址
ACCESS_ADDR=192.168.3.37:9092

docker-compose.yml内容如下：

version: '3.8'

services:
  broker:
    image: apache/kafka:3.7.0
    container_name: broker
    ports:
      - '9092:9092'
    environment:
      kafka_NODE_ID: 1
      kafka_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT'
      kafka_ADVERTISED_LISTENERS: 'PLAINTEXT_HOST://${ACCESS_ADDR},PLAINTEXT://broker:19092'
      kafka_PROCESS_ROLES: 'broker,controller'
      kafka_CONTROLLER_QUORUM_VOTERS: '1@broker:29093'
      kafka_LISTENERS: 'CONTROLLER://:29093,PLAINTEXT_HOST://:9092,PLAINTEXT://:19092'
      kafka_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT'
      kafka_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      CLUSTER_ID: '4L6g3nShT-eMCtK--X86sw'
      kafka_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      kafka_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      kafka_TRANSACTION_STATE_LOG_MIN_ISR: 1
      kafka_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      kafka_LOG_DIRS: '/var/lib/kafka/data'
    volumes:
      - $PWD/data/:/var/lib/kafka/data

  kafka-ui:
    image: provectuslabs/kafka-ui:v0.7.2
    container_name: kafka-ui
    ports:
      - "18080:8080"
    environment:
      kafka_CLUSTERS_0_NAME: 'Local kafka Cluster'
      kafka_CLUSTERS_0_BOOTSTRAPSERVERS: 'broker:19092'
      DYNAMIC_CONFIG_ENABLED: "true"
    depends_on:
      - broker

第一次使用时，创建一个data文件夹作为数据持久化，并且修改目录data权限，

mkdir data
chmod -R 0777 data

打开.env文件，修改 kafka broker 外部访问地址，用于外部客户端连接，然后启动kafaka服务：

docker-compose up -d

启动服务成功后，可以在浏览器打开 http://localhost:18080 查看kafka信息。

安装 kafka 集群

安装kafaka集群有.env和docker-compose.yml两个文件。

.env文件内容如下：

# 把下面的 192.168.3.37 改为你的ip地址
kafka_1_ACCESS_ADDR=192.168.3.37:33001
kafka_2_ACCESS_ADDR=192.168.3.37:33002
kafka_3_ACCESS_ADDR=192.168.3.37:33003

docker-compose.yml内容如下：

version: "3.8"

services:
  kafka-1:
    image: docker.io/bitnami/kafka:3.7
    container_name: kafka-1
    ports:
      - "33001:9092"
    environment:
      # KRaft settings
      - kafka_CFG_NODE_ID=0
      - kafka_CFG_PROCESS_ROLES=controller,broker
      - kafka_CFG_CONTROLLER_QUORUM_VOTERS=0@kafka-1:9093,1@kafka-2:9093,2@kafka-3:9093
      - kafka_KRAFT_CLUSTER_ID=abcdefghijklmnopqrstuv
      # Listeners
      - kafka_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
      #- kafka_CFG_ADVERTISED_LISTENERS=PLAINTEXT://:9092
      - kafka_CFG_ADVERTISED_LISTENERS=PLAINTEXT://${kafka_1_ACCESS_ADDR}
      - kafka_CFG_LISTENER_SECURITY_PROTOCOL_MAP=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
      - kafka_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - kafka_CFG_INTER_BROKER_LISTENER_NAME=PLAINTEXT
      # Clustering
      - kafka_CFG_OFFSETS_TOPIC_REPLICATION_FACTOR=3
      - kafka_CFG_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=3
      - kafka_CFG_TRANSACTION_STATE_LOG_MIN_ISR=2
    volumes:
      - $PWD/data/kafka-1:/bitnami/kafka
    networks:
      - kafka-net

  kafka-2:
    image: docker.io/bitnami/kafka:3.7
    container_name: kafka-2
    ports:
      - "33002:9092"
    environment:
      # KRaft settings
      - kafka_CFG_NODE_ID=1
      - kafka_CFG_PROCESS_ROLES=controller,broker
      - kafka_CFG_CONTROLLER_QUORUM_VOTERS=0@kafka-1:9093,1@kafka-2:9093,2@kafka-3:9093
      - kafka_KRAFT_CLUSTER_ID=abcdefghijklmnopqrstuv
      # Listeners
      - kafka_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
      #- kafka_CFG_ADVERTISED_LISTENERS=PLAINTEXT://:9092
      - kafka_CFG_ADVERTISED_LISTENERS=PLAINTEXT://${kafka_2_ACCESS_ADDR}
      - kafka_CFG_LISTENER_SECURITY_PROTOCOL_MAP=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
      - kafka_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - kafka_CFG_INTER_BROKER_LISTENER_NAME=PLAINTEXT
      # Clustering
      - kafka_CFG_OFFSETS_TOPIC_REPLICATION_FACTOR=3
      - kafka_CFG_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=3
      - kafka_CFG_TRANSACTION_STATE_LOG_MIN_ISR=2
    volumes:
      - $PWD/data/kafka-2:/bitnami/kafka
    networks:
      - kafka-net

  kafka-3:
    image: docker.io/bitnami/kafka:3.7
    container_name: kafka-3
    ports:
      - "33003:9092"
    environment:
      # KRaft settings
      - kafka_CFG_NODE_ID=2
      - kafka_CFG_PROCESS_ROLES=controller,broker
      - kafka_CFG_CONTROLLER_QUORUM_VOTERS=0@kafka-1:9093,1@kafka-2:9093,2@kafka-3:9093
      - kafka_KRAFT_CLUSTER_ID=abcdefghijklmnopqrstuv
      # Listeners
      - kafka_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
      #- kafka_CFG_ADVERTISED_LISTENERS=PLAINTEXT://:9092
      - kafka_CFG_ADVERTISED_LISTENERS=PLAINTEXT://${kafka_3_ACCESS_ADDR}
      - kafka_CFG_LISTENER_SECURITY_PROTOCOL_MAP=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
      - kafka_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - kafka_CFG_INTER_BROKER_LISTENER_NAME=PLAINTEXT
      # Clustering
      - kafka_CFG_OFFSETS_TOPIC_REPLICATION_FACTOR=3
      - kafka_CFG_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=3
      - kafka_CFG_TRANSACTION_STATE_LOG_MIN_ISR=2
    volumes:
      - $PWD/data/kafka-3:/bitnami/kafka
    networks:
      - kafka-net

  kafka-ui:
    image: provectuslabs/kafka-ui:v0.7.2
    restart: always
    container_name: kafka-ui
    ports:
      - "18080:8080"
    environment:
      - kafka_CLUSTERS_0_NAME=Local-Kraft-Cluster
      - kafka_CLUSTERS_0_BOOTSTRAPSERVERS=kafka-1:9092,kafka-2:9092,kafka-3:9092
      - DYNAMIC_CONFIG_ENABLED=true
      - kafka_CLUSTERS_0_AUDIT_TOPICAUDITENABLED=true
      - kafka_CLUSTERS_0_AUDIT_CONSOLEAUDITENABLED=true
    depends_on:
      - kafka-1
      - kafka-2
      - kafka-3
    networks:
      - kafka-net

networks:
  kafka-net:

第一次使用时，创建一个data文件夹作为数据持久化，并且修改目录data权限：

mkdir data/kafka-1 data/kafka-2 data/kafka-3
chmod -R 0777 data

打开.env文件，修改 kafka-1、kafka-2、kafka-3 外部访问地址，用于外部客户端连接，然后启动kafaka集群：

docker-compose up -d

启动服务成功后，可以在浏览器打开 http://localhost:18080 查看kafka信息。

使用go操作kafka示例

创建 topic 示例

package main

import (
    "flag"
    "fmt"

    "github.com/IBM/sarama"
)

var (
    brokerAddrs = []string{"192.168.3.37:33001", "192.168.3.37:33002", "192.168.3.37:33003"}
    topic       string
)

func main() {
    flag.StringVar(&topic, "topic", "", "the name of the topic to create")
    flag.Parsed()
    if topic == "" {
        fmt.Println("please specify the topic name, usage: go run main.go -topic <topic_name>")
        return
    }

    // 创建kafka管理员客户端
    admin, err := sarama.NewClusterAdmin(brokerAddrs, sarama.NewConfig())
    if err != nil {
        panic(err)
    }
    defer admin.Close()

    // 创建主题
    topicConfig := &sarama.TopicDetail{
        NumPartitions:     3, // 分区数
        ReplicationFactor: 1, // 副本数
        ConfigEntries:     map[string]*string{},
    }
    if err := CreateTopic(admin, topic, topicConfig); err != nil {
        panic(err)
    }
}

// IsTopicExists checks if a topic exists in the kafka cluster
func IsTopicExists(admin sarama.ClusterAdmin, topic string) bool {
    topics, err := admin.ListTopics()
    if err != nil {
        return false
    }

    _, ok := topics[topic]
    return ok
}

// CreateTopic creates a new topic in the kafka cluster, if topic already exists, it will ignore
func CreateTopic(admin sarama.ClusterAdmin, topic string, topicConfig *sarama.TopicDetail) error {
    if IsTopicExists(admin, topic) {
        return nil
    }

    err := admin.CreateTopic(topic, topicConfig, false)
    if err != nil {
        return err
    }

    fmt.Printf("topic %s created successfully\n", topic)
    return nil
}

生产者示例

1. 同步生产者示例

package main

import (
    "fmt"
    "math/rand"
    "time"

    "github.com/IBM/sarama"
)

var (
    brokerList = []string{"192.168.3.37:33001", "192.168.3.37:33002", "192.168.3.37:33003"}
    topicName = "test_topic"
)

func main() {
    // 创建kafka生产者配置
    config := sarama.NewConfig()
    // 设置kafka版本
    // config.Version = sarama.V3_6_0_0
    // ack类型 WaitForLocal(leader确认), WaitForAll(leader和follow都确认), NoResponse(不需确认)
    config.Producer.RequiredAcks = sarama.WaitForAll
    // 分区策略，默认是NewHashPartitioner、根据业务需要可以选择使用 NewRandomPartitioner、
    //NewRoundRobinPartitioner、NewReferenceHashPartitioner、NewManualPartitioner。
    config.Producer.Partitioner = sarama.NewHashPartitioner
    config.Producer.Retry.Max = 5
    // 成功交付的消息将在success channel返回
    config.Producer.Return.Successes = true
    config.ClientID = "kafka-demo"

    // 创建同步生产者
    producer, err := sarama.NewSyncProducer(brokerList, config)
    if err != nil {
        panic(err)
    }
    defer producer.Close()

    // 发送的消息到指定主题
    hostID := rand.Intn(1000)
    for i := 1; i <= 50; i++ {
        // 构造一个消息
        message := &sarama.ProducerMessage{
            Topic:    topicName,
            Value:    sarama.StringEncoder(fmt.Sprintf("'%d log content %d'", hostID, i)),
            Metadata: i,
        }

        // 发送消息
        partition, offset, err := producer.SendMessage(message)
        if err != nil {
            panic(err)
        }

        fmt.Printf("send msg, topic=%s, partition=%d, offset=%d, i=%v\n", topicName, partition, offset, i)
    }

    <-time.After(time.Second * 2)
}

2. 异步生产者示例

package main

import (
    "fmt"
    "math/rand"
    "time"

    "github.com/IBM/sarama"
)

var (
    brokerList = []string{"192.168.3.37:33001", "192.168.3.37:33002", "192.168.3.37:33003"}
    topicName = "test_topic"
)

func main() {
    // 创建kafka生产者配置
    config := sarama.NewConfig()
    // 设置kafka版本
    // config.Version = sarama.V3_6_0_0
    // ack类型 WaitForLocal(leader确认), WaitForAll(leader和follow都确认), NoResponse(不需确认)
    config.Producer.RequiredAcks = sarama.WaitForLocal
    // 分区策略，默认是NewHashPartitioner、根据业务需要可以选择使用 NewRandomPartitioner、
    //NewRoundRobinPartitioner、NewReferenceHashPartitioner、NewManualPartitioner。
    config.Producer.Partitioner = sarama.NewHashPartitioner
    // 成功交付的消息将在success channel返回
    config.Producer.Return.Successes = true
    // 触发批量发送消息数设置
    config.Producer.Flush.Messages = 10
    config.Producer.Flush.Frequency = time.Second

    // 创建异步生产者
    producer, err := sarama.NewAsyncProducer(brokerList, config)
    if err != nil {
        panic(err)
    }
    defer producer.Close()

    // 返回结果状态
    go func() {
        for {
            select {
            case pm := <-producer.Successes():
                fmt.Printf("send msg, topic=%s, partition=%d, offset=%d, i=%v\n", pm.Topic, pm.Partition, pm.Offset, pm.Metadata)
            case err := <-producer.Errors():
                fmt.Printf("send msg failed, err: %v", err)
            }
        }
    }()

    // 发送的消息到指定主题
    hostID := rand.Intn(1000)
    count := 50
    for i := 1; i <= count; i++ {
        // 构造一个消息
        message := &sarama.ProducerMessage{
            Topic:    topicName,
            Value:    sarama.StringEncoder(fmt.Sprintf("'%d log content %d'", hostID, i)),
            Metadata: i,
        }

        // 发送消息
        producer.Input() <- message
    }

    fmt.Println("send msg done")
    <-time.After(time.Second * 2)
}

消费者示例

1. 消费者组示例

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/IBM/sarama"
)

var (
    brokerList = []string{"192.168.3.37:33001", "192.168.3.37:33002", "192.168.3.37:33003"}
    groupID    = "group1"
    topicName  = "test_topic"
)

func main() {
    // 创建kafka消费者配置
    config := sarama.NewConfig()
    //config.Version = sarama.V3_6_0_0
    config.Consumer.Offsets.Initial = sarama.OffsetOldest // 从未消费的消息开始消费，有可能重复消费
    config.Consumer.Offsets.AutoCommit.Enable = true // true：自动提交偏移量，false：手动提交偏移量
    config.Consumer.Offsets.AutoCommit.Interval = time.Second

    // 创建kafka消费者组
    cg, err := sarama.NewConsumerGroup(brokerList, groupID, config)
    if err != nil {
        panic(err)
    }
    defer cg.Close()

    // 消费消息
    ctx := context.Background()
    autoCommit := config.Consumer.Offsets.AutoCommit.Enable
    err = cg.Consume(ctx, []string{topicName}, &consumerHandler{autoCommit: autoCommit})
    if err != nil {
        fmt.Printf("consume error: %v\n", err)
    }
}

// Setup 、 Cleanup 和 ConsumeClaim 是 s.handler.ConsumeClaim 的三个接口，需要用户自己实现。
// 可以简单理解为，当需要创建一个会话时，先运行 Setup ，然后在 ConsumeClaim 中处理消息，最后运行 Cleanup 。
type consumerHandler struct {
    autoCommit bool
}

func (h *consumerHandler) Setup(sess sarama.ConsumerGroupSession) error {
    fmt.Println("setup topic:partitions -->", sess.Claims()) // 当有新的消费者加入或退出消费者组时，动态平衡后后可以看到本消费者所负责的分区
    return nil
}

func (h *consumerHandler) Cleanup(sess sarama.ConsumerGroupSession) error {
    fmt.Println("cleanup topic:partitions -->", sess.Claims())
    return nil
}

func (h *consumerHandler) ConsumeClaim(sess sarama.ConsumerGroupSession, claim sarama.ConsumerGroupClaim) error {
    for msg := range claim.Messages() {
        fmt.Printf("received msg: topic=%s, partition=%d, offset=%d, key=%s, val=%s\n", msg.Topic, msg.Partition, msg.Offset, msg.Key, msg.Value)
        sess.MarkMessage(msg, "")
        if !h.autoCommit {
            sess.Commit()
        }
    }
    return nil
}

2. 分区消费示例

package main

import (
    "fmt"

    "github.com/IBM/sarama"
)

var (
    brokerList = []string{"192.168.3.37:33001", "192.168.3.37:33002", "192.168.3.37:33003"}
    topicName  = "test_topic"
)

func main() {
    // 创建kafka消费者配置
    config := sarama.NewConfig()
    config.Version = sarama.V3_6_0_0
    config.Consumer.Return.Errors = true

    // 创建kafka消费者
    consumer, err := sarama.NewConsumer(brokerList, config)
    if err != nil {
        panic(err)
    }
    defer consumer.Close()

    // 根据topic取到所有的分区
    partitionList, err := consumer.Partitions(topicName)
    if err != nil {
        panic(err)
    }

    // 消费的主题
    for _, partition := range partitionList {
        offset := sarama.OffsetNewest // 可以设置为指定偏移量、最新偏移量sarama.OffsetNewest、历史偏移量sarama.OffsetOldest
        go func(partitionID int32, offset int64) {
            pc, err := consumer.ConsumePartition(topicName, partitionID, offset)
            if err != nil {
                panic(err)
            }
            defer pc.Close()

            for {
                select {
                case msg := <-pc.Messages():
                    fmt.Printf("received msg: topic=%s, partition=%d, offset=%d, key=%s, val=%s\n", msg.Topic, msg.Partition, msg.Offset, msg.Key, msg.Value)
                case err := <-pc.Errors():
                    fmt.Println("consuming err:", err)
                }
            }
        }(partition, offset)
    }

    select {}
}

获取 topic 堆积数量示例

topic堆积数量是比较重要的一个指标，直接影响业务的进行，可以在从kafka服务中该指标，也可以实现一个简单客户端从kafka或该指标。

package main

import (
    "fmt"

    "github.com/IBM/sarama"
)

var (
    brokerList = []string{"192.168.3.37:33001", "192.168.3.37:33002", "192.168.3.37:33003"}
    topic      = "test_topic"
    groupID    = "test_group"
)

// ClientManager client manager
type ClientManager struct {
    client sarama.Client
    offsetManager sarama.OffsetManager
}

// Backlog info
type Backlog struct {
    Partition         int32 `json:"partition"`  // partition id
    Backlog           int64 `json:"backlog"`    // data backlog
    NextConsumeOffset int64 `json:"nextOffset"` // offset for next consumption
}

// InitClientManager init client manager
func InitClientManager(addrs []string, groupID string) (*ClientManager, error) {
    config := sarama.NewConfig()
    //config.Version = sarama.V3_6_0_0
    client, err := sarama.NewClient(addrs, config)
    if err != nil {
        return nil, err
    }

    offsetManager, err := sarama.NewOffsetManagerFromClient(groupID, client)
    if err != nil {
        return nil, err
    }

    return &ClientManager{
        client:        client,
        offsetManager: offsetManager,
    }, nil
}

// GetBacklog get topic backlog
func (m *ClientManager) GetBacklog(topic string) (int64, []*Backlog, error) {
    var (
        total             int64 = 0
        partitionBacklogs []*Backlog
    )

    partitions, err := m.client.Partitions(topic)
    if err != nil {
        return 0, nil, err
    }

    for _, partition := range partitions {
        // get offset from kafka
        offset, err := m.client.GetOffset(topic, partition, -1)
        if err != nil {
            return 0, nil, err
        }

        // create topic/partition manager
        pom, err := m.offsetManager.ManagePartition(topic, partition)
        if err != nil {
            return 0, nil, err
        }

        var backlog int64
        // call sarama The NextOffset method of PartitionOffsetManager. Return the offset for the next consumption
        // if the consumer group has not consumed the data for this section, the return value will be -1
        n, str := pom.NextOffset()
        if str != "" {
            return 0, nil, fmt.Errorf("partition %d, %s", partition, str)
        }
        if n == -1 {
            backlog = offset
        } else {
            backlog = offset - n
        }
        total += backlog

        partitionBacklogs = append(partitionBacklogs, &Backlog{
            Partition:         partition,
            Backlog:           backlog,
            NextConsumeOffset: n,
        })
    }

    return total, partitionBacklogs, nil
}

// Close topic backlog
func (m *ClientManager) Close() error {
    if m != nil && m.client != nil {
        return m.client.Close()
    }
    return nil
}

func main() {
    m, err := InitClientManager(brokerList, groupID)
    if err != nil {
        panic(err)
    }
    defer m.Close()

    total, backlogs, err := m.GetBacklog(topic)
    if err != nil {
        panic(err)
    }

    fmt.Println("total backlog:", total)
    for _, backlog := range backlogs {
        fmt.Printf("partation=%d, backlog=%d, next_consume_offset=%d\n", backlog.Partition, backlog.Backlog, backlog.NextConsumeOffset)
    }
}

总结

kafka 作为一个分布式流处理平台，应用非常广泛，尤其是在大数据处理领域，它以其高吞吐量、低延迟、可扩展性等特点，成为构建实时数据处理应用的首选平台之一。在使用 kafka 的过程中，需要了解一些kafka相关知识：

1. 深入理解 kafka 的核心概念

kafka 的核心概念包括主题、分区、消费者组、偏移量等。理解这些概念对于理解 kafka 的工作原理和使用 kafka 进行开发至关重要。

2. 掌握 kafka 的基本操作

kafka 提供了丰富的 API 来进行消息的发布和消费。掌握这些 API 是使用 kafka 的基础。

3. 了解 kafka 的常见应用场景

kafka 可以应用于各种场景，例如日志收集、数据分析、实时流处理等。了解 kafka 的常见应用场景可以帮助我们更好地选择 kafka 进行应用开发。

4. 关注 kafka 的性能优化

kafka 的性能优化是一个重要的课题。通过合理的配置和优化，可以提高 kafka 的吞吐量和降低延迟。

5. 学习 kafka 的生态系统

kafka 拥有丰富的生态系统，包括各种工具、框架和库。学习 kafka 的生态系统可以帮助我们更好地使用 kafka。

• 官网： https://kafka.apache.org/
• 文档：https://kafka.apache.org/documentation/#gettingStarted
• go SDK：https://github.com/IBM/sarama
• go SDK示例：https://github.com/IBM/sarama/tree/main/examples

总而言之，kafka 是一门强大的工具，可以帮助我们构建实时数据处理应用。通过深入学习和掌握 kafka 的相关知识和技能，我们可以充分发挥 kafka 的优势，为我们的业务带来价值。

本文链接：https://zhuyasen.com/post/kafka.html，参与评论 »

接着上一篇文章 一天多开发完成一个极简版社区后端服务 ，接下来使用工具sponge实战一个微服务集群项目community-cluster，点击查看community-cluster的完整项目代码，

单体服务community-single拆分为微服务具体过程

社区后端服务community-single采用单体web应用架构，为了应对需求增加，造成功能越来越复杂，代码维护和开发变得困难的问题，把community-single拆分成多个微服务，下面是拆分微服务具体步骤：

第一步是进行系统分析和设计。首先确定哪些功能模块适合独立作为微服务，需要对单体服务community-single进行了仔细的功能分解，将其划分为几个关键的领域，分为用户服务(user)、关系服务(relation)和内容创作服务(creation)三个独立的服务。用户服务负责用户注册登录等功能，关系服务负责好友关系管理等，内容创作服务负责帖子创建、评论、点赞、收藏等功能。这些领域代表了系统的核心功能，并且在不同的领域之间存在较强的逻辑隔离。

第二步是定义服务接口。每个微服务需要定义清晰的RPC接口供外部调用，接口需要指定输入输出的数据结构。每个服务开发团队需要根据业务设计自己的接口并完成接口文档。

第三步是设计集群架构。引入了一个rpc网关服务(community_gw)，rpc网关服务作为所有微服务的入口，负责路由请求和负载均衡，它可以根据请求的路由信息将请求转发给相应的微服务。此外，rpc网关服务还提供了身份验证、授权和安全性等共享功能，以确保系统的安全性和一致性，这种架构可以提高整体的扩展性。

第四步是数据迁移。单体服务community-single使用的单一数据库，现在需要将数据按服务拆分，迁移至每个微服务自己的数据存储中。这里用户服务、关系服务、创作服务使用独立的MySQL，实现各自的数据隔离。

第五步是开发、测试、部署微服务。在拆分后的微服务集群中，每个微服务都可以独立进行。团队成员可以专注于自己领域的开发工作，并且可以根据需求对各个微服务进行水平扩展，以满足不同的性能需求。此外，微服务架构还提供了更好的可扩展性，提供持续集成和持续交付(CI/CD)，以快速部署和发布新的功能和更新。微服务上线后，需要全面测试各个微服务的功能，确保拆分后的服务可以正常运行、RPC调用正常、满足预期功能。

最后是流量迁移。当微服务架构正常运行后，将外部流量逐步迁移至新的RPC网关层，停止对community-single的访问，完成从单体架构到微服务架构的过渡。后端服务的扩展和升级将主要在微服务层进行。

通过上述步骤，将单体服务community-single拆分为微服务是一个复杂而耗时的过程，通过系统分析、功能拆分、技术选型、API设计和迁移策略等步骤，实现系统的微服务化，并提升系统的可扩展性、可靠性和性能。微服务架构也带来了分布式事务、运维成本增加等新的挑战，需要综合考虑多个因素。通过持续的评估和优化，可以不断提升系统的灵活性和可维护性，以适应不断变化的业务需求。

community-cluster 介绍

community-cluster是由 gRPC服务 和 rpc网关服务 这两种服务类型组成，gRPC服务是各个功能的实现模块，rpc网关服务主要作用是转发请求给gRPC服务和组装数据。community-cluster服务集群由工具sponge搭建，sponge生成gRPC服务和rpc网关服务代码时都会自动剥离业务逻辑与非业务逻辑两部分代码，剥离业务逻辑与非业务逻辑的好处是让开发者聚焦在核心业务逻辑代码中，极大的减小搭建微服务集群的难度，减少人工编写大量代码。框架图如下图所示：

gRPC服务代码组成结构基于grpc封装，包括了丰富的服务治理插件、构建、部署脚本，gRPC服务代码组成结构如下图所示：

图1 gRPC服务代码结构图

从图1可以看出，开发一个完整的微服务聚焦在定义数据表、定义api接口、在模板代码中编写具体业务逻辑代码这3个节点上，而这3个节点代码在单体web服务community-single已经存在，不需要重新编写，直接把这些代码移植过来即可，也就是蛋黄(核心业务逻辑代码)保持不变，只需换蛋壳(web框架换成gRPC框架)和蛋白(http handler相关代码换成rpc service相关代码)，使用工具sponge，很容易完成web服务到gRPC服务的转换。

rpc网关服务代码基于gin封装，包括了丰富的服务治理插件、构建、部署脚本，rpc网关服务代码组成结构如下图所示：

图2 rpc网关服务代码结构图

从图2可以看出，开发一个完整rpc网关服务聚焦在定义api接口、在模板代码中编写具体业务逻辑代码这2个节点上，其中定义api接口在单体web服务community-single已经存在，不需要重新编写，复制proto文件过来就可以使用。

这是单体web服务和微服务集群依赖的proto文件对比图，左边是单体web服务依赖的proto文件，所有proto文件都在同一个服务中。右边是微服务依赖的proto文件，根据各个gRPC服务依赖自己的proto文件。

在rpc网关服务中，如果需要从多个微服务中获取的数据组装成一个新的api接口，把这个组装的新api接口描述信息填写到community_gw.proto文件中。

下面使用工具sponge从0开始到完成微服务集群过程，开发过程依赖工具sponge，需要先安装sponge，点击查看安装说明。

创建一个目录community-cluster，把各个独立微服务代码移动到这个目录下。

gRPC服务

创建user、relation、creation服务

进入sponge的UI界面，点击左边菜单栏【Protobuf】–> 【RPC类型】–>【创建rpc项目】，填写参数，分别生成三个微服务代码。

创建user服务

这是从单体服务community-single复制过来的proto文件user.proto，用来快速生成用户(user)服务代码，如下图所示：

解压代码，把目录名称改为user，然后把user目录移动community-cluster目录下。

创建relation服务

这是从单体服务community-single复制过来的proto文件relation.proto，用来快速生成关系(relation)服务，如下图所示：

解压代码，把目录名称改为relation，然后把relation目录移动community-cluster目录下。

创建creation服务

这是从单体服务community-single复制过来的proto文件post.proto、comment.proto、like.proto、collect.proto，快速生成创作(creation)服务，如下图所示：

解压代码，把目录名称改为creation，然后把creation目录移动community-cluster目录下。

经过简单的界面操作就创建了三个gRPC服务(user、relation、creation)，也就是完成了各个gRPC服务各自的图1中蛋壳部分，接下来完成图1中蛋白和蛋黄两部分代码。

编写user、relation、creation服务的业务逻辑代码

从上面图1中微服务鸡蛋模型解剖图看出，经过sponge剥离后的业务逻辑代码只包括蛋白和蛋黄两部分，编写业务逻辑代码都是围绕这两部分开展。

编写user服务业务逻辑代码

分三个步骤编写user服务业务逻辑代码。

第一步 生成模板代码，进入项目user目录，打开终端，执行命令：

make proto

这个命令生成了api接口模板代码、api接口错误码、rpc客户端测试代码和pb.go相关代码，这些代码对应图1中蛋白部分。

• api接口模板代码，在internal/service目录下，文件名称与proto文件名一致，后缀名是_login.go，文件里面的方法函数与proto文件定义的rpc方法名一一对应，默认每个方法函数下有简单的使用示例，只需在每个方法函数里面编写具体的逻辑代码。
• api接口错误码，在internal/ecode目录下，文件名称与proto文件名一致，后缀是_rpc.go，文件里面的默认错误码变量与proto文件定义的rpc方法名一一对应，在这里添加或更改业务相关的错误码，注意错误码不能重复，否则会触发panic。
• rpc客户端测试代码，在internal/service目录下，文件名称与proto文件名一致，后缀是_client_test.go，文件里面的方法函数与proto文件定义的rpc方法名一一对应，填写参数，就可以每个rpc方法。

第二步 迁移dao代码，把单体web服务community-single目录中的internal/model、internal/cache、internal/dao、,internal/ecode这四个目录下user开头的代码文件，复制到user服务目录下，复制后的目录和文件名称不变。复制的这些代码对应图1中蛋白部分。

第三步 迁移具体逻辑代码，把单体web服务community-single代码文件internal/handler/user_logic.go各个方法函数下的具体逻辑代码，复制到user服务代码文件internal/service/user_logic.go同名的函数下。这些代码是图1中蛋黄的编写业务逻辑代码部分。

编写relation服务业务逻辑代码

分三个步骤编写relation服务业务逻辑代码，参考上面user服务的三个步骤。

编写creation服务业务逻辑代码

分三个步骤编写creation服务业务逻辑代码，参考上面user服务的三个步骤。

测试user、relation、creation服务的rpc方法

测试user服务的rpc方法

编写了业务逻辑代码后，启动服务来测试rpc方法，在第一次启动服务前，先打开配置文件(user/configs/user.yml)设置mysql和redis地址、设置grpc和grpcClient相关参数，然后执行命令编译启动服务：

# 编译、运行服务
make run

在goland IDE打开user服务代码，进入user/internal/service目录，找到后缀为_client_test.go的代码文件，在各个rpc方法填写参数后进行测试。

测试relation服务的rpc方法

测试relation服务的rpc方法，请参考上面user服务的测试rpc方法。

测试creation服务的rpc方法

测试creation服务的rpc方法，请参考上面user服务的测试rpc方法。

rpc网关服务

完成了user、relation、creation这三个服务后，接着需要完成rpc网关服务community_gw，community_gw作为user、relation、creation服务的统一入口。

创建community_gw服务

进入sponge的UI界面，点击左边菜单栏【Protobuf】–> 【Web类型】–>【创建rpc网关项目】，填写一些参数生成rpc网关服务代码。

这是从单体服务community-single复制过来的proto文件user_gw.proto、relation_gw.proto、post_gw.proto、comment_gw.proto、like_gw.proto、collect_gw.proto，快速创建rpc网关服务community_gw，如下图所示：

解压代码，把目录名称改为community_gw。

因为community_gw服务作为请求入口，使用rpc方式与user、relation、creation通信，因此需要生成连接user、relation、creation服务的代码。进入sponge的UI界面，点击左边菜单栏【Public】–>【生成rpc服务连接代码】，填写一些参数生成rpc服务连接代码，如下图所示：

解压代码，把目录internal移动到community_gw服务目录下，然后把community_gw移动到community_cluster目录下。

同时把user、relation、creation三个服务的proto文件复制到community_gw的api目录下，如下列表所示。其中community_gw的v1目录下的proto文件是定义http的api接口信息，建议统一约定后缀名_gw.proto。

.
├── community_gw
│   └── v1
│       ├── collect_gw.proto
│       ├── comment_gw.proto
│       ├── like_gw.proto
│       ├── post_gw.proto
│       ├── relation_gw.proto
│       └── user_gw.proto
├── creation
│   └── v1
│       ├── collect.proto
│       ├── comment.proto
│       ├── like.proto
│       └── post.proto
├── relation
│   └── v1
│       └── relation.proto
└── user
    └── v1
        └── user.proto

通过简单的操作就完成创建了rpc网关服务community_gw。

编写community_gw服务的业务逻辑代码

从上面图2中rpc网关代码鸡蛋模型解剖图看出，经过sponge剥离后的业务逻辑代码只包括蛋白和蛋黄两部分，编写业务逻辑代码都是围绕这两部分开展。

编写与proto文件相关的业务逻辑代码

进入项目community-gw目录，打开终端，执行命令：

make proto

这个命令是根据community_gw/api/community_gw/v1目录下的proto文件生成了api接口模板代码、注册路由代码、api接口错误码、swagger文档和相关的pb.go代码，也就是图2中的蛋白部分。

(1) api接口模板代码，在community_gw/internal/service目录下，文件名称与proto文件名一致，后缀名是_logic.go，名称分别有：

collect_gw_logic.go, comment_gw_logic.go, like_gw_logic.go, post_gw_logic.go, relation_gw_logic.go, user_gw_logic.go

在这些文件里面的方法函数与proto文件定义的rpc方法名一一对应，每个方法函数下有默认的使用示例，只需要简单调整就可以调用user、relation、creation服务端的rpc方法。上面那些文件代码是已经编写具体逻辑之后的代码。

(2) 注册路由代码，在community_gw/internal/routers目录下，文件名称与proto文件名一致，后缀名是_router.go，名称分别有：

collect_gw_router.go, comment_gw_router.go, like_gw_router.go, post_gw_router.go, relation_gw_router.go, user_gw_router.go

在这些文件里面的设置api接口的中间件，例如jwt鉴权，每个接口都已经存在中间件模板代码，只需要取消注释代码就可以使中间件生效，只需要取消注释代码就可以使中间件生效，支持路由分组和单独路由来设置gin中间件。

(3) api接口错误码，在community_gw/internal/ecode目录下，文件名称与proto文件名一致，后缀是_rpc.go，名称分别有：

collect_gw_rpc.go, comment_gw_rpc.go, like_gw_rpc.go, post_gw_rpc.go, relation_gw_rpc.go, user_gw_rpc.go

在这些文件里面的默认错误码变量与proto文件定义的rpc方法名一一对应，在这里添加或更改业务相关的错误码，注意错误码不能重复，否则会触发panic。

注： 如果调用的rpc方法本身包含了错误码，可以直接返回该错误码。

(4) swagger文档，在community_gw/docs目录下，名称为apis.swagger.json

如果在proto文件添加或更改了api接口，都需要再执行一次命令make proto即可，会自动把新生成代码自动合并到对应文件代码中，不用担心合并代码中会丢失已编写的业务逻辑代码问题，可以在/tmp/sponge_merge_backup_code目录下可以找到合并前的代码备份。

make proto命令生成的代码是用来连接web框架代码和业务逻辑核心代码的桥梁，也就是图2中的蛋白部分，通过分层生成代码的好处是减少编写代码。

测试api接口

编写了业务逻辑代码后，启动服务测试api接口，在第一次启动服务前，先打开配置文件(community_gw/configs/community_gw.yml)设置连接rpc服务配置信息，如下所示：

# grpc client settings, support for setting up multiple rpc clients
grpcClient:
  - name: "user"
    host: "127.0.0.1"
    port: 18282
    registryDiscoveryType: ""
    enableLoadBalance: false
  - name: "relation"
    host: "127.0.0.1"
    port: 28282
    registryDiscoveryType: ""
    enableLoadBalance: false
  - name: "creation"
    host: "127.0.0.1"
    port: 38282
    registryDiscoveryType: ""
    enableLoadBalance: false

执行命令编译启动服务：

# 编译、运行服务
make run

在浏览器访问 http://localhost:8080/apis/swagger/index.htm ，进入swagger界面，如下图所示：

从图中看到有些api接口右边有一把锁标记，表示请求头会携带鉴权信息Authorization，服务端接收到请求是否做鉴权，由服务端决定，如果服务端需要做鉴权，可以在community_gw/internal/routers目录下后缀文件为_router.go文件中设置，也就是取消鉴权的注释代码，使api接口的鉴权中间件生效。

服务治理

gRPC服务(user、relation、creation)和rpc网关服务(community-gw)都包含了丰富的服务治理插件(日志、限流、熔断、链路跟踪、服务注册与发现、指标采集、性能分析、资源统计、配置中心)，有些服务治理插件默认是关闭的，根据实际需要开启使用。

除了服务本身提供的治理插件，也可以使用自己的服务治理插件，添加自己的服务治理插件说明：

• 对于gRPC服务(user、relation、creation)，在代码文件服务名称/internal/server/grpc.go里添加自己的插件，如果你的服务治理插件(拦截器)属于unary类型，添加到unaryServerOptions函数里面。如果你的服务治理插件(拦截器)属于stream类型，添加到streamServerOptions函数里面。
• 对于rpc网关服务community-gw，在代码文件community-gw/internal/routers/routers.go里添加自己的插件(gin中间件)。

下面是默认的服务治理插件开启和设置说明，统一在各自服务配置文件服务名称/configs/服务名称.yml进行设置。

日志

日志插件(zap)默认是开启的，默认是输出到终端，默认输出日志格式是console，可以设置输出格式为json，设置日志保存到指定文件，日志文件切割和保留时间。

在配置文件里的字段logger设置：

# logger 设置
logger:
  level: "info"             # 输出日志级别 debug, info, warn, error，默认是debug
  format: "console"     # 输出格式，console或json，默认是console
  isSave: false           # false:输出到终端，true:输出到文件，默认是false
  logFileConfig:          # isSave=true时有效
    filename: "out.log"            # 文件名称，默认值out.log
    maxSize: 20                     # 最大文件大小(MB)，默认值10MB
    maxBackups: 50               # 保留旧文件的最大个数，默认值100个
    maxAge: 15                     # 保留旧文件的最大天数，默认值30天
    isCompression: true          # 是否压缩/归档旧文件，默认值false

限流

限流插件默认是关闭的，自适应限流，不需要设置其他参数。

在配置文件里的字段enableLimit设置：

  enableLimit: false    # 是否开启限流(自适应)，true:开启, false:关闭

熔断

熔断插件默认是关闭的，自适应熔断，支持自定义错误码(默认500和503)触发熔断，在internal/routers/routers.go设置。

在配置文件里的字段enableCircuitBreaker设置：

  enableCircuitBreaker: false    # 是否开启熔断(自适应)，true:开启, false:关闭

链路跟踪

链路跟踪插件默认是关闭的，链路跟踪依赖jaeger服务。

在配置文件里的字段enableTrace设置：

  enableTrace: false    # 是否开启追踪，true:启用，false:关闭，如果是true，必须设置jaeger配置。
  tracingSamplingRate: 1.0      # 链路跟踪采样率, 范围0~1.0浮点数, 0表示不采样, 1.0表示采样所有链路


# jaeger 设置
jaeger:
  agentHost: "192.168.3.37"
  agentPort: 6831

在jaeger界面上查看链路跟踪信息文档说明。

服务注册与发现

服务注册与发现插件默认是关闭的，支持consul、etcd、nacos三种类型。

在配置文件里的字段registryDiscoveryType设置：

  registryDiscoveryType: ""    # 注册和发现类型：consul、etcd、nacos，如果为空表示关闭服务注册与发现。


# 根据字段registryDiscoveryType值来设置参数，例如使用consul作为服务发现，只需设置consul。
# consul 设置
consul:
  addr: "192.168.3.37:8500"

# etcd 设置
etcd:
  addrs: ["192.168.3.37:2379"]

# nacos 设置
nacosRd:
  ipAddr: "192.168.3.37"
  port: 8848
  namespaceID: "3454d2b5-2455-4d0e-bf6d-e033b086bb4c" # namespace id

指标采集

指标采集功能默认是开启的，提供给prometheus采集数据，默认路由是/metrics。

在配置文件里的字段enableMetrics设置：

  enableMetrics: true    # 是否开启指标采集，true：启用，false：关闭

使用prometheus和grafana采集指标和监控服务的文档说明。

性能分析

性能分析插件默认是关闭的，采集profile的默认路由是/debug/pprof，除了支持go语言本身提供默认的profile分析，还支持io分析，路由是/debug/pprof/profile-io。

在配置文件里的字段enableHTTPProfile设置：

  enableHTTPProfile: false    # 是否开启性能分析，true：启用，false：关闭

通过路由采集profile进行性能分析方式，通常在开发或测试时使用，如果线上开启会有一点点性能损耗，因为程序后台一直定时记录profile相关信息。sponge生成的服务本身对此做了一些改进，平时停止采集profile，用户主动触发系统信号时才开启和关闭采集profile，采集profile保存到/tmp/服务名称_profile目录，默认采集为60秒，60秒后自动停止采集profile，如果只想采集30秒，发送第一次信号开始采集，大概30秒后发送第二次信号表示停止采集profile，类似开关一样。

这是采集profile操作步骤：

# 通过名称查看服务pid
ps aux | grep 服务名称

# 发送信号给服务
kill -trap pid值

注：只支持linux、darwin系统。

资源统计

资源统计插件默认是开启的，默认每分钟统计一次并输出到日志，资源统计了包括系统和服务本身这两部分的cpu和内存相关的数据。

资源统计还包含了自动触发采集profile功能，当连续3次统计本服务的CPU或内存平均值，CPU或内存平均值占用系统资源超过80%时，自动触发采集profile，默认采集为60秒，采集profile保存到/tmp/服务名称_profile目录，从而实现了自适应采集profile，比通过人工发送系统信号来采集profile又改进了一步。

在配置文件里的字段enableHTTPProfile设置：

  enableStat: true    # 是否开启资源统计，true:启用，false:关闭

配置中心

目前支持nacos作为配置中心，配置中心文件configs/user_cc.yml，配置内容如下：

# nacos 设置
nacos:
  ipAddr: "192.168.3.37"    # 服务地址
  port: 8848                      # 监听端口
  scheme: "http"                # 支持http和https
  contextPath: "/nacos"       # 路径
  namespaceID: "3454d2b5-2455-4d0e-bf6d-e033b086bb4c" # namespace id
  group: "dev"                    # 组名称: dev, prod, test
  dataID: "community.yml"  # 配置文件id
  format: "yaml"                 # 配置文件类型: json,yaml,toml

而服务的配置文件configs/user.yml复制到nacos界面上配置。使用nacos配置中心，启动服务命令需要指定配置中心文件，命令如下：

./user -c configs/user_cc.yml -enable-cc

使用nacos作为配置中心的文档说明。

持续集成与部署

sponge生成的gRPC和rpc网关服务包括了编译和部署脚本，编译支持二进制编译和docker镜像构建，部署支持二进制部署、docker部署、k8s部署三种方式，这些功能都统一集成在Makefile文件里，使用make命令就可以很方便的执行指定编译或部署服务。

除了使用make命令编译和部署，还支持自动化部署工具Jenkins，默认的Jenkins设置在文件Jenkinsfile，支持自动化部署到k8s，如果需要二进制或docker部署，需要对Jenkinsfile进行修改。

使用Jenkins持续集成和部署的文档说明。

服务压测

压测服务时使用的一些工具：

• http压测工具wrk或go-stress-testing。
• 服务开启指标采集功能，使用prometheus采集服务指标和系统指标进行监控。
• 服务本身的自适应采集profile功能。

压测指标：

• 并发度: 逐渐增加并发用户数，找到服务的最大并发度，确定服务能支持的最大用户量。
• 响应时间: 关注并发用户数增加时，服务的平均响应时间和响应时间分布情况。确保即使在高并发下，响应时间也在可接受范围内。
• 错误率: 观察并发增加时，服务出现错误或异常的概率。使用压测工具进行长时间并发测试，统计各并发级别下的错误数量和类型。
• 吞吐量: 找到服务的最大吞吐量，确定服务在高并发下可以支持的最大请求量。这需要不断增加并发，直到找到吞吐量饱和点。
• 资源利用率: 关注并发增加时，CPU、内存、磁盘I/O、网络等资源的利用率，找到服务的资源瓶颈。
• 瓶颈检测: 通过观察高并发情况下服务的性能指标和资源利用率，找到系统和服务的硬件或软件瓶颈，以便进行优化。
• 稳定性: 长时间高并发运行可以检测到服务存在的潜在问题，如内存泄露、连接泄露等，确保服务稳定运行。这需要较长时间的并发压测，观察服务运行指标。

对服务进行压测，主要是为了评估其性能，确定能支持的最大并发和吞吐量，发现当前的瓶颈，并检测服务运行的稳定性，以便进行优化或容量规划。

总结

本文介绍了把单体服务community-single拆分为微服务集群community-cluster的具体实践过程，微服务集群包括了用户服务(user)、关系服务(relation)和内容创作服务(creation)三个独立的服务，一个微服务入口的网关服务(community_gw)，这些服务代码(图1和图2中的蛋壳和蛋白部分)都是由工具sponge生成，核心业务逻辑代码是直接手动无缝移植，基本不需要重复编写代码，减少了大量工作量，从而提高了效率。

如果不是从单体服务拆分为微服务，而是项目一开始采用微服务集群，使用sponge开发的步骤也是一样，一开始采用微服务集群时，核心业务逻辑代码(图1和图2中的蛋黄部分)需要人工编写。

使用工具sponge从开发到部署gRPC服务具体流程如下：

1. 定义mysql表
2. 在proto文件定义api接口
3. 生成gRPC服务框架代码
4. 根据proto文件生成业务逻辑相关代码
5. 根据mysql表生成dao代码
6. 在api接口模板文件中编写具体逻辑代码
7. 在生成的rpc客户端代码中测试验证api接口
8. 按需启用服务治理功能
9. 持续集成与部署
10. 服务压测

开发一个完整的gRPC服务，真正需要人工编写代码的只有1、2、6这三个核心业务代码。

使用工具sponge从开发到部署rpc网关服务具体流程如下：

1. 在proto文件定义api接口
2. 生成rpc网关服务框架代码
3. 生成prc服务连接代码
4. 根据proto文件生成业务逻辑相关代码
5. 在api接口模板文件中编写具体逻辑代码
6. 在swagger页面测试验证api接口
7. 按需启用服务治理功能
8. 持续集成与部署
9. 服务压测

开发一个完整的rpc网关服务，真正需要人工编写代码的只有1、5这两个核心业务代码。

使用工具sponge很容易开发一个完整的微服务集群，微服务集群的优点：

• 高性能：基于 Protobuf 的高性能通信协议，同时具备高并发处理和低延迟的特点。
• 可扩展性：丰富的插件和组件机制，开发者可以根据实际需求定制和扩展框架功能。
• 高可靠性：提供了服务注册和发现、限流、熔断、链路、监控告警等功能，提升了微服务的可靠性。

本文链接：https://zhuyasen.com/post/community-cluster.html，参与评论 »

community-single 介绍

community-single是一个极简版社区的后端服务，主要包括用户的注册、登录、关注等功能，创作内容(文本、图片、视频)的发布、评论、点赞、收藏等功能，这些功能在各个社区平台、视频平台、直播平台等都比较常见，可以作为学习参考用，点击查看完整的项目代码。

community-single项目一开始设计为单体web服务，整个服务由生成代码工具sponge辅助完成，sponge生成web服务代码过程中剥离了业务逻辑与非业务逻辑两部分代码，这里的非业务逻辑代码指的是web服务框架代码，主要包括：

• 经过封装的gin代码
• 服务治理(日志、限流、熔断、链路跟踪、服务注册与发现、指标采集、性能分析、配置中心、资源统计等)
• 编译构建和部署脚本(二进制、docker、k8s)
• CI/CD(jenkins)

除了web服务框架代码，其他都属于业务逻辑代码。

把一个完整web服务代码看作一个鸡蛋，蛋壳表示web服务框架代码，蛋白和蛋黄都表示业务逻辑代码，蛋黄是业务逻辑的核心(需要人工编写的代码)，例如定义mysql表、定义api接口、编写具体逻辑代码都属于蛋黄部分。蛋白是业务逻辑核心代码与web框架代码连接的桥梁(自动生成，不需要人工编写)，例如根据proto文件生成的注册路由代码、handler方法函数代码、参数校验代码、错误码、swagger文档等都属于蛋白部分。web服务鸡蛋模型剖析图如下图所示：

图1 web服务代码的组成结构图

因此开发一个完整web服务项目聚焦在了定义数据表、定义api接口、在模板代码中编写具体业务逻辑代码这3个节点上，也就是业务逻辑的核心代码(蛋黄)，其他代码(蛋壳和蛋白)是由sponge生成，可以帮助你少写很多代码，下面介绍从0开始到完成项目的开发过程。

开发过程依赖工具sponge，需要先安装sponge，点击查看安装说明。

定义数据表和api接口

根据业务需求，首先要定义数据表和api接口，这是业务逻辑代码核心(图1中的蛋黄部分)，后面需要根据数据表和api接口(IDL)来生成代码(图1中的蛋壳和蛋白两部分)。

定义数据表

这是已经定义好的mysql表 community.sql

定义api接口

在proto文件定义api接口、输入输出参数、路由等，下面是已经定义好的api接口的proto文件：

• user.proto
• relation.proto
• like.proto
• comment.proto
• collect.proto

开发中不大可能一次性就定义好业务所需的mysql表和api接口，增加或更改是很常见的事，修改mysql表和proto文件后，如何同步更新到代码里，在下面的编写业务逻辑代码章节中介绍。

生成项目代码

定义了数据表和api接口之后，然后在sponge的界面上根据proto文件生成web服务项目代码。进入sponge的UI界面，点击左边菜单栏【protobuf】–> 【Web类型】–>【创建web项目】，填写相关参数生成web项目代码，如下图所示：

解压代码，修改文件夹名称(例如community-single)，一个服务只需生成代码一次。 这就完成搭建了一个web服务的基本框架(图1中的蛋壳部分)，接着可以在web服务框架内编写业务逻辑代码了。

编写业务逻辑代码

从上面图1中web服务代码鸡蛋模型解剖图看出，经过sponge剥离后的业务逻辑代码包括蛋白和蛋黄两部分，编写业务逻辑代码基本都是围绕这两部分开展。

编写与proto文件相关的业务逻辑代码

进入项目community-single目录，打开终端，执行命令：

make proto

这个命令是根据api/community/v1目录下的proto文件生成了接口模板代码、注册路由代码、api接口错误码、swagger文档这四个部分代码，也就是图1中的蛋白部分。

(1) 生成的接口模板代码，在internal/handler目录下，文件名称与proto文件名一致，后缀名是_logic.go，名称分别有：

collect_logic.go, comment_logic.go, like_logic.go, post_logic.go, relation_logic.go, user_logic.go

在这些文件里面的方法函数与proto文件定义的rpc方法名一一对应，默认每个方法函数下有简单的使用示例，只需在每个方法函数里面编写具体的逻辑代码，上面那些文件代码是已经编写过具体逻辑之后的代码。

(2) 生成注册路由代码，在internal/routers目录下，文件名称与proto文件名一致，后缀名是_handler.pb.go，名称分别有：

collect_handler.pb.go, comment_handler.pb.go, like_handler.pb.go, post_handler.pb.go, relation_handler.pb.go, user_handler.pb.go

在这些文件里面的设置api接口的中间件，例如jwt鉴权，每个接口都已经存在中间件模板代码，只需要取消注释代码就可以使中间件生效，支持路由分组和单独路由来设置中间件。

(3) 生成接口错误码，在internal/ecode目录下，文件名称与proto文件名一致，后缀是_http.go，名称分别有：

collect_http.go, comment_http.go, like_http.go, post_http.go, relation_http.go, user_http.go

在这些文件里面的默认错误码变量与proto文件定义的rpc方法名一一对应，在这里添加或更改业务相关的错误码，注意错误码不能重复，否则会触发panic。

(4) 生成swagger文档，在docs目录下，名称为apis.swagger.json

如果在proto文件添加或更改了api接口，需要重新再执行一次命令make proto更新代码，会发现在internal/handler、internal/routers、internal/ecode目录下出现后缀名为日期时间的代码文件，打开文件，把新增或修改部分代码复制到同名文件代码中即可。复制完新增代码后，执行命令make clean清除这些日期后缀文件。

make proto命令生成的代码是用来连接web框架代码和业务逻辑核心代码的桥梁，也就是蛋白部分，这种分层生成代码的好处是减少编写代码。

编写与mysql表相关的业务逻辑代码

前面生成的web服务框架代码和根据proto文件生成的业务逻辑的部分代码，都还没有包括对mysql表的操作，因此需要根据mysql表生成dao(数据访问对象)代码，dao代码包括了对表的增删改查代码、缓存代码、model代码，这些代码属于图1中的蛋白部分。

进入sponge的UI界面，点击左边菜单栏【Public】–> 【生成dao CRUD代码】，填写相关参数生成dao代码，如下图所示：

解压dao代码，把internal目录移动到community-single目录下，这样就完成添加了对mysql表的增删改查操作方法。当有新添加的mysql表时，需要再次指定新的mysql表生成dao代码。

指定mysql表生成的dao代码包括三个部分。

(1) 生成model代码，在internal/model目录下，文件名称与mysql表名一致，分别有：

comment.go, commentContent.go, commentHot.go, commentLatest.go, post.go, postHot.go, postLatest.go, relationNum.go, user.go, userCollect.go, userComment.go, userFollower.go, userFollowing.go, userLike.go, userPost.go

这是生成的对应gorm的go结构体代码。

(2) 生成缓存代码，在internal/cache目录下文件，文件名称与mysql表名一致，分别有：

comment.go, commentContent.go, commentHot.go, commentLatest.go, post.go, postHot.go, postLatest.go, relationNum.go, user.go, userCollect.go, userComment.go, userFollower.go, userFollowing.go, userLike.go, userPost.go

编写业务代码过程中，为了提高性能，有可能使用到缓存，有时候对表的默认缓存(CRUD)不能满足要求，需要添加缓存代码，sponge支持一键生成缓存代码，点击左边菜单栏【Public】–> 【生成cache代码】，填写参数生成代码，然后把解压的internal目录移动到community-single目录下，然后在业务逻辑中直接调用缓存接口。

(3) 生成dao代码，在internal/dao目录下，文件名称与mysql表名一致，文件分别有：

comment.go, commentContent.go, commentHot.go, commentLatest.go, post.go, postHot.go, postLatest.go, relationNum.go, user.go, userCollect.go, userComment.go, userFollower.go, userFollowing.go, userLike.go, userPost.go

编写业务代码过程中会涉及到操作mysql表，有时候对表的默认操作(CRUD)不能满足要求，这时需要人工编写自定义操作mysql表的函数方法与实现代码，例如comment.go、post.go等都包含少部分人工定义的操作msyql表的方法函数。

在开发过程中有时会修改或新增mysql表，基于mysql表生成的代码需要同步到项目代码中，分为两种情况处理：

• 修改mysql表之后更新代码处理方式：只需根据修改后的表生成新model代码，替换旧的model代码。点击左边菜单栏【Public】–> 【生成model代码】，填写参数，选择更改的mysql表，然后把解压的internal目录移动到community-single目录下，并确认替换。
• 新增mysql表之后处理方式：只需根据新增的表生成新的dao代码，添加到项目目录下。点击左边菜单栏【Public】–> 【生成dao代码】，填写参数，选择新增的mysql表，然后把解压的internal目录移动到community-single目录下。

测试api接口

编写了业务逻辑代码后，启动服务测试api接口，在第一次启动服务前，先打开配置文件(configs/community.yml)设置mysql和redis地址，然后执行命令编译启动服务：

# 编译、运行服务
make run

在浏览器访问 http://localhost:8080/apis/swagger/index.htm ，进入swagger界面，如下图所示：

从图中看到有些api接口右边有一把锁标记，表示请求头会携带鉴权信息Authorization，服务端接收到请求是否做鉴权，由服务端决定，如果服务端需要做鉴权，可以在internal/routers目录下后缀文件为_handler.pb.go文件中设置，也就是取消鉴权的注释代码，使api接口的鉴权中间件生效。

服务治理

生成的web服务代码中包含了丰富的服务治理插件，有些服务治理插件默认是关闭的，根据实际需要开启使用，统一在配置文件configs/community.yml进行设置。

除了web服务提供的服务治理插件，也可以使用自己的服务治理插件，建议在internal/routers/routers.go引入自己的服务治理插件。

日志

日志插件(zap)默认是开启的，默认是输出到终端，默认输出日志格式是console，可以设置输出格式为json，设置日志保存到指定文件，日志文件切割和保留时间。

在配置文件里的字段logger设置：

# logger 设置
logger:
  level: "info"             # 输出日志级别 debug, info, warn, error，默认是debug
  format: "console"     # 输出格式，console或json，默认是console
  isSave: false           # false:输出到终端，true:输出到文件，默认是false
  logFileConfig:          # isSave=true时有效
    filename: "out.log"            # 文件名称，默认值out.log
    maxSize: 20                     # 最大文件大小(MB)，默认值10MB
    maxBackups: 50               # 保留旧文件的最大个数，默认值100个
    maxAge: 15                     # 保留旧文件的最大天数，默认值30天
    isCompression: true          # 是否压缩/归档旧文件，默认值false

限流

限流插件默认是关闭的，自适应限流，不需要设置其他参数。

在配置文件里的字段enableLimit设置：

  enableLimit: false    # 是否开启限流(自适应)，true:开启, false:关闭

熔断

熔断插件默认是关闭的，自适应熔断，支持自定义错误码(默认500和503)触发熔断，在internal/routers/routers.go设置。

在配置文件里的字段enableCircuitBreaker设置：

  enableCircuitBreaker: false    # 是否开启熔断(自适应)，true:开启, false:关闭

链路跟踪

链路跟踪插件默认是关闭的，链路跟踪依赖jaeger服务。

在配置文件里的字段enableTrace设置：

  enableTrace: false    # 是否开启追踪，true:启用，false:关闭，如果是true，必须设置jaeger配置。
  tracingSamplingRate: 1.0      # 链路跟踪采样率, 范围0~1.0浮点数, 0表示不采样, 1.0表示采样所有链路


# jaeger 设置
jaeger:
  agentHost: "192.168.3.37"
  agentPort: 6831

在jaeger界面上查看链路跟踪信息文档说明。

服务注册与发现

服务注册与发现插件默认是关闭的，支持consul、etcd、nacos三种类型。

在配置文件里的字段registryDiscoveryType设置：

  registryDiscoveryType: ""    # 注册和发现类型：consul、etcd、nacos，如果为空表示关闭服务注册与发现。


# 根据字段registryDiscoveryType值来设置参数，例如使用consul作为服务发现，只需设置consul。
# consul 设置
consul:
  addr: "192.168.3.37:8500"

# etcd 设置
etcd:
  addrs: ["192.168.3.37:2379"]

# nacos 设置
nacosRd:
  ipAddr: "192.168.3.37"
  port: 8848
  namespaceID: "3454d2b5-2455-4d0e-bf6d-e033b086bb4c" # namespace id

指标采集

指标采集功能默认是开启的，提供给prometheus采集数据，默认路由是/metrics。

在配置文件里的字段enableMetrics设置：

  enableMetrics: true    # 是否开启指标采集，true：启用，false：关闭

使用prometheus和grafana采集指标和监控服务的文档说明。

性能分析

性能分析插件默认是关闭的，采集profile的默认路由是/debug/pprof，除了支持go语言本身提供默认的profile分析，还支持io分析，路由是/debug/pprof/profile-io。

在配置文件里的字段enableHTTPProfile设置：

  enableHTTPProfile: false    # 是否开启性能分析，true：启用，false：关闭

通过路由采集profile进行性能分析方式，通常在开发或测试时使用，如果线上开启会有一点点性能损耗，因为程序后台一直定时记录profile相关信息。sponge生成的web服务对此做了一些改进，平时停止采集profile，用户主动触发系统信号时才开启和关闭采集profile，采集profile保存到/tmp/服务名称_profile目录，默认采集为60秒，60秒后自动停止采集profile，如果只想采集30秒，发送第一次信号开始采集，大概30秒后发送第二次信号表示停止采集profile，类似开关一样。

这是采集profile操作步骤：

# 通过名称查看服务pid
ps aux | grep 服务名称

# 发送信号给服务
kill -trap pid值

注：只支持linux、darwin系统。

资源统计

资源统计插件默认是开启的，默认每分钟统计一次并输出到日志，资源统计了包括系统和服务本身这两部分的cpu和内存相关的数据，资源统计包含了自动触发采集profile功能，当连续3次统计本服务的CPU或内存平均值，CPU或内存平均值占用系统资源超过80%时，自动触发采集profile，默认采集为60秒，采集profile保存到/tmp/服务名称_profile目录，从而实现自适应采集profile，比通过人工发送系统信号来采集profile又改进了一步。

在配置文件里的字段enableHTTPProfile设置：

  enableStat: true    # 是否开启资源统计，true:启用，false:关闭

配置中心

目前支持nacos作为配置中心，配置中心文件configs/community_cc.yml，配置内容如下：

# nacos 设置
nacos:
  ipAddr: "192.168.3.37"    # 服务地址
  port: 8848                      # 监听端口
  scheme: "http"                # 支持http和https
  contextPath: "/nacos"       # 路径
  namespaceID: "3454d2b5-2455-4d0e-bf6d-e033b086bb4c" # namespace id
  group: "dev"                    # 组名称: dev, prod, test
  dataID: "community.yml"  # 配置文件id
  format: "yaml"                 # 配置文件类型: json,yaml,toml

而服务的配置文件configs/community.yml复制到nacos界面上配置。使用nacos配置中心，启动服务命令需要指定配置中心文件，命令如下：

./community -c configs/community_cc.yml -enable-cc

使用nacos作为配置中心的文档说明。

持续集成与部署

sponge生成的web服务包括了编译和部署脚本，编译支持二进制编译和docker镜像构建，部署支持二进制部署、docker部署、k8s部署三种方式，这些功能都统一集成在Makefile文件里，使用make命令就可以很方便的执行指定编译或部署服务。

除了使用make命令编译和部署，还支持自动化部署工具Jenkins，默认的Jenkins设置在文件Jenkinsfile，支持自动化部署到k8s，如果需要二进制或docker部署，需要对Jenkinsfile进行修改。

使用Jenkins持续集成和部署的文档说明。

服务压测

压测服务时使用的一些工具：

• http压测工具wrk或go-stress-testing。
• 服务开启指标采集功能，使用prometheus采集服务指标和系统指标进行监控。
• 服务本身的自适应采集profile功能。

压测指标：

• 并发度: 逐渐增加并发用户数，找到服务的最大并发度，确定服务能支持的最大用户量。
• 响应时间: 关注并发用户数增加时，服务的平均响应时间和响应时间分布情况。确保即使在高并发下，响应时间也在可接受范围内。
• 错误率: 观察并发增加时，服务出现错误或异常的概率。使用压测工具进行长时间并发测试，统计各并发级别下的错误数量和类型。
• 吞吐量: 找到服务的最大吞吐量，确定服务在高并发下可以支持的最大请求量。这需要不断增加并发，直到找到吞吐量饱和点。
• 资源利用率: 关注并发增加时，CPU、内存、磁盘I/O、网络等资源的利用率，找到服务的资源瓶颈。
• 瓶颈检测: 通过观察高并发情况下服务的性能指标和资源利用率，找到系统和服务的硬件或软件瓶颈，以便进行优化。
• 稳定性: 长时间高并发运行可以检测到服务存在的潜在问题，如内存泄露、连接泄露等，确保服务稳定运行。这需要较长时间的并发压测，观察服务运行指标。

对服务进行压测，主要是为了评估其性能，确定能支持的最大并发和吞吐量，发现当前的瓶颈，并检测服务运行的稳定性，以便进行优化或容量规划。

总结

community-single是使用工具sponge从开发到部署的实战项目示例，具体流程如下：

1. 定义mysql表
2. 在proto文件定义api接口
3. 根据proto文件生成web框架代码
4. 根据proto文件生成业务逻辑相关代码
5. 根据mysql表生成dao代码
6. 在指定模板文件中编写具体逻辑代码
7. 在swagger测试验证api接口
8. 按需启用服务治理功能
9. 持续集成与部署
10. 服务压测

看起来流程有点多，真正需要人工编写代码的只有1、2、6这三个核心业务流程，其他流程涉及到的代码或脚本由sponge生成，使用sponge剥离非业务逻辑代码和业务逻辑代码，让开发项目时只需要聚焦在业务逻辑的核心代码上，同时也使得项目代码变得规范统一，不同的程序员都可以迅速上手。再结合编程辅助工具Copilot或Codeium写代码，开发变得更高效、轻松。

community-single是单体web服务，随着需求增加，功能越来越复杂，使得代码维护和开发变得困难，可以拆分成多个微服务，web单体服务拆分成微服务过程，只换了蛋壳(web框架换成gRPC框架)和蛋白(http handler相关代码换成rpc service相关代码)，蛋黄(核心业务逻辑代码)不变，核心业务逻辑代码可以无缝的移植到微服务代码中。在下一篇文章介绍使用工具sponge辅助完成把community-single拆分为微服务集群。

本文链接：https://zhuyasen.com/post/community-single.html，参与评论 »

sponge 介绍

sponge 是一个强大的 Go 开发框架，其核心理念是通过解析 SQL、Protobuf、JSON 文件逆向生成模块化的代码，这些模块代码可灵活组合成多种类型的完整后端服务（类似海绵细胞的特性，打散的海绵细胞能自动重新组合成新的海绵）。sponge 拥有出色的项目工程化能力，提供一站式项目开发解决方案，涵盖代码生成、开发、测试、API 文档生成和部署。sponge 通过模块化架构与AI助手深度融合，大幅提升开发效率、降低技术门槛，助力开发者以”低代码”方式轻松构建稳定可靠的后端系统。

github地址： https://github.com/go-dev-frame/sponge

适用场景

sponge 适用于快速构建多种类型的高性能后端服务，包括但不限于：

• RESTful API 服务
• Web 服务 (基于Gin)
• gRPC 服务
• HTTP+gRPC 混合服务
• gRPC Gateway API 服务
• 云原生微服务

此外，开发者还可以通过自定义模板，生成满足业务需求的各类代码。

核心优势

1. 一键生成完整后端服务代码
   对于仅需 CRUD API 的 Web 或 gRPC 服务，无需编写任何 Go 代码。只需连接数据库(如 MySQL、MongoDB、PostgreSQL、SQLite)，即可一键生成完整后端服务代码，并轻松部署到 Linux 服务器、Docker 或 Kubernetes 上。

2. 高效开发通用服务
   开发通用的 Web、gRPC、HTTP+gRPC 或 gRPC Gateway 服务，只需专注于以下三部分：

   • 数据库表的定义；
   • 在 Protobuf 文件中定义 API 描述信息；
   • 在生成的模板中，使用内置AI助手或人工编写业务逻辑代码。
     

服务的框架代码和 CRUD API 代码均由 sponge 自动生成。

1. 支持自定义模板，灵活扩展
   sponge 支持通过自定义模板生成项目所需的多种代码类型，不局限于 Go 语言。例如：

   • 后端代码；
   • 前端代码；
   • 配置文件；
   • 测试代码；
   • 构建和部署脚本等。

2. 在页面生成代码，简单易用
   sponge 提供在页面生成代码，避免了复杂的命令行操作，只需在页面上简单的填写参数即可一键生成代码。

3. 与 AI 助手协同开发，形成开发闭环
   sponge 与 内置的 AI 助手(DeepSeek、ChatGPT、Gemini)深度融合，形成一套完整的高效开发解决方案：

   • sponge：负责基础设施代码生成(服务框架、CRUD API 接口、自定义 API 接口代码(缺少业务逻辑)等)。
   • AI助手：专注业务逻辑实现(表结构 DDL 设计、自定义 API 接口定义、业务逻辑实现代码)。

快速开始

1. 安装 sponge 支持在 windows、mac、linux 环境下安装 sponge，点击查看 安装 sponge 说明。

2. 打开生成代码 UI 页面 安装完成后，执行命令打开 sponge UI 页面：

   sponge run

在本地浏览器访问 http://localhost:24631，在页面上操作生成代码，如下图所示：

主要功能

sponge包含丰富的组件(按需使用)：

• Web 框架 gin
• RPC 框架 grpc
• 配置解析 viper
• 日志 zap
• 数据库组件 gorm, mongo-go-driver
• 缓存组件 go-redis, ristretto
• 自动化api文档 swagger, protoc-gen-openapiv2
• 鉴权 jwt
• 校验 validator
• Websocket gorilla/websocket
• 定时任务 cron
• 消息队列组件 rabbitmq, kafka
• 分布式事务管理器 dtm
• 分布式锁 dlock
• 自适应限流 ratelimit
• 自适应熔断 circuitbreaker
• 链路跟踪 opentelemetry
• 监控 prometheus, grafana
• 服务注册与发现 etcd, consul, nacos
• 自适应采集 profile
• 资源统计 gopsutil
• 配置中心 nacos
• 代码质量检查 golangci-lint
• 持续集成部署 CICD jenkins, docker, kubernetes
• 生成项目业务架构图 spograph
• 自定义模板生成代码 go template

目录结构

生成的服务代码目录结构遵循 project-layout。

这是生成的单体应用单体仓库(monolith)或微服务多仓库(multi-repo)代码目录结构：

.
├── api            # protobuf文件和生成的*pb.go目录
├── assets         # 其他与资源库一起使用的资产(图片、logo等)目录
├── cmd            # 程序入口目录
├── configs        # 配置文件的目录
├── deployments    # 裸机、docker、k8s部署脚本目录
├── docs           # 设计文档和界面文档目录
├── internal       # 业务逻辑代码目录
│    ├── cache        # 基于业务包装的缓存目录
│    ├── config       # Go结构的配置文件目录
│    ├── dao          # 数据访问目录
│    ├── database     # 数据库目录
│    ├── ecode        # 自定义业务错误代码目录
│    ├── handler      # http的业务功能实现目录
│    ├── model        # 数据库模型目录
│    ├── routers      # http路由目录
│    ├── rpcclient    # 连接grpc服务的客户端目录
│    ├── server       # 服务入口，包括http、grpc等
│    ├── service      # grpc的业务功能实现目录
│    └── types        # http的请求和响应类型目录
├── pkg            # 外部应用程序可以使用的库目录
├── scripts        # 执行脚本目录
├── test           # 额外的外部测试程序和测试数据
├── third_party    # 依赖第三方protobuf文件或其他工具的目录
├── Makefile       # 开发、测试、部署相关的命令集合
├── go.mod         # go 模块依赖关系和版本控制文件
└── go.sum         # go 模块依赖项的密钥和校验文件

这是生成的微服务单体仓库(mono-repo)代码目录结构(也就是大仓库代码目录结构)：

.
├── api
│    ├── server1       # 服务1的protobuf文件和生成的*pb.go目录
│    ├── server2       # 服务2的protobuf文件和生成的*pb.go目录
│    ├── server3       # 服务3的protobuf文件和生成的*pb.go目录
│    └── ...
├── server1        # 服务1的代码目录，与微服务多仓库(multi-repo)目录结构基本一样
├── server2        # 服务2的代码目录，与微服务多仓库(multi-repo)目录结构基本一样
├── server3        # 服务3的代码目录，与微服务多仓库(multi-repo)目录结构基本一样
├── ...
├── third_party    # 依赖的第三方protobuf文件
├── go.mod         # go 模块依赖关系和版本控制文件
└── go.sum         # go 模块依赖项的密钥和校验和文件

使用示例

使用 sponge 创建服务示例

• 基于sql创建web服务(包括CRUD)
• 基于sql创建grpc服务(包括CRUD)
• 基于protobuf创建web服务
• 基于protobuf创建grpc服务
• 基于protobuf创建grpc网关服务
• 基于protobuf创建grpc+http服务

使用 sponge 开发完整项目示例

• 简单的社区web后端服务
• 简单的社区web后端服务拆分为微服务

分布式事务示例

• 简单的分布式订单系统
• 秒杀抢购活动
• 电商系统

总结

sponge 是一个帮助你大幅提高开发效率、降低开发成本的开发框架，通过支持主流数据库、低代码开发和自动化功能，同时支持自定义的灵活扩展功能。如果您正在寻找一种方法来显著提高开发效率并缩短上线时间，那么sponge绝对值得一试。

本文链接：https://zhuyasen.com/post/sponge.html，参与评论 »

go test命令只运行单元测试，添加-bench=.参数，go test同时执行单元测试和基准测试，当然可以通过正则过滤只运行基准测试，例如-bench=^Benchmark。添加-conver参数展示测试覆盖率。

测试代码

测试5种字符串拼接效果，共两个文件splice.go和splice_test.go

splice.go文件内容如下：

package splice

import (
    "bytes"
    "fmt"
    "strings"
)

// SpliceWithPlus 使用+号拼接字符串
func SpliceWithPlus(s1 string, s2 string) string {
    return s1 + s2
}

// SpliceWithSprintf 使用fmt.Sprintf拼接字符串
func SpliceWithSprintf(s1 string, s2 string) string {
    return fmt.Sprintf("%s%s", s1, s2)
}

// SpliceWithJoin 使用strings.Join拼接字符串
func SpliceWithJoin(s1 string, s2 string) string {
    return strings.Join([]string{s1, s2}, "")
}

// SpliceWithBuilder 使用strings.Builder拼接字符串
func SpliceWithBuilder(s1 string, s2 string) string {
    var builder strings.Builder
    builder.WriteString(s1)
    builder.WriteString(s2)
    return builder.String()
}

// SpliceWithBuilder 使用bytes.Buffer拼接字符串
func SpliceWithBuffer(s1 string, s2 string) string {
    var bf bytes.Buffer
    bf.WriteString(s1)
    bf.WriteString(s2)
    return bf.String()
}

测试文件splice_test.go内容如下：

package test_example

import "testing"

var (  
    count = 10
    s1    = strings.Repeat("1234567890", count)
    s2    = strings.Repeat("0987654321", count)
    want  = s1 + s2
)

func TestSpliceString(t *testing.T) {
    if got := SpliceWithPlus(s1, s2); got != want {
        t.Errorf("SpliceWithPlus() = %v, want %v", got, want)
    }
    if got := SpliceWithSprintf(s1, s2); got != want {
        t.Errorf("SpliceWithSprintf() = %v, want %v", got, want)
    }
    if got := SpliceWithJoin(s1, s2); got != want {
        t.Errorf("SpliceWithJoin() = %v, want %v", got, want)
    }
    if got := SpliceWithBuilder(s1, s2); got != want {
        t.Errorf("SpliceWithBuilder() = %v, want %v", got, want)
    }
    if got := SpliceWithBuffer(s1, s2); got != want {
        t.Errorf("SpliceWithBuffer() = %v, want %v", got, want)
    }
}

func BenchmarkSpliceWithPlus(b *testing.B) {
    for i := 0; i < b.N; i++ {
        SpliceWithPlus(s1, s2)
    }
}

func BenchmarkSpliceWithSprintf(b *testing.B) {
    for i := 0; i < b.N; i++ {
        SpliceWithSprintf(s1, s2)
    }
}

func BenchmarkSpliceWithJoin(b *testing.B) {
    for i := 0; i < b.N; i++ {
        SpliceWithJoin(s1, s2)
    }
}

func BenchmarkSpliceWithBuilder(b *testing.B) {
    for i := 0; i < b.N; i++ {
        SpliceWithBuilder(s1, s2)
    }
}

func BenchmarkSpliceWithBuffer(b *testing.B) {
    for i := 0; i < b.N; i++ {
        SpliceWithBuffer(s1, s2)
    }
}

单元测试

单元测试常用参数：

• -v：测试时显示详细信息，示例：go test -v
• -list: 列出测试、基准测试函数，示例：go test -list
• -run: 指定要运行的测试函数，示例：go test -run TestSpliceString
• -failfast: 在第一个失败的测试处停止，退出测试，示例 go test -failfast
• -count=1: 禁用缓存，示例：go test -count=1
• -cpu=4: 限制cpu数量，把参数值传递给GOMAXPROCS，示例：go test -cpu=4
• -race: 检测竞态条件，示例：go test -race

单元测试范围示例：

# 执行当前下所有单元测试，包括子文件夹
go test ./...

# 执行当前目录下所有单元测试，不包括子文件夹
go test ./dir

# 执行指定文件单元测试，指定测试文件和被测试文件
go test splice.go splice_test.go

# 运行指定单元测试用例
go test -run TestSpliceString

基准测试

基准测试框架对一个测试用例的默认测试时间是 1 秒。开始测试时，当以 Benchmark 开头的基准测试用例函数返回时还不到 1 秒，那么 testing.B 中的 N 值将按 1、2、5、10、20、50……递增，同时以递增后的值重新调用基准测试用例函数。

基准测试常用参数：

• -bench: 基准测试必填参数，参数值是正则表达式， -bench=. 表示同时运行单元测试和基准测试； -bench=^Benchmark 表示执行当前目录下所有基准测试，也可以具体到某个函数的基准测试。
• benchtime=3s: 自定义测试时间，示例：go test -bench=. -benchtime=3s
• -benchmem: 显示内存分配统计信息，示例：go test -bench=. -benchmem
• -cpu=4: 限制线程数量，把参数值传递给GOMAXPROCS，示例：go test -bench=. -cpu=4

基准测试范围示例：

# 执行当前目录下所有基准测试，包括子文件夹
go test -bench=. ./...

# 执行当前目录下的基准测试，不包括子文件夹
go test -bench=. ./dir

# 执行指定文件基准测试，指定测试文件和被测试文件
go test -bench=. splice.go splice_test.go

# 运行指定单元基准测试
go test -bench=BenchmarkSpliceWithPlus

修改splice_test.go文件的count变量值，分别为1、10、100，进行基准测试，结果如下：

go version go1.17.2 windows/amd64

# count=1，10bytes 长度字符串拼接基准压测
$ go test -bench=. -benchmem

goos: windows
goarch: amd64
pkg: demo/test_example
cpu: Intel(R) Core(TM) i7-8700 CPU @ 3.20GHz
BenchmarkSpliceWithPlus-12              80041087                14.95 ns/op            0 B/op          0 allocs/op
BenchmarkSpliceWithSprintf-12            8744901               128.1 ns/op            56 B/op          3 allocs/op
BenchmarkSpliceWithJoin-12              33571974                35.15 ns/op           24 B/op          1 allocs/op
BenchmarkSpliceWithBuilder-12           20154652                59.78 ns/op           48 B/op          2 allocs/op
BenchmarkSpliceWithBuffer-12            19531503                62.91 ns/op           88 B/op          2 allocs/op
PASS
ok      demo/test_example       6.314s


# count=10，100bytes 长度字符串拼接基准压测
$ go test -bench=. -benchmem

goos: windows
goarch: amd64
pkg: demo/test_example
cpu: Intel(R) Core(TM) i7-8700 CPU @ 3.20GHz
BenchmarkSpliceWithPlus-12              15102146                66.62 ns/op          208 B/op          1 allocs/op
BenchmarkSpliceWithSprintf-12            6655336               181.0 ns/op           240 B/op          3 allocs/op
BenchmarkSpliceWithJoin-12              17094942                70.57 ns/op          208 B/op          1 allocs/op
BenchmarkSpliceWithBuilder-12           10660695               112.0 ns/op           336 B/op          2 allocs/op
BenchmarkSpliceWithBuffer-12             5528898               201.4 ns/op           640 B/op          3 allocs/op
PASS
ok      demo/test_example       6.610s


# count=100，1000bytes 长度字符串拼接基准压测
$ go test -bench=. -benchmem

goos: windows
goarch: amd64
pkg: demo/test_example
cpu: Intel(R) Core(TM) i7-8700 CPU @ 3.20GHz
BenchmarkSpliceWithPlus-12               2898604               387.1 ns/op          2048 B/op          1 allocs/op
BenchmarkSpliceWithSprintf-12            2218687               511.3 ns/op          2081 B/op          3 allocs/op
BenchmarkSpliceWithJoin-12               2922162               412.0 ns/op          2048 B/op          1 allocs/op
BenchmarkSpliceWithBuilder-12            2015064               607.7 ns/op          3072 B/op          2 allocs/op
BenchmarkSpliceWithBuffer-12              999949                1186 ns/op          6144 B/op          3 allocs/op
PASS
ok      demo/test_example       8.067s

基准压测函数后面数字12，表示执行基准测试使用的线程数量，可以通过-cpu=4参数来修改。

5种字符串拼接性能最好的是BenchmarkSpliceWithPlus，其次是BenchmarkSpliceWithJoin。

Benchstat工具

单纯只压测一次结果不大准确，因此使用工具Benchstat 计算和比较有关基准的统计数据。

安装：

go install golang.org/x/perf/cmd/benchstat@latest

用法：

benchstat [-delta-test name] [-geomean] [-html] [-sort order] old.txt [new.txt] [more.txt …]

示例：

# 第一次压测某个函数
go test -run=NONE -bench=BenchmarkSpliceWithSprintf -count=5 | tee -a old.txt

# 优化后(使用+号替换fmt.Sprintf拼接字符串)第二次压测某个函数
go test -run=NONE -bench=BenchmarkSpliceWithSprintf -count=5 | tee -a new.txt

# 查看压测结果
benchstat old.txt
benchstat new.txt

# 比较两次的统计结果
benchstat old.txt new.txt
# name                  old time/op  new time/op  delta
# SpliceWithSprintf-12   128ns ± 1%    33ns ± 0%  -74.63%  (p=0.000 n=14+5)

任何大于 5% 的值都表明某些样本不可靠，在这种情况下，您应该重新运行基准测试，尽可能保持环境稳定以提高可靠性。

测试覆盖率

go test命令还支持展示测试覆盖率信息。

测试覆盖率常用参数：

• -cover: 测试覆盖率必填参数，示例：go test -v -cover
• -coverprofile: 导出单元测试覆盖率统计信息到文件，示例：go test -coverprofile=cover.out
• -html: 在浏览器查看覆盖哪些代码，示例：go tool cover -html=cover.out

测试覆盖率范围示例：

# 执行当前下所有单元测试，包括子文件夹，并展示覆盖率
go test -cover ./...

# 执行当前目录下所有单元测试，不包括子文件夹，并展示覆盖率
go test -cover ./dir

# 执行指定文件单元测试，指定测试文件和被测试文件，并展示覆盖率
go test -cover splice.go splice_test.go

# 运行指定单元测试用例，并展示覆盖率
go test -cover -run TestSpliceString

# 在浏览器查看覆盖哪些代码
go test -coverprofile=cover.out && go tool cover -html=cover.out

总结

单元测试是项目开发环节必不可少的环节，是检验程序是否符合预期手段，测试代码有可能比实际业务逻辑代码还多，主要原因是测试包括各种测试case，这些case尽可能覆盖率所有业务代码，使用goland IDE写代码，按快捷键Alt+Insert可以自动化添加单元测试代码，只需要填写测试用例，大大减少写测试代码时间。基准测试是性能要求比较高的业务逻辑中必须测试环节，通过暴力压测方式检验程序性能达到什么水平，一般看完成操作耗时和内存分配情况来判断，也是程序性能调优的常用手段。

本文链接：https://zhuyasen.com/post/gotest.html，参与评论 »

1 介绍

pprof 是一个可视化和分析数据的工具，pprof 读取 profile.proto 格式的分析样本集合并生成报告以可视化和帮助分析数据，它可以生成文本和图形报告，是用来分析应用程序的性能重要工具，也可以作为其他用途，例如查看反汇编、和Linux perf工具结合使用。

2 安装

golang本身自带pprof工具，pprof可视化时需要依赖Graphviz工具。

linux环境下安装Graphviz：

yum install -y graphviz

windows环境安装Graphviz：

# Graphviz下载地址： https://graphviz.org/download/
# (1) 安装，在界面默认是没有选择加入系统path，选择添加到系统path即可。(注：如果是默认安装，需要手动把`Graphviz/bin`目录放到系统path。)

# (2) 生成配置文件，进去 `Graphviz/bin` 安装目录，执行命令：
dot -c

3 使用模式

3.1 报告生成

pprof 生成指定格式的报告并退出，格式可以是文本或图形。

pprof <format> [options] source

3.2 交互式终端使用

pprof 启动一个交互式 shell，用户可以在其中键入命令，输入help获取命令帮助信息。

pprof [options] source

3.3 网页界面

pprof 可以指定端口上开启 HTTP 服务，在浏览器中访问该端口(例如 http://localhost:7778 )，相对前两种模式，比较常用。

pprof -http=[host]:[port] [options] source

4 一个go程序性能分析示例

下面代码是分配栈对象和堆对象测试代码，可以调整heapGSize和stackGSize变量大小来调整栈对象和堆对象数量，随着goroutine数量增大，gc压力增大，GC阶段占CPU时间越来越大，CPU执行用户逻辑占比变小，说明程序性能下降。

package main

import (
    "fmt"
    "math/rand"
    "net/http"
    _ "net/http/pprof"
    "time"
)

var chOut = make(chan string, 100)

func main() {
    // 开启pprof
    go func() {
        err := http.ListenAndServe(":7777", nil)
        if err != nil {
            panic(err)
        }
    }()

    // 20个goroutine创建堆对象
    heapGSize := 20
    for i := 0; i < heapGSize; i++ {
        NO := i
        go func() {
            for {
                heapVar(NO)
                sleep()
            }
        }()
    }

    // 20个goroutine创建栈对象
    stackGSize := 20
    for i := 0; i < stackGSize; i++ {
        NO := i
        go func() {
            for {
                stackVar(NO)
                sleep()
            }
        }()
    }

    go output(chOut)

    <-time.After(time.Hour)
}

func heapVar(NO int) {
    for i := 0; i < 2000; i++ {
        s := make([]int, 10240) // 10K
        s[0] = i
        if i == 0 { // 每次只把2000个堆对象中的第一个堆对象输出查看
            s[0] = time.Now().Second()
            chOut <- fmt.Sprintf("heap%d:%d", NO, s[0])
        }
    }
}

type User struct {
    ID    int
    Name  string
    Age   int
    Email string
}

func stackVar(NO int) {
    for i := 0; i < 100000; i++ {
        number := &User{ID: i}
        if i == 0 {
            number.ID = time.Now().Second()
            chOut <- fmt.Sprintf("stack%d:%d", NO, number.ID)
        }
    }
}

// 随机睡眠1~1.5秒
func sleep() {
    n := rand.Intn(500) + 1000
    time.Sleep(time.Millisecond * time.Duration(n))
}

// 打印输出
func output(ch <-chan string) {
    maxSize := 100
    msgs := make([]string, maxSize, maxSize)
    var v string
    var count int
    for {
        select {
        case v = <-ch:
            count++
            if count == maxSize {
                count = 0
                fmt.Printf(msgs[0] + " ") // 打印第0个位置消息，为了减少终端输出
            }
            msgs[count] = v
        }
    }
}

编译后运行测试程序，在浏览器打开 http://localhost:7777/debug/pprof 可以查看不同类型采集数据。

count  Profile
15     allocs           // 过去所有内存分配的样本
0      block            // 同步阻塞
0      cmdline          // 当前程序的命令行调用
47     goroutine        // 当前所有goroutine的堆栈痕迹
15     heap             // 现场对象的内存分配样本。你可以指定gc GET参数，在进行堆采样之前运行GC
0      mutex            // 争夺锁的持有者
0      profile          // CPU概况。你可以在seconds GET参数中指定持续时间。在你得到概况文件后，使用go工具pprof命令来调查概况
16     threadcreate     // 操作系统创建新线程
0      trace            // 当前程序的执行跟踪。你可以在秒的GET参数中指定持续时间。在你得到跟踪文件后，使用go tool trace命令来调查该跟踪

页面只能查看这些数据简单分析，但可视化不够直观，使用go tool pprof更方便查看对应每个类型profile，在菜单【View】可以查看类型包括：

• TOP：排名
• Graph：关系图
• Flame Graph：火焰图
• Peek：类似TOP，信息更详细
• Source：源码

4.1 CPU分析

在实际中，如果发现程序的CPU使用率高时，可以使用go tool pprof采集CPU分析数据。下面命令是采集最近20秒(默认是30秒)CPU执行分析数据，http端口是7778。

go tool pprof -http=:7778 -seconds=20 http://localhost:7777/debug/pprof/profile

等待20秒之后自动在浏览器展示，点击菜单【View】–> 【Flame Graph】查看CPU火焰图，如下图所示：

从图中可以看到heapVar和stackVar只占用1/3左右的CPU，2/3的CPU时间用来创建对象和回收对象了，说明有优化空间。

4.2 内存分析

在实际中，如果发现程序的内存使用比较高时，可以使用go tool pprof采集内存分析数据，下面命令是查看堆分配情况，http端口是7779。

go tool pprof -http=:7779 http://localhost:7777/debug/pprof/heap

执行命令之后自动在浏览器展示，点击菜单【SAMPLE】 –> 【inuse_space】，然后点击菜单【View】–> 【Flame Graph】查看内存火焰图，如下图所示：

从图中可以看到heapVar占用比较多，说明需要优化heapVar函数，其他系统底层调用，通常是用户程序调用导致，无法优化。

4.3 下载采集数据到本地分析

除了直接在浏览器分析，还可以把采集的数据下载到本地后再分析，命令如下：

# 下载到本地
wget <url> -O <filename>
# 下载的文件
go tool pprof -http=<:prort> <filename>

下载采集数据到本地之后，可以做优化前后对比，优化前测试程序的heapVar和stackVar变量值为20，优化后heapVar和stackVar变量值为1.

CPU优化前后对比

# 下载优化前采集数据
wget http://localhost:7777/debug/pprof/profile -O cpu_before.out

# 下载优化后数据
wget http://localhost:7777/debug/pprof/profile -O cpu_after.out

# 比较优化前后
go tool pprof -http=:7778 --base cpu_before.out cpu_after.out

执行命令后，查看Graph图，绿色是优化节省的CPU资源，如下图所示：

内存优化前后对比

# 下载优化前采集数据
wget http://localhost:7777/debug/pprof/heap -O heap_before.out

# 下载优化后数据
wget http://localhost:7777/debug/pprof/heap -O heap_after.out

# 优化前后比较
go tool pprof -http=:7779 --base heap_before.out heap_after.out

执行命令后，查看Graph图，绿色是优化节省的内存资源，如下图所示：

注：切换到【VIEW】 –> 【Source】源码界面，可以展示哪个函数节省了多少资源。

5 trace分析

通过trace可以看到goroutine数量、线程数量、堆数量、GC、各个goroutine调度情况，可以查看各个线程当前时刻执行哪个goroutine，当前时刻各个goroutine在干什么，使用trace需要两个步骤：

(1) 下载trace数据到trace.out文件，只有1秒内trace数据

wget http://localhost:7777/debug/pprof/trace -O trace.out

(2) 查看trace信息，http端口为7780

go tool trace -http=:7780 trace.out

执行命令之后在浏览界面点击View Trace查看具体跟踪信息，如下图所示：

从图中看出在1秒内，GC占用时间超过30%，说明这个程序是需要优化的。点击界面右边菜单File Size Stats，从统计中可以看到GC相关的事件数量非常多，例如 runtime.bgsweep、SWEEP、GC (dedicated)。

可以选择zoom进行放大看各个goroutine执行细节，在界面右上角搜索事件名称，例如STW、SWEEP等，下面是搜索STW的细节：

从图中看到在8ms内出现了不少STW(stop the world)，在一个GC完整周期出现两次STW，其中绿色是sweep termination阶段的STW，红色是mark termination阶段的STW。

6 总结

通过pprof作为go程序定位问题、性能优化的工具。建议生产环境的go服务开启pprof，正常情况下是不需要实时去采集内存、CPU数据来分析。因为不知道什么时候应该采集数据，建议写一个看门狗程序，检测CPU、内存或其他指标达到阈值时，自动采集保存现场数据，避免出现问题了，没有留下现场数据。

本文链接：https://zhuyasen.com/post/pprof.html，参与评论 »

channel 是一个数据管道，是 goroutine 之间数据通信桥梁，是线程安全的。channel分为有缓冲和无缓冲两种类型，其实无缓冲类型可以理解为有缓冲的一种特殊情况。

1 channel工作原理

源码 go/src/runtime/chan.go

type hchan struct {
    qcount   uint           // 当前队列中剩余元素个数  
    dataqsiz uint           // 环形队列长度，即缓冲区的大小，即make（chan T，N），N.
    buf      unsafe.Pointer // 环形队列指针
    elemsize uint16         // 每个元素的大小 
    closed   uint32         // 表示当前通道是否处于关闭状态。创建通道后，该字段设置为0，即通道打开; 通过调用close将其设置为1，通道关闭。 
    elemtype *_type         // 元素类型，用于数据传递过程中的赋值； 
    sendx    uint           // 环形缓冲区的状态字段，它指向环形队列当前发送索引
    recvx    uint           // 环形缓冲区的状态字段，它指向环形队列当前接收索引
    recvq    waitq          // 等待读消息的goroutine队列 
    sendq    waitq          // 等待写消息的goroutine队列 
    lock     mutex          // 互斥锁，为每个读写操作锁定通道，因为发送和接收必须是互斥操作
}

从结构体看核心字段是环形队列buf，而qcount、dataqsiz、sendx、recvx是维护buf状态字段，recvq和sendq是存放发送接收channel阻塞的goroutine队列，也是间接维护buf的，lock是整个结构体的锁，避免不同goroutine读写数据竞争，因此channel是并发安全的。

1.1 发送数据到channel

发送流程图:

1.2 从channel接收数据

接收流程图：

1.3 goroutine挂起与唤醒

goroutine挂起时调用gopark函数，唤醒调用goready函数，一般是成对出现。

• channel发送挂起，⼀定是由channel接收端(或close)唤醒。
• channel接收挂起，⼀定是由channel发送(或close)唤醒。
• 当主动closechannel时，同时唤醒channel发送和接收队列的所有goroutine。

1.4 channel操作方式

操作 channel 一般有如下三种方式：

• 读 <-ch
• 写 ch<-
• 关闭 close(ch)

可以使用for range接收管道数据

for v := range ch { // 一直循环等待读取数据，直到关闭通道退出循环
    fmt.Println(v)
}

可以使用select接收管道数据或发送数据到管道

var count int
for {
    select { // 可以用select作为接发送或接收选择器
    case v, ok := <-ch1: // 当关闭通道后，如果有数据也会读出来
        if !ok { // 判断通道是否已经关闭
            fmt.Println("通道已经关闭")
            return
        }
        fmt.Println(v)

    case ch2<-count: // 发送数据
    }
    count++
}

2 channel应用

2.1 信息交流

channel 的底层是一个循环队列，当队列的长度大于0的时候，可以在队列中缓存数据信息，向一个 goroutine存放数据，从一个 goroutine读取数据，就像水管的两头，这样就实现了goroutine之间的消息交流。

示例代码：

// InfoExchange 读取信息
func InfoExchange(ctx context.Context, in <-chan interface{}) {
    for {
        select {
        case v, ok := <-in:
            if !ok {
                fmt.Println("\n信息传递结束")
                return
            }
            fmt.Printf("%v ", v)

        case <-ctx.Done():
            return
        }
    }
}

测试代码：

func genInfo() <-chan interface{} {
    in := make(chan interface{}, 5)

    go func() {
        defer close(in)
        for i := 0; i < 10; i++ {
            in <- i
            time.Sleep(time.Millisecond * 500)
        }
    }()

    return in
}

func TestInfoExchange(t *testing.T) {
    in := genInfo()

    delay := time.Second * 5
    ctx, _ := context.WithTimeout(context.Background(), delay)
    go InfoExchange(ctx, in)

    <-time.After(delay)
}

/*
结果：

0 1 2 3 4 5 6 7 8 9 
信息传递结束
*/

2.2 数据传递

数据传递类似游戏“击鼓传花”。鼓响时，花（或者其它物件）从一个人手里传到下一个人，数据就类似这里的花

示例代码：

// DataTransfer 数据传递，从chan读取数据，并传递给下一个chan
func DataTransfer(id int, n int, chans []chan interface{}) {
    for {
        token := <-chans[id]
        fmt.Printf("id=%d, v=%v \n", id, token)

        chans[(id+1)%n] <- token
        time.Sleep(time.Second)
    }
}

测试代码：

func TestStartTask(t *testing.T) {
    n := 4
    chans := []chan interface{}{}

    for i := 0; i < n; i++ {
        chans = append(chans, make(chan interface{}, 1))
    }

    for i := 0; i < n; i++ {
        go DataTransfer(i, n, chans)
    }

    // 初始化数据
    chans[0] <- "a"
    chans[1] <- "b"
    chans[2] <- "c"
    chans[3] <- "d"

    <-time.After(time.Second * 5)
}

/*
结果：

id=3, v=d 
id=0, v=a 
id=1, v=b 
id=2, v=c 
id=1, v=a 
id=0, v=d 
id=3, v=c 
id=2, v=b 
...
*/

2.3 信号通知

使用非缓冲channel的特性，当channel没有数据接收时会阻塞，直到有新的数据进来或者 channel 被关闭才会退出阻塞，因此可以作为信号通知。

示例代码：

quit := make(chan os.Signal)  
signal.Notify(quit, os.Interrupt)  
<-quit

2.4 锁

示例代码：

// Mutex 使用chan实现互斥锁
type Mutex struct {
    ch chan struct{}
}

// NewMutex 使用锁需要初始化
func NewMutex() *Mutex {
    mu := &Mutex{make(chan struct{}, 1)}
    mu.ch <- struct{}{}
    return mu
}

// Lock 请求锁，直到获取到
func (m *Mutex) Lock() {
    <-m.ch
}

// Unlock 解锁
func (m *Mutex) Unlock() {
    select {
    case m.ch <- struct{}{}:
    default:
        panic("unlock of unlocked mutex")
    }
}

// TryLock 尝试获取锁
func (m *Mutex) TryLock() bool {
    select {
    case <-m.ch:
        return true
    default:
    }
    return false
}

// LockTimeout 加入一个超时的设置
func (m *Mutex) LockTimeout(timeout time.Duration) bool {
    timer := time.NewTimer(timeout)
    select {
    case <-m.ch:
        timer.Stop()
        return true
    case <-timer.C:
    }
    return false
}

// IsLocked 锁是否已被持有
func (m *Mutex) IsLocked() bool {
    return len(m.ch) == 0
}

测试代码：

func TestMutex_TryLock(t *testing.T) {
    m := NewMutex()

    for i := 0; i < 5; i++ {
        go func(i int) {
            if m.TryLock() {
                fmt.Printf("NO %d get lock success\n", i)
            } else {
                fmt.Printf("NO %d get lock failed\n", i)
            }
        }(i)
    }

    time.Sleep(time.Millisecond)
}

/*
结果：

NO 4 get lock success
NO 2 get lock failed
NO 3 get lock failed
NO 0 get lock failed
NO 1 get lock failed
*/

func TestMutex_Lock(t *testing.T) {
    a := -1
    m := NewMutex()

    for i := 0; i < 5; i++ {
        go func(i int) {
            for {
                m.Lock()
                a = i
                time.Sleep(time.Millisecond * 100)
                fmt.Println("a =", a)
                m.Unlock()
            }

        }(i)
    }

    time.Sleep(time.Second)
}


/*
结果：

a = 4
a = 2
a = 3
a = 0
a = 1
...
*/

2.5 任务编排

2.5.1 or-Done 模式

有n 个任务，其中任意一个完成就算完成，这叫or-Done 模式，

使用场景：用户查询请求，同时发两次给集群服务，取最快返回，使用冗余请求增加体验。

示例代码：

// OrDone 任意一个channel完成就退出
func OrDone(channels ...<-chan interface{}) <-chan interface{} { // <1>

    switch len(channels) {
    case 0: // <2>
        return nil
    case 1: // <3>
        return channels[0]
    }

    orDone := make(chan interface{})
    go func() { // <4>
        defer close(orDone)

        switch len(channels) {
        case 2: // <5>
            select {
            case <-channels[0]:
            case <-channels[1]:
            }
        default: // <6>
            select {
            case <-channels[0]:
            case <-channels[1]:
            case <-channels[2]:
            case <-OrDone(append(channels[3:], orDone)...): // <6>
            }
        }
    }()
    return orDone
}

测试：

func done(after time.Duration) <-chan interface{} {
    c := make(chan interface{})
    go func() {
        defer close(c)
        fmt.Println("delay:", after)
        time.Sleep(after)
    }()
    return c
}

// 随机1~10秒
func randTime() time.Duration {
    n := time.Duration(rand.Int31n(10))
    return n * time.Second
}

func TestOrDone(t *testing.T) {

    <-OrDone(
        done(randTime()),
        done(randTime()),
        done(randTime()),
        done(randTime()),
        done(randTime()),
        done(randTime()),
    )
}

/*
结果：

delay: 1s
delay: 1s
delay: 8s
delay: 7s
delay: 7s
delay: 9s
*/

2.5.2 扇入模式

多个结果组合到一个channel中的过程叫扇入模式下，输入源有多个，输出目标只有一个。

示例代码：

// FanIn 扇入，多个channel组合到一个channel
func FanIn(chans ...<-chan interface{}) <-chan interface{} {
    switch len(chans) {
    case 0:
        c := make(chan interface{})
        close(c)
        return c
    case 1:
        return chans[0]
    case 2:
        return mergeTwo(chans[0], chans[1])
    default:
        m := len(chans) / 2
        return mergeTwo( // 对多个数据进行合并处理
            FanIn(chans[:m]...),
            FanIn(chans[m:]...))
    }
}

func mergeTwo(a, b <-chan interface{}) <-chan interface{} {
    c := make(chan interface{})
    go func() {
        defer close(c)
        for a != nil || b != nil { //只要还有可读的chan
            select {
            case v, ok := <-a:
                if !ok { // a 已关闭，设置为nil
                    a = nil
                    continue
                }
                c <- v
            case v, ok := <-b:
                if !ok { // b 已关闭，设置为nil
                    b = nil
                    continue
                }
                c <- v
            }
        }
    }()
    return c
}

测试：

func done(v int) <-chan interface{} {
    in := make(chan interface{})
    go func() {
        defer close(in)
        in <- v
        time.Sleep(time.Millisecond * 500)
    }()
    return in
}

func TestFanIn(t *testing.T) {
    out := FanIn(
        done(1),
        done(2),
        done(3),
    )

    for v := range out {
        fmt.Println(v)
    }
}

/*
结果：

1
3
2
*/

2.5.3 扇出模式

扇出模式（Fan-Out）只有一个输入源，但是有多个输出目标。从源 channel 取出一个数据后，依次发送给多个目标 channel。发送的时候，既可以同步，也可以异步。

示例代码：

// FanOut 扇出，只有一个输入源，但是有多个输出目标
func FanOut(ch <-chan interface{}, out []chan interface{}, async bool) {
    go func() {
        defer func() { //退出时关闭所有的输出chan
            for i := 0; i < len(out); i++ {
                close(out[i])
            }
        }()

        for v := range ch { // 从输入chan中读取数据
            v := v
            for i := 0; i < len(out); i++ {
                i := i
                if async { //异步
                    go func() {
                        out[i] <- v // 放入到输出chan中，异步方式
                    }()
                } else {
                    out[i] <- v // 放入到输出chan中，同步方式
                }
            }
        }
    }()
}

测试：

func TestFanOut(t *testing.T) {
    ch := make(chan interface{})
    chLister := []chan interface{}{make(chan interface{}), make(chan interface{}), make(chan interface{})}

    FanOut(ch, chLister, false)

    for i := 0; i < 5; i++ {
        ch <- i
        fmt.Println(<-chLister[0], <-chLister[1], <-chLister[2])
        time.Sleep(time.Second)
    }
}

/*
结果：

0 0 0
1 1 1
2 2 2
3 3 3
4 4 4
*/

2.5.4 stream

stream 是把 channel 当做流式管道的方式。

// AsStream 将一个 slice 转成流
func AsStream(done <-chan struct{}, values ...interface{}) <-chan interface{} {
    s := make(chan interface{}) //创建一个unbuffered的channel
    go func() {                 // 启动一个goroutine，往s中塞数据
        defer close(s)             // 退出时关闭chan
        for _, v := range values { // 遍历数组
            select {
            case <-done:
                return
            case s <- v: // 将数组元素塞入到chan中
            }
        }
    }()
    return s
}

// TakeN 获取流的前n个数据
func TakeN(done <-chan struct{}, valueStream <-chan interface{}, n int) <-chan interface{} {
    takeStream := make(chan interface{}) // 创建输出流
    go func() {
        defer close(takeStream)
        for i := 0; i < n; i++ { // 只读取前num个元素
            select {
            case <-done:
                return
            case takeStream <- <-valueStream: //从输入流中读取元素
            }
        }
    }()
    return takeStream
}

2.5.5 map-reduce

map-reduce 是一种面向大规模数据处理的并行计算模型和方法，但是这里要介绍的是一种单机版的 map-reduce 模式。

map-reduce 分为两个步骤，第一步是 map，将队列中的数据用 mapFn 函数处理；第二步是 reduce，将处理后的数据用 reduceFn 函数汇总。

// MapChan 处理mapFn处理数据
func MapChan(in <-chan interface{}, mapFn func(interface{}) interface{}) <-chan interface{} {
    out := make(chan interface{}) // 创建一个输出chan
    if in == nil {                // 异常检查
        close(out)
        return out
    }

    go func() { // 启动一个goroutine,实现map的主要逻辑
        defer close(out)
        for v := range in { // 从输入chan读取数据，执行业务操作，也就是map操作
            out <- mapFn(v)
        }
    }()

    return out
}

// Reduce  reduceFn函数汇总
func Reduce(in <-chan interface{}, reduceFn func(r, v interface{}) interface{}) interface{} {
    if in == nil { // 异常检查
        return nil
    }

    out := <-in         // 先读取第一个元素
    for v := range in { // 实现reduce的主要逻辑
        out = reduceFn(out, v)
    }

    return out
}

测试：

// 需求：将一组数据中每个数据乘以10，最后计算总和。为此，我们需要实现 mapFn (乘 10) 和 reduceFn （求和）

// 生成一个数据流
func numStream(done <-chan struct{}) <-chan interface{} {
    s := make(chan interface{})
    values := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
    go func() {
        defer close(s)
        for _, v := range values { // 从数组生成
            select {
            case <-done:
                return
            case s <- v:
            }
        }
    }()
    return s
}

func TestMapReduce(t *testing.T) {
    in := numStream(nil)

    // map操作: 乘以10
    mapFn := func(v interface{}) interface{} {
        return v.(int) * 10
    }

    // reduce操作: 对map的结果进行累加
    reduceFn := func(r, v interface{}) interface{} {
        return r.(int) + v.(int)
    }

    sum := Reduce(MapChan(in, mapFn), reduceFn) //返回累加结果
    fmt.Println(sum)
}

2.6 worker模式

2.6.1 最简单的worker处理队列方式

package main

import "time"

type Job int

func worker(jobChan <-chan Job) {
    for job := range jobChan {
        // 顺序执行，缺点：如果处理过程中有等待或阻塞，会影响整个队列
        Process(job)

        // 并发执行，如果处理过程中有等待或阻塞，不会影响其他的job，
        // 缺点：并发处理job的goroutine数量不可控，每来一个新job就会启动一个goroutine，不建议这样处理。
        // 通常做法是开启有限个worker的goroutine来并行处理队列的job，而不是在process里并发执行。
        //go Process(job)
    }
}

func Process(job Job) {
    if job == 3 { // 等于3的这个job阻塞1s
        time.Sleep(time.Second)
    }
    println("job", job)
}

func main() {
    // make a channel with a capacity of 10.
    jobChan := make(chan Job, 10)

    // start the worker
    go worker(jobChan)

    // enqueue a job
    for i := 0; i < 20; i++ {
        jobChan <- Job(i)
    }

    time.Sleep(2 * time.Second)
}

/* 当次执行的结果如下：

(1) 顺序执行，在处理job 3时阻塞了一秒，其他job要等job 3处理完毕后再处理往下执行。
job 0
job 1
job 2
job 3
job 4
job 5
job 6
job 7
job 8
job 9
job 10
job 11
job 12
job 13
job 14
job 15
job 16
job 17
job 18
job 19

------------------------------------------------------

(2) 并发process执行，在处理job 3时阻塞了一秒，不影响其他的job处理。
job 2
job 10
job 0
job 6
job 4
job 5
job 9
job 7
job 1
job 8
job 13
job 11
job 12
job 19
job 17
job 18
job 14
job 15
job 16
job 3
*/

2.6.2 使用worker池处理队列

package main

import (
    "fmt"
    "time"
)

type Job int

func worker(i int, jobChan <-chan Job) {
    for job := range jobChan {
        Process(i, job)
    }
}

func Process(i int, job Job) {
    if job == 3 {
        time.Sleep(time.Second)
    }
    fmt.Printf("worker %2d process job %d\n", i, job)
}

func workPool(workerSize int, jobChan chan Job) {
    for i := 0; i < workerSize; i++ {
        go func(i int) {
            worker(i, jobChan)
        }(i)
    }
}

func main() {
    jobChan := make(chan Job, 10)

    // 启动多个worker池并发处理队列的job，多个worker去抢队列job来处理，只有空闲的worker才能从队列中获取job
    workPool(5, jobChan)

    for i := 0; i < 20; i++ {
        jobChan <- Job(i)
    }

    time.Sleep(2 * time.Second)
}

/*当次执行结果如下：

可以看到worker 2处理job 3时阻塞一秒，worker 2在阻塞过程中没有去抢占队列新的job来处理。
worker  4 process job 0
worker  3 process job 4
worker  0 process job 2
worker  3 process job 6
worker  3 process job 8
worker  3 process job 9
worker  3 process job 10
worker  3 process job 11
worker  3 process job 12
worker  3 process job 13
worker  3 process job 14
worker  3 process job 15
worker  3 process job 16
worker  3 process job 17
worker  3 process job 18
worker  1 process job 1
worker  4 process job 5
worker  0 process job 7
worker  3 process job 19
worker  2 process job 3
*/

2.6.3 等待worker处理所有队列的job

package main

import (
    "fmt"
    "math/rand"
    "sync"
    "time"
)

type Job int

func worker(n int, jobChan <-chan Job, wg *sync.WaitGroup) {
    for job := range jobChan {
        Process(n, job, wg)
    }
}

func Process(n int, job Job, wg *sync.WaitGroup) {
    defer wg.Done()

    // 加上随机延时，方便查看打印效果
    size := randTime()
    time.Sleep(size * time.Millisecond)

    fmt.Printf("worker %2d process job %d, time %dms\n", n, job, size)
}

// 随机时间100~500
func randTime() time.Duration {
    rand.Seed(time.Now().UnixNano())
    return time.Duration(rand.Intn(400) + 100)
}

func WaitTimeout(wg *sync.WaitGroup, timeout time.Duration) bool {
    ch := make(chan struct{})

    go func() {
        wg.Wait()
        close(ch)
    }()

    select {
    case <-ch:
        return true
    case <-time.After(timeout):
        return false
    }
}

func workPool(workerNum int, jobChan chan Job, wg *sync.WaitGroup) {
    for i := 0; i < workerNum; i++ {
        go func(i int) {
            worker(i, jobChan, wg)
        }(i)
    }
}

func main() {
    wg := &sync.WaitGroup{}
    jobChan := make(chan Job, 10)

    workPool(5, jobChan, wg)

    for i := 0; i < 20; i++ {
        wg.Add(1)
        jobChan <- Job(i)
    }

    t := time.Now()

    // 等待所有job处理完毕才退出，不足：不管是顺序执行还是并发process方式处理job，如果其中有一个job阻塞了，会一直等待下去
    wg.Wait()

    // 带超时等待，如果超时了，直接忽略等待
    //ok := WaitTimeout(wg, 300*time.Millisecond)
    //if !ok {
    //  fmt.Printf("\n warning, process job timeout \n")
    //}

    fmt.Printf("\n handle queue time %v\n", time.Now().Sub(t))
}

/* 当次执行结果如下：

(1) 不带超时的wait
worker  2 process job 2, time 147ms
worker  0 process job 0, time 147ms
worker  1 process job 1, time 147ms
worker  3 process job 4, time 147ms
worker  4 process job 3, time 147ms
worker  1 process job 7, time 282ms
worker  4 process job 9, time 282ms
worker  0 process job 6, time 282ms
worker  3 process job 8, time 282ms
worker  2 process job 5, time 399ms
worker  1 process job 10, time 149ms
worker  0 process job 12, time 149ms
worker  3 process job 13, time 149ms
worker  4 process job 11, time 149ms
worker  2 process job 14, time 145ms
worker  0 process job 16, time 265ms
worker  1 process job 15, time 265ms
worker  3 process job 17, time 265ms
worker  4 process job 18, time 265ms
worker  2 process job 19, time 234ms

 handle queue time 786.8609ms

------------------------------------------------

(2) 有超时的wait
worker  3 process job 3, time 257ms
worker  1 process job 1, time 272ms
worker  0 process job 0, time 272ms
worker  4 process job 4, time 272ms
worker  2 process job 2, time 272ms
worker  4 process job 8, time 102ms
worker  3 process job 5, time 224ms

 warning, process job timeout

 handle queue time 300.3939ms
*/

2.6.4 使用context或channel停止worker

有两种方式停止处理队列中的worker，分别是context和channel，多级函数传递或复杂点的控制建议使用context。

(1) 使用context停止worker

package main

import (
    "fmt"
    "math/rand"
    "time"

    "golang.org/x/net/context"
)

type Job int

func workPool(workerNum int, jobChan chan Job, ctx context.Context) {
    for i := 0; i < workerNum; i++ {
        go func(i int) {
            worker(i, jobChan, ctx)
        }(i)
    }
}

// 通过context取消未完成的job
func worker(n int, jobChan <-chan Job, ctx context.Context) {
    for {
        select {
        case job := <-jobChan:
            Process(n, job)

        case <-ctx.Done():
            fmt.Printf("cancel worker %d\n", n)
            return
        }
    }
}

func Process(n int, job Job) {
    size := randTime()
    time.Sleep(size * time.Millisecond)
    fmt.Printf("worker %2d process job %2d, time %dms\n", n, job, size)
}

// 随机时间100~500
func randTime() time.Duration {
    rand.Seed(time.Now().UnixNano())
    return time.Duration(rand.Intn(400) + 100)
}

func main() {
    jobChan := make(chan Job, 10)

    // 使用context控制worker是否停止，适合多级函数传递和控制，并且有超时取消
    ctx, cancel := context.WithCancel(context.Background())
    //ctx, cancel := context.WithTimeout(context.Background(), time.Second) // 可以设置延时的context
    workPool(5, jobChan, ctx)
    for i := 0; i < 20; i++ {
        jobChan <- Job(i)
    }

    cancel()
    time.Sleep(5 * time.Second)
}

/* 当次执行结果如下：
worker  2 process job  3, time 471ms
worker  3 process job  4, time 471ms
worker  1 process job  1, time 471ms
worker  4 process job  0, time 471ms
worker  0 process job  2, time 471ms
worker  3 process job  6, time 200ms
cancel worker 3
worker  4 process job  8, time 200ms
worker  2 process job  5, time 200ms
cancel worker 2
worker  0 process job  9, time 200ms
cancel worker 0 by context
worker  1 process job  7, time 200ms
cancel worker 1
worker  4 process job 10, time 310ms
cancel worker 4
*/

(2)使用channel停止worker

package main

import (
    "fmt"
    "math/rand"
    "time"
)

type Job int

func workPool(workerNum int, jobChan chan Job, ch chan struct{}) {
    for i := 0; i < workerNum; i++ {
        go func(i int) {
            worker(i, jobChan, ch)
        }(i)
    }
}

// 通过channel取消未完成的job
func worker(n int, jobChan <-chan Job, ch chan struct{}) {
    for {
        select {
        case job := <-jobChan:
            Process(n, job)

        case <-ch:
            fmt.Printf("cancel worker %d\n", n)
            return
        }
    }
}

func Process(n int, job Job) {
    size := randTime()
    time.Sleep(size * time.Millisecond)
    fmt.Printf("worker %2d process job %2d, time %dms\n", n, job, size)
}

// 随机时间100~500
func randTime() time.Duration {
    rand.Seed(time.Now().UnixNano())
    return time.Duration(rand.Intn(400) + 100)
}

func main() {
    jobChan := make(chan Job, 10)

    // 使用channel控制worker是否停止
    ch := make(chan struct{})
    workPool(5, jobChan, ch)
    for i := 0; i < 20; i++ {
        jobChan <- Job(i)
    }

    close(ch)
    time.Sleep(5 * time.Second)

}

/* 当次执行结果如下：
worker  1 process job  1, time 313ms
worker  3 process job  4, time 313ms
worker  2 process job  3, time 313ms
worker  0 process job  2, time 313ms
worker  4 process job  0, time 313ms
worker  3 process job  6, time 258ms
cancel worker 3
worker  2 process job  7, time 258ms
worker  4 process job  9, time 258ms
cancel worker 4
worker  0 process job  8, time 258ms
worker  1 process job  5, time 258ms
cancel worker 1
worker  0 process job 11, time 190ms
cancel worker 0
worker  2 process job 10, time 226ms
worker  2 process job 12, time 485ms
cancel worker 2
*/

2.7 关闭事件跟踪器

package main

import (
    "context"
    "fmt"
    "time"
)

// Tracker 跟踪器  
type Tracker struct {  
   ch   chan string  
   stop chan struct{}  
}  
  
// NewTracker 实例化 func NewTracker() *Tracker {  
   return &Tracker{  
      ch:   make(chan string, 20),  
      stop: make(chan struct{}),  
   }  
}  
  
// Event 触发事件  
func (t *Tracker) Event(ctx context.Context, data string) error {  
   select {  
   case t.ch <- data:  
      return nil  
   case <-ctx.Done():  
      return ctx.Err()  
   }  
}  
  
// Run 执行  
func (t *Tracker) Run() {  
   for data := range t.ch {  
      fmt.Println(data)  
      time.Sleep(time.Second * 10)  
   }  
   t.stop <- struct{}{}  
}  
  
// Shutdown 关闭  
func (t *Tracker) Shutdown(ctx context.Context) {  
   close(t.ch)  
   select {  
   case <-t.stop:  
      fmt.Println("正常结束")  
   case <-ctx.Done():  
      fmt.Println("超时结束")  
   }  
}

func main() {  
   ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(time.Second*2))  
   defer cancel() 
    
   tr := NewTracker()  
   go tr.Run()  
  
   tr.Event(ctx, "data1")  
   tr.Event(ctx, "data2")  
   tr.Event(ctx, "data3")  
  
   tr.Shutdown(ctx)

/*
执行结果：

data1
超时结束
*/
}

3 注意事项

未初始化的channel，读取里面的数据时，会造成死锁deadlock

var ch chan int
<-ch  // 未初始化channel读数据会死锁`

未初始化的channel，往里面写数据时，会造成死锁deadlock

var ch chan int
ch<-  // 未初始化channel写数据会死锁

未初始化的channel，关闭该channel时，会panic

var ch chan int
close(ch) // 关闭未初始化channel，触发panic

向已关闭的channel写数据，会pannic

var ch =make(chan int)
close(ch) 
ch<-1 // channel已关闭，触发panic

本文链接：https://zhuyasen.com/post/channel.html，参与评论 »

#runtime #GMP #goroutine

go语言组成有两部分，一部分是用户程序代码，一部分是runtime，runtime作用是为了实现额外功能，在程序运行时自动加载/运行的的一些模块，runtime由4部分组成：

• Scheduler: 调度器管理所有的GMP，在后台执行调度循环。
• Memory Management: 当代码需要内存时，负责内存分配工作。
• Garbage Collector: 当内存不再需要时，负责回收内存。
• Netpoll: 网络轮询负责管理网络FD相关的读写、就绪事件。

调度器 Scheduler

协程调度器GMP

调度器本质是一个生产-消费流程，用户在程序中执行go func{}生成一个协程实体，提交到协程调度器，线程来执行(消费)。

• G: goroutine，一个计算任务。由需要执行的代码和其上下文组成，上下文包括：当前代码位置，栈顶、栈底地址，状态等。
• M: machine，系统线程，执行实体，想要在CPU上执行代码，必须有线程，与C语⾔中的线程相同，通过系统调⽤clone来创建。
• P: processor，虚拟处理器，M必须获得P才能执行代码，否则必须陷入休眠(后台监控线程除外)，你也可以将其理解为⼀种token ，有这个token，才有在物理CPU核心上执行的权力。

协程框架图

上图左边是表示协程生产过程，包括虚拟处理器部分P和队列部分，每个P下面有runnext和local run quene，而global run quene是全局链表，所有P都可以共享，G执行优先级别最高是runnext，其次是本地队列，最后是全局队列。

• runnext: 下一个执行的G，类型是一个值。
• local run quene：每个P自己队列，类型是数组，最大长度为256。
• global run quene，全局队列，类型是链表，长度没有限制。

为什么队列要分为本地队列和全局队列？

为了在性能上达到更好目标，每个P执行自己的本地队列，不需要枷锁，而不同P之间频繁从全局队列获取G时要加锁的，队列分级就是避免频繁加锁，提高并发性能。


为什么最新创建的协程会被放到runnext去优先执行？

在计算机执行过程中，程序分为代码的局部性和数据的局部性，根据局部性原理，最近调用的代码，很大概率需要再一次调用，优先级更高，程序执行到当前时刻，变量和数据很大概率在当前CPU访问的cache里，因此访问效率也是最高的。刚刚创建的G很大概率是高优先级的G，因此放到runnext去优先执行。

上图的右边是协程的消费端，包括系统线程部分，工作的线程绑定P后一直调度循环，线程是按需创建的，空闲的线程在队列里，需要时再拿出来。

协程生产端

新创建的协程加入队列的流程图

使用go func()函数，通过newproc打包生产一个G，newproc里面做了申请栈、判断当前runnext、本地队列、全局队列是否需要对已存在的G进行转移，有三种情况：

• 第一种情况：runnext为空，新创建的G直接放到runnext去执行。
• 第二种情况：runnext为不空，本地队列未满(最大256)，把runnext旧的G转移到本地队列，新创建的G放到runnext去执行。
• 第三种情况：runnext为不空，本地队列已满(最大256)，把runnext旧的G和和本地队列的一半G放到全局队列(全局队列时链表，理论是无限大)，新创建的G放到runnext去执行。

协程消费端

协程消费端框架图

消费过程：

每循环调度一次schedtick值加1，每轮询60次本地队列，就去全局队列获取，目的是让全局队列的G也有机会被执行。

schedtick对60取模等于0的消费过程

全局队列不为空，本地队列不为空情况，从全局队列获取一个G来执行。

schedtick对60取模不为0的消费过程

• 当runnext有G，直接从runnext获取G执行。
• 当runnext为空，本地队列有G，从本地队列中获取G执行
• 当runnext为空，本地队列为空，全局队列有G，从全局队列获一批G来执行，从全局队列获取G数量规则是从全局队列获取一半，如果数量超过128，最大值取128，获取的是全局队列的尾部。
• 当runnext为空，本地队列为空，全局队列为空，查询其他线程的本地队列是否有G，如果其他P的本地队列有G，就从其他P的本地队列偷取一半(后半部分)到本地队列执行，如果其他P的本地队列也为空，则挣扎一下再查询一遍，如果全局和其他P都为空，然后进入休眠状态。

阻塞

上面的goroutine都是正常执行，当goroutine出现阻塞怎么处理呢。有些阻塞可以被runtime拦截，有些阻塞不能被runtime拦截。

runtime可以拦截的阻塞

常见会出现阻塞场景

(1) 调用time.Sleep函数

(2) 一直往channel写数据，另一端没来得及读取channel

(3) 一直读取channel数据，另一端没来得及写数据到channel

(4) 使用select，如果都没有出发channel，会阻塞

selct {
    case <-c1:
        fmt.Println("c1 read")
    case <-c2:
        fmt.Println("c2 read")    
}

(5) 锁，当资源被锁了，还没释放，另一个goroutine获取不到锁，出现阻塞

(6) 网络读写

var conn net.Conn
var buf = make([]byte, 1024)

// 读，没数据时阻塞
conn.Read(buf)

// 写，缓冲满时阻塞
conn.Write(buf)

runtime 不能拦截的阻塞

有些阻塞runtime不能被捕获到，例如cgo、系统调用，执行c代码或系统调用时，如果长时间运行需要剥离P执行，单独占用⼀个线程。

阻塞处理

如果一个8核处理器的8个线程同时都执行系统调用，而且都阻塞了，怎么办？

需要一个专有线程sysmon(system monitor)专门处理这个问题，sysmon线程拥有优高先级，而且不需要绑定P就可以执行。

sysmon主要功能有三个：

• checkdead: 检查所有线程是否都已经被阻塞了，如果是，则抛出异常，如果只是网络服务，这个检测不起作用，因为accept是正常运行的，不要被字面意思误解为可以检查死锁。
• netpoll: 将g列表注入全局运行队列。
• retake: 如果是syscall卡了很久，那就把p剥离(handoffp)，如果是用户g运行很久了(10ms)，那么发信号SIGURG抢占。

内存管理 Memory Management

内存管理的三个角色

内存管理概览

内存管理抽象

进程对应虚拟内存布局

内存分配器类型

(1) 线性分配器(Bump/Sequential Allocator)

Bump Sequential不会复用已经释放的内存，产生比较多内存碎片，基本不使用，Sequential Allocator可以复用已经释放内存，但是要额外维护一个free链表。

(2) 空闲链表分配器(Free List Allocator)

空闲链表分配器有first-fit、next-fit、best-fit、segregate-fit几种，go使用的是segregate-fit，减少内存碎片。

go语言内存分配

执行malloc时

• 分配内存小于128kb，brk只能通过调整 program break 位置推动堆增⻓
• 分配内存大于128kbmmap 可以从任意未分配位置映射内存

内存分配器在 Go 语⾔中维护了⼀个多级结构：mcache –> mcentral –> mheap

go的内存分类，预先分配好内存。

// class  bytes/obj  bytes/span  objects  tail waste  max waste  min align  
//     1          8        8192     1024           0     87.50%          8  
//     2         16        8192      512           0     43.75%         16  
//     3         24        8192      341           8     29.24%          8  
//     4         32        8192      256           0     21.88%         32  
//     5         48        8192      170          32     31.52%         16  
//     6         64        8192      128           0     23.44%         64  
//     7         80        8192      102          32     19.07%         16  
//     8         96        8192       85          32     15.95%         32  

...

//    66      28672       57344        2           0      4.91%       4096  
//    67      32768       32768        1           0     12.50%       8192

堆内存管理有Tiny alloc、Small alloc、Large alloc几种方式

• Tiny alloc分配内存

• Small alloc分配内存

• Large alloc分配内存

⼤对象分配会直接越过mcache 、 mcentral ，直接从mheap进⾏相应数量的page分配，pageAlloc 结构经过多个版本的变化，从： freelist -> treap -> radix tree ，查找时间复杂度越来越低，结构越来越复杂。

Refill 流程：

• 本地 mcache 没有时触发 (mcache.refill)
• 从 mcentral ⾥的 non-empty 链表中找 (mcentral.cacheSpan)
• 尝试 sweep mcentral 的 empty ， insert sweeped -> non-empty(mcentral.cacheSpan)
• 增⻓ mcentral ，尝试从 arena 获取内存 (mcentral.grow)
• arena 如果还是没有，向操作系统申请 (mheap.alloc)

最终还是会将申请到的mspan放在mcache中，如下图所示：

mspan内部结构

go的变量分配在栈和堆是由编译器自动分配的，编译器如果能在编译期间确定变量的生命周期，就会在栈上分配，否则就是逃逸行为，需要在堆上分配内存。分配效率栈大于堆，空间大小堆大于栈。

常见变量逃逸场景：

• 函数返回内部变量的指针
• 发送指针或带有指针的值到 channel 中
• 在一个切片上存储指针或带指针的值
• slice 的背后数组被重新分配了，因为 append 时可能会超出其容量（cap）
• 在 interface 类型上调用方法
• 申请内存容量过大

编译过程进行逃逸分析命令：

# 示例
go build -gcflags="-m" main.go

# 参数-m越多，打印信息越详细
go build -gcflags="-m -m" main.go

垃圾回收 Garbage Collector

内存垃圾类型分为语义垃圾和语法垃圾两种。

语义垃圾(semantic garbage)，有的被称作内存泄露，语义垃圾指的是从语法上可达 ( 可以通过局部、全局变量引⽤得到 ) 的对象，但从语义上来讲他们是垃圾，垃圾回收器对此⽆能为⼒。

type a sturct {
    
}

s:=make([]*a, 10,10)
s=s[:5]

// 后面5个在堆上的内存语义上是应该回收，实际是一直占用内存的

语法垃圾(syntactic garbage)，那些从语法上⽆法到达的对象，这些才是垃圾收集器主要的收集⽬标。

func fHeap()  {  
   s := make([]int, 10240)  
   fmt.Println(s)  
}

// 执行完函数，变量s内存会被回收

垃圾回收算法：

• 引用计数 (Reference Counting) ：某个对象的根引用计数变为0时，其所有子节点均需被回收。
• 标记压缩 (Mark-Compact) ：将存活对象移动到⼀起，解决内存碎片问题。
• 复制算法 (Copying) ：将所有正在使⽤的对象从From复制到To空间，堆利用率只有⼀半。
• 标记清扫 (Mark-Sweep) ：解决不了内存碎片问题。需要与能尽量避免内存碎片的分配器使用，如tcmalloc，go使用的垃圾回收算法。

触发gc条件：

• 人工runtime.GC
• 需要分配内存时runtime.mallocgc
• 强制gc forcegchelper

三色抽象:

具体过程看 https://www.kancloud.cn/aceld/golang/1958308#GC_376

具体过程

垃圾回收以STW作为界限可以分为5个阶段：

写屏障是一个在并发垃圾回收器中才会出现的概念，垃圾回收器的正确性体现在：不应出现对象的丢失，也不应错误的回收还不需要回收的对象。

(1) 标记设置

收集开始时，必须执行的第一个活动是打开写入屏障。写屏障的目的是允许收集器在收集期间保持堆上的数据完整性，因为收集器和应用程序 goroutine 将同时运行。为了打开 Write Barrier，必须停止运行的每个应用程序 goroutine，这个过程时间非常快，平均在10~30微秒内。

(2) 标记

一旦打开写屏障，收集器就会开始标记阶段，收集器做的第一件事就是为自己至少占用25%的可用CPU容量(如果有4个线程，一个用于执行GC)，这个阶段用户gc的goroutine和普通goroutine是并发执行的。如果收集内存对象速度赶不上新内存分配速度，收集器把原来执行应用程序 goroutine用来协助标记工作，这称为标记辅助。任何应用程序 Goroutine 被放置在 Mark Assist 中的时间量与它添加到堆内存中的数据量成正比，Mark Assist的作用是助于更快地完成收集。

并发标记，默认所有对象都是白色，使用三色标记法，优先扫描各个goroutine的栈对象，从根节点开始遍历所有对象，将可达的对象标记为黑色，再扫描标记堆对象。

并发扫描标记期间，其他goroutine在栈和堆有可能出现新建对象、对象引用指向变更等场景，有些场景会触发写屏障，写屏障只发生在堆的对象，栈对象的引用改变不会引起屏障触发，因为go是并发运行的，大部分的操作都发生在栈上，成千上万goroutine的栈都进行屏障保护会有性能问题。

场景1：并发扫描标记期间其他goroutine在栈或堆上创建的新对象

这些新建对象统一标记为黑色。

场景2：并发扫描标记期间，一个栈对象(编号1)引用一个堆对象(编号7)

因为对象1是在栈区，不启动写屏障，对象1标记为黑色，后面对象7被扫描到时标记为黑色。

场景3：并发扫描标记期间，一个新建的栈对象(编号9)引用一个栈对象(编号3)，同时原来一个栈对象(编号2)删除引用对象(编号3)

因为对象都是在栈区，不会触发写屏障，对象9标记为黑色，后面扫描到对象3时标记为黑色。

场景4：并发扫描标记期间，一个堆对象(编号10)引用一个堆对象(编号7)

因为是在堆区，会触发写屏障，对象10为黑色，此时对象7标记为灰色，下游对象6被保护，后面扫描到对象7和对象6会时会标记为黑色。

场景5：并发扫描标记期间，一个堆对象(编号4)删除引用堆对象(编号7)

因为对象4是在堆区，会触发写屏障，此时对象7标记为灰色，最终标记为黑色。

混合写屏障规则：

• GC开始将栈上的对象全部扫描并标记为黑色(之后不再进行第二次重复扫描，无需STW)。
• GC期间，任何在栈上创建的新对象，均为黑色。
• 被删除的对象标记为灰色。
• 被引用的对象标记为灰色。

使用变形的弱三色不变式

(3) 标记终止

标记工作完成后，下一阶段是标记终止。这阶段关闭Write Barrier，执行各种清理任务，计算下一个收集目标的时时间。在标记阶段发现自己处于紧密循环中的 Goroutines 也可能导致标记终止 STW 延迟延长，这个过程时间非常快，平均在60~90微秒内。

(4) 扫除

收集完成后会发生另一个活动叫扫除(sweeping)，扫除是指与堆内存中未标记为正在使用的值关联的内存被回收。当应用程序 Goroutine 尝试在堆内存中分配新值时，会发生此活动。

• gcStart –> gcBgMarkWorker && gcRootPrepare，这时gcBgMarkWorker在休眠中  
• schedule –> findRunnableGCWorker，唤醒适宜数量的gcBgMarkWorker
• gcBgMarkWorker –> gcDrain –> scanobject –> greyobject(set mark bit and put to gcw)
• 在 gcBgMarkWorker 中调⽤ gcMarkDone 排空各种 wbBuf 后，使⽤分布式 termination 检查算法，进入gcMarkTermination –> gcSweep 唤醒后台沉睡的 sweepg 和 scvg –> sweep –> wake bgsweep && bgscavenge

Golang各个版本垃圾回收区别：

• GoV1.3 普通标记清除法，整体过程需要启动STW，效率极低。

• GoV1.5 三色标记法， 堆空间启动写屏障，栈空间不启动，全部扫描之后，需要重新扫描一次栈(需要STW)，效率普通

• GoV1.8 三色标记法，混合写屏障机制， 栈空间不启动，堆空间启动，整个过程几乎不需要STW，效率较高。

GC跟踪

在运行任何 Go 应用程序时，可以通过GODEBUG在选项中包含环境变量来生成 GC 跟踪。gctrace=1每次发生收集时，运行时都会将 GC 跟踪信息写入stderr.

# 示例
GODEBUG=gctrace=1 ./app

gc 1405 @6.068s 11%: 0.058+1.2+0.083 ms clock, 0.70+2.5/1.5/0+0.99 ms cpu, 7->11->6 MB, 10 MB goal, 12 P

各个值的含义：
// General
gc 65       : 自程序开始以来运行了65次GC
@6.068s     : 程序开始后的6秒
11%         : 到目前为止，有11%的可用CPU被用在了GC上

// Wall-Clock
0.058ms     : STW        : 标记开始，打开写屏障
1.2ms       : Concurrent : 标记时间
0.083ms     : STW        : 标记终止，写入障碍物关闭和清理

// CPU Time
0.70ms      : STW        : 标记开始
2.5ms       : Concurrent : 标记-辅助时间（GC与分配一致）
1.5ms       : Concurrent : 标记 - 背景GC时间
0ms         : Concurrent : 标记 - 闲置的GC时间
0.99ms      : STW        : 标记终止

// Memory
7MB         : 记开始前使用的堆内存
11MB        : 标记结束后使用中的堆内存
6MB         : 标记结束后，堆内存被标记为活的
10MB        : 标记结束后，堆内存的收集目标是使用中的

// Threads
12P         : 用于运行Goroutines的逻辑处理器或线程的数量

上面是在日志打印每次垃圾回收数据，不够直观，可以使用go tool trace命令，通过图形化界面查看程序生命周期内的所有协程执行过程(包括gc过程)。

(1) 首先在程序中插入跟踪程序代码：

// 在程序当前目录生成trace.out文件
type Trace struct {
    F *os.File
}

func (t *Trace) Start() {
    var err error
    t.F, err = os.Create("trace.out")
    if err != nil {
        panic(err)
    }

    err = trace.Start(t.F)
    if err != nil {
        panic(err)
    }
}

func (t *Trace) Stop() {
    trace.Stop()
    t.F.Close()
}

func main() {
    tr := &Trace{}
    tr.Start()
    defer tr.Stop()
    
    // 你的程序
}

(2) 执行你的程序代码，等待程序正常结束，在程序当前目录下生成trace.out

(3) 查看程序跟踪信息

go tool trace trace.out

在浏览器显示支持跟踪类型

• View trace
• Goroutine analysis
• Network blocking profile (⬇)
• Synchronization blocking profile (⬇)
• Syscall blocking profile (⬇)
• Scheduler latency profile (⬇)
• User-defined tasks
• User-defined regions
• Minimum mutator utilization

点击第一个View trace，选中小控制面板的zoom，在指定位置点击鼠标左键网上拖动放大细节，如下图所示：

从图中可以看出，在垃圾回收阶段，处理器1和处理器2是专门用来给收集器收集对象，其中处理器3也会辅助标记，使得更快的完成收集，并发收集对象过程中也有用户程序在执行，同时看到在垃圾回收这个过程出现两次STW。

在垃圾收集启动期间，运行时会调用 runtime.gcBgMarkStartWorkers 为全局每个处理器创建用于执行后台标记任务的 Goroutine，每一个 Goroutine 都会运行 runtime.gcBgMarkWorker，所有运行 runtime.gcBgMarkWorker 的Goroutine在启动后都会陷入休眠等待调度器的唤醒。一般情况下此函数不会占用这么多的 cpu，出现这种情况一般都是内存 gc 问题，如果分配对象的数量非常多，采集器来不及采集对象，就会唤醒runtime.gcBgMarkWorker的goroutine进行台标记。

参考：

• Go 中的垃圾回收 https://www.ardanlabs.com/blog/2018/12/garbage-collection-in-go-part1-semantics.html
• Golang三色标记+混合写屏障GC模式全分析 https://www.kancloud.cn/aceld/golang/1958308#GC_376
• go tool trace https://making.pusher.com/go-tool-trace/
• 揭秘 Golang 内存管理优化 https://cdmana.com/2021/10/20211031083312698S.html
• 垃圾收集器 https://draveness.me/golang/docs/part3-runtime/ch07-memory/golang-garbage-collector/

本文链接：https://zhuyasen.com/post/runtime.html，参与评论 »

go调试工具

1 概念

Delve是一个用于Go程序的源码级调试器，通过控制程序的执行与你的程序互动，评估变量，并提供线程/goroutine状态、CPU寄存器状态等信息，目标是为调试Go程序提供一个简单而强大的接口。

使用方法：

dlv [command]

可用的命令：
  attach    连接到正在运行的进程并开始调试。
  connect   连接到一个无头调试服务器。
  core      检查一个核心转储。
  dap       [EXPERIMENTAL] 启动一个通过Debug Adaptor Protocol (DAP)通信的TCP服务器。
  debug     编译并开始调试当前目录下的主包，或指定的包。
  exec      执行一个预编译的二进制文件，并开始调试会话。
  help      关于任何命令的帮助
  run       已废弃的命令。使用'debug'代替。
  test      编译测试二进制文件并开始调试程序。
  trace     编译并开始追踪程序。
  version   打印版本。

可用标志：
      --accept-multiclient 允许无头服务器接受多个客户端连接。
      --api-version int 选择无头时的API版本。(默认为1)
      --backend string 后台选择（见'dlv help backend'）。(默认为 "default")
      --build-flags string 构建标志，将被传递给编译器。
      --check-go-version 检查正在使用的Go的版本是否与Delve兼容。(默认为true)
      --headless 只运行调试服务器，在无头模式下。
      --init string 启动文件，由终端客户端执行。
  -l, --listen string 调试服务器监听地址。(默认为 "127.0.0.1:0")
      --log 启用调试服务器的日志记录。
      --log-dest string 将日志写到指定的文件或文件描述符（见'dlv help log'）。
      --log-output string 逗号分隔的应该产生调试输出的组件列表(见'dlv help log')
      --only-same-user 只允许启动这个Delve实例的同一个用户的连接。(默认为true)
      --wd string 运行程序的工作目录。(默认为".")

2 debug和exec命令

使用debug命令是从源码编译成二进制后进入调试会话，在本地目录下编译出来的__debug_bin临时文件，结束调试会话会自动删除临时文件__debug_bin，debug命令进入调试会话：

dlv debug –check-go-version=false

使用exec命令指定编译后的二进制文件进入调试会话，也就是比debug少了编译过程，exec 命令进入调试交互会话：

dlv exec <binary file> –check-go-version=false

调试会话命令说明：

运行程序命令：
    call ------------------------ 恢复进程，注入一个函数调用（实验性的！！）。
    continue (alias: c) --------- 运行到断点或程序终止。
    next (alias: n) ------------- 跨越到下一个源代码行。
    restart (alias: r) ---------- 重新启动程序。
    step (alias: s) ------------- 单个程序的步骤。
    step-instruction (alias: si)  单步执行一条cpu指令。
    stepout (alias: so) --------- 走出当前函数。

操纵断点命令：
    break (alias: b) ------- 设置一个断点。
    breakpoints (alias: bp)  打印出活动断点的信息。
    clear ------------------ 删除断点。
    clearall --------------- 删除多个断点。
    condition (alias: cond)  设置断点条件。
    on --------------------- 当断点被击中时，执行一条命令。
    trace (alias: t) ------- 设置跟踪点。

查看程序变量和内存命令：
    args ----------------- 打印函数参数。
    display -------------- 每次程序停止时打印表达式的值。
    examinemem (alias: x)  检查内存。
    locals --------------- 打印本地变量。
    print (alias: p) ----- 评估一个表达式。
    regs ----------------- 打印CPU寄存器的内容。
    set ------------------ 改变一个变量的值。
    vars ----------------- 打印软件包变量。
    whatis --------------- 打印一个表达式的类型。

列出并在线程和goroutine之间切换命令：
    goroutine (alias: gr) -- 显示或改变当前的goroutine
    goroutines (alias: grs)  列出程序的goroutine。
    thread (alias: tr) ----- 切换到指定的线程。
    threads ---------------- 打印出每个被追踪的线程的信息。

查看调用栈和选择帧命令：
    deferred --------- 在一个延迟调用的背景下执行命令。
    down ------------- 将当前帧向下移动。
    frame ------------ 设置当前帧，或在不同的帧上执行命令。
    stack (alias: bt)  打印堆栈跟踪。
    up --------------- 将当前帧向上移动。

其他命令：
    config --------------------- 更改配置参数。
    disassemble (alias: disass)  反汇编程序。
    edit (alias: ed) ----------- 打开你在$DELVE_EDITOR或$EDITOR中的位置
    exit (alias: quit | q) ----- 退出调试器。
    funcs ---------------------- 打印函数的列表。
    help (alias: h) ------------ 打印帮助信息。
    libraries ------------------ 列出加载的动态库
    list (alias: ls | l) ------- 显示源代码。
    source --------------------- 执行一个包含delve命令列表的文件
    sources -------------------- 打印源文件的列表。
    types ---------------------- 打印类型列表

3 简单调试示例

文件列表

.
├── cal
│   └── cal.go
└── main.go

main.go代码

package main

import (
        "demo/calculators/cal"
        "fmt"
    "time"
)

func main() {
        v := cal.Cal{12, 3}

        go func() {
                time.Sleep(time.Minute)
        }()

        fmt.Println(v.Add())
        fmt.Println(v.Sub())
        fmt.Println(v.Mul())
        fmt.Println(v.Div())

    time.Sleep(time.Second * 5)
}

cal.go代码

package cal

type Cal struct {
        X1 int
        X2 int
}

func (c *Cal)Add() int {
        return c.X1 +c.X2
}
func (c *Cal)Sub() int {
        return c.X1 -c.X2
}

func (c *Cal)Mul() int {
        return c.X1 *c.X2
}

func (c *Cal)Div() int {
        return c.X1 / c.X2
}

进入调试会话

dlv debug main.go

(1) 打断点

Type 'help' for list of commands.
(dlv) b main.main
Breakpoint 1 set at 0x494b2f for main.main() ./main.go:9
(dlv) b main.go:16
Breakpoint 2 set at 0x494b6c for main.main() ./main.go:16
(dlv) b main.go:17
Breakpoint 3 set at 0x494bff for main.main() ./main.go:17
(dlv) b main.go:18
Breakpoint 4 set at 0x494c90 for main.main() ./main.go:18
(dlv) b main.go:19
Breakpoint 5 set at 0x494d25 for main.main() ./main.go:19

查看断点列表

(dlv) bp
Breakpoint runtime-fatal-throw at 0x432f00 for runtime.fatalthrow() /usr/local/go/src/runtime/panic.go:1244 (0)
Breakpoint unrecovered-panic at 0x433000 for runtime.fatalpanic() /usr/local/go/src/runtime/panic.go:1271 (0)
        print runtime.curg._panic.arg
Breakpoint 1 at 0x494b2f for main.main() ./main.go:9 (0)
Breakpoint 2 at 0x494b6c for main.main() ./main.go:16 (0)
Breakpoint 3 at 0x494bff for main.main() ./main.go:17 (0)
Breakpoint 4 at 0x494c90 for main.main() ./main.go:18 (0)
Breakpoint 5 at 0x494d25 for main.main() ./main.go:19 (0)

清除断点使用 clearall命令

(2) 执行到断点或结束位置

(dlv) c
> main.main() ./main.go:9 (hits goroutine(1):1 total:1) (PC: 0x494b2f)
     4:         "demo/calculators/cal"
     5:         "fmt"
     6:     "time"
     7: )
     8:
=>   9: func main() {
    10:         v := cal.Cal{12, 3}
    11:
    12:         go func() {
    13:                 time.Sleep(time.Minute)
    14:         }()

(3) 执行下一个代码行

(dlv) n
> main.main() ./main.go:12 (PC: 0x494b5e)
     7: )
     8:
     9: func main() {
    10:         v := cal.Cal{12, 3}
    11:
=>  12:         go func() {
    13:                 time.Sleep(time.Minute)
    14:         }()
    15:
    16:         fmt.Println(v.Add())
    17:         fmt.Println(v.Sub())

(4) 查看和修改变量

(dlv) locals
v = demo/calculators/cal.Cal {X1: 12, X2: 3}

(dlv) set v.X2=4

(dlv) locals
v = demo/calculators/cal.Cal {X1: 12, X2: 4}

(dlv) print v
demo/calculators/cal.Cal {X1: 12, X2: 4}

(5) 查看调用栈信息

(dlv) bt
0  0x0000000000494bff in main.main
   at ./main.go:17
1  0x0000000000435273 in runtime.main
   at /usr/local/go/src/runtime/proc.go:255
2  0x000000000045f961 in runtime.goexit
   at /usr/local/go/src/runtime/asm_amd64.s:1581

(5) 查看goroutine

# 当前goroutine
(dlv) goroutine
Thread 67537 at ./main.go:16
Goroutine 1:
        Runtime: ./main.go:16 main.main (0x494b6c)
        User: ./main.go:16 main.main (0x494b6c)
        Go: <autogenerated>:1 runtime.newproc (0x461e29)
        Start: /usr/local/go/src/runtime/proc.go:145 runtime.main (0x435080)

# 所有goroutine
(dlv) goroutines
* Goroutine 1 - User: ./main.go:16 main.main (0x494b6c) (thread 67537)
  Goroutine 2 - User: /usr/local/go/src/runtime/proc.go:367 runtime.gopark (0x435692)
  Goroutine 3 - User: /usr/local/go/src/runtime/proc.go:367 runtime.gopark (0x435692)
  Goroutine 4 - User: /usr/local/go/src/runtime/proc.go:367 runtime.gopark (0x435692)
  Goroutine 5 - User: /usr/local/go/src/runtime/proc.go:367 runtime.gopark (0x435692)
  Goroutine 6 - User: ./main.go:12 main.main.func1 (0x494e00)
[6 goroutines]

(6) 打印每个被追踪的线程的信息

(dlv) threads
* Thread 67537 at 0x494b6c ./main.go:16 main.main
  Thread 67667 at 0x46119d /usr/local/go/src/runtime/sys_linux_amd64.s:146 runtime.usleep
  Thread 67668 at 0x46119d /usr/local/go/src/runtime/sys_linux_amd64.s:146 runtime.usleep
  Thread 67669 at 0x461723 /usr/local/go/src/runtime/sys_linux_amd64.s:520 runtime.futex
  Thread 67670 at 0x461723 /usr/local/go/src/runtime/sys_linux_amd64.s:520 runtime.futex

(7) 反汇编

(dlv) disassemble
TEXT main.main(SB) /home/vison/work/golang/project/src/demo/calculators/main.go
        main.go:9       0x494b20        4c8d642498                      lea r12, ptr [rsp-0x68]
        main.go:9       0x494b25        4d3b6610                        cmp r12, qword ptr [r14+0x10]
        main.go:9       0x494b29        0f86a8020000                    jbe 0x494dd7
        main.go:9       0x494b2f*       4881ece8000000                  sub rsp, 0xe8
        main.go:9       0x494b36        4889ac24e0000000                mov qword ptr [rsp+0xe0], rbp
        main.go:9       0x494b3e        488dac24e0000000                lea rbp, ptr [rsp+0xe0]
        main.go:10      0x494b46        440f117c2420                    movups xmmword ptr [rsp+0x20], xmm15
        main.go:10      0x494b4c        48c74424200c000000              mov qword ptr [rsp+0x20], 0xc
        main.go:10      0x494b55        48c744242803000000              mov qword ptr [rsp+0x28], 0x3
        main.go:12      0x494b5e        31c0                            xor eax, eax
        main.go:12      0x494b60        488d1d89dd0100                  lea rbx, ptr [rip+0x1dd89]
        main.go:12      0x494b67        e81484faff                      call $runtime.newproc
=>      main.go:16      0x494b6c*       488d442420                      lea rax, ptr [rsp+0x20]
        main.go:16      0x494b71        e80ae5fcff                      call $demo/calculators/cal.(*Cal).Add
        main.go:16      0x494b76        4889442418                      mov qword ptr [rsp+0x18], rax
        main.go:16      0x494b7b        440f117c2470                    movups xmmword ptr [rsp+0x70], xmm15
        main.go:16      0x494b81        488d4c2470                      lea rcx, ptr [rsp+0x70]
        main.go:16      0x494b86        48894c2448                      mov qword ptr [rsp+0x48], rcx
        main.go:16      0x494b8b        488b442418                      mov rax, qword ptr [rsp+0x18]
        main.go:16      0x494b90        e80b52f7ff                      call $runtime.convT64
        main.go:16      0x494b95        4889442440                      mov qword ptr [rsp+0x40], rax
        main.go:16      0x494b9a        488b4c2448                      mov rcx, qword ptr [rsp+0x48]
        main.go:16      0x494b9f        8401                            test byte ptr [rcx], al
        main.go:16      0x494ba1        488d15f86d0000                  lea rdx, ptr [rip+0x6df8]
        main.go:16      0x494ba8        488911                          mov qword ptr [rcx], rdx
        main.go:16      0x494bab        488d7908                        lea rdi, ptr [rcx+0x8]
        main.go:16      0x494baf        833deab30c0000                  cmp dword ptr [runtime.writeBarrier], 0x0
        main.go:16      0x494bb6        7402                            jz 0x494bba
        main.go:16      0x494bb8        eb08                            jmp 0x494bc2
        main.go:16      0x494bba        48894108                        mov qword ptr [rcx+0x8], rax
        main.go:16      0x494bbe        6690                            data16 nop
        main.go:16      0x494bc0        eb07                            jmp 0x494bc9
        main.go:16      0x494bc2        e8d9adfcff                      call $runtime.gcWriteBarrier
        main.go:16      0x494bc7        eb00                            jmp 0x494bc9
        main.go:16      0x494bc9        488b442448                      mov rax, qword ptr [rsp+0x48]
        main.go:16      0x494bce        8400                            test byte ptr [rax], al
        main.go:16      0x494bd0        eb00                            jmp 0x494bd2
        main.go:16      0x494bd2        48898424b0000000                mov qword ptr [rsp+0xb0], rax
        main.go:16      0x494bda        48c78424b800000001000000        mov qword ptr [rsp+0xb8], 0x1
        main.go:16      0x494be6        48c78424c000000001000000        mov qword ptr [rsp+0xc0], 0x1
        main.go:16      0x494bf2        bb01000000                      mov ebx, 0x1
        main.go:16      0x494bf7        4889d9                          mov rcx, rbx
        main.go:16      0x494bfa        e8c1a8ffff                      call $fmt.Println
        main.go:17      0x494bff*       488d442420                      lea rax, ptr [rsp+0x20]
        main.go:17      0x494c04        e8b7e4fcff                      call $demo/calculators/cal.(*Cal).Sub
        main.go:17      0x494c09        4889442418                      mov qword ptr [rsp+0x18], rax
        main.go:17      0x494c0e        440f117c2470                    movups xmmword ptr [rsp+0x70], xmm15
        main.go:17      0x494c14        488d542470                      lea rdx, ptr [rsp+0x70]
        main.go:17      0x494c19        4889542438                      mov qword ptr [rsp+0x38], rdx
        main.go:17      0x494c1e        488b442418                      mov rax, qword ptr [rsp+0x18]
        main.go:17      0x494c23        e87851f7ff                      call $runtime.convT64
        main.go:17      0x494c28        4889442430                      mov qword ptr [rsp+0x30], rax
        main.go:17      0x494c2d        488b542438                      mov rdx, qword ptr [rsp+0x38]
        main.go:17      0x494c32        8402                            test byte ptr [rdx], al
        main.go:17      0x494c34        488d35656d0000                  lea rsi, ptr [rip+0x6d65]
        main.go:17      0x494c3b        488932                          mov qword ptr [rdx], rsi
        main.go:17      0x494c3e        488d7a08                        lea rdi, ptr [rdx+0x8]
        main.go:17      0x494c42        833d57b30c0000                  cmp dword ptr [runtime.writeBarrier], 0x0
        main.go:17      0x494c49        7402                            jz 0x494c4d
        main.go:17      0x494c4b        eb06                            jmp 0x494c53
        main.go:17      0x494c4d        48894208                        mov qword ptr [rdx+0x8], rax
        main.go:17      0x494c51        eb07                            jmp 0x494c5a
        main.go:17      0x494c53        e848adfcff                      call $runtime.gcWriteBarrier
        main.go:17      0x494c58        eb00                            jmp 0x494c5a
        main.go:17      0x494c5a        488b442438                      mov rax, qword ptr [rsp+0x38]
        main.go:17      0x494c5f        8400                            test byte ptr [rax], al
        main.go:17      0x494c61        eb00                            jmp 0x494c63
        main.go:17      0x494c63        4889842498000000                mov qword ptr [rsp+0x98], rax
        main.go:17      0x494c6b        48c78424a000000001000000        mov qword ptr [rsp+0xa0], 0x1
        main.go:17      0x494c77        48c78424a800000001000000        mov qword ptr [rsp+0xa8], 0x1
        main.go:17      0x494c83        bb01000000                      mov ebx, 0x1
        main.go:17      0x494c88        4889d9                          mov rcx, rbx
        main.go:17      0x494c8b        e830a8ffff                      call $fmt.Println
        main.go:18      0x494c90*       488d442420                      lea rax, ptr [rsp+0x20]
        main.go:18      0x494c95        e866e4fcff                      call $demo/calculators/cal.(*Cal).Mul
        main.go:18      0x494c9a        4889442418                      mov qword ptr [rsp+0x18], rax
        main.go:18      0x494c9f        440f117c2470                    movups xmmword ptr [rsp+0x70], xmm15
        main.go:18      0x494ca5        488d542470                      lea rdx, ptr [rsp+0x70]
        main.go:18      0x494caa        4889542468                      mov qword ptr [rsp+0x68], rdx
        main.go:18      0x494caf        488b442418                      mov rax, qword ptr [rsp+0x18]
        main.go:18      0x494cb4        e8e750f7ff                      call $runtime.convT64
        main.go:18      0x494cb9        4889442460                      mov qword ptr [rsp+0x60], rax
        main.go:18      0x494cbe        488b542468                      mov rdx, qword ptr [rsp+0x68]
        main.go:18      0x494cc3        8402                            test byte ptr [rdx], al
        main.go:18      0x494cc5        488d35d46c0000                  lea rsi, ptr [rip+0x6cd4]
        main.go:18      0x494ccc        488932                          mov qword ptr [rdx], rsi
        main.go:18      0x494ccf        488d7a08                        lea rdi, ptr [rdx+0x8]
        main.go:18      0x494cd3        833dc6b20c0000                  cmp dword ptr [runtime.writeBarrier], 0x0
        main.go:18      0x494cda        7402                            jz 0x494cde
        main.go:18      0x494cdc        eb06                            jmp 0x494ce4
        main.go:18      0x494cde        48894208                        mov qword ptr [rdx+0x8], rax
        main.go:18      0x494ce2        eb07                            jmp 0x494ceb
        main.go:18      0x494ce4        e8b7acfcff                      call $runtime.gcWriteBarrier
        main.go:18      0x494ce9        eb00                            jmp 0x494ceb
        main.go:18      0x494ceb        488b442468                      mov rax, qword ptr [rsp+0x68]
        main.go:18      0x494cf0        8400                            test byte ptr [rax], al
        main.go:18      0x494cf2        eb00                            jmp 0x494cf4
        main.go:18      0x494cf4        4889842480000000                mov qword ptr [rsp+0x80], rax
        main.go:18      0x494cfc        48c784248800000001000000        mov qword ptr [rsp+0x88], 0x1
        main.go:18      0x494d08        48c784249000000001000000        mov qword ptr [rsp+0x90], 0x1
        main.go:18      0x494d14        bb01000000                      mov ebx, 0x1
        main.go:18      0x494d19        4889d9                          mov rcx, rbx
        main.go:18      0x494d1c        0f1f4000                        nop dword ptr [rax], eax
        main.go:18      0x494d20        e89ba7ffff                      call $fmt.Println
        main.go:19      0x494d25*       488d442420                      lea rax, ptr [rsp+0x20]
        main.go:19      0x494d2a        e831e4fcff                      call $demo/calculators/cal.(*Cal).Div
        main.go:19      0x494d2f        4889442418                      mov qword ptr [rsp+0x18], rax
        main.go:19      0x494d34        440f117c2470                    movups xmmword ptr [rsp+0x70], xmm15
        main.go:19      0x494d3a        488d542470                      lea rdx, ptr [rsp+0x70]
        main.go:19      0x494d3f        4889542458                      mov qword ptr [rsp+0x58], rdx
        main.go:19      0x494d44        488b442418                      mov rax, qword ptr [rsp+0x18]
        main.go:19      0x494d49        e85250f7ff                      call $runtime.convT64
        main.go:19      0x494d4e        4889442450                      mov qword ptr [rsp+0x50], rax
        main.go:19      0x494d53        488b542458                      mov rdx, qword ptr [rsp+0x58]
        main.go:19      0x494d58        8402                            test byte ptr [rdx], al
        main.go:19      0x494d5a        488d353f6c0000                  lea rsi, ptr [rip+0x6c3f]
        main.go:19      0x494d61        488932                          mov qword ptr [rdx], rsi
        main.go:19      0x494d64        488d7a08                        lea rdi, ptr [rdx+0x8]
        main.go:19      0x494d68        833d31b20c0000                  cmp dword ptr [runtime.writeBarrier], 0x0
        main.go:19      0x494d6f        7402                            jz 0x494d73
        main.go:19      0x494d71        eb06                            jmp 0x494d79
        main.go:19      0x494d73        48894208                        mov qword ptr [rdx+0x8], rax
        main.go:19      0x494d77        eb09                            jmp 0x494d82
        main.go:19      0x494d79        e822acfcff                      call $runtime.gcWriteBarrier
        main.go:19      0x494d7e        6690                            data16 nop
        main.go:19      0x494d80        eb00                            jmp 0x494d82
        main.go:19      0x494d82        488b442458                      mov rax, qword ptr [rsp+0x58]
        main.go:19      0x494d87        8400                            test byte ptr [rax], al
        main.go:19      0x494d89        eb00                            jmp 0x494d8b
        main.go:19      0x494d8b        48898424c8000000                mov qword ptr [rsp+0xc8], rax
        main.go:19      0x494d93        48c78424d000000001000000        mov qword ptr [rsp+0xd0], 0x1
        main.go:19      0x494d9f        48c78424d800000001000000        mov qword ptr [rsp+0xd8], 0x1
        main.go:19      0x494dab        bb01000000                      mov ebx, 0x1
        main.go:19      0x494db0        4889d9                          mov rcx, rbx
        main.go:19      0x494db3        e808a7ffff                      call $fmt.Println
        main.go:21      0x494db8        48b800f2052a01000000            mov rax, 0x12a05f200
        main.go:21      0x494dc2        e8997afcff                      call $time.Sleep
        main.go:22      0x494dc7        488bac24e0000000                mov rbp, qword ptr [rsp+0xe0]
        main.go:22      0x494dcf        4881c4e8000000                  add rsp, 0xe8
        main.go:22      0x494dd6        c3                              ret
        main.go:9       0x494dd7        e8048cfcff                      call $runtime.morestack_noctxt
        main.go:9       0x494ddc        0f1f4000                        nop dword ptr [rax], eax
        main.go:9       0x494de0        e93bfdffff                      jmp $main.main

其他命令使用方法使用help查看。

本文链接：https://zhuyasen.com/post/delve.html，参与评论 »

1 基本概念

Cobra是Go的CLI框架，它包含一个用于创建强大的现代 CLI 应用程序的库和一个用于快速生成基于 Cobra 的应用程序和命令文件的工具。Cobra基于三个基本概念commands,arguments和flags，其中commands代表行为，arguments代表数值，flags代表对行为的改变，命令使用示例：

APPNAME VERB NOUN --ADJECTIVE
# 或者
APPNAME COMMAND ARG --FLAG

# server是commands，port是flag 
hugo server --port=1313

# clone是commands，URL是arguments，brae是flags
git clone URL --bare

特点： - 简单的基于子命令的 CLI：app server、app fetch等。 - 完全符合 POSIX 的标志（包括短版和长版）。 - 嵌套子命令。 - 全局、本地和级联标志。 - cobra init appname使用&轻松生成应用程序和命令cobra add cmdname。 - 明智的建议(app srver……你的意思是app server？). - 命令和标志的自动帮助生成。 - -h,--help等的自动帮助标志识别。 - 为您的应用程序自动生成 bash 自动完成功能。 - 为您的应用程序自动生成的手册页。 - 命令别名，这样您就可以在不破坏它们的情况下进行更改。 - 定义您自己的帮助、使用等的灵活性。 - 与viper的可选紧密集成。

2 安装cobra

安装命令：

go get -u github.com/spf13/cobra/cobra

基本目录结构：

▾ appName/
    ▾ cmd/
        root.go
        yourCommand1.go
        yourCommand2.go
      main.go

2.1 人工构建Cobra应用

root.go文件内容如下：

package cmd  
  
import (  
   "github.com/spf13/cobra"
)  
  
var RootCmd = &cobra.Command{  
   Use:                "mpc",  
   Short:              "Manage Prometheus configuration",  
   Long:               `Manage Prometheus configuration`,  
   DisableSuggestions: true,  
   Run: func(cmd *cobra.Command, args []string) {  
      cmd.Traverse(args)  
   },  
}  

man.go文件内容如下：

package main  
  
import (  
   "mpc/cmd"  
   "os"
)  

  
func main() {  
   if err := cmd.RootCmd.Execute(); err != nil {  
      fmt.Println(err)  
      os.Exit(1)  
   }  
}

2.2 使用生成器构建Cobra应用

安装cobra后，在GOPATH文件夹github.com/spf13/cobra/cobra下使用go install在$GOPATH/bin路径下生成cobra.exe可执行命令。

# cobra -h

Usage:
  cobra [command]
 
Available Commands:
  add         向Cobra应用程序添加命令
  completion  完成为指定的shell生成自动完成脚本                 
  help        任何命令都需要帮助
  init        初始化Cobra应用程序                                             

Flags: 
  -a, --author string    作者姓名(默认为“您的姓名”)
      --config string    配置文件(默认值为$HOME/.cobra.yaml)
  -h, --help             cobra帮助
  -l, --license string   项目许可证名称
      --viper            使用Viper进行配置
                                                                                          
Use "cobra [command] --help" for more information about a command.

初始化根命令，在当前项目下生成cmd/root.go

cobra init

添加子命令，在当前项目下生成cmd/your_command.go

cobra add

3 使用规则

cobra三大件是commands,arguments和flags，下面介绍三大件用法。

3.1 commands

每个客户端命令都有一个根命令入口，其他子命令在根命令下延申，类似一颗树，例如根命令kubectl，其中一个子命令为kubectl apply

cobra的根命令和子命令的简单示例：

// kubectl根命令
rootCMD := &cobra.Command{  
   Use:           "kubectl",  
   Short:         "kubectl controls the Kubernetes cluster manager.",  
}

// 添加子命令
rootCMD.AddCommand(  
    applyCMD
)


// 一个子命令apply
applyCMD := &cobra.Command{  
   Use:           "apply",  
   Short:         "Apply a configuration to a resource by filename or stdin.", 
   RunE: func(cmd *cobra.Command, args []string) error {  
      // 执行命令逻辑
   }, 
}

cobra.Command对象下有很多属性，下面是一些常用属性设置

(1) 版本

如果在root命令上设置了version字段，Cobra会添加一个顶级的--version标志。运行带有-version标志的应用程序将使用版本模板将版本打印到标准输出。

rootCmd.Version="0.0.1"
// 或自定义版本
rootCmd.SetVersionTemplate("the version is 0.0.1")

(2) 运行前和运行后钩子

可以在命令的主运行函数之前或之后运行函数。PersistentPreRun和PreRun函数在运行之前执行，而PersistentPostRun和PostRun将在运行后执行。如果子函数不声明自己的函数，则它们将继承Persistent*Run函数，这些函数按以下顺序运行：

PersistentPreRun –> PreRun –> Run –> PostRun –> PersistentPostRun

带有错误返回执行顺序

PersistentPreRunE –> PreRunE –> RunE –> PostRunE –> PersistentPostRunE

(3) 发生“未知命令”时的建议

当发生“未知命令”错误时，Cobra将打印自动建议。这使得Cobra在发生拼写错误时的行为类似于git命令，如果不需要在命令中建议或调整字符串距离，可以通过属性禁止。

command.DisableSuggestions = true
command.SuggestionsMinimumDistance = 1

(4) 为命令生成文档

Cobra可以基于子命令、标志等生成文档。请在docs generation文档中阅读更多关于它的信息。

(5) shell补全

Cobra可以为以下shell生成shell完成文件：bash、zsh、fish、PowerShell。如果您在命令中添加更多信息，这些补全功能将非常强大和灵活。在Shell Completions中阅读更多关于它的信息。

3.2 arguments

命令可能有必须的参数，在cobra.Command对象属性下可以对参数进行处理，例如命令后面必须有且只有一个参数，示例代码如下：

rootCMD := &cobra.Command{  
   Use:           "kubectl",  
   Short:         "kubectl controls the Kubernetes cluster manager.",
   Args:          cobra.ExactArgs(1),
}

cobra提供校验参数函数： - NoArgs: 如果存在任何位置参数，该命令将报告错误。 - ArbitraryArgs: 该命令将接受任何args。 - OnlyValidArgs: 如果有任何位置参数不在命令的ValidArgs字段中，则该命令将报告错误。 - MinimumNArgs(int): 如果没有至少N个位置参数，则该命令将报告错误。 - MaximumNArgs(int): 如果位置参数超过N个，则该命令将报告错误。 - ExactArgs(int): 如果没有正好N个位置参数，则命令将报告错误。 - ExactValidArgs(int): 如果没有正好N个位置参数，或者如果有任何位置参数不在命令的ValidArgs字段中，则该命令将报告错误 - RangeArgs(min，max): 如果args的数目不在预期的最小和最大args数目之间，则命令将报告错误。

也可以在cobra.Command对象属性下的Run或RunE进行自定义校验，示例代码：

var resourceNameArg string

applyCMD := &cobra.Command{  
   Use:           "get",  
   Short:         "Display one or many resources.", 
   RunE: func(cmd *cobra.Command, args []string) error {
      if len(args) < 1 {  
         return fmt.Errorf("You must specify the type of resource to get, eg: kubectl get pod")
      }
      resourceArg = args[0]  
      args = args[1:]  

      // 执行命令逻辑
   }, 
}

3.2 flags

flags用来控制操作命令的操作方式。

(1) 本地flags

在本地分配一个flag，该flag只应用于该特定命令。

// flag s只在localCmd上起作用
localCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read from")

默认情况下，Cobra只解析目标命令上的本地flag，而忽略父命令上的任何本地flags。通过启用Command.TraverseChildren，Cobra将在执行目标命令之前解析每个命令上的本地flags。

command := cobra.Command{
  Use: "print [OPTIONS] [COMMANDS]",
  TraverseChildren: true,
}

(2) 持久flags

flag可以是持久的，这意味着该flag将可用于分配给它的命令以及该命令下的每个命令。对于全局flag，在根上指定一个标志作为持久标志。

// flag v将在rootCmd及以下的子命令上都生效
rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")

(3) 必须的flags

flags默认是可选的，如果希望命令在未设置flag时报告错误。

rootCmd.Flags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
rootCmd.MarkFlagRequired("region")

(4)viper绑定flags

var author string

func init() {
  rootCmd.PersistentFlags().StringVar(&author, "author", "YOUR NAME", "Author name for copyright attribution")
  viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
}

在本例中，持久标志author与viper绑定。注意：当用户未提供–author标志时，变量author将不会设置为config中的值。

4 一个完整的cobra使用示例

以一个管理prometheus的配置文件自动化运维工具mpc(https://github.com/zhufuyi/mpc )为例，mpc主要对prometheus.yaml文件的job、targets、labels三个对象增删改查，支持远程安装exporter，命令帮助信息如下：

$ mpc
manage prometheus configuration, add,delete,update job

Usage:
  mpc [command]

Available Commands:
  add         Add job,targets,labels to prometheus configuration file
  completion  Generate the autocompletion script for the specified shell
  delete      Delete job,targets,labels in prometheus configuration file
  exec        Install and run service to one remote server
  execs       Install and run service to multiple remote servers
  get         Show job,targets,labels from prometheus configuration file
  help        Help about any command
  reload      Make the prometheus configuration effective
  replace     Replace job,targets,labels to prometheus configuration file
  resources   List of supported resources

Flags:
  -h, --help      help for mpc
  -v, --version   version for mpc

Use "mpc [command] --help" for more information about a command.

参考：

• https://cobra.dev/

本文链接：https://zhuyasen.com/post/cobbra.html，参与评论 »

1 grpc概述

grpc 是一个高性能、开源的rpc框架，目前提供了多种语言版本，基于HTTP/2标准设计，拥有双向流、流控、头部压缩、单TCP连接上的多复用请求特性，接口描述语言使用protobuf。

在grpc中，一共有四种调用方式：

• 一元RPC(unary RPC): 称为单次RPC，也就是一问一答RPC请求，是最基础最常用的调用方式。
• 服务端流式RPC(Server-side Streaming RPC): 是一个单向流，客户端发起一次普通RPC请求，服务端通过流式返回数据集。
• 客户端流式RPC(Client-side Streaming RPC): 是一个单向流，客户端通过流式发送数据集，服务端回复一次普通RPC请求。
• 双向流式RPC(Bidirectional Streaming RPC): 由客户端以流式发起请求，服务端同样以流式方式响应请求。一定有客户端发起，但交互方式(谁先谁后、一次发多少、相应多少、什么时候关闭)则由程序编写的方式来控制(可以结合协程)。

Unary和Stream相比，因为省掉了中间每次建立连接的花费，所以效率上会提升一些。

grpc调用流程：

• 客户端发起调用，即在程序中调用某个方法；
• 对请求信息使用protobuf进行对象序列化后发给服务端；
• 服务端接收请求后，解码请求信息，进行业务逻辑处理；
• 对处理结果使用protobuf进行对象序列化压缩后返回给客户端；
• 客户端接收到服务端响应后，解码结果。

grpc优点：

• 性能好，比json编解码数读快几十倍。
• 代码生成方便，使用proto工具自动生成对应语言代码。
• 支持多种流传输方式，支持一元RPC、服务端流式RPC、客户端流式RPC、双流向RPC共4中传输流。
• 有超时和取消处理机制，客户端和服务端在截止时间后对取消事件进行相关处理。

grpc缺点：

• 可读性差
• 不支持浏览器调用
• 外部组件支持性差

使用场景

• unary(一元RPC)

  • CRUD的api调用

• service-side streaming(服务端流方式)

  • 股票app：客户端向服务端发送一个股票代码，服务端就把该股票的实时数据源源不断的返回给客户端
  • app的在线push：client先发请求到server注册，然后server就可以发在线push了

• client-side rpc streaming(客户端流方式)

  • 物联网终端向服务器报送数据

• bi-side rpc streaming(双向流方式)

  • 聊天机器人
  • 有状态的游戏服务器进行数据交换。比如LOL，王者荣耀等竞技游戏，client和server之间需要非常频繁地交换数据

2 grpc插件和使用命令

2.1 安装插件

把下载的可执行文件全部存放到$GOPATH/bin目录下。并且把proto依赖的包include存放到目录$GOPATH/bin/include下。

# 各个插件版本
# protoc                    v3.20.1      命令
# protoc-gen-go             v1.28.0      protoc插件，根据proto文件生成*pb.go文件，是填充、序列化和检索消息类型代码。
# protoc-gen-gogofaster     v1.28.0      protoc插件，替换了protoc-gen-go插件，以提高编码和解码速度，还支持自定义标签。
# protoc-gen-go-grpc        v1.2.0       protoc插件，根据proto文件生成*_grpc.pb.go文件，是客户端和服务端的方法和接口代码。
# protoc-gen-grpc-gateway   v2.10.0      protoc插件，根据proto文件生成*pb.gw.go文件，是web的api代码。
# protoc-gen-openapiv2      v2.10.0      protoc插件，根据proto文件生成*swagger.json文件，是swagger-ui接口文档。
# protoc-gen-validate       v0.6.7       protoc插件，根据proto文件生成*pb.validate.go文件，是校验字段代码

# 下载protoc
wget https://github.com/protocolbuffers/protobuf/releases/tag/v3.20.1

# 安装protoc-gen-go、protoc-gen-go-grpc、protoc-gen-validate插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2
go install github.com/envoyproxy/protoc-gen-validate@v0.6.7

# 安装protoc-gen-grpc-gateway、protoc-gen-openapiv2插件，下载地址
wget https://github.com/grpc-ecosystem/grpc-gateway/releases/download/v2.10.0/protoc-gen-grpc-gateway-v2.10.0-windows-x86_64.exe
wget https://github.com/grpc-ecosystem/grpc-gateway/releases/download/v2.10.0/protoc-gen-openapiv2-v2.10.0-windows-x86_64.exe

2.2 protoc命令使用

outPath="${serviceName}pb"  # 和proto文件的go_package名称一致，也就是文件夹名和包名一致  
mkdir -p ${outPath}  
  
# 生成pb.go和grpc.pb.go文件，
# pb.go文件是用于填充、序列化和检索消息类型的代码。
# _grpc.pb.go文件的客户端和服务器代码。
# 为了兼容旧版本protoc-gen-go生成代码，需要添加参数--go-grpc_opt=require_unimplemented_servers=false  
protoc --go_out=${outPath} --go_opt=paths=source_relative --go-grpc_out=${outPath} --go-grpc_opt=paths=source_relative *.proto  

# 生成pb.go和grpc.pb.go文件，使用protoc-gen-gogofaster插件，支持添加自定义tag，并且序列化和反序列化都比protoc-gen-go更快
protoc --gogofaster_out=${outPath} --gogofaster_opt=paths=source_relative --go-grpc_out=${outPath} --go-grpc_opt=paths=source_relative *.proto

# 生成*.pb.gw.go文件，web的api接口文件  
protoc --grpc-gateway_opt=paths=source_relative --grpc-gateway_out=${outPath} *.proto  

# 生成*.swagger.json文件  
protoc --openapiv2_opt=logtostderr=true --openapiv2_out=${outPath} *.proto

# 生成*.validate.go文件
protoc --validate_opt=paths=source_relative --validate_out=lang=go:${outPath} *.proto

旧版本protoc-gen-go生成代码命令：

protoc –go_out=plugins=grpc:. *.proto

3 protobuf简介

protobuf是一种与语言无关、平台无关、可扩展的可序列化和结构化的数据描述语言(其IDL)，常用于通信协议、数据存储等，比json、XML更小，编码解码速度快得多。

语法模板：

最简单protobuf模板：

syntax = "proto3";

package helloworld;

service Greeter {
    rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
    string name = 1;
}

message HelloReply {
    string message = 1;
}

包括grpc-gateway和swagger文档模板

syntax = "proto3";  
  
package proto;  
  
// 把google/api/annotations.proto和protoc-gen-openapiv2/options/annotations.proto文件存放在protoc的同级目录include下  
// protoc默认从同级目录include下查找  
import "google/api/annotations.proto";  
import "protoc-gen-openapiv2/options/annotations.proto";  
  
// 设置生成*go的包名  
option go_package = "./accountpb";  
  
  
// 生成*.swagger.json文件的一些默认设置  
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {  
  info: {  
    version: "2.0";  
  };  
  // 显示扩展文档  
  external_docs: {  
    url: "https://baidu.com";  
    description: "描述信息";  
  }  
  // 默认为HTTPS，根据实际需要设置  
  schemes: HTTP;  
};  
  
  
service Account {  
  rpc AddUser (User) returns (ID) {  
    // http设置  
    option (google.api.http) = {  
      post: "/v1/addUser"  
      body: "*"  
    };  
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {  
      summary: "添加用户",  
      description: "add one User",  
      tags: "addUser",  
    };  
  }  
  
  rpc GetUser (ID) returns (User) {  
    // http设置  
    option (google.api.http) = {  
      get: "/v1/getUser"  
    };  
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {  
      summary: "获取用户",  
      description: "get one user",  
      tags: "getUser",  
    };  
  }  
}  
  
message ID {  
  int64 id = 1;  
}  
  
message User {  
  int64 id = 1;  
  string name = 2;  
  string email = 3;  
}

注：service、rpc、message名称都是大写，而message里的字段是小写或下划线

protobuf与go语言常见数据类型映射表：

复合类型映射表：

(1) 数组类型

message HelloRequest {
    repeated string name = 1；  // 等价go的[]string
}

(2) 嵌套类型

message User {
    string name = 1；
}

message HelloRequest {
    repeated User users = 1；  // 等价go的[]User
}

(3) map

message HelloRequest {
    map<string, string> names = 2；  // 等价go的map[string]striing
}

4 grpc使用示例

4.1 一些调试grpc工具

(1) bloomrpc

bloomRPC旨在为探索和查询 GRPC 服务提供最简单、最高效的开发人员体验，通过界面调试。

github: https://github.com/bloomrpc/bloomrpc

启动rpc服务端，导入proto文件，填写ip和端口，点击中间绿色按钮调用，如下图所示：

(2) evans

Evans 是通过命令行容易调试 gRPC 客户端工具，命令中自带自动提示功能，使用非常方便

(3) grpcurl

grpcurl是一个命令行工具，可让您与gRPC服务器进行交互，基本上是curl针对gRPC服务器的。

4.2 protobuf序列化和反序列化

点击查看protobuf示例代码

4.3 四种调用方式

点击查看helloworld示例代码

4.4 日志打印

点击查看日志示例代码

4.5 元数据操作

在HTTP/1.1中，通常通过Header来传递数据，对于grpc(HTTP/2)来说，很少直接用Header传递数据，一般使用metadata来传递和操作数据，metadata是一个map结构(map[string][]string)，共有两种创建方式：

• 直接使用函数 metadata.New(map[string]string{})
• 直接调用函数 metadata.Pairs(key,value)，默认会把key转为小写，如果key相同，会追加到对应key的[]string上

在grpc中，为了防止metadata从入站rpc直接转发到出站rpc情况，因此metadata分为传入和传出两种：

• metadata.NewIncomingContext: 创建一个附加了传入metadata的新上下文，仅供自身的grpc使用。
• metadata.NewOutgoingContext: 创建一个附加了传出metadata的新上下文，仅供外部的grpc使用。

在grpc中，metadata是存储在context的，context中的数据是在请求的Header中的，因此通过Header可以看到metadata数据。

设置自定义metadata信息示例：

key = "authorization"

// 创建 metadata 和 context
md := metadata.Pairs(key, "Bearer eyJhb...ssw5c")
ctx := metadata.NewOutgoingContext(context.Background(), md)

读出自定义metadata信息示例：

key = "authorization"

// 使用metadata包读取key
md, ok := metadata.FromIncomingContext(ctx)
if !ok {
    return status.Errorf(codes.DataLoss, "failed to get metadata")
}
if authorization, ok := md[key]; ok {
    fmt.Printf("metadata: %s=%v\n", key, authorization)
} else {
    fmt.Printf("not found '%s' in metadata\n", key)
}


// 或使用封装好的包metautils读取key
authorization := metautils.ExtractIncoming(ctx).Get(key)
fmt.Println(color1)

点击查看元数据示例代码

4.6 拦截器

grpc拦截器(Interceptor)可以在每一个RPC方法的前面或后面做统一的特殊处理，并且不直接侵入业务代码， 例如鉴权校验、超时控制、日志记录、链路跟踪等。拦截器的类型分为两种：

• 一元拦截器(UnaryInterceptor)：拦截和处理一元RPC调用。
• 流拦截器(StreamInterceptor)：拦截和处理流式RPC调用。

由于客户端和服务端有各自的一元拦截器和流拦截器， 因此，在gRPC中， 也可以说共有四种类型的拦截器。

• 服务端一元拦截器(StreamServerInterceptor)
• 服务端流拦截器(StreamServerInterceptor)
• 客户端一元拦截器(UnaryClientInterceptor)
• 客户端流拦截器(StreamClientInterceptor)

因为grpc拦截器类型不能重复，当需要多个拦截器时，借助go-grpc-middleware库来实现，安装库

go get -u github.com/grpc-ecosystem/go-grpc-middleware

go-grpc-middleware 拦截器分类：

Auth

• grpc_auth 一个可定制的（通过AuthFunc）的认证中间件

Logging

• grpc_ctxtags - 一个为上下文添加标签图的库，数据由请求主体填充
• grpc_zap 将zap日志库整合到gRPC处理程序中。
• grpc_logrus 将logrus日志库整合到gRPC处理程序中。
• grpc_kit 将go-kit日志库整合到gRPC处理程序中。

Monitoring

grpc_prometheus ⚡ - ⚡ - OpenTracing grpc_opentracing -

• grpc_prometheus ⚡ 普罗米修斯客户端和服务器端监控中间件 otgrpc
• otgrpc ⚡ - OpenTracing 客户端和服务器端拦截器
• grpc_opentracing OpenTracing客户端和服务器端拦截器，支持流和处理程序返回的标记。

Client

• grpc_retry 一个通用的gRPC响应代码重试机制

Server grpc_validator - grpc_recovery - ratelimit - - grpc_validator 来自.proto选项的codegen入站消息验证 - grpc_recovery 将恐慌转化为gRPC错误 - ratelimit 由你自己的限制器限制grpc速率

点击查看拦截器示例代码

4.7 keepalive

点击查看keepalive示例代码

4.8 超时

点击查看超时示例代码

4.9 recovery

点击查看recovery示例代码

4.10 生成swagger接口文档

(1) 安装插件 protoc-gen-openapiv2

# windows环境
wget https://github.com/grpc-ecosystem/grpc-gateway/releases/download/v2.10.0/protoc-gen-openapiv2-v2.10.0-windows-x86_64.exe

# 下载完成后改名为protoc-gen-openapiv2.exe,并移动到$GOPATH/bin/目录下

(2) 下载swagger UI文件

# 下载swagger UI文件，然后解压
wget https://github.com/swagger-api/swagger-ui/archive/v3.37.0.zip

# 在$GOPATH/bin/include/目录下新建swagger目录，在$GOPATH/bin目录下有protoc文件
mkdir -p $GOPATH/bin/include/swagger

# 把swagger-ui里的dist目录下所有文件移动到$GOPATH/bin/include/swagger/

(3) 安装go-bindata和go-bindata-assetfs库

go-bindata工具主要为了将swagger-ui静态文件转为go代码，go-bindata-assetfs库是为了使外能够部访问swagger UI。

go get -u github.com/go-bindata/go-bindata/...
go get -u github.com/elazarl/go-bindata-assetfs/...

(4) 将swagger静态资源转为go代码

# 创建目录swagger-ui和swagger，其中swagger-ui存放dist目录下所有静态文件，swagger存放把静态文件转换后的go文件
mkdir -p pkg/swagger-ui pkg/swagger

# 转换为go
go-bindata --nocompress -pkg=swagger -o=pkg/swagger/data.go pkg/swagger-ui/...

把转换后的data.go文件复制到当前swagger目录下。

(5) 测试swagger UI服务

点击查看完整的swagger-ui示例代码

启动服务，在浏览器访问 http://127.0.0.1:8080/swagger-ui/ ，把 http://127.0.0.1:8080/swagger/hello.swagger.json 复制到swagger界面执行，就可以执行接口测试了。

注：hello.swagger.json中的schemes字段值为空，在swagger测试时默认使用https，导致本来http接口无法访问，所以需要在生成的*.swagger.json文档中手动加入schemes字段，这样可以选择https或http来测试接口。

  "schemes":[
    "https",
    "http"
  ],

4.11 validate

点击查看validate示例代码

4.12 tag

点击查看tag示例代码

4.13 TLS

点击查看TLS示例代码

4.14 JWT

点击查看JWT示例代码

4.15 restful api 调用 grpc

gRPC-Gateway 是 Google 协议缓冲区编译器 protoc 的 插件。它读取 protobuf 服务定义并生成一个反向代理服务器，该服务器将 RESTful HTTP API 转换为 gRPC。该服务器是根据 google.api.http 您的服务定义中的注释生成的。

点击查看grpc-gateway示例代码

4.16 重试

点击查看重试示例代码

4.17 限流

点击查看限流示例代码

4.18 注册与发现

在分布式系统中，为了实现高可用，通常同一个服务会部署多个，为了使访问流量要均衡分散到多个服务上。

客户端要访问服务端，需要知道服务端ip地址和端口，如果服务数量比较少，并且服务不会频繁更改ip和端口，人还可以处理，如果服务数量多了，通过人工力量处理就非常麻烦了，需要动态获取服务端地址，也就是服务注册与发现，常见角色：

• 注册中心：承担对服务信息进行注册、协调、管理等工作。
• 服务提供者(服务端): 暴露特定端口，并提供一个到多个的服务来允许外部访问。
• 服务消费者(客户端): 调用服务方。

服务注册与发现原理：”服务提供者”在启动服务时会将自己的服务信息(ip地址、端口号、版本号等)注册到”注册中心”。”服务消费者”在进行调用时，会以约定命名标识(如服务名)到”注册中心”查询，发现当前哪些具体的服务可以调用。”注册中心”再根据约定的负载均衡算法进行调度，最终请求到服务提供者。

另外，当”服务提供者”出现问题时，或是当定期的”心跳检测”发现”服务提供者”无正确响应时，那么这个出现问题的服务就会被下线，并标识为不可用。即在启动时上报”注册中心”进行注册，把被检测到出问题的服务下线，以此来维护服务注册和发现。

点击查看etcd服务注册与发现示例代码

4.19 负载均衡

常见的负载均衡有客户端负载均衡和服务端负载均衡。

(1) 客户端负载均衡

客户端负载是指在调用时，由客户端到”注册中心”对服务提供者进行查询，并获取所需的服务清单。服务清单中包含各个服务的实际信息(如ip地址、端口号、集群命名空间等)。由客户端使用特定的负载均衡策略(如轮询)在服务清单中选择一个或多个服务进行调用。

• 优点: 高性能、去中心化，并且不需要借助独立的外部负载均衡组件。
• 缺点: 实现成本较高， 要对不同语言的客户端实现各自对应的SDK及其负载均衡策略。

(2) 服务端负载均衡

服务端负载，又被称为”代理”模式，在服务端侧搭设独立的负载均衡器，负载均衡器再根据给定的目标名称(如服务名)找到适合调用的服务实例，因此它具备负载均衡和反向代理两项功能。

• 优点: 简单、透明，客户端不需要知道背后的逻辑，只需按给定的目标名称调用、访问即可，由服务端侧管理负载、均衡策略及代理
• 缺点: 外部的负载均衡器理论上可能成为性能瓶颈，会受到负载均衡器的吞吐率影响，并且与客户端负载相比，有可能出现更高的网络延迟。同时，必须要保持高可用，因为它是整个系统的 关键节点，一旦出现问题，影响非常大。

(3) grpc官方设计思路

• 客户端根据服务名称发起请求。
• 名称解析器解析服务名称并返回，服务名称解析成一个或多个ip地址，每个ip都会有标识，标识分为服务端地址、负载均衡地址、客户端使用的负载均衡策略。
• 客户端根据服务端类型选择相应的策略，如果grpc客户端获取的地址是负载均衡器地址，那么客户端将使用grpclb策略，否则使用服务配置请求的负载均衡策略；如果服务配置未请求负载均衡策略，则客户端默认选择第一个可用的服务端地址。
• 最后根据不同的策略进行实际调用。

grpc默认支持两种负载均衡算法pick_first 和 round_robin。

点击查看负载均衡示例代码

点击查看结合etcd做负载均衡示例代码

4.20 链路跟踪

在微服务复制的分布式场景下，注入链路追踪是非常重要和必要的。做链路追踪的基本条件是注入追踪信息，而最简单的方法就是使用服务端和客户端拦截器组成完整的链路信息，具体如下：

• 服务端拦截器：从metadata中提取链路信息， 将其设置并追加到服务端的调用上下文中。也就是说，如果发现本次调用并没有上一级的链路信息，那么它将会生成对应的父级信息，自己成为父级；如果发现本次调用存在既有的上一级链路信息，那么它将会根据上一级链路信息进行设置，成为其子级。
• 客户端拦截器：从调用的上下文中提取链路信息， 并将其作为metadata追加到rpc调用中。

借助OpenTracing API和Jaeger Client两个go库实现与追踪系统对接。

点击查看gin调用rpc的链路跟踪示例代码

点击查看rpc调用rpc的链路跟踪示例代码

4.21 熔断

点击查看熔断示例代码

4.22 prometheus监控

固定标签

所有服务器端指标都以grpc_server名称开头。所有客户端指标都以grpc_client. 他们都有镜像概念，所有方法都包含相同的丰富标签：

• grpc_service- gRPC 服务名称，它是 protobufpackage和grpc_service部分名称的组合。例如 package = mwitkow.testproto和 service TestService组合的标签是grpc_service="mwitkow.testproto.TestService"

• grpc_method- 在 gRPC 服务上调用的方法的名称。例如 grpc_method="Ping"

• grpc_type- gRPC类型的请求。区分两者非常重要，尤其是对于延迟测量。

  • unary是单请求单响应 RPC
  • client_stream是一个多请求、单响应的 RPC
  • server_stream是一个单请求、多响应的 RPC
  • bidi_stream是一个多请求、多响应的 RPC

此外，对于已完成的 RPC，使用以下标签：

• grpc_code- 人类可读的gRPC 状态码。所有状态的列表都很长，但这里有一些常见的：

  • OK- 表示 RPC 成功
  • IllegalArgument- RPC 包含错误值
  • Internal- 未向客户端披露服务器端错误

点击查看默认指标监控示例代码

点击查看自定义指标监控示例代码

把client和server配置到prometheus之后，就可以在prometheus进行一些有用的查询了。

# 1分钟请求率 qps
sum(rate(grpc_server_started_total{job="hello_grpc_server"}[1m])) by (grpc_service)

# 一元请求错误率
sum(rate(grpc_server_handled_total{job="hello_grpc_server",grpc_type="unary",grpc_code!="OK"}[1m])) by (grpc_service)

# 一元请求错误百分比
sum(rate(grpc_server_handled_total{job="hello_grpc_server",grpc_type="unary",grpc_code!="OK"}[1m])) by (grpc_service) / sum(rate(grpc_server_started_total{job="hello_grpc_server",grpc_type="unary"}[1m])) by (grpc_service) * 100.0

# 平均响应流大小
sum(rate(grpc_server_msg_sent_total{job="hello_grpc_server",grpc_type="server_stream"}[10m])) by (grpc_service) / sum(rate(grpc_server_started_total{job="hello_grpc_server",grpc_type="server_stream"}[10m])) by (grpc_service)

# 一元请求的 99% 延迟
histogram_quantile(0.99, sum(rate(grpc_server_handling_seconds_bucket{job="hello_grpc_server",grpc_type="unary"}[5m])) by (grpc_service,le))

# 慢速一元查询的百分比 (>250ms)
100.0 - (sum(rate(grpc_server_handling_seconds_bucket{job="hello_grpc_server",grpc_type="unary",le="0.25"}[5m])) by (grpc_service) / sum(rate(grpc_server_handling_seconds_count{job="hello_grpc_server",grpc_type="unary"}[5m])) by (grpc_service)) * 100.0

4.23 grpc错误处理

grpc返回字段有Code和Message两部分，官方定义的状态码如下：

在grpc的状态信息中一共包含三个属性，分别是错误码(code)、错误消息(message)、错误信息详情(Details)，从any.proto文件引入detail字段，作为应用程序的错误码原型，重新封装grpc错误码和业务错误码。点击查看重新封装grpc错误码。

外部客户端可以直接调用 errcode.ToGRPCERROR(errcode.ERROR_LOGIN_DAIL)返回错误信息，而内部客户端获取错误详情代码如下：

    err := errcode.ToGRPCERROR(errcode.ERROR_LOGIN_DAIL)
    details := errcode.FromError(err).Details()

5 注意事项

5.1 使用grpc-gateway注意事项

(1) 生成swagger.json，默认使用HTTPS，但是rpc和web并没有设置TLS传输，请求会出错。

使用swagger-ui测试接口，返回错误 “ TypeError: Failed to fetch”，原因是使用https调用接口，而服务端web并没有开启https，调用会出错。

解决办法：

设置swagger.json，把HTTPS改为HTTP
"schemes": [  
  "http"  
]

或者修改proto文件，然后重新生成swagger.json
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {  
  // 默认为HTTPS，根据实际需要设置  
  schemes: HTTP;
}

(2) grpc-gateway的web服务注册路由pb.Register***HandlerFromEndpoint(ctx, gwMux, grpcAddr, options)的option和grpc服务grpc.NewServer(options...)的option设置要一致，要么同时使用TLS传输，要么同时取消TLS传输，否则报错类似http: TLS handshake error from 127.0.0.1:14323: remote error: tls: unknown certificate

如果grpc使用了TLS传输，web服务建议也使用，web服务使用TLS监听服务，：http.ListenAndServeTLS(webAddr, certfile.Path("server.crt"), certfile.Path("server.key"), mux)，此时swagger-ui都是使用https访问。

5.2 注意ctx混淆使用

(1) rpc的client端设置ctx，ctx的value通过header传递，server端接收到header，转为ctx。

// client端
md := metadata.Pairs(
  "uid","100",
  "authorization", token,
)  
ctx := metadata.NewOutgoingContext(context.Background(), md)


// 服务端读取可以使用grpc的metadata包读取，也可以用第三方封装方法读取github.com/grpc-ecosystem/go-grpc-middleware/util/metautils
metautils.ExtractIncoming(ctx).Get("uid")
metautils.ExtractIncoming(ctx).Get("authorization")

(2) ctx只在同一个服务内传递，新添加的kv和读取使用context的方法

// ctx设置value
newCtx := context.WithValue(ctx, "tokenInfo", cc) // 后面方法可以通过ctx.Value("tokenInfo").(*jwt.CustomClaims)

// ctx读取key
tokenInfo, ok := ctx.Value("tokenInfo").(*auth.Token) // 从拦截器设置值读取

5.3 注意etcd版本问题

etcd v3.5.0之后版本解决了grpc版本不兼容问题，etcd v3.5.0之后版本会优先使用代理地址代替etcd服务地址，使用时注意关闭代理。

本文链接：https://zhuyasen.com/post/grpc.html，参与评论 »

1 viper概述

viper是Go应用程序的完整配置解决方案。在构建现代化应用程序的过程中，开发人员可以通过使用viper而不必考虑配置文件的格式问题，可以被认为是所有应用程序配置需求的注册表。它支持功能：

• 设置默认值
• 从JSON，TOML，YAML，HCL和Java属性配置文件中读取
• 实时观看和重新读取配置文件(可选)
• 从环境变量中读取
• 从远程配置系统(etcd或Consul)读取，并观察变化
• 从命令行标志读取
• 从缓冲区读取
• 设置显式值

viper提供的配置方式的优先级顺序如下(由高到低)：

• (1) 设置显示调用(explicit call to Set)
• (2) 命令行标志(flag)
• (3) 环境变量(env)
• (4) 配置文件(config)
• (5) 远程键/值存储(key/value store)
• (6) 默认值(default)

viper支持在运行时让应用程序实时读取配置文件，使应用程序一直使用最新修改的配置文件，从而不需要再重启服务。

2 解析常用配置文件示例

示例展示读取yaml、toml、json配置到对象，并且实时监听更新配置文件变化。

文件目录如下：

.
├── conf.go
├── conf_test.go
├── conf.json
├── conf.toml
└── conf.yaml

yaml格式配置文件conf.yaml内容如下：

# 服务名称
serverName: "my server"
# 监听地址
serverPort: 8080
# 运行模式，dev:开发环境，prod:正式环境
runMode: "dev"

# 是否开启性能分析功能，true:开启，false:关闭
isEnableProfile: true

# 输出日志级别 debug, info, warn, error
logLevel: "debug"

# Etcd集群地址
etcdEndpoints:
  - "127.0.0.1:23791"
  - "127.0.0.1:23792"
  - "127.0.0.1:23793"

# mysql配置
mysqlURL: "root:123456@(127.0.0.1:3306)/user?charset=utf8&parseTime=true"

# mongodb配置
mongoURL: "mongodb://test:123456@127.0.0.1:27017/test"

# redis配置
redis:
  addr: "127.0.0.1:6379"
  password: "123456"
  db: 0

# 字典
servers:
  Beijing:
    addr: "127.0.0.1"
    port: "20060"
  Shanghai:
    addr: "127.0.0.1"
    port: "20061"

toml格式配置文件conf.toml内容如下：

# 服务名称
serverName = "my server"
# 监听地址
serverPort = 8080
# 运行模式，dev:开发环境，prod:正式环境
runMode = "dev"

# 是否开启性能分析功能，true:开启，false:关闭
isEnableProfile = true

# 输出日志级别 debug, info, warn, error
logLevel = "debug"

# Etcd集群地址
etcdEndpoints = ["127.0.0.1:23791", "127.0.0.1:23792", "127.0.0.1:23793"]

# mysql配置
mysqlURL = "root:123456@(127.0.0.1:3306)/user?charset=utf8&parseTime=true"

# mongodb配置
mongoURL = "mongodb://test:123456@127.0.0.1:27017/test"

# redis配置
[redis]
    addr = "127.0.0.1:6379"
    password = "123456"
    db = 0

# 字典
[servers]
    [servers.Beijing]
        addr = "127.0.0.1"
        port = "20060"
    [servers.Shanghai]
        addr = "127.0.0.1"
        port = "20061"

json格式配置文件conf.json内容如下：

{
    "serverName":"my server",
    "serverPort":8080,
    "runMode":"dev",
    "isEnableProfile":true,
    "logLevel":"debug",
    "etcdEndpoints":[
        "127.0.0.1:23791",
        "127.0.0.1:23792",
        "127.0.0.1:23793"
    ],
    "mysqlURL":"root:123456@(127.0.0.1:3306)/user?charset=utf8&parseTime=true",
    "mongoURL":"mongodb://test:123456@127.0.0.1:27017/test",
    "redis":{
        "addr":"127.0.0.1:6379",
        "password":"123456",
        "db":0
    },
    "servers":{
        "Beijing":{
            "addr":"127.0.0.1",
            "port":"20060"
        },
        "Shanghai":{
            "addr":"127.0.0.1",
            "port":"20061"
        }
    }
}

解析配置文件conf.go内容如下：

package config

import (
    "path"
    "strings"

    "github.com/spf13/viper"
)

var conf = new(Conf)

// Conf 服务配置信息
type Conf struct {
    // 服务名称
    ServerName string `json:"serverName" toml:"serverName"`
    // 服务端口
    ServerPort int `json:"serverPort" toml:"serverPort"`
    // 运行模式
    RunMode string `json:"runMode" toml:"runMode"`

    // 是否开启go profile
    IsEnableProfile bool `json:"isEnableProfile" toml:"isEnableProfile"`

    // 输出日志级别
    LogLevel string `json:"logLevel" toml:"logLevel"`

    // Etcd集群地址
    EtcdEndpoints []string `json:"etcdEndpoints" toml:"etcdEndpoints"`

    // mysql配置
    MysqlURL string `json:"mysqlURL" toml:"mysqlURL"`

    // mongodb配置
    MongoURL string `json:"mongoURL" toml:"mongoURL"`

    // redis配置
    Redis *RedisConf `json:"redis" toml:"redis"`

    // log配置
    Servers map[string]*Servers `json:"servers" toml:"servers"`
}

// RedisConf Redis配置信息
type RedisConf struct {
    Addr     string `json:"addr" toml:"addr"`
    Password string `json:"password" toml:"password"`
    DB       int    `json:"db" toml:"db"`
}

// Servers 服务地址
type Servers struct {
    Addr string `json:"addr" toml:"addr"`
    Port string `json:"port" toml:"port"`
}

// Get 获取配置对象
func Get() *Conf {
    return conf
}

// ParseConfig 解析配置文件到对象，包括yaml、toml、json等文件
func ParseConfig(filePath string, fileName string) error {
    viper.AddConfigPath(filePath)                                  // 路径
    viper.SetConfigName(fileName)                                  // 名称
    viper.SetConfigType(strings.TrimLeft(path.Ext(fileName), ".")) // 从文件名中获取配置类型

    err := viper.ReadInConfig()
    if err != nil {
        return err
    }

    err = viper.Unmarshal(conf)
    if err != nil {
        return err
    }

    // 监听配置文件更新
    viper.WatchConfig()
    viper.OnConfigChange(func(e fsnotify.Event) {
        viper.Unmarshal(conf)
    })

    return nil
}

conf_test.go文件内容如下：

package config

import (
    "testing"

    "github.com/k0kubun/pp"
)

func TestParseYAML(t *testing.T) {
    err := ParseConfig("./", "conf.yaml") // 解析yaml文件
    if err != nil {
        t.Error(err)
        return
    }

    pp.Println(Get())
}

func TestParseTOML(t *testing.T) {
    err := ParseConfig("./", "conf.toml") // 解析toml文件
    if err != nil {
        t.Error(err)
        return
    }

    pp.Println(Get())
}

func TestParseJSON(t *testing.T) {
    err := ParseConfig("./", "conf.json") // 解析json文件
    if err != nil {
        t.Error(err)
        return
    }

    pp.Println(Get())
}

// 测试更新配置文件
func TestWatch(t *testing.T) {
    err := ParseConfig("./", "conf.yaml")
    if err != nil {
        t.Error(err)
        return
    }

    for i := 0; i < 30; i++ {
        fmt.Println("port:", Get().ServerPort)
        time.Sleep(time.Second)
    }
}

经过测试，yaml、toml、json这三个文件解析结果都是一致的。

参考：https://blog.csdn.net/cs380637384/article/details/81217767

本文链接：https://zhuyasen.com/post/viper.html，参与评论 »

1.1 TLS/SSL基本概念

SSL(Secure Socket Layer 安全套接层)是基于HTTPS下的一个协议加密层，起初是因为HTTP在传输数据时使用的是明文，是不安全的，为了解决这一隐患网景公司(Netscape)推出了SSL安全套接字协议层，SSL是基于HTTP标准并对TCP传输数据时进行加密，在HTTP和TCP之间，所以HPPTS是HTTP+SSL/TCP的简称。

TLS(Transport Layer Security)是传输层安全性协议，是IETF把SSL经过标准化的传输协议，可以看作是SSL的升级版，目的是保障互联网通信提供安全性和数据完整性。事实上我们现在用的都是TLS，但因为历史上习惯了SSL这个称呼。

目前应用最广泛的是TLS 1.0，但是主流浏览器都已经实现了TLS 1.2的支持。TLS 1.0通常被标示为SSL 3.1，TLS 1.1为SSL 3.2，TLS 1.2为SSL 3.3。

SSL/TLS有单向认证和双向认证两种方式：

• 单向认证指的是只有一个对象校验对端的证书合法性，通常都是client来校验服务器的合法性，那么client需要一个ca.crt，服务器需要server.crt、server.key。
• 双向认证指的是相互校验，服务器需要校验每个client，client也需要校验服务器。server需要server.key 、server.crt 、ca.crt文件；client也需要client.key 、client.crt 、ca.crt文件。

1.2 TLS/SSL握手通信机制

TLS/SSL协议的基本过程：

• 客户端向服务器端索要并验证公钥。
• 双方协商生成”对话密钥”。
• 双方采用”对话密钥”进行加密通信。

客户端和服务器端在正式通信之前经过握手阶段，”握手阶段”涉及四次通信，如下图所示：

“握手阶段”的所有通信都是明文的，握手完成之后是通信内容是经过秘钥加密的，握手过程说明如下：

(1) 客户端发出请求(ClientHello)

首先，客户端(通常是浏览器)先向服务器发出加密通信的请求，这被叫做ClientHello请求，在这一步客户端主要向服务器提供以下信息。

• 支持的协议版本，比如TLS 1.0版。
• 一个客户端生成的随机数，稍后用于生成”对话密钥”。
• 支持的加密方法，比如RSA公钥加密。
• 支持的压缩方法。

这里需要注意的是，客户端发送的信息之中不包括服务器的域名。也就是说，理论上服务器只能包含一个网站，否则会分不清应该向客户端提供哪一个网站的数字证书。这就是为什么通常一台服务器只能有一张数字证书的原因。对于虚拟主机的用户来说，这当然很不方便。2006年，TLS协议加入了一个Server Name Indication扩展，允许客户端向服务器提供它所请求的域名。

(2) 服务器回应(SeverHello)

服务器收到客户端请求后，向客户端发出回应，这叫做SeverHello，服务器的回应包含以下内容：

• 确认使用的加密通信协议版本，比如TLS 1.0版本。如果浏览器与服务器支持的版本不一致，服务器关闭加密通信。
• 一个服务器生成的随机数，稍后用于生成”对话密钥”。
• 确认使用的加密方法，比如RSA公钥加密。
• 服务器证书。

除了上面这些信息，如果服务器需要确认客户端的身份，就会再包含一项请求，要求客户端提供”客户端证书”。比如，金融机构往往只允许认证客户连入自己的网络，就会向正式客户提供USB密钥，里面就包含了一张客户端证书。

(3) 客户端回应

客户端收到服务器回应以后，首先验证服务器证书。如果证书不是可信机构颁布、或者证书中的域名与实际域名不一致、或者证书已经过期，就会向访问者显示一个警告，由其选择是否还要继续通信。如果证书没有问题，客户端就会从证书中取出服务器的公钥。然后，向服务器发送下面三项信息：

• 一个随机数。该随机数用服务器公钥加密，防止被窃听。
• 编码改变通知，表示随后的信息都将用双方商定的加密方法和密钥发送。
• 客户端握手结束通知，表示客户端的握手阶段已经结束。这一项同时也是前面发送的所有内容的hash值，用来供服务器校验。

上面第一项的随机数，是整个握手阶段出现的第三个随机数，又称”pre-master key”。有了它以后，客户端和服务器就同时有了三个随机数，接着双方就用事先商定的加密方法，各自生成本次会话所用的同一把”会话密钥”。

注：如果前一步服务器要求客户端证书，客户端会在这一步发送证书及相关信息。

(4) 服务器的最后回应

服务器收到客户端的第三个随机数pre-master key之后，计算生成本次会话所用的”会话密钥”，向客户端最后发送下面信息：

• 编码改变通知，表示随后的信息都将用双方商定的加密方法和密钥发送。
• 服务器握手结束通知，表示服务器的握手阶段已经结束。这一项同时也是前面发送的所有内容的hash值，用来供客户端校验。

整个握手阶段全部结束，接下来客户端与服务器进入加密通信，就完全是使用普通的HTTP协议，只不过用”会话密钥”加密内容。

1.3 HTTPS

HTTPS(Hypertext Transfer Protocol over Secure Socket Layer)，是以安全为目标的HTTP通道，简单讲是HTTP的安全版，即HTTP和TCP之间加入TLS/SSL安全通信协议。

HTTPS和HTTP的区别：

• https协议需要到CA申请证书。
• http是超文本传输协议，信息是明文传输；https 则是具有安全性的ssl加密传输协议。
• http和https使用的是完全不同的连接方式，用的端口也不一样，前者是80，后者是443。
• http的连接很简单，是无状态的；HTTPS协议是由TLS/SSL+HTTP协议构建的可进行加密传输、身份认证的网络协议，比http协议安全。

2 加密解密常用术语

对于一份数据，通过一种算法，基于传入的密钥(一串由数字或字符组成的字符串，也称”key”)，将明文数据转换成了不可阅读的密文，这是”加密”，同样的，密文到达目的地后，需要再以相应的算法，配合一个密钥，将密文再解密成明文，这就是”解密”。

2.1 对称加密

如果加密和解密使用的是同一个密钥，那么这就是”对称密钥加解密”，最常见的对称加密算法是DES。

2.2 非对称加解密

如果加密和解密使用的是两个不同的密钥，那么这就是”非对称密钥加解密”，最常用的非对称加密算法是RSA。这两个不同的密钥一个叫作公开密钥(publickey)另一个叫私有密钥(privatekey)，公开密钥对外公开，而私有密钥则由自己保存，其实公钥和私钥并没有什么不同之处，公钥之所以成为公钥是因为它会被公开出来，产生任意份拷贝，供任何人获取，而只有服务主机持有唯一的一份私钥，这种分发模式实际上是Web站点多客户端(浏览器)与单一服务器的网络拓扑所决定的，多客户端意味着密钥能被复制和公开获取，单一服务器意味着密钥被严格控制，只能由本服务器持有，这实际上也是后面要提到的之所以能通过数据证书确定信任主机的重要原因之一。如果我们跳出web站点的拓扑环境，其实就没有什么公钥与私钥之分了，比如那些使用以密钥为身份认证的SSH主机，往往是为每一个用户单独生成一个私钥分发给他们自己保存，SSH主机会保存一份公钥，公钥私钥各有一份，都不会公开传播。

注：用公钥加密的数据，只能用私钥解密，公钥是无法解密的，同样用私钥加密的数据也只能用公钥来解密。

2.3 数字摘要

在下载文件的时候经常会看到有的下载站点也提供下载文件的”数字摘要”，供下载者验证下载后的文件是否完整，或者说是否和服务器上的文件”一模一样”。其实，数字摘要就是采用单项Hash函数将需要加密的明文”摘要”成一串固定长度(128位)的密文，这一串密文又称为数字指纹，它有固定的长度，而且不同的明文摘要成密文，其结果总是不同的，同样的明文其摘要必定一致。 因此，”数字摘要”叫”数字指纹”可能会更贴切一些。”数字摘要”是https能确保数据完整性和防篡改的根本原因。

2.4 数字签名

数字签名是水到渠成的技术，有了”非对称密钥加解密”和”数字摘要”两项技术之后，我们能做些什么呢？假如发送方想把一份报文发送给接收方，在发送报文前，发送方用一个哈希函数从报文文本中生成报文摘要，然后用自己的私人密钥对这个摘要进行加密，这个加密后的摘要将作为报文的”签名”和报文一起发送给接收方，接收方首先用与发送方一样的哈希函数从接收到的原始报文中计算出报文摘要，接着再用发送方的公用密钥来对报文附加的数字签名进行解密，如果这两个摘要相同、那么接收方就能确认报文是从发送方发送且没有被遗漏和修改过，这就是结合”非对称密钥加解密”和”数字摘要”技术所能做的事情，这也就是人们所说的”数字签名”技术。在这个过程中，对传送数据生成摘要并使用私钥进行加密的过程就是生成”数字签名”的过程，经过加密的数字摘要，就是人们所说的”数字签名”。

数字签名技术就是对”非对称密钥加解密”和”数字摘要”两项技术的应用，它将摘要信息用发送者的私钥加密，与原文一起传送给接收者。接收者只有用发送者的公钥才能解密被加密的摘要信息，然后用HASH函数对收到的原文产生一个摘要信息，与解密的摘要信息对比。如果相同，则说明收到的信息是完整的，在传输过程中没有被修改，否则说明信息被修改过，因此数字签名能够验证信息的完整性。数字签名只能验证数据的完整性，数据本身是否加密不属于数字签名的控制范围。

综上所述，数字签名有两种功效：一是能确定消息确实是由发送方签名并发出来的，因为别人假冒不了发送方的签名。二是数字签名能确定消息的完整性。

2.5 数字证书

数字证书是值得信赖的公钥，只从”准确认证发送方身份”和”确保数据完整性”两个安全方面来看，数字签名似乎已经完全做到了，还有漏洞握手过程中，用户收到的公钥是否真实可靠。传输过程会出现第三方劫持替换公钥，并串改信息可能。为了解决公钥是真实可靠问题，需要有一个权威的值得信赖的第三方机构(一般是由政府审核并授权的机构)来统一对外发放公钥，只有公钥在权威机构通过认证的，说明证书是真实可靠的。这种机构被称为证书权威机构(Certificate Authority，简称CA)，它们所发放的包含主机机构名称、公钥在内的文件就是人们所说的”数字证书”，数字证书包含内容：

• 证书颁发机构的名称
• 证书本身的数字签名
• 证书持有者公钥
• 证书签名用到的Hash算法

数字证书的颁发过程：用户首先产生自己的密钥对，并将公共密钥及部分个人身份信息传送给认证中心。认证中心在核实身份后，将执行一些必要的步骤，以确信请求确实由用户发送而来，然后，认证中心将发给用户一个数字证书，该证书内包含用户的个人信息和公钥信息，同时还附有认证中心的签名信息，用户拿到证书之后就可以进行相关的安全通信。数字证书各不相同，每种证书可提供不同级别的可信度。可以从证书发行机构获得您自己的数字证书。

浏览器默认都会内置CA根证书，其中根证书包含了CA的公钥，验证证书的有效性：

• 如果证书颁发的机构是伪造的，浏览器不认识，直接认为是危险证书。
• 如果证书颁发的机构是确实存在，浏览器会根据CA名，找到对应内置的CA根证书、CA的公钥。用CA的公钥，对伪造的证书的摘要进行解密，发现解不了，认为是危险证书。
• 对于篡改的证书验证，使用CA的公钥对数字签名进行解密得到摘要A，然后再根据签名的Hash算法计算出证书的摘要B，对比A与B，若相等则正常，若不相等则是被篡改过的。
• 证书可在其过期前被吊销，通常情况是该证书的私钥已经失密。较新的浏览器如Chrome、Firefox、Opera和Internet Explorer都实现了在线证书状态协议(OCSP)以排除这种情形：浏览器将网站提供的证书的序列号通过OCSP发送给证书颁发机构，后者会告诉浏览器证书是否还是有效的。

3 使用cfssl生成自签名证书

cfssl是用于生成颁发TLS/SSL证书的开源工具，cfssl不仅是分发证书的工具，也是证书颁发机构(CA)，对于使用HTTPS建立网站的任何人(从网站所有者到大型软件即服务公司)都是有用的。

3.1 安装

根据系统环境，从github(https://github.com/cloudflare/cfssl/releases)下载对应版本，然后把可执行文件添加到环境变量中。

3.2 生成自签名证书

(1) 生成根CA证书和私钥

创建根CA证书和私钥的CSR(证书签名请求文件)配置文件ca-csr.json，内容如下：

{
    "CN": "myPlatform",
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C": "China",
            "ST": "Beijing",
            "L": "Beijing",
            "O": "OName",
            "OU": "OUName"
        }
    ]
}

配置文件字段说明：

• CN：机构名称Comman Name，浏览器使用该字段验证网站是否合法
• C: Country， 国家
• ST: State，州，省
• L: Locality，地区，城市
• O: Organization Name，组织名称，公司名称
• OU: Organization Unit Name，公司部门

初始化CA，会生成3个文件，分别是ca.pem(ca证书文件)、ca-key.pem(ca私钥文件)、ca.csr(证书签名请求文件)，这些文件用于交叉签名或重新签

cfssl gencert -initca config/ca-csr.json | cfssljson -bare ca -

(2) 颁发本地证书和私钥

创建证书签名请求配置文件req-csr.json，内容如下：

{
    "CN": "myDomain",
    "hosts": [
        "localhost",
        "127.0.0.1",
        "domain_or_ip"
    ],
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C": "China",
            "ST": "GuangDong",
            "L": "GuangZhou",
            "O": "myOName",
            "OU": "myOUName"
        }
    ]
}

配置文件字段说明：

• hosts: 证书派发给哪些主机地址，ip或域名
• CN：机构名称Comman Name，也可以是域名
• C: Country， 国家
• ST: State，州，省
• L: Locality，地区，城市
• O: Organization Name，组织名称，公司名称
• OU: Organization Unit Name，公司部门

生成证书策略配置文件ca-config.json，让CA软件知道颁发什么样的证书，内容如下：

{
    "signing":{
        "default":{
            "expiry":"43800h"
        },
        "profiles":{
            "server":{
                "expiry":"43800h",
                "usages":[
                    "signing",
                    "key encipherment",
                    "server auth"
                ]
            },
            "client":{
                "expiry":"43800h",
                "usages":[
                    "signing",
                ]
            },
            "peer":{
                "expiry":"43800h",
                "usages":[
                    "signing",
                    "key encipherment",
                    "server auth",
                    "client auth"
                ]
            }
        }
    }
}

配置说明：

• 有一个默认的配置default，或者根据需求设置profile下多种策略
• signing: 表示证书可用于签名其它证书，生成的ca.pem证书中CA=TRUE
• key encipherment: 表示证书可用于加密
• server auth: 表示client可以用该CA对server提供的证书进行验证
• client auth: 表示server可以用该CA对client提供的证书进行验证

根据需求颁发不同类型的证书

# 颁发服务端使用的证书，例如网站服务器
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=config/ca-config.json -profile=server config/req-csr.json | cfssljson -bare server

# 颁发双方都要身份验证的证书，例如etcd集群
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=config/ca-config.json -profile=peer config/req-csr.json | cfssljson -bare peer

# 颁发客户端证书
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=config/ca-config.json -profile=client config/req-csr.json | cfssljson -bare client

注：-profile参数值必须是配置ca-config.json的profiles下对应字段，如果配置文件里没有www字段，颁发证书时使用-profile=www，会报错{“code”:5100,“message”:“Invalid policy: no key usage available”}

查看证书信息

# 查看cert(证书信息):
cfssl certinfo -cert myCertName.pem | jq
# 查看csr(证书签名请求)信息：
cfssl certinfo -csr myCertName.csr

# 也可以使用openssl命令查看证书和私钥信息
openssl x509 -text -noout  -in myCertName.pem
openssl rsa -text -noout -in ca-key.pem
#openssl req -text -noout -in ca.csr

# 验证派发的证书是否可用
openssl verify -CAfile ca.pem myCertName.pem

4 不同格式证书之间转换

一般证书有三种格式：

• PEM(.pem) 前面命令生成的都是这种格式
• DER(.cer .der) Windows 上常见
• PKCS#12文件(.pfx .p12) Mac上常见

# PEM转换为CRT
openssl x509 -outform der -in ca.pem -out ca.crt

# PEM转换为DER
openssl x509 -outform der -in ca.pem -out ca.der

# DER转换为PEM
openssl x509 -inform der -in myserver.cer -out myserver.pem

# PEM转换为PKCS
openssl pkcs12 -export -out myserver.pfx -inkey myserver.key -in myserver.crt -certfile ca.crt

# PKCS转换为PEM
openssl pkcs12 -in myserver.pfx -out myserver2.pem -nodes

5 生成TLS/SSL证书在nginx使用示例

此示例在linux环境下运行，把新生成的证书文件路径设置到nginx配置文件，使用docker启动nginx来测试。

5.1 创建生成证书的脚本文件

脚本文件gen-server-cert.sh内容如下：

#!/bin/bash


# -------------------------------- 参数判断 --------------------------------------------
params=$@

if [ $# -lt 1 ]; then
    echo "param is empty"
    echo "usage:"
    echo "  \"$0 zhuyasen.com\" or \"$0 192.168.3.100\""
    exit
fi

# 用参数替换req-csr.json固定字段值domains_or_ips
hostFields=''
for val in $params; do
    hostFields=${hostFields}\\\"$val\\\",
done
# 去掉最后一个逗号
hostFields=${hostFields%?}


# ---------------------------------- 创建认证中心(CA) ----------------------------------

# 创建存储证书目录和配置目录
mkdir -p certs
cd certs
mkdir -p config

# 创建根CA证书和私钥的CSR(证书签名请求文件)配置文件ca-csr.json
cat > config/ca-csr.json <<EOF
{
    "CN": "myMechanism",
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C": "CN",
            "ST": "Beijing",
            "L": "Beijing",
            "O": "my organization",
            "OU": "my organization unit name"
        }
    ]
}
EOF

# 生成CA证书和私钥，先判断ca-key.pem是否存在，如果存在则使用已存在的
if [[ ! -f "ca-key.pem" ]]; then
  echo "generate new ca.pem and ca-key.pem"
  cfssl gencert -initca config/ca-csr.json | cfssljson -bare ca -
else
  echo "use existing ca-key.pem."
fi


# ---------------------------------- 派发证书  ----------------------------------

# 创建证书签名请求配置文件req-csr.json，这里填写申请组织信息、ip或域名
cat > config/req-csr.json <<EOF
{
    "CN": "your-test-domain.com",
    "hosts": [
        "localhost",
        "127.0.0.1",
        "domains_or_ips"
    ],
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C": "CN",
            "ST": "GuangDong",
            "L": "GuangZhou",
            "O": "communication",
            "OU": "cluster"
        }
    ]
}
EOF


# 配置证书生成策略，让CA知道颁发什么样的证书。
cat > config/ca-config.json <<EOF
{
    "signing":{
        "default":{
            "expiry":"87600h"
        },
        "profiles":{
            "server":{
                "expiry":"8760h",
                "usages":[
                    "signing",
                    "key encipherment",
                    "server auth"
                ]
            },
            "client":{
                "expiry":"8760h",
                "usages":[
                    "signing",
                    "key encipherment",
                    "client auth"
                ]
            },
            "peer":{
                "expiry":"8760h",
                "usages":[
                    "signing",
                    "key encipherment",
                    "server auth",
                    "client auth"
                ]
            }
        }
    }
}
EOF


tagName='\"domains_or_ips\"'
# 把domains_or_ips替换为输入的参数
sed -i "s/$tagName/$hostFields/g" config/req-csr.json

# 使用现有证书和私钥重新颁发新的证书，类型为服务端使用
for name in $params; do
  cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=config/ca-config.json -profile=server config/req-csr.json | cfssljson -bare $name
done

# 删除多余文件
ls | grep -v pem | xargs -i rm -rf {}

5.2 创建nginx默认配置文件

nginx配置文件default.conf内容如下：

server {
    server_name  localhost;

    # 证书
    listen 443 ssl;
    ssl_certificate /etc/nginx/certs/nginx.pem;
    ssl_certificate_key /etc/nginx/certs/nginx-key.pem;
    ssl_session_timeout 5m;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;


    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

# 访问80端口是，重定向到443端口，重定地址是nginx所在宿主机的ip或域名
server{
    listen 80;
    server_name localhost;
    rewrite ^(.*)$  https://192.168.3.5 permanent;
}

5.3 创建启动nginx的docker启动脚本文件

启动nginx脚本文件docker-compose.yml内容如下：

version: '3.1'
services:
  nginx:
    restart: always
    image: nginx
    container_name: nginx
    ports:
      - 80:80
      - 443:443
    volumes:
      - $PWD/conf.d:/etc/nginx/conf.d
      - $PWD/certs:/etc/nginx/certs
      #- $PWD/log:/var/log/nginx

上面准备的脚本文件目录：

.
├── conf.d
│   └── default.conf
├── docker-compose.yml
└── gen-server-cert.sh

5.4 使用nginx检验证书是否可以使用

# 生成本地证书
./gen-server-cert.sh nginx

# 启动nginx
docker-compose up -d

# 在chrome浏览器打开 https://192.168.3.100，点击高级，继续前往，如果能访问，说明证书正常
# 把ca.pem改名为ca.crt，然后导入浏览器的受信任的根证书颁发机构，访问就不会警告了

参考：

• https://github.com/cloudflare/cfssl
• http://www.ruanyifeng.com/blog/2014/02/ssl_tls.html
• https://laurence.blog.csdn.net/article/details/7585965
• https://www.cnblogs.com/heart-runner/archive/2012/01/30/2332020.html
• https://blog.cloudflare.com/introducing-cfssl/

本文链接：https://zhuyasen.com/post/certificate.html，参与评论 »

etcd基础与使用

1 etcd简介

etcd是一个高可用的分布式的键值对存储系统，常用做配置共享和服务发现，由CoreOS公司发起的一个开源项目，受到ZooKeeper与doozer启发而催生的项目，名称”etcd”源自两个想法，即Unix的”/etc”文件夹和”d”分布式系统。”/etc”文件夹是用于存储单个系统的配置数据的地方，而etcd用于存储大规模分布式的配置信息，etcd有如下特点：

• 简单：基于HTTP+JSON的API，用curl就可以轻松使用。
• 可信：使用Raft算法充分实现了分布式。
• 安全：可选SSL客户认证机制。
• 快速：每个节点可支持上万QPS读写。

etcd有V2和V3两个版本，V3版本供了更多功能并提高了性能，应用程序使用新的grpc API访问mvcc存储，mvcc存储区和旧存储区v2是分开且隔离的，写入存储v2不会影响mvcc存储，写入mvcc存储也不会影响存储v2。

API v2和API v3之间存在一些显着差异：

• 事务：在v3中，etcd提供了多键条件事务。应用程序应使用事务代替Compare-And-Swap操作。
• 平面键空间：API v3中没有目录，只有键。例如，”/a/b/c/“是键。范围查询支持获取与给定前缀匹配的所有键。
• 紧凑的响应：delete操作不再返回以前的值。为了获得删除的值，可以使用事务原子地获取密钥，然后删除其值。
• 租约：替代v2 TTL；TTL绑定到租约，密钥附加到租约。TTL过期后，租约将被撤销，所有附加密钥也将被删除。

2 etcd工作原理

etcd集群本身是一个分布式系统，由多个节点相互通信构成整体对外服务，每个节点都存储了完整的数据，并且通过Raft协议保证每个节点维护的数据是一致的，在ETCD集群中任意时刻至多存在一个有效的主节点，由主节点处理所有来自客户端写操作，通过Raft协议保证写操作对状态机的改动会可靠的同步到其他节点，Raft协议如下图所示：

Raft协议主要分为三个部分：选举，复制日志，安全性。

2.1 选举

Raft协议是用于维护一组服务节点数据一致性的协议。这一组服务节点构成一个集群，并且有一个主节点来对外提供服务。当集群初始化，或者主节点挂掉后，面临一个选举问题。集群中每个节点，任意时刻处于Leader、Follower、Candidate这三个角色之一，选举特点如下：

• 当集群初始化时候，每个节点都是Follower角色。
• 集群中存在至多1个有效的主节点，通过心跳与其他节点同步数据；
• 当Follower在一定时间内没有收到来自主节点的心跳，会将自己角色改变为Candidate，并发起一次选举投票。
  • 当收到包括自己在内超过半数节点赞成后，选举成功。
  • 当收到票数不足半数选举失败，或者选举超时。
  • 若本轮未选出主节点，将进行下一轮选举(出现这种情况，是由于多个节点同时选举，所有节点均为获得过半选票)。
• Candidate节点收到来自主节点的信息后，会立即终止选举过程，进入Follower角色。

为了避免陷入选举失败循环，每个节点未收到心跳发起选举的时间是一定范围内的随机值，这样能够避免2个节点同时发起选举。

2.2 复制日志

日志复制是指主节点将每次操作形成日志条目，并持久化到本地磁盘，然后通过网络IO发送给其他节点。其他节点根据日志的逻辑时钟(TERM)和日志编号(INDEX)来判断是否将该日志记录持久化到本地。当主节点收到包括自己在内超过半数节点成功返回，那么认为该日志是可提交的(committed)，并将日志输入到状态机，将结果返回给客户端。

这里需要注意的是，每次选举都会形成一个唯一的TERM编号，相当于逻辑时钟，每一条日志都有全局唯一的编号。

主节点通过网络IO向其他节点追加日志。若某节点收到日志追加的消息，首先判断该日志的TERM是否过期，以及该日志条目的INDEX是否比当前以及提交的日志的INDEX跟早。若已过期，或者比提交的日志更早，那么就拒绝追加，并返回该节点当前的已提交的日志的编号。否则将日志追加，并返回成功。

当主节点收到其他节点关于日志追加的回复后，若发现有拒绝，则根据该节点返回的已提交日志编号，发生其编号下一条日志。

主节点向其他节点同步日志，还作了拥塞控制。主节点发现日志复制的目标节点拒绝了某次日志追加消息，将进入日志探测阶段，一条一条发送日志，直到目标节点接受日志，然后进入快速复制阶段，可进行批量日志追加。

按照日志复制的逻辑，我们可以看到，集群中慢节点不影响整个集群的性能。另外一个特点是，数据只从主节点复制到Follower节点，这样大大简化了逻辑流程。Raft日志复制路程如下图所示：

2.3 安全

选举和复制日志并不能保证节点间数据一致。当一个某个节点挂掉了，一段时间后再次重启，并刚好当选为主节点。而在其挂掉这段时间内，集群若有超过半数节点存活，集群会正常工作，那么会有日志提交，这些提交的日志无法传递给挂掉的节点。当挂掉的节点再次当选举节点，它将缺失部分已提交的日志。在这样场景下，按Raft协议，它将自己日志复制给其他节点，会将集群已经提交的日志给覆盖掉，这显然是不可接受的，对于出现这种问题解决办法：

• 其他协议解决这个问题的办法是，新当选的主节点会询问其他节点，和自己数据对比，确定出集群已提交数据，然后将缺失的数据同步过来。这个方案有明显缺陷，增加了集群恢复服务的时间(集群在选举阶段不可服务)，并且增加了协议的复杂度。

• Raft解决的办法是，在选举逻辑中，对能够成为主节点加以限制，确保选出的节点已定包含了集群已经提交的所有日志。如果新选出的主节点已经包含了集群所有提交的日志，那就不需要从和其他节点比对数据了，简化了流程，缩短了集群恢复服务的时间。

为什么只要仍然有超过半数节点存活，一定能够选出包含所有日志数据的节点作为主节点呢？因为已经提交的日志必然被集群中超过半数节点持久化，显然前一个主节点提交的最后一条日志也被集群中大部分节点持久化。当主节点挂掉后，集群中仍有大部分节点存活，那这存活的节点中一定存在一个节点包含了已经提交的日志了，因此要求etcd集群节点数量为奇数(3，5，7，9……)。

3 ETCD应用场景

3.1 服务发现

ETCD服务发现示意图如下图所示：

服务发现是分布式系统中最常见的需要解决的问题之一，即在同一个分布式集群中的进程或服务，客户端通过名字就可以查找和连接服务端。要解决服务发现的问题，需要有下面三点：

• 一个强一致性、高可用的服务存储目录。基于Raft算法的etcd天生就是这样一个强一致性高可用的服务存储目录。
• 一种注册服务和监控服务健康状态的机制。用户可以在etcd中注册服务，并且对注册的服务设置key TTL，定时保持服务的心跳以达到监控健康状态的效果。
• 一种查找和连接服务的机制。通过在etcd指定的主题快速找到服务地址。

(1) 在微服务中使用etcd服务发现

随着Docker容器的流行，多种微服务共同协作，构成一个相对功能强大的组织架构。使用etcd服务发现机制，在etcd中注册某个服务名字的目录，在该目录下存储可用的服务节点的IP。服务使用者从etcd目录下查找可用的服务节点IP来连接和调用，达到透明化的动态添加这些服务目的，示意图如下图所示：

(2) 在PaaS平台中使用etcd服务发现

PaaS平台中的应用一般都有多个实例，通过域名不仅可以透明的对多个实例进行访问，而且还可以做到负载均衡。但是应用的某个实例随时都有可能故障重启，这时就需要动态的配置域名解析(路由)信息,通过etcd的服务发现功能就可以轻松解决这个动态配置的问题，实现多实例与实例故障重启透明化目的，示意图如下图所示：

3.2 发布订阅消息

etcd的发布订阅消息示意图如下图所示：

在分布式系统中，消息发布与订阅最适合使用用在组件之间通信。使用etcd发布订阅功能可以实现一个配置共享中心，数据提供者在配置中心发布消息，消息消费者订阅他们关心的主题，一旦主题有新消息发布，就会实时通知订阅者，通过这种方式可以做到分布式系统配置的集中式管理与动态更新。

etcd发布订阅最典型应用在kubernetes上，其他场景应用：

• app或服务用到的一些配置信息放到etcd上进行集中管理。在启动的时候主动从etcd获取一次配置信息，在etcd节点上注册一个Watcher并等待，以后每次配置有更新的时候，etcd都会实时通知订阅者，以此达到获取最新配置信息的目的。
• 分布式搜索服务中，索引的元信息和服务器集群机器的节点状态存放在etcd中，供各个客户端订阅使用。使用etcd的key TTL功能可以确保机器状态是实时更新的。
• 分布式日志收集系统。 这个系统的核心工作是收集分布在不同机器的日志。收集器通常是按照应用(或主题)来分配收集任务单元，因此可以在etcd上创建一个以应用(主题)命名的目录，并将这个应用(主题相关)的所有机器ip，以子目录的形式存储到目录上，然后设置一个etcd递归的Watcher，递归式的监控应用(主题)目录下所有信息的变动。这样就实现了机器IP(消息)变动的时候，能够实时通知到收集器调整任务分配。
• 系统中信息需要动态自动获取与人工干预修改信息请求内容的情况。只需要要将信息存放到指定的etcd目录中，etcd的这些目录就可以通过HTTP的接口在外部访问。

3.3 负载均衡

etcd的负载均衡示意图如下图所示：

etcd本身分布式架构存储的信息访问支持负载均衡，etcd集群化以后，每个etcd的核心节点都可以处理用户的请求。所以把数据量小但是访问频繁的消息数据直接存储到etcd中也是个不错的选择。 etcd可以监控一个集群中多个节点的状态，利用etcd维护一个负载均衡节点表，当有一个请求发过来后，可以轮询式的把请求转发给存活着的节点。

分布式系统中，为了保证服务的高可用以及数据的一致性，通常都会把数据和服务部署多份，以此达到对等服务，即使其中的某一个服务失效了，也不影响使用。由此带来的坏处是数据写入性能下降，而好处则是数据访问时的负载均衡。因为每个对等服务节点上都存有完整的数据，所以用户的访问流量就可以分流到不同的机器上。

3.4 分布式通知与协调

这里说到的分布式通知与协调，与消息发布和订阅有些相似。都用到了etcd中Watche机制，通过注册与异步通知机制，实现分布式环境下不同系统之间 的通知与协调，从而对数据变更做到实时处理。实现方式：不同系统都在etcd上对同一个目录进行注册，同时设置Watcher观测该目录的变化(如果对子目录的变化也有需要，可以设置递归模式)，当某个系统更新了etcd的目录，那么设置了Watcher的系统就会收到通知，并作出相应处理。

使用etcd完成分布式协同工作原理如下图所示：

• 通过etcd进行低耦合的心跳检测。检测系统和被检测系统通过etcd上某个目录关联而非直接关联起来，这样可以大大减少系统的耦合性。
• 通过etcd完成系统调度。某系统有控制台和推送系统两部分组成，控制台的职责是控制推送系统进行相应的推送工作。管理人员在控制台作的一些操作，实际上是修改了etcd上某些目录节点的状态，而etcd就把这些变化通知给注册了Watcher的推送系统客户端，推送系统再作出相应的推送任务。
• 通过etcd完成工作汇报。大部分类似的任务分发系统，子任务启动后，到etcd来注册一个临时工作目录，并且定时将自己的进度进行汇报(将进度写入到这个临时目录)，这样任务管理者就能够实时知道任务进度。

3.5 分布式锁

因为etcd使用Raft算法保持了数据的强一致性，某次操作存储到集群中的值必然是全局一致的，所以很容易实现分布式锁，锁有两种使用方式:

• 保持独占，即所有获取锁的用户最终只有一个可以得到。etcd为此提供了一套实现分布式锁原子操作CAS(CompareAndSwap)的API。通过设置prevExist值，可以保证在多个节点同时去创建某个目录时只有一个成功，而创建成功的用户就可以认为是获得了锁。
• 控制时序，即所有想要获得锁的用户都会被安排执行，但是获得锁的顺序也是全局唯一的，同时决定了执行顺序。etcd为此也提供了一套API(自动创建有序键)，对一个目录建值时指定为POST动作，这样etcd会自动在目录下生成一个当前最大的值为键，存储这个新的值(客户端编号)。同时还可以使用API按顺序列出所有当前目录下的键值。此时这些键的值就是客户端的时序，而这些键中存储的值可以是代表客户端的编号。

从etcd获取的分布式锁如下图所示：

3.6 分布式队列

分布式队列的常规用法与场景五中所描述的分布式锁的控制时序用法类似，创建一个先进先出的队列，保证顺序。另一种比较有意思的实现是在保证队列达到某个条件时再统一按顺序执行。这种方法的实现可以在/queue这个目录中另外建立一个/queue/condition节点，condition可以表示信息如下：

• condition可以表示队列大小。比如一个大的任务需要很多小任务就绪的情况下才能执行，每次有一个小任务就绪，就给这个condition数字加1，直到达到大任务规定的数字，再开始执行队列里的一系列小任务，最终执行大任务，如下图所示：

• condition可以表示某个任务在不在队列。这个任务可以是所有排序任务的首个执行程序，也可以是拓扑结构中没有依赖的点。通常必须执行这些任务后才能执行队列中的其他任务。

• condition还可以表示其它的一类开始执行任务的通知。可以由控制程序指定，当condition出现变化时，开始执行队列任务。

3.7 集群监控

使用etcd来实现集群的实时性的监控，可以第一时间检测到各节点的健康状态，以完成集群的监控要求。etcd本身就有自带检点健康监控功能，实现起来也比较简单。

• 使用Watcher机制，当某个节点消失或有变动时，Watcher会第一时间发现并告知用户。
• 节点可以设置TTL key，比如每隔30s发送一次心跳使代表该机器存活的节点继续存在，否则节点消失。

3.8 Leader竞选

使用分布式锁，可以完成Leader竞选。这种场景通常是一些长时间CPU计算或者使用IO操作的机器，只需要竞选出的Leader计算或处理一次，就可以把结果复制给其他的Follower，从而避免重复劳动，节省计算资源。

可使用在搜索系统中建立全量索引。如果每个机器都进行一遍索引的建立，不但耗时而且建立索引的一致性不能保证。通过在etcd的CAS机制同时创建一个节点，创建成功的机器作为Leader，进行索引计算，然后把计算结果分发到其它节点。

4 安装

4.1 在docker安装单机版

使用docker-compose.yml脚本如下：

version: "3"
  
services:
  etcd:
    image: quay.io/coreos/etcd
    container_name: etcd-single
    restart: always
    ports:
      - 2379:2379
      - 2380:2380
    volumes:
      - $PWD/etcd-data:/etcd-data
    environment:
      - ETCDCTL_API=3
    command:
      - /usr/local/bin/etcd
      - --data-dir=/etcd-data
      - --name=etcd-single
      - --listen-peer-urls=http://0.0.0.0:2380
      - --listen-client-urls=http://0.0.0.0:2379
      - --initial-advertise-peer-urls=http://0.0.0.0:2380
      - --advertise-client-urls=http://0.0.0.0:2379
      #- --initial-cluster=etcd-single=http://0.0.0.0:2380 # 不指定参数，让etcd自动生成

# 启动etcd服务
docker-compose up -d

# 把容器里的etcdctl客户端复制到本地使用
docker exec -t etcd-single cp /usr/local/bin/etcdctl /etcd-data
sudo mv /etcd-data/etcdctl /usr/local/bin/

# 让etcdctl使用v3版本，和服务端对应
echo 'export ETCDCTL_API=3' >> ~/.bashrc
source  ~/.bashrc

# 查看版本
etcdctl version

# 查看成员
etcdctl member list

4.2 在一台主机上安装docker集群版

version: '3'

services:
  etcd1:
    image: quay.io/coreos/etcd
    container_name: etcd1
    restart: always
    environment:
      - ETCDCTL_API=3
    command:
      - etcd
      - --name=etcd1
      - --data-dir=/etcd-data
      - --advertise-client-urls=http://0.0.0.0:2379
      - --listen-client-urls=http://0.0.0.0:2379
      - --listen-peer-urls=http://0.0.0.0:2380
      - --initial-cluster-token=etcd-cluster
      - --initial-cluster=etcd1=http://etcd1:2380,etcd2=http://etcd2:2380,etcd3=http://etcd3:2380
      - --initial-cluster-state=new
    ports:
      - 23791:2379
      - 23801:2380
    volumes:
      - $PWD/etcd1-data:/etcd-data
    networks:
      - etcd-net

  etcd2:
    image: quay.io/coreos/etcd
    container_name: etcd2
    restart: always
    environment:
      - ETCDCTL_API=3
    command:
      - etcd
      - --name=etcd2
      - --data-dir=/etcd-data
      - --advertise-client-urls=http://0.0.0.0:2379
      - --listen-client-urls=http://0.0.0.0:2379
      - --listen-peer-urls=http://0.0.0.0:2380
      - --initial-cluster-token=etcd-cluster
      - --initial-cluster=etcd1=http://etcd1:2380,etcd2=http://etcd2:2380,etcd3=http://etcd3:2380
      - --initial-cluster-state=new
    ports:
      - 23792:2379
      - 23802:2380
    volumes:
      - $PWD/etcd2-data:/etcd-data
    networks:
      - etcd-net

  etcd3:
    image: quay.io/coreos/etcd
    container_name: etcd3
    restart: always
    environment:
      - ETCDCTL_API=3
    command:
      - etcd
      - --name=etcd3
      - --data-dir=/etcd-data
      - --advertise-client-urls=http://0.0.0.0:2379
      - --listen-client-urls=http://0.0.0.0:2379
      - --listen-peer-urls=http://0.0.0.0:2380
      - --initial-cluster-token=etcd-cluster
      - --initial-cluster=etcd1=http://etcd1:2380,etcd2=http://etcd2:2380,etcd3=http://etcd3:2380
      - --initial-cluster-state=new
    ports:
      - 23793:2379
      - 23803:2380
    volumes:
      - $PWD/etcd3-data:/etcd-data
    networks:
      - etcd-net

networks:
  etcd-net:

# 启动etcd集群
docker-compose up -d

# 查看集群成员列表
etcdctl --endpoints=http://127.0.0.1:23791 member list

# 查看成员状态
etcdctl --write-out=table --endpoints=http://127.0.0.1:23791 endpoint status

4.3 在多个节点安装etcd集群

一共三个节点，IP地址分别是192.168.3.101、192.168.3.102、192.168.3.103。

在192.168.3.101节点创建docker-compose.yml文件，内容如下：

version: "3.7"
  
services:
  etcd:
    image: quay.io/coreos/etcd
    container_name: my-etcd
    restart: always
    environment:
      - ETCDCTL_API=3
    command:
      - etcd
      # 成员
      - --name=etcd1
      - --data-dir=/etcd-data
      - --listen-peer-urls=http://0.0.0.0:2380
      - --listen-client-urls=http://0.0.0.0:2379
      # 集群
      - --initial-advertise-peer-urls=http://192.168.3.101:2380
      - --advertise-client-urls=http://192.168.3.101:2379
      - --initial-cluster-token=cluster-token
      - --initial-cluster=etcd1=http://192.168.3.101:2380,etcd2=http://192.168.3.102:2380,etcd3=http://192.168.3.103:2380
      - --initial-cluster-state=new
    volumes:
      - $PWD/etcd-data:/etcd-data
    ports:
      - 2379:2379
      - 2380:2380
    network_mode: "host"
    stdin_open: true
    tty: true

在192.168.3.102节点创建docker-compose.yml文件，内容如下：

version: "3.7"
  
services:
  etcd:
    image: quay.io/coreos/etcd
    container_name: my-etcd
    restart: always
    environment:
      - ETCDCTL_API=3
    command:
      - etcd
      # 成员
      - --name=etcd2
      - --data-dir=/etcd-data
      - --listen-peer-urls=http://0.0.0.0:2380
      - --listen-client-urls=http://0.0.0.0:2379
      # 集群
      - --initial-advertise-peer-urls=http://192.168.3.102:2380
      - --advertise-client-urls=http://192.168.3.102:2379
      - --initial-cluster-token=cluster-token
      - --initial-cluster=etcd1=http://192.168.3.101:2380,etcd2=http://192.168.3.102:2380,etcd3=http://192.168.3.103:2380
      - --initial-cluster-state=new
    volumes:
      - $PWD/etcd-data:/etcd-data
    ports:
      - 2379:2379
      - 2380:2380
    network_mode: "host"
    stdin_open: true
    tty: true

在192.168.3.103节点创建docker-compose.yml文件，内容如下：

version: "3.7"
  
services:
  etcd:
    image: quay.io/coreos/etcd
    container_name: my-etcd
    restart: always
    environment:
      - ETCDCTL_API=3
    command:
      - etcd
      # 成员
      - --name=etcd3
      - --data-dir=/etcd-data
      - --listen-peer-urls=http://0.0.0.0:2380
      - --listen-client-urls=http://0.0.0.0:2379
      # 集群
      - --initial-advertise-peer-urls=http://192.168.3.103:2380
      - --advertise-client-urls=http://192.168.3.103:2379
      - --initial-cluster-token=cluster-token
      - --initial-cluster=etcd1=http://192.168.3.101:2380,etcd2=http://192.168.3.102:2380,etcd3=http://192.168.3.103:2380
      - --initial-cluster-state=new
    volumes:
      - $PWD/etcd-data:/etcd-data
    ports:
      - 2379:2379
      - 2380:2380
    network_mode: "host"
    stdin_open: true
    tty: true

三个节点的etcd运行脚本不一样的地方只有三个启动参数，分别是–name、–initial-advertise-peer-urls、–advertise-client-urls。

# 分别在3个节点启动etcd
docker-compose up -d

# 查看集群成员列表
export ENDPOINTS=192.168.3.101:2379,192.168.3.102:2379,192.168.3.103:2379
etcdctl --endpoints=$ENDPOINTS member list

# 查看成员状态
etcdctl --write-out=table --endpoints=$ENDPOINTS endpoint status

4.4 TLS加密通信

如果集群需要使用TLS协议进行的加密通信，又要验证其身份，需要添加自签名证书，生成自签名证书脚本文件gen-peer-certs.sh如下：

#!/bin/bash


# -------------------------------- 参数判断 --------------------------------------------
params=$@

if [ $# -lt 1 ]; then
    echo "param is empty"
    echo "usage: $0 [domain ...] | [ip ...]"
    echo "eg: $0 zhuyasen.com 192.168.3.100"
    echo ""
    exit
fi

# 用参数替换req-csr.json固定字段值domains_or_ips
hostFields=''
for val in $params; do
    hostFields=${hostFields}\\\"$val\\\",
done
# 去掉最后一个逗号
hostFields=${hostFields%?}


# ---------------------------------- 创建认证中心(CA) ----------------------------------
# 创建存储证书目录和配置目录
mkdir -p certs
cd certs
mkdir -p config

# 创建根CA证书和私钥的CSR(证书签名请求文件)配置文件ca-csr.json
cat > config/ca-csr.json <<EOF
{
    "CN": "myMechanism",
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C": "CN",
            "ST": "Beijing",
            "L": "Beijing",
            "O": "my organization",
            "OU": "my organization unit name"
        }
    ]
}
EOF

# 生成CA证书和私钥，先判断ca-key.pem是否存在，如果存在则使用已存在的
if [[ ! -f "ca-key.pem" ]]; then
  echo "generate new ca.pem and ca-key.pem"
  cfssl gencert -initca config/ca-csr.json | cfssljson -bare ca -
else
  echo "use existing ca-key.pem."
fi


# ---------------------------------- 派发证书  ----------------------------------
# 创建证书签名请求配置文件req-csr.json，这里填写申请组织信息、ip或域名，注：当集群使用tls认证，并且只使用ip访问时，必须添加本地ip进来，外部访问才能通过鉴权，否则只能本地访问
cat > config/req-csr.json <<EOF
{
    "CN": "etcd",
    "hosts": [
        "localhost",
        "127.0.0.1",
        "domains_or_ips"
    ],
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C": "CN",
            "ST": "GuangDong",
            "L": "GuangZhou",
            "O": "communication",
            "OU": "cluster"
        }
    ]
}
EOF


# 配置证书生成策略，让CA知道颁发什么样的证书。
cat > config/ca-config.json <<EOF
{
    "signing":{
        "default":{
            "expiry":"87600h"
        },
        "profiles":{
            "peer":{
                "expiry":"8760h",
                "usages":[
                    "signing",
                    "key encipherment",
                    "server auth",
                    "client auth"
                ]
            }
        }
    }
}
EOF


tagName='\"domains_or_ips\"'
# 把domains_or_ips替换为输入的参数
sed -i "s/$tagName/$hostFields/g" config/req-csr.json

# 使用现有证书和私钥重新颁发新的证书，类型为服务端使用
for name in $params; do
  cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=config/ca-config.json -profile=peer config/req-csr.json | cfssljson -bare $name
  cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=config/ca-config.json -profile=peer config/req-csr.json | cfssljson -bare peer-$name
done

# 删除多余文件
ls | grep -v pem | xargs -i rm -rf {}

# 执行脚本生成证书，参数为各个节点ip地址，在当前certs目录下
./gen-peer-certs.sh 192.168.3.101 192.168.3.102 192.168.3.103

# 验证生成的证书是否有效
cd certs
openssl verify -CAfile ca.pem 192.168.3.101.pem
openssl verify -CAfile ca.pem peer-192.168.3.101.pem

# 在docker-compose.yml添加共享目录，把证书复制到容器里
    volumes:
      - $PWD/certs:/etcd-certs

# 在docker-compose.yml的etcd启动命令中添加证书参数，每个节点都需要添加
    command:
      # client端证书
      - --client-cert-auth
      - --trusted-ca-file=/etcd-certs/ca.pem
      - --cert-file=/etcd-certs/192.168.3.xxx.pem
      - --key-file=/etcd-certs/192.168.3.xxx-key.pem
      # peer端证书
      - --peer-client-cert-auth
      - --peer-trusted-ca-file=/etcd-certs/ca.pem
      - --peer-cert-file=/etcd-certs/peer-192.168.3.xxx.pem
      - --peer-key-file=/etcd-certs/peer-192.168.3.xxx-key.pem

# 连接客户端需要认证参数
--cacert --cert --key这三个参数都不能缺少，其中--cert --key这两个参数可以是任意一个节点的客户端证书和私钥

# 示例
etcdctl --endpoints=$ENDPOINTS \
--cacert=ca.pem \
--cert=192.168.3.101.pem \
--key=192.168.3.101-key.pem \
member list

# 为了避免每次都输入一大串参数，在~/.bashrc添加下面别名
export ETCDCTL_API=3
HOST_1=192.168.3.101:23791
HOST_2=192.168.3.102:23792
HOST_3=192.168.3.103:23793
ENDPOINTS=$HOST_1,$HOST_2,$HOST_3
alias etcdctl="etcdctl --endpoints=$ENDPOINTS"
certPath=/home/zhuyasen/work/etcd/etcd-cluster-local/certs
alias etcdctlcert="etcdctl --endpoints=$ENDPOINTS --cacert=${certPath}/ca.pem --cert=${certPath}/192.168.3.101.pem --key=${certPath}/192.168.3.101-key.pem"

# 刷新生效
source ~/.bashrc

# 使用
etcdctlcert member list

注：如果是在本地一台主机使用docker搭建的需要tls鉴权认证的etcd集群，局域网内其他主机想要通过tls鉴权访问集群，必须把etcd集群所在主机的ip地址填写到req-csr.json配置文件的hosts字段下，否则会报错authentication handshake failed: x509: certificate is valid for 127.0.0.1, not 192.168.3.5(集群所在主机的ip地址)

4.5 etcd集群性能压测

定义性能的两个因素是：延迟和吞吐量，延迟是完成操作所花费的时间。吞吐量是一段时间内完成的全部操作。

# 下载压测工具(需要代理)，需要先安装go才可以下载编译
set https_proxy=http://127.0.0.1:10809
set http_proxy=http://127.0.0.1:10809
go get -v go.etcd.io/etcd/tools/benchmark

# 进去目录$GOPATH/src/go.etcd.io/etcd/tools/benchmark
go build
sudo mv benchmark /usr/local/bin

设置环境变量

set HOST_1=192.168.3.101:2379
set HOST_2=192.168.3.102:2379
set HOST_3=192.168.3.103:2379

# 获取主节点(IS LEADER为true)
etcdctl endpoint status --endpoints=${HOST_1},${HOST_2},${HOST_3}
# 得知主节点为HOST_3

(1) 写入压测

# 压测写入主节点(多用户)
benchmark --endpoints=${HOST_1} --target-leader  --conns=100 --clients=1000 \
    put --key-size=8 --sequential-keys --total=100000 --val-size=256
# 结果: 吞吐量65985.5875 req/s，平均延时14.8毫秒

# 压测写入所有成员(多用户)
benchmark --endpoints=${HOST_1},${HOST_2},${HOST_3} --conns=100 --clients=1000 \
    put --key-size=8 --sequential-keys --total=100000 --val-size=256
# 结果: 吞吐量62264.1271 req/s，平均延时15.7毫秒

(2) 读取压测

# 线性化(linearizabe)读取数据
benchmark --endpoints=${HOST_1},${HOST_2},${HOST_3} --conns=100 --clients=1000 range foo --consistency=l --total=100000
# 结果: 吞吐量103923.3802 req/s，平均延时9毫秒

# 串行化(serializabe)读取数据
benchmark --endpoints=${HOST_1},${HOST_2},${HOST_3} --conns=100 --clients=1000 range foo --consistency=s --total=100000
# 结果: 吞吐量115904.776 req/s，平均延时8.1毫秒

5 etcdctl常用命令

etcdctl是一个命令行的客户端，它提供了简洁的命令，可理解为命令工具集，可以方便我们在对服务进行测试或者手动修改数据库内容。etcdctl与kubectl、systemctl命令原理及操作类似。

用法：

etcdctl [global options] command [command options][args…]

安装etcdctl：

# 方式一：从github官网下载 https://github.com/etcd-io/etcd/releases

# 方式二：从运行的docker中复制到本地
sudo docker cp etcd容器ID或名称:/usr/local/bin/etcdctl /usr/local/bin

etcd 在键的组织上采用了层次化的空间结构(类似于文件系统中目录的概念)，数据库操作围绕对键值和目录的 CRUD 增删改查完整生命周期的管理。

具体的命令选项参数可以通过 etcdctl command –help来获取相关帮助，下面都是V3版本命令。

指定etcd集群，在~/.bashrc添加下面内容

export ETCDCTL_API=3
HOST_1=127.0.0.1:23791
HOST_2=127.0.0.1:23792
HOST_3=127.0.0.1:23793
ENDPOINTS=$HOST_1,$HOST_2,$HOST_3
# 覆盖etcdctl命令，如果需要使用原生命令，可以在命令开头加一个\反斜线，例如：\etcdctl xxxx xxxx
alias etcdctl="etcdctl --endpoints=$ENDPOINTS"
alias etcdctljson="etcdctl --endpoints=$ENDPOINTS --write-out=json"
alias etcdctltable="etcdctl --endpoints=$ENDPOINTS --write-out=table"

刷新生效：

source ~/.bashrc

KV API的操作有下面保证：

• 原子性，所有API请求都是原子请求，一个操作要么完全完成，要么根本不完成。对于监视请求，由一个操作生成的所有事件将在一个监视响应中，Watch从不观察单个操作的部分事件。
• 耐用性，任何完成的操作都是持久的，所有可访问的数据也是持久数据，读取将永远不会返回尚未持久化的数据。
• 严格的可序列化性 ，这是分布式事务数据库系统的最强隔离保证，读操作将永远不会观察到任何中间数据。

5.1 增删改查数据相关命令

增加和修改，如果存在则替换

etcdctl put <键名> <键值> [选项]

# 示例
etcdctl put key "Hello ETCD"
etcdctl put key1 "Hello ETCD 1"
etcdctl put leaseKey "alive value" --lease=12f775cb02d34d94 # 有生命周期的key

查询

etcdctl get <键名> [选项]

# 示例：
etcdctl get key
etcdctl get key --prefix # 相同前缀查找
etcdctl get / --prefix --keys-only # 只获取/开始的所有key，不包括值

删除

etcdctl del <键名> [选项]

# 示例：
etcdctl del key
etcdctl get key --prefix # 相同前缀删除

5.2 集群状态相关命令

查看集群状态

etcdctl endpoint status --write-out=table

# +-----------------+------------------+---------+---------+-----------+-----------+------------+
# |    ENDPOINT     |        ID        | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
# +-----------------+------------------+---------+---------+-----------+-----------+------------+
# | 127.0.0.1:23791 | ade526d28b1f92f7 |   3.3.8 |   22 MB |     false |        10 |       9177 |
# | 127.0.0.1:23792 | d282ac2ce600c1ce |   3.3.8 |   22 MB |     false |        10 |       9177 |
# | 127.0.0.1:23793 | bd388e7810915853 |   3.3.8 |   22 MB |      true |        10 |       9177 |
# +-----------------+------------------+---------+---------+-----------+-----------+------------+

查看集群健康状态

etcdctl endpoint health

# 127.0.0.1:23793 is healthy: successfully committed proposal: took = 583.669µs
# 127.0.0.1:23792 is healthy: successfully committed proposal: took = 710.885µs
# 127.0.0.1:23791 is healthy: successfully committed proposal: took = 734.486µs

5.3 集群成员操作相关命令

查看集群成员列表

etcdctl member list --write-out=table

# +------------------+---------+-------+-------------------+---------------------+
# |        ID        | STATUS  | NAME  |    PEER ADDRS     |    CLIENT ADDRS     |
# +------------------+---------+-------+-------------------+---------------------+
# | ade526d28b1f92f7 | started | etcd1 | http://etcd1:2380 | http://0.0.0.0:2379 |
# | bd388e7810915853 | started | etcd3 | http://etcd3:2380 | http://0.0.0.0:2379 |
# | d282ac2ce600c1ce | started | etcd2 | http://etcd2:2380 | http://0.0.0.0:2379 |
# +------------------+---------+-------+-------------------+---------------------+

添加成员

etcdctl member add <成员名称> [--peer-urls=节点地址]

# 示例：将目标节点etcd4添加到集群
etcdctl member add etcd4 http://192.168.3.104:2380
# 启动目标集群时需要设置启动参数如下
etcd --name=etcd4 --data-dir=/etcd-data \
  --listen-peer-urls=http://192.168.3.104:2380 \
  --listen-client-urls=http://192.168.3.104:2379 \
  --initial-advertise-peer-urls=http://192.168.3.104:2380 \
  --advertise-client-urls=http://192.168.3.104:2379 \
  --initial-cluster=etcd1=http://192.168.3.101:2380,etcd2=http://192.168.3.102:2380,etcd3=http://192.168.3.103:2380,etcd4=http://192.168.3.104:2380 \
  --initial-cluster-state=existing

更新成员

新成员必须启动的，类似添加成员

etcdctl member update <成员id> [--peer-urls=节点地址]

  # 示例：
  etcdctl member update ade526d28b1f92f7 --peer-urls=http://192.168.3.111:2380

删除成员

etcdctl member remove <成员id>

# 示例
etcdctl member remove ade526d28b1f92f7

5.4 租约相关命令

租约具有生命周期，需要为租约授予一个TTL(time to live)，将租约绑定到一个key上，则key的生命周期与租约一致，可续租，可撤销租约。

etcdctl lease

etcdctl lease 子命令有：

• grant: 添加新租约
• revoke: 删除租约
• list: 列出所有租约
• timetolive: 获取租约详情信息
• keep-alive: 保持租约有效(续签)

# 生成一份新租约
etcdctl lease grant 600

# 查看租约列表
etcdctl lease list

# 查看租约的剩余生命时长，可以使用json输出得到字段值
etcdctl lease timetolive 12f775cb02d34d94
etcdctl lease timetolive 12f775cb02d34d94 --keys # 查看已绑定的key

# 撤销租约，绑定租约的key也会自动失效
etcdctl lease revoke 12f775cb02d34d94

# 续租
etcdctl lease keep-alive 12f775cb02d34d94 # 持续续租，无过期(阻塞)
etcdctl lease keep-alive 12f775cb02d34d94 --once # 将保持存活时间重置为其原始值并立即退出

# key绑定租约
etcdctl put leaseKey "alive value" --lease=12f775cb02d34d94

5.5 watch命令

watch是监听键或前缀发生改变的事件流。

# 对某个key监听操作，当/key1发生改变时，会返回最新值
etcdctl watch /key1

# 监听key前缀
etcdctl watch /key --prefix

# 监听到改变后执行相关操作
etcdctl watch /key1 -- etcdctl member list

5.6 事务txn

txn从标准输入读取多个etcd请求，并将它们作为单个原子事务应用。 交易由条件清单组成，如果所有条件都为真，则应用请求列表；如果任何条件为假，则不应用请求列表。

etcdctl txn [options]

# 设置key值
etcdctl put name zhangsan
etcdctl put age 22

# 交互式事务
etcdctl txn -i
# ---------------- 进入终端交互式 ----------------
compares:
value("age") > "18" # 条件清单1
value("name") = "zhangsan" # 条件清单2

success requests (get, put, del):
put result true  # 所有条件成立执行命令

failure requests (get, put, del):
put result false  # 至少有一个条件清单不成立执行命令

SUCCESS

OK
# ---------------- 结束终端交互式 ----------------

# 查看事务执行结果
etcdctl get result
  # result
  # true

5.7 分布式锁

分布式锁，多个客户端同时抢锁，抢到锁可以操作，其他没有获取到锁的会等待阻塞状态，等锁释放之后才可以获取到锁。

etcdctl lock [options] [exec-command arg1 arg2 …]

# 在第一个终端
etcdctl lock mutexKey
  # mutexKey/326963a02758b52d
​
# 在第二终端
etcdctl lock mutexKey
​
# 当第一个终端结束了，第二个终端会显示
mutexKey/326963a02758b531

注：只有当正常退出且释放锁后，lock命令的退出码是0，否则这个锁会一直被占用直到过期。

5.7 备份和恢复命令

# 快照
etcdctl snapshot save backup.db

# 查看快照文件信息
etcdctl snapshot status backup.db --write-out=table

# 恢复快照
etcdctl snapshot restore backup.db \
--name=etcd1 \
--data-dir=xxx \
--initial-advertise-peer-urls=xxx \
--initial-cluster=xxx \
--initial-cluster-token=xxx

5.8 查看警报命令

如果内部出现问题，会触发警报，可以通过命令查看警报引起原因。

# 查看所有警报
etcdctl alarm list

# 解除所有警报
etcdctl alarm disarm

5.9 用户和角色相关命令

etcd默认是没有开启访问控制的，如果开启外网访问etcd的话就需要考虑访问控制的问题，etcd提供了两种访问控制的方式：

• 基于身份验证的访问控制
• 基于证书的访问控制

etcd有一个特殊用户root和一个特殊角色root：

• root用户：root用户是etcd的超级管理员，拥有etcd的所有权限，在开启角色认证之前为们必须要先建立好root用户。
• root角色：具有该root角色的用户既具有全局读写访问权限，具有更新集群的身份验证配置的权限。此外，该root角色还授予常规集群维护的特权，包括修改集群成员资格，对存储进行碎片整理以及拍摄快照。

注：root用户必须拥有root角色之后，root用户才允许在操作etcd的所有东西。

etcd的权限资源：

• Users: user用来设置身份认证(user：passwd)，一个用户可以拥有多个角色，每个角色被分配一定的权限(只读、只写、可读写)，用户分为root用户和非root用户。
• Roles: 角色用来关联权限，角色主要三类：root角色。默认创建root用户时即创建了root角色，该角色拥有所有权限；guest角色，默认自动创建，主要用于非认证使用。普通角色，由root用户创建角色，并分配指定权限。
• Permissions: 权限分为只读、只写、可读写三种权限，权限即对指定目录或key的读写权限。

注意：如果没有指定任何验证方式，即没显示指定以什么用户进行访问，那么默认会设定为 guest 角色。默认情况下 guest 也是具有全局访问权限的。

管理用户的子命令

etcdctl user

etcdctl user 子命令有：

• add: 添加新用户
• delete: 删除用户
• get: 获取用户的详细信息
• list: 列出所有用户
• passwd: 修改用户密码
• grant-role: 授予用户角色
• revoke-role: 撤销用户的角色

管理角色的子命令

etcdctl role

etcdctl role 子命令有：

• add: 添加新角色
• delete: 删除角色
• get: 获取角色的详细信息
• list: 列出所有角色
• grant-permission: 把key操作权限授予给一个角色
• revoke-permission: 从角色中撤销key操作权限

开启root身份验证

开启了身份验证之后，所有etcdctl命令操作都需要指定用户参数–user，参数值为用户名:密码，类似开启了证书访问控制之后，所有etcdctl命令需要添加证书参数–cacert.

# 创建root后，root用户默认拥有类似linux一样超级管理员权限，添加用户root后默认还有root角色
etcdctl user add root
  # Password of root: 123456
  # Type password of root again for confirmation: 123456

# 开启身份验证，如果取消把enable改为disable
etcdctl auth enable

# 操作时必须指定用户，否则会报错
etcdctl put key "hello etcd" --user=root:123456
etcdctl get key --user=root:123456

新用户和角色授权

开启了root身份验证之后，就可以对普通用户和角色操作了。

(1) 用户增删改查

# 添加新用户zhangsan
etcdctl user add zhangsan --user=root:123456
  # Password of root: 123456
  # Type password of root again for confirmation: 123456

# 获取用户的详细信息
etcdctl user get zhangsan --user=root:123456

# 查看所有用户
etcdctl user list --user=root:123456

# 修改用户密码
etcdctl user passwd zhangsan --user=root:123456

# 删除用户
etcdctl user delete zhangsan --user=root:123456

(2) 角色增删改查

# 添加新角色redis
etcdctl role add redis --user=root:123456

# 获取角色的详细信息
etcdctl role get redis --user=root:123456

# 查看所有角色
etcdctl role list --user=root:123456

# 删除角色
etcdctl role delete redis --user=root:123456

(3) 绑定和授权

有了新用户和新角色之后，还需要把用户和角色绑定在一起，确定授权权限之后，新用户才可以对key有对应操作权限

# 授予角色redis权限，可以设置只读(read)、只写(write)、读写(readwrite)
etcdctl role grant-permission redis readwrite redisKey/ --user=root:123456
# 或授予key前缀 etcdctl role grant-permission redis readwrite redisKey/  --prefix=true  --user=root:123456

# 用户zhangsan绑定redis角色，获得操作权限
etcdctl user grant-role zhangsan redis --user=root:123456


# 下面是用户zhangsan在授权前后操作redisKey/
  xxxx@pc:~$ etcdctl put redisKey/ "hello redis" --user=root:123456
    # OK
  xxxx@pc:~$ etcdctl get redisKey/ --user=root:123456
    # redisKey/
    # hello redis
  xxxx@pc:~$ etcdctl get redisKey/ --user=zhangsan:123456
    # Error: etcdserver: permission denied
  xxxx@pc:~$ etcdctl role grant-permission redis readwrite redisKey/ --user=root:123456
    # Role redis updated
  xxxx@pc:~$ etcdctl get redisKey/ --user=zhangsan:123456
    # Error: etcdserver: permission denied
  xxxx@pc:~$ etcdctl user grant-role zhangsan redis --user=root:123456
    # Role redis is granted to user zhangsan
  xxxx@pc:~$ etcdctl get redisKey/ --user=zhangsan:123456
    # redisKey/
    # hello redis


# 撤回角色redis对redisKey/的操作权限
etcdctl role revoke-permission redis redisKey/ --user=root:123456

# 解绑用户zhangsan和角色redis，也就是用户zhangsan操作权限(redis角色的权限)被收回
etcdctl user revoke-role zhangsan redis --user=root:123456

6 etcd的go客户端

6.1 安装

不要直接使用 go get -u go.etcd.io/etcd 命令安装etcd客户端，可会遇到些奇怪问题，直接从github下载稳定版本 https://github.com/etcd-io/etcd/archive/v3.4.13.zip

# 在$GOPATH/src下创建目录go.etcd.io

# 解压文件v3.4.13.zip，并把目录名称改为etcd，然后把整个etcd目录移动到$GOPATH/src/go.etcd.io/目录下即可

6.2 连接etcd服务

(1) 简单连接

func InitETCD(endPoints []string) (*clientv3.Client, error) {
    // 配置
    config := clientv3.Config{
        Endpoints:   endPoints,
        DialTimeout: 10 * time.Second,
    }

    // 连接
    return clientv3.New(config)
}

/* 调用
    cli, err := InitETCD([]string{"192.168.3.5:2379"})
    if err != nil {
        panic(err)
    }
*/

(2) 有tls身份验证连接

// InitETCDWithTLS 连接需要认证的etcd
func InitETCDWithTLS(endPoints []string, caFile, certFile, keyFile string) (*clientv3.Client, error) {
    tlsInfo := transport.TLSInfo{
        TrustedCAFile: caFile,
        CertFile:      certFile,
        KeyFile:       keyFile,
    }
    tlsConfig, err := tlsInfo.ClientConfig()
    if err != nil {
        return nil, err
    }

    // 配置etcd
    config := clientv3.Config{
    Endpoints: endPoints,
        DialTimeout: 5 * time.Second,
        TLS:       tlsConfig,
    }

    return clientv3.New(config)
}

/*
    endPoints := []string{"192.168.3.5:23791", "192.168.3.5:23792", "192.168.3.5:23793"}
    caFile := "D:\\certs\\ca.pem"
    certFile := "D:\\certs\\etcd1.pem"
  keyFile := "D:\\certs\\etcd1-key.pem"
  
    cli, err := InitETCDWithTLS(endPoints, caFile, certFile, keyFile)
    if err != nil {
        panic(err)
    }
*/

6.3 增删改查数据

(1) 增加和修改

    putResp, err := cli.KV.Put(context.Background(), "/user/zhangsan", "v5")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println("global version is", putResp.Header.Revision)


  // 增加或修改时返回上一个版本值和版本号
    putResp, err := cli.KV.Put(context.Background(), "/user/zhangsan", "v6", clientv3.WithPrevKV())
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println("global version is", putResp.Header.Revision)
    if putResp.PrevKv != nil && string(putResp.PrevKv.Value) != "" {
        fmt.Printf("preVal=%s, preVersion=%d\n",
            string(putResp.PrevKv.Value), // 上一个版本值
            putResp.PrevKv.Version,       // 上一个历史版本号
        )
    }

(2) 查询

  key:="job1"

  // ops为空时，只查询单个key
    ops := []clientv3.OpOption{
        // 前缀查询
        //clientv3.WithPrefix(),

        // 范围查询
        //clientv3.WithRange("/job4"),

        // 查询结果排序，查询结果可以按Key、Value、CreateRevision(key创建的版本)、Version(key历史版本数量)、ModRevision(key对应最新版本)排序，可以升序(Ascend)或降序(Descend)。
        //clientv3.WithSort(clientv3.SortByVersion, clientv3.SortDescend),

        // 获取数量
    //clientv3.WithCountOnly(), // 只返回数量，不返回kv，可以判断指定key是否存在，可以用来统计key数量

        // 实现翻页功能
        //clientv3.WithFromKey(),
        //clientv3.WithLimit(3),
    }

    getResp, err := cli.KV.Get(context.Background(), key, ops...)
    if err != nil {
        fmt.Println(err)
        return
    }
    for i, v := range getResp.Kvs {
        fmt.Printf("(%d) %s -> %s, historySize=%d, createRev=%d, modRev=%d,headRev=%d\n",
            i,
            string(v.Key),
            string(v.Value),
            v.Version,               // 本key一共有多少个历史版本
            v.CreateRevision,        // 第一次创建所在版本号
            v.ModRevision,           // 最新更改版本号
            getResp.Header.Revision, // 全局最大版本号
        )
    }

(3) 删除

  // ops为空时，只删除个key
    ops := []clientv3.OpOption{
    // 删除匹配前缀所有的key
  //clientv3.WithPrefix(),
  }

    delResp, err := cli.KV.Delete(context.Background(), key, ops...)
    if err != nil {
        fmt.Println(err)
        return
  }
  
    fmt.Sprintln("deleted count: ", delResp.Deleted) // 删除了多少个key
    fmt.Sprintln("PrevKvs : ", delResp.PrevKvs)      // 删除了哪些key
  }

6.4 事务txn

    key := "num"

    _, err := cli.KV.Put(context.Background(), key, "05")
    if err != nil {
        panic(err)
    }

    // 链式操作
    txnResp, err := cli.KV.Txn(context.Background()).
        If(clientv3.Compare(clientv3.Value(key), ">", "10")). // 条件，可以多个clientv3.Cmp
        Then(clientv3.OpPut(key, "10")).                      // 所有条件成立，执行的操作，可以多个clientv3.Op
        Else(clientv3.OpPut(key, "0")).                       // 至少一个条件不成立，执行的操作，可以多个clientv3.Op
        Commit()
    if err != nil {
        panic(err)
    }

    if txnResp.Succeeded {
        fmt.Println("txn success")
    } else {
        fmt.Println("txn failed")
    }

6.5 租约lease

(1) 生成租约

    // 生成一个新的租约(单位秒)
    grantResp, err := cli.Grant(context.Background(), 300)
    if err != nil {
        panic(err)
    }
    fmt.Println("lease id is", grantResp.ID, "or", strconv.FormatInt(int64(grantResp.ID), 16))

    // 把新的租约绑定到key，租约过期后自动删除
    _, err = cli.KV.Put(context.Background(), "foo", "bar", clientv3.WithLease(grantResp.ID))
    if err != nil {
        panic(err)
    }

    // 只按原来租约时间续签一次
    kao, kaerr := cli.KeepAliveOnce(context.Background(), grantResp.ID)
    if kaerr != nil {
        panic(err)
    }
    fmt.Println("ttl:", kao.TTL)

    // 持续续签租约，直到程序运行结束
    kaResp, err := cli.KeepAlive(context.Background(), grantResp.ID)
    if err != nil {
        panic(err)
    }
    ka := <-kaResp // 通过管道获取返回信息，缓冲管道
    fmt.Println(ka.ID, ka.TTL)

    // 撤销租约，会使绑定租约的key立即删除
    time.Sleep(time.Second * 30)
    _, err = cli.Revoke(context.Background(), grantResp.ID)
    if err != nil {
        panic(err)
    }
  fmt.Printf("revoke lease(%d) success", grantResp.ID)
  
    // 查看租约还有多久过期，从而知道绑定的key什么时候过期
    ttlResp, err := cli.TimeToLive(context.Background(), grantResp.ID, clientv3.WithAttachedKeys())
    if err != nil {
        panic(err)
    }
    fmt.Println(
        ttlResp.GrantedTTL, // 租约总时长(秒)
        ttlResp.TTL,        // 剩余时长(秒)
        string(bytes.Join(ttlResp.Keys, []byte(","))), // 绑定的key
    )

6.7 监听watch

watch监听put和delete事件，可以使用ctx取消监听。

    // 监听一个key
    go func() {
        wChan := cli.Watch(context.Background(), "/user/zhangsan") // 对key监听
        for wResp := range wChan {                                 // 监听key值是否有变化(一直阻塞)，也可以使用for select来获取管道信息，结合ctx来控制是否退出监听
            for _, event := range wResp.Events { // 查看事件，根据事件类型(修改、删除)做出相应处理
                fmt.Printf("%s %q : %q\n", event.Type, event.Kv.Key, event.Kv.Value)
            }
        }
    }()

    // 监听key前缀
    go func() {
        ctx, _ := context.WithCancel(context.Background())
        wChan := cli.Watch(ctx, "/user/", clientv3.WithPrefix()) // 对适配前缀所有key监听
        for {
            select {
            case wResp := <-wChan:
                for _, event := range wResp.Events { // 查看事件，根据事件类型(修改、删除)做出相应处理
                    fmt.Printf("%s %q : %q\n", event.Type, event.Kv.Key, event.Kv.Value)
                }
            case <-ctx.Done():
                fmt.Println(ctx.Err())
                return
            }
        }
    }()

    // 不管key有没有更新，etcd会每个10分钟发送一次通知事件
    go func() {
        wChan := cli.Watch(context.Background(), "foo", clientv3.WithProgressNotify())
        for wResp := range wChan {
            for _, event := range wResp.Events {
                fmt.Printf("%s %q : %q\n", event.Type, event.Kv.Key, event.Kv.Value)
            }
            fmt.Printf("wResp.Header.Revision: %d\n", wResp.Header.Revision)
            fmt.Println("wResp.IsProgressNotify:", wResp.IsProgressNotify())
        }
    }()

    // key范围监听，不包括最大值
    go func() {
        wChan := cli.Watch(context.Background(), "job1", clientv3.WithRange("job3"))
        for wResp := range wChan {
            for _, event := range wResp.Events {
                fmt.Printf("%s %q : %q\n", event.Type, event.Kv.Key, event.Kv.Value)
            }
        }
    }()

6.8 实现分布式锁示例

package main

import (
    "context"
    "fmt"
    "time"

    "go.etcd.io/etcd/clientv3"
)

func main() {
    cli, err := InitETCD([]string{"192.168.3.5:2379"})
    if err != nil {
        panic(err)
    }

    handle := func() {
        fmt.Println("处理业务中...")
        time.Sleep(10 * time.Second)
        fmt.Println("处理业务完毕")
    }

    DistributedLock(cli, handle)
}

// InitETCD 连接etcd
func InitETCD(endPoints []string) (*clientv3.Client, error) {
    // 配置
    config := clientv3.Config{
        Endpoints:   endPoints,
        DialTimeout: 10 * time.Second,
    }

    // 连接
    return clientv3.New(config)
}

// DistributedLock 分布式锁
func DistributedLock(cli *clientv3.Client, handle func()) {
    // 生成一个新的租约(单位秒)
    grantResp, err := cli.Grant(context.Background(), 5)
    if err != nil {
        return
    }
    fmt.Println("new lease id is", grantResp.ID)

    ctx, cancelFunc := context.WithCancel(context.Background())
    // 处理完业务后结束租约
    defer func() {
        cli.Revoke(context.Background(), grantResp.ID)
        cancelFunc()
    }()

    // 持续续租，直到处理完业务
    err = keepAlive(ctx, cli, grantResp.ID)
    if err != nil {
        fmt.Println(err)
        return
    }

    // 新建事务
    txn := cli.KV.Txn(context.Background())
    key := "/lock/mutex"
    // 判断key是否存在，不存在说明成功抢到锁
    txn.If(clientv3.Compare(clientv3.CreateRevision(key), "=", 0)).
        Then(clientv3.OpPut(key, "ok", clientv3.WithLease(grantResp.ID))). // 创建key并绑定租约
        Else(clientv3.OpGet(key))                                          // 否则抢锁失败
    txnResp, err := txn.Commit() // 提交事务
    if err != nil {
        fmt.Println(err)
        return
    }

    // 判断是否抢到了锁，true:抢锁成功，false:抢锁失败
    if !txnResp.Succeeded {
        fmt.Printf("锁(%s)已被占用:", key)
        return
    }

    // 处理业务
    handle()
}

// 持续续租
func keepAlive(ctx context.Context, cli *clientv3.Client, leaseID clientv3.LeaseID) error {
    // 自动续租
    keepRespChan, err := cli.KeepAlive(ctx, leaseID)
    if err != nil {
        return err
    }

    // 处理续约应答
    go func(ctx context.Context) {
        for {
            select {
            case _, ok := <-keepRespChan:
                if !ok {
                    return
                }
            case <-ctx.Done():
                return
            }
        }
    }(ctx)

    return nil
}

参考：

• etcd官方文档 https://etcd.io/docs/v3.4.0/
• etcd应用场景 https://www.jianshu.com/p/abedeea7044e

本文链接：https://zhuyasen.com/post/etcd.html，参与评论 »

1 网格交易历史来源

网格交易的思路来源于信息论之父香农，上世纪40年代的某一天，香农在黑板上给大家演示了他的投资理论：

在任何一个价位，用资金的50%买入资产作为起始仓位，当价格上涨一定幅度就卖出一部分仓位套现，当价格下跌一定幅度就买入一部分仓位补仓，保持仓位和现金的比例始终为50%:50%，香农始终采用了半仓的持仓方式，保持每年复利29%，直到50岁得了老年痴呆症，才没能延续辉煌。

2 网格策略

根据香农仓位和现金1:1交易思路拓展为n:1，n表示网格数量，1表示一份投资金额，把投资金额平均分布在n个网格上，随着行情在网格范围内波动，行情下跌时逐步加仓，行情上涨时逐步减仓，持仓会跟着行情动态变化，通过低买高卖赚取利润。

如下表一个10个格子的网格策略列表，价格排列为等比数列，每格投资金额一样，从表格中可以看出当前网格卖出数量和下一格买入数量是相同的(例如序号1的卖出数量0.265和序号2的买入数量0.265是一样的)，也就是低价买入，高价卖出相同数量仓位来赚取利润，如果行情在网格价格范围内振荡越频繁，收益就越高。

3 网格类型

3.1 普通网格交易

普通网格交易是一种动态调仓位的自动化交易策略，设定网格上限、下限和网格数量，根据网格上下限按一定方式(等比、等差)分为N个格，把总投资金额平均分散到每个格子，在低价买入高价卖出来赚取利润，如下图所示。

适用场景

只适合横盘振荡行情，不适合大涨或大跌行情，当行情上涨或下跌超过网格范围后，网格就会在等待状态，需要等到行情重新回到网格范围内才会交易。

优点

• 行情在网格价格范围内不需要判断行情方向就可以实现盈利。
• 启动网格后自动化交易。

缺点

• 相比持币待涨方式，资金利用率低，收益率也低。
• 行情大跌的时候很快满仓造成亏损比较大，行情大涨时很快清仓完，导致盈利低下。
• 需要使用者判断当前行情是否在心理上的中低价位，如果不挑选时刻盲目进场，入场时行情价格刚好在高位，很容易造成亏损。

3.2 趋势网格交易

趋势网格是在普通网格交易基础上，添加网格自动跟随行情往上移动功能，以入场价为起点，当行情上涨超过网格最大值时，自动生成新网格，使得网格可以继续交易赚取利润，不需要人工干预，当行情下跌超过当前网格最小值后，网格会在等待状态，等到行情回到当前网格范围内才可以继续交易，如下图所示。

适用场景

只适合振荡上涨行情，因此需要用户选择恰当时机结束趋势网格来实现利润。因为行情持续下跌时的浮动盈亏会抵消到原来振荡上涨时赚取的利润，甚至亏损。

优点

• 行情在振荡或上涨情况下都可以实现盈利。
• 启动网格后自动化交易。

缺点

• 相比持币待涨方式，资金利用率低，收益率也低。
• 行情大跌的时候很快满仓造成亏损比较大。
• 行情下跌超出当前网格范围，造成网格会在等待状态，无法继续交易。
• 需要使用者判断当前行情是否在心理上的中低价位，如果不挑选时刻盲目进场，进场时行情价格刚好在高位，很容易造成亏损。
• 需要使用者判断当前行情是否在心理上为高位，结束网格来实现利润。

3.3 无限网格

无限网格和趋势网格交易类似，网格只有下限，没有上限，只需设置网格下限值和每格收益率，生成一个网格，当行情超过网格最大值时，买入一定仓位，自动挂更高的卖单，只要行情一直涨，都会跟随行情上涨下去。

适用场景

无限网格适合波动比较大、整体上涨的行情，适合连续执行半年以上。设置心理底价后直接进场，当行情下跌后分批抄底，当行情上涨至少也可以赚取利润。

优点

• 在波动比较大的行情下也不容易进入等待状态，可以持续套利盈利。
• 设置好参数运行后，不需要再关注行情，让其长期自动交易。

缺点

• 相对于网格交易，资金利用率更低，收益率也更低。
• 需要使用者判断当前行情是否在心理上的中低价位，如果不挑选时刻盲目进场，进场时行情价格刚好在高位，很容易造成亏损。

4 计算特定条件的最优网格

网格最理想情况是碰到反复振荡行情，遇到振荡行情，如果网格参数设置不合理，同样无法获得收益，甚至亏损。如果设置网格数少，并且网格间隔太大，虽然每格收益率大，但受制于行情振荡幅度，交易机会很小，收益也会少；如果网格数比较多，并且网格间隔太小，虽然交易机会比较多，但每次低买高卖的利润都不够手续费，造成亏损。因此设置好的网格参数不是随便设置网格数量、最小价格和最大价格就可以有收益了，需要平衡每格收益率和交易机会，与投资金额、买卖最小金额、手续费、当前行情价格、目标收益率有关，根据已知条件抽象出一条计算最优网格参数题目，如下所示：

已知品种ethusdt的当前价格380，投资总金额totalSum=100，每次买入或卖出最小金额limitVolume=10，每次成功的买入或卖出订单手续费为0.1%，网格在低价买入，然后高价卖出称为一次套利arbitrage，套利减去买和卖手续费后得到利润profit，每格收益率profitRate=profit÷arbitrage×100%，要求profitRate>0.1%，计算出最优的网格参数：

• (1) 网格数量num，其中5<=num<=60；
• (2) 网格平均间距intervalPrice，网格价格间隔越小，在行情震荡时出现套利机会越多；
• (3) 最优网格对应的最低价格minPrice、最高价格maxPrice、网格价格分布序列。

注：profitRate越小，并且intervalPrice也越小时得到的网格参数认为最优。

根据已知条件计算得出最优网格参数如下：

• 网格数num: 10
• 网格最低价格minPrice: 370.88 USDT
• 网格最高价格maxPrice: 401.28 USDT
• 网格平均间距intervalPrice: 3.04 USDT

网格序列如下：

根据投入金额和每格收益率即可计算出网格参数(最小价格、最大价格、网格数)，通过程序方式计算出来的网格参数可以适合各种不同手续费的交易所，因此可以做到自动化生成网格策略的效果。

5 总结

普通网格交易、趋势网格、无限网格适应不同行情类型，各有优缺点，不能说哪种更好，如果行情在某个范围内频繁振荡，使用普通网格交易、趋势网格最适合，收益更高，如果行情长期出现大幅涨跌情况，选择无限网格更适合，无论哪种网格策略，选择进场的时机(行情在低位)非常重要。

世界上还没有完美的交易策略可以长期应对不可预测的行情，网格策略可以应对某种特定行情的一种交易策略，因为行情不可预测，通过广撒网方式去捕捉行情，网格交易需要人工判断哪条河有鱼(行情)，才能把网撒出去，不能随便撒网，因为撒网需要成本的，随便撒网大多数结果是竹篮打水一场空(亏损)。

本文链接：https://zhuyasen.com/post/gridStrategy.html，参与评论 »

go语言本身带有runtime/pprof包，使用pprof可以查看程序profile信息(例如cpu、内存、goroutine等)。

一个项目中可能有很多服务，这些服务部署在k8s集群或不同节点，如果想查看某个服务的profile信息(前提是开启profile功能)，通常需要找到该服务对应节点ip和端口，如果服务部署在k8s集群，可以通过端口映射、端口转发、ingress等方式获取服务的profile信息，有点麻烦，特别是服务多了之后，不容易管理和查看，为了方便管理，希望只需要知道服务名称就可以获取到对应服务的profile信息，不需要知道ip和端口，通过服务名称就可以查看该服务的profile信息。

具体实现步骤：

• (1) 使用自定义的路由(/goprofile/your-server-name)替换默认路由(/debug/pprof)；
• (2) 使用nginx反向代理，根据路由转发请求到不同服务，然后使用负载均衡器转发请求到nginx服务。

1 在服务程序中获取profile信息

无论是web服务还是非服务，都可以做成通过http获取服务的profile信息，如果你的服务是web服务，刚好使用了gin框架，只需添加简单的几行代码即可，具体示例如下：

package main

import (
    "github.com/gin-contrib/pprof"
    "github.com/gin-gonic/gin"
)

var enableProfile bool

func init() {
    flag.BoolVar(&enableProfile, "enableProfile", "", "is enable go profile")
    flag.Parse()
}

func main() {
  r := gin.Default()
  if enableProfile {
    // 使用服务名称替换默认路由
    pprof.Register(r,"/goprofile/"+"your-server-name")
  }
  r.Run(":10060")
}

如果程序非gin框架程序，也可以通过gin伪造一个web服务出来放到goroutine去执行即可，具体示例如下：

package main

import (
    "github.com/gin-contrib/pprof"
    "github.com/gin-gonic/gin"
)

var enableProfile bool

func init() {
    flag.BoolVar(&enableProfile, "enableProfile", "", "is enable go profile")
    flag.Parse()
}

func profile() {
  r := gin.Default()
  // 使用服务名称替换默认路由
  pprof.Register(r,"/goprofile/"+"your-server-name")
  r.Run(":10060")
}

func main() {
  if enableProfile {
    go profile()
  }
  
  // run your code
  select{}
}

启动服务时开启profile功能：./your-app -enableProfile=true，开启profile功能后，在浏览器打开 http://:10060/goprofile/your-server-name 可以查看profile信息。

2 使用nginx做路由转发

新建一个nginx配置default.conf，文件内容如下：

server {
    listen       80;
    server_name  localhost;
    #charset koi8-r;
    #access_log  logs/host.access.log  main;

    location / {
        root   html;
        index  index.html index.htm;
    }
    
    location /goprofile/your-server-name1 {
        proxy_pass http://your-server-name1.com:8080/goprofile/your-server-name1;
    }

    location /goprofile/your-server-name2 {
        proxy_pass http://your-server-name2.com:8081/goprofile/your-server-name2;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   html;
    }
}

把default.conf文件复制到/etc/nginx/conf.d/目录下，启动nginx服务，使用nginx代理方式可以通过服务名称访问对应profile信息。

使用反向代理遇到的301重定向问题，例如在浏览器访问http://xxx.com/abc，会重定向到http://xxx.com/abc/，也就是当请求URL后面没有/，nginx目录中没有对应的文件，就会自动进行 301并加上/。

解决方式：

在nginx的配置文件中，加上port_in_redirect off; 如果是nginx 版本号大于1.11.8，可以考虑使用absolute_redirect off;

注意： 在用chrome的时候，一定要先清除缓存在测试，chrome会自动将301缓存在本地。

3 在k8s获取golang程序的profile信息的完整示例

(1) golang程序开启profile功能

首先添加获取golang程序的profile信息功能，然后使用参数方式开启和关闭profile功能，默认是关闭状态，例如开启profile功能：./your-app -enableProfile

(2) 在k8s部署nginx代理

nginx配置文件go-profile-proxy-configmap.yml文件内容如下：

apiVersion: v1
kind: ConfigMap
metadata:
  name: go-profile-proxy-config
data:
  default.conf: |-
    server {
        listen       80;
        server_name  localhost;
        #charset koi8-r;
        #access_log  logs/host.access.log  main;

        location / {
            root   html;
            index  index.html index.htm;
        }
        
        location /goprofile/wq-account {
            proxy_pass http://wq-account-svc:80/goprofile/wq-account;
        }

        location /goprofile/wq-pcc {
            proxy_pass http://wq-pcc-svc:80/goprofile/wq-pcc;
        }

        location /goprofile/wq-monitor-msg-collect {
            proxy_pass http://wq-monitor-msg-collect-svc:80/goprofile/wq-monitor-msg-collect;
        }
        
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html;
        }
    }

部署nginx服务脚本文件go-profile-proxy-deployment.yml内容如下：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-profile-proxy-dm
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-profile-proxy
  template:
    metadata:
      name: go-profile-proxy-pod
      labels:
        app: go-profile-proxy
    spec:
      containers:
      - name: go-profile-proxy
        image: nginx:1.15
        imagePullPolicy: IfNotPresent
        ports:
        - name: app-port
          containerPort: 80
        volumeMounts:
        - name: go-profile-proxy-vl
          mountPath: /etc/nginx/conf.d/
          readOnly: true

      volumes:
      - name: go-profile-proxy-vl
        configMap:
          name: go-profile-proxy-config

暴露nginx服务端口，部署脚本go-profile-proxy-svc.yml文件内容如下：

apiVersion: v1
kind: Service
metadata:
  name: go-profile-proxy-svc
spec:
  selector:
    app: go-profile-proxy
  type: NodePort
  ports: 
  - name: app-svc-port
    port: 80
    targetPort: 80
    nodePort: 32280

在k8s启动nginx代理服务：

kubectl apply -f go-profile-proxy-configmap.yml
kubectl apply -f go-profile-proxy-deployment.yml
kubectl apply -f go-profile-proxy-svc.yml

在浏览器打开 http://:32280/goprofile/your-server-name 就可以查看profile信息了。

4 go程序性能分析

(1) 查看服务的prifile概况

例如wq-pcc服务已开启了profile功能，这里使用负载均衡器域名和端口http://xxxxxx.elb.ap-northeast-1.amazonaws.com:32280转发请求到nginx服务，如果想查看wq-pcc服务的profile信息，在浏览器打开http://xxxxxx.elb.ap-northeast-1.amazonaws.com:32280/goprofile/wq-pcc即可，如下图所示：

(2) 具体分析服务的性能

收集服务wq-pcc在40秒内的cpu和内存信息，在这段时间内进行暴力压测，尽量让cpu占用性能产生数据，如果不指定时间，默认收集30秒。

go tool pprof --seconds 40 http://xxxxxx.elb.ap-northeast-1.amazonaws.com:32280/goprofile/wq-pcc/profile
go tool pprof --seconds 40 http://xxxxxx.elb.ap-northeast-1.amazonaws.com:32280/goprofile/wq-pcc/heap

收集完毕后使用top或web命令查看信息详情，使用web命令要求本地安装Graphviz工具，如下图所示：

如果本地安装了FlameGraph和go-torch，可以查看火焰图，生成火焰图方法：

# 采集30秒的cpu数据
go-torch go-torch http://dev-k8s-server-b6a745217e8dd924.elb.ap-northeast-1.amazonaws.com:32280/goprofile/wq-pcc/profile -t 30
# 30s后go-torch完成采样，输出以下信息：Writing svg to torch.svg (torch.svg文件保存在安装路径$GOPATH/github.com/brendangregg/FlameGraph目录下)

在浏览器打开file:///Users/any/work/go/src/github.com/brendangregg/FlameGraph/torch.svg

火焰图的y轴表示cpu调用方法的先后，x轴表示在每个采样调用时间内，方法所占的时间百分比，越宽代表占据cpu时间越多。

在win10中无法生成svg，出现错误：flamegraph.pl: %1 is not a valid Win32 application，暂时未有解决方法，在mac或linux可以正常生成svg文件。

更多详细性能分析教程查看：https://blog.csdn.net/wangdenghui2005/article/details/99119941

本文链接：https://zhuyasen.com/post/goprofile.html，参与评论 »

1 代码格式化

go默认已经有了gofmt工具，但是建议使用goimport工具，这个在gofmt的基础上增加了自动删除和引入包，目前IDE基本都支持goimports，安装goimports：

go get golang.org/x/tools/cmd/goimports

对import的包进行分组管理，用换行符分割，而且标准库作为分组的第一组。如果你的包引入了三种类型的包，有标准库包、程序内部包、第三方包，建议采用如下方式进行组织你的包：

import (
    "fmt"
    "os"

    "kmg/a"
    "kmg/b"

    "code.google.com/a"
    "github.com/b"
)

在项目中不要使用相对路径引入包：

// 错误示例
import "../net"

// 正确的做法
import "github.com/repo/proj/src/net"

2 注释

代码注释有两种方式：

• 行注释：//
• 块注释：/* …… */

如果想在每个文件中的头部加上版权注释，需要在版权注释和package注释前面加一个空行，否则版权注释会作为package的注释，如下所示：

// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

/*
Package net provides a portable interface for network I/O, including
TCP/IP, UDP, domain name resolution, and Unix domain sockets.
......
*/
package net

注：使用//注释时，在//之后应该加一个空格。

package里导出的变量和函数前面必须写注释，如果不添加注释，golint检查无法通过，如下所示：

const (
    // StatusRunning 运行状态
    StatusRunning = 1
)

// Send 发送消息
func Send(content []byte){
    ...
}

3 一些大小的约定

• 单个文件代码行数建议不超过500行。
• 单个函数长度不超过100行。
• 函数两个要求：单一职责、要短小。
• 单行语句不能过长，如不能拆分需要分行写，一行最多120个字符。
• 函数中缩进嵌套必须小于等于3层，禁止出现以下这种锯齿形的函数，应通过尽早通过return等方法重构。

错误的示范：

if ... {
    if ... {
        if ... {
            
        } else {
            if ... {
                
            }
        }
    } else {
        
    }
}

• 保持函数内部实现的组织粒度是相近的。

建议把下面代码整理下：

func main() {
    initLog()
    
    //这一段代码的组织粒度，明显与其他的不均衡
    orm.DefaultTimeLoc = time.UTC
    sqlDriver := beego.AppConfig.String("sqldriver")
    dataSource := beego.AppConfig.String("datasource")
    modelregister.InitDataBase(sqlDriver, dataSource)
    
    Run()
}

改为：

 func main() {
    initLog()

    initORM()  //修改后，函数的组织粒度保持一致 

    Run()
}

4 命名规则

(1) 局部变量命名规则

局部变量名称一般遵循驼峰法，但遇到特有名词时，需要遵循以下规则：

• 如果变量为私有，且特有名词为首个单词，则使用小写，如apiClient。
• 其它情况都应当使用该名词原有的写法，如 APIClient、repoID、UserID。
• 错误示例：UrlArray，应该写成urlArray或者URLArray。

如果变量类型为bool类型，则名称应以Is、Has、Can或Allow开头，例如：isExist、hasConflict、canManage、allowGitHook。

在相对简单的环境(对象数量少、针对性强)中，可以将一些名称由完整单词简写为单个字母，例如user简写为u。

(2) 全局变量命名规则

全局变量名称一般遵循驼峰法，不要使用简写，做到见其名知其义。

(3) 包的命名规则

包的命名使用小写，尽量不要使用下划线或者混合大小写，包名应该用单数的形式，比如util、model，而不是utils、models。

(4) 函数命名规则

使用驼峰式命名，名字可以长但是得把功能描述清楚，函数名应当是动词或动词短语，如postPayment、deletePage、save等，也可以在名词前面加上get、set、is前缀。

(5) 结构体命名规则

结构体名应该是名词或名词短语，如Custome、WikiPage、Account、AddressParser，避免使用Manager、Processor、Data、Info这样的名称，结构体名称不应该是动词。

带mutex的struct的接收者receivers必须是带指针的接收者，具体示例：

type foo struct {
    mutex sync.Mutex
    ...
}

// 这里的接收者必须是指针，保证只对同一个锁操作，达到对同一个资源操作的互斥效果。
func (f *foo) Write (content []byte) error {
    f.mutex.Lock()
    defer f.mutex.Unlock()
    
    ...
}

(6) 接口命名规则

单个函数的接口名以er作为后缀，如Reader、Writer。接口的实现则去掉er。

type Reader interface {
    Read(p []byte) (n int, err error)
}

两个函数的接口名综合两个函数名，后面加er：

type WriteFlusher interface {
    Write([]byte) (int, error)
    Flush() error
}

三个以上函数的接口名，抽象这个接口的功能，类似于结构体名：

type Car interface {
    Start([]byte)
    Stop() error
    Recover()
}

(7) 函数接收者命名规则

Receiver的名称应该缩写，一般使用一个或者两个字符作为Receiver的名称，如下所示：

func (f foo) method1() {
    ...
}

func (f *foo) method2() {
    ...
}

(8) 常量命名

使用驼峰式命名，如果是枚举类型的常量，需要先创建相应类型，例如：

type Scheme string

const (
    HTTP  Scheme = "http"
    HTTPS Scheme = "https"
)

常量名称容易混淆的情况下，为了更好地区分枚举类型，可以使用完整的前缀：

type Status string

const (
    StatusRunning Status = 1
    StatusStop Status = 2
)

不要写类似于下面这种代码，如果没有注释，不知到1代表什么意义。

if status == 1 {
    ...
}

应该先定义常量，多个同类型的常量方便统一维护，应该改为：

const (
    // 运行状态
    StatusRunning = 1
)

if status == StatusRunning {
    ...
}

(9) 单元测试文件和函数命名

• 单元测试文件名命名必须在文件名后面加上_test，表示该文件为单元测试文件，例如example_test.go。
• 测试用例的函数名称必须以Test开头，例如TestExample。
• 如果测试的函数是某个对象的方法，命名方式为Test+对象名_方法名，例如TestAccount_Insert。

5 error处理

为了编写强壮的代码，不要忽略错误，也不要使用panic抛出异常，而是要处理每一个错误，尽管代码写起来可能有些繁琐。

error处理不要写成下面这种形式，一旦有错误发生，尽可能return返回。

if err != nil {
    // error handling
} else {
    // normal code
}

而是写成下面这种形式：

if err != nil {
    // 如果是最顶层函数，处理错误。
    // 如果不是最顶层函数，可以在原来错误基础上添加新的错误说明，然后返回。
    return
}

// normal code

error的错误描述如果是英文必须为小写，不需要标点结尾。

go语言自带的包没有打印堆栈信息，多级错误返回情况下，比较难以判断返回错误的根因是在哪一个环节产生的，使用 github.com/pkg/errors 可以包装错误信息，如下所示：

package main

import (
    "fmt"
    "io/ioutil"

    "github.com/pkg/errors"
)

func main() {
    err := test1("hello.txt")
    if err != nil {
        // 无打印堆栈信息
        fmt.Println("1", err)

        // 只获取根因(无包装信息)
        fmt.Println("2", errors.Cause(err))

        // 使用%+v打印堆栈信息
        fmt.Printf("3 %+v\n", err)
        return
    }
}

func test1(file string) error {
    if err := test2(file); err != nil {
        // 因为下层错误已经包装过数据，无需重复包装
        return err
    }
    return nil
}

func test2(file string) error {
    content, err := ioutil.ReadFile(file)
    if err != nil {
        // 把错误的根因和消息包装后返回。
        return errors.Wrap(err, "read file error")
    }

    fmt.Println(string(content))

    return nil
}

6 string和slice

(1) 判断字符串为空

不要使用：

if len(str) == 0 {
    ...
}

而是使用：

if str == "" {
    ...
}

(2) 判断slice为非空

不要使用：

if slice != nil && len(slice) > 0 {
    ...
}

而是使用：

if len(slice) > 0 {
    ...
}

(3) byte/string slice的相等性比较

不要使用：

bytes.Compare(s1, s2) == 0
bytes.Compare(s1, s2) != 0

而是使用：

bytes.Equal(s1, s2) == 0
bytes.Equal(s1, s2) != 0

(4) 检测是否包含字串

不要使用 strings.IndexRune(s1, ‘x’) > -1及其类似的方法IndexAny、Index检查字符串包含， 而是使用strings.ContainsRune、strings.ContainsAny、strings.Contains来检查。

(5) 复制slice

不要使用遍历方式：

var b1, b2 []byte
for i, v := range b1 { 
    b2[i] = v
}
或
for i := range b1 { 
    b2[i] = b1[i]
}

而是使用：

copy(b2, b1)

(6) 把一个slice追加到另一个slice后面

不要使用遍历方式：

var a, b []int
for _, v := range a {
    b = append(b, v)
}

而是使用：

var a, b []int
b = append(b, a...)

7 布尔值判断

判断真假不要使用：

if b == true {
    ...
}
if b == false {
    ...
}

而是使用：

if b {
    ...
}
if !b {
    ...
}

8 参数传递

• 参数比较多时(7个以上)，建议把参数放到结构体里，通过结构体传参。
• 对于大量数据的struct使用指针传参。
• 对于map、slice、chan这些参数不需要传递指针，因为map、slice、chan是引用类型。

9 闭包使用

在循环或者goroutine中使用闭包，必须使用显式的变量调用。

典型的闭包错误使用方式：

func main() {
    var wg sync.WaitGroup
    wg.Add(5)
    for i := 0; i < 5; i++ {
        go func() {
            fmt.Println(i)
            wg.Done()
        }()
    }
    wg.Wait()
}

// 执行结果是55555，这显然不是我们想要的结果(01234)

正确的使用方式：

func main() {
    var wg sync.WaitGroup
    wg.Add(5)
    for i := 0; i < 5; i++ {
        // 显式传参进去
        go func(j int) {
            fmt.Println(j)
            wg.Done()
        }(i)
    }
    wg.Wait()
}

10 单元测试

(1) 无依赖的功能测试

单元测试的原则，就是测试的函数方法，不要受到所依赖环境的影响，比如网络访问等。

以下面一个简单的计算器代码为例：

package calculator

import (
    "fmt"
    "strconv"
)

const (
    ErrorDivision = "error: the dividend cannot be 0."
    ErrorOp       = "errorr: unknown op type, only support operations +-*/"
)

type Calculator struct {
    x1 int
    x2 int
    op string
}

func (c *Calculator) String() string {
    return fmt.Sprintf("%d%s%d=", c.x1, c.op, c.x2)
}

// Run 加减乘除计算
func (c *Calculator) Run() string {
    switch c.op {
    case "+":
        return strconv.Itoa(c.x1 + c.x2)
    case "-":
        return strconv.Itoa(c.x1 - c.x2)
    case "*":
        return strconv.Itoa(c.x1 * c.x2)
    case "/":
        if c.x2 == 0 {
            return ErrorDivision
        }
        return strconv.Itoa(c.x1 / c.x2)
    default:
        return ErrorOp
    }
}

测试代码：

package calculator

import (
    "reflect"
    "testing"

    "github.com/google/go-cmp/cmp"
)

// 测试示例1，有可能会这样写测试，逐个实例化后判断
func TestCalculator_Run1(t *testing.T) {
    got := (&Calculator{10, 2, "+"}).Run()
    expected := "12"
    if got != expected {
        t.Errorf("got: %v, expected: %v", got, expected)
    }

    got = (&Calculator{10, 2, "-"}).Run()
    expected = "8"
    if got != expected {
        t.Errorf("got: %v, expected: %v", got, expected)
    }

    got = (&Calculator{10, 2, "*"}).Run()
    expected = "20"
    if got != expected {
        t.Errorf("got: %v, expected: %v", got, expected)
    }

    got = (&Calculator{10, 2, "/"}).Run()
    expected = "5"
    if got != expected {
        t.Errorf("got: %v, expected: %v", got, expected)
    }
}

// 测试示例2，第1种测试太啰嗦了，可以这样优化，看起来更简洁
func TestCalculator_Run2(t *testing.T) {
    // 列举测试数据
    tests := []struct {
        input    *Calculator
        expected string
    }{
        {&Calculator{10, 2, "+"}, "12"},
        {&Calculator{10, 2, "-"}, "8"},
        {&Calculator{10, 2, "*"}, "20"},
        {&Calculator{10, 2, "/"}, "5"},
        {&Calculator{10, 0, "/"}, ErrorDivision},
        {&Calculator{10, 2, "$"}, ErrorOp},
    }

    // 判断
    for _, v := range tests {
        got := v.input.Run()
        expected := v.expected
        if !reflect.DeepEqual(got, expected) {
            t.Errorf("got: %v, expected: %v", got, expected)
        }
    }
}

// 测试示例3，第2种测试写法虽然很简洁，但是当某个输入判断不通过时，而且测试数据多的时候，不好区分是哪个输入测试失败，可以再优化一下
func TestCalculator_Run3(t *testing.T) {
    // 列举测试数据
    tests := map[string]struct {
        input    *Calculator
        expected string
    }{
        "加法":    {&Calculator{10, 2, "+"}, "12"},
        "减法":    {&Calculator{10, 2, "-"}, "8"},
        "乘法":    {&Calculator{10, 2, "*"}, "20"},
        "除法":    {&Calculator{10, 2, "/"}, "5"},
        "被除数为0": {&Calculator{10, 0, "/"}, ErrorDivision},
        "非法操作符": {&Calculator{10, 2, "$"}, ErrorOp},
    }

    // 判断
    for key, v := range tests {
        got := v.input.Run()
        expected := v.expected
        if !reflect.DeepEqual(got, expected) {
            t.Errorf("%s: got: %v, expected: %v", key, got, expected)
        }
    }
}

// 测试示例4，第3种测试方法可以很快定位哪个输入测试失败，如果比较对象的元素很多的时候，虽然最后可以判断出结果不一样，
// 但是不一样在哪里，没有指出来，所有引入一个强大的比较对象的包go-cmp，类似git diff比较不同。
func TestCalculator_Run4(t *testing.T) {
    // 列举测试数据
    tests := map[string]struct {
        input    *Calculator
        expected string
    }{
        "加法":    {&Calculator{10, 2, "+"}, "12"},
        "减法":    {&Calculator{10, 2, "-"}, "8"},
        "乘法":    {&Calculator{10, 2, "*"}, "20"},
        "除法":    {&Calculator{10, 2, "/"}, "5"},
        "被除数为0": {&Calculator{10, 0, "/"}, ErrorDivision},
        "非法操作符": {&Calculator{10, 2, "$"}, ErrorOp},
    }

    // 判断
    for key, v := range tests {
        got := v.input.Run()
        expected := v.expected
        if result := cmp.Diff(got, expected); result != "" {
            t.Error(key, result)
        }
    }
}

(2) mock单元测试

在开发过程中往往需要配合单元测试，但是很多时候，单元测试需要依赖一些比较复杂的准备工作，比如需要依赖数据库环境，需要依赖网络环境，单元测试就变成了一件非常麻烦的事情。

mock对象就是为了解决依赖环境的问题，mock(模拟)对象能够模拟实际依赖对象的功能，同时又不需要非常复杂的准备工作，你需要做的，仅仅就是定义对象接口，然后实现它，再交给测试对象去使用。

安装go mock工具：

go get github.com/golang/mock/gomock
go get github.com/golang/mock/mockgen

在$GOPATH/src目录下新建一个项目hello，新建一个hello.go文件，内容如下：

package hello

type Talker interface {
    SayHello(word string) (response string)
}

新建persion.go文件，在文件里定义一个Persion结构体，并实现Talker接口，persion.go文件内容如下：

package hello

import "fmt"

type Person struct {
    name string
}

func NewPerson(name string) *Person {
    return &Person{
        name: name,
    }
}

func (p *Person) SayHello(name string) (word string) {
    return fmt.Sprintf("hello %s, welcome come to our shop, my name is %s", name, p.name)
}

假设商店有一个迎宾员，实现了Talker接口，迎宾员能够自动向客人说SayHello，新建shop.go文件内容如下：

package hello

type Shop struct {
    Usher Talker
}

func NewShop(t Talker) *Shop {
    return &Shop{
        Usher: t,
    }
}

func (c *Shop) Meeting(guestName string) string {
    return c.Usher.SayHello(guestName)
}

使用mockgen工具模拟Shop对象：

# 新建文件夹
mkdir mock_hello

# mock对象
mockgen -source=hello.go > mock_hello/mock_hello.go

使用这个mock对象，新建一个测试文件shop_test.go文件：

package hello

import (
    "testing"
    "hello/mock_hello"

    "github.com/golang/mock/gomock"
)

func TestShop_Meeting(t *testing.T) {
    ctl := gomock.NewController(t)
    mock_talker := mock_hello.NewMockTalker(ctl)
    mock_talker.EXPECT().SayHello(gomock.Eq("张三")).Return("你好张三，欢迎光临。")

    shop := NewShop(mock_talker)
    t.Log(shop.Meeting("张三"))
    //t.Log(shop.Meeting("李四"))
}

mock对象的SayHello可以接受的参数有gomock.Eq(x interface{})和gomock.Any()，前一个要求测试参数必须相等，第二个允许传入任意参数。

11 README文件

每个文件夹下都应该有一个README文件，该文件是对当前目录下所有文件的一个概述和主要方法描述，并给出一些相应的链接地址，包含代码所在地、引用文档所在地、API文档所在地。

README文件不仅是对自己代码的一个梳理，更是让别人在接手你的代码时能帮助快速上手的有效资料。所以每一个写好README文档的程序员绝对都是一个负责任的好程序员。

12 合理规划项目的目录

合理规划目录，一个目录中只包含一个包(实现一个模块的功能)，如果模块功能复杂考虑拆分子模块，或者拆分目录。

不要把不同功能模块放到一个包下：

project
├─  config.go
├─  controller.go
├─  filter.go
├─  flash.go
└─  log.go

而是把各个模块功能分到不同目录：

project  
├─cache  
│  │  cache.go  
│  │  conv.go  
│  │        
│  └─redis  
│          redis.go  
├─config  
│  │  config.go  
│  │  fake.go  
│  │  ini.go  
│  └─yaml  
│     yaml.go  
└─log  
      conn.go  
      console.go  
      log.go  

13 channel和goroutine

(1) channel

在任何情况下，不要在读取channel数据端关闭channel，因为发送端在不知情况下继续发送数据到该channel时会造成panic。要停止使用channel正确做法是在channel发送端关闭，接收端可以检测到channel是否已关闭。

关于使用写入channel超时处理，有可能会下面这样写：

ticker := time.NewTicker(10 * time.Second)
defer ticker.Stop()

for{
    ...
    
    select {
    case dataChannel <- msg:
    case <-ticker.C:
        // 超时处理
    }
}

上面这样会有个小问题，当写入的channel和超时的channel同时触发的时候(当然这个情况概率是比较小的)，select会随机选择执行一个分支，如果select选择了触发超时分支，如果处理不当会造成该数据缺失了，为了避免这个问题，做一些修改，如下面代码所示：

ticker := time.NewTicker(10 * time.Second)
defer ticker.Stop()

for{
    ...
    
    select {
    case dataChannel <- msg:
    default: // forbid block
    }
    
    select {
    case <-ticker.C:
        // 超时处理
    default: // forbid block
    }
}

(2) goroutine

如果启动的goroutine是用来做任务的，建议要写成可手动结束的goroutine，防止goroutine泄漏：

func worker(ctx context.Context, jobChan <-chan Job) {
    select {
    case job <- jobChan:
        Process(job)
    case <-ctx.Done():
        // 结束worker
        return
    }
}

如果不受限制的启动新goroutine，有可能会消耗完系统资源，建议使用goroutine池，使用有限的goroutine去做共同任务：

func workPool(ctx context.Context, jobChan chan Job) {
    for i := 0; i < 10000; i++ {
        go func() {
            worker(ctx, jobChan)
        }()
    }
}

参考：

• https://www.jianshu.com/p/ea7dfe61f705
• https://colobu.com/2017/02/07/write-idiomatic-golang-codes
• https://www.cnblogs.com/Survivalist/articles/10596110.html
• https://www.jb51.net/article/151392.html

本文链接：https://zhuyasen.com/post/devspec.html，参与评论 »

1 prometheus介绍

Prometheus是一个云原生计算基础项目，是一个系统和服务监控系统。它以给定的时间间隔从配置的目标收集指标，评估规则表达式，显示结果，并且如果观察到某些条件为真，则可以触发警报。

prometheus的主要区别特征是：

• 一个多维数据模型（时间序列由指标名称定义和设置键/值尺寸）
• 一个灵活的查询语言来利用这一维度
• 不依赖于分布式存储; 单个服务器节点是自治的
• 时间序列集合通过HTTP 上的拉模型进行
• 通过中间网关支持推送时间序列
• 通过服务发现或静态配置发现目标
• 多种图形和仪表板支持模式
• 支持分层和水平联合

2 prometheus安装

2.1 在docker安装prometheus

prometheus的配置文件prometheus.yml内容如下：

# my global config
global:
  scrape_interval:     15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

# Alertmanager configuration
alerting:
  alertmanagers:
  - static_configs:
    - targets:
      # - alertmanager:9093

# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: 'prometheus'

    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.

    static_configs:
    - targets: ['localhost:9090']

docker-compose.yml的内容如下：

version: "3"

services:
  prometheus:
    container_name: prometheus
    image: prom/prometheus:v2.11.1
    ports:
      - 9090:9090
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prom-data:/prometheus

volumes:
  prom-data:
    driver: local

启动prometheus：

docker-compose up -d

启动后在浏览器打开 http://192.168.101.88:9090 ，进入prometheus界面，只是没有数据而已。

2.2 采集node节点资源、容器信息、grafana数据可视化

一般不建议使用docker安装node-exporter，如果在docker安装node-exporter需要把节点信息映射到容器中。

prometheus的配置文件prometheus.yml内容如下：

# my global config
global:
  scrape_interval:     15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

# Alertmanager configuration
alerting:
  alertmanagers:
  - static_configs:
    - targets:
      #- alertmanager:9093

# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
rule_files:
  # - "first_rules.yml"
  #- "/etc/prometheus/rules/*.yml"

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: 'prometheus'
    static_configs:
    - targets: ['localhost:9090','cadvisor:8080','node-exporter:9100']

grafana的配置文件datasource.yaml内容如下：

# config file version
apiVersion: 1

# list of datasources that should be deleted from the database
deleteDatasources:
  - name: Graphite
    orgId: 1

datasources:
- name: Prometheus
  type: prometheus
  access: proxy
  isDefault: true
  url: http://prometheus:9090
  # don't use this in prod
  editable: true

docker-compose.yml文件内容如下：

version: "3"

services:
  prometheus:
    container_name: prometheus
    restart: always
    image: prom/prometheus:v2.11.1
    ports:
      - 9090:9090
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
    volumes:
      - ./config/prometheus.yml:/etc/prometheus/prometheus.yml
      - prom-data:/prometheus
    networks:
      - prom-net

  # node节点资源信息
  node-exporter:
    container_name: node-exporter
    restart: always
    image: prom/node-exporter:latest
    ports:
      - 9100:9100
    networks:
      - prom-net

  # 容器相关信息
  cadvisor:
    container_name: cadvisor
    restart: always
    image: google/cadvisor:latest
    ports:
      - 9101:8080
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:rw
      - /sys:/sys:ro
      - /var/lib/docker:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    networks:
      - prom-net

  # 数据可视化
  grafana:
    container_name: grafana
    image: grafana/grafana:6.2.5
    restart: always
    ports:
      - "3003:3000"
    volumes:
      - ./grafana/datasource.yaml:/etc/grafana/provisioning/datasources/datasource.yaml
      - grafana-data:/var/lib/grafana
    networks:
      - prom-net
    #environment:
    #  - GF_SECURITY_ADMIN_PASSWORD=123456

volumes:
  prom-data:
    driver: local
  grafana-data:
    driver: local

networks: 
  prom-net:
    driver: bridge

启动prometheus：

docker-compose up -d

启动后在浏览器打开 http://192.168.101.88:9090 ，进入prometheus界面，点击菜单status下Targets查看已经生效的Targets，如下图所示：

输入关键字prometheus_http_requests_total可以查询请求prometheus数据，如下图所示：

在浏览器打开 http://192.168.101.88:3003 ，默认登陆账号和密码都是admin，由于grafana配置文件已经设置了prometheus的数据源，不需要再添加数据源，如果没有配置数据源，先要添加数据源。

在浏览器打开 https://grafana.com/grafana/dashboards ，搜索相应的dashboard，使用grafana编号为1860和8919能够满足node-export(系统)的数据可视化了，使用grafana编号893(容器)能够满足cadvisor的数据可视化，具体使用方法进入grafana界面，鼠标移动到左边菜单栏的+号，选择import，输入编号1860，鼠标点击任意其它地方，选择prometheus数据源后导入即可，最后效果图如下：

grafana免密码登录设置

修改配置文件，允许匿名登录enabled = true，匿名登录角色改为Admin

[auth.anonymous]
# enable anonymous access
enabled = true

# specify role for unauthenticated users
org_role = Admin

3 PromQL的基础知识

指标(Metric)的通用格式：

<metric name>{<label name>=<label value>, ...}

指标的名称(metric name)可以反映被监控样本的含义（比如，http_requeststotal - 表示当前系统接收到的HTTP请求总量）。指标名称只能由ASCII字符、数字、下划线以及冒号组成并必须符合正则表达式[a-zA-Z:][a-zA-Z0-9_:]*。

标签(label)反映了当前样本的特征维度，通过这些维度Prometheus可以对样本数据进行过滤，聚合等。标签的名称只能由ASCII字符、数字以及下划线组成并满足正则表达式[a-zA-Z][a-zA-Z0-9]*。

其中以__作为前缀的标签，是系统保留的关键字，只能在系统内部使用。标签的值则可以包含任何Unicode编码的字符。在Prometheus的底层实现中指标名称实际上是以 __name__=的形式保存在数据库中的，因此以下两种方式均表示的同一条time-series：

api_http_requests_total{method="POST", handler="/messages"}

{__name__="api_http_requests_total"，method="POST", handler="/messages"}

示例：

node_cpu{cpu="cpu0",mode="idle"} 362812.7890625
node_load1 3.0703125

node_cpu和node_load1表明了当前指标的名称、大括号中的标签则反映了当前样本的一些特征和维度、浮点数则是该监控样本的具体值。

3.1 Metrics类型

Prometheus定义了4中不同的指标类型(metric type)：

• Counter（计数器）
• Gauge（仪表盘）
• Histogram（直方图）
• Summary（摘要）

在Exporter返回的样本数据中，其注释中也包含了该样本的类型。例如：

# HELP node_cpu Seconds the cpus spent in each mode.
# TYPE node_cpu counter
node_cpu{cpu="cpu0",mode="idle"} 362812.7890625

(1) Counter：只增不减的计数器

Counter类型的指标其工作方式和计数器一样，只增不减（除非系统发生重置）。常见的监控指标，如http_requests_total，node_cpu都是Counter类型的监控指标。 一般在定义Counter类型指标的名称时推荐使用_total作为后缀。

Counter是一个简单但有强大的工具，例如我们可以在应用程序中记录某些事件发生的次数，通过以时序的形式存储这些数据，我们可以轻松的了解该事件产生速率的变化。PromQL内置的聚合操作和函数可以用户对这些数据进行进一步的分析：

# 通过rate()函数获取HTTP请求量的增长率：
rate(http_requests_total[5m])

# 查询当前系统中，访问量前10的HTTP地址：
topk(10, http_requests_total)

(2) Gauge：可增可减的仪表盘

与Counter不同，Gauge类型的指标侧重于反应系统的当前状态。因此这类指标的样本数据可增可减。常见指标如：node_memory_MemFree（主机当前空闲的内容大小）、node_memory_MemAvailable（可用内存大小）都是Gauge类型的监控指标。

通过Gauge指标，用户可以直接查看系统的当前状态：node_memory_MemFree对于Gauge类型的监控指标，通过PromQL内置函数delta()可以获取样本在一段时间返回内的变化情况。还可以使用deriv()计算样本的线性回归模型，甚至是直接使用predict_linear()对数据的变化趋势进行预测。

# 计算CPU温度在两个小时内的差异：
delta(cpu_temp_celsius{host="zeus"}[2h])

# 预测系统磁盘空间在4个小时之后的剩余情况：
predict_linear(node_filesystem_free{job="node"}[1h], 4 * 3600)

(3) 使用Histogram和Summary分析数据分布情况

除了Counter和Gauge类型的监控指标以外，Prometheus还定义分别定义Histogram和Summary的指标类型。Histogram和Summary主用用于统计和分析样本的分布情况。

在大多数情况下人们都倾向于使用某些量化指标的平均值，例如CPU的平均使用率、页面的平均响应时间。这种方式的问题很明显，以系统API调用的平均响应时间为例：如果大多数API请求都维持在100ms的响应时间范围内，而个别请求的响应时间需要5s，那么就会导致某些WEB页面的响应时间落到中位数的情况，而这种现象被称为长尾问题。例如，统计延迟在0~10ms之间的请求数有多少而10~20ms之间的请求数又有多少，通过这种方式可以快速分析系统慢的原因。Histogram和Summary都是为了能够解决这样问题的存在，通过Histogram和Summary类型的监控指标，我们可以快速了解监控样本的分布情况。

# HELP prometheus_tsdb_wal_fsync_duration_seconds Duration of WAL fsync.
# TYPE prometheus_tsdb_wal_fsync_duration_seconds summary
prometheus_tsdb_wal_fsync_duration_seconds{quantile="0.5"} 0.012352463
prometheus_tsdb_wal_fsync_duration_seconds{quantile="0.9"} 0.014458005
prometheus_tsdb_wal_fsync_duration_seconds{quantile="0.99"} 0.017316173
prometheus_tsdb_wal_fsync_duration_seconds_sum 2.888716127000002
prometheus_tsdb_wal_fsync_duration_seconds_count 216

从上面的样本中可以得知当前Prometheus Server进行wal_fsync操作的总次数为216次，耗时2.888716127000002s。其中中位数（quantile=0.5）的耗时为0.012352463，9分位数（quantile=0.9）的耗时为0.014458005s。

3.4 PromQL基础

Prometheus通过指标名称（metrics name）以及对应的一组标签（labelset）唯一定义一条时间序列。指标名称反映了监控样本的基本标识，而label则在这个基本特征上为采集到的数据提供了多种特征维度。用户可以基于这些特征维度过滤，聚合，统计从而产生新的计算后的一条时间序列。

PromQL是Prometheus内置的数据查询语言，其提供对时间序列数据丰富的查询，聚合以及逻辑运算能力的支持。并且被广泛应用在Prometheus的日常应用当中，包括对数据查询、可视化、告警处理当中。可以这么说，PromQL是Prometheus所有应用场景的基础，理解和掌握PromQL是Prometheus入门的第一课。

(1) 查询时间序列

当Prometheus通过Exporter采集到相应的监控指标样本数据后，我们就可以通过PromQL对监控样本数据进行查询。

当我们直接使用监控指标名称查询时，可以查询该指标下的所有时间序列。如：

prometheus_http_requests_total
# 等价于
prometheus_http_requests_total{}

PromQL还支持用户根据时间序列的标签匹配模式来对时间序列进行过滤，目前主要支持两种匹配模式：完全匹配(=)和排除匹配(!=)。

通过使用label=value可以选择那些标签满足表达式定义的时间序列； 反之使用label!=value则可以根据标签匹配排除时间序列；

# 查询所有prometheus_http_requests_total时间序列中满足标签instance为localhost:9090的时间序列，则可以使用如下表达式：
prometheus_http_requests_total{instance="localhost:9090"}

# 反之使用instance!="localhost:9090"则可以排除这些时间序列：
prometheus_http_requests_total{instance!="localhost:9090"}

除了使用完全匹配的方式对时间序列进行过滤以外，PromQL还可以支持使用正则表达式作为匹配条件，多个表达式之间使用|进行分离：

使用label=~regx表示选择那些标签符合正则表达式定义的时间序列； 反之使用label!~regx进行排除；

# 如果想查询多个环节下的时间序列序列可以使用如下表达式：
http_requests_total{environment=~"staging|testing|development",method!="GET"}

(2) 范围查询

直接通过类似于PromQL表达式http_requests_total查询时间序列时，返回值中只会包含该时间序列中的最新的一个样本值，这样的返回结果我们称之为瞬时向量。而相应的这样的表达式称之为瞬时向量表达式。

而如果我们想过去一段时间范围内的样本数据时，我们则需要使用区间向量表达式。区间向量表达式和瞬时向量表达式之间的差异在于在区间向量表达式中我们需要定义时间选择的范围，时间范围通过时间范围选择器[]进行定义。例如，通过以下表达式可以选择最近5分钟内的所有样本数据：

http_requests_total{}[5m]

s - 秒
m - 分钟
h - 小时
d - 天
w - 周
y - 年

(3) 时间位移操作

在瞬时向量表达式或者区间向量表达式中，都是以当前时间为基准：

http_requests_total{} # 瞬时向量表达式，选择当前最新的数据
http_requests_total{}[5m] # 区间向量表达式，选择以当前时间为基准，5分钟内的数据
而如果我们想查询，5分钟前的瞬时样本数据，或昨天一天的区间内的样本数据呢? 这个时候我们就可以使用位移操作，位移操作的关键字为offset。

可以使用offset时间位移操作：

http_requests_total{} offset 5m
http_requests_total{}[1d] offset 1d

(4) 聚合操作

如果描述样本特征的标签(label)在并非唯一的情况下，通过PromQL查询数据，会返回多条满足这些特征维度的时间序列。而PromQL提供的聚合操作可以用来对这些时间序列进行处理，形成一条新的时间序列：

# 查询系统所有http请求的总量
sum(http_requests_total)

# 按照mode计算主机CPU的平均使用时间
avg(node_cpu) by (mode)

# 按照主机查询各个主机的CPU使用率
sum(sum(irate(node_cpu{mode!='idle'}[5m]))  / sum(irate(node_cpu[5m]))) by (instance)

(5) 合法的PromQL

http_requests_total # 合法
http_requests_total{} # 合法
{method="get"} # 合法
{__name__=~"http_requests_total"} # 合法
{__name__=~"node_disk_bytes_read|node_disk_bytes_written"} # 合法

而如下表达式，则不合法：
{job=~".*"} # 不合法

3.5 PromQL操作符

使用PromQL除了能够方便的按照查询和过滤时间序列以外，PromQL还支持丰富的操作符，用户可以使用这些操作符对进一步的对事件序列进行二次加工。这些操作符包括：数学运算符，逻辑运算符，布尔运算符等等

(1) 数学运算符

PromQL支持的所有数学运算符如下所示：

+ (加法)
- (减法)
* (乘法)
/ (除法)
% (求余)
^ (幂运算)

例如查看内存使用率：

(node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes

(2) 逻辑运行

目前，Prometheus支持以下布尔运算符如下：

== (相等)
!= (不相等)
> (大于)
< (小于)
>= (大于等于)
<= (小于等于)

例如查看内存使用率超过0.707的数据：

(node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes > 0.707

(3) 布尔运算

布尔运算符的默认行为是对时序数据进行过滤。而在其它的情况下我们可能需要的是真正的布尔结果。例如，只需要知道当前模块的HTTP请求量是否>=1000，如果大于等于1000则返回1（true）否则返回0（false）。这时可以使用bool修饰符改变布尔运算的默认行为。

prometheus_http_requests_total > bool 5000

(4) 使用集合运算符

使用瞬时向量表达式能够获取到一个包含多个时间序列的集合，我们称为瞬时向量。 通过集合运算，可以在两个瞬时向量与瞬时向量之间进行相应的集合操作。目前，Prometheus支持以下集合运算符：

and (并且)
or (或者)
unless (排除)
vector1 and vector2 会产生

(5) 操作符优先级

在PromQL操作符中优先级由高到低依次为：

^
*, /, %
+, -
==, !=, <=, <, >=, >
and, unless
or

3.6 PromQL聚合操作

Prometheus还提供了下列内置的聚合操作符，这些操作符作用域瞬时向量。可以将瞬时表达式返回的样本数据进行聚合，形成一个新的时间序列。

rate（时间内变化率，指定时间范围内所有数据点，适合缓慢变化的计数器）
irate（时间内变化率，指定时间范围内的最近两个数据点来算速率，适合快速变化的计数器）
sum (求和)
min (最小值)
max (最大值)
avg (平均值)
stddev (标准差)
stdvar (标准差异)
count (计数)
count_values (对value进行计数)
bottomk (后n条时序)
topk (前n条时序)
quantile (分布统计)

使用聚合操作的语法如下：

<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]

aggr-op: 聚合操作符
parameter: 参数(可选)
vector expression: 矢量式
without: 用于从计算结果中移除列举的标签(维度)，而保留其它标签
by: 向量中只保留列出的标签(维度)，其余标签则移除，必须指明标签列表

示例：

sum(prometheus_http_requests_total) without (instance)

等价于

sum(prometheus_http_requests_total) by (code,handler,job,method)

例如获取HTTP请求数前5位的时序样本数据：

topk(5, prometheus_http_requests_total)

例如找到当前样本数据中的中位数(0<v<1)：

quantile(0.5, prometheus_http_requests_total)

常用top10统计promQL语句示例：

# CPU 使用率 top10
label_replace(topk(10,(100 - avg(irate(node_cpu_seconds_total{mode="idle"}[5m]))by (instance) * 100)),"ip","$1","instance","(.*):.*")

# 内存使用率 top10
label_replace(topk(10,((1 - (node_memory_MemAvailable_bytes{} / (node_memory_MemTotal_bytes{})))* 100)),"ip","$1","instance","(.*):.*")

# 磁盘使用率 top10
label_replace(topk(10,((1 - (node_memory_MemAvailable_bytes{} / (node_memory_MemTotal_bytes{})))* 100))by (instance),"ip","$1","instance","(.*):.*")

# 磁盘IO总线利用率 top10
label_replace(topk(10,(avg(irate(node_disk_io_time_seconds_total{}[1m])) by(instance)* 100)),"ip","$1","instance","(.*):.*")

# 网络下载 top10
label_replace(topk(10,(sum(irate(node_network_receive_bytes_total{device!~"tap.*|veth.*|br.*|docker.*|virbr*|lo*"}[1m])*8) by (instance))),"ip","$1","instance","(.*):.*")

# 网络上传 top10
label_replace(topk(10,(sum(irate(node_network_transmit_bytes_total{device!~"tap.*|veth.*|br.*|docker.*|virbr*|lo*"}[1m])*8) by (instance))),"ip","$1","instance","(.*):.*")

# TCP 网络包错误率 top10
label_replace(topk(10,(avg(irate(node_netstat_Tcp_InErrs{}[1m])) by (instance) / avg(irate(node_netstat_Tcp_InSegs{}[1m])) by (instance))),"ip","$1","instance","(.*):.*")

# TCP 建立连接数 top10
label_replace(topk(10,avg(node_netstat_Tcp_CurrEstab{}) by (instance)) ,"ip","$1","instance","(.*):.*")

# TCP 等待断开连接 top10
label_replace(topk(10,avg(node_sockstat_TCP_tw{}) by (instance)) ,"ip","$1","instance","(.*):.*")

# 1分钟，5分钟，15分钟CPU平均负载 top10
label_replace(topk(10,avg(node_load1{}) by (instance)),"ip","$1","instance","(.*):.*")
label_replace(topk(10,avg(node_load5{}) by (instance)),"ip","$1","instance","(.*):.*")
label_replace(topk(10,avg(node_load15{}) by (instance)),"ip","$1","instance","(.*):.*")

# CPU 上下文切换平均次数 top10
label_replace(topk(10,avg(irate(node_context_switches_total{}[5m]))by (instance)),"ip","$1","instance","(.*):.*")

# swap 交换分区使用 top10
label_replace(topk(10,avg(node_memory_SwapTotal_bytes{}-node_memory_SwapFree_bytes{}) by (instance)) ,"ip","$1","instance","(.*):.*")

3.7 PromQL子查询

常用的子查询：

avg_over_time()  # 指定间隔内所有点的平均值。
min_over_time()  # 指定间隔中所有点的最小值。
max_over_time()  # 指定间隔内所有点的最大值。
sum_over_time()  # 指定时间间隔内所有值的总和。

avg_over_time 示例：

# 查询一天空闲空间的平均值
avg_over_time(node_filesystem_files_free[1d])

min_over_time 示例：

# 一天 空闲空间的最大值
max_over_time(node_filesystem_files_free[1d])

max_over_time 示例：

# 统计prometheus上/metrics页面在5分钟内区间向量的平均值的点，在1个小时中每个点的值。
max_over_time(rate(prometheus_http_requests_total[5m])[1h:1m])
 
# rate(prometheus_http_requests_total[5m])[1h:1m]  
# 它将五分钟的数据聚合成一个瞬时向量。
# [1h就像范围向量选择器一样，它定义了相对于查询求值时间的范围大小。
# :1m]要使用的间隔值。如果没有定义，它默认为全局计算区间。

sum_over_time 示例：

# 统计prometheus上/metrics页面在5分钟内区间向量值的点总和，在1个小时中每个点的值。
sum_over_time(rate(prometheus_http_requests_total[5m])[1h:1m])

请求数量总和：

# 最近10分钟请求数量总和
sum(max_over_time(prometheus_http_requests_total{}[10m]) - min_over_time(prometheus_http_requests_total{}[10m]))

3.8 逻辑运算（与、或、非）

and      # 与
or       # 或
unless   # 非

and 示例:

# 同时满足多个条件
node_filesystem_size_bytes{fstype!="tmpfs"} and node_filesystem_size_bytes != 0 and node_filesystem_size_bytes{mountpoint="/root-disk"}

or 示例:

# 至少满足一个条件
node_filesystem_avail_bytes > 200000 or node_filesystem_avail_bytes < 2500000

unless 示例:

# 忽略标签为{instance="192.168.1.21:9100",job="node"}数据
up{instance="192.168.1.20:9100",job="node"} unless up{instance="192.168.1.21:9100",job="node"}
 
# 当标签相同时输出数据
up{instance="192.168.1.20:9100",job="node"} unless up{instance="192.168.1.20:9100",job="node"}

3.9 4个黄金指标和USE方法

监控内容对应的Exporter：

(1) 4个黄金指标

Four Golden Signals是Google针对大量分布式监控的经验总结，4个黄金指标可以在服务级别帮助衡量终端用户体验、服务中断、业务影响等层面的问题，主要关注与以下四种类型的指标：延迟，通讯量，错误以及饱和度。

• 延迟：服务请求所需时间。

记录用户所有请求所需的时间，重点是要区分成功请求的延迟时间和失败请求的延迟时间。 例如在数据库或者其他关键祸端服务异常触发HTTP 500的情况下，用户也可能会很快得到请求失败的响应内容，如果不加区分计算这些请求的延迟，可能导致计算结果与实际结果产生巨大的差异。除此以外，在微服务中通常提倡“快速失败”，开发人员需要特别注意这些延迟较大的错误，因为这些缓慢的错误会明显影响系统的性能，因此追踪这些错误的延迟也是非常重要的。

• 通讯量：监控当前系统的流量，用于衡量服务的容量需求。

流量对于不同类型的系统而言可能代表不同的含义。例如，在HTTP REST API中, 流量通常是每秒HTTP请求数；

• 错误：监控当前系统所有发生的错误请求，衡量当前系统错误发生的速率。

对于失败而言有些是显式的(比如, HTTP 500错误)，而有些是隐式(比如，HTTP响应200，但实际业务流程依然是失败的)。

对于一些显式的错误如HTTP 500可以通过在负载均衡器(如Nginx)上进行捕获，而对于一些系统内部的异常，则可能需要直接从服务中添加钩子统计并进行获取。

• 饱和度：衡量当前服务的饱和度。

主要强调最能影响服务状态的受限制的资源。 例如，如果系统主要受内存影响，那就主要关注系统的内存状态，如果系统主要受限与磁盘I/O，那就主要观测磁盘I/O的状态。因为通常情况下，当这些资源达到饱和后，服务的性能会明显下降。同时还可以利用饱和度对系统做出预测，比如，“磁盘是否可能在4个小时候就满了”。

(2) RED方法

RED方法是Weave Cloud在基于Google的“4个黄金指标”的原则下结合Prometheus以及Kubernetes容器实践，细化和总结的方法论，特别适合于云原生应用以及微服务架构应用的监控和度量。主要关注以下三种关键指标：

• (请求)速率：服务每秒接收的请求数。
• (请求)错误：每秒失败的请求数。
• (请求)耗时：每个请求的耗时。

在“4大黄金信号”的原则下，RED方法可以有效的帮助用户衡量云原生以及微服务应用下的用户体验问题。

(3) USE方法

USE方法全称”Utilization Saturation and Errors Method”，主要用于分析系统性能问题，可以指导用户快速识别资源瓶颈以及错误的方法。正如USE方法的名字所表示的含义，USE方法主要关注与资源的：使用率(Utilization)、饱和度(Saturation)以及错误(Errors)。

• 使用率：关注系统资源的使用情况。 这里的资源主要包括但不限于：CPU，内存，网络，磁盘等等。100%的使用率通常是系统性能瓶颈的标志。
• 饱和度：例如CPU的平均运行排队长度，这里主要是针对资源的饱和度(注意，不同于4大黄金信号)。任何资源在某种程度上的饱和都可能导致系统性能的下降。
• 错误：错误计数。例如：“网卡在数据包传输过程中检测到的以太网网络冲突了14次”。

4 告警

告警能力在Prometheus的架构中被划分成两个独立的部分。通过在Prometheus中定义AlertRule（告警规则），Prometheus会周期性的对告警规则进行计算，如果满足告警触发条件就会向Alertmanager发送告警信息。

在Prometheus中一条告警规则主要由以下几部分组成：

• 告警名称：用户需要为告警规则命名，当然对于命名而言，需要能够直接表达出该告警的主要内容。
• 告警规则：告警规则实际上主要由PromQL进行定义，其实际意义是当表达式（PromQL）查询结果持续多长时间（During）后出发告警。

Alertmanager特性：

• 分组：分组机制可以将详细的告警信息合并成一个通知，避免一次性接受大量的告警通知，而无法对问题进行快速定位。
• 抑制：抑制是指当某一告警发出后，可以停止重复发送由此告警引发的其它告警的机制。
• 静默：提供了一个简单的机制可以快速根据标签对告警进行静默处理。如果接收到的告警符合静默的配置，Alertmanager则不会发送告警通知。

4.1 定义告警规则

一条典型的告警规则如下所示：

groups:
- name: example
  rules:
  - alert: HighErrorRate
    expr: job:request_latency_seconds:mean5m{job="myjob"} > 0.5
    for: 10m
    labels:
      severity: page
    annotations:
      summary: High request latency
      description: description info

• alert：告警规则的名称。
• expr：基于PromQL表达式告警触发条件，用于计算是否有时间序列满足该条件。
• for：评估等待时间，可选参数。用于表示只有当触发条件持续一段时间后才发送告警。在等待期间新产生告警的状态为pending。
• labels：自定义标签，允许用户指定要附加到告警上的一组附加标签。
• annotations：用于指定一组附加信息，比如用于描述告警详细信息的文字等，annotations的内容在告警产生时会一同作为参数发送到Alertmanager。

使用promtool工具检查告警语法：

promtool check rules /path/to/example.rules.yml

promtool工具下载地址： https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/

4.2 alertmanager配置详解

Alertmanager主要负责对Prometheus产生的告警进行统一处理，因此在Alertmanager配置中一般会包含以下几个主要部分：

• 全局配置（global）：用于定义一些全局的公共参数，如全局的SMTP配置，Slack配置等内容；
• 模板（templates）：用于定义告警通知时的模板，如HTML模板，邮件模板等；
• 告警路由（route）：根据标签匹配，确定当前告警应该如何处理；
• 接收人（receivers）：接收人是一个抽象的概念，它可以是一个邮箱也可以是微信，Slack或者Webhook等，接收人一般配合告警路由使用；
• 抑制规则（inhibit_rules）：合理设置抑制规则可以减少垃圾告警的产生

其完整配置格式如下：

global:
  [ resolve_timeout: <duration> | default = 5m ]
  [ smtp_from: <tmpl_string> ] 
  [ smtp_smarthost: <string> ] 
  [ smtp_hello: <string> | default = "localhost" ]
  [ smtp_auth_username: <string> ]
  [ smtp_auth_password: <secret> ]
  [ smtp_auth_identity: <string> ]
  [ smtp_auth_secret: <secret> ]
  [ smtp_require_tls: <bool> | default = true ]
  [ slack_api_url: <secret> ]
  [ victorops_api_key: <secret> ]
  [ victorops_api_url: <string> | default = "https://alert.victorops.com/integrations/generic/20131114/alert/" ]
  [ pagerduty_url: <string> | default = "https://events.pagerduty.com/v2/enqueue" ]
  [ opsgenie_api_key: <secret> ]
  [ opsgenie_api_url: <string> | default = "https://api.opsgenie.com/" ]
  [ hipchat_api_url: <string> | default = "https://api.hipchat.com/" ]
  [ hipchat_auth_token: <secret> ]
  [ wechat_api_url: <string> | default = "https://qyapi.weixin.qq.com/cgi-bin/" ]
  [ wechat_api_secret: <secret> ]
  [ wechat_api_corp_id: <string> ]
  [ http_config: <http_config> ]

templates:
  [ - <filepath> ... ]

route: <route>

receivers:
  - <receiver> ...

inhibit_rules:
  [ - <inhibit_rule> ... ]

在全局配置中需要注意的是resolve_timeout，该参数定义了当Alertmanager持续多长时间未接收到告警后标记告警状态为resolved（已解决）。该参数的定义可能会影响到告警恢复通知的接收时间，读者可根据自己的实际场景进行定义，其默认值为5分钟。

(1) route告警路由

alertmanager配置中的route是基于标签的告警路由，对于不同级别的告警，我们可能会有不同的处理方式，在route中可以定义更多的子Route，这些Route通过标签匹配告警的处理方式，告警的匹配有两种方式可以选择：

• 方式一：基于字符串验证，通过设置match规则判断当前告警中是否存在标签labelname并且其值等于labelvalue。
• 方式二：基于正则表达式，通过设置match_re验证当前告警标签的值是否满足正则表达式的内容。

alertmanager配置示例如下：

route:
  receiver: 'default-receiver'
  group_by: [cluster, alertname]
  group_wait: 30s
  group_interval: 10m
  repeat_interval: 1h
  
  routes:
  - receiver: 'database-pager'
    # 这里没有group_by，继承顶级的group_by
    group_wait: 10s
    match_re:
      service: mysql|cassandra
  - receiver: 'frontend-pager'
    group_by: [product, environment]
    match:
      team: frontend

使用命令检查告警规则是否合法

promtool check rules /path/to/example.rules.yml

(2) receiver告警接收器发送通知

每一个receiver具有一个全局唯一的名称，并且对应一个或者多个通知方式：

name: <string>
email_configs:
  [ - <email_config>, ... ]
webhook_configs:
  [ - <webhook_config>, ... ]
hipchat_configs:
  [ - <hipchat_config>, ... ]
pagerduty_configs:
  [ - <pagerduty_config>, ... ]
pushover_configs:
  [ - <pushover_config>, ... ]
slack_configs:
  [ - <slack_config>, ... ]
opsgenie_configs:
  [ - <opsgenie_config>, ... ]
victorops_configs:
  [ - <victorops_config>, ... ]

目前官方内置的第三方通知集成包括：邮件、 即时通讯软件（如Slack、Hipchat）、移动应用消息推送(如Pushover)和自动化运维工具（例如：Pagerduty、Opsgenie、Victorops）。Alertmanager的通知方式中还可以支持Webhook，通过这种方式开发者可以实现更多个性化的扩展支持。

4.3 告警发钉钉实例

如果只是告警，不把告警消息发出去，不需要安装alertmanager和prometheus-webhook-dingtalk服务，编写告警规则，然后在prometheus配置中导入告警规则文件即可。

rule_files:
  # - "first_rules.yml"
  - "/etc/prometheus/rules/*.yml"

然后在浏览器访问 http://192.168.101.88:9090/alerts 可以看到有没有告警消息。

为了实现告警发钉钉消息，需要安装alertmanager和prometheus-webhook-dingtalk两个服务，下面是一个在docker上实现prometheus采集和告警发钉钉脚本。

(1) 添加告警规则配置，./rules/hoststats-alert.yml文件内容如下：

groups:
- name: hostStatsAlert
  rules:
  - alert: hostCpuUsageAlert
    expr: sum(avg without (cpu)(irate(node_cpu_seconds_total{mode!='idle'}[5m]))) by (instance) > 0.5
    for: 1m
    labels:
      severity: page
    annotations:
      summary: "Instance {{ $labels.instance }} CPU usgae high"
      description: "{{ $labels.instance }} CPU usage above 50% (current value: {{ $value }})"
  - alert: hostMemUsageAlert
    expr: (node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes > 0.8
    for: 1m
    labels:
      severity: critical
    annotations:
      summary: "Instance {{ $labels.instance }} MEM usgae high"
      description: "{{ $labels.instance }} MEM usage above 80% (current value: {{ $value }})"

(2) 添加alertmanager配置，文件./config/alertmanager.yml内容如下：

global:
  resolve_timeout: 5m

route:
  group_by: ['alertname']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 1h
  receiver: 'dingding-webhook1'
  routes:
    - match:
        severity: critical
      receiver: dingding-webhook1
    - match:
        severity: page
      receiver: dingding-webhook2

receivers:
  # 对应prometheus-webhook-dingtalk服务监听地址，改服务启动时需要添加webhook1、webhook2对应的钉钉地址参数。
- name: dingding-webhook1
  webhook_configs:
  - url: http://prometheus-webhook-dingtalk:8060/dingtalk/webhook1/send 
- name: dingding-webhook2
  webhook_configs:
  - url: http://prometheus-webhook-dingtalk:8060/dingtalk/webhook2/send

(3) 修改prometheus配置，添加规则文件和报警管理器，文件./config/prometheus.yml的内容如下：

# my global config
global:
  scrape_interval:     15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

# Alertmanager configuration
alerting:
  alertmanagers:
  - static_configs:
    - targets:
      - alertmanager:9093

# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
rule_files:
  # - "first_rules.yml"
  - "/etc/prometheus/rules/*.yml"

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: 'prometheus'
    static_configs:
    - targets: ['localhost:9090','cadvisor:8080','node-exporter:9100']

修改docker-compose.yml配置，添加alertmanager和prometheus-webhook-dingtalk服务，docker-compose.yml文件内容如下：

version: "3"

services:
  prometheus:
    container_name: prometheus
    restart: always
    image: prom/prometheus:v2.11.1
    ports:
      - 9090:9090
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
    volumes:
      - ./config/prometheus.yml:/etc/prometheus/prometheus.yml
      - ./rules:/etc/prometheus/rules
      - prom-data:/prometheus
    networks:
      - prom-net

  node-exporter:
    container_name: node-exporter
    restart: always
    image: prom/node-exporter:latest
    ports:
      - 9100:9100
    networks:
      - prom-net

  cadvisor:
    container_name: cadvisor
    restart: always
    image: google/cadvisor:latest
    ports:
      - 9101:8080
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:rw
      - /sys:/sys:ro
      - /var/lib/docker:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    networks:
      - prom-net

  grafana:
    container_name: grafana
    image: grafana/grafana:6.2.5
    restart: always
    ports:
      - "3003:3000"
    volumes:
      - ./grafana/datasource.yaml:/etc/grafana/provisioning/datasources/datasource.yaml
      - grafana-data:/var/lib/grafana
    networks:
      - prom-net
    #environment:
    #  - GF_SECURITY_ADMIN_PASSWORD=123456

  # prometheus的告警信息发送到alertmanager服务，alertmanager可以转发告警信息到邮件、微信、钉钉等
  alertmanager:
    container_name: alertmanager
    restart: always
    image: prom/alertmanager:latest
    command:
      - "--config.file=/etc/alertmanager/alertmanager.yml"
      - "--storage.path=/alertmanager"
    volumes:
      - ./config/alertmanager.yml:/etc/alertmanager/alertmanager.yml
      - alertmanager-data:/alertmanager
    ports:
      - 9093:9093
    networks:
      - prom-net

  # 发送告警信息到钉钉
  prometheus-webhook-dingtalk:
    container_name: prometheus-webhook-dingtalk
    restart: always
    image: timonwong/prometheus-webhook-dingtalk:latest
    command:
      - "--ding.profile=webhook1=https://oapi.dingtalk.com/robot/send?access_token=f6ac4c35e3aedd9a3d34b9d6950d8e0d0891c4d6837b1596a738e3b9d77e932b"
      - "--ding.profile=webhook2=https://oapi.dingtalk.com/robot/send?access_token=fcc0038d1d09712449a1ba129e0e11748e1bc63f547d49140db35079e29c3973"
    ports:
      - 8060:8060
    networks:
      - prom-net

volumes:
  prom-data:
    driver: local
  grafana-data:
    driver: local
  alertmanager-data:
    driver: local

networks: 
  prom-net:
    driver: bridge

启动服务：

docker-compose up -d

在浏览器打开 http://192.168.101.88:9090/rules ，查看告警文件是否生效，如下图所示：

点击菜单Alerts，查看是否有告警触发，未触发时背景是绿色 0 active，触发后有两种状态pending和firing，pending状态的背景为黄色 1 active，firing状态背景变为红色 1 active，如下图所示：

测试让其触发告警：

# 启动测试容器
docker run --rm -it busybox sh

# 执行耗cpu命令
cat /dev/zero>/dev/null

# 注意：如果一个容器不够，可以启动多几个
# 因为rules文件里设置for为1分钟，说明如果1分钟后告警条件持续满足，则会实际触发告警并且告警状态为FIRING。

对于已经pending或者firing的告警，prometheus也会将它们存储到时间序列ALERTS{}中，可以通过表达式，查询告警结果如下：

ALERTS{alertname="hostMemUsageAlert",alertstate="firing",instance="node-exporter:9100",job="prometheus",severity="critical"}

样本值为1表示当前告警处于活动状态（pending或者firing），当告警从活动状态转换为非活动状态时，样本值则为0。

在浏览器访问alertmanager服务界面( http://192.168.101.88:9093/#/alerts )，如果prometheus触发(firing)了告警，会显示告警消息记录，同时也会把告警消息转发给prometheus-webhook-dingtalk服务，如下图所示：

当触发告警时，alertmanager服务通过http推送(POST)告警信息给prometheus-webhook-dingtalk服务，推送告警消息的url格式为 http://xxxxx:8060/dingtalk/webhook1/send ，其中webhook1是钉钉地址对应的名称，该名称在prometheus-webhook-dingtalk服务启动时设置，docker-compose.yml中prometheus-webhook-dingtalk服务启动参数如下：

    command:
      - "--ding.profile=webhook1=https://oapi.dingtalk.com/robot/send?access_token=xxxxxx"

prometheus-webhook-dingtalk服务接收到消息后从url解析出钉钉地址对应的名称，根据名称获得钉钉地址，然后把告警消息推送到钉钉，如下图所示：

5 exporter

广义上讲所有可以向Prometheus提供监控样本数据的程序都可以被称为一个Exporter。而Exporter的一个实例称为target。

(1) 常用Exporter

(2) Exporter的运行方式

从Exporter的运行方式上来讲，又可以分为：

• 独立使用的

以已经使用过的Node Exporter为例，由于操作系统本身并不直接支持Prometheus，同时用户也无法通过直接从操作系统层面上提供对Prometheus的支持。因此，用户只能通过独立运行一个程序的方式，通过操作系统提供的相关接口，将系统的运行状态数据转换为可供Prometheus读取的监控数据。 除了Node Exporter以外，比如MySQL Exporter、Redis Exporter等都是通过这种方式实现的。 这些Exporter程序扮演了一个中间代理人的角色。

• 集成到应用中的

为了能够更好的监控系统的内部运行状态，有些开源项目如Kubernetes，ETCD等直接在代码中使用了Prometheus的Client Library，提供了对Prometheus的直接支持。这种方式打破的监控的界限，让应用程序可以直接将内部的运行状态暴露给Prometheus，适合于一些需要更多自定义监控指标需求的项目。

(3) Exporter规范

# HELP node_cpu Seconds the cpus spent in each mode.
# TYPE node_cpu counter
node_cpu{cpu="cpu0",mode="idle"} 362812.7890625
# HELP node_load1 1m load average.
# TYPE node_load1 gauge
node_load1 3.0703125

如果当前行以# HELP开始，Prometheus将会按照以下规则对内容进行解析，得到当前的指标名称以及相应的说明信息。

如果当前行以# TYPE开始，Prometheus会按照以下规则对内容进行解析，得到当前的指标名称以及指标类型，如果没有明确的指标类型需要返回为untyped。

除了# 开头的所有行都会被视为是监控样本数据。

5.1 linux系统监控

(1) 启动node-exporter

使用docker启动，docker-compose.yml内容如下：

version: '3.1'

services:
  node-exporter:
    image: prom/node-exporter:v1.2.2
    container_name: node-exporter
    command:
      - '--path.rootfs=/host'
    network_mode: host
    pid: host
    restart: always
    volumes:
      - '/:/host:ro,rslave'

(2) 配置prometheus

在Prometheus配置文件添加job，内容如下：

  - job_name: 'node-exporter'
    scrape_interval: 15s
    static_configs:
      - targets: ['192.168.111.128:9100']
        labels:
          project: "电商"
          env: "dev"

重载prometheus配置，使配置生效

curl -X POST http://192.168.111.128:9090/-/reload

注：启动prometheus时必须添加参数–web.enable-lifecycle，表示开启prometheus重载配置功能。

(3) 导入grafana模板

打开grafana，点击import，输入编号12377，其中数字编号是官网 https://grafana.com/grafana/dashboards 的一个模板编号，确定之后，grafana会自动从grafana官网下载模板json文件。

5.2 cadvisor容器监控

cadvisor是Google开源的一款用于展示和分析容器运行状态的可视化工具。通过在主机上运行CAdvisor用户可以轻松的获取到当前主机上容器的运行统计信息，并以图表的形式向用户展示。

(1) 启动cadvisor容器

使用docker启动，docker-compose.yml内容如下：

version: '3.1'

services:
    cadvisor-exporter:
        image: gcr.io/cadvisor/cadvisor:v0.37.5
        container_name: cadvisor
        # 设置容器权限为root
        privileged: true
        volumes:
            - /:/rootfs:ro
            - /var/run:/var/run:ro
            - /sys:/sys:ro
            - /var/lib/docker/:/var/lib/docker:ro
            - /dev/disk/:/dev/disk:ro
        ports:
            - 9192:8080
        restart: always

注：如果启动容器cadvisor时出现下面错误：

Failed to start container manager: inotify_add_watch /sys/fs/cgroup/cpuacct,cpu: no such file or directory

解决办法：在管理员模式下执行

mount -o remount,rw '/sys/fs/cgroup'
ln -s /sys/fs/cgroup/cpu,cpuacct /sys/fs/cgroup/cpuacct,cpu

(2) 配置Prometheus

在prometheus的配置文件scrape_configs下添加配置：

  - job_name: 'cadvisor'
    scrape_interval: 60s
    static_configs:
    - targets: ['192.168.11.128:9192']

重载prometheus配置，使配置生效

curl -X POST http://192.168.111.128:9090/-/reload

注：启动prometheus时必须添加参数–web.enable-lifecycle，表示开启prometheus重载配置功能。

(3) 导入grafana模板

打开grafana，点击import，输入编号14282，其中数字编号是官网 https://grafana.com/grafana/dashboards 的模板编号，确定之后，grafana会自动从grafana官网下载模板json文件。

使用14282模板时，需要做一下调整，可以结合node-exporter在一个界面展示。

# 修改变量host的Query字段值
label_values(cadvisor_version_info{}, instance)

# 根据实际情况是否过滤显示端口，字段Regex值
/([^:]+):.*/

# 如果过滤端口，每个dashboard都需要添加
instance=~"$host:.*"

(4) 一些常使用的监控

下面表格中列举了一些cadvisor中获取到的典型监控指标：

获取监控值的表达式：

# 计算容器的CPU使用率
sum(irate(container_cpu_usage_seconds_total{image!=""}[1m])) without (cpu)

# 查询容器内存使用量(字节)
container_memory_usage_bytes{image!=""}

# 查询容器网络接收量速率(字节/秒)
sum(rate(container_network_receive_bytes_total{image!=""}[1m])) without (interface)

# 查询容器网络传输量速率(字节/秒)
sum(rate(container_network_transmit_bytes_total{image!=""}[1m])) without (interface)

# 查询容器文件系统读取速率(字节/秒)
sum(rate(container_fs_reads_bytes_total{image!=""}[1m])) without (device)

# 查询容器文件系统写入速率(字节/秒)
sum(rate(container_fs_writes_bytes_total{image!=""}[1m])) without (device)

5.3 mysql监控

通过mysql exporter实现对mysql数据库的性能以及资源利用率进行监控和度量。

(1) 启动mysql-exporter容器

使用docker启动，docker-compose.yml内容如下：

version: '3.1'

services:
    mysql-exporter:
        image: prom/mysqld-exporter:v0.13.0
        restart: always
        ports:
            - 9104:9104
        environment:
            DATA_SOURCE_NAME: "root:123456@(192.168.111.128:3306)/"

(2) 配置Prometheus

在prometheus的配置文件scrape_configs下添加配置：

  # mysql资源export
  - job_name: 'mysql-exporter'
    static_configs:
    - targets: ['192.168.111.128:9104']
      #labels:
        #project: 'dbaas'
        #environment: 'dev'

重载prometheus配置，使配置生效

curl -X POST http://192.168.111.128:9090/-/reload

注：启动prometheus时必须添加参数–web.enable-lifecycle，表示开启prometheus重载配置功能。

可以在prometheus UI中查看到当前所有的Target状态，如果为up状态，说明mysql-exporter与prometheus集成成功。

(3) 导入grafana

把dashboard id(单机版536或集群版537)导入到grafana的dashboard。

(4) 一些mysql常使用的监控指标

• 监控数据库吞吐量

对于数据库而言，最重要的工作就是实现对数据的增、删、改、查。为了衡量数据库服务器当前的吞吐量变化情况。在mysql内部通过一个名为Questions的计数器，当客户端发送一个查询语句后，其值就会加1，对应mysql语句：

SHOW GLOBAL STATUS LIKE “Questions”;

一般还可以从监控读操作和写操作的执行情况进行判断。通过mysql全局状态中的Com_select可以查询到当前服务器执行查询语句的总次数：相应的，也可以通过Com_insert、Com_update以及Com_delete的总量衡量当前服务器写操作的总次数，通过以下指令查询当前mysql实例insert语句的执行次数总量：

SHOW GLOBAL STATUS LIKE “Com_insert”;

通过以上监控指标，以及实际监控的场景，我们可以利用PromQL快速建立多个监控项。

# 查看当前mysql实例查询速率的变化情况，查询数量的突变往往暗示着可能发生了某些严重的问题，因此用于用户应该关注并且设置响应的告警规则，以及时获取该指标的变化情况
rate(mysql_global_status_questions[2m])
    
# 查看当前MySQL实例写操作速率的变化情况
sum(rate(mysql_global_status_commands_total{command=~"insert|update|delete"}[2m])) without (command)

• 监控连接情况

在MySQL中通过全局设置max_connections限制了当前服务器允许的最大客户端连接数量。一旦可用连接数被用尽，新的客户端连接都会被直接拒绝。用户可以通过以下指令查看当前MySQL服务的max_connections配置：

SHOW VARIABLES LIKE ‘max_connections’;

mysql_global_variables_max_connections： 允许的最大连接数；

mysql_global_status_threads_connected： 当前打开的连接；

mysql_global_status_threads_running：当前正在使用的连接数；

mysql_global_status_aborted_connects：当前拒绝的连接数；

mysql_global_status_connection_errors_total{error=“max_connections”}：由于超出最大连接数导致的错误；

mysql_global_status_connection_errors_total{error=“internal”}：由于系统内部导致的错误；

通过以上监控指标，以及实际监控的场景，我们可以利用PromQL快速建立多个监控项。

# 查询当前剩余的可用连接数
mysql_global_variables_max_connections - mysql_global_status_threads_connected

# 查询当前MySQL实例连接拒绝数
mysql_global_status_aborted_connects

• 监控缓冲池使用情况

mysql默认的存储引擎InnoDB使用了一片称为缓冲池的内存区域，用于缓存数据表以及索引的数据。 当缓冲池的资源使用超出限制后，可能会导致数据库性能的下降，同时很多查询命令会直接在磁盘中执行，导致磁盘I/O不断攀升。

在mysql查看当前缓冲池中的内存页的总页数：

SHOW GLOBAL STATUS LIKE “Innodb_buffer_pool_pages_total”;

在mysql查看正常从缓冲池读取数据的请求数量：

SHOW GLOBAL STATUS LIKE “Innodb_buffer_pool_read_requests”;

当缓冲池无法满足时，mysql只能从磁盘中读取数据，如果Innodb_buffer_pool_reads的值开始增加，可能意味着数据库的性能有问题，查看从磁盘读取数据的请求数量：

SHOW GLOBAL STATUS LIKE “Innodb_buffer_pool_reads”;

通过以上监控指标，以及实际监控的场景，我们可以利用PromQL快速建立多个监控项。

# 通过以下PromQL可以得到各个MySQL实例的缓冲池利用率:
(sum(mysql_global_status_buffer_pool_pages) by (instance) - sum(mysql_global_status_buffer_pool_pages{state="free"}) by (instance)) / sum(mysql_global_status_buffer_pool_pages) by (instance)

# 计算2分钟内磁盘读取请求次数的增长率的变化情况：
rate(mysql_global_status_innodb_buffer_pool_reads[2m])

• 查询性能

MySQL还提供了一个Slow_queries的计数器，当查询的执行时间超过long_query_time的值后，计数器就会+1，其默认值为10秒。

在mysql查看慢查询命令：

SHOW VARIABLES LIKE ‘long_query_time’;

在mysql查看慢查询的数量：

SHOW GLOBAL STATUS LIKE “Slow_queries”;

通过监控Slow_queries的增长率，可以反映出当前MySQL服务器的性能状态：

rate(mysql_global_status_slow_queries[2m])

5.4 redis监控

(1) 启动redis-exporter

使用docker启动，docker-compose.yml内容如下：

version: '3.1'

services:
    redis-exporter:
        container_name: redis-exporter
        image: bitnami/redis-exporter:1.27.1
        restart: always
        ports:
            - 9121:9121
        command:
            - "-redis.addr=redis://192.168.83.133:6379"
            - "-redis.password=123456"

(2) 配置prometheus

在Prometheus配置文件添加job，内容如下：

  - job_name: 'redis-exporter'
    scrape_interval: 15s
    static_configs:
      - targets: ['192.168.111.128:9121']

重载prometheus配置，使配置生效

curl -X POST http://192.168.111.128:9090/-/reload

注：启动prometheus时必须添加参数–web.enable-lifecycle，表示开启prometheus重载配置功能。

(3) 导入grafana模板

打开grafana，点击import，输入编号763，其中数字编号是官网 https://grafana.com/grafana/dashboards 的一个模板编号，确定之后，grafana会自动从grafana官网下载模板json文件。

5.5 blackbox exporter网络探测

白盒监控包括主机的资源用量、容器的运行状态、数据库中间件的运行数据，通过白盒能够了解其内部的实际运行状态，通过对监控指标的观察能够预判可能出现的问题，从而对潜在的不确定因素进行优化。

黑盒监控相较于白盒监控最大的不同在于黑盒监控是以故障为导向当故障发生时，黑盒监控能快速发现故障，而白盒监控则侧重于主动发现或者预测潜在的问题。一个完善的监控目标是要能够从白盒的角度发现潜在问题，能够在黑盒的角度快速发现已经发生的问题。

(1) 启动blackbox-exporter容器

使用docker启动，docker-compose.yml内容如下：

version: '3.1'

services:
  blackbox-exporter:
    container_name: blackbox-exporter
    restart: always
    image: prom/blackbox-exporter:v0.19.0
    command:
      - "--config.file=/config/blackbox.yml"
    volumes:
      - $PWD/config/blackbox.yml:/config/blackbox.yml
    ports:
      - 9115:9115

配置文件blackbox.yml内容如下：

modules:
  http_2xx:
    prober: http
    timeout: 5s
    http:
      method: GET
  tcp_connect:
    prober: tcp
    timeout: 5s

(2) 配置prometheus

在prometheus的配置文件scrape_configs下添加配置：

  # http export
  - job_name: 'blackbox'
    scrape_interval: 30s #每次获取数据的时间间隔
    metrics_path: /probe
    params:
      module: [http_2xx]  # Look for a HTTP 200 response.
    static_configs:
      - targets:
        # 监控目标
        - https://www.baidu.com
        - https://zhuyasen.com
        - https://test.demo.com
        - http://example:8080
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox-exporter:9115  # The blackbox exporter's real hostname:port.

重载prometheus配置，使配置生效

curl -X POST http://192.168.111.128:9090/-/reload

注：启动prometheus时必须添加参数–web.enable-lifecycle，表示开启prometheus重载配置功能。

(3) 导入grafana模板

打开grafana，点击import，输入编号13659或9965，其中数字编号是官网 https://grafana.com/grafana/dashboards 的一个模板编号，确定之后，grafana会自动从grafana官网下载模板json文件。

5.6 linux进程监控

(1) 启动process-exporter

使用docker启动，docker-compose.yml内容如下：

version: '3.1'

services:
    process-exporter:
        image: ncabatoff/process-exporter:0.7.5
        volumes:
            - /proc:/host/proc
            - $PWD/config/process.yml:/config/process.yml
        command:
            - '--procfs=/host/proc'
            - '--config.path=/config/process.yml'
        ports:
            - 9256:9256
        restart: always

GitHub地址：https://github.com/ncabatoff/process-exporter

配置文件process.yml如下：

process_names:
  - comm:
    - chromium-browse
    - bash
    - prometheus
    - gvim
  - exe:
    - /sbin/upstart
    cmdline:
    - --user
    name: upstart:-user

(2) 配置prometheus

在Prometheus配置文件添加job，内容如下：

  - job_name: 'process-exporter'
    scrape_interval: 15s
    static_configs:
      - targets: ['192.168.83.133:9256']

(3) 导入grafana模板

打开grafana，点击import，输入编号249，其中数字编号是官网 https://grafana.com/grafana/dashboards 的一个模板编号，确定之后，grafana会自动从grafana官网下载模板json文件。

6 kubernetes监控

6.1 使用Prometheus监控Kubernetes集群

监控Kubernetes集群监控的各个维度以及策略：

(1) 从Kubelet获取节点运行状态

修改prometheus.yml配置文件，并添加以下采集任务配置：

    - job_name: 'kubernetes-kubelet'
      kubernetes_sd_configs:
      - role: node
      scheme: https
      tls_config:
        ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
      bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
      relabel_configs:
      - action: labelmap
        regex: __meta_kubernetes_node_label_(.+)
      - target_label: __address__
        replacement: kubernetes.default.svc:443
      - source_labels: [__meta_kubernetes_node_name]
        regex: (.+)
        target_label: __metrics_path__
        replacement: /api/v1/nodes/${1}/proxy/metrics

通过指标kubelet_pod_start_latency_microseconds可以获得当前节点中Pod启动时间相关的统计数据：

kubelet_pod_start_latency_microseconds{quantile=“0.99”}/1000000

监控指标kubeletdocker*还可以体现出kubelet与当前节点的docker服务的调用情况，从而可以反映出docker本身是否会影响kubelet的性能表现等问题：

kubelet_pod_start_latency_microseconds_sum / kubelet_pod_start_latency_microseconds_count

(2) 使用NodeExporter监控集群资源使用情况

修改prometheus.yml配置文件，并添加以下采集任务配置：

    - job_name: 'kubernetes-nodes'
      kubernetes_sd_configs:
      - role: node
      scheme: https
      tls_config:
        ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
      bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
      relabel_configs:
      - action: labelmap
        regex: __meta_kubernetes_node_label_(.+)
      - target_label: __address__
        replacement: kubernetes.default.svc:443
      - source_labels: [__meta_kubernetes_node_name]
        regex: (.+)
        target_label: __metrics_path__
        replacement: /api/v1/nodes/${1}/proxy/metrics

    - job_name: 'kubernetes-pods'
      kubernetes_sd_configs:
      - role: pod
      relabel_configs:
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
        action: keep
        regex: true
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
        action: replace
        target_label: __metrics_path__
        regex: (.+)
      - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
        action: replace
        regex: ([^:]+)(?::\d+)?;(\d+)
        replacement: $1:$2
        target_label: __address__
      - action: labelmap
        regex: __meta_kubernetes_pod_label_(.+)
      - source_labels: [__meta_kubernetes_namespace]
        action: replace
        target_label: kubernetes_namespace
      - source_labels: [__meta_kubernetes_pod_name]
        action: replace
        target_label: kubernetes_pod_name

(3) 从kube-apiserver获取集群运行监控指标

修改prometheus.yml配置文件，并添加以下采集任务配置：

    - job_name: 'kubernetes-apiservers'
      kubernetes_sd_configs:
      - role: endpoints
      scheme: https
      tls_config:
        ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
      bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
      relabel_configs:
      - source_labels: [__meta_kubernetes_namespace, __meta_kubernetes_service_name, __meta_kubernetes_endpoint_port_name]
        action: keep
        regex: default;kubernetes;https
      - target_label: __address__
        replacement: kubernetes.default.svc:443

(4) 对Ingress和Service进行网络探测

修改prometheus.yml配置文件，并添加以下采集任务配置：

    - job_name: 'kubernetes-services'
      scrape_interval: 20s #每次获取数据的时间间隔
      kubernetes_sd_configs:
      - role: service
      metrics_path: /probe
      params:
        module: [http_2xx]
      relabel_configs:
      # 过滤探测目标service
      # 如果注释掉下面source_labels三行，会探测所有service
      # 如果不注释，只有service的metadata里添加注解(annotations) prometheus.io/probe: "true"才会被探测
      - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_probe]
        action: keep
        regex: true
      - source_labels: [__address__]
        target_label: __param_target
      - target_label: __address__
        replacement: blackbox-exporter:9115
      - source_labels: [__param_target]
        target_label: instance
      - action: labelmap
        regex: __meta_kubernetes_service_label_(.+)
      - source_labels: [__meta_kubernetes_namespace]
        target_label: kubernetes_namespace
      - source_labels: [__meta_kubernetes_service_name]
        target_label: kubernetes_name

    - job_name: 'kubernetes-ingresses'
      scrape_interval: 20s #每次获取数据的时间间隔
      kubernetes_sd_configs:
      - role: ingress
      metrics_path: /probe
      params:
        module: [http_2xx]
      relabel_configs:
      # 过滤探测目标ingresses
      # 如果注释掉下面source_labels三行，会探测所有ingresses
      # 如果不注释，只有ingresses的metadata里添加注解(annotations) prometheus.io/probe: "true"才会被探测
      - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_probe]
        action: keep
        regex: true
      - source_labels: [__meta_kubernetes_ingress_scheme,__address__,__meta_kubernetes_ingress_path]
        regex: (.+);(.+);(.+)
        replacement: ${1}://${2}${3}
        target_label: __param_target
      - target_label: __address__
        replacement: blackbox-exporter:9115
      - source_labels: [__param_target]
        target_label: instance
      - action: labelmap
        regex: __meta_kubernetes_ingress_label_(.+)
      - source_labels: [__meta_kubernetes_namespace]
        target_label: kubernetes_namespace
      - source_labels: [__meta_kubernetes_ingress_name]
        target_label: kubernetes_name

启动blackbox服务，启动脚本如下：

apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    app: blackbox-exporter
  name: blackbox-exporter
  namespace: monitoring
data:
  blackbox.yml: |-
    modules:
      http_2xx:
        prober: http
        timeout: 30s
        http:
          valid_http_versions: ["HTTP/1.1", "HTTP/2"]
          valid_status_codes: [200,302,301,401,404]
          method: GET
          preferred_ip_protocol: "ip4"

---

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: blackbox-exporter
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: blackbox-exporter
  replicas: 1
  template:
    metadata:
      labels:
        app: blackbox-exporter
    spec:
      restartPolicy: Always
      containers:
      - name: blackbox-exporter
        image: prom/blackbox-exporter:v0.14.0
        imagePullPolicy: IfNotPresent
        ports:
        - name: blackbox-port
          containerPort: 9115
        readinessProbe:
          tcpSocket:
            port: 9115
          initialDelaySeconds: 20
          timeoutSeconds: 5
        resources:
          requests:
            memory: 10Mi
            cpu: 10m
          limits:
            memory: 60Mi
            cpu: 200m
        volumeMounts:
        - name: config
          mountPath: /etc/blackbox_exporter
        args:
        - --config.file=/etc/blackbox_exporter/blackbox.yml
        - --log.level=debug
        - --web.listen-address=:9115
      volumes:
      - name: config
        configMap:
          name: blackbox-exporter

---

apiVersion: v1
kind: Service
metadata:
  labels:
    app: blackbox-exporter
  name: blackbox-exporter
  namespace: monitoring
  annotations:
    prometheus.io/scrape: 'true'
spec:
  selector:
    app: blackbox-exporter
  ports:
  - name: blackbox
    port: 9115
    targetPort: 9115
    protocol: TCP

遇到问题：

在kubernetes-apiservers的target出现错误提示信息：

Get https://192.168.99.100:10250/metrics: x509: cannot validate certificate for 192.168.99.100 because it doesn’t contain any IP SANs

这是由于当前使用的ca证书中，并不包含192.168.99.100的地址信息。

解决方法：

第一种方法是直接跳过ca证书校验过程，通过在tls_config中设置 insecure_skip_verify为true即可。 这样Promthues在采集样本数据时，将会自动跳过ca证书的校验过程。

第二种方式，不直接通过kubelet的metrics服务采集监控数据，而通过Kubernetes的api-server提供的代理API访问各个节点中kubelet的metrics服务：

      - target_label: __address__
        replacement: kubernetes.default.svc:443
      - source_labels: [__meta_kubernetes_node_name]
        regex: (.+)
        target_label: __metrics_path__
        replacement: /api/v1/nodes/${1}/proxy/metrics

6.2 认识Prometheus Operator

为了在Kubernetes能够方便的管理和部署Prometheus，使用ConfigMap来管理Prometheus配置文件。每次对Prometheus配置文件进行升级时，我们需要手动移除已经运行的Pod实例，从而让Kubernetes可以使用最新的配置文件创建Prometheus，这种通过手动的方式部署和升级Prometheus过程繁琐并且效率低下。

(1) Prometheus Operator的工作原理

从概念上来讲Operator就是针对管理特定应用程序的，在Kubernetes基本的Resource和Controller的概念上，以扩展Kubernetes api的形式。帮助用户创建，配置和管理复杂的有状态应用程序。从而实现特定应用程序的常见操作以及运维自动化。

Prometheus的本职就是一组用户自定义的CRD资源以及Controller的实现，Prometheus Operator负责监听这些自定义资源的变化，并且根据这些资源的定义自动化的完成如Prometheus Server自身以及配置的自动化管理工作。

(2) Prometheus Operator能做什么

Prometheus Operator能够帮助用户自动化的创建以及管理Prometheus Server以及其相应的配置，目前提供的️4类资源：

• Prometheus：声明式创建和管理Prometheus Server实例；
• ServiceMonitor：负责声明式的管理监控配置；
• PrometheusRule：负责声明式的管理告警配置；
• Alertmanager：声明式的创建和管理Alertmanager实例。

(3) 安装Prometheus Operator

部署prometheus-operator.yml脚本文件内容如下：

apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: prometheus-operator
    app.kubernetes.io/version: v0.31.1
  name: prometheus-operator
  namespace: monitoring

---

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: prometheus-operator
    app.kubernetes.io/version: v0.31.1
  name: prometheus-operator
rules:
- apiGroups:
  - apiextensions.k8s.io
  resources:
  - customresourcedefinitions
  verbs:
  - '*'
- apiGroups:
  - monitoring.coreos.com
  resources:
  - alertmanagers
  - prometheuses
  - prometheuses/finalizers
  - alertmanagers/finalizers
  - servicemonitors
  - podmonitors
  - prometheusrules
  verbs:
  - '*'
- apiGroups:
  - apps
  resources:
  - statefulsets
  verbs:
  - '*'
- apiGroups:
  - ""
  resources:
  - configmaps
  - secrets
  verbs:
  - '*'
- apiGroups:
  - ""
  resources:
  - pods
  verbs:
  - list
  - delete
- apiGroups:
  - ""
  resources:
  - services
  - services/finalizers
  - endpoints
  verbs:
  - get
  - create
  - update
  - delete
- apiGroups:
  - ""
  resources:
  - nodes
  verbs:
  - list
  - watch
- apiGroups:
  - ""
  resources:
  - namespaces
  verbs:
  - get
  - list
  - watch

---

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: prometheus-operator
    app.kubernetes.io/version: v0.31.1
  name: prometheus-operator
  namespace: monitoring
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: prometheus-operator
subjects:
- kind: ServiceAccount
  name: prometheus-operator
  namespace: monitoring

---

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: prometheus-operator
    app.kubernetes.io/version: v0.31.1
  name: prometheus-operator
  namespace: monitoring
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/component: controller
      app.kubernetes.io/name: prometheus-operator
  template:
    metadata:
      labels:
        app.kubernetes.io/component: controller
        app.kubernetes.io/name: prometheus-operator
        app.kubernetes.io/version: v0.31.1
    spec:
      containers:
      - args:
        - --kubelet-service=kube-system/kubelet
        - --logtostderr=true
        - --config-reloader-image=quay.io/coreos/configmap-reload:v0.0.1
        - --prometheus-config-reloader=quay.io/coreos/prometheus-config-reloader:v0.31.1
        #image: quay.io/coreos/prometheus-operator:v0.31.1
        image: 281073576117.dkr.ecr.cn-north-1.amazonaws.com.cn/prometheus-operator:v0.31.1
        name: prometheus-operator
        ports:
        - containerPort: 8080
          name: http
        resources:
          limits:
            cpu: 200m
            memory: 200Mi
          requests:
            cpu: 100m
            memory: 100Mi
        securityContext:
          allowPrivilegeEscalation: false
      nodeSelector:
        beta.kubernetes.io/os: linux
      securityContext:
        runAsNonRoot: true
        runAsUser: 65534
      serviceAccountName: prometheus-operator

---

apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: prometheus-operator
    app.kubernetes.io/version: v0.31.1
  name: prometheus-operator
  namespace: monitoring
spec:
  clusterIP: None
  ports:
  - name: http
    port: 8080
    targetPort: http
  selector:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: prometheus-operator

启动prometheus operator：

kubectl apply -f prometheus-operator.yml

查看启动情况：

kubectl get all -n monitoring

查看新添加的自定义资源：

kubectl get crd

NAME                                    CREATED AT
alertmanagers.monitoring.coreos.com     2019-08-14T05:56:46Z
podmonitors.monitoring.coreos.com       2019-08-14T05:56:50Z
prometheuses.monitoring.coreos.com      2019-08-14T05:56:46Z
prometheusrules.monitoring.coreos.com   2019-08-14T05:56:50Z
servicemonitors.monitoring.coreos.com   2019-08-14T05:56:50Z

6.3 使用Operator管理Prometheus

(1) 创建Prometheus实例

当集群中已经安装Prometheus Operator之后，对于部署Prometheus Server实例就变成了声明一个Prometheus资源，安装Prometheus的部署脚本prometheus-inst.yml文件内容如下：

apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: inst
  namespace: monitoring
spec:
  resources:
    requests:
      memory: 400Mi

启动prometheus：

kubectl apply -f prometheus-inst.yml

查看sts和pod实例启动情况：

kubectl get sts,pod -n monitoring

通过port-forward访问Prometheus实例:

kubectl port-forward –address=0.0.0.0 statefulsets/prometheus-inst 9090:9090 -n monitoring

如果能在浏览器访问 http://:9090 访问，说明prometheus启动正常，此时prometheus的配置只有默认的配置，可以点击菜单Status–>Configuration查看。

(2) 使用ServiceMonitor管理监控配置

修改监控配置项是Prometheus下常用的运维操作之一，为了能够自动化的管理Prometheus的配置，Prometheus Operator使用了自定义资源类型ServiceMonitor来描述监控对象的信息。

部署一个示例应用，部署脚本example-app.yaml内容如下：

kind: Service
apiVersion: v1
metadata:
  name: example-app
  labels:
    app: example-app
spec:
  selector:
    app: example-app
  ports:
  - name: web
    port: 8080
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: example-app
spec:
  replicas: 3
  template:
    metadata:
      labels:
        app: example-app
    spec:
      containers:
      - name: example-app
        image: fabxc/instrumented_app
        ports:
        - name: web
          containerPort: 8080

查看实例启动情况：

kubectl get svc,pod | grep example-app

通过port-forward访问任意Pod实例：

kubectl port-forward –address=0.0.0.0 deployments/example-app 8080:8080

在浏览器查看 http://:8080/metrics，能够看到很多符合prometheus采集的信息，此时prometheus还不能采集example-app监控数据。

为了能够让Prometheus能够采集应用的监控数据，在原生的Prometheus配置方式中，我们在Prometheus配置文件中定义单独的Job，同时使用kubernetes_sd定义整个服务发现过程。而在Prometheus Operator中，则可以直接声明一个ServiceMonitor对象，把监听的服务和端口添加进来，这是ServiceMonitor关联服务对象过程。

脚本prometheus-serviceMonitor.yml内容如下所示：

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: example-app
  namespace: monitoring
  labels:
    team: frontend
spec:
  namespaceSelector:
    matchNames:
    - default
  selector:
    matchLabels:
      app: example-app
  endpoints:
  - port: web

通过定义selector中的标签定义选择监控目标的Pod对象，同时在endpoints中指定port名称为web的端口。默认情况下ServiceMonitor和监控对象必须是在相同Namespace下的。在本示例中由于Prometheus是部署在Monitoring命名空间下，因此为了能够关联default命名空间下的example对象，需要使用namespaceSelector定义让其可以跨命名空间关联ServiceMonitor资源。如果希望ServiceMonitor可以关联任意命名空间下的标签，则通过以下方式定义：

spec:
  namespaceSelector:
    any: true

(3)关联ServiceMonitor与Promethues

为了能够让Prometheus关联到ServiceMonitor，需要在Pormtheus定义中使用serviceMonitorSelector，我们可以通过标签选择当前Prometheus需要监控的ServiceMonitor对象，修改prometheus-inst.yaml中Prometheus的定义如下所示：

apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: inst
  namespace: monitoring
spec:
  serviceMonitorSelector:
    matchLabels:
      team: frontend
  resources:
    requests:
      memory: 400Mi

更新prometheus服务：

kubectl apply -f prometheus-inst.yml

等待一会时间，在浏览器打开http://:9090/config ，会发现prometheus自动添加monitoring/example-app/0的Job配置。

虽然自动添加Job配置，但是Prometheus的Target中并没包含任何的监控对象。查看Prometheus的Pod实例日志，可以看到如下信息：

level=error ts=2019-08-14T10:01:27.707953281Z caller=klog.go:94 component=k8s_client_runtime func=ErrorDepth msg="/app/discovery/kubernetes/kubernetes.go:302: Failed to list *v1.Pod: pods is forbidden: User \"system:serviceaccount:monitoring:default\" cannot list pods at the cluster scope"

说明在monitoring名称空间下的prometheus没有权限获取defaul名称空间的example-app信息。

(4) 自定义ServiceAccount

为了提升权限获取defaul名称空间的服务信息，需要在Monitoring命名空间下为创建一个名为Prometheus的ServiceAccount，并且为该账号赋予相应的集群访问权限。

资源文件prometheus-rbac.yaml内容如下：

apiVersion: v1
kind: ServiceAccount
metadata:
  name: prometheus
  namespace: monitoring
  
---

apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRole
metadata:
  name: prometheus
rules:
- apiGroups: [""]
  resources:
  - nodes
  - services
  - endpoints
  - pods
  verbs: ["get", "list", "watch"]
- apiGroups: [""]
  resources:
  - configmaps
  verbs: ["get"]
- nonResourceURLs: ["/metrics"]
  verbs: ["get"]
  
---

apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
  name: prometheus
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: prometheus
subjects:
- kind: ServiceAccount
  name: prometheus
  namespace: monitoring

在完成ServiceAccount创建后，修改prometheus-inst.yaml，并添加ServiceAccount如下所示：

apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: inst
  namespace: monitoring
spec:
  serviceAccountName: prometheus
  serviceMonitorSelector:
    matchLabels:
      team: frontend
  resources:
    requests:
      memory: 400Mi

等待Prometheus Operator完成相关配置变更后，此时查看Prometheus，我们就能看到当前Prometheus已经能够正常的采集实例应用的相关监控数据了。

常用的grafana面板

grafana免密码登录设置，打开conf/defaults.ini，把auth.anonymous值改为true

[auth.anonymous]
enabled = true

参考：

• https://github.com/yunlzheng/prometheus-book

本文链接：https://zhuyasen.com/post/prometheus.html，参与评论 »

rabbitMQ简介

rabbitMQ是一个广泛使用的开源消息队列系统，它实现了高级消息队列协议(AMQP)标准，为分布式应用程序提供了强大的消息传递功能。rabbitMQ是 Erlang 语言编写的，具有高度的可扩展性和可靠性，因此被广泛用于构建分布式、异步的消息通信系统。

消息队列的概念

消息队列是一种通信模式，用于在不同组件、服务或应用程序之间传递消息。它允许发送者将消息放入队列，而接收者可以从队列中获取消息，实现了解耦、异步通信和数据传递的目标。消息队列通常用于处理以下情况：

• 异步通信：发送方和接收方之间不需要立即响应，提高了系统的可伸缩性和性能。
• 任务排队：将需要处理的任务放入队列，由工作进程异步执行。
• 解耦组件：允许不同的应用程序或服务之间进行松耦合的通信。

rabbitMQ 工作模式

• Direct Exchange(直连交换机)：对于每个队列与direct交换机绑定的key进行完全匹配。
• Topic Exchange(主题交换机) ：对于每个队列与Topic交换机绑定的key进行模糊匹配。
• Fanout Exchange(扇出型交换机)： Fanout类型的交换机会将消息分发给所有绑定了此交换机的队列。
• Headers Exchange(头交换机)：Headers类型的交换机是通过headers信息来匹配的，工作原理与direct类型类似。
• Delayed Message Exchange(延时交换机)：指定一个消息不是立即投递到队列，而是在指定的一段时间后才投递。

rabbitMQ 的核心概念

• Producer(生产者)：负责向消息队列发送消息的应用程序或服务。
• Consumer(消费者)：负责从消息队列接收和处理消息的应用程序或服务。
• Queue(队列)：用于存储消息的缓冲区，消费者从队列中获取消息进行处理。
• Exchange(交换机)：接收生产者发送的消息并将其路由到一个或多个队列。
• Binding(绑定)：定义了队列和交换机之间的关系，指定了如何将消息从交换机路由到队列。
• Virtual Host(虚拟主机)：rabbitMQ允许将多个逻辑消息队列隔离到不同的虚拟主机中，以实现资源隔离和多租户支持。

工作流程

rabbitMQ的工作流程如下：

• 生产者将消息发布到一个或多个交换机。
• 交换机根据绑定规则将消息路由到一个或多个队列。
• 消费者订阅队列并接收消息。
• 消费者处理消息，并可以确认消息已被成功处理。
• 消息可以持久化到磁盘，以确保在 rabbitMQ重启后不会丢失。

消息确认和持久化

rabbitMQ具有高度的可靠性，它支持消息确认机制，确保消息在成功处理后才从队列中删除。如果消费者在处理消息时发生错误，消息将被重新排队，而不会丢失。此外，rabbitMQ还支持将消息持久化到磁盘，以防止消息在系统故障时丢失。

可用性和扩展性

rabbitMQ具有高可用性和可伸缩性的特性。它支持镜像队列(Queue Mirroring)来确保队列数据的冗余备份，以提高可用性。此外，rabbitMQ集群可以水平扩展，允许将多个节点添加到集群中以增加处理能力。

协议支持

rabbitMQ支持多种协议，包括 AMQP(高级消息队列协议)、STOMP、MQTT 等。这使得不同类型的应用程序可以与 rabbitMQ进行通信，而无需修改现有代码。

应用场景

• 分布式系统通信：用于不同组件或服务之间的消息传递。
• 异步任务处理：将需要执行的任务放入队列，由工作者进行处理。
• 日志和监控数据的收集：将日志和监控数据发送到 rabbitMQ，以进行集中处理和分析。

安装rabbitMQ

在docker安装单机版rabbitMQ

docker-compose.yaml配置文件内容如下：

version: '3'
 
services:
  rabbitmq:
    image: rabbitmq:3.12-management
    container_name: rabbitmq
    hostname: rabbitmq-service
    restart: always
    ports:
      - 5672:5672
      - 15672:15672
    volumes:
      - $PWD/data:/var/lib/rabbitmq
      - $PWD/plugins/enabled_plugins:/etc/rabbitmq/enabled_plugins
      - $PWD/plugins/rabbitmq_delayed_message_exchange-3.12.0.ez:/plugins/rabbitmq_delayed_message_exchange-3.12.0.ez
    environment:
      TZ: Asia/Shanghai
      RABBITMQ_DEFAULT_USER: guest
      RABBITMQ_DEFAULT_PASS: guest
      RABBITMQ_DEFAULT_VHOST: /

• enabled_plugins 是设置默认开启的插件，内容为 [rabbitmq_delayed_message_exchange,rabbitmq_management,rabbitmq_prometheus]
• rabbitmq_delayed_message_exchange-3.12.0.ez 是延时队列插件。

启动rabbitmq：

docker-compose up -d

可以在浏览器访问管理后台 http://localhost:15672，户名和密码都是guest。

在docker安装高可用的rabbitMQ集群

安装根据实际需要使用普通模式和镜像模式，一共有三个rabbitmq节点和一个高可用代理服务haproxy，haproxy务作为代理连接入口，文件列表如下：

.
├── cluster-entrypoint.sh
├── docker-compose.yml
├── .env
└── haproxy.cfg

(1) 加入rabbitMQ集群的脚本文件cluster-entrypoint.sh内容如下：

#!/bin/bash

set -e

# Start RMQ from entry point.
# This will ensure that environment variables passed
# will be honored
/usr/local/bin/docker-entrypoint.sh rabbitmq-server -detached

# Do the cluster dance
rabbitmqctl stop_app
rabbitmqctl join_cluster rabbit@rabbitmq1

# Stop the entire RMQ server. This is done so that we
# can attach to it again, but without the -detached flag
# making it run in the forground
rabbitmqctl stop

# Wait a while for the app to really stop
sleep 2s

# Start it
rabbitmq-server

(2) docker-compose配置文件的环境变量.env内容如下，.env文件包含可用于更改默认用户名，密码等。

RABBITMQ_DEFAULT_USER=guest
RABBITMQ_DEFAULT_PASS=guest
RABBITMQ_DEFAULT_VHOST=/
RABBITMQ_ERLANG_COOKIE=rec123456

(3) 高可用服务的配置文件haproxy.cfg内容如下：

    global
            log 127.0.0.1   local1
            maxconn 4096
     
    defaults
            log     global
            mode    tcp
            option  tcplog
            retries 3
            option redispatch
            maxconn 2000
            timeout connect 5000
            timeout client 50000
            timeout server 50000
     
    listen  stats
            bind *:1936
            mode http
            stats enable
            stats hide-version
            stats realm Haproxy\ Statistics
            stats uri /
     
    listen rabbitmq
            bind *:5672
            mode            tcp
            balance         roundrobin
            timeout client  3h
            timeout server  3h
            option          clitcpka
            server          rabbitmq1 rabbitmq1:5672  check inter 5s rise 2 fall 3
            server          rabbitmq2 rabbitmq2:5672  check inter 5s rise 2 fall 3
            server          rabbitmq3 rabbitmq3:5672  check inter 5s rise 2 fall 3

    listen mgmt
            bind *:15672
            mode            tcp
            balance         roundrobin
            timeout client  3h
            timeout server  3h
            option          clitcpka
            server          rabbitmq1 rabbitmq1:15672  check inter 5s rise 2 fall 3
            server          rabbitmq2 rabbitmq2:15672  check inter 5s rise 2 fall 3
            server          rabbitmq3 rabbitmq3:15672  check inter 5s rise 2 fall 3

(4) docker-compose.yml配置文件内容如下：

version: '3'

services:

  rabbitmq1:
    hostname: rabbitmq1
    image: rabbitmq:3.12-management
    restart: always
    environment:
      - RABBITMQ_ERLANG_COOKIE=${RABBITMQ_ERLANG_COOKIE}
      - RABBITMQ_DEFAULT_USER=${RABBITMQ_DEFAULT_USER}
      - RABBITMQ_DEFAULT_PASS=${RABBITMQ_DEFAULT_PASS}
      - RABBITMQ_DEFAULT_VHOST=${RABBITMQ_DEFAULT_VHOST}
    volumes:
      - ./data/rabbitmq1:/var/lib/rabbitmq/mnesia

  rabbitmq2:
    hostname: rabbitmq2
    image: rabbitmq:3.12-management
    restart: always
    depends_on:
      - rabbitmq1
    environment:
      - RABBITMQ_ERLANG_COOKIE=${RABBITMQ_ERLANG_COOKIE}
    volumes:
      - ./cluster-entrypoint.sh:/usr/local/bin/cluster-entrypoint.sh
      - ./data/rabbitmq2:/var/lib/rabbitmq/mnesia
    entrypoint: sh /usr/local/bin/cluster-entrypoint.sh

  rabbitmq3:
    hostname: rabbitmq3
    image: rabbitmq:3.12-management
    restart: always
    depends_on:
      - rabbitmq1
    environment:
      - RABBITMQ_ERLANG_COOKIE=${RABBITMQ_ERLANG_COOKIE}
    volumes:
      - ./cluster-entrypoint.sh:/usr/local/bin/cluster-entrypoint.sh
      - ./data/rabbitmq3:/var/lib/rabbitmq/mnesia
    entrypoint: sh /usr/local/bin/cluster-entrypoint.sh
    
  haproxy:
    image: haproxy:1.9
    restart: always
    volumes:
      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
    depends_on:
      - rabbitmq1
      - rabbitmq2
      - rabbitmq3
    ports:
      - 15672:15672
      - 5672:5672

启动rabbitMQ集群：

docker-compose up -d

# 默认用户名guest，默认密码guest
# 代理连接地址：localhost:5672
# 管理界面地址：localhost:15672

可以在浏览器访问管理后台 http://localhost:15672，户名和密码都是guest。

在k8s安装rabbitMQ集群

根据实际需要，安装rabbitmq集群可以选择普通模式和镜像模式，如果需要设置为镜像模式，在普通集群的中任意节点启用策略，策略会自动同步到集群节点：

rabbitmqctl set_policy ha-all “^ha.” ‘{“ha-mode”:“all”}’

注意：”^ha” 这个规则要根据自己修改，这个是指同步”ha”开头的队列名称，配置时使用的应用于所有队列，所以表达式为”^“。

创建rabbitmq集群的Erlang cookie，配置文件rabbitmq-secret.yml内容如下：

apiVersion: v1
kind: Secret
metadata:
  name: rabbitmq-config
  namespace: default
data:
  erlang-cookie: |-
    MTIzNDU2Nzg5MAo=

使用statefulset启动rabbitmq，配置文件rabbitmq-sts.yml内容如下：

apiVersion: apps/v1beta1
kind: StatefulSet
metadata:
  name: rabbitmq
spec:
  serviceName: rabbitmq
  replicas: 3
  template:
    metadata:
      labels:
        app: rabbitmq
    spec:
      containers:
      - name: rabbitmq
        image: rabbitmq:3.12-management
        lifecycle:
          postStart:
            exec:
              command:
              - /bin/sh
              - -c
              - >
                if [ -z "$(grep rabbitmq /etc/resolv.conf)" ]; then
                  sed "s/^search \([^ ]\+\)/search rabbitmq.\1 \1/" /etc/resolv.conf > /etc/resolv.conf.new;
                  cat /etc/resolv.conf.new > /etc/resolv.conf;
                  rm /etc/resolv.conf.new;
                fi;
                until rabbitmqctl node_health_check; do sleep 1; done;
                if [[ "$HOSTNAME" != "rabbitmq-0" && -z "$(rabbitmqctl cluster_status | grep rabbitmq-0)" ]]; then
                  rabbitmqctl stop_app;
                  rabbitmqctl join_cluster rabbit@rabbitmq-0;
                  rabbitmqctl start_app;
                fi;
                rabbitmqctl set_policy ha-all "." '{"ha-mode":"exactly","ha-params":3,"ha-sync-mode":"automatic"}'
        env:
        - name: RABBITMQ_ERLANG_COOKIE
          valueFrom:
            secretKeyRef:
              name: rabbitmq-config
              key: erlang-cookie
        ports:
        - containerPort: 5672
          name: amqp
        volumeMounts:
        - name: rabbitmq
          mountPath: /var/lib/rabbitmq
  volumeClaimTemplates:
  - metadata:
      name: rabbitmq
      annotations:
        volume.alpha.kubernetes.io/storage-class: anything
    spec:
      accessModes: [ "ReadWriteOnce" ]
      resources:
        requests:
          storage: 2Gi

注：必须准备好存储卷后，pod才能启动。

rabbitmq服务配置文件rabbitmq-svc.yml内容如下，对外开放http端口，其它端口在集群内部使用。

apiVersion: v1
kind: Service
metadata:
  # Expose the management HTTP port on each node
  name: rabbitmq-management
  labels:
    app: rabbitmq
spec:
  selector:
    app: rabbitmq
  type: NodePort
  ports:
  - port: 15672
    name: http
    nodePort: 30072

---

apiVersion: v1
kind: Service
metadata:
  # The required headless service for StatefulSets
  name: rabbitmq
  labels:
    app: rabbitmq
spec:
  selector:
    app: rabbitmq
  clusterIP: None
  ports:
  - port: 5672
    name: amqp
  - port: 4369
    name: epmd
  - port: 25672
    name: rabbitmq-dist

启动rabbitmq集群

kubectl apply -f rabbitmq-secret.yml
kubectl apply -f rabbitmq-sts.yml
kubectl apply -f rabbitmq-svc.yml

# 默认用户名guest，默认密码guest
# 代理连接地址：rabbitmq.default:5672
# 管理界面地址：node-ip:30072

Direct类型消息队列的golang示例

生产端示例代码

package main

import (
    "context"
    "fmt"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "direct-exchange-demo"
    queueName    = "direct-queue-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()

    routingKey1 := "info"
    exchange1 := NewDirectExchange(exchangeName, routingKey1)
    p1, err := NewProducer(queueName, conn, exchange1)
    checkErr(err)
    defer p1.Close()

    routingKey2 := "warning"
    exchange2 := NewDirectExchange(exchangeName, routingKey2)
    p2, err := NewProducer(queueName, conn, exchange2)
    checkErr(err)
    defer p2.Close()

    var body string
    count := 0
    for i := 1; i <= 5; i++ {
        body = fmt.Sprintf("%s message %d", routingKey1, i)
        err = p1.Publish(ctx, []byte(body)) // p1 发送消息
        checkErr(err)

        body = fmt.Sprintf("%s message %d", routingKey2, i)
        err = p2.Publish(ctx, []byte(body)) // p2 发送消息
        checkErr(err)
        count += 2
    }
    fmt.Println("publish total", count)
}

// Exchange 交换机
type Exchange struct {
    Name       string // exchange名称
    Type       string // exchange类型
    RoutingKey string // 路由key
}

// NewDirectExchange 实例化一个direct类型交换机
func NewDirectExchange(exchangeName string, routingKey string) *Exchange {
    return &Exchange{
        Name:       exchangeName,
        Type:       "direct",
        RoutingKey: routingKey,
    }
}

// Producer 生产者对象
type Producer struct {
    queueName string
    exchange  *Exchange
    conn      *amqp.Connection
    ch        *amqp.Channel
}

// NewProducer 实例化一个生产者
func NewProducer(queueName string, conn *amqp.Connection, exchange *Exchange) (*Producer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, // 交换机的类型
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,              // 队列名称
        exchange.RoutingKey, // 路由key
        exchange.Name,       // 交换机名称
        false,
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Producer{
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        exchange:  exchange,
    }, nil
}

// Publish 发送消息
func (p *Producer) Publish(ctx context.Context, body []byte) error {
    err := p.ch.PublishWithContext(
        ctx,
        p.exchange.Name,       // exchange name
        p.exchange.RoutingKey, // key
        false,                 // mandatory 如果为true，根据自身exchange类型和routingKey规则无法找到符合条件的队列会把消息返还给发送者
        false,                 // immediate 如果为true，当exchange发送消息到队列后发现队列上没有消费者，则会把消息返还给发送者
        amqp.Publishing{
            //DeliveryMode: amqp.Persistent, // 如果队列的声明是持久化的，那么消息也设置为持久化
            ContentType: "text/plain",
            Body:        body,
        },
    )
    if err != nil {
        return err
    }
    fmt.Println("[send]: " + string(body))
    return nil
}

// Close 关闭生产者
func (p *Producer) Close() {
    if p.ch != nil {
        _ = p.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

消费端示例代码

package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "sync/atomic"
    "syscall"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "direct-exchange-demo"
    queueName    = "direct-queue-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()

    routingKey1 := "info"
    exchange1 := NewDirectExchange(exchangeName, routingKey1)
    c1, err := NewConsumer(ctx, queueName, exchange1, conn)
    checkErr(err)
    c1.Consume() // 消费消息
    defer c1.Close()

    routingKey2 := "warning"
    exchange2 := NewDirectExchange(exchangeName, routingKey2)
    c2, err := NewConsumer(ctx, queueName, exchange2, conn)
    checkErr(err)
    c2.Consume() // 消费消息
    defer c2.Close()

    fmt.Println("exit press CTRL+C")
    exit := make(chan os.Signal, 1)
    signal.Notify(exit, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
    <-exit
    fmt.Println("exit consume messages,  received total", counter)
}

// Exchange 交换机
type Exchange struct {
    Name       string // exchange名称
    Type       string // exchange类型，支持"direct"、"topic"、"fanout"、"headers"
    RoutingKey string // 路由key
}

// NewDirectExchange 实例化一个direct类型交换机
func NewDirectExchange(exchangeName string, routingKey string) *Exchange {
    return &Exchange{
        Name:       exchangeName,
        Type:       "direct",
        RoutingKey: routingKey,
    }
}

// Consumer 消费者
type Consumer struct {
    ctx       context.Context
    queueName string
    conn      *amqp.Connection
    ch        *amqp.Channel
    delivery  <-chan amqp.Delivery
    exchange  *Exchange
}

// NewConsumer 实例化一个消费者
func NewConsumer(ctx context.Context, queueName string, exchange *Exchange, conn *amqp.Connection) (*Consumer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, // 交换机的类型
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,
        exchange.RoutingKey,
        exchange.Name,
        false,
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    delivery, err := ch.ConsumeWithContext(
        ctx,
        queueName, // queue 名称
        "",        // consumer 用来区分多个消费者
        true,      // auto-ack 是否自动应答
        false,     // exclusive 是否独有
        false,     // no-local 如果设置为true，表示不能将同一个Connection中生产者发送的消息传递给这个Connection中的消费者
        false,     // no-wait 是否阻塞
        nil,       // args
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Consumer{
        ctx:       ctx,
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        delivery:  delivery,
        exchange:  exchange,
    }, nil
}

var counter int32 = 0

// Consume 接收消息
func (c *Consumer) Consume() {
    go func() {
        fmt.Printf("waiting for messages, type=%s, queue=%s, key=%s\n", c.exchange.Type, c.queueName, c.exchange.RoutingKey)
        for d := range c.delivery {
            // 处理消息
            if d.RoutingKey == "info" {
                fmt.Printf("[info received]: %s\n", d.Body)
            } else if d.RoutingKey == "warning" {
                fmt.Printf("[warning received]: %s\n", d.Body)
            }
            atomic.AddInt32(&counter, 1)
            // _ = d.Ack(false) // 如果auto-ack为false时，需要手动ack
        }
    }()
}

// Close 关闭
func (c *Consumer) Close() {
    if c.ch != nil {
        _ = c.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

topic类型消息队列的golang示例

topic中，将routingkey通过”.“来分为多个部分，匹配规则

• “*“：代表一个部分，例如routingkey为key1.*或*.key2， topic=key1.key2都可以匹配
• ”#“：代表0个或多个部分，例如routingkey为key1.#或#.key3， topic=key1.key2.key3都可以匹配，注意：如果绑定的路由键为 “#” 时，则接受所有消息，因为路由键所有都匹配。

生产端示例代码

package main

import (
    "context"
    "fmt"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "topic-exchange-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()

    queueName := "topic-queue-1"
    exchange := NewTopicExchange(exchangeName, "*.orange.*")
    p, err := NewProducer(queueName, conn, exchange)
    checkErr(err)
    key := "key1.orange.key3"
    err = p.Publish(ctx, key, []byte(key+" say hello"))
    checkErr(err)
    defer p.Close()

    queueName = "topic-queue-2"
    exchange = NewTopicExchange(exchangeName, "*.*.rabbit")
    p, err = NewProducer(queueName, conn, exchange)
    checkErr(err)
    defer p.Close()
    key = "key1.key2.rabbit"
    err = p.Publish(ctx, key, []byte(key+" say hello"))
    checkErr(err)

    exchange = NewTopicExchange(exchangeName, "lazy.#")
    p, err = NewProducer(queueName, conn, exchange)
    checkErr(err)
    defer p.Close()
    key = "lazy.key2.key3"
    err = p.Publish(ctx, key, []byte(key+" say hello"))
    checkErr(err)
}

// Exchange 交换机
type Exchange struct {
    Name       string // exchange名称
    Type       string // exchange类型，支持"direct"、"topic"、"fanout"、"headers"
    RoutingKey string // 路由key
}

// NewTopicExchange 实例化一个topic类型交换机
func NewTopicExchange(exchangeName string, routingKey string) *Exchange {
    return &Exchange{
        Name:       exchangeName,
        Type:       "topic",
        RoutingKey: routingKey,
    }
}

// Producer 生产者对象
type Producer struct {
    queueName string
    exchange  *Exchange
    conn      *amqp.Connection
    ch        *amqp.Channel
}

// NewProducer 实例化一个生产者
func NewProducer(queueName string, conn *amqp.Connection, exchange *Exchange) (*Producer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, // 交换机的类型，支持direct、topic、fanout、headers
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,
        exchange.RoutingKey,
        exchange.Name,
        false,
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Producer{
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        exchange:  exchange,
    }, nil
}

// Publish 发送消息
func (p *Producer) Publish(ctx context.Context, routingKey string, body []byte) error {
    err := p.ch.PublishWithContext(
        ctx,
        p.exchange.Name, // exchange name
        routingKey,      // key
        false,           // mandatory 如果为true，根据自身exchange类型和routingKey规则无法找到符合条件的队列会把消息返还给发送者
        false,           // immediate 如果为true，当exchange发送消息到队列后发现队列上没有消费者，则会把消息返还给发送者
        amqp.Publishing{
            ContentType: "text/plain",
            Body:        body,
        },
    )
    if err != nil {
        return err
    }
    fmt.Printf("[send]: %s\n", body)
    return nil
}

// Close 关闭
func (p *Producer) Close() {
    if p.ch != nil {
        _ = p.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

消费端示例代码

package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "syscall"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "topic-exchange-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()
    var queueName string // 对应的发送端的队列名称，如果发送的key模糊匹配命中，可以接收到消息

    queueName = "topic-queue-1"
    exchange := NewTopicExchange(exchangeName, "*.orange.*")
    queue, err := NewConsumer(ctx, queueName, exchange, conn)
    checkErr(err)
    queue.Consume()
    defer queue.Close()

    queueName = "topic-queue-2"
    exchange = NewTopicExchange(exchangeName, "*.*.rabbit")
    queue, err = NewConsumer(ctx, queueName, exchange, conn)
    checkErr(err)
    defer queue.Close()
    queue.Consume()
    exchange = NewTopicExchange(exchangeName, "lazy.#")
    queue, err = NewConsumer(ctx, queueName, exchange, conn)
    checkErr(err)
    defer queue.Close()
    queue.Consume()

    fmt.Println("exit press CTRL+C")
    interrupt := make(chan os.Signal, 1)
    signal.Notify(interrupt, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
    <-interrupt
    fmt.Println("exit consume messages")
}

// Exchange 交换机
type Exchange struct {
    Name       string // exchange名称
    Type       string // exchange类型，支持"direct"、"topic"、"fanout"、"headers"
    RoutingKey string // 路由key
}

// NewTopicExchange 实例化一个topic类型交换机
func NewTopicExchange(exchangeName string, routingKey string) *Exchange {
    return &Exchange{
        Name:       exchangeName,
        Type:       "topic",
        RoutingKey: routingKey,
    }
}

// Consumer 消费者
type Consumer struct {
    ctx       context.Context
    queueName string
    conn      *amqp.Connection
    ch        *amqp.Channel
    delivery  <-chan amqp.Delivery
    exchange  *Exchange
}

// NewConsumer 实例化一个消费者
func NewConsumer(ctx context.Context, queueName string, exchange *Exchange, conn *amqp.Connection) (*Consumer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, // 交换机的类型
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,
        exchange.RoutingKey,
        exchange.Name,
        false,
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 为消息队列注册消费者
    delivery, err := ch.ConsumeWithContext(
        ctx,
        queueName, // queue 名称
        "",        // consumer 用来区分多个消费者
        true,      // auto-ack 是否自动应答
        false,     // exclusive 是否独有
        false,     // no-local 如果设置为true，表示不能将同一个Connection中生产者发送的消息传递给这个Connection中的消费者
        false,     // no-wait 是否阻塞
        nil,       // args
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Consumer{
        ctx:       ctx,
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        delivery:  delivery,
        exchange:  exchange,
    }, nil
}

// Consume 接收消息
func (c *Consumer) Consume() {
    go func() {
        fmt.Printf("waiting for messages, type=%s, queue=%s, key=%s\n", c.exchange.Type, c.queueName, c.exchange.RoutingKey)
        for d := range c.delivery {
            // 处理消息
            fmt.Printf("[%s received]: %s\n", c.queueName, d.Body)
            // _ = d.Ack(false) // 如果auto-ack为false时，需要手动ack
        }
    }()
}

// Close 关闭
func (c *Consumer) Close() {
    if c.ch != nil {
        _ = c.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

fanout类型消息队列的golang示例

fanout类型的交换机会将消息分发给所有绑定了此交换机的队列，此时routingkey参数相当于无效。可以使用fanout来实现发布订阅。

生产端示例代码

package main

import (
    "context"
    "fmt"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "fanout-exchange-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()

    queueName := "fanout-queue-1"
    exchange := NewFanOutExchange(exchangeName)
    p, err := NewProducer(queueName, conn, exchange)
    checkErr(err)
    defer p.Close()
    err = p.Publish(ctx, []byte(queueName+" say hello"))
    checkErr(err)

    queueName = "fanout-queue-2"
    exchange = NewFanOutExchange(exchangeName)
    p, err = NewProducer(queueName, conn, exchange)
    checkErr(err)
    defer p.Close()
    err = p.Publish(ctx, []byte(queueName+" say hello"))
    checkErr(err)

    queueName = "fanout-queue-3"
    exchange = NewFanOutExchange(exchangeName)
    p, err = NewProducer(queueName, conn, exchange)
    checkErr(err)
    defer p.Close()
    err = p.Publish(ctx, []byte(queueName+" say hello"))
    checkErr(err)
}

// Exchange 交换机
type Exchange struct {
    Name       string // exchange名称
    Type       string // exchange类型，支持direct、topic、fanout、headers
    RoutingKey string // 路由key
}

// NewFanOutExchange 实例化一个fanout类型交换机
func NewFanOutExchange(exchangeName string) *Exchange {
    return &Exchange{
        Name:       exchangeName,
        Type:       "fanout",
        RoutingKey: "",
    }
}

// Producer 生产者对象
type Producer struct {
    queueName string
    exchange  *Exchange
    conn      *amqp.Connection
    ch        *amqp.Channel
}

// NewProducer 实例化一个生产者
func NewProducer(queueName string, conn *amqp.Connection, exchange *Exchange) (*Producer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, // 交换机的类型
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,
        exchange.RoutingKey, // 如果交换机类型为fanout，此参数无效
        exchange.Name,
        false,
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Producer{
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        exchange:  exchange,
    }, nil
}

// Publish 发送消息
func (p *Producer) Publish(ctx context.Context, body []byte) error {
    err := p.ch.PublishWithContext(
        ctx,
        p.exchange.Name, // exchange name
        "",              // key  如果类型为fanout，此参数无效
        false,           // mandatory 如果为true，根据自身exchange类型和routingKey规则无法找到符合条件的队列会把消息返还给发送者
        false,           // immediate 如果为true，当exchange发送消息到队列后发现队列上没有消费者，则会把消息返还给发送者
        amqp.Publishing{
            ContentType: "text/plain",
            Body:        body,
        },
    )
    if err != nil {
        return err
    }
    fmt.Printf("[send]: %s\n", body)
    return nil
}

// Close 关闭生产者
func (p *Producer) Close() {
    if p.ch != nil {
        _ = p.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

消费端示例代码

package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "syscall"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "fanout-exchange-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()
    var queueName string // 对应的发送端的队列名称，如果发送的key模糊匹配命中，可以接收到消息

    queueName = "fanout-queue"
    exchange := NewFanOutExchange(exchangeName)
    queue, err := NewConsumer(ctx, queueName, exchange, conn)
    checkErr(err)
    queue.Consume() // 消费消息
    defer queue.Close()

    fmt.Println("exit press CTRL+C")
    interrupt := make(chan os.Signal, 1)
    signal.Notify(interrupt, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
    <-interrupt
    fmt.Println("exit consume messages")
}

// Exchange 交换机
type Exchange struct {
    Name       string // exchange名称
    Type       string // exchange类型，支持"direct"、"topic"、"fanout"、"headers"
    RoutingKey string // 路由key
}

// NewFanOutExchange 实例化一个fanout类型交换机
func NewFanOutExchange(exchangeName string) *Exchange {
    return &Exchange{
        Name:       exchangeName,
        Type:       "fanout",
        RoutingKey: "",
    }
}

// Consumer 消费者
type Consumer struct {
    ctx       context.Context
    queueName string
    conn      *amqp.Connection
    ch        *amqp.Channel
    delivery  <-chan amqp.Delivery
    exchange  *Exchange
}

// NewConsumer 实例化一个消费者
func NewConsumer(ctx context.Context, queueName string, exchange *Exchange, conn *amqp.Connection) (*Consumer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, // 交换机的类型
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,              // 队列名称
        exchange.RoutingKey, // 如果是fanout类型，无效
        exchange.Name,       // 交换机名称
        false,
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 为消息队列注册消费者
    delivery, err := ch.ConsumeWithContext(
        ctx,
        queueName, // queue 名称
        "",        // consumer 用来区分多个消费者
        true,      // auto-ack 是否自动应答
        false,     // exclusive 是否独有
        false,     // no-local 如果设置为true，表示不能将同一个Connection中生产者发送的消息传递给这个Connection中的消费者
        false,     // no-wait 是否阻塞
        nil,       // args
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Consumer{
        ctx:       ctx,
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        delivery:  delivery,
        exchange:  exchange,
    }, nil
}

// Consume 接收消息
func (c *Consumer) Consume() {
    go func() {
        fmt.Printf("waiting for messages, queue = %s\n", c.queueName)
        for d := range c.delivery {
            // 处理消息
            fmt.Printf("[%s received]: %s\n", c.queueName, d.Body)
            // _ = d.Ack(false) // 如果auto-ack为false时，需要手动ack
        }
    }()
}

// Close 关闭
func (c *Consumer) Close() {
    if c.ch != nil {
        _ = c.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

header类型消息队列的golang示例

headers匹配AMQP消息的header而不是路由键，此时routingkey参数相当于无效，headers交换机和direct交换机类似。

消费方指定的headers中必须指定一个”x-match”的键，键”x-match”的值只有2个

• x-match=all：表示所有的键值对都匹配才能接收到消息
• x-match=any：表示只要键值对匹配就能接收消息

生产端示例代码

package main

import (
    "context"
    "fmt"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "headers-exchange-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()

    // 完全匹配headers，消费端才能收到消息
    queueName1 := "headers-queue-1"
    kv1 := map[string]interface{}{"hello1": "world1", "foo1": "bar1"}
    exchange1 := NewHeaderExchange(exchangeName, "all", kv1)
    p1, err := NewProducer(queueName1, conn, exchange1)
    checkErr(err)
    defer p1.Close()
    headersKey1 := kv1 // 完全匹配，消费端队列可以收到消息
    err = p1.Publish(ctx, headersKey1, []byte(p1.queueName+" say hello 1"))
    checkErr(err)
    headersKey1 = map[string]interface{}{"k": "v"} // 完全不匹配，消费端队列不能收到消息
    err = p1.Publish(ctx, headersKey1, []byte(p1.queueName+" say hello 2"))
    checkErr(err)
    headersKey1 = map[string]interface{}{"foo1": "bar1"} // 部分匹配，消费端队列不能收到消息
    err = p1.Publish(ctx, headersKey1, []byte(p1.queueName+" say hello 3"))
    checkErr(err)

    // 部分匹配headers，消费端能收到消息
    queueName2 := "headers-queue-2"
    kv2 := map[string]interface{}{"hello2": "world2", "foo2": "bar2"}
    exchange2 := NewHeaderExchange(exchangeName, "any", kv2)
    p2, err := NewProducer(queueName2, conn, exchange2)
    checkErr(err)
    defer p2.Close()
    headersKey2 := kv2 // 完全匹配，消费端队列可以收到消息
    err = p2.Publish(ctx, headersKey2, []byte(p2.queueName+" say hello 4"))
    checkErr(err)
    headersKey2 = map[string]interface{}{"k": "v"} // 完全不匹配，消费端队列不能收到消息
    err = p2.Publish(ctx, headersKey2, []byte(p2.queueName+" say hello 5"))
    checkErr(err)
    headersKey2 = map[string]interface{}{"foo2": "bar2"} // 部分匹配，消费端队列可以收到消息
    err = p2.Publish(ctx, headersKey2, []byte(p2.queueName+" say hello 6"))
    checkErr(err)
}

// Exchange 交换机
type Exchange struct {
    Name       string                 // exchange名称
    Type       string                 // exchange类型，支持"direct"、"topic"、"fanout"、"headers"
    RoutingKey string                 // 路由key，如果类型为fanout和headers，此字段无效，不需要设置
    Headers    map[string]interface{} // 如果类型为headers，此字段必填
}

// NewHeaderExchange 实例化一个header类型的交换机，headerType支持all和any
func NewHeaderExchange(exchangeName string, headerType string, kv map[string]interface{}) *Exchange {
    if kv == nil {
        kv = make(map[string]interface{})
    }

    switch headerType {
    case "all", "any":
        kv["x-match"] = headerType
    default:
        kv["x-match"] = "all"
    }

    return &Exchange{
        Name:       exchangeName,
        Type:       "headers",
        RoutingKey: "",
        Headers:    kv,
    }
}

// Producer 生产者对象
type Producer struct {
    queueName string
    exchange  *Exchange
    conn      *amqp.Connection
    ch        *amqp.Channel
}

// NewProducer 实例化一个生产者
func NewProducer(queueName string, conn *amqp.Connection, exchange *Exchange) (*Producer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, // 交换机的类型
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,
        exchange.RoutingKey,
        exchange.Name,
        false,
        exchange.Headers,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Producer{
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        exchange:  exchange,
    }, nil
}

// Publish 发送消息
func (p *Producer) Publish(ctx context.Context, headers map[string]interface{}, body []byte) error {
    err := p.ch.PublishWithContext(
        ctx,
        p.exchange.Name,       // exchange name
        p.exchange.RoutingKey, // key
        false,                 // mandatory 如果为true，根据自身exchange类型和routingKey规则无法找到符合条件的队列会把消息返还给发送者
        false,                 // immediate 如果为true，当exchange发送消息到队列后发现队列上没有消费者，则会把消息返还给发送者
        amqp.Publishing{
            Headers:     headers,
            ContentType: "text/plain",
            Body:        body,
        },
    )
    if err != nil {
        return err
    }
    fmt.Printf("[send]: %s\n", body)
    return nil
}

// Close 关闭生产者
func (p *Producer) Close() {
    if p.ch != nil {
        _ = p.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

消费端示例代码

package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "syscall"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "headers-exchange-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()

    queueName1 := "headers-queue-1"
    kv1 := map[string]interface{}{"hello1": "world1", "foo1": "bar1"}
    exchange1 := NewHeadersExchange(exchangeName, "all", kv1)
    c1, err := NewConsumer(ctx, queueName1, exchange1, conn)
    checkErr(err)
    c1.Consume()
    defer c1.Close()

    queueName2 := "headers-queue-2"
    kv2 := map[string]interface{}{"hello2": "world2", "foo2": "bar2"}
    exchange2 := NewHeadersExchange(exchangeName, "any", kv2)
    c2, err := NewConsumer(ctx, queueName2, exchange2, conn)
    checkErr(err)
    c2.Consume()
    defer c2.Close()

    fmt.Println("exit press CTRL+C")
    interrupt := make(chan os.Signal, 1)
    signal.Notify(interrupt, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
    <-interrupt
    fmt.Println("exit consume messages")
}

// Exchange 交换机
type Exchange struct {
    Name       string                 // exchange名称
    Type       string                 // exchange类型，支持"direct"、"topic"、"fanout"、"headers"
    RoutingKey string                 // 路由key，如果类型为fanout和headers，此字段无效，不需要设置
    Headers    map[string]interface{} // 如果类型为headers，此字段必填
}

// NewHeadersExchange 创建一个header类型的交换机，headerType支持all和any
func NewHeadersExchange(exchangeName string, headerType string, kv map[string]interface{}) *Exchange {
    if kv == nil {
        kv = make(map[string]interface{})
    }

    switch headerType {
    case "all", "any":
        kv["x-match"] = headerType
    default:
        kv["x-match"] = "all"
    }

    return &Exchange{
        Name:       exchangeName,
        Type:       "headers",
        RoutingKey: "",
        Headers:    kv,
    }
}

// Consumer 消费者
type Consumer struct {
    ctx       context.Context
    queueName string
    conn      *amqp.Connection
    ch        *amqp.Channel
    delivery  <-chan amqp.Delivery
    exchange  *Exchange
}

// NewConsumer 实例化一个消费者
func NewConsumer(ctx context.Context, queueName string, exchange *Exchange, conn *amqp.Connection) (*Consumer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, // 交换机的类型
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,
        exchange.RoutingKey,
        exchange.Name,
        false,
        exchange.Headers,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 为消息队列注册消费者
    delivery, err := ch.ConsumeWithContext(
        ctx,
        queueName, // queue 名称
        "",        // consumer 用来区分多个消费者
        true,      // auto-ack 是否自动应答
        false,     // exclusive 是否独有
        false,     // no-local 如果设置为true，表示不能将同一个Connection中生产者发送的消息传递给这个Connection中的消费者
        false,     // no-wait 是否阻塞
        nil,       // args
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Consumer{
        ctx:       ctx,
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        delivery:  delivery,
        exchange:  exchange,
    }, nil
}

// Consume 接收消息
func (c *Consumer) Consume() {
    go func() {
        fmt.Printf("waiting for messages, queue = %s\n", c.queueName)
        for d := range c.delivery {
            // 处理消息
            fmt.Printf("[%s received]: %s\n", c.queueName, d.Body)
            // _ = d.Ack(false) // 如果auto-ack为false时，需要手动ack
        }
    }()
}

// Close 关闭
func (c *Consumer) Close() {
    if c.ch != nil {
        _ = c.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

延时类型消息队列的golang示例代码

rabbitMQ默认不支持延时消息队列类型，需要另外安装插件来实现，使用延时队列需要指定具体一种消息类型(direct、topic、fanout、headers)，下面以direct类型的延时消息队列为例。

生产端示例代码

package main

import (
    "context"
    "fmt"
    "strconv"
    "time"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "delayed-message-exchange-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()

    queueName := "delayed-message-queue"
    routingKey := "delayed-key"
    delayedMessageType := "direct"
    exchange := NewDelayedMessageExchange(exchangeName, delayedMessageType, routingKey)
    q, err := NewProducer(queueName, conn, exchange)
    checkErr(err)
    defer q.Close()
    for i := 1; i <= 5; i++ {
        body := time.Now().Format("2006-01-02 15:04:05.000") + " hello world " + strconv.Itoa(i)
        err = q.Publish(ctx, time.Second*5, []byte(body)) // 发送消息
        checkErr(err)
        time.Sleep(time.Second)
    }
}

// Exchange 交换机
type Exchange struct {
    Name                string // exchange名称
    Type                string // exchange类型，支持direct、topic、fanout、headers、x-delayed-message
    RoutingKey          string // 路由key
    XDelayedMessageType string // 延时消息类型，支持direct、topic、fanout、headers
}

// NewDelayedMessageExchange 实例化一个delayed-message类型交换机，参数delayedMessageType 消息类型direct、topic、fanout、headers
func NewDelayedMessageExchange(exchangeName string, delayedMessageType string, routingKey string) *Exchange {
    return &Exchange{
        Name:                exchangeName,
        Type:                "x-delayed-message",
        RoutingKey:          routingKey,
        XDelayedMessageType: delayedMessageType,
    }
}

// Producer 生产者对象
type Producer struct {
    queueName string
    exchange  *Exchange
    conn      *amqp.Connection
    ch        *amqp.Channel
}

// NewProducer 实例化一个生产者
func NewProducer(queueName string, conn *amqp.Connection, exchange *Exchange) (*Producer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, //  x-delayed-message
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        amqp.Table{
            "x-delayed-type": exchange.XDelayedMessageType, // 延时消息的类型direct、topic、fanout、headers
        },
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,
        exchange.RoutingKey,
        exchange.Name,
        false,
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Producer{
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        exchange:  exchange,
    }, nil
}

// Publish 发送消息
func (p *Producer) Publish(ctx context.Context, delayTime time.Duration, body []byte) error {
    err := p.ch.PublishWithContext(
        ctx,
        p.exchange.Name,       // exchange name
        p.exchange.RoutingKey, // key
        false,                 // mandatory 如果为true，根据自身exchange类型和routingKey规则无法找到符合条件的队列会把消息返还给发送者
        false,                 // immediate 如果为true，当exchange发送消息到队列后发现队列上没有消费者，则会把消息返还给发送者
        amqp.Publishing{
            DeliveryMode: amqp.Persistent, // 如果队列的声明是持久化的，那么消息也设置为持久化
            ContentType:  "text/plain",
            Body:         body,
            Headers: amqp.Table{
                "x-delay": int(delayTime / time.Millisecond), // 延迟时间: 毫秒
            },
        },
    )
    if err != nil {
        return err
    }
    fmt.Printf("[send]: %s\n", body)
    return nil
}

// Close 关闭生产者
func (p *Producer) Close() {
    if p.ch != nil {
        _ = p.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

消费端示例代码

package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "syscall"
    "time"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "delayed-message-exchange-demo"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()

    queueName := "delayed-message-queue"
    routingKey := "delayed-key"
    delayedMessageType := "direct"
    exchange := NewDelayedMessageExchange(exchangeName, delayedMessageType, routingKey)
    c, err := NewConsumer(ctx, queueName, exchange, conn)
    checkErr(err)
    c.Consume() // 消费消息
    defer c.Close()

    fmt.Println("exit press CTRL+C")
    interrupt := make(chan os.Signal, 1)
    signal.Notify(interrupt, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
    <-interrupt
    fmt.Println("exit consume messages")
}

// Exchange 交换机
type Exchange struct {
    Name                string // exchange名称
    Type                string // exchange类型，支持direct、topic、fanout、headers、x-delayed-message
    RoutingKey          string // 路由key
    XDelayedMessageType string // 延时消息类型，支持direct、topic、fanout、headers
}

// NewDelayedMessageExchange 实例化一个delayed-message类型交换机，参数delayedMessageType 消息类型direct、topic、fanout、headers
func NewDelayedMessageExchange(exchangeName string, delayedMessageType string, routingKey string) *Exchange {
    return &Exchange{
        Name:                exchangeName,
        Type:                "x-delayed-message",
        RoutingKey:          routingKey,
        XDelayedMessageType: delayedMessageType,
    }
}

// Consumer 消费者
type Consumer struct {
    ctx       context.Context
    queueName string
    conn      *amqp.Connection
    ch        *amqp.Channel
    delivery  <-chan amqp.Delivery
    exchange  *Exchange
}

// NewConsumer 实例化一个消费者
func NewConsumer(ctx context.Context, queueName string, exchange *Exchange, conn *amqp.Connection) (*Consumer, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchange.Name, // 交换机名称
        exchange.Type, // 交换机的类型，支持direct、topic、fanout、headers
        true,          // 是否持久化
        false,         // 是否自动删除
        false,         // 是否公开，false即公开
        false,         // 是否等待
        amqp.Table{
            "x-delayed-type": exchange.XDelayedMessageType, // 延时消息的类型direct、topic、fanout、headers
        },
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,
        exchange.RoutingKey,
        exchange.Name,
        false,
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 为消息队列注册消费者
    delivery, err := ch.ConsumeWithContext(
        ctx,
        queueName, // queue 名称
        "",        // consumer 用来区分多个消费者
        true,      // auto-ack 是否自动应答
        false,     // exclusive 是否独有
        false,     // no-local 如果设置为true，表示不能将同一个Connection中生产者发送的消息传递给这个Connection中的消费者
        false,     // no-wait 是否阻塞
        nil,       // args
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Consumer{
        queueName: queueName,
        conn:      conn,
        ch:        ch,
        delivery:  delivery,
        exchange:  exchange,
    }, nil
}

// Consume 接收消息
func (c *Consumer) Consume() {
    go func() {
        fmt.Printf("waiting for messages, type=%s, queue=%s, key=%s\n", c.exchange.Type, c.queueName, c.exchange.RoutingKey)
        for d := range c.delivery {
            // 处理消息
            fmt.Printf("%s %s [received]: %s\n", time.Now().Format("2006-01-02 15:04:05.000"), c.exchange.RoutingKey, d.Body)
            // _ = d.Ack(false) // 如果auto-ack为false时，需要手动ack
        }
    }()
}

// Close 关闭
func (c *Consumer) Close() {
    if c.ch != nil {
        _ = c.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

发布订阅的golang示例代码

发布订阅是在fanout消息类型基础上实现的。

发布端示例代码

package main

import (
    "context"
    "fmt"
    "strconv"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "pub-sub"
)

func main() {
    // 连接rabbitmq
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    // 实例化一个发布者
    p, err := NewPublisher(exchangeName, conn)
    checkErr(err)
    defer p.Close()

    ctx := context.Background()

    // 发送消息
    for i := 1; i <= 10; i++ {
        err = p.Publish(ctx, []byte("hello world "+strconv.Itoa(i)))
        checkErr(err)
    }
}

// Publisher 发布者
type Publisher struct {
    exchangeName string
    conn         *amqp.Connection
    ch           *amqp.Channel
}

// NewPublisher 实例化一个发布者
func NewPublisher(exchangeName string, conn *amqp.Connection) (*Publisher, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchangeName, // 交换机名称
        "fanout",     // 交换机的类型
        true,         // 是否持久化
        false,        // 是否自动删除
        false,        // 是否公开，false即公开
        false,        // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Publisher{
        exchangeName: exchangeName,
        conn:         conn,
        ch:           ch,
    }, nil
}

func (p *Publisher) Publish(ctx context.Context, body []byte) error {
    err := p.ch.PublishWithContext(
        ctx,
        p.exchangeName, // exchange name
        "",             // 消息类型为fanout，此参数无效
        false,          // mandatory 如果为true，根据自身exchange类型和routingKey规则无法找到符合条件的队列会把消息返还给发送者
        false,          // immediate 如果为true，当exchange发送消息到队列后发现队列上没有消费者，则会把消息返还给发送者
        amqp.Publishing{
            ContentType: "text/plain",
            Body:        body,
        },
    )
    if err != nil {
        return err
    }
    fmt.Printf("[send]: %s\n", body)
    return nil
}

// Close 关闭生产者
func (p *Publisher) Close() {
    if p.ch != nil {
        _ = p.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

订阅端示例代码

package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "syscall"

    amqp "github.com/rabbitmq/amqp091-go"
)

var (
    url          = "amqp://guest:guest@192.168.3.37:5672/"
    exchangeName = "pub-sub"
)

func main() {
    conn, err := amqp.Dial(url)
    checkErr(err)
    defer conn.Close()

    ctx := context.Background()

    queueName1 := "pub-sub-queue-1"
    s1, err := NewSubscriber(ctx, exchangeName, queueName1, conn)
    checkErr(err)
    s1.Subscribe() // 消费信息
    defer s1.Close()

    queueName2 := "pub-sub-queue-2"
    s2, err := NewSubscriber(ctx, exchangeName, queueName2, conn)
    checkErr(err)
    s2.Subscribe() // 消费信息
    defer s2.Close()

    fmt.Println("exit press CTRL+C")
    interrupt := make(chan os.Signal, 1)
    signal.Notify(interrupt, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
    <-interrupt
    fmt.Println("finished receiving messages")
}

// Subscriber 订阅者
type Subscriber struct {
    ctx          context.Context
    exchangeName string
    queueName    string
    conn         *amqp.Connection
    ch           *amqp.Channel
    delivery     <-chan amqp.Delivery
}

// NewSubscriber 实例化一个订阅者
func NewSubscriber(ctx context.Context, exchangeName string, queueName string, conn *amqp.Connection) (*Subscriber, error) {
    // 创建管道
    ch, err := conn.Channel()
    if err != nil {
        return nil, err
    }

    // 声明交换机类型
    err = ch.ExchangeDeclare(
        exchangeName, // 交换机名称
        "fanout",     // 交换机的类型
        true,         // 是否持久化
        false,        // 是否自动删除
        false,        // 是否公开，false即公开
        false,        // 是否等待
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 声明队列，如果队列不存在则自动创建，存在则跳过创建
    q, err := ch.QueueDeclare(
        queueName, // 消息队列名称
        true,      // 是否持久化
        false,     // 是否自动删除
        false,     // 是否具有排他性(仅创建它的程序才可用)
        false,     // 是否阻塞处理
        nil,       // 额外的属性
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 绑定队列和交换机
    err = ch.QueueBind(
        q.Name,       // 队列名称
        "",           // 消息类型为fanout时无效
        exchangeName, // 交换机名称
        false,
        nil,
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    // 为消息队列注册消费者
    delivery, err := ch.ConsumeWithContext(
        ctx,
        queueName, // queue 名称
        "",        // consumer 用来区分多个消费者
        true,      // auto-ack 是否自动应答
        false,     // exclusive 是否独有
        false,     // no-local 如果设置为true，表示不能将同一个Connection中生产者发送的消息传递给这个Connection中的消费者
        false,     // no-wait 是否阻塞
        nil,       // args
    )
    if err != nil {
        _ = ch.Close()
        return nil, err
    }

    return &Subscriber{
        ctx:          ctx,
        exchangeName: exchangeName,
        queueName:    queueName,
        conn:         conn,
        ch:           ch,
        delivery:     delivery,
    }, nil
}

// Subscribe 订阅
func (c *Subscriber) Subscribe() {
    go func() {
        fmt.Printf("waiting for messages, queue = %s\n", c.queueName)
        for d := range c.delivery {
            // 处理消息
            fmt.Printf("[%s received]: %s\n", c.queueName, d.Body)
            // _ = d.Ack(false) // 如果auto-ack为false时，需要手动ack
        }
    }()
}

// Close 关闭
func (p *Subscriber) Close() {
    if p.ch != nil {
        _ = p.ch.Close()
    }
}

func checkErr(err error) {
    if err != nil {
        panic(err)
    }
}

死信队列队列

什么是死信队列？

“死信”(Dead Letter)是指消息在正常的消息队列中无法被成功消费或处理而被重新路由到另一个专门的队列中，这个专门的队列称为”死信队列”(Dead Letter Queue，DLQ)。死信队列用于存储那些未能被正常处理的消息，以便后续分析和处理。

以下是一些常见的导致消息变成死信的原因：

1. 消息被拒绝(Rejection)：消费者处理消息时显式地拒绝了该消息(Reject或Nack)，并且没有要求将其重新入队。
2. 消息过期(TTL Expiration)：消息在队列中存储的时间超过了设置的TTL(声明队列时arg设置参数x-message-ttl，单位为毫秒)，即消息的存活时间。
3. 队列长度限制(Queue Length Limit)：队列的消息数量达到了预设的最大值(声明队列时arg设置参数x-max-length)，新的消息无法被加入到队列中。
4. 消息返回到仲裁队列的次数超过了投递限制的次数。

如何设置死信队列

在RabbitMQ中，可以通过设置队列的参数(args)来指定死信队列。主要涉及以下几个参数：

• x-dead-letter-exchange：指定死信消息要发送到的交换机。
• x-dead-letter-routing-key：指定死信消息的路由键（可选）。

在go语言设置死信队列 示例。

使用场景

• 错误处理：将无法处理的消息转移到死信队列，可以进行后续分析和重试。
• 消息监控：监控死信队列中的消息，及时发现和处理异常情况。
• 延迟队列：通过TTL和死信队列的组合，可以实现消息的延迟投递。

通过合理配置和使用死信队列，可以提高系统的可靠性和可维护性。

注意事项

1. 设置生产者的的queue的args与消费者queue的args必须一致，否则会报错 Exception (406) Reason: \"PRECONDITION_FAILED - inequivalent arg ......

2. 对于已经设置的queue，如果后面添加args，会报错 报错Exception (504) Reason: "channel/connection is not open"

总结

上面介绍了rabbitMQ各个类型消息队列的简单使用，在实际使用中，连接rabbitMQ应该有网络断开重连功能。如果消费端处理消息比较慢，在消费端设置channel.Qos来限制每次消费消息的数量，平衡消息吞吐量和公平性，防止消费者受到消息突发流量冲击。例如设置prefetch_count=1，则表示每个消费者每次只会处理1条消息，处理完成后才会获取下一条消息。这可以防止少数消费者处理能力弱导致大量消息堆积。 适当地设置这些参数,可以优化rabbitMQ在大量消息场景下的性能表现。

这是在github.com/rabbitmq/amqp091-go基础上封装的 rabbitmq 库。

参考：

• https://www.rabbitmq.com

本文链接：https://zhuyasen.com/post/rabbitmq.html，参与评论 »