基于 Flink CDC 构建 MySQL 到 Databend 的 实时数据同步

这篇教程将展示如何基于 Flink CDC 快速构建 MySQL 到 Databend 的实时数据同步。本教程的演示都将在 Flink SQL CLI 中进行，只涉及 SQL，无需一行 Java/Scala 代码，也无需安装 IDE。

假设我们有电子商务业务，商品的数据存储在 MySQL ，我们需要实时把它同步到 Databend 中。

接下来的内容将介绍如何使用 Flink Mysql/Databend CDC 来实现这个需求，系统的整体架构如下图所示：

准备阶段

准备一台已经安装了 Docker 的 Linux 或者 MacOS 电脑。

准备教程所需要的组件

接下来的教程将以 docker-compose 的方式准备所需要的组件。

debezium-MySQL

docker-compose.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

version: '2.1'
services:
  postgres:
    image: debezium/example-postgres:1.1
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_DB=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
  mysql:
    image: debezium/example-mysql:1.1
    ports:
      - "3306:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=123456
      - MYSQL_USER=mysqluser
      - MYSQL_PASSWORD=mysqlpw

Databend

docker-compose.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

version: '3'
services:
  databend:
    image: datafuselabs/databend
    volumes:
      - /Users/hanshanjie/databend/local-test/databend/databend-query.toml:/etc/databend/query.toml
    environment:
      QUERY_DEFAULT_USER: databend
      QUERY_DEFAULT_PASSWORD: databend
      MINIO_ENABLED: 'true'
    ports:
      - '8000:8000'
      - '9000:9000'
      - '3307:3307'
      - '8124:8124'

在 docker-compose.yml 所在目录下执行下面的命令来启动本教程需要的组件：

1

ocker-compose up -d

该命令将以 detached 模式自动启动 Docker Compose 配置中定义的所有容器。你可以通过 docker ps 来观察上述的容器是否正常启动。

下载 Flink 和所需要的依赖包

1. 下载 Flink 1.16.0 并将其解压至目录 flink-1.16.0
2. 下载下面列出的依赖包，并将它们放到目录 flink-1.16.0/lib/ 下：
3. 下载链接只对已发布的版本有效, SNAPSHOT 版本需要本地编译

• flink-sql-connector-mysql-cdc-2.3.0.jar

• 最好将 conf/flink-conf.yaml 中的 taskmanager.memory.process.size 改为 4096m

  以及将 taskmanager.sh 中的 UseGCG1 去掉

编译 flink-connector-databend

1
2
3

git clone https://github.com/databendcloud/flink-connector-databend
cd flink-connector-databend
mvn clean install -DskipTests

将 target/flink-connector-databend-1.16.0-SNAPSHOT.jar 拷贝到目录 flink-1.16.0/lib/ 下。

准备数据

在 MySQL 数据库中准备数据

进入 MySQL 容器

1

docker-compose exec mysql mysql -uroot -p123456

创建数据库 mydb 和表 products，并插入数据:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

CREATE DATABASE mydb;
USE mydb;

CREATE TABLE products (id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,name VARCHAR(255) NOT NULL,description VARCHAR(512));
ALTER TABLE products AUTO_INCREMENT = 10;

INSERT INTO products VALUES (default,"scooter","Small 2-wheel scooter"),
(default,"car battery","12V car battery"),
(default,"12-pack drill bits","12-pack of drill bits with sizes ranging from #40 to #3"),
(default,"hammer","12oz carpenter's hammer"),
(default,"hammer","14oz carpenter's hammer"),
(default,"hammer","16oz carpenter's hammer"),
(default,"rocks","box of assorted rocks"),
(default,"jacket","water resistent black wind breaker"),
(default,"cloud","test for databend"),
(default,"spare tire","24 inch spare tire");

Databend 中建表

1

CREATE TABLE bend_products (id INT NOT NULL, name VARCHAR(255) NOT NULL, description VARCHAR(512) );

启动 Flink 集群和 Flink SQL CLI

使用下面的命令跳转至 Flink 目录下

1

cd flink-16.0

使用下面的命令启动 Flink 集群

1

./bin/start-cluster.sh

启动成功的话，可以在 http://localhost:8081/ 访问到 Flink Web UI，如下所示：

使用下面的命令启动 Flink SQL CLI

1

./bin/sql-client.sh

在 Flink SQL CLI 中使用 Flink DDL 创建表

首先，开启 checkpoint，每隔3秒做一次 checkpoint

1
2

-- Flink SQL
Flink SQL> SET execution.checkpointing.interval = 3s;

然后, 对于数据库中的表 products 使用 Flink SQL CLI 创建对应的表，用于同步底层数据库表的数据

1
2
3
4
5
6
7
8
9
10
11

-- Flink SQL
Flink SQL> CREATE TABLE products (id INT,name STRING,description STRING,PRIMARY KEY (id) NOT ENFORCED)
WITH ('connector' = 'mysql-cdc',
'hostname' = '127.0.0.1',
'port' = '3306',
'username' = 'root',
'password' = '123456',
'database-name' = 'mydb',
'table-name' = 'products',
'server-time-zone' = 'UTC'
);

最后，创建 d_products 表， 用来订单数据写入 Databend 中

1
2
3
4
5
6
7
8
9
10

-- Flink SQL
create table d_products (id INT,name String,description String)
with ('connector' = 'databend',
'url'='databend://cloudapp:ssggkxgub3k0@tn3ftqihs.gw.aws-us-east-2.default.databend.com:443/testdb?warehouse=medium-p8at&ssl=true',
'database-name'='testdb',
'table-name'='bend_products',
'sink.batch-size' = '1',
'sink.ignore-delete' = 'false',
'sink.flush-interval' = '1000',
'sink.max-retries' = '3');

使用 Flink SQL 将 products 表中的数据同步到 Databend 的 d_products 表中：

1

insert into d_products select * from products;

此时 flink job 就会提交成功，打开 flink UI 可以看到:

同时在 databend 中可以看到 MySQL 中的数据已经同步过来了：

同步 Insert/Update 数据

此时我们在 MySQL 中再插入 10 条数据：

1
2
3
4
5
6
7
8
9
10
11

INSERT INTO products VALUES
(default,"scooter","Small 2-wheel scooter"),
(default,"car battery","12V car battery"),
(default,"12-pack drill bits","12-pack of drill bits with sizes ranging from #40 to #3"),
(default,"hammer","12oz carpenter's hammer"),
(default,"hammer","14oz carpenter's hammer"),
(default,"hammer","16oz carpenter's hammer"),
(default,"rocks","box of assorted rocks"),
(default,"jacket","water resistent black wind breaker"),
(default,"cloud","test for databend"),
(default,"spare tire","24 inch spare tire");

这些数据会立即同步到 Databend 当中。

假如此时 MySQL 中更新了一条数据:

那么 id=10 的数据在 databend 中也会被立即更新：

环境清理

操作结束后，在 docker-compose.yml 文件所在的目录下执行如下命令停止所有容器：

1

docker-compose down

在 Flink 所在目录 flink-1.16.0 下执行如下命令停止 Flink 集群：

1

./bin/stop-cluster.sh

结论

以上就是基于 Flink CDC 构建 MySQL 到 Databend 的 实时数据同步的全部过程。

mysql flink connector is over 2.4.1

flin version is 1.17.1

Deep Dive into SeaTunnel Databend Sink Connector CDC Implementation

Background

Databend is an AI-native data warehouse optimized for analytical workloads with a columnar storage architecture, serving as an open-source alternative to Snowflake. When handling CDC (Change Data Capture) scenarios, executing individual UPDATE and DELETE operations severely impacts performance and fails to leverage Databend’s batch processing advantages.

Before PR #9661, SeaTunnel’s Databend sink connector only supported batch INSERT operations, lacking efficient handling of UPDATE and DELETE operations in CDC scenarios. This limitation restricted its application in real-time data synchronization scenarios.

Core Challenges

CDC scenarios present the following main challenges:

1. Performance Bottleneck: Executing individual UPDATE/DELETE operations generates excessive network round-trips and transaction overhead
2. Resource Consumption: Frequent single operations cannot utilize Databend’s columnar storage advantages
3. Data Consistency: Ensuring the order and completeness of change operations
4. Throughput Limitation: Traditional approaches struggle with high-concurrency, large-volume CDC event streams

Solution Architecture

Overall Design Approach

The new CDC mode achieves high-performance data synchronization through the following innovative design:

1
2
3
4
5
6

graph LR
    A[CDC Data Source] --> B[SeaTunnel]
    B --> C[Raw Table]
    C --> D[Databend Stream]
    D --> E[MERGE INTO Operation]
    E --> F[Target Table]

Core Components

1. CDC Mode Activation Mechanism

When users specify the conflict_key parameter in configuration, the connector automatically switches to CDC mode:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

sink {
  Databend {
    url = "jdbc:databend://databend:8000/default?ssl=false"
    user = "root"
    password = ""
    database = "default"
    table = "sink_table"
    
    # Enable CDC mode
    batch_size = 100
    conflict_key = "id"
    allow_delete = true
  }
}

2. Raw Table Design

The system automatically creates a temporary raw table to store CDC events:

1
2
3
4
5
6
7

CREATE TABLE IF NOT EXISTS raw_cdc_table_${target_table} (
    id VARCHAR,                    -- Primary key identifier
    table_name VARCHAR,            -- Target table name
    raw_data JSON,                 -- Complete row data (JSON format)
    add_time TIMESTAMP,            -- Event timestamp
    action VARCHAR                 -- Operation type: INSERT/UPDATE/DELETE
)

3. Stream Mechanism

Leveraging Databend Stream functionality to monitor raw table changes:

1
2

CREATE STREAM IF NOT EXISTS stream_${target_table} 
ON TABLE raw_cdc_table_${target_table}

Stream advantages:

• Incremental Processing: Only processes new change records
• Transaction Guarantee: Ensures no data loss
• Efficient Querying: Avoids full table scans

4. Two-Phase Processing Model

Phase 1: Data Writing

• SeaTunnel writes all CDC events (INSERT/UPDATE/DELETE) to the raw table in JSON format
• Supports batch writing for improved throughput

Phase 2: Merge Processing

• Periodically executes MERGE INTO operations based on SeaTunnel AggregatedCommitter
• Merges data from raw table to target table

MERGE INTO Core Logic

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

MERGE INTO target_table AS t
USING (
    SELECT 
        raw_data:column1::VARCHAR AS column1,
        raw_data:column2::INT AS column2,
        raw_data:column3::TIMESTAMP AS column3,
        action,
        id
    FROM stream_${target_table}
    QUALIFY ROW_NUMBER() OVER(
        PARTITION BY _id 
        ORDER BY _add_time DESC
    ) = 1 
) AS s
ON t.id = s.id
WHEN MATCHED AND s._action = 'UPDATE' THEN 
    UPDATE SET *
WHEN MATCHED AND s._action = 'DELETE' THEN 
    DELETE
WHEN NOT MATCHED AND s._action != 'DELETE' THEN 
    INSERT *

Implementation Details

Key Code Implementation

Based on PR #9661 implementation, the main core classes involved are:

DatabendSinkWriter Enhancement

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

public class DatabendSinkWriter extends AbstractSinkWriter<SeaTunnelRow, DatabendWriteState> {
    
    private boolean cdcMode;
    private String rawTableName;
    private String streamName;
    private ScheduledExecutorService mergeExecutor;
    
    @Override
    public void write(SeaTunnelRow element) throws IOException {
        if (cdcMode) {
            // CDC mode: write to raw table
            writeToRawTable(element);
        } else {
            // Normal mode: write directly to target table
            writeToTargetTable(element);
        }
    }
  
    private void performMerge(List<DatabendSinkAggregatedCommitInfo> aggregatedCommitInfos) {
        // Merge all data from raw table to target table
        String mergeSql = generateMergeSql();
        log.info("[Instance {}] Executing MERGE INTO statement: {}", instanceId, mergeSql);

        try (Statement stmt = connection.createStatement()) {
            stmt.execute(mergeSql);
            log.info("[Instance {}] Merge operation completed successfully", instanceId);
        } catch (SQLException e) {
            log.error(
                    "[Instance {}] Failed to execute merge operation: {}",
                    instanceId,
                    e.getMessage(),
                    e);
            throw new DatabendConnectorException(
                    DatabendConnectorErrorCode.SQL_OPERATION_FAILED,
                    "Failed to execute merge operation: " + e.getMessage(),
                    e);
        }
    }
}

Configuration Options Extension

New CDC-related configurations in DatabendSinkOptions:

1
2
3
4
5
6
7
8
9
10
11
12
13

public class DatabendSinkOptions {
    public static final Option<String> CONFLICT_KEY =
            Options.key("conflict_key")
                    .stringType()
                    .noDefaultValue()
                    .withDescription("Conflict key for CDC merge operations");

    public static final Option<Boolean> ALLOW_DELETE =
            Options.key("allow_delete")
                    .booleanType()
                    .defaultValue(false)
                    .withDescription("Whether to allow delete operations in CDC mode");
}

Batch Processing Optimization Strategy

The system employs a dual-trigger mechanism for executing MERGE operations:

1. Quantity-based: Triggers when accumulated CDC events reach batch_size
2. Time-based: Triggers when SeaTunnel’s checkpoint.interval is reached

1
2
3

if (isCdcMode && shouldPerformMerge()) {
    performMerge(aggregatedCommitInfos);
}

Performance Advantages

1. Batch Processing Optimization

• Traditional Approach: 1000 updates = 1000 network round-trips
• CDC Mode: 1000 updates = 1 batch write + 1 MERGE operation

2. Columnar Storage Utilization

• MERGE INTO operations fully leverage Databend’s columnar storage characteristics
• Batch updates only scan relevant columns, reducing I/O overhead

3. Resource Efficiency Improvement

• Reduced connection overhead
• Lower transaction management costs
• Enhanced concurrent processing capability

Usage Examples

Complete Configuration Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

env{
  parallelism = 1
  job.mode = "STREAMING"
  checkpoint.interval = 1000
}

source {
  MySQL-CDC {
   base-url="jdbc:mysql://127.0.0.1:3306/mydb"
   username="root"
   password="123456"
   table-names=["mydb.t1"]
   startup.mode="initial"
  }
}

sink {
  Databend {
    url = "jdbc:databend://127.0.0.1:8009?presigned_url_disabled=true"
    database = "default"
    table = "t1"
    user = "databend"
    password = "databend"
    batch_size = 2
    auto_create = true
    interval = 3
    conflict_key = "a"
    allow_delete = true
  }
}

Monitoring and Debugging

1
2
3
4
5
6
7
8
9
10
11
12
13

-- View Stream status
SHOW STREAMS;

-- Check raw table data volume
SELECT COUNT(*) FROM raw_cdc_table_users;

-- View pending changes
SELECT _action, COUNT(*) 
FROM stream_users 
GROUP BY _action;

-- Manually trigger merge (for debugging)
CALL SYSTEM$STREAM_CONSUME('stream_users');

Error Handling and Fault Tolerance

1. Retry Mechanism

The system includes intelligent retry mechanisms that automatically retry during network anomalies or temporary failures.

2. Data Consistency Guarantee

• Uses QUALIFY ROW_NUMBER() to ensure only the latest changes are processed
• Stream mechanism ensures no data loss
• Supports checkpoint recovery

3. Resource Cleanup

1
2
3

-- Periodically clean processed raw table data
DELETE FROM raw_cdc_table_users 
WHERE _add_time < DATEADD(day, -7, CURRENT_TIMESTAMP());

Future Optimization Directions

1. Intelligent Batching: Dynamically adjust batch sizes based on data characteristics
2. Schema Evolution: Automatically handle table structure changes
3. Monitoring Metrics: Integrate comprehensive performance monitoring
4. Parallel Processing: Support multi-table parallel CDC synchronization

Conclusion

By introducing Stream and MERGE INTO mechanisms, SeaTunnel’s Databend sink connector successfully implements high-performance CDC support. This innovative solution not only significantly improves data synchronization performance but also ensures data consistency and reliability. For OLAP scenarios requiring real-time data synchronization, this feature provides robust technical support.

Related Links

• PR #9661: feat(Databend): support CDC mode for databend sink connector
• Databend MERGE INTO Documentation
• Databend Stream Documentation
• SeaTunnel Databend Connector Documentation
• Databend GitHub Repository

SeaTunnel Databend Sink Connector CDC 功能实现详解

背景介绍

Databend 是一个面向分析型工作负载优化的 OLAP 数据库，采用列式存储架构。在处理 CDC（Change Data Capture，变更数据捕获）场景时，如果直接执行单条的 UPDATE 和 DELETE 操作，会严重影响性能，无法充分发挥 Databend 在批处理方面的优势。

在 PR #9661 之前，SeaTunnel 的 Databend sink connector 仅支持批量 INSERT 操作，缺乏对 CDC 场景中 UPDATE 和 DELETE 操作的高效处理能力。这限制了在实时数据同步场景中的应用。

核心问题与挑战

在 CDC 场景中，主要面临以下挑战：

1. 性能瓶颈：逐条执行 UPDATE/DELETE 操作会产生大量的网络往返和事务开销
2. 资源消耗：频繁的单条操作无法利用 Databend 的列式存储优势
3. 数据一致性：需要确保变更操作的顺序性和完整性
4. 吞吐量限制：传统方式难以应对高并发大数据量的 CDC 事件流

解决方案架构

整体设计思路

新的 CDC 模式通过以下创新设计实现高性能数据同步：

1
2
3
4
5
6

graph LR
    A[CDC 数据源] --> B[SeaTunnel]
    B --> C[原始表 Raw Table]
    C --> D[Databend Stream]
    D --> E[MERGE INTO 操作]
    E --> F[目标表 Target Table]

核心组件

1. CDC 模式激活机制

当用户在配置中指定 conflict_key 参数时，connector 自动切换到 CDC 模式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

sink {
  Databend {
    url = "jdbc:databend://databend:8000/default?ssl=false"
    user = "root"
    password = ""
    database = "default"
    table = "sink_table"
    
    # Enable CDC mode
    batch_size = 100
    conflict_key = "id"
    allow_delete = true
  }
}

2. 原始表设计

系统自动创建一个临时原始表来存储 CDC 事件：

1
2
3
4
5
6
7

CREATE TABLE IF NOT EXISTS raw_cdc_table_${target_table} (
    id VARCHAR,                    -- 主键标识
    table_name VARCHAR,            -- 目标表名
    raw_data JSON,                 -- 完整的行数据（JSON格式）
    add_time TIMESTAMP,            -- 事件时间戳
    action VARCHAR                 -- 操作类型：INSERT/UPDATE/DELETE
)

3. Stream 机制

利用 Databend Stream 功能监控原始表的变化：

1
2

CREATE STREAM IF NOT EXISTS stream_${target_table} 
ON TABLE raw_cdc_table_${target_table}

Stream 的优势：

• 增量处理：只处理新增的变更记录
• 事务保证：确保数据不丢失
• 高效查询：避免全表扫描

4. 两阶段处理模型

第一阶段：数据写入

• SeaTunnel 将所有 CDC 事件（INSERT/UPDATE/DELETE）以 JSON 格式写入原始表
• 支持批量写入，提高吞吐量

第二阶段：合并处理

• 基于 seatunnel AggregatedCommitter 定期执行 MERGE INTO 操作
• 将原始表的数据合并到目标表

MERGE INTO 核心逻辑

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

MERGE INTO target_table AS t
USING (
    SELECT 
        raw_data:column1::VARCHAR AS column1,
        raw_data:column2::INT AS column2,
        raw_data:column3::TIMESTAMP AS column3,
        action,
        id
    FROM stream_${target_table}
    QUALIFY ROW_NUMBER() OVER(
        PARTITION BY _id 
        ORDER BY _add_time DESC
    ) = 1 
) AS s
ON t.id = s.id
WHEN MATCHED AND s._action = 'UPDATE' THEN 
    UPDATE SET *
WHEN MATCHED AND s._action = 'DELETE' THEN 
    DELETE
WHEN NOT MATCHED AND s._action != 'DELETE' THEN 
    INSERT *

实现细节

关键代码实现

根据 PR #9661 的实现，主要涉及以下核心类：

DatabendSinkWriter 增强

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

public class DatabendSinkWriter extends AbstractSinkWriter<SeaTunnelRow, DatabendWriteState> {
    
    private boolean cdcMode;
    private String rawTableName;
    private String streamName;
    private ScheduledExecutorService mergeExecutor;
    
    @Override
    public void write(SeaTunnelRow element) throws IOException {
        if (cdcMode) {
            // CDC 模式：写入原始表
            writeToRawTable(element);
        } else {
            // 普通模式：直接写入目标表
            writeToTargetTable(element);
        }
    }
  
    private void performMerge(List<DatabendSinkAggregatedCommitInfo> aggregatedCommitInfos) {
        // Merge all the data from raw table to target table
        String mergeSql = generateMergeSql();
        log.info("[Instance {}] Executing MERGE INTO statement: {}", instanceId, mergeSql);

        try (Statement stmt = connection.createStatement()) {
            stmt.execute(mergeSql);
            log.info("[Instance {}] Merge operation completed successfully", instanceId);
        } catch (SQLException e) {
            log.error(
                    "[Instance {}] Failed to execute merge operation: {}",
                    instanceId,
                    e.getMessage(),
                    e);
            throw new DatabendConnectorException(
                    DatabendConnectorErrorCode.SQL_OPERATION_FAILED,
                    "Failed to execute merge operation: " + e.getMessage(),
                    e);
        }
    }
}

配置选项扩展

在 DatabendSinkOptions 中新增 CDC 相关配置：

1
2
3
4
5
6
7
8
9
10
11
12
13

public class DatabendSinkOptions {
      public static final Option<String> CONFLICT_KEY =
            Options.key("conflict_key")
                    .stringType()
                    .noDefaultValue()
                    .withDescription("Conflict key for CDC merge operations");

    public static final Option<Boolean> ALLOW_DELETE =
            Options.key("allow_delete")
                    .booleanType()
                    .defaultValue(false)
                    .withDescription("Whether to allow delete operations in CDC mode");
}

批处理优化策略

系统采用双重触发机制执行 MERGE 操作：

1. 基于数量：当累积的 CDC 事件达到 batch_size 时触发
2. 基于时间：seatunnel 的 checkpoint.interval 达到后触发

1
2
3

if (isCdcMode && shouldPerformMerge()) {
          performMerge(aggregatedCommitInfos);
      }

性能优势

1. 批量处理优化

• 传统方式：1000 条更新 = 1000 次网络往返
• CDC 模式：1000 条更新 = 1 次批量写入 + 1 次 MERGE 操作

2. 列式存储利用

• MERGE INTO 操作充分利用 Databend 的列式存储特性
• 批量更新时只需扫描相关列，减少 I/O 开销

3. 资源效率提升

• 减少连接开销
• 降低事务管理成本
• 提高并发处理能力

使用示例

完整配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

env{
  parallelism = 1
  job.mode = "STREAMING"
  checkpoint.interval = 1000
}

source {
  MySQL-CDC {
   base-url="jdbc:mysql://127.0.0.1:3306/mydb"
   username="root"
   password="123456"
   table-names=["mydb.t1"]
   startup.mode="initial"
  }
}
sink {
  Databend {
    url = "jdbc:databend://127.0.0.1:8009?presigned_url_disabled=true"
    database = "default"
    table = "t1"
    user = "databend"
    password = "databend"
    batch_size = 2
    auto_create = true
    interval = 3
    conflict_key = "a"
    allow_delete = true
  }
}

监控与调试

1
2
3
4
5
6
7
8
9
10
11
12
13

-- 查看 Stream 状态
SHOW STREAMS;

-- 查看原始表数据量
SELECT COUNT(*) FROM raw_cdc_table_users;

-- 查看待处理的变更
SELECT _action, COUNT(*) 
FROM stream_users 
GROUP BY _action;

-- 手动触发合并（调试用）
CALL SYSTEM$STREAM_CONSUME('stream_users');

错误处理与容错

1. 重试机制

2. 数据一致性保证

• 使用 QUALIFY ROW_NUMBER() 确保只处理最新的变更
• Stream 机制保证不丢失数据
• 支持 checkpoint 恢复

3. 资源清理

1
2
3

-- 定期清理已处理的原始表数据
DELETE FROM raw_cdc_table_users 
WHERE _add_time < DATEADD(day, -7, CURRENT_TIMESTAMP());

未来优化方向

1. 智能批处理：根据数据特征动态调整批处理大小
2. Schema 演进：自动处理表结构变更
3. 监控指标：集成更完善的性能监控

总结

通过引入 Stream 和 MERGE INTO 机制，SeaTunnel 的 Databend sink connector 成功实现了高性能的 CDC 支持。这一创新方案不仅大幅提升了数据同步性能，还保证了数据一致性和可靠性。对于需要实时数据同步的 OLAP 场景，这一功能提供了强大的技术支撑。

相关链接

• PR #9661: feat(Databend): support CDC mode for databend sink connector
• Databend MERGE INTO 文档
• Databend Stream 文档
• SeaTunnel Databend Connector 文档

  ---

使用 Seatunnel 建立从 MySQL 到 Databend 的数据同步管道

前言

SeaTunnel 是一个非常易用、超高性能的分布式数据集成平台，支持实时海量数据同步。 每天可稳定高效地同步数百亿数据，已被近百家企业应用于生产，在国内较为普及。

Databend 是一款开源、弹性、低成本，基于对象存储也可以做实时分析的云原生湖仓。

seatunnel 架构

SeaTunnel 整体架构：

本文将使用 Seatunnel 建立从 MySQL 到 Databend 的数据同步管道，实现从 MySQL 数据源同步数据到 Databend 目标表的目的。

SeaTunnel MySQL-CDC 和 Databend Sink Connector

SeaTunnel 的 MySQL CDC 连接器允许从 MySQL 数据库中读取快照数据和增量数据，其实现的原理是基于 debezium-mysql-connector 。

而 Databend 在 PR [Feature][Connector-V2] Support databend source/sink connector 之后也同时在 seatunnel 中支持了 Databend 作为 Source 和 Sink Connector。这里我们使用 Seatunnel 的 MySQL-CDC Source Connector 和 Databend Sink Connector 来搭建数据同步管道。

编译 Seatunnel

由于上述 Databend Connector 的 PR 刚合并入 seatunnel 的 dev 分支，还没有正式 release，所以目前要使用 Databend Connector 的话，需要基于源码对 seatunnel 进行构建。

Clone 源码

首先我们需要从 GitHub 克隆 SeaTunnel 源代码。

1

git clone git@github.com:apache/seatunnel.git

本地安装子项目

在克隆源代码之后，需要运行 ./mvnw 命令将子项目安装到 maven 本地存储库。否则代码无法在 JetBrains IntelliJ IDEA 中正确启动。

1

./mvnw install -Dmaven.test.skip

构建 Seatunnel

安装 maven 后，可以使用以下命令进行编译和打包。

1

mvn clean package -pl seatunnel-dist -am -Dmaven.test.skip=true

构建后的内容在 seatunnel/seatunnel-dist/target 中，我们需要解压 apache-seatunnel-2.3.12-SNAPSHOT-src.tar.gz，得到如下目录：

bin 下面是可以直接运行的 shell 脚本，能够一键启动 seatunnel；

config 中是 jvm options 相关的配置文件；

lib 中是运行 seatunnel 或者 connector 相关的 jar 包。

创建 connector 配置文件

我们的任务设定是通过 SeaTunnel 从 MySQL 中同步 mydb.t1 表。 配置文件 为 mysql-to-databend.conf：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

env{
  parallelism = 1
  job.mode = "STREAMING"
  checkpoint.interval = 2000
}

source {
  MySQL-CDC {
   base-url="jdbc:mysql://127.0.0.1:3306/mydb"
   username="root"
   password="123456"
   table-names=["mydb.t1"]
   startup.mode="initial"
  }
}
sink {
  Databend {
    url = "jdbc:databend://127.0.0.1:8000?presigned_url_disabled=true"
    database = "default"
    table = "t1"
    username = "databend"
    password = "databend"
    # 批量操作设置
    batch_size = 2
    # 如果目标表不存在，是否自动创建
    auto_create = true
  }
}

相关的参数设定可以参考 seatunnel MySQL文档 和 seatunnel Databend Connector。

本地启动 MySQL 与 Databend

启动并初始化 MySQL 表数据

本地启动 MySQL 后，创建一个数据库 mydb，在 mydb 中新建一张表并插入 10 条数据：

1
2
3
4
5
6

create database mydb;
use mydb;
create table t1 (a int, b varchar(100));
insert into t1 values(1,'aa')
...
insert into t1 values(10,'bb')

本地启动 Databend

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

version: '3'
services:
  databend:
    image: datafuselabs/databend:v1.2.754-nightly
    platform: linux/arm64
    ports:
      - "8000:8000"
    environment:
      - QUERY_DEFAULT_USER=databend
      - QUERY_DEFAULT_PASSWORD=databend
      - MINIO_ENABLED=true
    volumes:
      - ./data:/var/lib/minio
    healthcheck:
      test: "curl -f localhost:8080/v1/health || exit 1"
      interval: 2s
      retries: 10
      start_period: 2s
      timeout: 1s

直接 docker-compose up 即可启动 databend 服务。

启动 seatunnel

1

./bin/seatunnel.sh --config ./bin/mysql-to-databend.conf -m local

启动后 Databend Sink Connector 会首先将 MySQL 表中的全量数据同步过来:

接下来我们往 MySQL 中插入几条数据，就会同步 MySQL 中增量的数据：

可以看到 seatunnel 在终端输出的日志：

以及 Databend 中查询到数据：

说明数据已经及时同步过来了。

目前 Databend Sink Connector 还只支持 Append Only 模式，对于 update、delete 的数据没做处理，会在下一个 seatunnel 的 PR 中实现完整的 CDC 功能。

结论

通过本文我们成功实现了从 MySQL 到 Databend 的实时数据同步管道。这个解决方案具有以下优势：

1. 简单易用：SeaTunnel 提供了简洁的配置方式，只需少量配置即可建立高效的数据同步管道。
2. 实时性强：基于 CDC 技术，能够实时捕获 MySQL 的数据变更并同步到 Databend。
3. 可扩展性好：SeaTunnel 的分布式架构使其能够处理海量数据同步需求。
4. 低开发成本：无需编写复杂的 ETL 代码，通过配置文件即可完成数据集成任务。

需要注意的是，目前 Databend Sink Connector 还只支持 Append Only 模式，对于 update、delete 的数据没做处理，完整的 CDC 功能将在后续的 PR 中实现。这个方案特别适合需要将 MySQL 数据实时同步到 Databend 进行分析的场景，帮助企业构建实时数据湖仓架构。

打破信息差，手把手教你本地部署 DeepSeek

在AI技术迅速发展的今天，越来越多的人开始尝试将大语言模型（如DeepSeek）应用于日常学习和工作中。然而，对于普通用户来说，如何快速、便捷地在本地环境中部署并使用这些工具仍然存在一定的门槛。再加上最近官方 deepseek 访问压力大和来源未知的大量 ddos 攻击，经常出现服务器访问繁忙的情况，使用体验并不好。

本文将以 Open Web UI 和 Ollama 为例，手把手教你完成本地部署，让你轻松实现与AI模型的交互，本教程适合新手和不具备相关行业经验的小白新手。

为什么要本地部署？

1. 数据隐私：相比于在线服务，本地部署可以避免将数据上传到云端，确保敏感信息的安全性。
2. 个性化配置：可以根据自己的需求调整服务参数，获得更好的使用体验。
3. 低成本运行：通过开源工具和本地资源，大幅降低使用成本。

部署前的准备

在开始部署之前，请确认以下几点：

1. 安装依赖：
   • 确保你的系统已经安装了Python 3.11或更高版本。
   • 如果你选择使用Docker，则需要先安装 Docker 和 Docker Compose。
2. 网络环境：确保本地网络可以正常访问互联网，以便下载所需的软件包和镜像。

步骤一：安装并启动 Open Web UI

Open Web UI 是一个基于Web的界面工具，支持与多种AI模型（包括DeepSeek）进行交互。以下是两种常见的安装方式：

方式一：通过 pip 安装

如果你更倾向于直接在本地机器上运行服务，可以使用以下命令：

1

pip3.11 install open-webui

安装完成后，输入以下命令启动服务：

1

open-webui --host 0.0.0.0 --port 3000

这将在本地的 localhost:3000 端口启动一个Web界面。

方式二：通过 Docker 安装（推荐）

如果你希望更简单地管理服务，可以使用 Docker。运行以下命令：

1
2
3
4
5
6
7

docker run -d \
  -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

这条命令会下载并运行 Open Web UI 的Docker镜像，服务会在 localhost:3000 端口启动。

步骤二：安装并启动 Ollama

Ollama 是一个轻量级的AI模型运行工具，支持多种大语言模型。你需要先在本地安装并启动 Ollama 服务，然后将其与 Open Web UI 集成。

安装 Ollama

根据你的操作系统选择相应的安装方式：

在 Linux 上：

1

curl -s https://ollama.ai/install.sh | bash

在 macOS 上：

1

brew install ollama

在 Windows 上：

你可以通过 Ollama 官方网站 下载安装包。

启动 Ollama

安装完成后，运行以下命令启动服务：

1

ollama serve --listen 0.0.0.0:11434

这样，Ollama 将在 localhost:11434 端口提供模型推理服务。

模型下载

deepseek 提供了不同参数数量的模型，比如 7b, 14b, 32b, 70b 和满血版本的 671b，这里根据你的机器配置选择不同的参数，我本地的机器是 128g 的内存，选择了 32b 的模型，仅供参考。

1

ollama run deepseek-r1:32b

步骤三：配置 Open Web UI

启动 Open Web UI 后，访问 http://localhost:3000，你需要进行以下配置：

1. 添加 Ollama 服务：

   • 在页面上找到“Add New Model”或类似选项。
   • 填写模型名称（如 DeepSeek）和地址（http://localhost:11434/api/generate）。
   • 确保勾选支持的模型类型（如文本生成、问答等）。

2. 验证连接：

   • 配置完成后，尝试发送一条简单的查询（例如“你好”）。
   • 如果返回正常结果，则说明配置成功。

步骤四：测试 DeepSeek 功能

完成上述步骤后，你就可以通过 Open Web UI 使用 DeepSeek 提供的功能了。以下是几个常见的使用场景：

1. 文本生成：
   • 输入类似“写一篇关于人工智能的科普文章”。
2. 问答交互：
   • 提问：“DeepSeek 和其他大语言模型有什么区别？”
3. 代码辅助：
   • 输入：“帮我写一个Python脚本，用于计算斐波那契数列。”

常见问题与故障排查

1. 服务无法启动：

   • 检查端口是否被占用（如 3000 或 11434）。
   • 确保防火墙或安全软件没有阻止相关端口的访问。

2. 模型响应慢或无响应：

   • 确认 Ollama 服务是否正常运行。
   • 检查网络连接，确保模型可以访问互联网（部分模型依赖于在线资源）。

3. 配置错误：

   • 确保 Open Web UI 和 Ollama 的地址配置正确。
   • 参考官方文档或社区论坛，获取更多帮助。

More

如果是想使用满血版本的 deepseek r1 ，目前稳定输出方案就是在硅基流动生成 API 密钥，结合 CHATBOX使用。不过该方案稍微复杂，适合有些基础的同学，感兴趣的话后面开新的教程讲一下。

总结

通过本文的指导，你已经成功在本地部署了 DeepSeek 相关服务，并可以通过 Open Web UI 与模型进行交互。这种方式不仅降低了使用成本，还提供了更高的灵活性和安全性。如果你对AI技术感兴趣，不妨尝试将这些工具应用到更多的场景中，进一步探索其潜力！

Introduction to Testcontainers

Testcontainers is an open-source library that provides lightweight, disposable instances of databases, message brokers, web browsers, or any service that can run in a Docker container.

Core Features:

• Disposable: Can be discarded after testing
• Lightweight: Quick to start with minimal resource usage
• Docker-based: Leverages container technology for isolation

  Main Use Cases:

• Database testing: MySQL, PostgreSQL, MongoDB, Databend etc.
• Message queue testing: RabbitMQ, Kafka, etc.
• Browser automation testing
• Testing any containerizable service
  Using TestContainers for test cases helps avoid test environment pollution, ensures test environment consistency, simplifies test configuration, and improves test reliability.

This tool is particularly suitable for testing scenarios that depend on external services, enabling quick creation of isolated test environments.

Support Databend for Testcontainers

The Databend team has completed support for Databend data source in three major programming languages through PRs in testcontainer-java, testcontainers-go, and testcontainers-rs. This means developers can easily integrate Databend test environments in projects using these languages.

Prerequisites

• Docker installed in the operating environment
• Development environments for Java, Go, and Rust installed

Java Dependency Configuration

First, create a new Java Demo project. Here’s an example using Maven, adding databend testcontainers and databend-jdbc dependencies in pom.xml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<dependencies>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>databend</artifactId>
        <version>1.20.4</version>
        <scope>test</scope>
    </dependency>

    <dependency>
        <groupId>com.databend</groupId>
        <artifactId>databend-jdbc</artifactId>
        <version>0.2.8</version>
    </dependency>
</dependencies>

For Gradle, use:

1
2

testImplementation "org.testcontainers:databend:1.20.4"

Creating Test Class

1
2
3
4
5
6
7
8
9
10

Create a `TestContainerDatabend` test class with its constructor:
public class TestContainerDatabend {
    private final DatabendContainer dockerContainer;

    public TestContainerDatabend() {
        dockerContainer = new DatabendContainer("datafuselabs/databend:v1.2.615");
        dockerContainer.withUsername("databend").withPassword("databend").withUrlParam("ssl", "false");
        dockerContainer.start();
    }
}

We specified datafuselabs/databend:v1.2.615 as the Docker image for starting Databend, other databend versions available at databend docker hub, then set the username and password, and started the container service.

Here’s the test case:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@Test
public void testSimple() {
    try (Connection connection = DriverManager.getConnection(getJdbcUrl())) {
        DatabendStatement statement = (DatabendStatement) connection.createStatement();
        statement.execute("SELECT 1");
        ResultSet r = statement.getResultSet();
        while (r.next()) {
            int resultSetInt = r.getInt(1);
            System.out.println(resultSetInt);
            assert resultSetInt == 1;
        }
    } catch (Exception e) {
        throw new RuntimeException("Failed to execute statement: ", e);
    }
}

public String getJdbcUrl() {
    return format("jdbc:databend://%s:%s@%s:%s/",
            dockerContainer.getUsername(),
            dockerContainer.getPassword(),
            dockerContainer.getHost(),
            dockerContainer.getMappedPort(8000));
}

While running the test, we can see that testcontainers has started a databend container service in our system:

After the test completes, the container is immediately destroyed and resources are released.

Besides Databend, Testcontainers supports most databases and message queues available in the market, making it easy to build test suites that depend on these resources.

Go

Similarly, for Golang projects requiring Databend services, you can use testcontainers-go:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

package main

import (
    "context"
    "database/sql"
    "testing"

    _ "github.com/datafuselabs/databend-go"
    "github.com/stretchr/testify/require"

    "github.com/testcontainers/testcontainers-go"
    "github.com/testcontainers/testcontainers-go/modules/databend"
)

func TestDatabend(t *testing.T) {
    ctx := context.Background()

    ctr, err := databend.Run(ctx, "datafuselabs/databend:v1.2.615")
    testcontainers.CleanupContainer(t, ctr)
    require.NoError(t, err)

    connectionString, err := ctr.ConnectionString(ctx, "sslmode=disable")
    require.NoError(t, err)

    mustConnectionString := ctr.MustConnectionString(ctx, "sslmode=disable")
    require.Equal(t, connectionString, mustConnectionString)

    db, err := sql.Open("databend", connectionString)
    require.NoError(t, err)
    defer db.Close()

    err = db.Ping()
    require.NoError(t, err)

    _, err = db.Exec("CREATE TABLE IF NOT EXISTS a_table ( \n" +
        " `col_1` VARCHAR(128) NOT NULL, \n" +
        " `col_2` VARCHAR(128) NOT NULL \n" +
        ")")
    require.NoError(t, err)
}

Rust

Since Databend is written in Rust, you can naturally use testcontainer-rs to quickly start a Databend container service in Rust projects:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

#[cfg(test)]
mod tests {
    use databend_driver::Client;

    use crate::{databend::Databend as DatabendImage, testcontainers::runners::AsyncRunner};

    #[tokio::test]
    async fn test_databend() {
        let databend = DatabendImage::default().start().await.unwrap();
        let http_port = databend.get_host_port_ipv4(8000).await.unwrap();
        let dsn = format!(
            "databend://databend:databend@localhost:{}/default?sslmode=disable",
            http_port
        );
        let client = Client::new(dsn.to_string());
        let conn = client.get_conn().await.unwrap();
        let row = conn.query_row("select 'hello'").await.unwrap();
        assert!(row.is_some());
        let row = row.unwrap();
        let (val,): (String,) = row.try_into().unwrap();
        assert_eq!(val, "hello");

        let conn2 = conn.clone();
        let row = conn2.query_row("select 'world'").await.unwrap();
        assert!(row.is_some());
        let row = row.unwrap();
        let (val,): (String,) = row.try_into().unwrap();
        assert_eq!(val, "world");
    }
}

Conclusion

For modern software development, reliable testing frameworks and toolchains are crucial foundations for ensuring code quality. With Databend’s multi-language support for Testcontainers, developers can more conveniently perform database-related integration testing, thereby improving overall development efficiency and code quality.

Whether using Java, Go, or Rust, Testcontainers provides reliable support for Databend developers’ testing work. We look forward to seeing more developers apply this powerful testing tool in real projects to build more robust application systems.

自 2013 年推出以来，Docker 已发展了十多年，现已成为容器技术的行业标准。

它支持所有主流操作系统和云平台，几乎可以将任何类型的应用程序容器化，使应用程序可以在不同的机器、集群甚至云服务之间轻松迁移。

每个 Docker 容器都是通过 Dockerfile 构建的，因此在编写 Dockerfile 时必须遵循最佳实践。

下面我们就来探讨其中的一些做法。

1.根据需要添加文件

在编写 Dockerfile 时，最关键的是要考虑缓存机制。

每次从 Dockerfile 构建 Docker 镜像时，Docker 都会保存在构建过程中生成的缓存。

如果在重建镜像时缓存可用，就能大大加快构建过程。例如，执行 npm install 命令可能需要几分钟才能下载并安装 Node.js 项目的所有依赖项。

因此，在运行 docker 构建命令时，你需要利用这个缓存，这样下一次构建就能快速从缓存中提取数据，而不是每次都要等上几分钟，这既恼人又低效。

如果你不在乎缓存，你的 Dockerfile 可能看起来像这样：

1
2
3
4

FROM node:20
COPY . .
RUN npm install
RUN npm build

该 Dockerfile 使用 Docker 的 COPY 命令将所有项目文件（包括源代码）添加到镜像中，然后执行 npm install 安装依赖项，最后运行 npm build 从源代码中构建应用程序。

虽然这是可行的，但效率不高。假设你运行了 docker build，然后修改了项目文件中的一些业务逻辑，现在又想重建。

第一行 FROM node:20 保持不变，因此 Docker 会使用缓存来处理这部分内容，但缓存会在第二行 COPY … 中断，因为文件已经更改。

Docker 使用分层缓存机制，Dockerfile 中的每一行通常代表一层。

这意味着，一旦某个层的缓存被破坏，所有后续层将不会使用缓存进行构建。

这是因为 Docker 假定后面的每一层都依赖于前面的所有层，这是一个合理的假设。

在我们的示例中，npm install 会在项目文件发生变化时运行，但它实际上并不依赖于项目的源代码；它只依赖于 package.json 和 package-lock.json 文件。

package.json 定义了 npm 需要安装的所有依赖项。那么，让我们来改进 Dockerfile：

1
2
3
4
5

FROM node:20
COPY package*.json .
RUN npm install
COPY . .
RUN npm build

在这里，我使用 package*.json 来复制 package.json 和 package-lock.json。

如你所见，我只在运行 npm install 之后和运行 npm build 之前复制整个应用程序的源代码，因为 npm build 依赖于源代码。

这样，如果源代码发生变化，只要 package.json 保持不变，就可以从缓存中调用 npm install。

只有当我们更改 package.json 中的某些依赖项时，才需要重新运行 npm install。

真正的 Node.js 应用程序 Dockerfile 会有所不同。例如，在添加文件和运行 npm 命令之前，应该设置 WORKDIR。

2.添加 .dockerignore 文件

当你不想把某个文件推送到 Git 仓库时，你可以把它添加到 .gitignore 文件中。
同样，当你不想在 Docker 构建上下文中包含某个文件时，你应该把它添加到 .dockerignore 文件中。

构建 Docker 镜像时，需要指定构建上下文路径，如 docker build -t image_tag .

这里，最后一个点表示使用当前工作目录作为构建上下文。

然后，构建上下文会被发送（复制）到 Docker 守护进程，由它来构建镜像。

以 Node.js 为例，假设我们在本地使用 npm install 和 npm start 来运行应用程序，然后再构建 Docker 镜像。

由于这些命令是直接在本地计算机上执行的，因此 npm 会在项目目录中创建一个 node_modules 目录，以存储所有下载的依赖项。

项目目录结构可能如下：

1
2
3
4
5

node_modules/
public/
src/
package.json
package-lock.json

node_modules 目录的大小很容易达到 1GB。假设我们使用 npm start 在本地测试了应用程序，现在想为应用程序构建 Docker 镜像。

因此，我们在项目目录中创建了一个 Dockerfile，与前面提到的类似。

然后，我们执行命令 docker build -t image_tag 。然而，查看构建日志，你会发现构建上下文的大小接近 1GB：

1
2

=> [internal] load build context
=> => transferring context: 893.00MB

这是因为整个项目目录（包括 node_modules）都是作为构建上下文发送的。

我们希望避免上传 node_modules，因此创建了一个 .dockerignore 文件，并在其中添加了 node_modules。

现在，当我们再次构建 Docker 镜像时，构建日志显示上下文大小比之前小了很多：

1
2

=> [internal] load build context
=> => transferring context: 11.41kB

我们现在的项目结构是:

1
2
3
4
5
6
7

node_modules/
public/
src/
Dockerfile
.dockerignore
package.json
package-lock.json

请记住，.dockerignore 文件应始终放在构建上下文的根目录下。

你可能会问，为什么要将 node_modules 排除在构建上下文之外？

这是因为 node_modules 是由 npm 创建的目录，其中并不包含应用程序的源代码。
它是由本地机器上的本地 npm 创建的。在 Docker 中运行的 npm 应在 Docker 镜像中创建自己的 node_modules。

将本地 node_modules 添加到我们的 Docker 镜像中并不是一个好做法。

只需向 Docker 提供应用程序的源代码，然后在 Docker 内部运行构建命令来构建应用程序。这样，Docker 构建就不会与本地构建冲突。

3.一次性执行所有命令

这很简单。你经常会发现自己在使用 apt 或其他软件包管理器安装必要的软件包。

在运行 apt install 之前，必须先运行 apt update。

与其在 Dockerfile 中使用多个 RUN 指令，不如将它们合并为一个指令：

1
2
3
4

RUN apt-get update && apt-get install -y \
  git \
  jq \
  kubectl

请注意我是如何将软件包名称分成多行，并按字母顺序排列，以提高可读性的。

如果使用多条 RUN 指令，每条指令都会创建一个新层，这会减慢构建过程并占用更多存储空间。

4.设置环境变量和版本

使用 ENV 指令，您可以在构建过程中设置环境变量，这些变量将保留在镜像中，并在容器运行时可用。
可以像这样优雅地修改 PATH 变量：

1

ENV PATH=/opt/maven/bin:${PATH}

如果正在运行一个 Node.js 应用程序，并读取 process.env.PORT，启动服务器时，可以在 Dockerfile 中设置服务器的端口：

1

ENV PORT=8080

一般建议尽可能使用环境变量配置应用程序。

在部署应用程序时，更改环境变量总是比修改代码中的文件然后重新部署应用程序要容易得多。

还可以使用 ENV 指令直观地设置某些依赖项的版本：

1
2
3

ENV KUBECTL_VERSION=1.27
RUN curl -fsSL https://pkgs.k8s.io/core:/stable:/v${KUBECTL_VERSION}/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
...

说到版本和 Docker，强烈建议不要对镜像使用 “latest” 标签。
同样，应避免使用过于具体的版本号（如 1.27.4），因为这将使你无法收到重要的补丁更新，而这些更新可能会修复漏洞或提高安全性。

而应使用主版本号（x）或次版本号（x.y）：

1

FROM python:3.10

也可以只写 “python”，但这样 Docker 就会一直调用最新版本，如果新版本中有任何破坏性更改，就会破坏应用程序。

5.使用多阶段构建

多阶段构建是 Docker 的一项强大功能，但可能被低估了。其概念是将镜像的构建过程分为多个阶段。

最终，只有最后一个阶段的内容会被包含在最终图像中，而之前的阶段则会被丢弃。

典型的用例是在第一阶段使用构建工具和源代码创建二进制文件，然后只将这些二进制文件复制到下一阶段。

最终镜像将不包含源代码或构建工具，这是有道理的，因为最终镜像只需要运行应用程序，而不需要构建它。

1
2
3
4
5
6
7
8
9
10
11
12
13

FROM mcr.microsoft.com/dotnet/sdk:7.0 AS build-env
WORKDIR /App
​
# Build the app
COPY . ./
RUN dotnet restore
RUN dotnet publish -c Release -o out
​
# Build runtime image
FROM mcr.microsoft.com/dotnet/aspnet:7.0
WORKDIR /App
COPY --from=build-env /App/out .
ENTRYPOINT ["dotnet", "DotNet.Docker.dll"]

这个官方示例 Dockerfile 用于构建和运行 ASP.NET 应用程序。请注意 COPY –from=build-env /App/out .命令，它将二进制文件从第一阶段复制到第二阶段。

第一阶段基于包含构建工具的镜像 (mcr.microsoft.com/dotnet/sdk:7.0)，而第二阶段基于较小的运行时奖项 (mcr.microsoft.com/dotnet/aspnet:7.0)。

此外，请注意他们是如何指定镜像的次版本的。

6. 优先考虑使用 Slim 和 Alpine Image

Alpine 镜像基于 Alpine Linux，而 Alpine Linux 以轻量级著称，这使得 Alpine 镜像理论上可以更快地构建、调用和运行。

1
2
3
4

REPOSITORY   TAG            SIZE
python       3.10-alpine    50.4MB
python       3.10-slim      128MB
python       3.10           1GB

以 Python 为例，Alpine 镜像的大小是基于 Debian 的完整镜像的 1/20。

Python 还提供 Slim 镜像，它基于 Debian，但去除了大部分标准软件包。

在 Go 中，创建设计模式有助于管理对象的创建，并控制对象的实例化方式。这些模式在对象创建过程复杂或需要特殊处理时特别有用。以下是 Go 中常用的主要创建模式：

单例模式

单例模式确保一个类只有一个实例，并提供一个全局访问点。

如何实现

1. 定义一个结构，并将其作为单个实例。
2. 为该结构创建一个全局变量，但不要立即将其初始化。
3. 使用 sync.Once 确保实例只创建一次，即使在多线程情况下也是如此。
4. 提供一个全局函数来返回实例。

以下是实现单例模式的基本示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

package main

import (
 "fmt"
 "sync"
)

type (
 singleton struct {
  data string
 }
)

var instance *singleton
var once sync.Once

// Function to return the single instance
func GetInstance() *singleton {
 // Use sync.Once to ensure the instance is created only once
 once.Do(func() {
  instance = &singleton{data: "This is a singleton"}
 })

 return instance
}

func main() {
 s1 := GetInstance()
 s2 := GetInstance()

 // Both should point to the same instance
 fmt.Println(s1 == s2) // true
 fmt.Println(s1.data)  // "This is a singleton"
}

sync.Once 可确保实例只创建一次，即使在并发调用 GetInstance 的情况下也是如此。

工厂方法模式

工厂方法模式定义了创建对象的接口，但允许子类改变将创建的对象类型。在 Go 中，这可以通过创建工厂函数来实现。这种设计模式提供一种将实例化逻辑委托给子类的方法，从而可以灵活地创建对象。

实现步骤：

1. 创建一个为不同对象定义通用行为的接口。
2. 创建多个实现此接口的结构体。
3. 创建一个函数（工厂方法），接收一些输入（如类型）并返回相应结构的实例。

以下是实现工厂方法模式的基本示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

package main

import (
 "fmt"
)

type Animal interface {
  Speak() string
 }

 Dog struct{}
 Cat struct{}
)

func (d Dog) Speak() string {
 return "Woof!"
}

func (c Cat) Speak() string {
 return "Meow!"
}

func AnimalFactory(animalType string) Animal {
 if animalType == "dog" {
  return &Dog{}
 } else if animalType == "cat" {
  return &Cat{}
 }
 return nil
}

func main() {
 dog := AnimalFactory("dog")
 fmt.Println(dog.Speak()) // Woof!

 cat := AnimalFactory("cat")
 fmt.Println(cat.Speak()) // Meow!
}

工厂方法允许创建不同类型的对象，但用户端隐藏了创建逻辑。当对象创建过程比较复杂，需要进行抽象时，这种模式尤其有用。

抽象工厂模式

抽象工厂（Abstract Factory）提供了一个接口，用于创建相关或依赖对象的族，而无需指定它们的具体类。在 Go 中，可以通过定义不同的工厂接口来实现它。

当系统需要独立于其对象的创建、组成和表示方式时，它就非常有用。它允许创建相关对象族。

以下是实现抽象工厂模式的基本示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

package main

import (
 "fmt"
)

// Define an abstract factory
type (
 GUIFactory interface {
  CreateButton() Button
  CreateCheckbox() Checkbox
 }
)

// Define interfaces for products
type (
 Button interface {
  Press() string
 }

 Checkbox interface {
  Check() string
 }

 // Implement concrete products for Windows
 WindowsButton   struct{}
 WindowsCheckbox struct{}

 // Implement concrete products for Mac
 MacButton   struct{}
 MacCheckbox struct{}

 // Implement factories for each platform
 WindowsFactory struct{}
 MacFactory     struct{}
)

func (w *WindowsButton) Press() string { return "Windows Button Pressed" }

func (w *WindowsCheckbox) Check() string { return "Windows Checkbox Checked" }

func (m *MacButton) Press() string { return "Mac Button Pressed" }

func (m *MacCheckbox) Check() string { return "Mac Checkbox Checked" }

func (w *WindowsFactory) CreateButton() Button     { return &WindowsButton{} }
func (w *WindowsFactory) CreateCheckbox() Checkbox { return &WindowsCheckbox{} }

func (m *MacFactory) CreateButton() Button     { return &MacButton{} }
func (m *MacFactory) CreateCheckbox() Checkbox { return &MacCheckbox{} }

func main() {
 // Get a Windows factory
 var wf GUIFactory = &WindowsFactory{}
 button := wf.CreateButton()
 checkbox := wf.CreateCheckbox()

 fmt.Println(button.Press())   // Output: Windows Button Pressed
 fmt.Println(checkbox.Check()) // Output: Windows Checkbox Checked

 var mf GUIFactory = &MacFactory{}
 button = mf.CreateButton()
 checkbox = mf.CreateCheckbox()

 fmt.Println(button.Press())   // Output: Mac Button Pressed
 fmt.Println(checkbox.Check()) // Output: Mac Checkbox Checked
}

Builder 模式

构建器模式将复杂对象的构建与其表示分离开来，允许同一构建过程创建不同的表示。它能解决问题：复杂的对象通常是一步一步构建的。构建器模式为创建此类对象提供了灵活的解决方案，分解了实例化过程。

以下是实现构建器模式的基本示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

package main

import (
 "fmt"
)

// Product to be built
type House struct {
  windows string
  doors   string
  roof    string
 }

 // Concrete builder for a villa
 type VillaBuilder struct {
  house House
 }

 // Director controls the building process
 type Director struct {
  builder HouseBuilder
 }
)

// Builder interface
type HouseBuilder interface {
  SetWindows() HouseBuilder
  SetDoors() HouseBuilder
  SetRoof() HouseBuilder
  Build() *House
 }


func (v *VillaBuilder) SetWindows() HouseBuilder {
 v.house.windows = "Villa Windows"
 return v
}

func (v *VillaBuilder) SetDoors() HouseBuilder {
 v.house.doors = "Villa Doors"
 return v
}

func (v *VillaBuilder) SetRoof() HouseBuilder {
 v.house.roof = "Villa Roof"
 return v
}

func (v *VillaBuilder) Build() *House {
 return &v.house
}

func (d *Director) Construct() *House {
 return d.builder.SetWindows().SetDoors().SetRoof().Build()
}

func main() {
 director := &Director{}

 // Build a villa
 v_builder := &VillaBuilder{}
 director.builder = v_builder
 villa := director.Construct()
 fmt.Println(*villa) // Output: {Villa Windows Villa Doors Villa Roof}
}

在创建需要大量可选配置的复杂对象时，创建者模式非常有用。

原型模式

原型模式允许通过复制现有对象（原型）来创建新对象，而不是从头开始创建。
当创建一个新对象的成本很高，而现有对象又可以克隆重用时，原型模式就派上用场了。

以下是实现原型模式的基本示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

package main

import (
 "fmt"
)

// Cloneable interface
type (
 Cloneable interface {
  Clone() Cloneable
 }
)

// Concrete struct (prototype)
type (
 Product struct {
  name     string
  category string
 }
)

// Clone method creates a copy of the Product
func (p *Product) Clone() Cloneable {
 return &Product{name: p.name, category: p.category}
}

func (p *Product) SetName(name string) {
 p.name = name
}

func (p *Product) GetDetails() string {
 return fmt.Sprintf("Product Name: %s, Category: %s", p.name, p.category)
}

func main() {
 // Original product
 original := &Product{name: "Phone", category: "Electronics"}
 fmt.Println(original.GetDetails()) // Output: Product Name: Phone, Category: Electronics

 // Clone the product and change its name
 cloned := original.Clone().(*Product)
 cloned.SetName("Smartphone")
 fmt.Println(cloned.GetDetails()) // Output: Product Name: Smartphone, Category: Electronics
}

当创建对象的成本很高，而你又想通过复制现有对象来创建多个类似对象时，原型模式就很有效。这种模式通过克隆现有实例来简化对象的创建，而不是从头开始创建新实例。

总结

每种模式都有其特定的用例，选择恰当的设计模式会使代码更有条理、可重用且更易于维护！

本文介绍内存泄漏的常见原因以及如何避免。
无论使用哪种编程语言，内存泄漏都是一个常见问题。本文将说明可能发生内存泄漏的几种情况，让我们学习如何通过研究这些反模式来避免内存泄漏。

未关闭已打开的文件

结束打开文件时，应始终调用其关闭方法。否则可能会导致文件描述符数量达到上限，从而无法打开新文件或连接。这可能会导致 “too many open files”错误。

代码示例 1：不关闭文件导致文件描述符耗尽。

1
2
3
4
5
6
7
8
9
10
11
12
13

func main() {  
    files := make([]*os.File, 0)  
    for i := 0; ; i++ {  
       file, err := os.OpenFile("test.log", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)  
       if err != nil {  
          fmt.Printf("Error at file %d: %v\n", i, err)  
          break  
       } else {  
          _, _ = file.Write([]byte("Hello, World!"))  
          files = append(files, file)  
       }  
    }  
}

输出：

1

Error at file 61437: open test.log: too many open files

在我的 Mac 上，一个进程最多可以打开 61 440 个文件句柄。 Go 进程通常会打开三个文件描述符（stderr、stdout、stdin），因此最多只能打开 61437 个文件。可以手动调整这一限制。

未关闭 http.Response.Body

Go 有比较容易犯的错误，即忘记关闭 HTTP 请求的正文会导致内存泄漏。例如

代码示例 2：未关闭 HTTP 主体导致内存泄漏。

1
2
3
4
5
6
7
8
9
10
11
12
13

func makeRequest() {  
    client := &http.Client{}  
    req, err := http.NewRequest(http.MethodGet, "http://localhost:8081", nil)  
    res, err := client.Do(req)  
    if err != nil {  
       fmt.Println(err)  
    }  
    _, err = ioutil.ReadAll(res.Body)  
    // defer res.Body.Close()  
    if err != nil {  
       fmt.Println(err)  
    }  
}

字符串和切片内存泄漏

Go 规范没有明确说明子串是否与其原始字符串共享内存。不过，编译器允许这种行为，这通常是好事，因为它减少了内存和 CPU 的使用。但有时这会导致暂时的内存泄露。

代码示例 3：字符串导致的内存泄漏。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

func main() {
Demo1()
runtime.GC()
time.Sleep(1 * time.Second)
exit()
}
func exit() {
fmt.Println("Saving heap profile...")
// create a  heap profile
f, err := os.Create("heap.pprof")
if err != nil {
log.Fatal("could not create heap profile: ", err)
}
runtime.GC()
//time.Sleep(1 * time.Second)
//  heap profile
if err = pprof.WriteHeapProfile(f); err != nil {
log.Fatal("could not write heap profile: ", err)
}
fmt.Println("Heap profile saved in heap.pprof")
_ = f.Close()
}

var packageStr1 []string

func Demo1() {
for i := 0; i < 10; i++ {
s := createStringWithLengthOnHeap(1 << 20) //1M
packageStr1 = append(packageStr1, s[:50])
}
}

func createStringWithLengthOnHeap(i int) string {
s := make([]byte, i)
for j := 0; j < i; j++ {
s[j] = byte(j % 256 % (rand.Intn(256) + 1))
}
return string(s)
}

为了防止临时内存泄漏，我们可以使用 strings.Clone()。

代码示例 4：使用 strings.Clone() 避免临时内存泄漏。

1
2
3
4
5
6

func Demo1() {  
    for i := 0; i < 10; i++ {  
       s := createStringWithLengthOnHeap(1 << 20) // 1MB  
       packageStr1 = append(packageStr1, strings.Clone(s[:50]))  
    }  
}

Goroutine Handler

大多数内存泄漏都是由于程序泄漏造成的。例如，下面的示例会迅速耗尽内存，导致 OOM（内存不足）错误。
代码示例 5：goroutine 处理程序泄漏。

1
2
3
4
5
6

for {  
       go func() {  
          time.Sleep(1 * time.Hour)  
       }()  
    }  
}

滥用 Channels

不正确地使用 channel 也很容易导致程序泄漏。对于无缓冲通道，在向通道写入数据之前，生产者和消费者都必须准备就绪，否则通道就会阻塞。在下面的示例中，函数提前退出，导致了程序泄漏。

代码示例 6：非缓冲通道滥用导致程序泄漏。

1
2
3
4
5
6
7
8
9
10
11
12
13

func Example() {
    a := 1
    c := make(chan error)
    go func() {
        c <- err
        return
    }()
    // Example exits here, causing a goroutine leak.
    if a > 0 {
        return
    }
    err := <-c
}

只需将其改为缓冲通道即可解决这一问题： c := make(chan error, 1)

滥用 range with Channels

可以使用 range 遍历通道。但是，如果通道为空，range 将等待新数据，可能会阻塞 goroutine。

代码示例 7：滥用范围导致程序泄漏。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

func main() {  
    wg := &sync.WaitGroup{}  
    c := make(chan any, 1)  
    items := []int{1, 2, 3, 4, 5}  
    for _, i := range items {  
       wg.Add(1)  
       go func() {  
          c <- i  
       }()  
    }  
    go func() {  
       for data := range c {  
          fmt.Println(data)  
          wg.Done()  
       }  
       fmt.Println("close")  
    }()  
    wg.Wait()  
    time.Sleep(1 * time.Second)  
}

要解决这个问题，请在调用 wg.Wait() 后关闭通道。

误用 runtime.SetFinalizer.

如果两个对象都使用 runtime.SetFinalizer 进行了设置，并且它们相互引用，那么即使它们不再使用，也不会被垃圾回收。

time.Ticker

这是 Go 1.23 之前的一个问题。如果不调用 ticker.Stop()，可能会导致内存泄漏。Go 1.23 已修复了这个问题。

滥用 defer

虽然使用延迟释放资源不会直接导致内存泄漏，但它会通过两种方式导致临时内存泄漏：

• 执行时间：延迟总是在函数结束时执行。如果函数运行时间过长或从未结束，则 defer 中的资源可能无法及时释放。

• 内存使用：每个延迟都会在内存中增加一个调用点。如果在循环内使用，可能会导致临时内存泄漏。

代码示例 8：延迟导致的临时内存泄漏。

1
2
3
4
5
6
7
8
9
10
11

func ReadFile(files []string) {  
    for _, file := range files {  
      f, err := os.Open(file)  
      if err != nil {  
         fmt.Println(err)  
         return  
      }  
      // do something  
      defer f.Close()  
    }  
}

这段代码会造成临时内存泄漏，并可能导致 “too many open files” 的错误。除非必要，否则应避免过度使用延迟。

结论

本文介绍了 Go 中可能导致内存泄漏的几种行为，其中最常见的是 goroutine 泄漏。通道的不当使用，尤其是选择和范围的不当使用，会增加检测泄漏的难度。当遇到内存泄漏时，pprof 可以帮助快速定位问题，确保我们编写出更健壮的代码。References。

Go 标准库中有一个 varint 的内置实现，可以在 encoding/binary/varint.go 中找到。这个实现类似于 protobuf 中使用的 varint。利用 Golang 标准库的 varint 源代码，我们将系统地学习和复习 varint 的概念。 如果您熟悉 protobuf，您可能已经知道所有整数类型（除了固定类型，如 fixed32 和 fixed64）都使用 varint 编码。
varint 主要解决了两个问题：

• 空间效率：以 uint64 为例，它可以表示 18,446,744,073,709,551,615 这样大的数值。但在大多数实际应用中，我们的整数值要小得多。如果你的系统需要处理小到 1 的值，那么在传输过程中，你仍然需要使用 8 个字节来表示这个值，这就浪费了空间，因为大多数字节并不存储有用的数据。varint 编码使用长度可变的字节序列来表示整数，从而减少了较小值所需的空间。

• 兼容性：varint 允许我们在不改变编码/解码逻辑的情况下处理不同大小的整数。这意味着字段可以从较小的类型（如 uint32）升级到较大的类型（如 uint64），而不会破坏向后兼容性。

本文将深入研究 Golang varint 的实现，探讨其设计原理以及如何应对负数编码的挑战。

varint 的设计原则

varint 的设计基于简单的原则：

• 7 位分组：整数的二进制表示分为 7 位组。从最小有效位到最大有效位，每个 7 位组都是一个单位。

• 延续位：在每个 7 位组之前添加一个标志位，形成一个 8 位字节。如果后面有更多字节，则标志位设置为 1；否则设置为 0。

例如，整数 uint64(300) 的二进制表示为 100101100。将其分为两组-10 和 0101100，再加上标志位，就得到两个字节：00000010 和 10101100，这就是 300 的 varint 编码。与使用 4 个字节的 uint64 相比，varint 减少了 75% 的存储空间。

1
2
3
4
5
6
7
8
9
10

// list1:  uint64 to varint
func main() {  
    v := uint64(300)  
    bytes := make([]byte, 0)  
    bytes = binary.AppendUvarint(bytes, v)  
    fmt.Println(len(bytes))  
    for i := len(bytes); i > 0; i-- {  
       fmt.Printf("%08b ", bytes[i-1])  
    }  
}

varint 表示无符号整数

Go 标准库提供了两组 varint 函数：一组用于无符号整数（PutUvarint、Uvarint），另一组用于有符号整数（varint、Putvarint）。 让我们先看看无符号整数 varint 的实现：

1
2
3
4
5
6
7
8
9
10
11

// list2: go src PutUvarint
func PutUvarint(buf []byte, x uint64) int {
    i := 0
    for x >= 0x80 {
        buf[i] = byte(x) | 0x80
        x >>= 7
        i++
    }
    buf[i] = byte(x)
    return i + 1
}

代码中有一个基本常数：0x80 相当于二进制代码 1000 0000。这个常数对后面的逻辑非常重要：

• x >= 0x80：这将检查 x 是否需要超过 7 位的表示。如果需要，则需要拆分 x。

• byte(x) | 0x80：这将对 0x80（1000 0000）进行位操作，确保最高位设置为 1，并提取 x 的最低 7 位。

• x >>= 7：将 x 右移 7 位，以处理下一组。

• buf[i] = byte(x)：当循环结束时，最高位全为 0，因此无需进一步操作。

Uvarint 与 PutUvarint 相反。

需要注意的是：varint 将整数分成 7 位组，这意味着大整数可能会面临效率低下的问题。例如，uint64 的最大值需要 10 个字节，而不是通常的 8 个字节（64/7 ≈ 10）。

负数编码之字形编码

虽然 varint 的效率很高，但它并不考虑负数。在计算中，数字是以 2 的补码形式存储的，这意味着一个小的负数可能有一个很大的二进制表示。 例如，32 位形式的 -5 表示为 1111111111111111111111111011，在 varint 编码中需要 5 个字节
Go 使用之字形编码来解决这个问题：

• 对于正数 n，将它们映射为 2n。
• 对于负数-n，将其映射为 2n-1。
  例如，对 int32(-5) 进行 “之 “字形编码后，其值变为 9（000000000000000000001001），而 varint 只需 1 个字节即可表示该值。

下面是 Golang 的实现：

1
2
3
4
5
6
7
8

// go src Putvarint
func Putvarint(buf []byte, x int64) int {
    ux := uint64(x) << 1
    if x < 0 {
        ux = ^ux
    }
    return PutUvarint(buf, ux)
}

从代码中我们可以看到，对于有符号整数 varint 的实现，Go 标准库将其分为两个步骤：

• 首先，使用 ZigZag 编码转换整数。
• 然后，使用 varint 对转换后的值进行编码。

对于负数，还有一个额外的步骤：ux = ^ux。这部分可能会让人感到困惑–为什么这种变换的结果是 2n -1？

假设我们有一个整数 -n，我们可以大致推导出这个过程：

• 首先，将原值左移，然后倒置。结果是 2*(~(-n)) + 1。

• 负数的二进制是其绝对值加 1 的位反转。那么，我们如何从二的补码得出绝对值呢？有这样一个公式|A| = ~A + 1。

• 将此公式代入第一步：2*（n - 1）+ 1 = 2n - 1。这与负数的 ZigZag 编码完全吻合。

在 Go 标准库中，调用 PutUvarint 只应用 varint 编码，而调用 PutVarint 则首先应用 ZigZag 编码，然后再应用 varint 编码。

在 protobuf 中，如果类型是 int32、int64、uint32 或 uint64，则只使用 varint 编码。但是，对于 sint32 和 sint64，首先使用 ZigZag 编码，然后使用 varint 编码。

当 varint 不适用时

尽管 varint 有很多优点，但它并不是所有情况下都适用：

• 大整数：对于大整数，varint 编码的效率可能低于定长编码。
• 随机数据访问：由于 varint 使用可变长度，直接索引特定整数具有挑战性。
• 频繁的数学运算：变量编码数据需要在运算前解码，可能会影响性能。
• 安全敏感型应用：varint 编码可能会泄露原始整数大小的信息，这在安全环境中是不可接受的。

背景介绍

JSON 是一种轻量级数据交换格式，自十年前 Go 的编码/json 软件包问世以来，开发人员一直对其灵活的特性青睐有加。开发人员可以通过 struct 标记自定义 struct 字段的 JSON 表示法，也允许 Go 类型自定义自己的 JSON 表示法。然而，随着 Go 语言和 JSON 标准的发展，一些功能缺陷和性能限制也逐渐暴露出来。

• 功能缺失：例如，无法为 time.Time 类型指定自定义格式，无法在序列化过程中省略特定的 Go 值等。
• API 的缺陷：例如，没有简单的方法从 io.Reader.Reader 中正确反序列化 JSON。
• 性能限制：标准 json 软件包的性能并不令人满意，尤其是在处理大量数据时。

• 行为缺陷：例如，JSON 语法的错误处理不够严格，反序列化不区分大小写等。

与 math/v2 一样，Go 官方也提出了 encoding/json/v2 来解决上述问题。本文的主要目的是分析在 encoding/json 中有关空值的一些问题，以及在 encoding/json/v2 中如何解决这些问题。本文不涉及 encoding/json/v2 中的其他修改。

omitempty 行为

在 encoding/json 包中，对 omitempty 有如下描述：

omitemptyoption 指定，如果字段的值为空（定义为 false、0、nil 指针、nil 接口值以及任何空数组、片、映射或字符串），则编码中应省略该字段。

这种预定义的 nil value 的判断逻辑并不能满足所有实际场景的需要。让我们来看一个例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

type Post struct {  
    Id         int64           `json:"id,omitempty"`  
    CreateTime time.Time       `json:"create_time,omitempty"`  
    TagList    []Tag           `json:"tag_list,omitempty"`  
    Name       string          `json:"name,omitempty"`  
    Score      float64         `json:"score,omitempty"`  
    Category   Category        `json:"category,omitempty"`  
    LikePost   map[string]Post `json:"like,omitempty"`  
}  
type Tag struct {  
    ID   string `json:"id"`  
    Name string `json:"name"`  
}  
type Category struct {  
    ID   float64 `json:"id"`  
    Name string  `json:"name"`  
}  
  
func main() {  
    b, _ := json.Marshal(new(Post))  
    fmt.Println(string(b))  
}

输出结果为:

1

{"create_time":"0001-01-01T00:00:00Z","category":{"id":0,"name":""}}

虽然在 Post 的每个字段中都添加了 omitempty，但结果并不尽如人意。

• omitempty 不能处理空结构，如 Post.Category
• omitempty 处理 time.Time 的方式不是我们理解的 UTC =0，即 1970-01-01 00:00:00，而是 0001-01-01T00:00:00Z。

omitzero Tag

在 encoding/json/v2 中，将添加一个新标签 omitzero，它增加了两个功能来解决上述两个问题。(此功能仍在开发中，开发者可以通过 go-json-experiment/json 提前体验新功能）

• 更好地处理时间类型
• 支持自定义 IsZero 函数，例如以下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

package main  
  
import (  
    "encoding/json"  
    "fmt"    v2_json "github.com/go-json-experiment/json"  
    "math"    "time")  
  
type Post struct {  
    Id         int64           `json:"id,omitempty,omitzero"`  
    CreateTime time.Time       `json:"create_time,omitempty,omitzero"`  
    TagList    []Tag           `json:"tag_list,omitempty"`  
    Name       string          `json:"name,omitempty"`  
    Score      ScoreType       `json:"score,omitempty,omitzero"`  
    Category   Category        `json:"category,omitempty,omitzero"`  
    LikePost   map[string]Post `json:"like,omitempty"`  
}  
type ScoreType float64  
  
func (s ScoreType) IsZero() bool {  
    return s < math.MinInt64  
}  
  
type Tag struct {  
    ID   string `json:"id"`  
    Name string `json:"name"`  
}  
type Category struct {  
    ID   float64 `json:"id"`  
    Name string  `json:"name"`  
}  
  
func main() {  
    v1String, _ := json.Marshal(new(Post))  
    fmt.Println(string(v1String))  
    v2String, _ := v2_json.Marshal(new(Post))  
    fmt.Println(string(v2String))  
}

与 encoding/json 相比，encoding/json/v2 解决了上述问题。

输出结果为：

1
2

{"create_time":"0001-01-01T00:00:00Z","category":{"id":0,"name":""}}
{"score":0}

结论

通过引入 omitzero 标记，Go 在解决 JSON 编码中 nil value 处理的痛点方面迈出了非常关键的一步。这一解决方案不仅满足了开发人员对更灵活的 nil 值定义的需求，还保持了与现有系统的兼容性。omitzero 的登陆时间尚未确定，最早也要等到 Go 1.24 版本。

此外，encoding/xml 和其他软件包也将遵循 json 软件包，并添加 omitzero 标记。encoding/json/v2 还包括其他方面的更新，例如性能。感兴趣的 Gophers 可以提前了解这些变化，本博客也将继续关注这一提议。

Eli Bendersky 2024年9月12日

随着过去一年大型语言模型（LLM）及其相关工具（如嵌入模型）的能力显著增长，越来越多的开发者开始考虑将 LLM 集成到他们的应用程序中。

由 于LLM 通常需要专用硬件和大量的计算资源，它们最常见的形式是作为提供 API 访问的网络服务。这就是领先的 LLM 如 OpenAI 或Google Gemini 的 API 的工作方式；即使是运行你自己的 LLM 工具，如 Ollama，也会将 LLM 包装在 REST API 中供本地使用。此外，利用 LLM 的开发者通常还需要辅助工具，如向量数据库，这些通常也作为网络服务部署。

换句话说，LLM 驱动的应用程序很像其他现代云原生应用程序：它们需要对 REST 和 RPC 协议、并发性和性能有出色的支持。这些恰好是Go 擅长的领域，使它成为编写 LLM 驱动应用程序的绝佳语言。

这篇博客文章通过一个简单的例子，展示了如何使用 Go 为 LLM 驱动的应用程序工作。它首先描述了演示应用程序要解决的问题，然后展示了几个变体的应用程序，它们都完成了相同的任务，但使用了不同的包来实现。这篇帖子的所有演示代码都可以在线获取。

用于问答的 RAG 服务器

LLM 驱动应用程序的一种常见技术是 RAG - Retrieval Augmented Generation。RAG 是为特定领域的交互定制 LLM 知识库的最可扩展方式之一。

我们将用 Go 构建一个 RAG 服务器。这是一个 HTTP 服务器，为用户提供两个操作：

• 向知识库添加文档
• 向 LLM 提问有关这个知识库的问题

在典型的现实世界场景中，用户会向服务器添加一批文档，然后开始提问。例如，一家公司可以用内部文档填充 RAG 服务器的知识库，并使用它为内部用户提供 LLM 驱动的问答能力。

以下是显示我们服务器与外部世界交互的图：

除了用户发送 HTTP 请求（上述两个操作）之外，服务器还与以下内容交互：

• 一个嵌入模型，用于计算提交的文档和用户问题的向量嵌入。
• 一个向量数据库，用于存储和高效检索嵌入。

• 一个 LLM，用于根据从知识库收集的上下文提出问题。
  具体来说，服务器向用户公开两个HTTP端点：

• /add/: POST {“documents”: [{“text”: “…”}, {“text”: “…”}, …]}: 向服务器提交一系列文本文档，以便添加到其知识库中。对于此请求，服务器：

  • 使用嵌入模型为每个文档计算向量嵌入。
  • 将文档及其向量嵌入存储在向量数据库中。
• /query/: POST {“content”: “…”}: 向服务器提交一个问题。对于此请求，服务器：
  • 使用嵌入模型计算问题的向量嵌入。
  • 使用向量数据库的相似性搜索找到知识库中最相关文档。
  • 使用简单的提示工程将问题重新表述为在步骤（2）中找到的最相关文档作为上下文，并将其发送给LLM，将答案返回给用户。

我们的演示使用的服务包括：

• Google Gemini API 用于 LLM 和嵌入模型。
• Weaviate 作为本地托管的向量数据库；Weaviate 是一个用 Go 实现的开源向量数据库。
• 应该很容易用其他等效服务替换这些。事实上，这就是第二个和第三个服务器变体的全部内容！我们将从直接使用这些工具的第一个变体开始。

直接使用 Gemini API 和 Weaviate

Gemini API 和 Weaviate 都有方便的 Go SDK(客户端库），我们的第一个服务器变体直接使用这些。这个变体的完整代码在这个目录中。

我们不会在这篇博客文章中复制整个代码，但在阅读时请注意以下几点：

• 结构：代码结构对于任何写过Go HTTP服务器的人来说都很熟悉。Gemini和Weaviate的客户端库被初始化，客户端存储在传递给HTTP处理程序的状态值中。

• 路由注册：使用 Go 1.22 中引入的路由增强功能，我们的服务器的 HTTP 路由很容易设置：

  1 2 3

  mux := http.NewServeMux() mux.HandleFunc("POST /add/", server.addDocumentsHandler) mux.HandleFunc("POST /query/", server.queryHandler)

• 并发性：我们的服务器的 HTTP 处理程序通过网络访问其他服务并等待响应。这对 Go 来说不是问题，因为每个 HTTP 处理程序都在自己的 goroutine 中并发运行。这个 RAG 服务器可以处理大量并发请求，每个处理程序的代码都是线性和同步的。

• 批量 API：由于 /add/ 请求可能提供大量文档添加到知识库，服务器利用嵌入（embModel.BatchEmbedContents）和 Weaviate DB（rs.wvClient.Batch）的批量 API 以提高效率。

使用 LangChainGo

我们的第二个 RAG 服务器变体使用 LangChainGo 来完成相同的任务。

LangChain 是一个流行的 Python 框架，用于构建 LLM 驱动的应用程序。LangChainGo 是它的 Go 框架。该框架有一些工具，可以将应用程序构建为模块化组件，并支持许多 LLM 提供商和向量数据库的通用 API。这允许开发者编写可以与任何提供商一起工作的代码，并很容易地更改提供商。

这个变体的完整代码在这个目录中。在阅读代码时，你会注意到两件事：

• 首先，它比之前的变体稍短。LangChainGo 负责包装向量数据库的完整 API 到通用接口中，初始化和处理 Weaviate 所需的代码更少。
• 其次，LangChainGo API 使得切换提供商相当容易。假设我们想用另一个向量数据库替换 Weaviate；在我们之前的变体中，我们将不得不重写所有与向量数据库接口的代码以使用新的 API。有了像 LangChainGo 这样的框架，我们就不再需要这样做了。只要 LangChainGo 支持我们感兴趣的新向量数据库，我们应该能够替换我们服务器中的几行代码，因为所有数据库都实现了一个通用接口：

  1 2 3 4

  type VectorStore interface { AddDocuments(ctx context.Context, docs []schema.Document, options ...Option) ([]string, error) SimilaritySearch(ctx context.Context, query string, numDocuments int, options ...Option) ([]schema.Document, error) }

使用 Genkit for Go

今年早些时候，Google 为 Go 引入了 Genkit - 一个构建 LLM 驱动应用程序的新开源框架。Genkit 与 LangChain 有一些共同的特点，但在其他方面有所不同。

像LangChain一样，它提供了可以由不同提供商（作为插件）实现的通用接口，从而使从一个提供商切换到另一个提供商变得更简单。然而，它并不试图规定不同的LLM组件如何交互；相反，它专注于生产特性，如提示管理和工程，以及集成开发工具的部署。

我们的第三个RAG服务器变体使用Genkit for Go来完成相同的任务。它的完整代码在这个目录中。

这个变体与LangChainGo非常相似 - 使用LLM、嵌入器和向量数据库的通用接口，而不是直接提供商API，使得从一个切换到另一个变得更容易。此外，使用Genkit将LLM驱动的应用程序部署到生产环境要容易得多；我们没有在我们的变体中实现这一点，但如果你感兴趣，可以阅读文档。

总结 - Go 用于 LLM 驱动的应用程序

这篇文章中的示例只是构建 Go 中 LLM 驱动应用程序的可能性的一小部分。它展示了如何用相对较少的代码构建一个功能强大的 RAG 服务器；最重要的是，由于 Go 的一些基本特性，这些示例具有相当程度的生产准备度。

与LLM服务合作通常意味着向网络服务发送 REST 或 RPC 请求，等待响应，根据该响应向其他服务发送新请求等等。Go 在所有这些方面都表现出色，为管理并发性和处理网络服务的复杂性提供了出色的工具。

此外，Go 作为云原生语言的卓越性能和可靠性使其成为实现 LLM 生态系统更基本构建块的自然选择。一些例子包括 Ollama、LocalAI、Weaviate 或 Milvus 等项目。

探索 Goja：Golang 中的 JavaScript 运行时

这篇文章探讨了 Goja，这是 Golang 生态系统中的一个 JavaScript 运行时库。Goja 作为一个在 Go 应用程序中嵌入 JavaScript 的强大工具，提供了独特的优势，尤其是在操作数据和提供不需要 go build 过程中的 SDK。

背景：Goja 的需求

在我的项目中，我在查询和操作大型数据集时遇到了挑战。最初，一切都是用 Go 编写的，这在效率上是有利的，但在处理复杂的 JSON 响应时变得笨拙。虽然 Go 的极简主义方法通常是一个优势，但特定任务所需的冗长性减慢了我的速度。

使用嵌入式脚本语言可以简化这个过程，这让我探索了各种选项。Lua 是我的首选，因为它以轻量级和可嵌入而闻名。但我很快发现，Go 中的 Lua 库在实现、版本（5.1、5.2 等）和活跃支持方面参差不齐。

然后我调查了 Go 生态系统中其他流行的脚本语言。我考虑了 Expr、V8 和 Starlark 等选项，但最终 Goja 成为了最有希望的候选者。

这里是我在这些库上进行基准测试的 GitHub 仓库，测试了它们的性能和与 Go 的集成便利性。

为什么选择 Goja？

Goja 因其与 Go 结构体的无缝集成而赢得了我的青睐。当你将一个 Go 结构体分配给 JavaScript 运行时中的一个值时，Goja 会自动推断字段和方法，使它们在 JavaScript 中可访问，而不需要单独的桥接层。它利用 Go 的反射能力来调用这些字段上的 getter 和 setter，提供了 Go 和 JavaScript 之间强大而透明的交互。

让我们通过一些示例来看看 Goja 的实际应用。这些示例突出了我发现有用的特性，但我希望在文档中有更多示例。

赋值和返回值

首先，让我们来看一个简单的例子，我们将一个从 1 到 100 的整数数组从 Go 传递到 JavaScript 运行时，并过滤出偶数值。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

package main

import (
"fmt"

"github.com/dop251/goja"
)

func main() {
vm := goja.New()

// 从 1 到 100 传递一个整数数组
values := []int{}
for i := 1; i <= 100; i++ {
values = append(values, i)
}

// 定义 JavaScript 代码以过滤偶数值
script := `
values.filter((x) => {
return x % 2 === 0;
})
  `

// 在 JavaScript 运行时中设置数组
vm.Set("values", values)

// 运行脚本
result, err := vm.RunString(script)
if err != nil {
panic(err)
}

// 将结果转换回 Go 的空接口切片
filteredValues := result.Export().([]interface{})

fmt.Println(filteredValues)
// 输出：[2 4 6 8 10 12 14 16 18 20 22 24 26 28 30 32 34 36 38 40 42 44 46 48 50 52 54 56 58 60 62 64 66 68 70 72 74 76 78 80 82 84 86 88 90 92 94 96 98 100]

first := filteredValues[0].(int64)
fmt.Println(first)
}

在这个例子中，你可以看到在 Goja 中遍历数组不需要显式类型注释。Goja 能够根据内容推断数组的类型，这得益于 Go 的反射机制。在过滤值并返回结果时，Goja 将结果转换回空接口切片（[]interface{}）。这是因为 Goja 需要在 Go 的静态类型系统中处理 JavaScript 的动态类型。

如果你需要在 Go 中处理结果值，你将不得不执行类型断言以提取整数。在内部，Goja 将所有整数表示为 int64。

结构体和方法调用

接下来，让我们探索 Goja 如何处理 Go 结构体，特别关注方法和导出字段。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

package main

import (
    "fmt"
    "github.com/dop251/goja"
)

type Person struct {
    Name string
    age  int
}

// 获取年龄的方法（未导出）
func (p *Person) GetAge() int {
    return p.age
}

func main() {
    vm := goja.New()

    // 创建一个新的 Person 实例
    person := &Person{
        Name: "John Doe",
        age:  30,
    }

    // 在 JavaScript 运行时中设置 Person 结构体
    vm.Set("person", person)

    // JavaScript 代码以访问结构体的字段和方法
    script := `
        const name = person.Name;    // 访问导出字段
        const age = person.GetAge(); // 通过 getter 访问未导出字段
        name + " is " + age + " years old.";
    `

    result, err := vm.RunString(script)
    if err != nil {
        panic(err)
    }

    fmt.Println(result.String()) // 输出：John Doe is 30 years old.
}

在这个例子中，我定义了一个 Person 结构体，它有一个导出的 Name 字段和一个未导出的 age 字段。GetName 方法是导出的。当从 JavaScript 访问这些字段和方法时，Goja 遵循结构体上的命名约定。方法 GetAge 被访问为 GetName。

有一个模式是通过 FieldNameMapper 将 JavaScript 命名约定的小驼峰式转换为 Golang 命名约定。这允许 Go 方法 GetAge 在 JavaScript 调用中被调用为 getAge。

异常处理

当 JavaScript 中发生异常时，Goja 使用标准的 Go 错误处理来管理它。让我们探索一个运行时异常的例子——除以零。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

package main

import (
"errors"
"fmt"

"github.com/dop251/goja"
)

// 触发除以零错误的 JavaScript 代码
const script = `
// 在 JavaScript 中使用 BigInt 表示法
const a = 1n / 0n;
`

func main() {
vm := goja.New()

// 执行 JavaScript 代码
_, err := vm.RunString(script)

// 处理发生的任何错误
var exception *goja.Exception
if errors.As(err, &exception) {
fmt.Printf("JavaScript error: %s\n", exception.Error())
// 输出：JavaScript error: RangeError: Division by zero at <eval>:1:1(3)
} else if err != nil {
// 处理其他类型的错误（如果有）
fmt.Printf("Error: %s\n", err.Error())
}
}

返回的错误值是 *goja.Exception 类型，它提供了有关引发 JavaScript 异常的信息以及失败的位置。虽然我没有强烈的需求去检查这些错误之外的记录它们到像 New Relic 或 DataDog 这样的服务，但 Goja 确实提供了这样做的工具，如果需要的话。

此外，Goja 可以引发其他类型的异常，如 goja.StackOverflowError、goja.InterruptedError 和 *goja.CompilerSyntaxError，这些异常对应于解释器的特定问题。这些异常在处理执行 JavaScript 代码的客户端时，有助于处理和报告，特别是。

使用 VM 池沙箱用户代码

在开发我的应用程序时，我注意到初始化 VM 需要相当长的时间。每个 VM 都需要在运行时对用户可用的全局模块。Go 提供了 sync.Pool 来帮助重用对象，这非常适合我的情况，避免了沉重的初始化开销。

下面是一个 Goja VM 池的例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

package main

import (
"fmt"
"sync"

"github.com/dop251/goja"
)

var vmPool = sync.Pool{
New: func() interface{} {
vm := goja.New()

// 在每个 VM 中定义全局函数
vm.Set("add", func(a, b int) int {
return a + b
})

// ... 设置其他全局值 ...

return vm
},
}

func main() {
vm := vmPool.Get().(*goja.Runtime)
// 将 VM 放回池中重用
defer vmPool.Put(vm)

script := `
const result = add(5, 10);
result;
`

value, err := vm.RunString(script)
if err != nil {
panic(err)
}

fmt.Println("Result:", value.Export())
// 结果：15
}

由于 sync.Pool 有详细的文档，让我们专注于 JavaScript 运行时。在这个例子中，用户声明了一个变量 result，它的值被返回。然而，我们遇到了一个限制：VM 不能像现在这样重用。

全局命名空间已经被变量 result 污染了。如果我用同一个池重新运行相同的代码，我会收到以下错误：SyntaxError: Identifier ‘result’ has already been declared at :1:1(0)。有一个 GitHub 问题推荐每次清除 result 的值。然而，我发现这种模式由于在处理用户提供的代码时增加的复杂性而不切实际。

到目前为止，我给出的例子都是预定义代码的演示。然而，我的应用程序允许用户在 Goja 运行时中提供自己的代码。这需要一些实验、探索和采用模式来避免“已经声明”的错误。

1
2
3
4

value, err := vm.RunString("(function() {" + userCode + "})()")
if err != nil {
panic(err)
}

沙箱用户代码的最终解决方案涉及在它自己的范围内执行 userCode 在一个匿名函数中。由于函数没有命名，它没有被全局分配，因此不需要清理。经过一些基准测试后，我确认垃圾收集有效地清理了它。

结论

我们已经解锁了一种灵活高效的方式来处理复杂的脚本任务，而不会牺牲性能。这种方法大大减少了在繁琐任务上花费的时间，让你有更多的时间专注于其他重要的方面，并通过提供无缝和响应迅速的脚本环境来增强整体用户体验。

Robert Findley
2024年9月3日

Go 1.23 提供了一种新的方式来帮助改进 Go 工具链。通过启用 Telemetry，可以选择与 Go 团队共享有关工具链程序及其使用情况的数据。这些数据将帮助 Go 贡献者修复错误，避免退步，并做出更好的决策。

默认情况下，Go Telemetry 的数据仅存储在的本地计算机上。如果启用上传，用户数据的有限子集将每周发布到 telemetry.go.dev。

从 Go 1.23 开始，可以使用以下命令启用本地telemetry 数据的上传：

1

go telemetry on

要禁用甚至本地遥测数据收集，请运行以下命令：

1

go telemetry off

Telemetry 文档包含了更详细的实现描述。

Go Telemetry 的由来

虽然软件遥测并不是一个新概念，但 Go 团队经历了多次迭代，寻找符合 Go 对性能、可移植性和透明度要求的 Telemetry 实现。

最初的设计旨在尽可能不显眼、开放和保护隐私，以至于默认情况下可以接受启用，但许多用户在漫长的公开讨论中提出了担忧，最终改变了设计，要求远程上传需要用户明确同意。

新的设计在 2023 年 4 月被接受，并在那个夏天实施。

Telemetry in gopls¶

Go Telemetry 的第一个迭代在 2023 年 10 月的 Go 语言服务器 gopls 的 v0.14 版本中发布。发布后，大约有 100 名用户启用了上传，可能是受到发布说明或Gophers Slack 频道讨论的激励，数据开始流入。不久，遥测在 gopls 中发现了第一个错误：

Dan 在他上传的 telemetry 数据中注意到的堆栈跟踪导致了一个错误报告和修复。值得一提的是，我们并不知道是谁报告了这个堆栈。

IDE Prompting¶

虽然看到遥测在实践中起作用是很好的，我们也很感激那些早期采用者的支持，但 100 名参与者并不足以测量我们想要测量的类型。

正如 Russ Cox 在他最初的博客文章中指出的，遥测默认关闭的一个缺点是需要不断鼓励参与。为了维持足够大的样本量以进行有意义的定量数据分析，并代表用户群体，需要进行外展。虽然博客文章和发布说明可以提高参与度（如果您在阅读本文后启用遥测，我们将不胜感激！），但它们会导致样本偏差。例如，我们在 gopls 中的遥测早期采用者中几乎未收到来自 GOOS=windows 的数据。

为了帮助接触更多用户，我们在 VS Code Go 插件中引入了一个提示，询问用户是否想要启用遥测：

VS Code 显示的遥测提示。
截至这篇博客文章，该提示已向 5% 的 VS Code Go 用户推出，遥测样本已增长到大约每周 1800 名参与者：

每周上传与提示率，提示有助于接触更多用户。
（最初的增长可能归因于提示所有 VS Code Go 扩展的用户）。

然而，它引入了明显倾向于 VS Code 用户的偏差，与最近的 Go 调查结果相比：

我们怀疑 VS Code 在 telemetry 数据中被过度代表。
我们计划通过提示所有使用 gopls 的 LSP 功能编辑器，使用语言服务器协议本身的一个特性来解决这种偏差。

Telemetry wins¶

出于谨慎，我们提议在 gopls telemetry 的初始发布中只收集一些基本指标。其中之一是 gopls/bug stack counter，它记录 gopls 遇到的意外或“不可能”的条件。实际上，它是一种断言，但不是停止程序，而是在遥测中记录它在某些执行中被达到，以及堆栈跟踪。

在我们的 gopls 可扩展性工作中，我们添加了许多这种类型的断言，但我们很少在测试或我们自己的 gopls 使用中观察到它们失败。我们预计这些断言几乎都无法到达。

当我们开始在 VS Code 中随机提示用户启用遥测时，我们看到许多这些条件在实践中被达到，堆栈跟踪的上下文通常足以让我们复现并修复长期存在的错误。我们开始在 gopls/telemetry-wins 标签下收集这些问题，以跟踪遥测促进的“胜利”。

感谢 Paul 的建议。

来自遥测的错误最令人惊讶的方面是它们有多少是真实的。当然，有些错误对用户来说是看不见的，但相当多的错误是 gopls 的实际错误行为——比如缺少交叉引用，或者在某些罕见条件下的补全不准确。它们正是用户可能会轻微烦恼但可能不会麻烦报告为问题的那种事情。也许用户会认为这种行为是有意为之的。如果他们确实报告了一个问题，他们可能不确定如何复现错误，或者我们需要在问题跟踪器上进行长时间的来回讨论以捕获堆栈跟踪。没有遥测，这些错误中的大多数是不可能被发现的，更不用说被修复了。

而这仅仅是来自几个计数器。我们只为我们知道的潜在错误设置了堆栈跟踪。我们没有预料到的问题呢？

自动崩溃报告

Go 1.23 包括一个新的 runtime.SetCrashOutput API，可以用来通过看门狗进程实现自动崩溃报告。从 v0.15.0 开始，如果 gopls 本身是用 Go 1.23 构建的，那么当它崩溃时，gopls 会报告一个 crash/crash stack counter。

当我们发布 gopls@v0.15.0 时，只有少数用户在我们的样本中使用了 Go 1.23 的未发布开发构建，但新的 crash/crash counter 仍然发现了两个 bug。

Go 工具链及更广泛的遥测

Go 1.23 在 Go 工具链中记录遥测，包括 go 命令和其他工具，如编译器、链接器和 go vet。我们已经在 vulncheck 和 VS Code Go 插件中添加了遥测，并提议将其添加到 delve 中。

原始遥测博客系列为遥测如何帮助改进 Go 进行了大量头脑风暴。我们期待探索这些想法以及更多。

在 gopls 中，我们计划使用遥测来提高可靠性并为决策制定和优先级排序提供信息。随着 Go 1.23 启用的自动崩溃报告，我们预计在预发布测试中捕获更多崩溃。展望未来，我们将添加更多计数器来衡量用户体验——关键操作的延迟、各种功能的使用频率——以便我们可以集中精力在最有利于 Go 开发者的地方。

Go 将在 11 月迎来 15 岁生日，语言及其生态系统继续增长。遥测将在帮助 Go 贡献者更快、更安全地朝着正确方向前进中发挥关键作用。

Golang - 使用 GoFakeIt 生成 Mock 数据

介绍

在软件开发中，测试至关重要，以确保代码能够按预期工作。然而，出于隐私考虑、数据可用性以及收集和清理数据，获取真实数据进行测试是不合理的。我们需要生成 Mock 数据来进行测试。在 Go 编程语言中，用于生成假数据的最流行库之一是 GoFakeIt。

什么是 GoFakeIt？

GoFakeIt 是一个强大的库，允许开发人员为测试目的生成各种随机数据。它支持创建名字、地址、电子邮件地址、电话号码、日期等信息的真实假数据。通过使用 GoFakeIt，开发人员可以快速地用虚拟数据填充他们的测试环境，使他们的测试过程更加高效和有效。

安装 GoFakeIt

要开始使用 GoFakeIt，首先需要安装库。可以使用 go get 命令来完成这个操作：

1

go get -u github.com/brianvoe/gofakeit/v6

生成基础假数据

使用 GoFakeIt 生成基础假数据非常简单。以下是一些代码示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27