Protobuf on Liangweidong's blog

ProtoBuf & gRPC 实战：proto3 时代的跨语言 RPC 与数据建模

Sun, 15 Oct 2017 00:00:00 +0800

ProtoBuf & gRPC 实战：proto3 时代的跨语言 RPC 与数据建模

TL;DR：ProtoBuf 是一类语言无关、平台无关、可扩展的二进制结构化数据序列化方法，比 XML 小 3 ~ 10 倍、快 20 ~ 100 倍。2017 年是它真正"工业化"的一年——gRPC 1.0（2017-08 GA）、protoc-gen-validate（2017-08 开源）、Envoy 1.0（2017-09）先后落地，proto3 也从 2016-07 GA 后成为默认语法。本文用 5 个心智模型 + 一组完整示例，讲清 proto3 的数据建模、字段类型、嵌套、Map、service 与四种流模式。

一、为什么需要 ProtoBuf（When to use）

在微服务、跨端通信、持久化序列化场景中，传统 JSON / XML 是人类友好但机器低效的格式：

体积：JSON 里一个 int 字段最少 1~~11 字节，ProtoBuf 用变长编码通常 1~~5 字节
速度：XML 解析要遍历 DOM，ProtoBuf 直接按 schema 二进制切片
类型安全：JSON 拿到的是字符串，ProtoBuf 拿到的是强类型对象
演进能力：ProtoBuf 通过**字段编号（field number）**支持前向/后向兼容，新增字段不会破坏旧客户端

典型适用场景（2017 视角）：

微服务间 RPC——gRPC 1.0（2017-08）以 ProtoBuf 作为 IDL 和默认序列化器，跨语言、强类型、双向流
消息队列载荷——Kafka 早已支持 ProtoBuf，Pulsar（2016-09 在 Yahoo! 开源、2017 年逐步成熟）也提供 schema registry 与 ProtoBuf 集成
K8s 内部通信——Kubernetes 1.0（2015-07 GA）以来，所有 API 资源（Pod、Service、Deployment…）的 schema 都用 ProtoBuf 定义，apiserver 与 kubelet、scheduler、controller-manager 之间走 ProtoBuf over HTTP/2
Service Mesh 数据面——Envoy（2017-09 发布 v1.0）的 xDS（LDS/RDS/CDS/EDS）API 全部基于 ProtoBuf，Istio 等控制面通过 xDS 下发配置
跨语言 SDK 数据交换——前端、移动端、后端用同一份 .proto 各自生成代码
移动端与后端通信——节省流量、电量

不适用场景：

需要人类可读的配置（用 YAML / TOML）
Web 前端到后端的标准通信（JSON 更通用）
一次性、小数据量、无演进需求的传输

二、ProtoBuf 速览

一个数据交换的协议

protocol buffers（ProtoBuf）是一种语言无关、平台无关、可扩展的序列化结构数据的方法，可用于（数据）通信协议、数据存储等。

是一种灵活、高效、自动化机制的结构数据序列化方法——可类比 XML，但比 XML 更小（3 ~ 10 倍）、更快（20 ~ 100 倍）、更简单。

JSON / XML 都是基于文本格式，ProtoBuf 是二进制格式。

三、proto3 速览：与 proto2 的关键差异

2016-07 proto3 正式 GA，并成为 protoc 的默认语法。和 proto2 相比，proto3 的核心简化是：

维度	proto2	proto3
默认语法	需显式 `syntax = "proto2"`	2016-07 后默认为 proto3
字段是否存在	区分 `optional` / `required` / 默认	没有 `required`，字段默认"存在与否"用 `optional` 关键字显式标注（proto3 默认字段可以被设默认值以"不编码"）
默认值	0 / 空字符串	同上，但未设置字段不会被序列化（节省体积）
枚举	第一个值必须为 0	同上，但首成员必须为 0，且枚举值在 wire format 中是 varint
未知字段	解析时默认保留	解析时不保留未知字段（演进更严格）
`map` 支持	旧版本不支持	原生支持 `map<K, V>`
`Any` 类型	需 `google/protobuf/any.proto` 扩展	官方内置 `google.protobuf.Any`
时间戳	同上	同上，但官方推荐 `google.protobuf.Timestamp`
JSON 映射	需插件	官方 `proto3 <-> JSON` 映射规范

实战建议：新项目一律 syntax = "proto3"；维护老服务再保留 proto2。

四、第一个 .proto：消息定义

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


// 指定 proto3 语法（2016-07 后是默认，但显式声明更稳）
syntax = "proto3";

package foo.bar; // 包名避免同名 Message 冲突

// option 可用于 proto、message、enum、service 的 scope

// Message ≈ Java 的 class / C 的 struct
message Response {
 // 字段 = 类型 + 名字 + 序号（序号是 wire format 的"身份证"，绝不能改）
 string data = 1;
 int32 status = 2;
}

关键约定：

package：避免命名空间冲突
message：数据结构的最小单元
字段序号 = 1, = 2, ...：一旦发布就不可修改、不可复用——这是 ProtoBuf 演进能力的根基
syntax = "proto3"：2017 主流；不写时 2017 之后的 protoc 默认按 proto3 解析

五、编译器：.proto → 目标语言

官方编译器 protoc 仓库：https://github.com/protocolbuffers/protobuf/releases

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


# 安装 protoc 后，生成 Java 代码到当前目录
protoc --java_out=. response.proto

# 生成 Go 代码
protoc --go_out=. --go_opt=paths=source_relative response.proto

# 生成 Python 代码
protoc --python_out=. response.proto

# 生成 C++ 代码
protoc --cpp_out=. --proto_path=. response.proto

# 生成 gRPC 桩代码（protoc + 插件 grpc-plugin，gRPC 1.0 GA 后官方推荐）
protoc --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_cpp_plugin` response.proto

小贴士：生成的代码不要手动改——下次 protoc 会被覆盖。业务代码继承/组合生成的类即可。

六、数据类型映射表

proto 类型	说明	java 类型	golang 类型
`double`	双精度浮点	`double`	`float64`
`float`	单精度浮点	`float`	`float32`
`int32`	变长编码，对负值效率低，负值请用 `sint32`	`int`	`int32`
`uint32`	变长编码	`int`	`uint32`
`uint64`	变长编码	`long`	`uint64`
`sint32`	变长编码，负值比 int32 高效	`int`	`int32`
`sint64`	变长编码，有符号	`long`	`int64`
`fixed32`	固定 4 字节，值域常大于 2²⁸ 时比 `uint32` 高效	`int`	`uint32`
`fixed64`	固定 8 字节，值域常大于 2²⁵⁶ 时比 `uint64` 高效	`long`	`uint64`
`sfixed32`	固定 4 字节	`int`	`int32`
`sfixed64`	固定 8 字节	`long`	`int64`
`bool`	布尔	`boolean`	`bool`
`string`	必须 UTF-8 或 7-bit ASCII	`String`	`string`
`bytes`	任意二进制（文件、图片）	`ByteString`	`[]byte`

实战口诀：负数 → sint32/sint64；大正整数 → fixed32/fixed64；其余 → int32/uint32。

七、枚举、数组、嵌套、导入

7.1 枚举

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


syntax = "proto3";

enum PhoneType { // 枚举首成员必须为 0，且值唯一
 MOBILE = 0;
 HOME = 1;
 WORK = 2;
}

message PhoneNumber {
 string number = 1;
 PhoneType type = 2;
}

7.2 数组（repeated）

1
2
3
4
5


message Msg {
 repeated int32 arrays = 1; // 整数数组
 repeated string names = 2; // 字符串数组
 repeated PhoneNumber phones = 3;
}

7.3 嵌套消息 vs 跨文件导入

1
2
3
4
5
6
7
8
9


// 嵌套：把 Result 写进 SearchResponse 内部
message SearchResponse {
 message Result {
 string url = 1;
 string title = 2;
 repeated string snippets = 3;
 }
 repeated Result results = 1;
}

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


// 跨文件导入：把 Result 抽到 result.proto
// result.proto
syntax = "proto3";
package foo.bar;
message Result {
 string url = 1;
 string title = 2;
 repeated string snippets = 3;
}

// search_response.proto
syntax = "proto3";
package foo.bar;
import "result.proto";
message SearchResponse {
 repeated Result results = 1;
}

proto3 中不允许直接嵌套枚举（嵌套 enum 必须先 message 包一层），这是与 proto2 的小差异。

八、Map / 时间戳 / Any

8.1 Map 类型

1
2
3
4
5
6
7


syntax = "proto3";

message Product {
 string name = 1;
 // key 不能是浮点 / bytes / enum；value 不能是另一个 map
 map<string, string> attrs = 2; // 商品属性 K/V
}

Map 字段不能用 repeated 修饰；map 不能迭代顺序依赖。

8.2 时间戳

1
2
3
4
5
6
7


syntax = "proto3";

import "google/protobuf/timestamp.proto";

message MyMessage {
 google.protobuf.Timestamp my_field = 1;
}

简单场景可直接用 int64 时间戳（毫秒/秒），看团队约定。

8.3 Any 任意类型

1
2
3
4
5


// Any 可以承载 .proto 未定义的任意内置类型
message ErrorStatus {
 string message = 1;
 repeated google.protobuf.Any details = 2;
}

K8s API 的 runtime.RawExtension 字段底层就是 Any——apiserver 把不识别的对象原样塞进去。

九、定义服务

proto3 原生支持 service 定义，与 gRPC 1.0 配合即可生成跨语言 RPC 桩代码：

1
2
3


service SearchService {
 rpc Search (SearchRequest) returns (SearchResponse);
}

gRPC 1.0（2017-08）默认走 HTTP/2 + ProtoBuf，这是 ProtoBuf 在 RPC 领域最主流的落地形态。

十、stream 关键字：四种流模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 客户端推 → 服务端（client-side streaming）
rpc GetStream (StreamReqData) returns (stream StreamResData) {}

// 服务端推 → 客户端（server-side streaming）
rpc PutStream (stream StreamReqData) returns (StreamResData) {}

// 双向流（bidirectional streaming）
rpc AllStream (stream StreamReqData) returns (stream StreamResData) {}

// 单调用（非流式）
rpc Unary (UnaryReq) returns (UnaryRes);

典型场景：

客户端流：IoT 设备上报（go2rtc 这类轻量级流媒体代理 / RTSP-over-WebRTC 设备采集后的元数据上报就属于这一类）
服务端流：股票行情、消息推送、K8s watch API
双向流：聊天、协同编辑、Envoy xDS（控制面 ↔ 数据面长连接推送配置）
单调用：普通 RPC

Envoy 1.0 的 xDS（LDS/RDS/CDS/EDS）正是 gRPC 双向流的典型案例——控制面（Istio Pilot 等）通过 gRPC stream 主动推送配置变更给数据面（Envoy）。

十一、数据校验：protoc-gen-validate（2017-08）

ProtoBuf 本身不包含字段值校验（最小值、最大值、长度、枚举合法性等）。2017-08 开源的 protoc-gen-validate（Envoy 项目出品）补齐了这一点：

仓库：https://github.com/envoyproxy/protoc-gen-validate

 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


syntax = "proto3";

package foo.bar;

import "validate/validate.proto";

message CreateUserRequest {
 // 用户名：3~32 字符，正则限制
 string username = 1 [
 (validate.rules).string = {
 min_len: 3
 max_len: 32
 pattern: "^[a-zA-Z0-9_]+$"
 }
 ];

 // 年龄：0~150
 int32 age = 2 [(validate.rules).int32 = {gte: 0, lte: 150}];

 // 邮箱：必须是 email 格式
 string email = 3 [(validate.rules).string = {email: true}];

 // 列表元素非空、长度限制
 repeated string tags = 4 [
 (validate.rules).repeated = {
 min_items: 1
 max_items: 10
 items: {string: {min_len: 1, max_len: 32}}
 }
 ];
}

1
2
3
4
5
6
7


# 安装 protoc-gen-validate 后，protoc 会生成带校验逻辑的桩代码
protoc \
 -I . \
 -I /path/to/protoc-gen-validate \
 --go_out=. \
 --validate_out=lang=go,paths=source_relative:. \
 create_user.proto

相比 JSR 303 Bean Validation（Java 生态），protoc-gen-validate 的优势是校验规则写在 .proto 里、跨语言、跨 RPC 框架一致——这正是 2017 年 gRPC + Envoy 生态推崇的"单一来源"做法。

十二、现代基础设施里的 ProtoBuf

2017 年这个时间点，ProtoBuf 已经不只是"序列化格式"，而是分布式系统的事实 IDL。

12.1 Kubernetes：所有 API 资源都是 ProtoBuf

Kubernetes 1.0（2015-07 GA）以来，所有 API 资源（Pod、Service、Deployment…）的 schema 都定义在 k8s.io/api 仓库的 .proto 文件中：

apiserver ↔ kubelet / scheduler / controller-manager：通过 HTTP/2 + ProtoBuf 通信
CRD / Operator：用户自定义资源也走 .proto（或 OpenAPI 自动生成）
kubectl：本地构造 ProtoBuf 对象 → 走 apiserver 序列化

典型 .proto 片段（简化版）：

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


// k8s.io/api/core/v1/generated.proto
syntax = "proto3";
package k8s.io.api.core.v1;

import "k8s.io/apimachinery/pkg/runtime/generated.proto";

message Pod {
 map<string, string> labels = 1;
 map<string, string> annotations = 2;
 PodSpec spec = 3;
 PodStatus status = 4;
}

12.2 gRPC：ProtoBuf 跨语言 RPC 的事实标准

gRPC 1.0（2017-08 GA）由 Google 开源（2015 年从内部 Stubby 演进，移到 GitHub），以 ProtoBuf 作为 IDL 和默认序列化：

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


// user.proto
syntax = "proto3";

package user;

service UserService {
 // 单调用
 rpc GetUser (GetUserRequest) returns (User);
 // 服务端流
 rpc ListUsers (ListUsersRequest) returns (stream User);
 // 客户端流
 rpc CreateUsers (stream User) returns (CreateUsersResponse);
 // 双向流
 rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

message User { string id = 1; string name = 2; }

gRPC 关键特性：

HTTP/2 多路复用
ProtoBuf 二进制序列化
双向流、四种流模式
自动生成 10+ 语言桩代码（Java/Go/C++/Python/Ruby/Node/PHP/C#/Dart/Android-Java）
截止时间（deadline）、取消、metadata 等通用拦截语义

12.3 Pulsar：消息总线里的 ProtoBuf

Apache Pulsar（2016-09 在 Yahoo! 开源、2017 年逐步孵化成 Apache 顶级项目）原生支持 ProtoBuf schema：

内置 Schema.PROTOBUF，producer / consumer 用 .proto 自动反序列化
与 SchemaRegistry 配合做 schema 演进
消息载荷紧凑、跨语言、多租户隔离

12.4 Envoy / xDS：Service Mesh 的数据面 API

Envoy（Lyft 开源，2017-09 发布 v1.0）的 xDS 协议族是 gRPC + ProtoBuf 的工业级范本：

LDS（Listener Discovery Service）：下发监听器配置
RDS（Route Discovery Service）：下发路由配置
CDS（Cluster Discovery Service）：下发集群配置
EDS（Endpoint Discovery Service）：下发端点配置

控制面（Istio Pilot 等）通过 gRPC 双向流把 ProtoBuf 消息增量推送给数据面（Envoy），实现配置热更新。

这套 xDS 协议后来成为 Istio（2017-05 由 Google/IBM/Lyft 联合开源）的核心数据面 API。

12.5 IoT / 视频流场景

ProtoBuf 在 IoT 与视频流领域的应用同样广泛——比如轻量级流媒体代理在设备元数据、控制信令、配置同步上都会用 .proto 定义设备能力集，避免重复造轮子。go2rtc 这类工具虽然面世更晚，但同样遵循"ProtoBuf 作为控制面信令、媒体流走 RTSP/WebRTC"的分层思路。

十三、协议升级的视角：IPv4→IPv6 给我们的启示

2017 年前后正值 IPv6 规模部署讨论。把网络协议和序列化协议放一起看，能发现共通的设计哲学：

协议升级对现有程序的影响（参考 IPv4→IPv6）

地址格式的硬编码问题——视频监控、配置文件、程序中字面量硬编码
网络 API / 库的协议版本依赖——Java 库要使用更通用的 InetAddress；Go 视频播放客户端优先 net.LookupIP 同时解析 A 与 AAAA
地址解析与 DNS 交互逻辑——程序需支持"双 DNS 查询"（同时请求 A 和 AAAA 记录）
操作系统层面支持
运行时 / 容器——Java 需确保 java.net.preferIPv6Addresses=true；libc 解析器需开启 getaddrinfo 的 AI_ADDRCONFIG；Docker / K8s 需配置 IPv6 网络模式（--ipv6 flag、CNI 插件）
防火墙规则——IPv4 规则需重新配置 IPv6 专属规则

升级建议路径：

阶段	目标
第一阶段	支持双栈兼容（IPv4/IPv6 并存）
第二阶段	修复IPv6 专属问题（DNS、MTU、链路本地地址）
第三阶段	全量 IPv6，下线 IPv4

类比到 ProtoBuf：

第一阶段（双栈）：旧字段保留 + 新字段加 optional 标注
第二阶段（修复兼容问题）：使用 reserved 关键字冻结废弃字段编号（防止误用）

1
2
3
4
5
6
7


message User {
 reserved 5, 7, 9 to 11; // 保留字段编号，未来也不能用
 reserved "old_name", "old_email"; // 保留字段名

 string name = 1;
 string email = 2;
}

第三阶段（全量）：灰度下架旧字段、提供 schema 校验工具

十四、常见 5 个坑

#	坑	现象	对策
1	修改已发布字段的序号	旧客户端解码新数据字段错位、值乱跳	一旦发布，序号就是合约；只能加新字段 + 用 `reserved` 废弃旧的
2	误用 `int32` 存负数	负数被编码为 10 字节超大无符号数	负数统一用 `sint32` / `sint64`
3	`string` 字段塞非 UTF-8	反序列化报错、跨语言崩溃	文本类字段用 `string`；二进制用 `bytes`
4	`repeated` 字段不设上限	大消息体 OOM、带宽爆炸	在 `Service` 入口拦截层加 `Collection.size()` 校验；或用 `protoc-gen-validate` 的 `repeated.min_items` / `max_items` 限制
5	proto2 / proto3 混用	wire format 行为不同，反序列化失败	团队统一 `syntax = "proto3"`；proto2 仅在维护老服务时保留

十五、核心 6 点速记

字段编号 = 合约：一旦发布就不可改；用 reserved 冻结废弃编号
负数用 sint：变长编码对负值有专门优化
stream 关键字：四种流模式决定 ProtoBuf 自带 RPC 通信方向——gRPC 1.0 把它变成跨语言标准
校验靠 protoc-gen-validate：2017-08 开源，跨语言、.proto 单一来源，比 JSR 303 更适合 gRPC 时代
现代基础设施统一用 .proto 作为 IDL：K8s API、Pulsar schema、Envoy xDS、gRPC、CRD
演进式升级：双栈 → 修复 → 全量，与 IPv4→IPv6 的协议升级哲学一致

十六、参考资料

ProtoBuf 官方仓库：https://github.com/protocolbuffers/protobuf
protoc 发布页：https://github.com/protocolbuffers/protobuf/releases
gRPC 1.0 公告：https://grpc.io/blog/grpc-1-0-goes-ga/
gRPC 仓库：https://github.com/grpc/grpc
protoc-gen-validate：https://github.com/envoyproxy/protoc-gen-validate
Envoy 仓库：https://github.com/envoyproxy/envoy
xDS 协议：https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/xds_api
Kubernetes API 源码：https://github.com/kubernetes/api
Apache Pulsar：https://pulsar.apache.org/
Any 类型：https://developers.google.com/protocol-buffers/docs/proto#any

Windows 绿色版开发工具链：CMake、MinGW、Maven、Gradle、nvm、ffmpeg、sqlite3 与 protoc 全配置

Sun, 15 Mar 2015 00:00:00 +0800

一、为什么要在 Windows 上做"绿色版"开发工具链

每台新机器、每个新客户现场、每个虚拟机都要重新装一遍开发环境，是 Windows 程序员最痛苦的事之一。理想状态是：一个 D:\portable\ 目录，拷过去就能干活。

本文把开发时最常用的小工具（不包含 IDE 与 Docker）整理成一份"解压即用"配置手册：

C/C++ 编译：CMake + MinGW
JVM 构建：Maven + Gradle
Node 多版本：nvm-windows
多媒体处理：ffmpeg
嵌入式数据库：sqlite3
IDL 编译：protoc
搜索引擎：Elasticsearch（本地开发用）

二、C/C++ 工具链：CMake + MinGW

2.1 MinGW-w64 下载与配置

推荐 niXman/mingw-builds-binaries，选 x86_64-13.x.x-release-posix-seh-ucrt-rt_v11-rev0.7z（ucrt 是 Win10/11 推荐运行时）。

或者从 winlibs.com 下整合好的 zip。

解压到 D:\portable\dev\mingw64，加到 PATH：

1

PATH=D:\portable\dev\mingw64\bin

验证：

1
2
3
4
5
6


gcc --version
# gcc.exe (MinGW-W64) 13.2.0

# 把 mingw32-make.exe 复制一份改名 make
cp D:\portable\dev\mingw64\bin\mingw32-make.exe D:\portable\dev\mingw64\bin\make.exe
make --version

2.2 CMake 下载与配置

cmake.org/download 下载 cmake-3.x.x-windows-x86_64.zip，解压到 D:\portable\dev\cmake-3.28.3-windows-x86_64\bin 加 PATH。

1
2


cmake --version
# cmake version 3.28.3

避坑：下载页有两个版本 *-windows-x86_64.msi（安装器）和 *-windows-x86_64.zip（绿色版），选 zip 才能 portable。

2.3 完整编译一个 hello.cpp

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


cmd /c cd. > hello.cpp

# 写代码（用 vim 或记事本）
cat > hello.cpp <<EOF
#include <iostream>
int main() {
 std::cout << "Hello, World!" << std::endl;
 return 0;
}
EOF

# 编译
g++ -c hello.cpp
g++ hello.o -o hello.exe
./hello.exe

2.4 用 CMake 跨平台构建

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


cmd /c cd. > CMakeLists.txt

cat > CMakeLists.txt <<EOF
cmake_minimum_required(VERSION 3.0)
project(hello)
add_executable(hello hello.cpp)
if(WIN32)
 set(CMAKE_CXX_FLAGS "-static-libgcc -static-libstdc++")
endif()
EOF

mkdir build && cd build
cmake -G "Unix Makefiles" ../
make
./hello.exe

-static-libgcc -static-libstdc++ 关键！不写这两个就依赖 libgcc_s_seh-1.dll 等动态库，绿色拷贝出去会缺 DLL。

2.5 32 位与 64 位交叉编译

1
2


g++ -m32 hello.cpp -o hello32.exe
g++ -m64 hello.cpp -o hello64.exe

三、JVM 构建：Maven 与 Gradle

3.1 Maven 3.9

maven.apache.org 下载 apache-maven-3.9.4-bin.zip，解压到 D:\portable\dev\apache-maven-3.9.4。

环境变量：

1
2


MAVEN_HOME=D:\portable\dev\apache-maven-3.9.4
PATH=%PATH%;%MAVEN_HOME%\bin

注：%MAVEN_HOME% 这种写法在 PowerShell 里要用 $env:MAVEN_HOME，cmd 才是 %...%。

%MAVEN_HOME%\conf\settings.xml 必改项：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- 1. 镜像（公司 Nexus / 阿里云） -->
<mirrors>
 <mirror>
 <id>internal-nexus</id>
 <mirrorOf>central</mirrorOf>
 <url>http://internal.example.com:8081/repository/maven-public/</url>
 </mirror>
</mirrors>

<!-- 2. 本地仓库放 D 盘 -->
<localRepository>D:\portable\dev\.m2\repository</localRepository>

3.2 Maven 找不到插件 `spring-boot-maven-plugin` 的坑

pom.xml 里只声明 <plugin> 不带 <version>，会报：

1

[ERROR] Plugin 'org.springframework.boot:spring-boot-maven-plugin:' not found

原因：<pluginManagement> 里引用时未指定版本，或继承的 spring-boot-starter-parent 缺失。修法：

1
2
3
4
5
6
7
8
9


<build>
 <plugins>
 <plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 <version>2.3.0.RELEASE</version> <!-- 显式版本 -->
 </plugin>
 </plugins>
</build>

3.3 Gradle 8.x

gradle.org/releases 下 gradle-8.5-bin.zip，解压到 D:\portable\dev\gradle-8.5。

1

PATH=D:\portable\dev\gradle-8.5\bin

3.4 引入本地第三方 jar（Maven 实战）

业务 jar 不在公共仓库时，不能用 mvn install，得在 common 模块的 pom.xml 里加 scope=system：

1
2
3
4
5
6
7


<dependency>
 <groupId>com.example</groupId>
 <artifactId>thirdparty-jar</artifactId>
 <version>1.0.0</version>
 <scope>system</scope>
 <systemPath>${project.basedir}/src/main/resources/lib/thirdparty.jar</systemPath>
</dependency>

文件布局：

1
2
3


common/
├── src/main/resources/lib/thirdparty.jar
├── pom.xml

这种方式是反模式（jar 进 git），Maven 官方不推荐；正路是搭 Nexus / 阿里云 Maven 仓库。实在没私有仓库时，临时用。

四、Node 多版本：nvm-windows

4.1 下载

coreybutler/nvm-windows/releases 下载 nvm-noinstall.zip，解压到 D:\portable\dev\nvm。

settings.txt 配置镜像（阿里云）：

1
2
3
4


root: D:\portable\dev\nvm
path: D:\portable\dev\nodejs
node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/

4.2 常用命令

1
2
3
4
5


nvm install 18.20.0 # 装 Node 18 LTS
nvm install 20.11.0 # 装 Node 20 LTS
nvm use 18.20.0 # 切换到 18
nvm list # 已装版本
nvm alias default 20.11.0

五、ffmpeg：音视频处理

5.1 下载

ffmpeg.org 找 gyan.dev 或 BtbN 提供的构建包，下载 ffmpeg-release-essentials.zip，解压到 D:\portable\dev\ffmpeg，把 bin 加 PATH：

1

ffmpeg -version

5.2 YouTube 1080p Adaptive 音视频合并

YouTube-DL 抓下来的 1080p 视频是音视频分离的（一个 .mp4、一个 .webm），合成：

1

ffmpeg -i input.mp4 -i input.webm -strict -2 -acodec copy -vcodec copy output.mp4

-strict -2：启用实验性 AAC 编码（合成 1080p 必须）；
-acodec copy / -vcodec copy：流复制，秒级完成。

5.3 截图、剪切、转码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 截取第 5 秒的帧
ffmpeg -i input.mp4 -ss 5 -vframes 1 cover.jpg

# 裁剪 1080p → 480p
ffmpeg -i input.mp4 -vf scale=854:480 output_480p.mp4

# 剪切 00:30 - 01:30
ffmpeg -i input.mp4 -ss 00:00:30 -to 00:01:30 -c copy clip.mp4

# 视频转 GIF
ffmpeg -i input.mp4 -vf "fps=15,scale=480:-1" out.gif

六、sqlite3：嵌入式数据库

6.1 下载

sqlite.org/download.html 拉两个 zip：

sqlite-dll-win64-x64-3410200.zip：sqlite3.dll
sqlite-tools-win32-x86-3410200.zip：命令行工具

解压到 D:\portable\dev\sqlite3，把 sqlite3.exe 加 PATH。

6.2 基础使用

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


# 打开/创建 db
sqlite> .open test.db

# 常用元命令
.databases # 列出所有 db
.tables # 列出所有表
.schema user # 查看 user 表 DDL
.headers on
.mode column

# 退出
.exit

6.3 用 Navicat / IDEA 连接

sqlite3 本身支持 TCP 监听，但用 Navicat / IDEA 直连 .db 文件更直接：

1
2
3
4
5
6


# Navicat
连接类型：SQLite
数据库文件：D:\path\to\test.db

# IDEA Database 工具
Data Sources → SQLite → 选择 .db 文件

实战经验：很多"配置文件中心"工具（如 H2、HSQLDB、Apache Geode）底层都支持 sqlite 协议；本地开发、单元测试时 sqlite 比 MySQL 快 10 倍。

七、protoc：protobuf 编译

7.1 下载

protocolbuffers/protobuf/releases 下载 protoc-21.3-win64.zip（21.x 是 proto3 稳定版），解压到 D:\portable\dev\protoc-21.3\bin，加 PATH。

7.2 编译 .proto

1
2
3


protoc --java_out=./src/main/java -I. user.proto
protoc --go_out=./pkg -I. user.proto
protoc --python_out=. -I. user.proto

-I（或 --proto_path）：proto 文件搜索目录
--xxx_out：目标语言输出目录

7.3 gRPC 代码生成

protoc 默认不生成 gRPC 服务端 / 客户端 stub，需要装 plugin：

1
2
3
4
5


# Java
protoc --java_out=. --grpc-java_out=. -I. user.proto

# Go
protoc --go_out=. --go-grpc_out=. -I. user.proto

详见 grpc/grpc-java / grpc/grpc-go 文档。

八、Elasticsearch：本地开发用

8.1 下载

elastic.co/downloads/past-releases 选 7.17.x 或 8.x 的 Windows zip（不推荐用 msi）。

1

D:\portable\dev\elasticsearch-8.11.0\bin\elasticsearch.bat

8.2 配置文件

config/elasticsearch.yml 关键项：

1
2
3
4
5
6


cluster.name: dev-cluster
node.name: dev-node-1
network.host: 127.0.0.1
http.port: 9200
discovery.type: single-node  # 单节点模式，省去选举
xpack.security.enabled: false # 本地开发关掉安全

8.3 启动

1
2
3
4
5


# 不能用 root（Windows 默认 Administrator 即可）
bin\elasticsearch.bat

# 验证
curl http://127.0.0.1:9200

8.4 Head 插件

elasticsearch-head 是个 Chrome 插件 + 老式 Node 项目，可视化查看 index：

1
2
3
4
5


git clone https://github.com/mobz/elasticsearch-head
cd elasticsearch-head
npm install
npm run start
# 浏览器打开 http://localhost:9100

8.x 之后 Kibana 自带 Dev Tools Console，更现代，建议用 Kibana。

九、必备小工具

工具	用途	绿色版路径
HeidiSQL	MySQL/MariaDB 客户端	`D:\portable\dev\heidisql`
RedisDesktopManager	Redis GUI	`D:\portable\dev\rdm`
Caddy	HTTP 服务器	`D:\portable\dev\caddy`
7-Zip	解压	系统自带 / scoop 装
ripgrep	文件搜索	`D:\portable\dev\rg\rg.exe`

十、便携版目录约定

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


D:\portable\
├── dev\
│ ├── mingw64\
│ ├── cmake-3.28.3\
│ ├── apache-maven-3.9.4\
│ ├── gradle-8.5\
│ ├── nvm\
│ ├── nodejs\ # nvm 切版本时切换的软链目标
│ ├── ffmpeg\
│ ├── sqlite3\
│ ├── protoc-21.3\
│ ├── elasticsearch-8.11.0\
│ ├── caddy\
│ └── .m2\ # 本地 Maven 仓库
└── path\bin\ # 全部 exe 软链

十一、常见坑

现象	原因	对策
g++ 链接缺 dll	默认动态链接	加 `-static-libgcc -static-libstdc++`
Maven 下载 jar 卡死	仓库无代理	配 Nexus / 阿里云镜像
Gradle 启动报 JAVA_HOME 错	JDK 路径含空格	重装 JDK 到无空格目录如 `C:\java\jdk-17`
ffmpeg 合成提示 “Experimental”	AAC 编码	加 `-strict -2`
sqlite3 中文乱码	命令行编码	`chcp 65001` 切 UTF-8
protoc 找不到 .proto	`-I` 路径错	绝对路径或 cd 到 .proto 所在目录
Elasticsearch 启动 OOM	JVM 堆太小	`config/jvm.options` 加 `-Xms2g -Xmx2g`

十二、下一步

C/C++ 进阶：CMake + vcpkg / Conan 跨平台包管理
Maven 进阶：maven-shade-plugin 打 fat jar、maven-assembly-plugin 自定义打包
Node 进阶：pnpm / yarn / corepack 多包管理器
Elasticsearch 进阶：用 Docker 部署集群（参考 2019-06-20《Docker 进阶与运维》）

Protobuf on Liangweidong's blog

ProtoBuf & gRPC 实战：proto3 时代的跨语言 RPC 与数据建模

ProtoBuf & gRPC 实战：proto3 时代的跨语言 RPC 与数据建模

一、为什么需要 ProtoBuf（When to use）

二、ProtoBuf 速览

三、proto3 速览：与 proto2 的关键差异

四、第一个 .proto：消息定义

五、编译器：.proto → 目标语言

六、数据类型映射表

七、枚举、数组、嵌套、导入

7.1 枚举

7.2 数组（repeated）

7.3 嵌套消息 vs 跨文件导入

八、Map / 时间戳 / Any

8.1 Map 类型

8.2 时间戳

8.3 Any 任意类型

九、定义服务

十、stream 关键字：四种流模式

十一、数据校验：protoc-gen-validate（2017-08）

十二、现代基础设施里的 ProtoBuf

12.1 Kubernetes：所有 API 资源都是 ProtoBuf

12.2 gRPC：ProtoBuf 跨语言 RPC 的事实标准

12.3 Pulsar：消息总线里的 ProtoBuf

12.4 Envoy / xDS：Service Mesh 的数据面 API

12.5 IoT / 视频流场景

十三、协议升级的视角：IPv4→IPv6 给我们的启示

十四、常见 5 个坑

十五、核心 6 点速记

十六、参考资料

Windows 绿色版开发工具链：CMake、MinGW、Maven、Gradle、nvm、ffmpeg、sqlite3 与 protoc 全配置

一、为什么要在 Windows 上做"绿色版"开发工具链

二、C/C++ 工具链：CMake + MinGW

2.1 MinGW-w64 下载与配置

2.2 CMake 下载与配置

2.3 完整编译一个 hello.cpp

2.4 用 CMake 跨平台构建

2.5 32 位与 64 位交叉编译

三、JVM 构建：Maven 与 Gradle

3.1 Maven 3.9

3.2 Maven 找不到插件 spring-boot-maven-plugin 的坑

3.3 Gradle 8.x

3.4 引入本地第三方 jar（Maven 实战）

四、Node 多版本：nvm-windows

4.1 下载

4.2 常用命令

五、ffmpeg：音视频处理

5.1 下载

5.2 YouTube 1080p Adaptive 音视频合并

5.3 截图、剪切、转码

六、sqlite3：嵌入式数据库

6.1 下载

6.2 基础使用

6.3 用 Navicat / IDEA 连接

七、protoc：protobuf 编译

7.1 下载

7.2 编译 .proto

7.3 gRPC 代码生成

八、Elasticsearch：本地开发用

8.1 下载

8.2 配置文件

8.3 启动

8.4 Head 插件

九、必备小工具

十、便携版目录约定

十一、常见坑

十二、下一步

十三、参考资料

3.2 Maven 找不到插件 `spring-boot-maven-plugin` 的坑