编程语言 on 牛哥聊技术

从 Lambda 到虚拟线程——Java 关键特性演进

Sat, 21 Mar 2026 15:30:00 +0800

写在前面

Java 已经走过 30 年——从 1995 年发布到 2025 年的 25——它被"唱衰"过很多次，但每次都挺过来了。

很多人对 Java 的印象停留在 8——Lambda、Stream、Optional。但 Java 8 之后每 6 个月一个版本——加入了大量颠覆性特性：

9-11：模块化、var、HTTP Client
14-17：Records、Sealed Classes、Pattern Matching
19-21：虚拟线程、结构化并发、Pattern Matching for Switch
22-25：Valhalla 进展、String Templates、Stream 增强

本文按时间线梳理——从 Java 8（2014）一路到 Java 25（2025），再看未来 5 年走向何方。

一、Java 8（2014）：函数式革命

仍是 2026 年最广泛使用的版本——全球生产环境的 Java 中至少 30% 还在 Java 8。

核心特性：

Lambda 表达式
Stream API
Optional
新 Date/Time API（替代腐朽的 Date / Calendar）
接口默认方法 / 静态方法

Java 8 让 Java 从纯 OOP 拥抱函数式——是 Java 的"现代化转折"。

二、Java 11（2018）：第一个 LTS 之后

Java 9-10 是过渡——Java 11 是第一个长期支持版本（LTS）。

核心特性：

var 局部变量类型推断
HTTP Client（替代笨重的 HttpURLConnection）
String 增强（isBlank、lines、strip 等）
删除 Java EE 模块（javax.xml、java.activation 等）
G1 GC 默认

Java 11 是当下仍在生产广泛使用的版本——多数中型项目的现状。

三、Java 17（2021）：第二个 LTS

Spring Boot 3 的最低基线——强迫整个生态升级。

新增：

Records：数据载体类
Sealed Classes：限定的继承
Pattern Matching for instanceof
Switch Expressions
Text Blocks
删除 Applet API
Pseudorandom Number Generators

Java 17 是目前最值得长期 commit 的版本——稳定 + 现代 + 生态全面支持。

四、Java 21（2023）：虚拟线程时代

第三个 LTS——Java 21 的核心特性可以说是 Java 近十年最具分量的一批：

虚拟线程（Project Loom）

1
2
3
4
5


// 之前：每个请求一个 OS 线程
ExecutorService pool = Executors.newFixedThreadPool(200);

// 现在：虚拟线程，能开几百万个
ExecutorService pool = Executors.newVirtualThreadPerTaskExecutor();

虚拟线程让传统 MVC 同步代码 = 异步性能——不需要学 WebFlux / Reactive 了。

结构化并发

1
2
3
4
5
6
7
8
9


try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
 StructuredTaskScope.Subtask<User> userTask = scope.fork(() -> fetchUser(id));
 StructuredTaskScope.Subtask<Order> orderTask = scope.fork(() -> fetchOrder(id));

 scope.join();
 scope.throwIfFailed();

 return new Result(userTask.get(), orderTask.get());
}

注：scope.fork(...) 在 Java 21 返回的是 StructuredTaskScope.Subtask<T>，不是 Future<T>。未 join() 之前直接 Subtask.get() 会抛 IllegalStateException——必须先 join() 让所有子任务终止、再 throwIfFailed() 处理失败、最后才能 get() 取值。

让"一组并发任务"有清晰的生命周期——避免 goroutine 泄漏式的反模式。

Pattern Matching for Switch

1
2
3
4
5
6
7
8
9


String describe(Object obj) {
 return switch (obj) {
 case Integer i when i > 0 -> "positive int " + i;
 case Integer i -> "non-positive int " + i;
 case String s -> "string of length " + s.length();
 case null -> "null";
 default -> "unknown";
 };
}

模式匹配让代码更简洁——这一波明显借鉴了 Scala / Kotlin 的成熟实践。

Records & Sealed 升级

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public sealed interface Shape permits Circle, Square, Triangle {}

public record Circle(double radius) implements Shape {}

double area(Shape s) {
 return switch (s) {
 case Circle c -> Math.PI * c.radius() * c.radius();
 case Square sq -> sq.side() * sq.side();
 case Triangle t -> 0.5 * t.base() * t.height();
 };
}

Records + Sealed + Pattern Matching = 代数数据类型（ADT） ——表达力大幅提升。

五、Java 25（2025 LTS）：当下的最新 LTS

2025 年 9 月发布——第四个 LTS。

新加 / 标准化的特性：

Stream Gatherers（标准化）

1
2
3
4


List<List<Integer>> windows = Stream.of(1, 2, 3, 4, 5)
 .gather(Gatherers.windowFixed(2))
 .toList();
// [[1, 2], [3, 4], [5]]

Stream API 的扩展点——能写自己的中间操作。

Scoped Values（替代 ThreadLocal）

1
2
3
4
5


private static final ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();

ScopedValue.where(CURRENT_USER, user).run(() -> {
 // 任意位置可读 CURRENT_USER.get()
});

比 ThreadLocal 更安全（不可变）、虚拟线程友好。

Class-File API

操作 .class 文件的标准 API——替代第三方 ASM / Javassist。

Pattern Matching 进一步增强

支持 deconstruction patterns：

1
2
3


if (obj instanceof Point(int x, int y)) {
 // 直接解构出 x, y
}

KEM（Key Encapsulation Mechanism）API

后量子密码学的标准 API——为量子计算时代做准备。

六、未来：在路上的特性

Project Valhalla：Value Types

Java 历史上最大的待发布特性之一——把 int / long 这种"值"也变成 first-class 类型：

1
2
3
4
5
6


value class Point {
 int x;
 int y;
}

// Point 像 int 一样在栈上，没有 object header

对性能极其敏感的场景（数值计算、大量小对象）会有数量级的提升。预计 Java 27/28 才能正式 GA。

Project Panama：原生互操作

替代 JNI——让 Java 直接调 C 库不需要写胶水代码：

1
2
3
4
5


SymbolLookup loader = SymbolLookup.libraryLookup("c", arena);
MethodHandle strlen = Linker.nativeLinker().downcallHandle(
 loader.find("strlen").orElseThrow(),
 FunctionDescriptor.of(JAVA_LONG, ADDRESS)
);

部分功能在 Java 22 已 GA（FFM API）——后续完善中。

Project Leyden：AOT 编译

让 Java 启动时间更接近 GraalVM Native Image——但保留 JVM 的全部能力。

Project Lilliput：紧凑对象头

把对象头从 96 位压到 64 位——所有 Java 对象内存占用减小，对小对象密集场景显著。

Project Babylon：HAT（Heterogeneous Accelerator Toolkit）

让 Java 直接利用 GPU / TPU——为 AI 时代准备。

七、生态展望

几条趋势性判断，2026 年看：

虚拟线程改变了 Reactive 的位置——Java 21+ 让传统 MVC + 虚拟线程在高并发场景接近 WebFlux 的吞吐，多团队从 WebFlux 回到 MVC + 虚拟线程，Reactive 的适用面收窄到流式/背压场景。
Native Image 在特定场景成为主流——Serverless 冷启动、CLI 工具、短生命周期 K8s Pod 这类场景里 GraalVM Native Image 已是常见选择；通用业务系统仍用 JVM。
企业 AI 服务的部署主力仍是 Java——Python 主导训练，但模型上线后的高 QPS 推理服务、RAG 中台、Agent 编排，Spring AI、LangChain4j 等 Java 框架在快速吃这块。
Spring Boot 3 强制 Java 17+ 让"还在 Java 8/11"的项目数量在 2026 年明显下降。
Kotlin 在 Android 仍占主导，服务端推进缓慢——Java 21/25 已吸收了 Kotlin 大部分语法优势，服务端从 Java 转 Kotlin 的动力变弱。

至于 Java 还有没有未来——TIOBE 长期前 5（近年常驻第 3-4）、GitHub Octoverse 长期前 5、金融/电信/政府企业市场 90% 仍是 Java、Stack Overflow 调查显示使用率稳定。生态成熟 + 性能稳定 + 工具完善 + 招聘容易这四条没有变。可以预期的几个落地方向：服务端主力（金融、电商、SaaS 后端）、大数据基础设施（Kafka / Flink / Spark / Elasticsearch 都是 JVM）、企业 AI 服务部署。

八、给开发者的实战建议

1. 升级路径

Java 8 → Java 17：主要工作是 module path / removed API 检查
Java 11 → Java 17：相对平滑
Java 17 → Java 21：稳健，主要享受虚拟线程
Java 21 → Java 25：仅加新特性，向后兼容

没有 LTS 间跳跃的特殊难点——多数升级 1-2 周能完成。

2. 选择当下的 LTS

如果要长期 commit：

新项目 → Java 21 或 25
稳定老项目 → 先升 17，再考虑 21
特殊老系统 → Java 8 仍可用，但 Spring Boot 2.7 EOL 在即

3. 关注的特性

按重要性：

虚拟线程（Java 21+）——直接影响架构选择
Pattern Matching（Java 21+）——影响日常代码风格
Records / Sealed（Java 17+）——值类对象设计
Text Blocks（Java 17+）——SQL / JSON 嵌入更舒适
Switch Expressions（Java 17+）——告别 break

4. 工具链

JDK 发行版：Eclipse Temurin（默认推荐）、Amazon Corretto、Azul Zulu、GraalVM
构建工具：Maven 仍主流，Gradle 在新项目崛起
IDE：IntelliJ IDEA 是事实标准

小结

把全文压一句：

Java 不是『过气』也不是『万能』——它是『稳健、强生态、持续演进』的成熟语言。从 8 到 25，每一步都在补齐缺陷，但保留了向后兼容的稳定性。

工程要点：

当下 LTS 用 Java 21 或 25
Spring Boot 3 强制 Java 17+
虚拟线程改变了高并发架构选择
Pattern Matching 让代码现代化
Valhalla / Panama / Leyden 是未来 5 年最大的 Java 项目

如果你 5 年没升过 Java，2026 年值得认真考虑升级——Java 21+ 的体验和过去差别很大。

Go 与 Java 泛型：晚到的 vs 老牌的，对比谁更好用

Tue, 09 Dec 2025 15:30:00 +0800

写在前面

泛型是现代编程语言的"老话题"了——Java 1.5（2004 年）就有，C++、C#、TypeScript 都早早具备。但Go 直到 1.18（2022 年）才引入泛型。

很多人好奇——Go 的泛型和 Java 比有什么不同？只是"语法换换"还是真有本质差异？

本文从语法、实现机制、边界、常见用法做全面对比——让你看完能准确判断"什么场景哪个语言的泛型更好用"。

一、语法层面对比

最简单的例子：泛型函数

Java：

1
2
3
4
5
6


public static <T> T identity(T x) {
 return x;
}

String s = identity("hello");
Integer i = identity(42);

Go：

1
2
3
4
5
6


func Identity[T any](x T) T {
 return x
}

s := Identity("hello")
i := Identity(42)

非常相似——只是位置不同。Java 用 <T> 在返回类型前，Go 用 [T any] 在函数名后。

泛型类型 / 结构体

Java：

1
2
3
4
5
6
7


public class Box<T> {
 private T value;
 public Box(T value) { this.value = value; }
 public T get() { return value; }
}

Box<String> box = new Box<>("hello");

Go：

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


type Box[T any] struct {
 value T
}

func NewBox[T any](v T) *Box[T] {
 return &Box[T]{value: v}
}

func (b *Box[T]) Get() T {
 return b.value
}

box := NewBox("hello") // 类型推断

Go 的方法接收者也要写 [T]——稍啰嗦。但类型推断更友好——NewBox("hello") 不用写 NewBox[string]。

二、约束系统的差异

这是两者最大的差异——怎么限制泛型的类型。

Java：基于 `extends` 的边界

1
2
3


public static <T extends Comparable<T>> T max(T a, T b) {
 return a.compareTo(b) > 0 ? a : b;
}

T extends Comparable<T> 限定 T 必须实现 Comparable 接口。

也支持 & 多个接口：

1

public static <T extends Comparable<T> & Serializable> ...

Go：基于"约束接口"

Go 用 interface 表达约束——但比 Java 灵活得多：

1
2
3
4
5
6
7
8


type Ordered interface {
 ~int | ~int64 | ~float64 | ~string
}

func Max[T Ordered](a, b T) T {
 if a > b { return a }
 return b
}

注意 ~int 中的 ~ 符号——表示"底层类型是 int 的所有类型"，包括 type MyInt int 这种自定义类型。

类型集合（type set）

Go 引入了"类型集合"概念——可以用 | 表达多个类型的并集：

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


type Number interface {
 int | int8 | int16 | int32 | int64 | uint | uint8 | ...
 float32 | float64
}

func Sum[T Number](s []T) T {
 var total T
 for _, v := range s {
 total += v
 }
 return total
}

Java 做不到同样的事——Java 没法说"接受 int 或 long 但不接受其他"。Java 要这种行为只能用接口（牺牲基本类型）或重载方法。

三、实现机制：擦除 vs 单态化

这是最深的差异——编译器怎么处理泛型代码。

Java：类型擦除（Type Erasure）

Java 编译时把泛型类型擦除成 Object，运行时所有 List<String> 和 List<Integer> 都是同一个 List 类。

1
2
3


List<String> a = new ArrayList<>();
List<Integer> b = new ArrayList<>();
System.out.println(a.getClass() == b.getClass()); // true！

类型擦除的代价

1
2
3
4
5
6
7


public <T> T create() {
 return new T(); // ❌ 不能 new T，运行时不知道 T 是什么
}

public <T> T[] toArray() {
 return new T[10]; // ❌ 同样不行
}

绕路要传 Class<T>：

1
2
3


public <T> T create(Class<T> clazz) {
 return clazz.getDeclaredConstructor().newInstance();
}

Go：单态化（Monomorphization）

Go 编译时为每个具体类型生成专门的代码——Max[int] 和 Max[float64] 是两段独立代码。

1
2


m1 := Max(1, 2) // 编译生成 Max_int
m2 := Max(1.0, 2.0) // 编译生成 Max_float64

实际上 Go 做的是部分单态化（GCShape）——按"GC 形状"分组，不是每个类型都独立。

对比

	Java（擦除）	Go（单态化）
编译速度	快	慢（要展开多份）
二进制体积	小	大
运行时性能	中（要装箱拆箱）	高（特化代码）
反射支持	弱（运行时类型擦除）	强（保留类型信息）
不能 new T	真	可以（用 reflect）

四、装箱与基本类型

Java 泛型最大的痛——不能用基本类型：

1
2


List<int> l = ...; // ❌ 不行
List<Integer> l = ...; // ✓ 装箱

每个 int 都被装箱成 Integer 对象——内存占用 4-5 倍，还有 GC 压力。

Go 没这个问题：

1
2


list := []int{1, 2, 3} // 直接是 int，无装箱
GenericFunc[int](42) // 直接传 int

Go 在数值密集场景下泛型性能远超 Java 泛型。

五、常见用法对比

1. 集合工具函数

Java（用 Stream）：

1
2
3


List<Integer> doubled = list.stream()
 .map(i -> i * 2)
 .collect(Collectors.toList());

Go（自己实现 Map）：

1
2
3
4
5
6
7
8
9


func Map[T, U any](s []T, f func(T) U) []U {
 r := make([]U, len(s))
 for i, v := range s {
 r[i] = f(v)
 }
 return r
}

doubled := Map(list, func(i int) int { return i * 2 })

Go 1.21 之后标准库有 slices 包：

1
2
3
4
5


import "slices"

slices.Sort(list)
slices.Contains(list, 5)
slices.Max(list)

2. 容器类

Java：

1

Map<String, List<User>> usersByCity = new HashMap<>();

Go：

1

usersByCity := make(map[string][]*User)

Go 的内置容器（map、slice）已经支持泛型——不需要单独的"泛型容器"。这是 Go 的优势。

3. 错误处理 / Result 类型

Rust 风格 Result 类型——Java 没有但能实现：

Java：

1
2
3
4
5


public class Result<T, E> {
 private final T value;
 private final E error;
 // ...
}

Go：

1
2
3
4
5
6
7


type Result[T any] struct {
 Value T
 Err error
}

func Ok[T any](v T) Result[T] { return Result[T]{Value: v} }
func Err[T any](e error) Result[T] { return Result[T]{Err: e} }

不过 Go 社区主流仍是 (value, error) 双返回——Result 类型不流行。

六、Go 泛型的限制

Go 1.18 引入泛型时刻意做了"最小可用"——功能上比 Java 少很多：

1. 无方法泛型

Go 的方法不能引入新的泛型参数——只能复用所属类型的参数：

1
2
3
4
5
6
7


type Box[T any] struct { v T }

// ❌ 不行：方法不能有自己的泛型参数
func (b *Box[T]) Map[U any](f func(T) U) *Box[U] { ... }

// ✓ 必须包装成顶级函数
func MapBox[T, U any](b *Box[T], f func(T) U) *Box[U] { ... }

这是 Go 泛型的最大遗憾——写流式 API 比 Java 啰嗦。

状态更新（截至 Go 1.25, 2025-08）：方法泛型仍未支持，且 Go FAQ 明确写着 “we do not anticipate that Go will ever add generic methods”。社区有持续提案（issue #77273 是当前最新的 spec 提案），但官方态度悲观。技术原因主要是"参数化方法会产生无限多的具体方法签名"——会破坏 reflect 包的向后兼容。所以可见的未来里，写 Go 泛型流式 API 都得用顶级函数包一层。

2. 无变型（Variance）

Java 有 ? extends T / ? super T 表达协变 / 逆变——Go 没有。

1

List<? extends Number> list = new ArrayList<Integer>(); // ✓

1

// Go 没有等价语法

3. 无 Constraint Inference

Java 的类型推断范围广，能推断出复杂约束——Go 仅做"显式 + 简单推断"。

4. 没有"条件实现"

Go 的方法集是"全有或全无"——无法表达"仅当 T 满足某个约束时，Box[T] 才实现某个接口"（C# 的 where T: IFoo + 条件 impl，或 Rust 的 conditional impl<T: Foo> Bar for Box<T> 都做得到，Go 没有等价物）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


type Stringer interface {
 String() string
}

type Box[T any] struct { v T }

// ✓ 可以无条件实现 Stringer，T 是不是 Stringer 都行
func (b Box[T]) String() string { return fmt.Sprintf("%v", b.v) }

// ❌ 没法表达"仅当 T 是 Stringer 时 Box[T] 才实现 Stringer"

5. 顺手吐槽：`[]` 把泛型、map、切片三件事挤在一起

以下纯属个人意见，不喜请轻喷。

Java / C# / Rust / TypeScript 都用 <T> 表达泛型，和数组下标 []、Map 访问 .get(k) 各管一摊，看一眼就知道是哪件事。Go 当年的官方理由是 <> 会和比较运算符 < > 在解析时产生歧义（例如 a, b = w < x, y > (z) 这种）——所以选了已经被 map / slice 占用的方括号。

听起来很学术，但实际上：

Java、C#、Rust、TypeScript 全都用 <>，解析器写得也都没出问题——所谓的歧义在工程上是可以处理的，无非是写编译器麻烦点
Go 团队选 [] 真正避开的是"写解析器麻烦"，但代价是把这个负担转嫁给了所有读代码的人——同一个 [] 现在要在脑子里区分三件事：

1
2
3
4


m[k] // map 访问（运行时）
s[i] // 切片下标（运行时）
List[int] // 泛型类型实参（编译期）
List[int]{1,2} // ↑ 后面跟花括号才知道是泛型实例化，不是数组下标

实际项目里读到 Cache[string, User] 一开始要愣两秒——脑子里要切换到"哦这是泛型"。pool.Get[*User]() 这种调用乍一看像是"取下标然后调用"，得想一下才反应过来。

不算硬伤，但确实是 Go 泛型读起来"差点意思"的最直接原因。省了编译器作者一次工，让全世界的 Go 程序员每天多想一秒——这买卖不太划算。

6. 顺便再吐一句：Go 的时间格式

同样是个人吐槽。

既然提到了 Go 的语法选择——Go 的时间格式化设计也是一脉相承的"为我自己方便"：别的语言都用 %Y-%m-%d %H:%M:%S 这种 strftime / ISO 风格，Go 偏要让你记一个 reference time：

1
2
3


"Mon Jan 2 15:04:05 MST 2006"
// 对应美式记忆：1 月 2 日 下午 3 点 4 分 5 秒 2006 年，时区 MST，星期一
// 1 / 2 / 3 / 4 / 5 / 6 / 7 顺口溜

设计者很得意——“你看，1234567 多好记”。

问题是：

01/02 是美式日期格式（MM/DD），全世界绝大部分国家用 DD/MM
15:04:05 旁边还要配 AM/PM 的 12 小时制
MST（Mountain Standard Time）是美国山地时区——非美国人这辈子用不到几次
整个"顺口溜"只有美国人觉得顺口

所以 Go 程序员每次写 time.Format("2006-01-02 15:04:05") 时，都得在脑子里把美式 1/2/3/4/5/6/7 顺口溜过一遍——其他语言一句 %Y-%m-%d %H:%M:%S 就能表达的事，Go 要绕一圈。

跟泛型用 [] 一样，这两件事有同一种气味——设计者当年的便利感，最后由所有用户来承担。多少有点 American-centric 的味道。

不影响 Go 是好语言，但读 / 写这两处时偶尔会忍不住想"本来可以不这样的"。

七、Java 泛型的限制

1. 类型擦除导致的反射受限

1
2


List<String> list = new ArrayList<>();
list.getClass(); // 只是 ArrayList，不知道 String

要拿到 String 类型信息要 TypeReference（Jackson 等库的常见做法）。

2. 不能 new T

如前所述。

3. 数组与泛型不兼容

1
2


T[] arr = new T[10]; // ❌
List<String>[] lists = new List<String>[10]; // ❌

历史包袱——Java 数组先于泛型存在，两者设计不兼容。

八、性能对比

	Java	Go
泛型函数调用开销	装箱 + 虚调用	无装箱 + 直接调用
内存占用	每个对象多一层 object header	紧凑数组
GC 影响	装箱对象增加 GC 负担	无影响
编译速度	快	慢（单态化）
二进制体积	小	大（每个特化版本）

数值密集场景 Go 泛型快 2-5 倍 —— 因为 Go 不装箱。

九、典型场景该用谁

flowchart TD
 Q1{要写库还是业务?}
 Q1 -->|库| Lib{需要复杂类型约束?}
 Q1 -->|业务| Biz[两个都够用]
 Lib -->|是，需要变型 / 复杂边界| Java[Java 泛型表达力更强]
 Lib -->|否，简单约束| Either[Go 更简洁]

实战建议：

Go 项目：用 1.21+ 标准库的 slices / maps 包——日常需求够了；自己写库时少滥用泛型（Go 社区文化是"够用就好"）
Java 项目：泛型几乎是必须——集合、Stream、CompletableFuture 都依赖

十、Go 社区对泛型的争议

Go 引入泛型的争议持续多年——有人觉得 Go 不需要泛型：

“Go 的简单是它的核心优势——加泛型只会让代码变复杂”

也有人坚定支持：

“没有泛型，每个排序函数都要写一遍”

最终 Go 团队选择了保守的最小可用方案——这是为什么 Go 泛型没有方法泛型、没有变型、没有约束推断。

这个保守是好事还是坏事？——主流意见是好事。Go 泛型保留了 Go 的简洁哲学，业务代码里 90% 场景不需要泛型。

十一、什么时候真的该用泛型

不论 Go 还是 Java——别为了用泛型而用泛型。判断标准：

✅ 真的需要：

写数据结构（链表、树、图）
写算法工具（排序、查找、map/filter/reduce）
写容器（cache、pool）
写跨类型的辅助函数（Identity、Coalesce）

❌ 不该用：

业务实体（User、Order 不需要泛型化）
单一类型的工具函数
“为了通用"的过度设计

简单代码胜过抽象代码——这条原则在两个语言都适用。

小结

把全文压一句：

Go 泛型的设计哲学是『最小可用 + 高性能』，Java 泛型是『表达力强 + 历史包袱重』——前者赢在简洁和速度，后者赢在生态成熟和工具完善。

各自适合的场景：

Go 泛型：性能敏感、数值密集、库开发场景胜出
Java 泛型：复杂业务建模、需要变型、生态丰富时胜出

但两者最重要的共同点：90% 的业务代码根本不需要泛型。把泛型当工具，需要时拿出来用——不要为了显示"会泛型"而强行抽象。

Protobuf 协议原理解析：为什么它能比 JSON 小一半还快几倍

Thu, 06 Nov 2025 15:30:00 +0800

写在前面

写过 gRPC 或 Dubbo 的人都见过 .proto 文件：

1
2
3
4
5


message User {
 int64 id = 1;
 string name = 2;
 repeated string tags = 3;
}

编译生成代码、序列化、传输——业务里只用到几行 API，但底层 Protobuf 的二进制格式做了非常多巧妙的设计。

理解 Protobuf 的内部原理对工程有几个直接价值：

能解释为什么 Protobuf 比 JSON 小一半——不只是"去掉了字段名"那么简单
能避免字段编号变更导致的兼容性灾难
能在性能敏感场景做出精准选型

本文从 wire format 到 Varint 到字段标签，把 Protobuf 的核心机制讲清楚。

一、为什么不是 JSON

JSON 的问题：

字段名占大量空间——{"username": "alice", "age": 30} 字段名比值还长
数字编码冗余——123456789 当字符串编码要 9 字节
解析慢——要 tokenize、要 parse、要 build object
无 schema——不知道字段类型，要靠运行时推断

Protobuf 的解法：

字段名替换为编号——username 变成 1，age 变成 2
数字用 Varint——小数字用更少字节
二进制 stream 解析——按 schema 直接读
schema 是契约——sender / receiver 都依赖同一个 .proto

二、Wire Format：字段的二进制表示

每个字段在 wire 上都是 (tag, value) 的形式。tag 由两部分组成：

1

tag = (field_number << 3) | wire_type

field_number：在 .proto 里定义的字段编号（如 name = 2 中的 2）
wire_type：3 位，表示 value 的编码方式

Wire Types

Type	名称	用途
0	Varint	int32 / int64 / uint32 / uint64 / bool / enum
1	64-bit	fixed64 / sfixed64 / double
2	Length-delim	string / bytes / message / packed
5	32-bit	fixed32 / sfixed32 / float

类型 3、4 是 group 类型（已弃用）。

例子

message Person { string name = 1; int32 age = 2; }，对应数据 {name: "abc", age: 30}：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


field 1, wire_type 2 (string):
 tag = (1<<3) | 2 = 0x0A
 length = 3 (varint)
 value = "abc" → 61 62 63

field 2, wire_type 0 (varint):
 tag = (2<<3) | 0 = 0x10
 value = 30 (varint) → 0x1E

整个二进制：
 0A 03 61 62 63 10 1E

只有 7 字节——而 JSON 的 {"name":"abc","age":30} 是 22 字节。

三、Varint：变长整数编码

Varint 是 Protobuf 的核心创新——小数字用更少字节，大数字才用多字节。

编码规则

每个字节的最高位（MSB）作为"还有更多字节"的标志：

MSB = 1 → 后面还有
MSB = 0 → 这是最后一个字节
其余 7 位是 payload

编码示例

数字 1：

1
2


binary: 00000001
Varint: 00000001 (1 byte)

数字 300：

1
2
3
4
5


binary: 100101100 (9 bits)
groups of 7: 0000010 0101100
按小端: 0101100 0000010
加 MSB: 1010 1100 0000 0010
hex: AC 02

数字越小占的字节越少：

数字范围	Varint 字节数
0 - 127	1
128 - 16383	2
16384 - 2M	3
2M - 268M	4
268M+	5

业务里 ID 多数小于 2 亿——Varint 比定长 8 字节 int64 节省 50% 以上。

Varint 的代价

负数特别大：-1 在补码下是 0xFFFFFFFF...FFFF（10 字节），所有负数都用 10 字节
解决：sint32 / sint64 用 ZigZag 编码——正负数交替排列，让 -1, 1, -2, 2 都很小

1
2
3
4
5


sint32 编码: (n << 1) ^ (n >> 31)
-1 → 1
1 → 2
-2 → 3
2 → 4

有负数的字段一定要用 sint32 / sint64——否则空间浪费惊人。

四、Length-delimited：字符串和子消息

string、bytes、嵌套 message、packed repeated 都用 length-delimited：

1

[tag][length][bytes...]

length 也是 Varint——所以 1 字节就能表示 0-127 字节的内容。

嵌套 message

1
2
3
4
5


message Address { string city = 1; }
message Person {
 string name = 1;
 Address addr = 2;
}

嵌套消息不是"展开"——而是当作一段嵌入的二进制流：

1
2
3
4


field 2 (addr):
 tag = (2<<3) | 2 = 0x12
 length = N (varint)
 value = [Address 的完整序列化字节]

这意味着——Protobuf 的解析器是递归的，但内存效率极高。

五、字段编号：兼容性的命脉

字段编号是 Protobuf 兼容性的核心约定——一旦定了，永不能改：

1
2
3
4
5


message User {
 int64 id = 1;
 string name = 2;
 string email = 3; // 之后加的
}

兼容规则

新增字段 → 老 client 解析时跳过未知字段（不报错）
删除字段 → 字段编号永不复用，加 reserved 防止
改类型 → 大多数情况会破坏兼容（除少数兼容对，如 int32 ↔ int64）
改字段名 → 不影响 wire（wire 只用编号）但破坏代码层面 API

reserved 的用法

1
2
3
4
5
6
7
8


message User {
 reserved 4, 5;
 reserved "old_field";

 int64 id = 1;
 string name = 2;
 // ...
}

防止后人不小心复用了已删除的字段编号——会编译错误。

字段编号的成本

1-15 编号占 1 字节 tag
16-2047 占 2 字节
2048+ 占 3 字节

高频字段尽量用 1-15 编号——能省一字节。

六、Repeated 和 packed 编码

1

repeated int32 ids = 4;

默认编码（proto2）：每个元素单独发一遍 tag + value：

1

tag value tag value tag value ...

[packed = true]（proto3 默认）：合并成单个 length-delimited 块：

1

tag length value value value ...

packed 显著节省空间——尤其当数组元素都是小数字时。proto3 默认 packed，proto2 要显式声明。

七、Proto2 vs Proto3

Proto2

字段标记 required / optional / repeated
默认值显式声明
区分"未设置"和"等于默认值"

Proto3

删掉 required 和 optional（后又部分恢复）
字段总是 optional
默认值不发送
packed 默认开启

现状

新项目用 proto3——更简洁
2020 年后 proto3 又支持 optional——能区分"没设" vs “等于默认值”
老项目用 proto2 也没问题，但社区主要在 proto3

八、性能对比

	JSON	Protobuf	Avro	MessagePack
体积（典型业务对象）	1×	0.4-0.5×	0.4×	0.6×
序列化速度	1×	5-10×	5×	3×
反序列化速度	1×	5-10×	5×	3×
跨语言	✓	✓	✓	✓
人类可读	✓	✗	✗	✗
Schema 强约束	✗	✓	✓	✗

Protobuf 的核心优势：体积 + 速度 + schema 一致性。核心劣势：不可读 + 必须先有 schema。

九、什么场景用 Protobuf

✅ 适合：

gRPC 服务调用——Protobuf 是 gRPC 默认序列化
微服务间通信——schema 强约束，避免字段约定问题
移动端 / IoT ——节省带宽
批量数据处理（Hadoop / Kafka）——高吞吐
存储优化——某些 KV 存储用 Protobuf 序列化 value

❌ 不适合：

对外 REST API——前端期望 JSON
小项目 / 调试期——要 .proto 文件 + 编译器，启动成本高
schema 频繁变化——每次都要发版
需要人类可读——Protobuf 没法直接看

十、几个工程踩坑

1. 字段编号永不复用

1
2
3
4


message User {
 // 删除了 string old_field = 4;
 string new_field = 4; // ❌ 不能复用编号 4！
}

老 client 拿到新数据时会把 new_field 的内容当成 old_field 解析——数据被错乱。永远 reserved。

2. enum 默认值

1
2
3
4


enum Status {
 PENDING = 0; // 必须有 0 值（默认）
 ACTIVE = 1;
}

proto3 强制 enum 必须有 0 值——这个值代表"未设置"。业务设计 enum 时考虑这个。

3. 大消息分包

某些 RPC 框架对单个 message 大小有限制（如 gRPC 默认 4MB）——大数据要 stream 而非单包：

1
2
3


service FileService {
 rpc Upload(stream FileChunk) returns (UploadResp);
}

4. 字符串编码

Protobuf string 必须是合法 UTF-8——塞二进制数据用 bytes 类型，否则解析会失败。

5. Optional 的 has 方法

proto3 的 optional 字段才能区分"没设"和"等于默认值"——普通字段无法区分：

1
2
3
4


message User {
 int32 age = 1; // 普通：age = 0 和"没设"无法区分
 optional int32 score = 2; // optional：能区分
}

业务模型设计时考虑——重要的"是否存在"语义字段加 optional。

十一、Protobuf 与 gRPC 的关系

很多人误以为"Protobuf = gRPC"——其实它们独立：

Protobuf：序列化协议
gRPC：基于 HTTP/2 的 RPC 框架，默认用 Protobuf

Protobuf 也能用在：

不走 gRPC 的 RPC（如 Dubbo3 的 Triple 协议）
Kafka 消息序列化
自己写的二进制协议
文件存储

小结

把全文压一句：

Protobuf 不只是『二进制 JSON』——它是 schema-driven 序列化的范式：用编号代替字段名、用 Varint 节省空间、用 wire type 保证可解析、用兼容规则保证演进。

工程要点：

字段编号永不复用
小数字用 Varint，负数用 sint
重要字段用 1-15 编号
enum 必须有 0 值
packed repeated 默认开
大数据用 stream RPC

理解 Protobuf 的内部原理——下次再排查"为什么我的 protobuf 数据 client 解不出来"时，你能瞬间想到是字段编号被改了还是类型不兼容。

数据字典表与菜单的国际化方案

Fri, 19 Sep 2025 15:30:00 +0800

写在前面

国内系统做国际化常常掉进一个误区——以为前端搞个 i18n 文件就完事了。但当业务真要支持多语言（出海、跨境电商、海外 SaaS）时，你会发现：

错误消息从后端来——前端 i18n 没用
数据字典（订单状态、产品类型）从 DB 来——前端写死翻译会脱节
菜单和按钮文本从配置中心来——前端 i18n 不能覆盖
营销内容/邮件模板/短信模板都要多语言

真正的国际化是『后端数据 + 前端展示』的协同。本文围绕数据字典和菜单这两个最难的场景，给出生产级方案。

一、为什么数据字典国际化最难

普通业务表的国际化简单——加个 _en 字段就完事。但数据字典特殊：

字典本身可配置——产品/运营会随时新增字典项
多语言字段动态——今天支持中英，明天加日韩西
菜单层级深——一级菜单/二级菜单都要翻译
跨业务共享——同一个字典被多个模块用

这种场景下"加 _en 字段"会导致：

1

status_zh, status_en, status_ja, status_ko, status_es, ...

字段无限增长——根本没法管。

二、方案 1：i18n 副表

最常见的做法——主表存核心数据，副表存翻译：

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


CREATE TABLE dict_item (
 id BIGINT PRIMARY KEY,
 type VARCHAR(50), -- order_status / product_type ...
 code VARCHAR(50), -- PAID / SHIPPED ...
 sort INT,
 enabled BOOLEAN,
 UNIQUE KEY uk_type_code (type, code)
);

CREATE TABLE dict_item_i18n (
 id BIGINT PRIMARY KEY,
 dict_item_id BIGINT,
 locale VARCHAR(10), -- zh-CN / en-US / ja-JP / ...
 label VARCHAR(255), -- 翻译后的名称
 description VARCHAR(500), -- 翻译后的描述
 UNIQUE KEY uk_item_locale (dict_item_id, locale)
);

查询时 JOIN：

1
2
3
4
5


SELECT i.code, t.label
FROM dict_item i
LEFT JOIN dict_item_i18n t ON t.dict_item_id = i.id AND t.locale = ?
WHERE i.type = 'order_status' AND i.enabled = TRUE
ORDER BY i.sort;

优点

加新语言只增数据不改 schema
字典项本身和翻译解耦
易于配后台管理

缺点

每次查都 JOIN——大量字典查询有性能开销
缺少某语言时 fallback 要自己处理

Fallback 策略

请求 locale = ja-JP，但只有 zh-CN 和 en-US 翻译——怎么办？两种策略：

回退到默认语言（通常是 en-US）——返回英文
回退到 code 本身——比如返回 “PAID”

1
2
3
4
5
6
7
8


SELECT i.code,
 COALESCE(
 t.label,
 (SELECT label FROM dict_item_i18n WHERE dict_item_id = i.id AND locale = 'en-US'),
 i.code
 ) AS label
FROM dict_item i
LEFT JOIN dict_item_i18n t ON t.dict_item_id = i.id AND t.locale = ?

三、方案 2：JSON 字段

主表用 JSON 字段存所有语言：

1
2
3
4
5
6
7


CREATE TABLE dict_item (
 id BIGINT PRIMARY KEY,
 type VARCHAR(50),
 code VARCHAR(50),
 labels JSON, -- {"zh-CN": "已付款", "en-US": "Paid", "ja-JP": "支払済み"}
 sort INT
);

查询：

1
2


SELECT code, JSON_EXTRACT(labels, '$."zh-CN"') AS label
FROM dict_item WHERE type = 'order_status';

优点

不用 JOIN，单表查询快
schema 极简
取数据时一次拿到所有语言

缺点

JSON 字段查询/索引能力差
后台编辑更新某个语言要 JSON 操作
字典量大时 JSON 体积膨胀

适合字典量不大、改动不频繁的场景。

四、方案 3：消息文件 + DB 关联

把翻译完全放在配置文件（properties / yaml）里：

1
2
3
4
5


# messages_zh_CN.properties
dict.order_status.PAID=已付款
dict.order_status.SHIPPED=已发货

dict.product_type.SAAS=SaaS 服务

1
2
3


# messages_en_US.properties
dict.order_status.PAID=Paid
dict.order_status.SHIPPED=Shipped

DB 只存 code，业务里用 MessageSource 翻译：

1
2
3
4
5
6
7
8


@Autowired private MessageSource messageSource;

public String getLabel(String type, String code, Locale locale) {
 return messageSource.getMessage(
 "dict." + type + "." + code,
 null, code, locale
 );
}

优点

走标准 Spring i18n——成熟可靠
文件易于版本管理
性能极好（启动时全加载到内存）

缺点

不能在后台动态改翻译——必须发版
配置文件长了不好维护
多语言文件容易忘改

适合翻译相对稳定的场景——但是少数。多数业务希望运营能自己改翻译，这种方案不行。

五、推荐：副表 + 多级缓存

对一个生产级国际化系统，我推荐这套架构：

flowchart LR
 Client[前端] --> Cache1[CDN 缓存]
 Cache1 --> API[API 网关]
 API --> AppCache[应用本地缓存
Caffeine]
 AppCache --> RedisCache[(Redis)]
 RedisCache --> DB[(主表 + i18n 副表)]
 Admin[管理后台] -.改翻译.-> DB
 Admin -.触发刷新.-> RedisCache
 RedisCache -.广播失效.-> AppCache

设计要点：

DB 用副表方案（方案 1）
Redis 缓存全量字典——几 MB 数据，启动加载
应用本地 Caffeine 缓存——避免每次查 Redis
管理后台改翻译时主动失效缓存——所有实例同步刷新（用 Redis pub/sub 或 MQ）
前端 Service Worker / CDN 缓存按 locale 区分

六、菜单的国际化

菜单是另一个棘手场景——菜单结构是动态的，每个用户看到的菜单可能不同：

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


CREATE TABLE menu (
 id BIGINT PRIMARY KEY,
 code VARCHAR(100) UNIQUE,
 parent_code VARCHAR(100),
 icon VARCHAR(100),
 path VARCHAR(255),
 sort INT,
 permission VARCHAR(100),
 enabled BOOLEAN
);

CREATE TABLE menu_i18n (
 menu_id BIGINT,
 locale VARCHAR(10),
 title VARCHAR(255),
 PRIMARY KEY (menu_id, locale)
);

查询：

1
2
3
4
5
6
7


SELECT m.id, m.code, m.parent_code, m.icon, m.path, m.sort,
 COALESCE(t.title, t_default.title, m.code) AS title
FROM menu m
LEFT JOIN menu_i18n t ON t.menu_id = m.id AND t.locale = ?
LEFT JOIN menu_i18n t_default ON t_default.menu_id = m.id AND t_default.locale = 'en-US'
WHERE m.enabled = TRUE
ORDER BY m.sort;

返回前端时已经是带翻译的菜单树——前端只需渲染。

七、错误消息的国际化

后端错误也要多语言——但错误信息往往动态：

1

throw new BusinessException("user_not_found", "User " + userId + " not found");

不能写死翻译——要用模板：

1
2
3


# messages_zh_CN.properties
error.user_not_found=用户 {0} 不存在
error.insufficient_balance=余额不足，需要 {0} 但只有 {1}

 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


public class I18nException extends RuntimeException {
 private final String code;
 private final Object[] args;

 public I18nException(String code, Object... args) {
 super(code);
 this.code = code;
 this.args = args;
 }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
 @Autowired private MessageSource messageSource;

 @ExceptionHandler(I18nException.class)
 public Result handle(I18nException e, Locale locale) {
 String msg = messageSource.getMessage(
 "error." + e.getCode(),
 e.getArgs(),
 "Unknown error",
 locale
 );
 return Result.fail(e.getCode(), msg);
 }
}

业务里：

1

throw new I18nException("user_not_found", userId);

八、Locale 的传递

前端怎么告诉后端"我要中文"？三种方式：

1. HTTP Header

1

Accept-Language: zh-CN, en;q=0.9

Spring 默认能识别。

2. URL 参数

1

GET /api/dict/order_status?locale=zh-CN

3. 用户偏好

用户登录后，从用户配置里读 locale——存在 user 表或 JWT claim 里。

1
2
3


LocaleResolver resolver = new SessionLocaleResolver();
// 或
LocaleResolver resolver = new AcceptHeaderLocaleResolver();

生产推荐：用户偏好优先 → URL 参数次之 → Header 兜底。

九、几个工程实践

1. 翻译流程标准化

研发 / 产品 / 翻译方的协作流程：

研发提交新字典项（默认中英两语）
翻译方在管理后台补其他语言
缓存自动刷新
上线前 review 是否所有 active 字典项都有翻译

2. 缺翻译的报警

定期跑一个脚本——任何 enabled 字典项缺少某种 locale 翻译就告警：

1
2
3
4
5
6


SELECT i.type, i.code
FROM dict_item i
WHERE i.enabled = TRUE
 AND NOT EXISTS (
 SELECT 1 FROM dict_item_i18n WHERE dict_item_id = i.id AND locale = 'en-US'
 );

3. 翻译质量保证

机器翻译只是初稿——专业翻译必须人工 review。某些行业术语机器翻得很离谱。

4. RTL 语言（阿拉伯语 / 希伯来语）

不只是文字翻译——整个 UI 要从右到左。CSS 用 dir="rtl" 切换。

5. 数字 / 日期 / 货币本地化

1
2
3
4


NumberFormat.getCurrencyInstance(locale).format(123456.78);
// zh-CN: ¥123,456.78
// en-US: $123,456.78
// de-DE: 123.456,78 €

不要自己写——用 ICU / java.text 标准库。

6. 时区

不同 locale 通常配不同时区——时间字段统一存 UTC，展示时按用户 timezone 转换。

十、常见踩坑

1. 把 locale 和 currency 混淆

zh-CN 是 locale，CNY 是 currency——两个完全独立的概念。中国大陆用户也可能想看 USD 报价。

2. 字典项加了但缓存没刷新

新加 dict_item 后必须主动失效缓存——否则要等 Redis TTL 到才能看到。

3. 字典 ID 和 code 都泄漏

返回前端时——只用 code，不要把 ID 暴露。后端内部关联用 ID，前端展示用 code。

4. 移动端 / Web 缓存策略不一致

移动 App 缓存了字典，Web 没缓存——改翻译后 App 用户要等很久才看到。要么 App 也定期同步，要么强制版本检查。

5. SEO 友好

国际化网站——每种语言一个 URL 路径（/zh-cn/... 和 /en-us/...）——而不是用同一个 URL 切换语言。这样搜索引擎能正确索引。

小结

把全文压一句：

后台系统的国际化不是『前端 i18n 文件』那么简单——数据字典、菜单、错误消息这些"动态文本"需要一套完整的『DB + 缓存 + 标准协议』方案。

工程要点：

数据字典用 i18n 副表 + 缓存
菜单同样的姿势
错误消息用 MessageSource + 占位符
缓存改时主动失效
缺翻译要监控告警
locale ≠ currency ≠ timezone，三者独立

把这些做对，你的系统能真正承载"出海到任意国家"——而不只是"加个英文翻译"。

Spring Boot 配置加载机制详解

Thu, 14 Aug 2025 15:00:00 +0800

几乎每个 Spring Boot 项目都遇到过

排查问题时最让人崩溃的一类故障是——

配置改了重启了，行为还是老的。

经验稍丰富的开发会立刻反应过来：它从别处加载了更高优先级的配置，覆盖了你的修改。但这"别处"具体是哪里？覆盖顺序是什么？为什么有些配置改了没生效，有些反而立刻生效？

Spring Boot 的配置加载体系在文档里写得相对分散，本文把它完整拉直说一遍——从 application.yml 到环境变量、从 bootstrap.yml 到 EnvironmentPostProcessor、从 --server.port=8080 到 K8s ConfigMap，把所有渠道按优先级排成一张图。

一、Spring Boot 配置的"位置"全集

Spring Boot 能从这些地方读取配置（优先级从高到低）：

flowchart TD
 A["1. 命令行参数
--server.port=8080"]
 B["2. SPRING_APPLICATION_JSON
JSON 串注入"]
 C["3. ServletConfig / ServletContext 参数"]
 D["4. JNDI 属性"]
 E["5. Java System Properties
-Dxxx=yyy"]
 F["6. OS 环境变量
SERVER_PORT=8080"]
 G["7. RandomValuePropertySource
random.*"]
 H["8. 外部 application.yml
(jar 包外)"]
 I["9. 外部 application-{profile}.yml"]
 J["10. 内部 application.yml
(jar 包内)"]
 K["11. 内部 application-{profile}.yml"]
 L["12. @PropertySource 注解"]
 M["13. 默认值
SpringApplication.setDefaultProperties"]

 A --> B --> C --> D --> E --> F --> G --> H --> I --> J --> K --> L --> M

优先级越靠上的源覆盖越靠下的源——同一个 key 多处定义时，最高优先级的值生效。

记住一个原则：

“外部覆盖内部、命令行覆盖文件、Profile 覆盖默认”——这三句话覆盖了 95% 的优先级问题。

二、为什么命令行优先级最高

Spring Boot 把命令行优先级设到最高，是为了给运维一个『不需要改代码也能改配置』的口子：

1

java -jar app.jar --server.port=9999 --spring.datasource.url=...

无论 jar 包里 application.yml 写了什么，命令行说了算。

K8s 里也是这个意思——通过 ConfigMap 传环境变量，环境变量优先级高于 jar 内配置，就实现了"同一个 jar 部署到不同环境"。

三、application.yml 在哪些位置会被找到

Spring Boot 启动时按以下顺序查找配置文件（Spring Boot 2.3+ 默认）：

1
2
3
4
5


1. file:./config/*/ (运行目录 config 下的一级子目录,2.3+ 起最高优先级)
2. file:./config/ (运行目录的 config 子目录)
3. file:./ (运行目录)
4. classpath:/config/ (jar 内的 config/)
5. classpath:/ (jar 内根目录)

file: 开头表示文件系统位置
classpath: 是 jar 包内
越靠前的位置优先级越高
file:./config/*/ 经常被忽视——K8s 把多个 ConfigMap 分别挂到 config/redis/、config/db/ 等子目录时，就靠这一项被加载

这就是为什么"jar 同级目录放 application.yml"能覆盖 jar 内配置——是 #2 覆盖 #4 的体现。

文件名默认是 application，可以通过 spring.config.name 改：

1

java -jar app.jar --spring.config.name=myapp

会去找 myapp.yml / myapp.properties。

spring.config.location 能完全自定义查找路径：

1

java -jar app.jar --spring.config.location=file:/etc/myapp/

四、Profile 机制：环境维度切换

激活 Profile

1

java -jar app.jar --spring.profiles.active=prod

或者环境变量：

1

SPRING_PROFILES_ACTIVE=prod java -jar app.jar

Profile 文件命名

1
2
3
4


application.yml ← 共享配置
application-dev.yml ← dev profile 独占
application-test.yml ← test profile 独占
application-prod.yml ← prod profile 独占

激活某个 profile 时，application.yml 和 application-{profile}.yml 都会被加载，profile 文件覆盖通用文件。

多 Profile 同时激活

1

--spring.profiles.active=prod,monitoring,debug

按数组顺序加载，后面的覆盖前面的。这是做"基础 prod 配置 + 加监控 + 加调试日志"组合的标准姿势。

`spring.profiles.include`

不同于 active 是"激活什么"，include 是"再附加什么"：

1
2
3
4


# application-prod.yml
spring:
 profiles:
 include: monitoring

激活 prod 时自动也加载 application-monitoring.yml——保证一组配置成套生效，不用每次写命令行参数。

五、`bootstrap.yml` vs `application.yml`

Spring Cloud 项目里还会出现 bootstrap.yml——它是 Spring Cloud 引入的，比 application.yml 更早加载。

flowchart LR
 A[bootstrap.yml
加载阶段 1] --> B[拉取远程配置中心]
 B --> C[application.yml
加载阶段 2]
 C --> D[最终 Environment]

bootstrap.yml 的典型用途——配置"配置中心客户端本身"：

1
2
3
4
5
6
7
8
9


# bootstrap.yml
spring:
 application:
 name: user-service
 cloud:
 nacos:
 config:
 server-addr: nacos.internal:8848
 namespace: prod

为什么必须更早加载？因为 Nacos / Apollo / Spring Cloud Config 的客户端要先连上配置中心，才能拉到 application.yml 里的业务配置——鸡生蛋、蛋生鸡的问题。

Spring Cloud 2020.0 之后官方推荐用 spring.config.import 替代 bootstrap.yml：
1
2
3
spring:
 config:
 import: optional:nacos:application.yml
但 bootstrap.yml 仍然兼容，且大量老项目还在用。

六、外部化配置：12-Factor 的最佳实践

12-Factor App 第三条：“Store config in the environment”——配置应当从环境而来，而不是写死在代码里。Spring Boot 的设计完全贴合这个理念：

1
2
3
4
5
6


# application.yml
spring:
 datasource:
 url: ${DB_URL:jdbc:mysql://localhost:3306/test}
 username: ${DB_USER:root}
 password: ${DB_PASS:}

${VAR:default} 语法——先看环境变量，没有就用默认值。这种写法的好处：

同一个 jar 在 dev/test/prod 三套环境跑
K8s 里通过 ConfigMap / Secret 注入
本地开发不需要 Secret，用默认值

K8s 部署时：

1
2
3
4
5
6
7
8


env:
 - name: DB_URL
 value: jdbc:mysql://prod-mysql:3306/order
 - name: DB_PASS
 valueFrom:
 secretKeyRef:
 name: db-secret
 key: password

七、`@Value` vs `@ConfigurationProperties`

业务代码注入配置有两种主流方式。

`@Value`：单字段注入

1
2


@Value("${server.port:8080}")
private int port;

简单直接，但有几个限制：

不支持类型校验——拼写错了运行时才发现
不支持嵌套对象——只能拿单个值
不便于测试——要在 test 里 mock 整个 Environment

`@ConfigurationProperties`：批量映射

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


@Component
@ConfigurationProperties(prefix = "feature")
@Validated
public class FeatureConfig {
 @NotBlank
 private String name;
 @Min(0) @Max(100)
 private int threshold;
 private Map<String, String> tags;

 // getters / setters
}

1
2
3
4
5
6


feature:
 name: my-feature
 threshold: 50
 tags:
 region: cn
 env: prod

@ConfigurationProperties 是生产推荐姿势——类型安全、能 @Validated 校验、IDE 提示完整、便于单元测试。

`@RefreshScope`

配置中心场景下，要让配置变更立刻生效需要加 @RefreshScope：

1
2
3
4


@Component
@RefreshScope
@ConfigurationProperties(prefix = "feature")
public class FeatureConfig { ... }

但记住：

@RefreshScope 不要加在 @Configuration 上
@ConfigurationProperties 自带的刷新已经够多数场景用，不一定需要 @RefreshScope
复杂业务的"动态配置"建议直接通过事件订阅，而不是依赖 @RefreshScope 重建 Bean

八、调试技巧：搞清楚配置从哪里来

1. Actuator 的 `/actuator/env`

1
2
3
4
5


management:
 endpoints:
 web:
 exposure:
 include: env,configprops

调用 /actuator/env 能看到每个 PropertySource、每个 key 的来源和最终值——是排查"配置不生效"的最快办法。

1
2
3
4
5
6


{
 "name": "applicationConfig: [classpath:/application.yml]",
 "properties": {
 "server.port": { "value": 8080 }
 }
}

2. 启动日志 DEBUG

1

java -jar app.jar --debug

会打出每个 starter 的自动配置生效情况。

3. 启动参数检查

如果你怀疑有命令行参数在覆盖配置，看启动脚本里的所有 -D 和 --，再看环境变量：

1

env | grep -i SPRING

很多"诡异覆盖"是 K8s ConfigMap 里悄悄塞了同名变量。

九、几个最常被踩的坑

坑 1：YAML 缩进与冒号后空格

1
2


server:
 port:8080  # ❌ 冒号后没空格 → 当作字符串

1
2


server:
 port: 8080 # ✓

坑 2：Profile 里的相对路径

1
2
3
4


# application-prod.yml
logging:
 file:
 name: logs/app.log  # 相对路径，相对于"工作目录"，不是项目目录

部署到容器后工作目录可能不是你以为的位置——生产路径写绝对路径。

坑 3：环境变量大小写转换

YAML 里的 spring.datasource.url 对应环境变量是 SPRING_DATASOURCE_URL——点变下划线、全大写。写成 spring.datasource.url 当环境变量是不会被认到的（虽然 Spring Boot 现在支持驼峰转 kebab，但环境变量必须全大写）。

坑 4：占位符递归

1
2


foo: ${bar}
bar: ${foo}  # ❌ 死循环

启动直接报错。但更隐蔽的是：

1
2
3


prefix: app
fullName: ${prefix}-${name:default}
name: ${prefix}-suffix

会展开成预期之外的字符串，自己看不出来。复杂占位符建议拉直写。

坑 5：`@ConfigurationProperties` 没生效

最常见原因是没加 @Component 或 @EnableConfigurationProperties：

1
2
3


@Component
@ConfigurationProperties(prefix = "feature")
public class FeatureConfig { ... }

或者：

1
2
3


@Configuration
@EnableConfigurationProperties(FeatureConfig.class)
public class AppConfig { ... }

二者选其一。

十、生产 Checklist

部署前过一遍：

不在代码 / yml 里硬编码密钥、数据库密码
敏感配置通过环境变量 / Secret 注入
不同环境分别有 application-{env}.yml
--spring.profiles.active 在启动脚本明确传入
业务代码用 @ConfigurationProperties + @Validated
路径相关配置写绝对路径
Actuator env 和 configprops 在生产环境关闭或加权限
大型项目的全局配置走 bootstrap.yml 或 spring.config.import
启动后用 /actuator/env 抽查关键配置的来源

小结

把全文压一句：

Spring Boot 配置加载的本质是『多个 PropertySource 按优先级合并』——只要把『谁覆盖谁』这件事弄明白，所有"配置不生效"的问题都能 5 分钟定位。

记住几条核心规则：

优先级：命令行 > 环境变量 > 外部文件 > 内部文件 > 默认值
Profile：通用 + profile 配置都加载，profile 覆盖通用
业务用 @ConfigurationProperties，少用 @Value
配置中心走 bootstrap.yml / spring.config.import
排查用 /actuator/env

把这些吃透，配置层基本不会再出意外。

我写的 Go 状态机库 go-fsm——设计与实践

Fri, 04 Jul 2025 16:00:00 +0800

写在前面

订单流转、审批流程、设备状态、协议握手、游戏角色——任何"有限状态 + 状态间转移规则"的业务，本质上都是状态机。

写过这种业务的人都知道：

1
2
3
4
5
6
7
8


// 反例：散落的 if-else
func Approve(order *Order) error {
 if order.Status != "pending" {
 return errors.New("only pending order can be approved")
 }
 order.Status = "approved"
 // ... 还有几十处类似的散落转换逻辑
}

状态多了之后——没人能讲清"系统里有多少种合法转换"。这就是把 FSM 当作一等公民的价值——状态、事件、转换规则集中声明，业务代码只触发事件。

我维护的 go-fsm 是一个轻量的 Go 状态机库——零依赖、类型安全、Builder 风格 API。本文介绍它的设计理念、核心 API、典型用法。

一、设计目标

写 go-fsm 之前调研过几个 Go 状态机库——多数有几个共同问题：

状态/事件用 string——拼写错了运行时才发现
API 啰嗦——每个 transition 要好几行
依赖大——拉一个 100KB 库，依赖几十个第三方包
没有 hook——不能在转换前后做副作用

go-fsm 的设计目标：

类型安全：State 和 Event 是自定义类型，编译期就能查错
Fluent Builder：定义状态机像写句子
零依赖：纯标准库
Hooks：转换前/后/失败都能挂钩
并发安全：开箱即用

二、最小可运行例子

 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


package main

import (
 "fmt"
 "github.com/lingcoder/go-fsm"
)

type OrderState string
type OrderEvent string

const (
 StatePending OrderState = "pending"
 StateApproved OrderState = "approved"
 StateRejected OrderState = "rejected"
 StateShipped OrderState = "shipped"

 EventApprove OrderEvent = "approve"
 EventReject OrderEvent = "reject"
 EventShip OrderEvent = "ship"
)

func main() {
 m := fsm.New(StatePending).
 On(EventApprove).From(StatePending).To(StateApproved).
 On(EventReject).From(StatePending).To(StateRejected).
 On(EventShip).From(StateApproved).To(StateShipped).
 Build()

 fmt.Println(m.State()) // pending

 if err := m.Trigger(EventApprove); err != nil {
 fmt.Println(err)
 }
 fmt.Println(m.State()) // approved

 if err := m.Trigger(EventApprove); err != nil {
 fmt.Println(err) // ErrNoTransition: no transition for event...
 }
}

Builder 链式语法让状态机定义读起来像配置文档：

“EventApprove 事件，从 StatePending 到 StateApproved。”

三、Hooks：转换前后做副作用

实际业务中状态切换通常伴随副作用——记日志、发通知、写 DB：

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


m := fsm.New(StatePending).
 On(EventApprove).
 From(StatePending).
 To(StateApproved).
 Before(func(ctx *fsm.Context) error {
 // 转换前校验
 if !canApprove(ctx.Data) {
 return errors.New("not eligible")
 }
 return nil
 }).
 After(func(ctx *fsm.Context) error {
 // 转换后副作用
 sendApprovalNotification(ctx.Data)
 return nil
 }).
 Build()

Before 返回错误 → 转换被中止；After 在状态已经切换后执行——通常用于通知/日志。

全局 Hook

不只针对某个 transition——整个 FSM 也能挂全局 Hook：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


m := fsm.New(StatePending).
 On(EventApprove).From(StatePending).To(StateApproved).
 OnAnyTransition(func(ctx *fsm.Context) error {
 log.Printf("[%s] %s → %s", ctx.Event, ctx.From, ctx.To)
 return nil
 }).
 OnError(func(ctx *fsm.Context, err error) {
 log.Printf("transition failed: %v", err)
 }).
 Build()

全局 Hook 是处理审计日志、metrics、debug 的最佳位置。

四、并发安全

go-fsm 内部用 RWMutex 保护——多 goroutine 调用 Trigger / State 是安全的：

1
2
3
4
5
6
7
8
9


var wg sync.WaitGroup
for i := 0; i < 100; i++ {
 wg.Add(1)
 go func() {
 defer wg.Done()
 m.Trigger(EventApprove) // 并发安全
 }()
}
wg.Wait()

只有一个 goroutine 的 Trigger 能成功（其他被拒绝因为状态已经变了）——这是状态机的天然语义。

五、典型用法：订单状态机

 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


type Order struct {
 ID string
 Amount float64
 State OrderState
}

func NewOrderFSM(order *Order) *fsm.FSM {
 return fsm.New(order.State).
 On(EventPay).From(StatePending).To(StatePaid).
 Before(func(ctx *fsm.Context) error {
 if order.Amount > 100000 {
 return errors.New("require manual review")
 }
 return nil
 }).
 After(func(ctx *fsm.Context) error {
 return paymentService.Confirm(order.ID)
 }).

 On(EventShip).From(StatePaid).To(StateShipped).
 After(func(ctx *fsm.Context) error {
 return logisticsService.CreateOrder(order.ID)
 }).

 On(EventRefund).From(StatePaid).To(StateRefunded).
 On(EventRefund).From(StateShipped).To(StateRefunded).

 On(EventComplete).From(StateShipped).To(StateCompleted).

 OnAnyTransition(func(ctx *fsm.Context) error {
 order.State = ctx.To
 return orderRepo.Save(order)
 }).
 Build()
}

业务里：

1
2
3
4


m := NewOrderFSM(order)
if err := m.Trigger(EventPay); err != nil {
 return err
}

业务代码完全不需要写 if-else 判断状态——状态机自己拦截非法转换。

六、可视化导出

go-fsm 支持导出 DOT 格式——直接喂给 Graphviz 生成状态图：

1
2
3


dot := m.ToDOT()
ioutil.WriteFile("order_fsm.dot", []byte(dot), 0644)
// dot -Tpng order_fsm.dot -o order_fsm.png

生成的图：

flowchart LR
 Pending --> Paid: pay
 Paid --> Shipped: ship
 Paid --> Refunded: refund
 Shipped --> Refunded: refund
 Shipped --> Completed: complete

可视化是状态机维护的核心工具——状态多了之后没图没人能 review。

七、常见使用场景

1. 订单 / 审批流转

经典场景——已经在前文展示过。

2. 协议握手

TCP/TLS/WebSocket 握手过程都是有限状态机：

1
2
3
4
5


fsm.New(StateInit).
 On(EventClientHello).From(StateInit).To(StateServerHello).
 On(EventServerHello).From(StateServerHello).To(StateExchange).
 On(EventExchange).From(StateExchange).To(StateEstablished).
 Build()

3. 设备状态

IoT 设备：online → offline → maintenance → online。

4. 游戏角色

角色状态：idle → walking → running → attacking → dying。

5. 工作流引擎

简单的 BPMN 流程可以用状态机表达——节点是状态，迁移条件是事件。

八、什么时候不该用状态机

虽然状态机是好工具，但不是所有"有状态业务"都该上：

❌ 不适合：

状态简单（只有 2-3 种）——if 就够
状态间无清晰转换规则——状态机反而限制业务
状态由外部驱动且不需要校验——状态机是限制非法转换的工具，不需要限制就没意义

✅ 适合：

状态 ≥ 5 种
转换规则明确
要求"非法转换永远不发生"
多人协作开发同一业务

九、go-fsm 的几个未来方向

go-fsm 是 v0.x 阶段——开源后受到一些反馈，正在演进：

持久化状态：把状态机的当前状态自动同步到 DB
超时转换：状态停留超过 X 秒自动跳到下一个状态
嵌套状态机：复杂业务里子状态机
基于 generics 的强类型——Go 1.18+ 后能做出更类型安全的 API
图形化编辑器：基于 DOT 反向编辑状态机

社区贡献欢迎——github.com/lingcoder/go-fsm。

十、设计反思

写 go-fsm 时学到几个关于"如何设计 Go 库"的事：

API 优先于实现——先想"用户怎么用最爽"，再想内部
零依赖是真正的承诺——拉了一个状态机库就拖一堆传递依赖，是对用户不负责
类型安全是 Go 的礼物——别学其他语言用 string 做枚举
Builder 模式让 API 像 DSL——读起来像句子的代码是好代码
Hooks 优于继承——比起让用户继承基类，提供 callback 更灵活

小结

把 go-fsm 的价值压一句：

业务有 5+ 状态时，状态机不是『过度设计』——它是把『非法转换永远不发生』这件事固化进代码的最佳武器。

go-fsm 的核心三句话：

零依赖——纯标准库
类型安全——State / Event 是你的自定义类型
Builder Fluent——读起来像配置

如果你写 Go 业务系统并且为状态散落 if-else 痛苦过——值得试一下 go-fsm。

1

go get github.com/lingcoder/go-fsm

期待你的 issue / star / PR。

Spring Boot 3 与 Spring 6 的变化与迁移

Tue, 17 Jun 2025 16:00:00 +0800

写在前面

Spring Boot 3.0 / Spring 6.0 在 2022 年 11 月发布，是 Spring 自 Spring 4.0 以来最大的一次跃迁。它不只是版本号 +1——而是整个技术栈的重新对齐：

Java 17 是最低基线——告别 Java 8/11
从 javax 到 jakarta——命名空间彻底切换
GraalVM 原生镜像支持——启动时间从秒级到毫秒级
内置 Observability——Micrometer + OTel
Servlet 6.0 / Jakarta EE 10

本文讲清楚这些变化、为什么这么变、升级要踩什么坑、什么场景该升、什么场景缓一缓。

一、最大的变化：javax → jakarta

这是最容易踩的坑——所有从 javax. 开始的标准库包名都改成了 jakarta.：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Spring Boot 2.x
import javax.servlet.http.HttpServletRequest;
import javax.persistence.Entity;
import javax.validation.constraints.NotNull;
import javax.annotation.Resource;

// Spring Boot 3.x
import jakarta.servlet.http.HttpServletRequest;
import jakarta.persistence.Entity;
import jakarta.validation.constraints.NotNull;
import jakarta.annotation.Resource;

为什么改

Java EE 在 2017 年捐给 Eclipse 基金会成为 Jakarta EE。2019 年 Oracle 正式禁止 Eclipse 在新版本中继续使用 javax.*——所以从 Jakarta EE 9 开始全部改成 jakarta.*。Spring 6 跟着改。

升级痛点

依赖的第三方库要全是 Jakarta 兼容版本——MyBatis、Hibernate、Druid、各种 starter 都要升级
大量 import 要批量替换——IDE 有自动迁移工具，但要 review
老的 javax 库没升级 → 直接编译失败

如果项目里有依赖仍在用 javax——升 Spring Boot 3 之前必须先确认所有依赖都有兼容版本。

二、Java 17 最低基线

Spring Boot 3 强制 Java 17+——告别 Java 8/11。

Java 17 给你的礼物

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


// Records（数据载体）
public record UserDTO(Long id, String name, Integer age) {}

// Sealed classes
public sealed interface Shape permits Circle, Square {}

// Pattern matching for instanceof
if (obj instanceof String s && s.length() > 5) { ... }

// Switch expressions
String result = switch (status) {
 case "A" -> "Active";
 case "I" -> "Inactive";
 default -> "Unknown";
};

// Text blocks（多行字符串）
String json = """
 {
 "name": "test",
 "age": 30
 }
 """;

这些特性早几年就有，但Spring Boot 3 让你必须用 Java 17——团队终于有理由全员升级。

升级痛点

Java 8/11 的 build 脚本要改
某些第三方库（特别是字节码操作类）要升级——CGLIB、ASM、Lombok 等
JVM 参数有变化——某些 Java 8 时代的参数被废除

三、原生镜像：启动速度的革命

Spring Boot 3 内置 GraalVM 原生镜像支持——把 JVM 应用编译成单个原生二进制：

1
2


./mvnw native:compile
./target/myapp # 启动！

性能对比

	标准 JVM	原生镜像
启动时间	5-30 秒	30-100ms
内存占用	200-500 MB	30-80 MB
峰值性能	高（JIT 优化）	中（AOT 编译）
编译时间	秒级	几分钟
镜像体积	JAR + JDK	单二进制

适用场景

Serverless / FaaS——冷启动毫秒级，函数计算成本大降
CLI 工具
K8s 短生命周期 Pod
资源受限环境

不适合

峰值性能敏感——AOT 编译没 JIT 优化空间
大量动态特性（反射、动态代理）——需要额外配置元数据
依赖很多的项目——编译时间长得受不了

GraalVM 是杀手锏但不是银弹——多数业务系统暂时不需要。

四、Observability 一等公民

Spring Boot 3 把可观测性提到了前所未有的高度——内置 Micrometer Observation API：

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


@Bean
public ObservedAspect observedAspect(ObservationRegistry registry) {
 return new ObservedAspect(registry);
}

@Service
public class OrderService {
 @Observed(name = "order.create")
 public Order create(OrderDTO dto) {
 // 自动产生 metrics + traces + logs
 }
}

@Observed 自动产出：

Metrics：Prometheus 抓取
Traces：OpenTelemetry 上报到 Tempo/Jaeger
Logs：结构化日志带 trace_id

统一的 Observability 模型——以前要分别配 Micrometer + Sleuth + 自定义 logger，现在一个注解搞定。

五、HTTP Interface：声明式 HTTP 客户端

Spring 6 引入声明式 HTTP 客户端——类似 Feign 但内置：

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


public interface UserClient {
 @GetExchange("/users/{id}")
 User getById(@PathVariable Long id);

 @PostExchange("/users")
 User create(@RequestBody UserDTO dto);
}

@Bean
public UserClient userClient(WebClient.Builder builder) {
 HttpServiceProxyFactory factory = HttpServiceProxyFactory
 .builderFor(WebClientAdapter.create(builder.baseUrl("https://api.com").build()))
 .build();
 return factory.createClient(UserClient.class);
}

不需要再引 Feign——官方原生支持。

六、Problem Details (RFC 7807)

错误响应标准化——返回 application/problem+json：

1
2
3
4
5
6
7


{
 "type": "https://example.com/probs/insufficient-balance",
 "title": "Insufficient balance",
 "status": 400,
 "detail": "Balance is 100, required 500",
 "instance": "/orders/12345"
}

1
2
3
4
5
6


@ExceptionHandler(InsufficientBalanceException.class)
public ProblemDetail handle(InsufficientBalanceException e) {
 ProblemDetail pd = ProblemDetail.forStatusAndDetail(BAD_REQUEST, e.getMessage());
 pd.setType(URI.create("https://example.com/probs/insufficient-balance"));
 return pd;
}

业内标准——前端能用统一姿势处理。

七、虚拟线程（Spring Boot 3.2+）

JDK 21 GA 了虚拟线程——Spring Boot 3.2+ 一键启用：

1
2
3
4


spring:
 threads:
 virtual:
 enabled: true

效果：

Tomcat 每个请求一个虚拟线程
阻塞 IO 不再占用 OS 线程
传统 MVC 风格代码 + 虚拟线程 = WebFlux 的吞吐

很多人会问"还要不要 WebFlux？"——虚拟线程让传统 MVC 代码用接近 WebFlux 的吞吐量服务高并发，且没学习曲线。WebFlux 的位置开始变窄。

八、其他变化清单

删除 Java 8 / 11 支持
删除 Spring MVC 老的 path matcher（默认走 PathPattern）
新的 PropertyResolver
CRaC（Coordinated Restore at Checkpoint）：JVM 状态快照恢复，再降启动时间
HTTP/2 H2C 支持改进
AOT 编译预处理
更好的 SQL DSL（Spring Data 改进）

九、升级实战清单

评估期

列出所有依赖，确认全部有 Spring Boot 3 / Jakarta 兼容版本
确认 Java 17+ 在所有环境（dev、test、prod、CI）可用
评估 javax → jakarta 替换工作量
检查是否用了将被废弃的 API（如 WebSecurityConfigurerAdapter）

升级期

升 JDK 到 17（独立做，验证业务正常）
批量替换 javax → jakarta（IDE 工具或 OpenRewrite）
升 Spring Boot 3.0 → 3.x 最新版
升所有第三方依赖到 Jakarta 兼容版
修编译错误 + 测试
Spring Security 改为新 SecurityFilterChain 写法
开启 Observability 替换老的 Sleuth

验证期

全量回归测试
性能基准比对（启动时间、内存、QPS）
灰度发布

迁移工具

OpenRewrite：github.com/openrewrite/rewrite-spring 自动改大部分代码
Spring Boot Migrator：官方工具
IntelliJ IDEA：内置 jakarta 替换重构

十、什么场景该升 / 什么场景缓一缓

✅ 应该升

新项目——直接用 3.x，不要从 2.x 起步
JDK 已经在 17+——升级成本最小
想用虚拟线程 / 原生镜像
Spring Boot 2.7 已无 OSS 支持（OSS 支持已于 2023 年 11 月结束，商业扩展支持也已于 2025 年 8 月结束）

⏳ 缓一缓

依赖中有大量未升级的 javax 库
JDK 还卡在 8/11 升不上去
业务系统稳定，没有强需求
团队没人有时间做迁移测试

绝大多数项目应该启动迁移——Spring Boot 2.7 的 OSS 支持已于 2023 年 11 月结束，商业扩展支持也已于 2025 年 8 月结束，再不升就完全没有安全更新了。

十一、Spring Boot 2 → 3 的几个真实坑

1. JPA 用了 `javax.persistence.GenerationType` 等

全局替换 import。

2. Spring Security 配置类

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 2.x
public class SecurityConfig extends WebSecurityConfigurerAdapter {
 @Override
 protected void configure(HttpSecurity http) throws Exception { ... }
}

// 3.x
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 return http...build();
}

WebSecurityConfigurerAdapter 在 3.x 完全删除——所有项目都要重写 Security 配置。

3. SwaggerUI（springdoc-openapi）

要从 1.x 升 2.x——配置完全重写。

4. Spring Cloud 版本对应

Spring Boot 3 不能用 Spring Cloud 2021.0（仍是 javax）。对应关系按 Boot 小版本严格区分：

Spring Boot	Spring Cloud
3.0.x / 3.1.x	2022.0.x（Kilburn）
3.2.x	2023.0.x（Leyton）
3.3.x / 3.4.x	2023.0.x 或 2024.0.x（Moorgate）
3.5.x	2025.0.x（Northfields）

踩坑提醒：跨大版本配错（如 Boot 3.4+ 配 2022.0.x）会出现 starter 缺失、CVE 不修等问题。升 Boot 时务必参照 Spring Cloud Supported Versions 同步升 Cloud。

5. MyBatis-Plus

需要 3.5.3+——更老的版本不兼容 Spring Boot 3。

6. Lombok

要 1.18.24+——老版本可能编译不过。

小结

把全文压一句：

Spring Boot 3 是 Spring 生态进入 Jakarta + Java 17 + 原生镜像 + Observability 时代的入场券——不是小升级，是范式转移。

工程实践：

新项目优先用 3.x
老项目要规划迁移——拖到 2.7 EOL 就被动了
Java 17+ 是基线，不可回避
OpenRewrite 自动迁移省掉 80% 体力活
虚拟线程让传统 MVC 写法逼近 WebFlux 吞吐

升 Spring Boot 3 不是"为了升而升"——是 Java 服务端走向下一个十年的必经之路。

Flutter Web3 Wallet 开发指南

Tue, 20 May 2025 17:48:31 +0800

Flutter Web3 Wallet 开发指南

1. 文档说明

本文档是一份全面的 Flutter Web3 Wallet 开发知识体系与资源整理指南，旨在为团队提供：基础知识体系,标准规范参考,开发资源索引,术语解释。

1.1 目标读者

产品经理：了解技术可行性和实现方案，发现潜在功能需求
技术架构：掌握技术选型和架构设计
开发团队：获取开发资源和实现指南
安全团队：了解安全标准和最佳实践
项目经理：评估开发周期和资源需求
测试团队：了解测试策略和测试工具

1.2 使用指南

知识储备阶段

学习区块链基础
理解钱包技术
掌握安全标准
熟悉开发工具

技术选型阶段

评估技术方案
选择开发框架
确定工具链
制定安全策略

开发准备阶段

搭建开发环境
准备测试网络
配置监控工具
建立安全机制

2. 基础知识

2.1 区块链基础

官方文档
区块浏览

3. 标准提案规范

3.1 钱包相关

通用钱包标准
- BIP-32：分层确定性钱包（HD Wallets）
- BIP-39：助记词生成与恢复
- BIP-44：多币种、多账户HD路径结构
- SLIP-0044：币种编码
- BIP-38：加密私钥的安全增强（可选）
比特币钱包专有标准
- BIP-49: 多网络支持
- BIP-84: Native SegWit 地址
- BIP-85: 确定性熵生成
- BIP-86: Taproot 地址
- BIP-174: PSBT，促进硬件/软件钱包多方签名协作
以太坊钱包专有标准
- EIP-55: 校验和地址格式，用于防止用户输入错误的以太坊地址。
- EIP-137: ENS 域名服务，实现“地址即域名”转账等功能。
- EIP-155: 交易签名重放保护，为多链网络防止交易重放攻击。
- EIP-681: 以太坊 URI 支付请求标准，便于钱包扫码或链接转账请求。
- EIP-712: 结构化数据签名，钱包常用于DApp登录、合约操作等。
- EIP-1193: Provider API 标准，dApp与钱包之间通信通用接口。
- EIP-1271: 合约钱包签名验证标准，为智能合约账户带来签名验证。
- EIP-2255: 钱包权限管理，提升钱包对外接口权限的细粒度管理。
- EIP-2335: BLS12-381 Keystore，专用于以太坊 2.0（信标链）validator 的 BLS 私钥加密存储；普通 EOA 钱包使用的是 Web3 Secret Storage（业内俗称 Keystore V3）。
- EIP-2612: ERC20 代币 Permit 功能，钱包可通过授权签名直接操作approve功能，提升用户体验。
- EIP-3085: 钱包网络切换请求，便于dApp添加/切换自定义网络到钱包。
- EIP-4337: 账户抽象（Account Abstraction），智能合约钱包的关键协议。
- EIP-4361: 使用以太坊地址签名认证（Sign-In With Ethereum）。
- EIP-5805: 投票与委托标准（治理代币的链上投票/委托接口，与钱包安全无关）。
- EIP-6963: 多钱包发现和选择，提升多钱包生态用户体验。
索拉纳钱包专有标准
- Ed25519: Solana 钱包采用的公私钥加密算法
- Solana Wallet Standard: 钱包与 DApp 连接与兼容协议
- Solana Pay: 原生扫码/支付请求协议
- Solana Address/Account Model：账户结构及模型
波场钱包专有标准
- Tron Multi-signature：多签账户功能

3.2 比特币生态标准

交易与协议扩展
- BIP-2/BIP-9: BIP规范流程/软分叉激活讨论
- BIP-21: 比特币支付URI统一收款标准
- BIP-47: 支付代码（静默支付/隐私增强）
- BIP-65: OP_CHECKLOCKTIMEVERIFY时锁
- BIP-70: 支付请求协议
- BIP-174: PSBT部分签名交易格式
- BIP-340/341/342: Taproot/Schnorr签名/可扩展性升级
地址与账号模型
- BIP-13: 多重签名P2SH地址
- BIP-170: 长度检查/二维码兼容
隐私与效率
- BIP-78: PayJoin隐私增强支付
- BIP-155: 节点通讯结构扩展
- BIP-157/158: 轻钱包同步（Neutrino）
扩展与第三方协议
- Lightning Network: 闪电网络高效链下转账
- Open Assets: 比特币链上非标准资产发行
- Colored Coins: 彩色币-layer2资产协议

3.3 以太坊生态标准

资产与合约标准
- EIP-20: 可替代代币（ERC-20）
- EIP-721: NFT非同质化代币
- EIP-1155: 多代币/混合资产标准
- EIP-4626: Vault资产保险库
功能和扩展标准
- EIP-2612: 代币无Gas批量操作（Permit）
- EIP-4337: 账户抽象(AA)
- EIP-2930: 可选访问列表
- EIP-3607: 拒绝合约代码地址签发的交易（防止账户抽象前的地址冲突安全风险）
- EIP-2535: Diamond多合约分片架构
- EIP-712: 结构化签名
治理与基础设施
- EIP-1967: Proxy可升级合约标准
- EIP-4824: DAO组织元数据标准
- EIP-173: 合约所有权控制

3.4 索拉纳生态标准

代币与资产标准
- SPL Token: 基础代币标准（SPL Token Program）
- SPL Associated Token Account: 关联Token账户
- SPL Token Metadata: 元数据/NFT扩展
- SPL Token Swap: 代币兑换池
- Metaplex NFT: NFT铸造/交易标准
功能与交互标准
- SPL Name Service: 域名服务
- SPL Governance: 治理/DAO标准
- SPL Stake: 质押参与规则
- SPL Token Lending: 借贷协议标准
- SPL Memo: 转账备注消息标准

3.5 波场生态标准

资产与NFT标准
- TRC-10: 基础资产发行标准
- TRC-20: ERC-20兼容合约资产
- TRC-721: NFT资产发行协议
- TRC-1155: 多代币协议
- TRC-30: 资产元数据、扩展协议
核心资源与功能
- 带宽模型: 交易带宽资源分配
- 能量模型: 智能合约执行资源管理
- 资源委托: 资源托管代理
- 资源交易: 市场化资源换取机制
治理体系标准
- TRC-51: 提案投票制度
- TRC-54: 参数治理配置
- 链上治理: 链上治理机制
- 社区治理: 社区/开发者治理规则

3.6 安全最佳实践（跨生态）

Ethereum Smart Contract Best Practices（ConsenSys，事实标准）
Solana Security Best Practices
SWC Registry：Smart Contract Weakness Classification（合约漏洞分类与缓解）

4. 竞品分析

4.1 主流钱包分析

EVM 生态

MetaMask
- 核心功能
  - SDK: SDK 使用
  - Snap 系统: 插件系统，支持自定义功能扩展
  - 钱包服务: 钱包服务 API
  - 钱包API: 通用钱包 API
- 技术实现
  - 移动端源码: React Native 实现
  - 核心库: 状态管理和业务逻辑
  - Keyring 系统: 密钥管理实现
Trust Wallet
- 核心功能
  - 多链支持: 支持 60+ 区块链
  - DApp 浏览器: 内置浏览器
  - 代币管理: 代币添加和管理
- 技术实现
  - 钱包核心库: C++ 实现的核心库
  - Android实现: Android 实现
  - iOS实现: Swift 实现
  - 区块链适配器: 链适配器实现
Rainbow
- 核心功能
  - 官网: 官方网站
- 技术实现
  - 源码: 完整源码

Solana 生态

Phantom
- 核心功能
  - 官方文档: 官方文档
  - 交易处理: 交易处理
Solflare
- 核心功能
  - 官方文档: 官方文档
  - 钱包SDK: DApp 集成

TRON 生态

TronLink
- 官方网站: 官方网站
- 官方文档: 完整源码
TokenPocket
- 官方网站: 官方网站
- 官方文档: 官方文档
- TokenPocket-Protocol: 该协议可以用于从网页和第三方App拉起TokenPocket钱包做授权转账等操作

Bitcoin 生态

BlueWallet
官方网站: 官方网站
官方文档: 官方文档
完整源码: 完整源码
Samourai Wallet
官方网站: 官方网站
官方文档: 官方文档
完整源码: 完整源码

4.2 钱包集成框架

WalletConnect

核心功能
- 协议规范: 协议技术规范
- 会话管理: 连接会话管理
- 消息中继: 消息中继机制
- 推送通知: 消息推送服务
开发工具
- Flutter SDK: Flutter 开发工具包
- 示例代码: 集成示例
- 测试工具: 测试和调试工具
- 监控服务: 监控和分析
云服务
- 推送服务: 交易和消息推送
- 中继服务: 消息中继和同步
- 分析服务: 使用数据分析
- 管理控制台: 服务管理平台

DeepLink

iOS: iOS DeepLink
Android: Android DeepLink

5. 开发资源

5.1 Flutter 开发资源

核心框架

Flutter 框架
- 官方文档: 完整的开发文档和指南
- 性能优化: 性能调优和最佳实践
- 状态管理: 状态管理方案
- 平台集成: 平台特定功能
开发工具
- Flutter CLI: 命令行工具
- DevTools: 调试和性能分析
- VS Code 插件: VS Code 开发环境
- Android Studio 插件: Android Studio 开发环境
测试工具
- 单元测试: 测试框架和工具
- Widget 测试: UI 组件测试
- 集成测试: 端到端测试
- 性能测试: 性能基准测试

5.2 开发工具与库

Flutter 核心包

状态管理
- riverpod: 现代化状态管理方案
- get_it: 依赖注入容器
- flutter_bloc: BLoC 模式实现
- mobx: 响应式状态管理
网络与存储
- dio: 强大的 HTTP 客户端
- shared_preferences: 本地数据存储
- hive: 轻量级键值数据库
- sqflite: SQLite 数据库
安全存储
- flutter_secure_storage: 安全数据存储
- flutter_secure_storage_macos: macOS 安全存储
- flutter_secure_storage_web: Web 安全存储
- flutter_keychain: 钥匙串访问
系统交互
- path_provider: 文件路径管理
- connectivity_plus: 网络连接状态
- package_info_plus: 应用包信息
- device_info_plus: 设备信息

UI 组件

基础组件
- flutter_svg: SVG 图片支持
- cached_network_image: 图片缓存
- flutter_animate: 动画效果
- lottie: Lottie 动画支持
交互组件
- mobile_scanner: 二维码扫描
- flutter_slidable: 滑动操作
- flutter_screenutil: 屏幕适配
- google_fonts: Google 字体
反馈组件
- flutter_easyloading: 加载提示
- fluttertoast: Toast 提示
- flutter_switch: 开关组件
- flutter_spinkit: 加载动画

Web3 开发包

⚠️ pub.dev 上 Web3 相关包名变化频繁——下面只列出 2025 年仍在维护、可在 pub.dev 上确实存在的包。WalletConnect v2 在 Flutter 生态实际上由 Reown（前 WalletConnect 团队）维护，是当前主流入口。

以太坊开发
- web3dart: 以太坊开发核心库（事实标准）
- wallet_core_bindings: Trust Wallet Core 绑定
WalletConnect / Reown（钱包连接）
- reown_appkit: Reown AppKit（dApp 端钱包连接 + UI）
- reown_walletkit: Reown WalletKit（钱包端集成 WalletConnect v2）
- reown_core: Reown 协议核心
- walletconnect_flutter_v2: 旧版 WalletConnect v2 包（已被 reown_* 取代，新项目用 reown）
链适配器
- solana / solana_web3: Solana 开发库
- TRON / Bitcoin 在 pub.dev 上没有事实上的主流 Dart SDK，常见做法是通过节点 RPC + 自实现签名（参考 bip32 + pointycastle），或通过 flutter_rust_bridge / wallet_core_bindings 复用 Rust/C++ 实现

安全与加密

密钥管理
- bip39: 助记词生成
- bip32: 分层确定性钱包
- ed25519_hd_key: Ed25519 密钥派生
- crypto: 加密算法
生物认证 / 安全存储
- local_auth: 生物认证（指纹 / 面容，官方包，事实标准）
- flutter_secure_storage: 平台 keychain / keystore 安全存储（钱包密钥、助记词推荐用这个）
- biometric_storage: 生物识别保护下的安全存储

测试与质量

测试框架
- flutter_test: 单元测试框架
- mockito: 模拟测试
- flutter_driver: 端到端测试
- integration_test: 集成测试
代码质量
- analyzer: Dart 静态分析（官方）
- very_good_analysis: 严格 lint 规则集
- flutter_lints: Flutter 官方推荐 lint 规则
- dart_code_metrics: 代码度量与高级 lint
- coverage: 测试覆盖率

调试与开发

开发工具
- logger: 日志记录
- flutter_logs: 日志管理
- flutter_dotenv: 环境变量
- flutter_config: 配置管理
代码生成
- build_runner: 代码生成工具
- freezed: 不可变数据类生成
- json_serializable: JSON 序列化
- json_annotation: JSON 注解
应用配置
- flutter_native_splash: 启动屏
- flutter_launcher_icons: 应用图标
- flutter_isolate: 隔离执行
- url_launcher: URL 处理

5.3 节点与 API 服务

EVM 链服务

节点服务
- Infura: 以太坊节点服务
- Alchemy: 高级 API 服务
- QuickNode: 全球节点网络
- Chainstack: 企业级节点服务
API 服务
- Etherscan API: 区块浏览器 API
- Covalent API: 多链数据 API
- The Graph: 链上数据索引
- Moralis: Web3 开发平台

Solana 服务

节点服务
- Helius: 高性能 RPC 服务
- Alchemy Solana: Solana API
- QuickNode Solana: Solana 节点
- GenesysGo: 企业级节点服务
API 服务
- Solana Explorer API: 区块浏览器 API
- Solana FM API: 高级数据 API
- DAS API: 数字资产 API
- Jupiter API: DEX 聚合器 API

其他链服务

TRON 服务
- TronGrid: TRON 节点服务
- TRON API: TRON 开发 API
- TRON Explorer API: 区块浏览器 API
- TRON Network API: 网络数据 API
Bitcoin 服务
- Mempool: 内存池服务
- BlockCypher: 比特币 API

6. 钱包工程相关术语

通用区块链概念（区块链、共识机制、智能合约、DeFi、NFT、Layer2、分片等）这里不再罗列——可以参考各家公开的术语表。本节只保留与 Flutter 钱包工程直接相关的术语，其他都假定读者已经熟悉。

6.1 钱包形态

名词	一句话解释
热钱包 / 冷钱包	是否在线持有私钥（在线 = 热，离线 = 冷）
托管钱包 / 非托管钱包	私钥在第三方手里 vs 在用户手里
HD 钱包（BIP-32）	单一种子派生多账户、多链、多地址的钱包
多签钱包	需要 N 把私钥中的 M 把签名才能花费
智能合约钱包（AA）	账户由合约控制，可自定义验签、社交恢复、付 gas 等
Watch-only 钱包	只看余额、不签名（导入公钥/地址即可）

6.2 密钥与派生

名词	一句话解释
私钥 / 公钥	椭圆曲线密钥对，公钥派生地址、私钥用于签名
助记词（BIP-39）	12/24 个单词组成的可读种子，能恢复整个 HD 钱包
派生路径（BIP-44）	`m/44'/60'/0'/0/0` 这样的 HD 派生层级，每条链有自己 coin type
Keystore（V3）	Web3 Secret Storage——加密保存私钥的 JSON 文件
硬件钱包接入	Ledger / Trezor 通过 USB / BLE 暴露签名接口，私钥永不离开设备

6.3 签名与连接

名词	一句话解释
EIP-191	以太坊原始签名格式（`personal_sign`）
EIP-712	结构化数据签名，钱包能给用户展示可读的待签内容
EIP-1271	合约钱包的签名验证标准（合约自己说"这签名我认"）
Sign-In With Ethereum（EIP-4361）	用钱包签名做去中心化登录
WalletConnect / Reown	dApp 与钱包之间的跨设备通信协议
EIP-1193	dApp 向钱包要 provider 的统一接口

6.4 移动端工程关注

名词	一句话解释
Secure Enclave / Keystore	iOS / Android 平台级安全芯片，存私钥的最佳归宿
生物识别	指纹 / 面容触发签名，私钥不直接暴露给应用层
深链接（Deep Link）	dApp ↔ 钱包跳转，处理"扫码 → 唤起钱包 → 签完返回"的链路
Push 通知	WalletConnect 离线时通过 Push 唤醒钱包接收新签名请求

Lua 速通——核心语法与特性

Tue, 22 Apr 2025 15:00:00 +0800

写在前面

Lua 是一门有意保持小巧的脚本语言——核心语法只有几十条规则，标准库非常精简，参考实现的解释器只有约 2.4 万行 C 代码（含标准库），编译后产物约 250 KB。

但它表达力并不弱：first-class function、metatable、协程、模式匹配——很多被现代语言陆续吸收的特性，Lua 早就有。

本文给一份偏语言本身的速通——讲清楚 Lua 的核心语法、表、面向对象的实现方式、协程，以及一些容易踩的语法陷阱。读完之后你能看懂多数 Lua 代码，也能写出一些不丢人的 Lua。

一、最基本的语法

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


-- 注释从两个减号开始
print("Hello, world!")

-- 变量（默认全局）
x = 10
local y = 20 -- local 是局部，强烈推荐永远用 local

-- 字符串
local name = "Lua"
print("Hi, " .. name) -- 字符串拼接用 ..
print(#name) -- # 取长度

-- 数字
local a = 1.5
local b = 2

-- nil（不存在/未定义）
local nothing = nil

-- 布尔（注意：只有 false 和 nil 是 falsy，0 是 truthy！）
if 0 then print("0 是 truthy") end -- 会执行

⚠️ 几个和主流语言不一样的地方：

nil 不是 null——访问不存在的字段返回 nil
0 是真值！这和大多数语言相反
字符串拼接用 ..，不是 +
取长度用 #str，不是 len(str)

二、控制流

 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


-- if
if x > 10 then
 print("big")
elseif x > 5 then
 print("medium")
else
 print("small")
end

-- while
while x > 0 do
 x = x - 1
end

-- repeat-until（条件为 true 时退出）
repeat
 x = x + 1
until x > 100

-- for（数值型）
for i = 1, 10 do print(i) end -- 1 到 10
for i = 1, 10, 2 do print(i) end -- 步长 2
for i = 10, 1, -1 do print(i) end -- 倒序

-- for（迭代器）
for k, v in pairs(table) do print(k, v) end
for i, v in ipairs(array) do print(i, v) end

注意——for 没有 ++ --，循环结束用 end。

三、函数

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


function add(a, b)
 return a + b
end

-- 多返回值（Lua 一大特色）
function divmod(a, b)
 return a / b, a % b
end
local q, r = divmod(7, 2)

-- 可变参数
function printAll(...)
 local args = {...}
 for i, v in ipairs(args) do print(i, v) end
end

-- 匿名函数 + 局部变量
local sayHello = function(name)
 print("Hello, " .. name)
end
sayHello("World")

函数是 first-class value——可以传递、返回、存进表，闭包语义和 JS / Python 类似。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


function counter()
 local n = 0
 return function()
 n = n + 1
 return n
 end
end

local next = counter()
print(next()) -- 1
print(next()) -- 2

四、Table——Lua 唯一的数据结构

Lua 的核心是 table——既是数组、又是字典、又是对象——一个数据结构表达所有：

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


-- 数组式
local arr = {10, 20, 30}
print(arr[1]) -- 10（注意从 1 开始！）
print(#arr) -- 3

-- 字典式
local user = { name = "alice", age = 30 }
print(user.name)
print(user["name"])

-- 混合
local mixed = { "a", "b", "c", color = "red" }

⚠️ Lua 的数组从 1 开始！ 不是 0。这是和 99% 主流语言的不同——也是新手最容易踩的坑。

表的常用操作

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


table.insert(arr, 40) -- 末尾追加
table.remove(arr, 1) -- 移除第 1 个
table.concat(arr, ", ") -- 拼成字符串
table.sort(arr) -- 排序

-- 字典遍历
for k, v in pairs(user) do
 print(k, v)
end

-- 数组遍历
for i, v in ipairs(arr) do
 print(i, v)
end

pairs 遍历所有键值对（包括字符串 key）；ipairs 只遍历数字索引 1, 2, 3…——遇到 nil 停止。

五、字符串与模式匹配

字符串是 Lua 里仅次于 table 的常用类型，标准库里有不少利器：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


local s = "Hello, Lua!"

print(#s) -- 11
print(string.upper(s)) -- HELLO, LUA!
print(string.sub(s, 8, 10)) -- Lua
print(string.rep("ab", 3)) -- ababab

-- 也可以用 OO 调用
print(s:upper())
print(s:find("Lua")) -- 8 10

模式匹配

Lua 没有正则，但有自己的轻量"模式"语法：

1
2
3
4
5
6


local date = "2025-04-22"
local y, m, d = string.match(date, "(%d+)-(%d+)-(%d+)")
print(y, m, d) -- 2025 04 22

-- 替换
print(string.gsub("hello world", "world", "Lua")) -- hello Lua 1

%d 数字、%a 字母、%w 字母数字、%s 空白——和 PCRE 不完全一样但够用，性能也好。

六、Metatable 与面向对象

Lua 没有 class，但 metatable 几乎能模拟出任何 OO 特性：

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


local Animal = {}
Animal.__index = Animal

function Animal.new(name)
 local self = setmetatable({}, Animal)
 self.name = name
 return self
end

function Animal:eat() -- 注意冒号 :
 print(self.name .. " is eating")
end

local dog = Animal.new("Rex")
dog:eat() -- 调用也用冒号

冒号 : 是语法糖——obj:method() 等价于 obj.method(obj)，自动传 self。

元方法（metamethods）

metatable 里几个特殊键名能"重载"运算符：

1
2
3
4
5
6
7
8


local Vec = {}
Vec.__index = Vec
Vec.__add = function(a, b) return setmetatable({x = a.x + b.x, y = a.y + b.y}, Vec) end
Vec.__tostring = function(v) return "(" .. v.x .. ", " .. v.y .. ")" end

local v1 = setmetatable({x = 1, y = 2}, Vec)
local v2 = setmetatable({x = 3, y = 4}, Vec)
print(v1 + v2) -- (4, 6)

常用元方法：__index / __newindex / __add / __sub / __mul / __eq / __lt / __tostring / __call。

继承

1
2
3
4
5


local Dog = setmetatable({}, {__index = Animal})

function Dog:bark()
 print(self.name .. ": woof!")
end

子类查找方法时，自身没有就沿 __index 一路向上找——这就是 Lua 的"原型继承"。

七、协程（coroutine）

协程是 Lua 一个常被忽略的强项——轻量级、对称式协程，比线程便宜得多：

1
2
3
4
5
6
7
8
9


local co = coroutine.create(function(a, b)
 print("start: " .. a .. ", " .. b)
 local c = coroutine.yield(a + b)
 print("resumed with: " .. c)
 return "done"
end)

print(coroutine.resume(co, 1, 2)) -- start: 1, 2 \n true 3
print(coroutine.resume(co, 99)) -- resumed with: 99 \n true done

yield 把控制权还给调用者并把值传出去；resume 重新激活协程并把值传进去。

协程能用来写生成器：

1
2
3
4
5
6
7
8
9


local function range(from, to)
 return coroutine.wrap(function()
 for i = from, to do
 coroutine.yield(i)
 end
 end)
end

for v in range(1, 5) do print(v) end -- 1 2 3 4 5

coroutine.wrap 是 create + resume 的简化包装。

八、模块化

1
2
3
4
5
6
7
8


-- mylib.lua
local M = {}

function M.greet(name)
 return "Hello, " .. name
end

return M

1
2
3


-- main.lua
local lib = require("mylib")
print(lib.greet("World"))

require 自动从 package.path 里找 .lua 文件，结果会被缓存——同一个模块多次 require 只加载一次。

九、几个常踩的语法陷阱

1. 数组从 1 开始

1
2
3


local a = {10, 20, 30}
print(a[0]) -- nil（不是 10！）
print(a[1]) -- 10

2. nil 不能放在数组中间

1
2
3


local a = {1, 2, nil, 4}
print(#a) -- 不一定是 4，可能是 2
for i,v in ipairs(a) do print(v) end -- 只打到 2

ipairs 遇 nil 停——这种 sparse array 在 Lua 里要特别小心。

3. 0 和 "" 是 truthy

1
2
3
4


if 0 then print("yes") end -- yes
if "" then print("yes") end -- yes
if nil then print("yes") end -- 不打印
if false then print("yes") end -- 不打印

只有 false 和 nil 是 falsy。

4. 字符串与数字自动转换

1
2


local x = "10" + 5 -- 15（字符串自动转数字）
local y = 10 .. "abc" -- "10abc"

便利但容易隐藏 bug——关键代码显式 tonumber() / tostring()。

5. 默认全局

1
2
3
4


function foo()
 x = 10 -- 这是全局变量！
 local y = 20 -- 这才是局部
end

永远写 local——否则一不小心污染全局。

6. 整数与浮点（5.3+）

Lua 5.3 引入了原生 integer 类型，整数除法用 //：

1
2


print(7 / 2) -- 3.5（浮点）
print(7 // 2) -- 3 （整除）

5.3 之前所有数字都是 double——老脚本升到 5.3 时除法行为可能微妙改变。

十、Lua 的设计哲学

了解一下 Lua 之所以这么设计的几条核心原则：

极简正交：核心特性极少，但每条都正交，能组合出强大能力
机制不策略：metatable 是机制，怎么实现 OO / 继承 / 运算符重载都是策略
数据结构唯一性：只用 table 表达所有复合数据
首类函数 + 闭包：函数式编程的基本元素都齐了

正是这种克制让 Lua 能在两万多行 C 代码里塞下一门完整的语言——也让它的标准库相对寒酸（“麻雀虽小五脏不全”），需要用 luarocks 或 LuaJIT 的 ffi 补足。

十一、Lua 版本与 LuaJIT

Lua 5.x 版本演进

5.1：经典版，使用面最广
5.2：引入 goto、bit32 库
5.3：引入原生 integer 类型、整除 //、原生位运算符 & | ~ << >>（bit32 库被废弃）
5.4：generational GC、<const> 与 <close> 属性

5.1 → 5.4 不完全兼容——升级时要核对每条变化。

LuaJIT

LuaJIT 是 Lua 的 JIT 编译器实现——比标准 Lua 快 5-10 倍，性能直逼 C。它的 ffi 库还能直接调用 C 函数，扩展能力极强。

不过 LuaJIT 主要兼容 5.1 + 部分 5.2 特性——和 5.3 / 5.4 的 integer 等新特性不兼容。

包管理

luarocks 是事实标准——类似 npm/pip。

十二、什么场景该用 Lua

✅ 适合

轻量脚本：启动快、依赖少，比 Python 启动几十倍快
DSL / 配置：用作业务规则、配置文件的承载语言
作为宿主程序的扩展层：被嵌入到其他程序里执行业务逻辑（这是它历史上最常见的用法之一）
性能敏感的脚本：LuaJIT 性能接近 C

❌ 不适合

独立大型应用：标准库薄，生态远不如 Python / Node
复杂业务系统：OO 弱、错误处理粗糙
数据科学：没有 NumPy / Pandas 之类生态

小结

把全文压一句：

**Lua 是一门用很少的概念表达很多能力的小语言——核心是 table 与 first-class function，加上 metatable 和协程，几乎能覆盖任何脚本场景。 **

记住几个关键点：

数组从 1 开始
local 永远要写
nil 和 false 才是 falsy
字符串拼接用 ..
table 是唯一复合数据结构
metatable 是 Lua OO 与运算符重载的统一机制
协程是它被低估的强项

掌握了这些，你已经可以读懂 95% 的 Lua 代码，并写出符合语言风格的脚本。

Spring Cloud 微服务之间如何避免循环依赖

Thu, 11 Apr 2024 16:00:00 +0800

一个隐性而致命的问题

微服务团队成长到一定规模后，几乎都会遇到服务之间的循环依赖：

1

订单服务 → 用户服务 → 订单服务

朴素的解决思路：“只是调用关系而已，能跑就行”——但这种循环会带来一系列问题：

启动顺序混乱：A 启动时要连 B 的健康检查，B 启动时要连 A 的——谁先启动？
故障爆炸式扩散：A 挂 → B 挂 → A 挂——单点故障变成集群故障
测试灾难：要起 A 必须先起 B、起 B 必须先起 A
架构腐化：循环让"职责边界"完全消失——任何修改都要全链条考虑
死锁/雪崩风险：链路超时、回调嵌套、连接池耗尽
重构寸步难行：想拆分服务时所有循环都拦着

循环依赖不是技术问题，是架构问题。本文从识别、分析、解决三个层面讲清楚。

一、循环依赖的几种典型形态

1. 直接循环（A ↔ B）

flowchart LR
 A[订单服务] -->|查用户信息| B[用户服务]
 B -->|查用户最近订单| A

最常见的——双方都要对方的数据。

2. 间接循环（A → B → C → A）

flowchart LR
 A[订单服务] --> B[支付服务]
 B --> C[风控服务]
 C --> A

链路一长就难发现——往往是新增功能时引入的。

3. 通过事件的"软循环"

flowchart LR
 A[订单] -->|OrderCreated 事件| MQ
 MQ --> B[积分服务]
 B -->|RPC 查订单状态| A

虽然是异步，但积分服务回头查订单服务——本质上还是循环。

4. 启动期循环

A 启动时要从 B 拉某个全局配置，B 启动时也要从 A 拉某个配置——启动期死锁。

二、为什么循环依赖会出现

业务视角看是"一不小心引入"——但本质原因通常是：

1. 实体边界没分清

订单和用户都是核心实体——从用户视角"查我的订单"、从订单视角"查谁下的单"——两个视角看起来都合理，于是双向都建了 RPC。

2. 共享数据没有归属

“用户最近一笔订单”——这个数据算用户属性还是订单属性？没人 say 清楚归谁，最后就两边都查。

3. 微服务过细

把"用户登录"和"用户资料"拆成两个服务——结果它们成天互相调用。过度拆分是循环的温床。

4. 业务驱动反向调用

最常见的——“产品要订单详情页面也展示用户头像”：

1

订单服务（主）→ 用户服务 ✓ 正常依赖

下一个版本，“用户主页要展示最近订单”：

1

用户服务（主）→ 订单服务 ❌ 反向依赖来了

业务一推动就改，没人检查依赖图——循环就此诞生。

三、识别：怎么发现循环

1. 静态扫描

整理所有服务间的 OpenFeign / RestTemplate 调用：

1

grep -r "@FeignClient" --include="*.java"

输出每个服务依赖哪些服务，画个有向图——用 Graphviz 或简单的脚本。

2. 链路追踪

SkyWalking / Zipkin / Jaeger 在生产里聚合调用拓扑——自动看到 A 调 B、B 调 A。

3. 服务注册中心

Nacos / Consul 看每个服务的调用方列表——能看到反向依赖。

4. 在 CI 加检查

1
2
3


# 每次 PR 检查依赖图，新增反向调用直接 fail
- name: Check service dependencies
 run: ./scripts/check-deps.sh

把检查变成机制——比每次 review 时人工排查靠谱。

四、解决方案

方案 1：合并服务（最直接）

如果 A 和 B 长期互相调用——它们可能就该是一个服务。微服务不是越细越好——业务边界不清的两个服务合并回去是合理的。

判断标准：

数据强一致需求
改动通常一起来
链路上 80% 都是双向调用

方案 2：抽出共享层

A 和 B 都依赖某段共享逻辑/数据——抽到 C：

1
2


重构前：A ↔ B
重构后：A → C ← B

例如"用户基础信息"抽到 user-base 服务——A 和 B 都查 C，互不依赖。

方案 3：事件驱动 + 数据冗余

最优雅但工程量大——A 改了数据后发事件，B 订阅事件维护自己一份冗余：

flowchart LR
 A -->|UserUpdated 事件| MQ
 MQ --> B[B 维护用户冗余表]
 User --> B
 B -.无需调 A.-> B

B 不再实时调 A 取数据——读自己的本地冗余。代价是数据有微小延迟，但循环彻底消除。

方案 4：依赖反转

A 调 B 是为了"通知 B 一件事"——改成 B 主动监听：

1
2


重构前：A → B（通知 B 用户状态变化）
重构后：A 发事件 → B 订阅

依赖方向倒过来——A 不再依赖 B。

方案 5：API Gateway / BFF 聚合

页面需要 A + B 的数据——不应该让 B 调 A，应该让 BFF（Backend For Frontend）调 A 和 B 聚合：

flowchart LR
 Frontend --> BFF
 BFF --> A
 BFF --> B

A 和 B 的依赖被 BFF 拆开——它们之间不再相互依赖。

方案 6：批量查询代替单次

如果 B 调 A 是为了"批量查 1000 个用户的订单"——让 A 提供批量接口，B 拿到 ID 列表后批量请求一次：

1
2


之前：B 循环 1000 次调 A
之后：B 一次性发 1000 个 ID 给 A

调用次数大幅降低 → 即使保留依赖，影响也小。

五、典型场景的具体解法

场景 1：订单展示要用户头像，用户主页要展示订单数

重构前	重构后
订单服务 ↔ 用户服务（互相调用）	BFF 聚合：BFF → 订单服务、BFF → 用户服务
	订单服务里冗余存 user_name + avatar_url

场景 2：积分服务通过事件加积分，但要查订单金额

重构前	重构后
订单 → 发事件 → 积分 → RPC 查订单	订单发事件时事件载荷里就带金额

场景 3：风控决策要查多个上下文

重构前	重构后
风控服务 ↔ 订单 ↔ 用户 ↔ 风控	调用方主动把上下文打包传给风控

六、架构层面的纪律

1. 严格的"上下游"层级

把服务分层——只允许上层调下层，下层永不调上层：

flowchart TD
 BFF[BFF / API 层]
 BFF --> Domain[业务领域服务]
 Domain --> Foundation[基础服务
用户/账户/支付]
 Foundation --> Infra[基础设施
消息/存储/索引]

任何"下层调上层"PR 直接 reject。

2. 共享数据归属唯一

每个数据的"主人"只有一个服务——其他服务要用，要么调主人，要么订阅事件维护冗余。

3. 增量加 PR 时强制依赖检查

1
2
3


# 检查是否引入新的 cross-tier 依赖
- name: Check architecture
 run: archunit-test

ArchUnit 这种工具能在测试里强制架构规则——机制保证大于人为约束。

4. 定期审视依赖图

每个迭代结束 review 一次依赖图——发现"上次没有的反向依赖"立刻处理。

七、Spring Cloud 特有的注意点

1. OpenFeign 自调本服务的隐患

服务内部代码注入指向"本服务名"的 FeignClient：

1
2
3
4
5
6
7
8


@FeignClient(name = "user-service")
public interface UserClient { ... }

// 用户服务里
@Service
class UserService {
 @Autowired private UserClient userClient; // 指向本服务
}

这种用法不会立刻报错——Feign 通过注册中心负载均衡转发，请求会落到本服务的某个实例（可能是自己也可能是同名其他实例）。但它是个反模式：

普通自调虽不立刻失败，但会绕一跳网络、多一段 trace、丢失本地事务上下文
若调用链最终回到调用方所在的同一个接口（A 通过 LB 调到 A 自己，又走相同方法），就会形成无限递归 → 栈溢出 / 连接池耗尽
调用链路在 trace 里突然多一段，排查困难

结论：本服务的内部能力直接走 Bean 调用，不要通过 FeignClient 绕一圈。要复用接口契约可以把 Client 接口和 Controller 实现拆出 SPI 模块共享。

2. Eureka / Nacos 服务发现的循环

A 启动时连不上 B，B 启动时连不上 A——注册中心会等到双方都活着才允许调用。但如果配置了"启动期健康检查"，就会双方互等。

解决：启动期检查只用基础设施（DB、Redis），不要互相检查。

3. 配置中心的循环

A 服务启动时要从配置中心拉 B 的地址——但配置中心要先注册到 A 才能正常工作？这种设计是错的。配置中心应该是最底层无依赖的服务。

八、一份"循环依赖"治理清单

发现循环后按这个流程处理：

明确循环类型——直接 / 间接 / 软 / 启动期
画出当前依赖图
判断业务边界——是不是该合并服务？
如果不合并——选方案：抽共享层 / 事件 + 冗余 / 依赖反转 / BFF
设计冗余数据的同步机制——保证最终一致
测试覆盖——确保循环消除后业务不退化
加 ArchUnit 检查防止回退

九、一些反例

反例 1：为了"性能"双向冗余

A 存 B 的数据、B 存 A 的数据——两边都要同步对方的变化。最终变成"两个真相"——数据不一致。冗余应该单向。

反例 2：用 MQ 假装解耦

1
2


A → MQ → B
B → MQ → A

虽然走 MQ 不直接调用，但本质还是循环——只是把同步等待换成异步等待。问题没解决。

反例 3：用注释"承认循环"

1
2


// TODO: 这里是循环依赖，暂时无法避免
@Autowired private UserClient userClient;

写注释承认问题等于不解决——技术债越堆越多。循环依赖应作为架构债务专项跟踪，原则上不允许长期存在。

小结

把全文压一句：

服务间循环依赖不是『可以容忍的小毛病』——它是架构腐化的早期信号，会慢慢腐蚀整个系统。发现一个解决一个。

工程纪律：

服务分层，禁止上下层逆向调
数据归属唯一，跨域用事件 + 冗余
共享逻辑下沉到独立服务
页面聚合走 BFF
CI 自动检查，不靠人工
循环依赖出现立刻处理，不容忍

把这套做对，微服务才能真正"独立、可演进、可扩展"——而不是变成"分布式单体"。

Go 程序中 context 的职责与边界

Mon, 26 Feb 2024 15:30:00 +0800

写在前面

每个 Go 函数签名里都见过它：

1

func (s *Service) GetUser(ctx context.Context, id int64) (*User, error)

ctx 是什么？做什么用的？很多新人对这个第一参数的认知止步于"传超时和取消信号"——但 context 在 Go 里的角色远不止于此。

它是 请求级别的数据通道 + 生命周期管理——理解清楚 context，是写出生产级 Go 服务的基础。

本文从设计动机到实战陷阱，把 context 讲透。

一、context 在解决什么问题

设想一个 Web 请求处理链路：

1
2
3
4
5


HTTP Handler → Service → Repository → DB Driver
 ↓
 RPC Client → 上游 Service
 ↓
 Cache

每一层都有自己的 IO，整个链路可能耗时几百 ms。如果在某一层之间发生：

客户端关闭连接：HTTP handler 应该立刻停止处理，下游的 DB 查询也该取消
整体超时：5 秒超时到了，每一层都该立刻返回
传递请求级数据：traceId、userId、rpc deadline 怎么沿调用链传

每一层都自己写一套"超时控制 + 取消信号 + 数据传递"——重复劳动 + 容易漏。

Go 设计了 context 作为统一抽象——沿调用链向下游透明传递取消、截止时间、键值对。

二、context 的接口

1
2
3
4
5
6


type Context interface {
 Deadline() (deadline time.Time, ok bool)
 Done() <-chan struct{}
 Err() error
 Value(key any) any
}

四个方法：

Deadline：何时超时（如果有）
Done：通道，关闭时表示"该停了"
Err：context 的终止原因（取消 / 超时）
Value：取请求级键值对

三、几种创建 context 的方式

1. 起点：Background / TODO

1
2


ctx := context.Background() // 顶层，永不 cancel
ctx := context.TODO() // 占位，意为"未来要补"

Background 是所有派生 context 的根——通常在 main、初始化代码、HTTP handler 入口创建。

2. WithCancel：手动取消

1
2
3
4
5
6
7
8


ctx, cancel := context.WithCancel(parent)
defer cancel() // 必须！

go func() {
 if shouldStop() {
 cancel() // 手动触发取消
 }
}()

派生出的 ctx 在 cancel() 调用后立刻关闭 Done channel。

3. WithTimeout / WithDeadline

1
2
3
4
5


ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()

ctx, cancel := context.WithDeadline(parent, deadline)
defer cancel()

到时间自动取消。

4. WithValue：传请求级数据

1
2
3
4
5
6
7


type ctxKey string
const userIDKey ctxKey = "userID"

ctx := context.WithValue(parent, userIDKey, "u-12345")

// 下游
userID := ctx.Value(userIDKey).(string)

注意：key 必须是自定义类型——不能用 string，否则容易撞键。

四、context 的派生关系

context 是不可变的——每次 With 都返回一个新 context：

flowchart TD
 Bg[Background] --> Req[WithCancel]
 Req --> A[WithTimeout 5s]
 A --> A1[WithValue userID]
 A --> A2[WithValue traceID]
 Req --> B[WithCancel]

派生关系是树形——parent 取消时所有 child 自动取消。这是 context 的核心性质。

五、典型用法

1. HTTP handler 透传

1
2
3
4
5


func handler(w http.ResponseWriter, r *http.Request) {
 ctx := r.Context() // Go 自带：客户端断开时 ctx 自动 cancel
 user, err := userService.GetByID(ctx, id)
 // ...
}

r.Context() 是 Go 标准库给的 ——客户端断连时这个 ctx 自动 cancel。

2. 整体超时

1
2
3
4
5


ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
defer cancel()

// 整个链路 3 秒超时，无论哪一层卡住都会触发
result, err := service.HeavyOp(ctx)

3. 传递 traceId

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


type ctxKey string
const traceIDKey ctxKey = "traceID"

func TraceMiddleware(next http.Handler) http.Handler {
 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 traceID := r.Header.Get("X-Trace-Id")
 if traceID == "" { traceID = uuid.NewString() }
 ctx := context.WithValue(r.Context(), traceIDKey, traceID)
 next.ServeHTTP(w, r.WithContext(ctx))
 })
}

// 下游
traceID, _ := ctx.Value(traceIDKey).(string)
log.Printf("[trace=%s] querying user...", traceID)

4. 数据库查询

database/sql 自带 context 支持：

1

rows, err := db.QueryContext(ctx, "SELECT * FROM user WHERE id = ?", id)

context 取消时 query 立刻返回 context.Canceled 错误。

5. 监听 Done

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func longRunning(ctx context.Context) error {
 for {
 select {
 case <-ctx.Done():
 return ctx.Err()
 case msg := <-ch:
 handle(msg)
 }
 }
}

任何长循环都该监听 ctx.Done——否则 context 取消你的代码不知道，照样跑。

六、几个最常被踩的坑

1. 忘了 defer cancel

1

ctx, _ := context.WithTimeout(parent, 5*time.Second) // ❌ 忽略 cancel

不调 cancel 会导致 context 资源泄漏——它会一直保留对父 context 的引用，直到 deadline 到。go vet 会警告。

正确：

1
2


ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()

2. context.Background() 用错地方

1
2
3
4


func someService() {
 ctx := context.Background() // ❌ 应该接收上游 ctx
 db.QueryContext(ctx, ...)
}

Background 只在程序入口用。函数应该接收 ctx 参数，否则上游取消信号传不进来。

3. 用 string 作 Value 的 key

1

ctx := context.WithValue(parent, "userID", "u-123") // ❌

string key 容易撞——尤其是其他库也用了 “userID”。永远用自定义类型。

4. 把 context 塞 struct 里

1
2
3


type Service struct {
 ctx context.Context // ❌ 反模式
}

context 应该作为参数传递，不应该作为字段保存——否则 context 的"请求级"语义被破坏。

5. 用 context 传业务参数

1
2
3


ctx = context.WithValue(ctx, "orderID", "1234")
// 下游
orderID := ctx.Value("orderID").(string)

反模式——业务参数应该走函数参数，context 只传"基础设施数据"（traceID、userID、deadline）。

6. 不监听 Done

1
2
3
4
5


func work(ctx context.Context) {
 for i := 0; i < 1000000; i++ {
 // ... 不检查 ctx
 }
}

context 取消了你的循环还在跑——白白浪费资源。长循环必须 select 监听 ctx.Done。

七、context 在 RPC 框架里

gRPC、Dubbo、Thrift 这些 RPC 框架都内置 context 支持——ctx 跨进程传递 deadline 和元数据：

1
2
3
4
5
6
7


// 客户端
ctx := metadata.AppendToOutgoingContext(ctx, "x-trace-id", traceID)
resp, err := client.GetUser(ctx, req)

// 服务端
md, _ := metadata.FromIncomingContext(ctx)
traceID := md.Get("x-trace-id")[0]

ctx 让"分布式 trace"变成框架自动处理的事。

八、什么不该用 context 传

context 的定位是基础设施级数据 + 生命周期——不是万能的"请求级 store"。

✅ 适合 context 传：

traceID / requestID
userID（轻量身份标识）
tenantID
locale / language
deadline / cancellation

❌ 不该用 context 传：

业务参数（如 OrderID）→ 函数参数
大对象（如完整 User）→ 函数参数
配置（如数据库连接）→ 通过依赖注入

如果 context 里塞太多东西——说明你把 context 当成『万能容器』用了，需要重新审视设计。

九、context 与 goroutine

启动 goroutine 时永远要传 ctx：

1
2
3
4
5
6
7
8


go func(ctx context.Context) {
 select {
 case <-ctx.Done():
 return
 case msg := <-ch:
 process(msg)
 }
}(ctx)

不传 ctx 的 goroutine 是"野生 goroutine"——主流程结束它还在跑，资源泄漏 + 数据错乱。

errgroup 的 context

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


g, ctx := errgroup.WithContext(parent)

for _, task := range tasks {
 task := task
 g.Go(func() error {
 return process(ctx, task) // 用 group 派生的 ctx
 })
}

if err := g.Wait(); err != nil {
 return err
}

任一 goroutine 失败时 errgroup 自动 cancel ctx——其他 goroutine 立刻退出。这是最优雅的"并发任务 + 全员协同退出"模式。

十、什么时候需要把 ctx 写出来

新人写 Go 经常困惑——“什么时候要在函数签名里加 ctx？"。

经验法则：

函数会做 IO 操作（DB / HTTP / RPC）→ 接收 ctx
函数会启 goroutine → 接收 ctx
函数链路长，可能被中途取消 → 接收 ctx
纯计算、纯转换、辅助函数 → 不需要

1
2
3
4
5
6
7


// ✓ 需要
func GetUser(ctx context.Context, id int64) (*User, error)
func Process(ctx context.Context, items []Item) error

// ✗ 不需要
func formatName(name string) string
func calculateDiscount(amount float64) float64

按"是否会 IO/并发/可能被中途打断"判断——一目了然。

小结

把全文压一句：

context 是 Go 的『请求级数据通道』——不只是 cancel 信号，而是『生命周期 + 元数据』的统一传递。

工程实战清单：

顶层用 Background，函数链路传 ctx
WithTimeout 永远配 defer cancel
value 的 key 用自定义类型
业务参数走函数参数，不要走 ctx
长循环 select 监听 Done
goroutine 永远传 ctx，配 errgroup 更优雅
ctx 不塞 struct，永远当参数传

把 context 用对，你的 Go 服务在"超时控制 + trace 跟踪 + 优雅退出"这三件事上几乎不会再出问题。

Go 中的 Option 模式：构造函数参数膨胀的优雅解法

Tue, 12 Dec 2023 15:30:00 +0800

一个写过 Go 库都遇到的痛

写一个 HTTP client 库——一开始构造函数很简单：

1
2
3


func NewClient(baseURL string) *Client {
 return &Client{baseURL: baseURL}
}

业务用着用着，需要加超时：

1

func NewClient(baseURL string, timeout time.Duration) *Client { ... }

又要加重试：

1

func NewClient(baseURL string, timeout time.Duration, retries int) *Client { ... }

再加 logger、TLS、middleware、connection pool size、custom headers……一年后构造函数变成这样：

1
2
3
4
5


func NewClient(baseURL string, timeout time.Duration, retries int,
 logger *log.Logger, tlsConfig *tls.Config, middleware []Middleware,
 poolSize int, headers map[string]string, dialer *net.Dialer) *Client {
 // ...
}

调用：

1
2


NewClient("https://api.com", 30*time.Second, 3, logger, nil, nil, 100, nil, nil)
// 这一堆 nil 是什么？

这就是『构造函数参数膨胀』反模式——参数多、含义模糊、加新参数破坏向后兼容。

Go 社区的标准解法是 Functional Options Pattern——Rob Pike 推广，K8s / etcd / gRPC / dapr 等几乎所有大型 Go 项目都在用。

一、Option 模式长什么样

 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


type Client struct {
 baseURL string
 timeout time.Duration
 retries int
 logger *log.Logger
 headers map[string]string
}

type Option func(*Client)

func WithTimeout(t time.Duration) Option {
 return func(c *Client) { c.timeout = t }
}

func WithRetries(n int) Option {
 return func(c *Client) { c.retries = n }
}

func WithLogger(l *log.Logger) Option {
 return func(c *Client) { c.logger = l }
}

func WithHeader(k, v string) Option {
 return func(c *Client) {
 if c.headers == nil { c.headers = map[string]string{} }
 c.headers[k] = v
 }
}

func NewClient(baseURL string, opts ...Option) *Client {
 c := &Client{
 baseURL: baseURL,
 timeout: 10 * time.Second, // 默认值
 retries: 0,
 }
 for _, opt := range opts {
 opt(c)
 }
 return c
}

调用方：

1
2
3
4
5
6


client := NewClient("https://api.com",
 WithTimeout(30*time.Second),
 WithRetries(3),
 WithLogger(myLogger),
 WithHeader("X-API-Key", apiKey),
)

参数顺序无所谓、可以省略、加新选项不破坏老代码——优雅、灵活、类型安全。

二、为什么 Option 比其他方案好

对比方案 1：构造函数重载（Java 风格）

1
2
3
4


func NewClient(baseURL string) *Client { ... }
func NewClientWithTimeout(baseURL string, t time.Duration) *Client { ... }
func NewClientWithLogger(baseURL string, l *log.Logger) *Client { ... }
// ...

Go 不支持重载——只能换名字。组合爆炸：3 个可选参数有 8 种组合，要写 8 个构造函数。

对比方案 2：Config struct

1
2
3
4
5
6
7
8


type Config struct {
 BaseURL string
 Timeout time.Duration
 Retries int
 Logger *log.Logger
}

func NewClient(cfg Config) *Client { ... }

调用：

1
2
3
4


NewClient(Config{
 BaseURL: "https://api.com",
 Timeout: 30 * time.Second,
})

也不错——但有几个不足：

零值无法区分"没传"和"传了零值"——Retries: 0 是没设置还是显式设置为 0？
不能动态校验/默认值——只能在构造函数里 if-else 兜底
不能"行为型"配置——比如"应用某个 middleware"
不友好对外文档——配置项散在 struct 里

对比方案 3：Builder

1
2
3
4


client := NewClientBuilder("https://api.com").
 Timeout(30 * time.Second).
 Retries(3).
 Build()

Builder 也常见——但要写更多模板代码（Builder 类、Build() 方法、链式 setter），且不如 Option 灵活（无法把多个相关配置打包成一个 helper）。

Option 的独特优势

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Option 可以做"组合配置"
func WithProductionDefaults() Option {
 return func(c *Client) {
 c.timeout = 30 * time.Second
 c.retries = 5
 c.logger = log.Default()
 }
}

// 用户一行搞定一组生产环境配置
client := NewClient(url, WithProductionDefaults(), WithHeader("X-Env", "prod"))

这是 Option 的杀手级特性——把一组配置封装成一个 Option，可复用、可组合、可继承。

三、Option 的进阶用法

1. 必填参数 vs 可选参数

1
2
3
4
5
6


// 必填参数走构造函数位置参数
func NewClient(baseURL string, opts ...Option) *Client { ... }

// 可选参数走 Option
WithTimeout(...)
WithRetries(...)

位置参数表达必填，Option 表达可选——语义清晰。

2. 校验

1
2
3
4
5
6


func WithRetries(n int) Option {
 return func(c *Client) {
 if n < 0 { panic("retries must be >= 0") }
 c.retries = n
 }
}

或者让 Option 返回 error（更优雅但模板代码多）：

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


type Option func(*Client) error

func WithRetries(n int) Option {
 return func(c *Client) error {
 if n < 0 { return errors.New("retries must be >= 0") }
 c.retries = n
 return nil
 }
}

func NewClient(baseURL string, opts ...Option) (*Client, error) {
 c := &Client{baseURL: baseURL, ...}
 for _, opt := range opts {
 if err := opt(c); err != nil {
 return nil, err
 }
 }
 return c, nil
}

3. 互斥/依赖检查

构造完成后整体校验——多个 Option 之间的关系，比单个 Option 内更复杂：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func NewClient(baseURL string, opts ...Option) (*Client, error) {
 c := &Client{...}
 for _, opt := range opts {
 opt(c)
 }
 if c.useTLS && c.tlsConfig == nil {
 return nil, errors.New("TLS enabled but no config")
 }
 return c, nil
}

4. Option 加在已有对象上

1
2
3
4
5
6
7
8
9


func (c *Client) Apply(opts ...Option) {
 for _, opt := range opts {
 opt(c)
 }
}

client := NewClient(url, WithTimeout(10*time.Second))
// 后续动态调整
client.Apply(WithTimeout(30*time.Second))

适合配置可热更新的场景。

5. 接口式 Option（隐藏内部字段）

如果不想暴露内部字段：

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


type Option interface {
 apply(*config)
}

type config struct {
 timeout time.Duration
 retries int
}

type timeoutOption time.Duration

func (t timeoutOption) apply(c *config) { c.timeout = time.Duration(t) }

func WithTimeout(d time.Duration) Option {
 return timeoutOption(d)
}

更复杂——但对外完全不暴露 config 结构。K8s 的 client-go 用了类似模式。

四、Option 模式的"反派"

不是所有场景都该上 Option：

1. 简单 + 字段少

1

func NewQueue(size int) *Queue { ... }

3 个以下参数，直接位置参数最简单——上 Option 是过度设计。

2. 内部数据结构

1
2
3
4
5
6
7


type User struct {
 Name string
 Age int
}

// 反例：给 User 写 Option？
NewUser(WithName("张三"), WithAge(20)) // ❌ 没必要

业务对象用 struct literal 就够：

1

user := &User{Name: "张三", Age: 20}

3. 一次性参数

1

func Send(msg string, channel string) error

每次调用都不同，根本不需要 Option。

五、几个真实案例

gRPC

1
2
3
4
5
6
7


conn, err := grpc.NewClient(
 "localhost:8080",
 grpc.WithTransportCredentials(insecure.NewCredentials()),
 grpc.WithDefaultCallOptions(grpc.MaxCallSendMsgSize(10*1024*1024)),
 grpc.WithKeepaliveParams(...),
 grpc.WithUnaryInterceptor(...),
)

gRPC 是 Option 模式最经典案例——选项几十个，业务用啥配啥。

K8s informers

1
2
3
4
5
6
7
8


factory := informers.NewSharedInformerFactoryWithOptions(
 clientset,
 time.Minute,
 informers.WithNamespace("default"),
 informers.WithTweakListOptions(func(opts *metav1.ListOptions) {
 opts.LabelSelector = "app=myapp"
 }),
)

Kubernetes 生态的 informer / controller-runtime / cobra 等库大量使用 Option——典型的"参数多 + 大多数有合理默认 + 经常加新选项"场景。

etcd client

1
2
3
4


cli, err := clientv3.New(clientv3.Config{
 Endpoints: []string{"localhost:2379"},
 DialTimeout: 5 * time.Second,
})

etcd 用了 Config struct——也是 Go 社区认可的姿势。可以混用。

六、踩坑提醒

1. Option 名要规范

约定：WithXxx 格式。

1
2
3


WithTimeout(...)
WithLogger(...)
WithRetries(...)

不要写成 SetTimeout、Timeout 等——With 是 Go 社区共识。

2. Option 不要保存状态

1
2
3
4
5
6
7
8


// 反例
var sharedHeader = make(map[string]string)
func WithHeaders(h map[string]string) Option {
 return func(c *Client) {
 sharedHeader = h // ❌ Option 不该改外部状态
 c.headers = sharedHeader
 }
}

Option 应当是纯函数——只改传入的对象。

3. 不要在 Option 里做重活

1
2
3
4
5


func WithDB(dsn string) Option {
 return func(c *Client) {
 c.db = openDB(dsn) // ❌ 在 Option 里建连接
 }
}

Option 应当只设值——副作用、IO、初始化都放到 NewClient 主流程。

4. Option 数量过多

如果你的 Option 已经 30 个了——这不是 Option 模式的问题，是 API 设计太复杂。考虑把 Client 拆成多个职责更聚焦的子 Client。

七、Option 是 Go 的"文化"

Java 用 Builder，Python 用 kwargs，TypeScript 用 Options object——每个语言生态都有自己的"配置传递文化"。

Go 的 Option 模式不仅是技术选择——它是 Go 文化的体现：

简单：不需要继承、不需要装饰器
显式：每个选项都有自己的函数 + 文档
可读：WithTimeout(30*time.Second) 比 cfg.Timeout = 30*time.Second 更像句子

学 Go 不只是学语法——学这种"小语言、强约定"的文化。

小结

把全文压一句：

Option 模式是 Go 解决『构造函数参数膨胀』的标准答案——必填走位置参数，可选走 WithXxx Option，灵活、可组合、对外友好。

工程实践：

2-3 个参数用位置参数；4+ 用 Option
WithXxx 命名规范
Option 是纯函数，不做副作用
校验在 NewXxx 主流程一次性做
可以把多个 Option 组合成预设

下次写 Go 库时——别再让构造函数变成"参数大字报"。Option 是 Go 给你的礼物。

Spring Reactor 入门与常见陷阱

Fri, 24 Nov 2023 16:00:00 +0800

写在前面

Spring 5 引入 WebFlux 后，“响应式编程"成了 Java 圈无法绕过的话题。但多数人对 Reactor 的理解止于：

“把 List 换成 Flux 不就行了？把 Object 换成 Mono？”

实际写起来你会发现根本不是这回事——

同步代码改成 Reactor 后性能不一定提升
一不小心 .block() 一下，所有响应式优势瞬间归零
异常处理逻辑要重新设计
ThreadLocal、Spring Security context 全部不见了

Reactor 不是『async 的语法糖』——它是另一种编程范式。本文用最少的概念把 Reactor 讲清楚：核心思想、Mono / Flux、操作符、调度器、和典型陷阱。

一、为什么需要响应式

传统 Spring MVC 的线程模型是一请求一线程：

flowchart LR
 R1[Request 1] --> T1[Thread 1
占用整个生命周期]
 R2[Request 2] --> T2[Thread 2]
 R3[Request 3] --> T3[Thread 3]
 T1 --> DB1[(DB query 100ms)]
 T2 --> DB2[(DB query 200ms)]

Tomcat 默认线程池 200 个——理论上 200 并发。但实际上每个线程在等数据库时完全空闲——CPU 浪费、内存占用大。

响应式的思路是 少线程 + 异步驱动：

flowchart LR
 R1[Request 1] --> EL[Event Loop
单/少线程]
 R2[Request 2] --> EL
 R3[Request 3] --> EL
 EL -.异步.-> DB[(DB)]
 DB -.callback.-> EL

请求来了立刻挂起 callback，不占线程；DB 返回时再继续——几个线程能撑几万 QPS。

这就是 Node.js / Netty / Reactor 的哲学。

二、Reactor 的两个核心类型

Mono：0 或 1 个值的异步流

1

Mono<User> user = userRepo.findById(1L);

类似 Optional<CompletableFuture<T>>——可能有值、可能没值、可能异步。

Flux：0 到 N 个值的异步流

1

Flux<User> users = userRepo.findAll();

类似 Stream<CompletableFuture<T>>——一系列异步到达的元素。

共同特征：lazy

1
2
3
4


Flux<Integer> f = Flux.range(1, 10).map(i -> i * 2);
// 此时什么都没发生
f.subscribe(System.out::println);
// 现在才执行

没有 subscribe 就什么都不会发生——这是初学者最大的坑（“为什么我的 log 没打印”）。

三、常用操作符

创建

1
2
3
4
5
6
7
8
9


Mono.just(value) // 单个值
Mono.empty() // 空
Mono.error(new RuntimeException())
Mono.fromCallable(() -> ...) // 包装阻塞调用

Flux.just(1, 2, 3)
Flux.range(1, 100)
Flux.fromIterable(list)
Flux.interval(Duration.ofSeconds(1)) // 每秒发一个

转换

1
2
3
4


Flux.range(1, 5)
 .map(i -> i * 2) // 同步转换
 .flatMap(i -> Mono.fromCallable(() -> rpcCall(i))) // 异步转换
 .filter(i -> i > 5)

map vs flatMap 的差异：

map：T → R
flatMap：T → Mono / Flux，会"展平"嵌套

组合

1
2
3
4
5


Mono.zip(getUserA(), getUserB()) // 并行执行，全部完成后合并
 .map(t -> new Pair(t.getT1(), t.getT2()));

Flux.merge(streamA, streamB) // 多流交错合并
Flux.concat(streamA, streamB) // A 完后再 B

错误处理

1
2
3
4


mono.onErrorReturn(defaultValue) // 出错给默认值
 .onErrorResume(e -> backupMono) // 出错切到备用流
 .retry(3) // 重试
 .timeout(Duration.ofSeconds(5)); // 超时

终止

1
2


mono.subscribe(value -> ..., err -> ..., () -> done); // 触发执行
mono.block(); // ⚠️ 阻塞拿值

四、调度器：在哪个线程执行

Reactor 的关键之一——控制每段代码跑在哪个线程：

1
2
3
4
5


Mono.fromCallable(() -> jdbcQuery()) // 阻塞调用
 .subscribeOn(Schedulers.boundedElastic()) // 移到 IO 线程池
 .map(this::transform) // 仍在 IO 线程
 .publishOn(Schedulers.parallel()) // 切到 CPU 线程池
 .map(this::heavyCompute); // 在 CPU 线程

主流调度器：

调度器	用途
`Schedulers.parallel()`	CPU 密集，线程数 = 核数
`Schedulers.boundedElastic()`	阻塞 IO（默认线程上限 10×CPU，每线程任务队列上限 100k，空闲 60s 自动回收）
`Schedulers.single()`	全局共享单线程
`Schedulers.immediate()`	当前线程直接执行

subscribeOn vs publishOn

	subscribeOn	publishOn
影响范围	整条链（从源开始）	之后的操作符
多次调用	只有第一次生效	每次都生效，切换线程
典型用途	把"源头"放到对应线程	中途切换线程

记住：subscribeOn 全局生效一次，publishOn 每次都生效。

五、阻塞与响应式的边界

Reactor 的最大原则——响应式链里绝不能有阻塞代码。

1
2
3
4


// ❌ 反例
Mono.just(id)
 .map(i -> jdbcTemplate.queryForObject("SELECT ...", ...)) // 阻塞！
 .subscribe();

JDBC 是阻塞的——直接放在 map 里会阻塞 Reactor 的事件线程，整个应用响应能力归零。

正确做法 1：包到 fromCallable + boundedElastic：

1
2
3


Mono.fromCallable(() -> jdbcTemplate.queryForObject("SELECT ...", ...))
 .subscribeOn(Schedulers.boundedElastic()) // 在 IO 池跑
 .map(this::transform);

正确做法 2：用响应式驱动（R2DBC 替代 JDBC）：

1
2


DatabaseClient client = ...;
client.sql("SELECT ...").map(row -> ...).first(); // 原生响应式

R2DBC、Spring Data Reactive Mongo / Redis、WebClient 都是响应式驱动——整条链是真异步。

六、几个最常被踩的坑

1
2
3
4


public void process() {
 fluxOfWork.map(...).subscribe(...); // 启动了
 monoOfThing.map(...); // ❌ 没 subscribe，这条链永远不跑
}

Reactor 链一旦写出来就要 subscribe，否则等于死代码。

2. block() 滥用

1

User user = userRepo.findById(id).block(); // 把异步变同步

.block() 让响应式优势全没了——主要用在测试代码、main 函数、或与同步框架/启动初始化的桥接处。生产代码里大面积出现 .block() 通常是反模式信号。

3. ThreadLocal 失效

1
2
3


Mono.fromCallable(() -> {
 // ThreadLocal 拿不到——线程切换了
})

线程跨切换后 ThreadLocal、Spring Security 上下文都丢失。Reactor 提供 Context 替代：

1
2
3
4


Mono.deferContextual(ctx -> {
 String userId = ctx.get("userId");
 return service.process(userId);
}).contextWrite(Context.of("userId", currentUserId));

4. 顺序保证

1
2
3


Flux.range(1, 100)
 .flatMap(i -> remoteCall(i)) // 并发执行，结果顺序乱
 .subscribe(System.out::println);

flatMap 默认并发——结果顺序不保证。要保序用 concatMap：

1

.concatMap(i -> remoteCall(i)) // 串行执行，保序

5. Hot vs Cold

1
2
3
4
5
6
7
8


Flux<Integer> cold = Flux.range(1, 5);
cold.subscribe(System.out::println); // 1 2 3 4 5
cold.subscribe(System.out::println); // 1 2 3 4 5（每个 subscriber 都从头）

Flux<Long> hot = Flux.interval(Duration.ofSeconds(1)).share();
hot.subscribe(System.out::println); // 0 1 2 ...
Thread.sleep(3000);
hot.subscribe(System.out::println); // 3 4 5 ...（错过的丢了）

Cold 流给每个 subscriber 重放；Hot 流是广播——搞错会导致数据丢失。

七、WebFlux：响应式 Web

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


@RestController
public class UserController {

 private final UserRepository repo;

 @GetMapping("/users/{id}")
 public Mono<User> getUser(@PathVariable Long id) {
 return repo.findById(id);
 }

 @GetMapping("/users")
 public Flux<User> listUsers() {
 return repo.findAll();
 }

 @PostMapping("/users")
 public Mono<User> create(@RequestBody Mono<UserDTO> dto) {
 return dto.map(this::toEntity).flatMap(repo::save);
 }
}

WebFlux 用 Netty 做底层，单服务器能撑数万长连接——比 MVC 模型在高并发场景下省资源。

但WebFlux 不是『性能银弹』——

业务复杂、JDBC 重的场景，MVC 反而更简单
团队没有响应式经验时，WebFlux 的代码维护成本高
99% 的中小项目用 MVC 完全够

八、调试响应式代码

log() 操作符

1
2
3
4


mono.log("user-fetch")
 .map(...)
 .log("after-map")
 .subscribe();

打印每一步的 onSubscribe、request、onNext、onComplete、onError——是调试响应式链最基础的方法。

checkpoint

1
2
3
4
5


Flux.range(1, 5)
 .checkpoint("after-range")
 .map(i -> 100 / (i - 3))
 .checkpoint("after-divide")
 .subscribe(...);

checkpoint 给错误堆栈加标签——出错时能立刻定位到哪一段。

Reactor Tools

启动时 Hooks.onOperatorDebug() 让所有错误带完整堆栈——性能影响大，仅开发调试用。

九、什么场景值得用 WebFlux

✅ 适合：

大量 IO 等待（如 fetch 多个 RPC 然后聚合）
长连接（SSE / WebSocket / 流式响应）
网关/代理类应用（高并发转发）
集成响应式数据源（R2DBC + WebClient + Reactive Redis）

❌ 不适合：

CPU 密集业务——线程模型变化无收益
JDBC + JPA 重度依赖——R2DBC 生态远不如 JPA 成熟
小团队、传统业务——MVC 简单就行

小结

把全文压一句：

Reactor 不是『async 包装』，是『让你以"数据流"思维重写程序』——核心收益在 IO 密集、高并发场景，但要付出整条链路全异步的代价。

工程要点：

没 subscribe 不会执行
.block() 是反模式
阻塞代码必须用 boundedElastic
ThreadLocal 失效，用 Context
flatMap 不保序，concatMap 保序

掌握 Reactor 不只是学几个 API——是接受"程序由数据流驱动"这种思维。值得每个 Spring 开发者了解，但不必每个项目都用。

如何把 Go 模块文档发布到 pkg.go.dev

Thu, 05 Oct 2023 15:30:00 +0800

写在前面

Go 生态里没有 npm registry / Maven Central 这种"集中仓库"——Go 模块直接通过 git 仓库地址拉取：

1

go get github.com/lingcoder/go-fsm

但有一个东西扮演了"官方文档站"的角色——pkg.go.dev。它不存代码，只存文档——从你的 Go 源码自动生成。

如果你写了一个 Go 库想让人用，go get 能拉到不代表你"发布了"——pkg.go.dev 上有完整文档、版本列表、示例代码、依赖图，才是 Go 生态意义上的"发布"。

本文用我自己的 go-fsm 作为例子，把发布流程、文档规范、版本管理讲清楚。

一、pkg.go.dev 是什么

它是 Google 维护的 Go 模块文档中心：

自动从 GitHub / GitLab 拉取公开 Go 模块
解析源码生成 HTML 文档
显示版本列表、license、依赖图、被引用数
支持搜索、跳转、链接到源码

flowchart LR
 GitHub[GitHub Tag] --> Proxy[proxy.golang.org]
 Proxy --> PkgGoDev[pkg.go.dev]
 PkgGoDev --> Doc[文档站]

你不需要"提交"什么——只要模块能被 go get，pkg.go.dev 就会自动收录。

二、最小可发布的 Go 模块

1. 仓库结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


go-fsm/
├── go.mod
├── go.sum
├── LICENSE
├── README.md
├── doc.go # 包级文档
├── fsm.go # 主代码
├── fsm_test.go
└── examples/
 └── basic/
 └── main.go

2. go.mod

1
2
3


module github.com/lingcoder/go-fsm

go 1.21

module 名必须是仓库的 import path——pkg.go.dev 通过这个找到对应的 git 仓库。

3. doc.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


// Package fsm provides a lightweight, type-safe finite state machine
// implementation for Go applications.
//
// # Quick Start
//
// Define states and events:
//
// const (
// StatePending = fsm.State("pending")
// StateApproved = fsm.State("approved")
// StateRejected = fsm.State("rejected")
// )
//
// m := fsm.New(StatePending).
// On(EventApprove).From(StatePending).To(StateApproved).
// On(EventReject).From(StatePending).To(StateRejected).
// Build()
//
// # Features
//
// - Type-safe state and event definitions
// - Hooks before / after transitions
// - Concurrent-safe by default
// - Zero dependencies
package fsm

doc.go 里的 package 注释会成为 pkg.go.dev 主页的描述——它是用户对你库的第一印象。

4. README.md

pkg.go.dev 会同时展示 README 与包级 doc——README 显示在首页 Overview 区，包级 doc 显示在 Documentation 区。两者各司其职：README 面向 GitHub / pkg.go.dev 访客做项目介绍，doc.go 面向 godoc / IDE 跳转做 API 文档。建议把 GitHub 风格的徽章、功能 GIF、安装命令放 README，把 API 用法和 example 放 doc.go。

三、文档规范：让 godoc 漂亮

pkg.go.dev 的文档完全从 Go 源码注释生成——注释规范决定文档质量。

1. 每个导出符号都要有注释

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


// State represents a state in the finite state machine.
type State string

// Event represents a transition trigger event.
type Event string

// FSM is a finite state machine instance.
type FSM struct {
 current State
 // ...
}

// New creates a new FSM with the given initial state.
func New(initial State) *FSM {
 return &FSM{current: initial}
}

注释必须以符号名开头——这是 godoc 的强约定。

2. 多行注释

1
2
3
4
5
6
7
8
9


// Trigger fires an event and transitions the FSM.
//
// If no transition is defined for the current state and event,
// it returns an ErrNoTransition error.
//
// Trigger is safe for concurrent use.
func (m *FSM) Trigger(e Event) error {
 // ...
}

空行分段，每段一个意思。

3. 列表

1
2
3
4
5


// Available hooks:
//
// - BeforeTransition: called before state changes
// - AfterTransition: called after state changes
// - OnError: called when transition fails

注意——列表项前要有 4 空格缩进，pkg.go.dev 才会渲染成 bullet。

4. 可执行示例

example_*.go 文件里的 Example* 函数会自动出现在 pkg.go.dev：

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


// example_test.go
package fsm_test

import (
 "fmt"
 "github.com/lingcoder/go-fsm"
)

func ExampleFSM_Trigger() {
 m := fsm.New("pending").
 On("approve").From("pending").To("approved").
 Build()

 m.Trigger("approve")
 fmt.Println(m.State())
 // Output: approved
}

// Output: ... 是 Go 测试框架的语法——它既验证示例正确性，也是文档。

5. 标题（Go 1.19+）

1
2
3
4
5
6
7


// # Configuration
//
// The FSM can be configured via options...

// # Performance
//
// The FSM is optimized for...

# 在注释里被识别为标题——pkg.go.dev 会渲染成大标题、生成目录。

四、版本管理：发布正式版本

1. 用 git tag 发布

1
2


git tag v1.0.0
git push origin v1.0.0

tag 必须是 vX.Y.Z 格式——Go modules 强制语义化版本。

2. 让 pkg.go.dev 收录新版本

打 tag 后，第一次访问 https://pkg.go.dev/github.com/lingcoder/go-fsm@v1.0.0 会触发proxy.golang.org 抓取——几秒后页面就有了。

或者用：

1

go get github.com/lingcoder/go-fsm@v1.0.0

也会触发同样的抓取。

3. v2+ 的特殊规则

重要：v2 及以上版本要在 module path 里加版本号：

1
2
3


v0.x.x / v1.x.x → module path: github.com/lingcoder/go-fsm
v2.x.x → module path: github.com/lingcoder/go-fsm/v2
v3.x.x → module path: github.com/lingcoder/go-fsm/v3

发布 v2 时：

1
2
3
4


# go.mod
module github.com/lingcoder/go-fsm/v2

go 1.21

并打 tag v2.0.0。这是 Go 1.13 之后的强制规则——强迫"breaking change 必显式"。

五、license 文件：影响排名

pkg.go.dev 会显示模块的 license——有 license 的模块在搜索结果里更靠前。最常用：

MIT —— 最宽松，工业首选
Apache 2.0 —— 带专利授权条款，大公司喜欢
BSD-3-Clause —— 简单、宽松

把对应的 LICENSE 文件放仓库根目录就行——pkg.go.dev 自动识别。

没 license 的代码 法律上等于"All rights reserved" ——别人不能用。开源前一定要加。

六、CI 集成：自动化发布

GitHub Actions 自动测试 + 发版：

 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


# .github/workflows/release.yml
name: release

on:
 push:
 tags: ['v*']

jobs:
 release:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - uses: actions/setup-go@v4
 with:
 go-version: '1.21'

 - name: Test
 run: go test ./...

 - name: Vet
 run: go vet ./...

 - name: Trigger pkg.go.dev fetch
 run: |
 curl -sSf "https://proxy.golang.org/github.com/${{ github.repository }}/@v/${{ github.ref_name }}.info"

最后一步主动告诉 proxy.golang.org 拉取——比等用户访问快。

七、提高搜索排名

pkg.go.dev 的搜索排名考虑：

被 import 数量——其他 Go 模块依赖你的越多，排名越高
license 是否存在
文档完整度——所有导出符号都有注释
版本稳定——是否打过 v1+ tag
README / doc.go 内容——关键词是否覆盖搜索词

策略：

取好搜的名字（关键词命中度高）
早发 v1.0.0——pkg.go.dev 把 0.x 版本视为不稳定
写好 doc.go——是搜索引擎的主要食粮
写 example——示例丰富的库更受欢迎

八、常见问题

1. 推了 tag 但 pkg.go.dev 没显示

主动触发抓取：

1

curl "https://proxy.golang.org/github.com/your/repo/@v/v1.0.0.info"

或访问一次 https://pkg.go.dev/github.com/your/repo@v1.0.0。

2. README 里的图片不显示

pkg.go.dev 会渲染 README，但不加载相对路径的本地图片——![logo](docs/logo.png) 这种引用在 pkg.go.dev 上看不到。要让图片正常显示：

用 GitHub raw 的绝对 URL：![logo](https://raw.githubusercontent.com/owner/repo/main/docs/logo.png)
或者把图片放在 GitHub Pages / 图床上引用

API 文档建议同时维护 README（项目介绍）和 doc.go（API 用法）——两者会分别在 Overview 区和 Documentation 区展示，互不替代。

3. 私有仓库怎么办

私有 module 不会在 pkg.go.dev 出现。要内部 doc：

自托管 godoc -http=:6060
公司内部用 pkgsite 自建

4. 删除已发布版本

不能删除。一旦 tag 发布到 proxy.golang.org，会被永久缓存——这是 Go modules 的"checksum 不可变"承诺。

发现版本有 bug：

标记 retract（go.mod 里加 retract v1.0.5）
立刻发新版本 v1.0.6 修复

1
2
3
4
5
6


// go.mod
module github.com/lingcoder/go-fsm

go 1.21

retract v1.0.5 // bug, use v1.0.6+

retracted 版本仍能解析，但用户用 go get 时会得到警告。

5. examples 怎么组织

简单示例 → example_test.go（pkg.go.dev 显示）
完整 demo → examples/ 目录（GitHub 显示但 pkg.go.dev 不显示——所以 doc.go 里指向）

九、一份发布前 Checklist

发版前对照检查：

go.mod 的 module path 正确
doc.go 写好包级文档
所有导出符号有注释（用 golint / revive 检查）
LICENSE 文件存在
README.md 包含安装、quickstart、license
至少 3 个 Example 函数
单元测试覆盖关键路径
CI 通过
打 v1.0.0+ tag（或符合 v2+ 规则）
推 tag 后访问 pkg.go.dev 验证

小结

把全文压一句：

Go 模块发布的『正式仪式』是 git tag + pkg.go.dev——但真正决定库能否被人用的是 doc.go 和 Example 函数的质量。

工程要点：

注释以符号名开头，每个导出符号都有
doc.go 是包的脸面——花时间写
Example 函数比一万字文档有效
v1.0.0 是分水岭——别永远停在 0.x
v2+ 必改 module path

把这套做对，你的 Go 库就不只是"能 go get"——它有文档、有版本、有声誉，是 Go 生态的"正式公民"。

Flutter安装与配置

Thu, 14 Sep 2023 22:59:57 +0800

下载安装

Flutter SDK 或者使用Git从官方仓库下载

1

git clone -b dev https://github.com/flutter/flutter.git

下载解压

环境配置

1
2
3
4
5
6
7
8
9


export PUB_HOSTED_URL=https://pub.flutter-io.cn

export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

export PATH="$PWD/flutter/bin:$PATH"

# 不管
cd ./flutter
flutter doctor

Conda和poetry搭配使用

Mon, 11 Sep 2023 18:07:52 +0800

创建一个新的conda环境，并在这个环境中使用 poetry。这是为了防止conda环境和poetry环境之间有冲突，或者因为全局系统级别的Python和包影响项目。

步骤：

创建conda环境（此处的myenv是环境名，3.11是你需要的Python版本）：

1

conda create -n myenv python=3.11 --no-default-packages

激活这个conda环境：

1

conda activate myenv

确认你正在使用conda环境中的Python。在终端输入以下命令，查看python路径：

1

which python

你应该可以看到一个指向你刚创建的conda环境的路径。

现在，你应该可以在你的conda环境中安装和使用 poetry 了。可以通过以下命令来安装 poetry：

1

pip install poetry

当我们在conda环境中启动了poetry后，可以创建一个新的poetry项目，或切换到已有的poetry项目目录下，然后使用 poetry install 安装项目的依赖。由于你是在conda环境中启动的 poetry，所以依赖会被安装在当前的conda环境中。请注意，使用这种方式，conda会负责管理Python和二进制依赖，而poetry则负责管理Python包。

最后，附赠一份poetry项目常用的镜像构建脚本：

 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



FROM python:3.11-bookworm as builder

WORKDIR /app

COPY pyproject.toml poetry.lock /app/

ENV POETRY_VIRTUALENVS_CREATE false

RUN pip3 install pip --upgrade && pip3 install poetry --upgrade && poetry install --no-root --only main


FROM python:3.11-slim-bookworm

WORKDIR /app

COPY --from=builder /usr/local/lib/python3.11 /usr/local/lib/python3.11

COPY --from=builder /usr/local/bin/ /usr/local/bin/

COPY . /app

EXPOSE 8080

# Run the application when the container launches
CMD ["python", "main.py"]

Java 权限框架怎么选——Shiro 与 Spring Security 对比

Thu, 22 Jun 2023 16:00:00 +0800

一句话先把定位讲清楚

	Shiro	Spring Security
起源	Apache，2009	Spring 全家桶原生
设计哲学	简单、上手快、最小依赖	完备、可扩展、深度集成
体系庞大度	轻量	重量
默认特性	认证 + 授权 + Session + 加密	认证 + 授权 + 大量协议（OAuth2、CSRF、CORS、JWT）
学习曲线	平缓	陡峭
与 Spring 集成	适配良好但不"自家"	原生

简单说：

Shiro 是『来即用的工具』，Spring Security 是『全功能的框架』。

下面把这两套方案的差异、各自优劣、不同场景下的选型建议讲清楚。

一、概念结构对比

Shiro 的核心概念

flowchart LR
 Subject[Subject
当前用户] --> SecurityManager[SecurityManager
核心]
 SecurityManager --> Authenticator[Authenticator
认证]
 SecurityManager --> Authorizer[Authorizer
授权]
 SecurityManager --> SessionManager[SessionManager
会话]
 Authenticator --> Realm[(Realm
数据源)]
 Authorizer --> Realm

Subject：当前操作的用户主体
SecurityManager：所有功能的入口
Realm：连接用户/角色/权限数据源（DB、LDAP、缓存）

代码风格非常直观：

1
2
3
4


Subject subject = SecurityUtils.getSubject();
subject.login(new UsernamePasswordToken(username, password));
subject.checkRole("admin");
subject.checkPermission("user:delete");

Spring Security 的核心概念

flowchart LR
 Filter[FilterChainProxy] --> AuthFilter[Authentication Filter]
 AuthFilter --> AuthMgr[AuthenticationManager]
 AuthMgr --> Provider[AuthenticationProvider]
 Provider --> UDS[(UserDetailsService)]
 AuthFilter --> SC[SecurityContext]
 SC --> Authz[AccessDecisionManager]
 Authz --> Voter[Voter / AuthorizationManager]

FilterChainProxy：所有请求都过的过滤器链
AuthenticationManager / Provider：认证流水线
UserDetailsService：连数据源
SecurityContext：认证后的上下文（线程级）
AuthorizationManager：授权决策

业务里典型用法：

1
2
3
4
5
6
7


@PreAuthorize("hasRole('ADMIN')")
public void deleteUser(Long id) {
 userService.delete(id);
}

// 或者细粒度
@PreAuthorize("hasAuthority('user:delete')")

一眼看上去 Spring Security 概念多得多——这是它的本质特征：用更细分的角色解耦每一步。

二、特性能力对比

	Shiro	Spring Security
用户名密码登录	✓	✓
角色 / 权限模型	✓ 简洁	✓ 强（GrantedAuthority）
会话管理	✓ 内置 Session	✓ HttpSession + 自定义
记住我	✓	✓
加密工具	✓	✓
注解鉴权	✓ `@RequiresPermissions`	✓ `@PreAuthorize`
URL 鉴权	✓ ini / Java DSL	✓ Java DSL
OAuth2 / OIDC	△ 第三方扩展	✓ 原生
CSRF 防御	✗	✓ 默认开启
CORS	✗	✓
JWT	△ 第三方	✓ Resource Server / OAuth2 配套
多因子认证	△	✓
Method 级注解 SpEL	✓ 简单	✓ 强大（SpEL 全支持）
Reactive 支持	✗ 不支持	✓ WebFlux 原生

差距的几个关键点：

OAuth2 / OIDC：只要你的系统涉及第三方登录、单点登录、服务对接、API 鉴权，Spring Security 几乎是唯一现实选择。Shiro 也能做，但要拼装大量代码
CSRF / CORS：Shiro 不管这些，要自己写过滤器；Spring Security 默认就帮你做好了
JWT：两者都能做，但 Spring Security 5.x 之后 Resource Server 支持极完善
Reactive：WebFlux 项目根本不要考虑 Shiro

三、典型代码对比

同样是"用户名密码登录 + 检查权限"：

Shiro

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


// 配置 Realm
public class MyRealm extends AuthorizingRealm {
 @Override
 protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection p) {
 String username = (String) p.getPrimaryPrincipal();
 SimpleAuthorizationInfo info = new SimpleAuthorizationInfo();
 info.setRoles(userService.getRoles(username));
 info.setStringPermissions(userService.getPermissions(username));
 return info;
 }

 @Override
 protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) {
 UsernamePasswordToken upt = (UsernamePasswordToken) token;
 User user = userService.findByUsername(upt.getUsername());
 if (user == null) throw new UnknownAccountException();
 return new SimpleAuthenticationInfo(user.getUsername(), user.getPassword(), getName());
 }
}

// 业务里
Subject subject = SecurityUtils.getSubject();
subject.login(new UsernamePasswordToken("admin", "123456"));
subject.checkPermission("user:delete");

Spring Security

 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


// UserDetailsService
@Service
public class MyUserDetailsService implements UserDetailsService {
 @Override
 public UserDetails loadUserByUsername(String username) {
 User user = userService.findByUsername(username);
 if (user == null) throw new UsernameNotFoundException(username);
 return org.springframework.security.core.userdetails.User.builder()
 .username(user.getUsername())
 .password(user.getPassword())
 .authorities(user.getAuthorities())
 .build();
 }
}

// SecurityFilterChain
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 return http
 .authorizeHttpRequests(auth -> auth
 .requestMatchers("/login").permitAll()
 .anyRequest().authenticated())
 .formLogin(Customizer.withDefaults())
 .csrf(Customizer.withDefaults())
 .build();
}

// 业务里
@PreAuthorize("hasAuthority('user:delete')")
public void delete(Long id) { ... }

Shiro 的代码更直观——但每件事都要你做主动调用；Spring Security 是"声明 + 自动连接"，刚开始绕，习惯了反而省心。

四、扩展性

Shiro：扩展点少而清晰

Shiro 把扩展点限定在几个核心接口：Realm、SessionManager、Authenticator、Filter。要做特殊认证（比如手机验证码登录）只需要自己写个 Token + 改 Realm。扩展边界小、写起来直接。

Spring Security：扩展点多但有学习曲线

Spring Security 有几十个可扩展点：AuthenticationProvider、UserDetailsService、SecurityContextRepository、AuthenticationEntryPoint、AccessDeniedHandler、各种 Filter……第一次接它的人会被这么多概念吓到。

但一旦熟悉了：

想要"OAuth2 + 数据库角色 + JWT 接口 + 表单登录"四种方式共存？只是几个 SecurityFilterChain 的事
想要把 Session 存进 Redis 实现集群登录？SecurityContextRepository 改一个就够
想要某个 URL 用一种鉴权方式、另一些用另一种？多 SecurityFilterChain 按顺序匹配

复杂场景下 Spring Security 远胜 Shiro——因为它把每件事都拆成了独立的扩展点。

五、社区与维护活跃度

	Shiro	Spring Security
主线版本	1.13.x（2024）	6.x，与 Spring 6 同步
发布频率	一年一两个小版本	跟 Spring Boot 节奏同步迭代
中文资料	较多（早期热门）	越来越多
国际社区	中等	强
招聘频率	中小厂偶尔提及	大厂、外企必考

国内 Shiro 用户多，是因为它早期太"友好"——五分钟上手，老项目就用了下来。但近年 Shiro 历史上爆出过多个 RCE 漏洞（CVE-2020-1957、CVE-2020-11989、CVE-2022-32532 等），这是用 Shiro 的项目必须持续关注版本升级的硬性事实。

Spring Security 漏洞同样有，但修复响应快、官方推送积极、版本管理跟着 Spring Boot 一起走——大型项目更省心。

六、性能差距：基本不存在

很多博客争论性能差距——这是个伪问题。

Shiro 和 Spring Security 都是"内存中读权限规则、过滤器链拦截请求"
性能瓶颈永远在你写的 Realm / UserDetailsService——也就是数据库查询
单次请求的鉴权耗时通常在几百微秒到 1ms 之间，业务代码随便就比这慢一个数量级

不要拿微基准跑出来的数字当选型依据。

七、什么场景选什么

选 Shiro 的场景

小到中型项目，权限模型简单（角色 + 几条权限）
不涉及 OAuth / SSO / 第三方登录
团队对 Shiro 已经熟悉、已有项目大量使用
不要 Reactive / WebFlux

选 Spring Security 的场景

需要 OAuth2、OIDC、SSO、JWT 等标准协议
大型 / SaaS / 多租户系统
有 WebFlux / Reactive 需求
新项目、想跟 Spring 全家桶生态保持一致
大厂面试 / 简历加分

八、共存与迁移建议

共存

老项目用 Shiro，新模块想用 Spring Security——理论上能共存，但强烈不推荐。两套过滤器链同时存在会很混乱，调试链路变长，维护成本极高。一个项目只用一套。

老项目从 Shiro 迁移到 Spring Security

迁移成本不小，但路径相对固定：

Realm → UserDetailsService + AuthenticationProvider
@RequiresPermissions → @PreAuthorize
Filter 配置改写成 SecurityFilterChain
Session 管理改 Spring Security 的 SecurityContext

要点：先打通主链路（登录 + 一个接口的鉴权），再批量替换注解——不要一口气全切。

九、几个被反复争论的话题

争论 1：Spring Security 太复杂

部分对——但它复杂的地方多数是"复杂功能不是你需要的功能"。基础的"账号密码登录 + 接口鉴权"配置极简：

1
2
3
4
5
6
7


@Bean
public SecurityFilterChain chain(HttpSecurity http) throws Exception {
 return http
 .authorizeHttpRequests(a -> a.anyRequest().authenticated())
 .formLogin(Customizer.withDefaults())
 .build();
}

是不是看起来比 Shiro 还少？

争论 2：Shiro 文档少

部分对——Shiro 官方文档质量一般，社区资料质量参差。Spring Security 文档有官方系统手册 + 大量社区文章，反而更容易学。

争论 3：Sa-Token 是不是更好的选择？

Sa-Token 是国内开源的轻量框架，API 极简，适合中小项目快速上手。它的定位更接近 Shiro——简单、易用、适合中小项目。

但 Sa-Token 的社区影响力和 Spring Security 不在一个量级，团队对接外部系统、招聘新人、跟进安全更新时仍然有差距。有兴趣可以学，但不要在大型项目里盲目替换主流框架。

十、决策树

flowchart TD
 Start([新项目?])
 Start -->|是| OAuth{需要 OAuth/SSO/第三方登录?}
 Start -->|否，老项目| Have{已经在用什么?}
 Have -->|Shiro 稳定| Keep[继续用，关注 CVE]
 Have -->|Spring Security| Keep2[继续用]
 OAuth -->|需要| SS1[Spring Security]
 OAuth -->|不需要| Reactive{用 WebFlux?}
 Reactive -->|是| SS2[Spring Security]
 Reactive -->|否| Scale{中长期会变复杂?}
 Scale -->|会| SS3[Spring Security]
 Scale -->|不会，工具型小项目| Choose[Shiro / Sa-Token / Spring Security 任选]

小结

把全文压一句：

Shiro 上手快、能力够、维护需谨慎；Spring Security 学习陡、能力全、生态强。中小项目都行，中大型项目优先 Spring Security。

工程上几条建议：

新项目优先 Spring Security——尤其涉及 OAuth/SSO 时
老项目用 Shiro 稳定运行的，不要折腾——但版本升级要跟住 CVE
不要两套共存——选一个，全量做
学权限框架不只是学 API，要学概念——用得好的关键是理解 Authentication / Authorization / Filter Chain / Context 这些底层概念
不要把"网上博客对比性能差几毫秒"当选型依据——那是噪声

把这两套之中任意一套用熟，配合好你的业务权限模型，安全这层基本就稳住了。

Go 业务代码里的错误处理最佳实践

Wed, 29 Mar 2023 16:00:00 +0800

写在前面

Java / Python / JS 抛异常，Go 用返回值——这是 Go 最被争论的设计。一段典型的 Go 业务代码：

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


user, err := userRepo.GetByID(id)
if err != nil {
 return nil, err
}
order, err := orderRepo.Create(user, dto)
if err != nil {
 return nil, err
}
err = mqProducer.Send(orderCreatedEvent(order))
if err != nil {
 return nil, err
}
return order, nil

每隔三行就 if err != nil——很多新手吐槽"丑"。但写过几年 Go 你会发现：这种"显式错误传递"反而让错误处理路径极其清晰——不像异常那样在调用栈里随机冒出。

但工程上要做对，几个细节：

怎么区分错误类型？err 都是 string 不利于业务判断
怎么追溯错误源头？层层 return err 后只剩最后一层信息
panic 什么时候用？
业务错误 vs 系统错误怎么处理？

本文把 Go 业务代码里错误处理的最佳实践讲清楚。

一、Go 错误处理的核心原则

四个关键原则：

错误是值（errors are values）——不是控制流
错误要有类型——光凭字符串无法做精确判断
错误要带上下文——知道错在哪里
错误要可断言——上层能判断"是不是某种特定错误"

老的 Go 代码多用 fmt.Errorf("%v: %v", ...) 拼字符串——丢失类型。新的 Go（1.13+）有 errors.Is、errors.As、fmt.Errorf("%w", ...)——错误处理终于有了正经工具。

二、定义业务错误：sentinel + 类型

Sentinel 错误（哨兵错误）

1
2
3
4
5
6
7
8
9


package usercase

import "errors"

var (
 ErrUserNotFound = errors.New("user not found")
 ErrUserInactive = errors.New("user inactive")
 ErrInvalidStatus = errors.New("invalid status")
)

调用方判断：

1
2
3
4


user, err := getUser(id)
if errors.Is(err, ErrUserNotFound) {
 return c.Status(404).JSON(...)
}

errors.Is 会沿着 error 链查找——即便错误被 wrap 包过几层，仍然能识别。

类型化错误

光 sentinel 不够——业务错误经常带细节信息：

1
2
3
4
5
6
7
8


type ValidationError struct {
 Field string
 Message string
}

func (e *ValidationError) Error() string {
 return fmt.Sprintf("validation: %s: %s", e.Field, e.Message)
}

调用方判断：

1
2
3
4
5
6
7


var ve *ValidationError
if errors.As(err, &ve) {
 return c.Status(400).JSON(map[string]string{
 "field": ve.Field,
 "message": ve.Message,
 })
}

errors.As 把 error 链中类型匹配的错误赋值给目标变量——能拿到具体字段。

三、Wrap 错误：保留上下文

朴素的 return err 让错误传递时丢失链路：

1
2


// 反例：看不出错在哪里
return userRepo.GetByID(id)

正确做法是 wrap 上下文：

1
2


// 1.13+ 用 fmt.Errorf %w
return fmt.Errorf("getUserByID(%d): %w", id, err)

%w 让错误保留可被 errors.Is/As 追溯的链——而不是普通 %v 拼字符串后丢失类型。

错误打印长这样：

1

service.GetOrder: repo.GetOrder(123): db query: connection refused

每一层都加上下文——出问题时直接看错误信息就能定位。

有些第三方库用 `pkg/errors`

1
2
3


import "github.com/pkg/errors"

err = errors.Wrap(err, "getOrder failed")

老 Go 项目还能见到这种写法——和标准库的 %w 同一思想，新项目直接用标准库即可。

四、什么时候 wrap，什么时候不 wrap

不是每个 err 都要 wrap——盲目 wrap 会让信息冗余：

1
2


// 反例：每层都 wrap，错误信息变成俄罗斯套娃
service: handle: process: validate: check: getValue: db query: connection refused

实战原则：

跨层时 wrap（repo → service → handler）
加业务上下文时 wrap（“creating order for user 123”）
同层多次调用同一函数时 wrap（区分是哪次失败）
直接 return 即可的简单透传，不 wrap

五、Sentinel 还是类型化？

	sentinel error	typed error
表达力	弱（只是个标识）	强（带字段）
比较方式	`errors.Is`	`errors.As`
模板代码	少	多（要写 type）
适合	简单标志（NotFound/Forbidden）	携带详细信息

实战折中：简单错误用 sentinel，需要带字段用 typed。

1
2
3


var ErrNotFound = errors.New("not found") // sentinel

type RateLimitError struct { RetryAfter time.Duration } // typed

六、错误分层：业务错误 vs 系统错误

业务错误（用户输入错了、状态不允许）和系统错误（DB 挂了、网络超时）应该完全不同处理：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


type DomainError struct {
 Code string // "USER_NOT_FOUND" / "INSUFFICIENT_BALANCE"
 Message string // 给用户看的消息
 HTTPStatus int // 4xx
}

func (e *DomainError) Error() string {
 return fmt.Sprintf("%s: %s", e.Code, e.Message)
}

// system error 是普通 error

handler 里统一处理：

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


func errorHandler(c *fiber.Ctx, err error) error {
 var de *DomainError
 if errors.As(err, &de) {
 // 业务错误：返回给用户
 return c.Status(de.HTTPStatus).JSON(map[string]string{
 "code": de.Code,
 "message": de.Message,
 })
 }

 // 系统错误：500，且消息脱敏
 log.Errorf("internal error: %+v", err)
 return c.Status(500).JSON(map[string]string{
 "code": "INTERNAL_ERROR",
 "message": "服务暂时不可用",
 })
}

业务错误暴露给前端没问题；系统错误的细节（如 SQL 报错）绝不能传给用户——日志记录、外部模糊处理。

七、不要用 panic 做控制流

panic 是 Go 的"异常逃生通道"——但不是给业务用的：

1
2
3
4
5
6
7
8


// ❌ 反例：用 panic 做错误处理
func GetOrder(id int) *Order {
 order, err := repo.GetByID(id)
 if err != nil {
 panic(err)
 }
 return order
}

业务代码里 panic 的合法用途几乎只有两类：

真正不应该发生的情况（如 nil pointer 解引用、数组越界）——表示编程 bug
初始化时的致命错误（如配置文件加载失败）——直接退出

正常业务流程永远 return error，让调用方决定怎么处理。

recover 的合法用途

1
2
3
4
5
6
7
8
9


func handler(w http.ResponseWriter, r *http.Request) {
 defer func() {
 if r := recover(); r != nil {
 log.Errorf("panic recovered: %v", r)
 http.Error(w, "internal error", 500)
 }
 }()
 // 业务逻辑
}

每个 HTTP handler 入口、goroutine 入口加 recover——避免一个 panic 把整个服务搞挂。这是兜底，不是常规手段。

八、goroutine 里的错误

启动 goroutine 后，错误不会自动传回 main——必须显式：

1
2
3
4
5
6
7


// ❌ 错误丢失
go func() {
 err := doWork()
 if err != nil {
 // ??? 没人收
 }
}()

正确姿势：

1
2
3
4
5
6
7


errCh := make(chan error, 1)
go func() {
 errCh <- doWork()
}()
if err := <-errCh; err != nil {
 return err
}

或者用 errgroup——更优雅：

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


import "golang.org/x/sync/errgroup"

g, ctx := errgroup.WithContext(ctx)
for _, task := range tasks {
 task := task
 g.Go(func() error {
 return process(ctx, task)
 })
}
if err := g.Wait(); err != nil {
 return err
}

errgroup 还会任一任务失败时自动 cancel ctx——其他任务能立刻退出。

九、错误日志的姿势

1
2
3


// 反例：错误又抛出又日志，导致重复日志
log.Errorf("query user: %v", err)
return err

原则：要么 log，要么 return。同一错误只 log 一次——通常在最上层（HTTP handler / cron entry）。

1
2
3
4
5
6
7
8


// 在 service / repo 层只 wrap：
return fmt.Errorf("getUser: %w", err)

// 在 handler 层一次性记录：
if err := service.GetUser(id); err != nil {
 log.Errorf("getUser failed: %+v", err)
 return ...
}

%+v 配合带 stack trace 的 error 库（如 pkg/errors 或 cockroachdb/errors）能打印完整调用栈。

十、几个常见反模式

1. 错误吞掉

1

result, _ := json.Marshal(obj) // ❌

_ 把错误丢了——出问题永远查不到。显式忽略只在你 100% 确定不会出错时才用，并加注释说明。

2. 错误转字符串再判断

1

if err.Error() == "not found" { ... } // ❌

字符串匹配脆得不行——别人改一个字你的判断就废了。用 errors.Is / errors.As。

3. 把所有错误压成一个 Internal Error

1

return errors.New("internal error")

调用方完全不知道发生什么——永远要 wrap 原 error，保留链。

4. 错误信息含敏感数据

1

return fmt.Errorf("query failed: %v", sqlPassword) // ❌

错误信息可能上日志、上前端——敏感数据要脱敏。

5. error 字段在结构体里

1
2
3
4


type Result struct {
 Data interface{}
 Err error // ❌ 反 Go 风格
}

Go 的约定是"return (T, error)"——别学其他语言把 error 塞结构体里。

十一、Go 1.20+ 的 errors.Join

Go 1.20 引入 errors.Join——支持组合多个错误：

1
2
3


err1 := process(1)
err2 := process(2)
return errors.Join(err1, err2) // 把多个错误打包返回

errors.Is 仍能识别每个原错误：

1
2
3


joined := errors.Join(ErrA, ErrB)
errors.Is(joined, ErrA) // true
errors.Is(joined, ErrB) // true

适合并发任务、批量操作场景——以前要自己写一个 multi-error，现在标准库有了。

小结

把全文压一句：

Go 错误处理的核心是『错误是值，要有类型、有上下文、可断言』——if err != nil 看着烦，但带上 errors.Is/As/Wrap 后是 Go 最干净的设计。

工程实战清单：

业务错误用 sentinel 或 typed，不要 errors.New(...) 拼字符串
跨层 wrap，加业务上下文，用 %w
errors.Is 比较 sentinel，errors.As 提取 typed
业务错误和系统错误分层处理——前端区分对待
panic 不做业务控制流——只在不可恢复 + 初始化失败时
goroutine 用 errgroup
错误只 log 一次，在最上层

把这些做对，“if err != nil 写到吐"会变成你 Go 代码里最可靠的一部分——而不是负担。

estimateGas 与 ethCall：以太坊 RPC 中两个最容易混淆的方法

Fri, 25 Nov 2022 15:30:00 +0800

两个看着差不多的 RPC 方法

写过以太坊 dapp 的人都用过这两个 JSON-RPC 方法：

eth_call：调用合约只读函数、模拟交易
eth_estimateGas：估算一笔交易要多少 Gas

它们的请求参数几乎一模一样：

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


{
 "jsonrpc": "2.0",
 "method": "eth_call",
 "params": [{
 "from": "0x...",
 "to": "0x...",
 "data": "0x..."
 }, "latest"]
}

{
 "jsonrpc": "2.0",
 "method": "eth_estimateGas",
 "params": [{
 "from": "0x...",
 "to": "0x...",
 "data": "0x..."
 }, "latest"]
}

调用方式都不会真的上链，都是节点本地模拟，都返回结果。新人很容易把它们混为一谈——其实它们解决的问题完全不同。

一、本质差异

	eth_call	eth_estimateGas
返回值	函数 ABI 编码的 return data	Gas 数量（uint）
是否模拟执行	✓	✓
是否实际改状态	✗（执行完丢弃）	✗（执行完丢弃）
用途	查 view/pure 函数、模拟调用	计算交易需要多少 gas
是否需要 from	通常不需要	可能需要（影响 gas）
是否能"send"	✗	✗

简单说：eth_call 关心『结果是什么』，estimateGas 关心『要花多少 gas』。

二、eth_call：模拟执行查结果

最常见用途：调 view 函数

1
2


// ethers.js 的 contract.balanceOf(addr) 底层就是 eth_call
const balance = await contract.balanceOf("0xabc...");

底层 RPC：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "method": "eth_call",
 "params": [
 {
 "to": "0xTokenAddr",
 "data": "0x70a08231000000000000000000000000abc..."
 },
 "latest"
 ]
}

返回十六进制 ABI 编码的余额。

进阶用途：模拟交易查结果

eth_call 也能用来"试运行一笔本应是 transaction 的交易"——比如：

1
2
3
4
5
6


// 模拟 transfer 看会不会 revert
try {
 await contract.callStatic.transfer(to, amount); // ethers v5
} catch (e) {
 // 模拟失败 → 真实交易也会失败
}

callStatic 就是 eth_call。这种姿势特别有用：

提交 tx 前先模拟，避免上链失败浪费 Gas
检查"用户是否有权限调这个函数"
检查"调用会返回什么"

eth_call 的特殊能力：状态覆盖

部分节点（Geth / Erigon）支持 state override——模拟时可以临时改变某个地址的代码或存储：

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


{
 "method": "eth_call",
 "params": [
 {"to": "0x...", "data": "0x..."},
 "latest",
 {
 "0xUserAddr": {
 "balance": "0x100000000",
 "code": "0x...",
 "state": {"0x...": "0x..."}
 }
 }
 ]
}

这种能力让你能模拟"如果某用户有 100 ETH 会怎样"——是高级 dapp 调试和"什么 if 分析"的利器。

三、eth_estimateGas：估算交易 Gas

工作原理

estimateGas 大致流程：

节点用一个高 Gas Limit（如区块 limit）模拟执行
记录实际消耗的 gas
加一个 buffer 返回（不同节点策略不同，通常加 25%）

1

const gasLimit = await contract.estimateGas.transfer(to, amount);

返回值是这笔交易上链需要的 gas 数量——前端用它构造 transaction 时设置 gasLimit：

1
2
3


const tx = await contract.transfer(to, amount, {
 gasLimit: gasLimit.mul(110).div(100) // 再加 10% 安全 buffer
});

为什么经常会失败

estimateGas 失败极常见——主要原因：

交易本身会 revert——节点尝试模拟时 revert，没法估
caller 余额不足——估算时 from 地址余额不够支付 gas
依赖未初始化的状态——比如调用 view 函数检查某个 mapping，对方还没设过
block 时间相关逻辑——估算时的"当前时间"和真正上链时不一致

错误返回通常长这样：

1
2
3
4
5
6


{
 "error": {
 "code": -32603,
 "message": "execution reverted: ERC20: insufficient balance"
 }
}

不要相信 estimateGas 的精确值

估算返回的值不是上链时真正消耗的 gas——它是"本次模拟所用 + buffer"。但实际上链时：

区块时间变了
mempool 有其他交易先执行了
gasprice 变化导致状态访问的成本变化（EIP-2929 后的差距更明显）

永远要在 estimate 基础上加额外 buffer——通常 1.1× 到 1.5×。

四、何时用 eth_call、何时用 estimateGas

flowchart TD
 Start([需要什么?])
 Start --> A{是 view 函数吗?}
 A -->|是| Call1[eth_call]
 A -->|否，可能改状态| B{发交易前的预检?}
 B -->|检查会不会 revert| Call2[eth_call]
 B -->|要传给 tx 的 gasLimit| Estimate[eth_estimateGas]
 B -->|两者都要| Both[先 call 验证，再 estimate]

实战姿势 1：发交易前完整预检

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


async function safeSend(contract, method, args, sender) {
 // 1. 先模拟看会不会 revert
 try {
 await contract.callStatic[method](...args, { from: sender });
 } catch (e) {
 throw new Error(`tx will revert: ${e.message}`);
 }

 // 2. 估 Gas
 const gas = await contract.estimateGas[method](...args, { from: sender });

 // 3. 加 buffer 实际发送
 return contract[method](...args, {
 gasLimit: gas.mul(110).div(100)
 });
}

实战姿势 2：检查用户能否调用

很多 dapp 会在按钮置灰前先 eth_call 一次：

1
2
3
4
5
6
7
8


async function canMint(contract, user) {
 try {
 await contract.callStatic.mint({ from: user, value: 0 });
 return true;
 } catch (e) {
 return false;
 }
}

按钮 disabled 状态根据这个判断——比让用户点了再 revert 用户体验好得多。

五、Gas 估算的几个特殊情况

1. payable 函数

1
2
3


const gas = await contract.estimateGas.buy({
 value: ethers.utils.parseEther("0.1")
});

不传 value 估算可能 revert（因为 msg.value < price）——estimateGas 时一定要带上预期的 value。

2. revert reason 解析

estimate 失败时只返回笼统错误。要拿具体原因，用 ethers 的 callStatic：

1
2
3
4
5


try {
 await contract.callStatic.method(...args);
} catch (e) {
 console.log(e.reason); // "ERC20: insufficient balance"
}

3. EIP-1559 后的 fee 估算

estimateGas 只估 gas 用量，不估 gasPrice。EIP-1559 之后 gasPrice 由 baseFee + priorityFee 决定，要单独 query：

1
2
3


const fee = await provider.getFeeData();
// fee.maxFeePerGas
// fee.maxPriorityFeePerGas

六、节点行为的差异

不同节点对这两个 RPC 的实现细节有差异：

	Geth	Erigon	Nethermind	Reth
state override	✓	✓	✓	✓
默认 gas cap	50M	50M	100M	50M
历史 block call	✓	✓	✓	✓

gas cap 很关键——超过节点配置的 gas cap，estimate 会被截断报错（“gas required exceeds allowance”）。某些复杂交易（比如 Uniswap 大流动性 swap）可能超 50M gas，被默认 cap 卡住。RPC 提供商如 Alchemy / Infura 也有自己的 cap。

七、踩坑提醒

1. 不要用 estimate 当 view

很多新人写：

1
2


// ❌ 反例：用 estimateGas 拿"功能能否成功"
const ok = await contract.estimateGas.method(...).catch(() => false);

estimate 是"估 gas"——它只是顺带告诉你"会不会 revert"。真要查结果或验证，用 callStatic / eth_call。

2. eth_call 不会扣 gas

eth_call 是免费的——本地模拟、不上链。前端可以放心地频繁调用，但要注意 RPC 限流。

3. estimateGas 也不会扣 gas

即便 estimateGas 模拟时显示用了 200,000 gas——调用方不付钱。但 RPC 提供商可能按调用次数收费/限流。

4. block 参数的语义

"latest" / "pending" / 具体 block 号都行。pending 包含 mempool 里的未确认交易——估算"考虑当前其他人正在打的交易"时用 pending。但有些节点 pending 不可用。

5. archive node 才支持历史 block call

1

await contract.balanceOf(addr, { blockTag: 12345678 }); // 历史 block

非 archive 节点只保留最近 128 block 的状态——历史 block call 会失败。

6. 模拟环境和真实差异

estimate 时的 block.timestamp、block.number、coinbase 都和"真上链时"不同——对这些敏感的合约（如时间锁、伪随机），estimate 给的 gas 可能不准。

八、常见 Web3 库的封装

	eth_call	eth_estimateGas
ethers.js v5	`contract.callStatic.X()`	`contract.estimateGas.X()`
ethers.js v6	`contract.X.staticCall()`	`contract.X.estimateGas()`
web3.js	`contract.methods.X.call()`	`contract.methods.X.estimateGas()`
viem	`publicClient.simulateContract`	`publicClient.estimateContractGas`
Foundry cast	`cast call`	`cast estimate`

小结

把全文压一句：

eth_call 问『会发生什么』，eth_estimateGas 问『要花多少 gas』。两者都不上链，但用途完全不同。

工程实践：

view 查询永远用 eth_call
发 tx 前用 callStatic 预检 revert，用 estimateGas 估 gas，加 buffer 后再发
payable 函数 estimate 必带 value
revert reason 解析用 callStatic，不要靠 estimate 错误
EIP-1559 fee 单独 getFeeData

理解这两个的边界，你写 dapp 就不会再"为什么我估 gas 一直失败"——多数情况下你需要的不是 estimateGas，而是 eth_call。

Java MapStruct 实战：替你写完所有 BO/DTO/VO 转换

Fri, 21 Oct 2022 15:00:00 +0800

这件事每个 Java 项目都遇到

任何一个稍有规模的 Java 项目都会有这种代码：

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


// 数据库实体
public class UserEntity {
 private Long id;
 private String username;
 private String email;
 private LocalDateTime createTime;
 private Integer status;
}

// 给前端的 VO
public class UserVO {
 private String id; // 需要 toString
 private String username;
 private String email;
 private String createTime; // 需要格式化成 yyyy-MM-dd HH:mm:ss
 private String statusName; // 需要根据 status 翻译成中文
}

转换逻辑写起来无比啰嗦：

1
2
3
4
5
6
7
8
9


public UserVO toVO(UserEntity e) {
 UserVO vo = new UserVO();
 vo.setId(e.getId().toString());
 vo.setUsername(e.getUsername());
 vo.setEmail(e.getEmail());
 vo.setCreateTime(e.getCreateTime().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
 vo.setStatusName(StatusEnum.fromCode(e.getStatus()).getName());
 return vo;
}

加一个字段就要改这种模板代码两次（一次实体，一次转换）。这是最容易出 bug 又最浪费时间的代码——人懒了一定会漏字段。

社区有几种主流解法：

方案	性能	类型安全	字段增减提示
手写	高	✓	编译期
`BeanUtils.copyProperties`	低（反射）	✗	无
`BeanCopier` (cglib)	中高	✗	无
MapStruct（编译期生成）	高（接近手写）	✓	编译期

MapStruct 是目前这件事最成熟的方案。 它不是运行时反射，而是在编译时由 APT 生成转换代码——既类型安全，又性能接近手写。

一、最小可运行 Demo

1. 引入依赖

1
2
3
4
5


<dependency>
 <groupId>org.mapstruct</groupId>
 <artifactId>mapstruct</artifactId>
 <version>1.5.5.Final</version>
</dependency>

maven-compiler-plugin 配置（关键）：

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


<plugin>
 <artifactId>maven-compiler-plugin</artifactId>
 <configuration>
 <annotationProcessorPaths>
 <path>
 <groupId>org.mapstruct</groupId>
 <artifactId>mapstruct-processor</artifactId>
 <version>1.5.5.Final</version>
 </path>
 <path>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok</artifactId>
 <version>1.18.30</version>
 </path>
 <path>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok-mapstruct-binding</artifactId>
 <version>0.2.0</version>
 </path>
 </annotationProcessorPaths>
 </configuration>
</plugin>

⚠️ 用 Lombok 的话必须加 lombok-mapstruct-binding——否则 Lombok 生成的 getter/setter 在 MapStruct 跑 APT 时还看不到，会编译失败。

2. 写映射接口

1
2
3
4
5
6
7


@Mapper(componentModel = "spring")
public interface UserMapper {

 UserVO toVO(UserEntity entity);

 List<UserVO> toVOList(List<UserEntity> entities);
}

接口不需要写实现，编译时会自动生成 UserMapperImpl。

业务里直接注入：

1
2
3
4
5
6
7
8


@Service
public class UserService {
 @Autowired UserMapper userMapper;

 public UserVO get(Long id) {
 return userMapper.toVO(userRepo.findById(id).orElseThrow());
 }
}

componentModel = "spring" 让 Mapper 自动成为 Spring Bean，可以 @Autowired。

3. 看一眼生成的代码

target/generated-sources/annotations/.../UserMapperImpl.java：

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


@Component
public class UserMapperImpl implements UserMapper {
 @Override
 public UserVO toVO(UserEntity entity) {
 if (entity == null) return null;
 UserVO vo = new UserVO();
 vo.setId(entity.getId() == null ? null : entity.getId().toString());
 vo.setUsername(entity.getUsername());
 vo.setEmail(entity.getEmail());
 // ...
 return vo;
 }
}

这就是手写代码——只是不用你写。

二、字段名/类型不匹配的处理

字段名不一致：`@Mapping`

1
2
3
4
5
6
7


@Mapper(componentModel = "spring")
public interface OrderMapper {
 @Mapping(target = "orderNo", source = "code")
 @Mapping(target = "userName", source = "user.name") // 嵌套属性
 @Mapping(target = "amount", source = "money", numberFormat = "#,##0.00")
 OrderVO toVO(OrderEntity entity);
}

支持几个常用配置：

source / target：源字段、目标字段
dateFormat：日期格式化
numberFormat：数字格式化
defaultValue：源为 null 时的默认值
expression：自定义表达式
ignore = true：跳过这个字段

类型转换：自动 + 自定义

MapStruct 已经内置了大量类型转换：

基本类型互转
包装类 ↔ 基本类型
String ↔ 日期/数字
枚举 ↔ String/Integer
集合 ↔ 集合（递归调用同包的其他 mapper）

复杂转换可以用自定义方法：

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


@Mapper(componentModel = "spring", uses = StatusConverter.class)
public interface UserMapper {
 @Mapping(target = "statusName", source = "status")
 UserVO toVO(UserEntity entity);
}

@Component
public class StatusConverter {
 public String toStatusName(Integer status) {
 return StatusEnum.fromCode(status).getName();
 }
}

uses 把转换器注册进来，MapStruct 会自动按方法签名匹配——不需要在每个 @Mapping 上指定。

三、反向映射：`@InheritInverseConfiguration`

实体到 VO 写过映射后，VO 到实体的反向映射通常是镜像的：

1
2
3
4
5
6
7
8
9


@Mapper(componentModel = "spring")
public interface UserMapper {

 @Mapping(target = "id", source = "userId")
 UserVO toVO(UserEntity entity);

 @InheritInverseConfiguration // 自动反向：userId → id
 UserEntity toEntity(UserVO vo);
}

减少重复声明。

四、更新现有对象：`@MappingTarget`

修改场景下，前端只传变更字段，要把 DTO 合并到现有实体：

1
2
3
4
5
6


@Mapper(componentModel = "spring")
public interface UserMapper {

 @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
 void updateEntity(UserUpdateDTO dto, @MappingTarget UserEntity entity);
}

1
2
3


UserEntity entity = userRepo.findById(id).orElseThrow();
userMapper.updateEntity(dto, entity); // 只覆盖非 null 字段
userRepo.save(entity);

NullValuePropertyMappingStrategy.IGNORE 让 null 不参与覆盖——这就是"只更新前端传了的字段"语义。

五、集合与分页转换

集合转换默认就支持，注意点是集合元素的类型也要有对应映射：

1
2
3
4
5
6
7


@Mapper(componentModel = "spring")
public interface OrderMapper {
 OrderVO toVO(OrderEntity entity);
 List<OrderVO> toVOList(List<OrderEntity> entities);

 OrderItemVO toItemVO(OrderItemEntity item); // 子元素的映射
}

集合内的元素 MapStruct 会自动调对应的 toItemVO。

分页对象（Page<T>）通常这样写：

1
2
3


default Page<UserVO> toVOPage(Page<UserEntity> page) {
 return page.map(this::toVO);
}

default 方法允许在接口里写实现，方便混合自定义逻辑。

六、几种实用进阶用法

1. 一次返回带多源对象的合并

订单 VO 里既要订单字段又要用户字段：

1
2
3
4


@Mapping(target = "orderNo", source = "order.orderNo")
@Mapping(target = "userName", source = "user.name")
@Mapping(target = "amount", source = "order.amount")
OrderVO toVO(OrderEntity order, UserEntity user);

2. 表达式 / 常量

1
2
3


@Mapping(target = "version", constant = "1.0")
@Mapping(target = "fullName", expression = "java(entity.getFirstName() + \" \" + entity.getLastName())")
UserVO toVO(UserEntity entity);

3. 嵌套对象的子映射

1
2
3


@Mapping(target = "addressVO.street", source = "address.street")
@Mapping(target = "addressVO.city", source = "address.city")
UserVO toVO(UserEntity entity);

4. 通用配置：`@MapperConfig`

很多 Mapper 共用相同设置，抽出一个配置接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@MapperConfig(
 componentModel = "spring",
 nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE
)
public interface CentralMapperConfig {}

@Mapper(config = CentralMapperConfig.class)
public interface UserMapper {
 UserVO toVO(UserEntity entity);
}

5. 测试 Mapper 也很简单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


class UserMapperTest {
 UserMapper mapper = Mappers.getMapper(UserMapper.class);

 @Test
 void shouldMapToVO() {
 UserEntity entity = new UserEntity(1L, "张三", "z@x.com");
 UserVO vo = mapper.toVO(entity);
 assertEquals("1", vo.getId());
 assertEquals("张三", vo.getUsername());
 }
}

不依赖 Spring，单元测试很快。

七、性能对比（简单基准）

	QPS	相对手写
手写	26,000,000	1×
MapStruct	25,000,000	0.96×
BeanCopier (cglib)	19,000,000	0.73×
Spring BeanUtils	4,500,000	0.17×
Apache Commons BeanUtils	1,200,000	0.05×

MapStruct 几乎等于手写——这是因为它本来就是手写代码（编译时生成）。BeanUtils 那种反射方案在大数据量场景下性能差距非常显著。

八、踩坑提醒

Lombok 一起用要加 lombok-mapstruct-binding——否则编译期看不到 Lombok 生成的 getter
生成的代码要每次 build 一次——IDE 看不见 UserMapperImpl 是因为没编译过；Rebuild Project 一下
接口方法不要互相覆盖——同一个接口里两个方法签名相同，MapStruct 不知道生成哪个
uses = ... 的转换器要可被注入——自定义转换器需要 @Component 才能在 spring 模式下工作
空集合 vs null：默认源为 null 会返回 null，很多业务希望返回空集合——加 nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT
不要在转换器里写复杂业务——转换器应该是纯映射，不要做 DB 查询或 RPC 调用，否则 MapStruct 的"性能 + 简洁"双优势就崩了

九、一份生产级模板

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


@Mapper(
 componentModel = "spring",
 unmappedTargetPolicy = ReportingPolicy.WARN, // 漏字段编译警告
 nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE,
 uses = { CommonConverter.class }
)
public interface UserMapper {

 @Mapping(target = "id", source = "id", defaultValue = "0L")
 @Mapping(target = "createTime", source = "createTime", dateFormat = "yyyy-MM-dd HH:mm:ss")
 @Mapping(target = "statusName", source = "status")
 UserVO toVO(UserEntity entity);

 List<UserVO> toVOList(List<UserEntity> entities);

 @InheritInverseConfiguration
 @Mapping(target = "createTime", ignore = true) // 实体的时间不让前端覆盖
 @Mapping(target = "id", ignore = true)
 UserEntity toEntity(UserCreateDTO dto);

 void updateEntity(UserUpdateDTO dto, @MappingTarget UserEntity entity);
}

小结

把全文压一句：

MapStruct 把『写转换代码』这件事从『反复劳动』变成『声明意图』——你只描述映射规则，编译器替你写实现，性能接近手写。

工程上几条建议：

新项目优先用 MapStruct，别再在生产代码里 BeanUtils.copyProperties
配 unmappedTargetPolicy = WARN 让编译警告帮你抓漏字段
复杂业务用自定义 Converter，但 Converter 里不要写 RPC/DB
Lombok 同时用一定要加 binding 依赖

把这件每天写、每天烦的事自动化掉，是工具的真正价值。

用 EasyExcel 导出复杂组织机构树到 Excel

Fri, 02 Sep 2022 15:30:00 +0800

一个让人头大的需求

业务方：“把公司全部部门、员工、汇报关系导出到 Excel”。打开他们用的 Word 模板：

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


+--------------+--------+--------+----------+--------+
| 一级部门 | 二级 | 三级 | 员工姓名 | 工号 |
+--------------+--------+--------+----------+--------+
| | | 一组 | 张三 | 001 |
| | | | 李四 | 002 |
| | 研发部 +--------+----------+--------+
| | | 二组 | 王五 | 003 |
| 技术中心 +--------+--------+----------+--------+
| | | | 赵六 | 004 |
| | 测试部 | | 钱七 | 005 |
+--------------+--------+--------+----------+--------+
| | | | ... | ... |
+--------------+--------+--------+----------+--------+

需求关键词：

层级关系：部门可能 1-5 层
单元格合并：同部门跨多行合并
数据量大：上千员工
样式要求：表头加粗、边框、分组色
导出快：用户等 30 秒会投诉

POI 拿来撸是噩梦——内存爆炸 + 写起来痛苦。EasyExcel 是这件事的事实标准答案——它把内存占用压到极致，API 也清爽很多。

本文用一个完整实例讲清楚 EasyExcel 导出树形结构 + 合并单元格的姿势。

一、EasyExcel 的核心优势

	Apache POI	EasyExcel
内存占用	一次性加载全部	流式写，几 MB 搞定
编码体验	大量 setCellValue	注解 + Java Bean
大数据量	容易 OOM	70 万行无压力
学习曲线	陡	平
复杂样式	灵活	灵活

EasyExcel 由阿里开源，本质是 POI 上加一层流式封装——背后还是 POI，但内存模型彻底改了。

二、最小可用 Demo

引入：

1
2
3
4
5


<dependency>
 <groupId>com.alibaba</groupId>
 <artifactId>easyexcel</artifactId>
 <version>3.3.2</version>
</dependency>

定义实体：

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


@Data
public class EmployeeRow {
 @ExcelProperty("一级部门")
 private String dept1;

 @ExcelProperty("二级部门")
 private String dept2;

 @ExcelProperty("三级部门")
 private String dept3;

 @ExcelProperty("员工姓名")
 private String name;

 @ExcelProperty("工号")
 private String empNo;
}

写出：

1
2
3
4
5


List<EmployeeRow> rows = buildRows(orgTree);

EasyExcel.write("org.xlsx", EmployeeRow.class)
 .sheet("组织架构")
 .doWrite(rows);

四行代码，搞定基础导出。

三、把组织树展平成行

业务里组织通常是个树——要导出必须展开成扁平的行集合。

树结构

1
2
3
4
5
6
7


@Data
public class OrgNode {
 private Long id;
 private String name;
 private List<OrgNode> children;
 private List<Employee> employees;
}

DFS 展平

 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


public List<EmployeeRow> flatten(List<OrgNode> roots) {
 List<EmployeeRow> rows = new ArrayList<>();
 for (OrgNode root : roots) {
 traverse(root, new ArrayDeque<>(), rows);
 }
 return rows;
}

private void traverse(OrgNode node, Deque<String> path, List<EmployeeRow> rows) {
 path.push(node.getName());

 if (node.getChildren() != null && !node.getChildren().isEmpty()) {
 for (OrgNode child : node.getChildren()) {
 traverse(child, path, rows);
 }
 }
 if (node.getEmployees() != null) {
 for (Employee e : node.getEmployees()) {
 EmployeeRow row = new EmployeeRow();
 // 把 path 从根到叶填到 dept1/2/3
 String[] depts = path.descendingIterator().hasNext()
 ? toArray(path.descendingIterator()) : new String[0];
 row.setDept1(depts.length > 0 ? depts[0] : "");
 row.setDept2(depts.length > 1 ? depts[1] : "");
 row.setDept3(depts.length > 2 ? depts[2] : "");
 row.setName(e.getName());
 row.setEmpNo(e.getEmpNo());
 rows.add(row);
 }
 }
 path.pop();
}

这一步得到了 Excel 的扁平行数据——树形被打平、每个员工对应一行。

四、单元格合并：组织树的核心

光打平还不够——同部门下多个员工，部门列应该合并。这是组织树导 Excel 最核心的需求。

思路：写完后再合并

EasyExcel 写时按行流式输出，不能在写入时直接判断"和上一行合并"。最稳妥的做法是：

先按扁平行写完
再用 POI 的 addMergedRegion 合并同列连续相同值

EasyExcel 提供了 WriteHandler 让你介入流程：

 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


public class TreeMergeHandler extends AbstractMergeStrategy {

 private final List<EmployeeRow> data;

 public TreeMergeHandler(List<EmployeeRow> data) { this.data = data; }

 @Override
 protected void merge(Sheet sheet, Cell cell, Head head, Integer relativeRowIndex) {
 // 处理 dept1, dept2, dept3 三列
 if (relativeRowIndex == null || relativeRowIndex == 0) return;

 int colIdx = cell.getColumnIndex();
 if (colIdx > 2) return; // 后两列不合并（员工姓名/工号列）

 int absoluteRow = cell.getRowIndex();
 String prevValue = sheet.getRow(absoluteRow - 1).getCell(colIdx).getStringCellValue();
 String currValue = cell.getStringCellValue();

 if (Objects.equals(prevValue, currValue)) {
 // 找到现有 region 并扩展，或新建
 for (int i = sheet.getNumMergedRegions() - 1; i >= 0; i--) {
 CellRangeAddress region = sheet.getMergedRegion(i);
 if (region.getFirstColumn() == colIdx
 && region.getLastRow() == absoluteRow - 1) {
 sheet.removeMergedRegion(i);
 sheet.addMergedRegion(new CellRangeAddress(
 region.getFirstRow(), absoluteRow, colIdx, colIdx));
 return;
 }
 }
 // 没找到，新建
 sheet.addMergedRegion(new CellRangeAddress(
 absoluteRow - 1, absoluteRow, colIdx, colIdx));
 }
 }
}

1
2
3
4


EasyExcel.write("org.xlsx", EmployeeRow.class)
 .registerWriteHandler(new TreeMergeHandler(rows))
 .sheet("组织架构")
 .doWrite(rows);

效果——同部门跨多行的部门列被合并成一个单元格。

五、样式：表头加粗 + 居中 + 边框

通过 HorizontalCellStyleStrategy 配置：

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


WriteCellStyle headerStyle = new WriteCellStyle();
headerStyle.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex());
headerStyle.setHorizontalAlignment(HorizontalAlignment.CENTER);
WriteFont headerFont = new WriteFont();
headerFont.setFontHeightInPoints((short) 12);
headerFont.setBold(true);
headerStyle.setWriteFont(headerFont);

WriteCellStyle bodyStyle = new WriteCellStyle();
bodyStyle.setHorizontalAlignment(HorizontalAlignment.CENTER);
bodyStyle.setVerticalAlignment(VerticalAlignment.CENTER);
bodyStyle.setBorderTop(BorderStyle.THIN);
bodyStyle.setBorderBottom(BorderStyle.THIN);
bodyStyle.setBorderLeft(BorderStyle.THIN);
bodyStyle.setBorderRight(BorderStyle.THIN);

EasyExcel.write("org.xlsx", EmployeeRow.class)
 .registerWriteHandler(new HorizontalCellStyleStrategy(headerStyle, bodyStyle))
 .registerWriteHandler(new TreeMergeHandler(rows))
 .sheet("组织架构")
 .doWrite(rows);

六、列宽自适应

LongestMatchColumnWidthStyleStrategy 让列宽根据内容长度自适应：

1

.registerWriteHandler(new LongestMatchColumnWidthStyleStrategy())

注意——它的算法是按"行最长字符串"算列宽，对中文支持不够好（一个汉字算一个字符宽，但实际显示更宽）。生产里通常自己写一个：

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


public class CJKColumnWidthHandler implements CellWriteHandler {
 @Override
 public void afterCellDispose(CellWriteHandlerContext ctx) {
 Cell cell = ctx.getCell();
 Sheet sheet = cell.getSheet();
 int colIdx = cell.getColumnIndex();
 int len = cell.getStringCellValue() != null
 ? estimateWidth(cell.getStringCellValue()) : 10;
 if (sheet.getColumnWidth(colIdx) < len * 256) {
 sheet.setColumnWidth(colIdx, Math.min(len * 256, 80 * 256));
 }
 }

 private int estimateWidth(String s) {
 int w = 0;
 for (char c : s.toCharArray()) {
 w += (c >= '一' && c <= '龥') ? 2 : 1;
 }
 return w;
 }
}

七、Web 接口下载

Spring Controller 写法：

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


@GetMapping("/export/org")
public void export(HttpServletResponse response) throws IOException {
 response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
 response.setCharacterEncoding("utf-8");
 String fileName = URLEncoder.encode("组织架构", "UTF-8").replaceAll("\\+", "%20");
 response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + fileName + ".xlsx");

 List<EmployeeRow> rows = orgService.flattenForExport();
 EasyExcel.write(response.getOutputStream(), EmployeeRow.class)
 .registerWriteHandler(new TreeMergeHandler(rows))
 .sheet("组织架构")
 .doWrite(rows);
}

文件名编码这块要小心——中文不处理浏览器下载会乱码。filename*=utf-8''xxx 是 RFC 5987 标准。

八、大数据量场景

数据量到几万、几十万行时，几个工程要点：

1. 用流式写

1
2
3
4
5
6
7
8


ExcelWriter writer = EasyExcel.write(outputStream, EmployeeRow.class).build();
WriteSheet sheet = EasyExcel.writerSheet("组织架构").build();
int batchSize = 1000;
for (int offset = 0; offset < total; offset += batchSize) {
 List<EmployeeRow> batch = orgService.getRows(offset, batchSize);
 writer.write(batch, sheet);
}
writer.finish();

每次只加载一批，JVM 内存不会爆。

2. 多 Sheet

单 Sheet 上限 1,048,576 行——超过要拆 Sheet：

1
2
3
4


for (int sheetNo = 0; sheetNo < sheetCount; sheetNo++) {
 WriteSheet sheet = EasyExcel.writerSheet(sheetNo, "Sheet" + sheetNo).build();
 writer.write(getRows(sheetNo), sheet);
}

3. 合并单元格的内存瓶颈

合并单元格的 addMergedRegion 信息是全量记录在内存里——大量合并会让导出再次膨胀。几万行 + 大量合并是 EasyExcel 也吃不消的场景——这种情况建议改用 CSV 或者拆分多 Sheet。

4. 异步导出

接口同步返回 30 秒会超时——大数据量必须异步：

flowchart LR
 User --> API[POST /export/job]
 API --> Job[创建任务记录]
 API --> Queue[发到 MQ]
 Worker[Worker] --> Queue
 Worker --> S3[导出到 S3/OSS]
 Worker --> Notify[推送通知/邮件]
 User --> Status[GET /export/status]
 Status --> S3

九、踩坑提醒

1. 模板模式 vs Bean 模式

简单导出用 @ExcelProperty 注解（Bean 模式）；表头复杂、含图片、需要复用的导出用 模板模式：

1
2
3
4


EasyExcel.write("out.xlsx")
 .withTemplate("template.xlsx")
 .sheet()
 .doWrite(data);

模板里用 {name} 占位符。

2. POI 版本冲突

EasyExcel 自带 POI 4.x，如果项目里有其他依赖引入了 POI 3.x，冲突会让 ClassNotFound。用 mvn dependency:tree 检查并 exclude。

3. 中文表头乱码

@ExcelProperty("中文表头") 一般没问题，但如果中文出现在动态字段（比如表头从配置读），要确保字符串编码 UTF-8。

4. 日期格式

1
2
3


@ExcelProperty("入职日期")
@DateTimeFormat("yyyy-MM-dd")
private LocalDate joinDate;

不加 @DateTimeFormat 会导成 Excel 的"序列号"格式（比如 44927）。

5. 数字精度

金额最好用 BigDecimal，并配合：

1
2
3


@ExcelProperty("金额")
@NumberFormat("#,##0.00")
private BigDecimal amount;

小结

把全文压一句：

导出复杂结构 Excel 的核心是『先扁平、再合并、再样式』——EasyExcel 把内存压到极致，写法干净，是 Java 项目里 Excel 导出的最佳选择。

工程要点：

业务层把树展开成扁平行——逻辑独立、便于测试
单元格合并用 WriteHandler，不要业务里自己控
大数据量必须流式 + 异步
样式用 Strategy，列宽用自定义中文 handler
生产代码记得设 Content-Disposition 处理中文文件名

把这套吃透，下次"导出报表"不再是噩梦——是个 1 小时就能搞定的标准任务。

JetCache 实战：Spring 项目里的多级缓存利器

Fri, 15 Apr 2022 17:00:00 +0800

为什么 Spring Cache 不够用

Spring Cache (@Cacheable/@CacheEvict) 是个好抽象——把"读数据先看缓存"这件事用注解优雅地表达出来。但用过的人都知道，它有几个和生产场景对不上的硬伤：

不支持过期时间——原生 @Cacheable 没法在注解上指定 TTL，要么改全局配置，要么自定义 CacheManager
不支持多级缓存——你要么全 Caffeine，要么全 Redis，没法"先查 Caffeine 再查 Redis"
没有自动刷新——缓存到期后第一个请求要等 DB，热点 key 必失效雪崩
没有防穿透——查询不存在的数据，每次都要打 DB
多实例 Caffeine 不一致——本地缓存各自一份，DB 改了一台缓存没刷
统计能力弱——命中率、QPS 都要自己埋点

阿里开源的 JetCache 把这些痛点几乎全方位补足。本文不写"JetCache 是什么"，直接讲它在生产里怎么用、踩什么坑。

一、最小可运行 Demo

引入：

1
2
3
4
5


<dependency>
 <groupId>com.alicp.jetcache</groupId>
 <artifactId>jetcache-starter-redis</artifactId>
 <version>2.7.5</version>
</dependency>

application.yml：

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


jetcache:
 statIntervalMinutes: 15 # 每 15 分钟打一次命中率统计日志
 areaInCacheName: false
 local:
 default:
 type: caffeine
 keyConvertor: jackson
 limit: 10000 # 本地最多缓存 10000 条
 expireAfterWriteInMillis: 60000
 remote:
 default:
 type: redis
 keyConvertor: jackson
 valueEncoder: java
 valueDecoder: java
 poolConfig:
 maxTotal: 50
 host: localhost
 port: 6379

启动类加注解：

1
2
3
4
5
6
7
8


@SpringBootApplication
@EnableCreateCacheAnnotation
@EnableMethodCache(basePackages = "com.app")
public class App {
 public static void main(String[] args) {
 SpringApplication.run(App.class, args);
 }
}

业务里直接用：

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


@Service
public class UserService {

 @Cached(name = "user:", key = "#id",
 cacheType = CacheType.BOTH,
 expire = 300, localExpire = 60,
 localLimit = 1000)
 public User getById(Long id) {
 return userMapper.selectById(id);
 }

 @CacheInvalidate(name = "user:", key = "#user.id")
 public void update(User user) {
 userMapper.updateById(user);
 }
}

CacheType.BOTH 即为多级缓存——先查本地 Caffeine，没命中再查 Redis，再没有才打 DB。

二、多级缓存背后的访问模型

flowchart LR
 Req([请求]) --> L1{本地 Caffeine}
 L1 -->|命中| Return1[返回]
 L1 -->|未命中| L2{远程 Redis}
 L2 -->|命中| Fill1[回写 Caffeine] --> Return2[返回]
 L2 -->|未命中| DB[(DB / RPC)]
 DB --> Fill2[写 Redis + Caffeine] --> Return3[返回]

这套模型解决了几个核心问题：

大部分热点请求被本地 Caffeine 拦截，QPS 飙升
本地缓存丢失（重启、扩容）时由 Redis 兜底，避免直接打 DB
DB 压力被收敛到"每个 key 第一次访问"那一次

三、自动刷新：解决雪崩的杀手锏

普通缓存到期后，第一个请求要等 DB——如果 key 是热点，并发会打穿到 DB（缓存击穿）。JetCache 的 @Cached 提供 refresh 选项：

1
2
3
4
5
6
7
8


@Cached(name = "hotConfig:", key = "#key",
 cacheType = CacheType.BOTH,
 expire = 600,
 cacheNullValue = true)
@CacheRefresh(refresh = 60, stopRefreshAfterLastAccess = 600)
public Config get(String key) {
 return configMapper.selectByKey(key);
}

参数解读：

refresh = 60：每 60 秒后台异步刷新一次（即便 key 还没过期）
stopRefreshAfterLastAccess = 600：如果 600 秒没人访问这个 key 就停止刷新（避免无效刷新冷数据）
cacheNullValue = true：缓存 null 也能加速防穿透

自动刷新让热点 key 永远不会"出现在缓存外"——即便 DB 短暂故障，前端拿到的也只是稍微旧一点的数据，不会瞬间打穿。

四、防穿透：缓存空值

查询一个不存在的 ID，按朴素实现每次都打 DB：

1

请求 user/9999999 → 缓存没有 → 查 DB 没有 → 不写缓存 → 下次还是打 DB

JetCache 解法：

1
2
3
4
5
6
7


@Cached(name = "user:", key = "#id",
 cacheType = CacheType.BOTH,
 expire = 600,
 cacheNullValue = true) // ★ 关键
public User getById(Long id) {
 return userMapper.selectById(id);
}

cacheNullValue = true 让"DB 返回 null"也被缓存，短时间内连续查不存在的 key 不会重复打 DB。

注意：缓存 null 的 TTL 通常应该比正常数据短一些，避免数据从无到有时延迟太久才被前端看到。可以两个 @Cached 分开缓存，或者 TTL 设短点。

五、批量缓存：`@CacheRefresh` 不灵的场景用编程式 API

@Cached 注解适合"一个方法一个 key"，但批量场景（一次查 100 个用户）用注解就别扭。JetCache 提供了编程式 API：

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


@CreateCache(name = "user:", expire = 300, cacheType = CacheType.BOTH)
private Cache<Long, User> userCache;

public Map<Long, User> getByIds(List<Long> ids) {
 // 一次性批量查缓存
 Map<Long, User> cached = userCache.getAll(new HashSet<>(ids));
 
 Set<Long> missed = ids.stream()
 .filter(id -> !cached.containsKey(id))
 .collect(Collectors.toSet());

 if (!missed.isEmpty()) {
 Map<Long, User> fromDb = userMapper.selectByIds(missed)
 .stream().collect(Collectors.toMap(User::getId, Function.identity()));
 userCache.putAll(fromDb);
 cached.putAll(fromDb);
 }
 return cached;
}

getAll / putAll 在 Redis 上是 pipeline 批量执行，比 N 次单独 get 快得多。

六、本地缓存一致性：广播失效

多级缓存最大的隐患是——多实例本地缓存各自一份，一台改了 DB 后只清自己本地的，另一台还是旧数据。

JetCache 内置了 广播失效（基于 Redis Pub/Sub）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


jetcache:
 local:
 default:
 type: caffeine
 keyConvertor: jackson
 syncLocal: true # ⚠️ 关键：开启跨 JVM 本地失效同步
 remote:
 default:
 broadcastChannel: app-cache-channel  # 启用广播
 type: redis.lettuce
 ...

broadcastChannel 与 syncLocal: true 缺一不可——只配 broadcastChannel 不开 syncLocal，本地 Caffeine 不会订阅广播，跨 JVM 失效不生效。

每次 @CacheInvalidate 触发时：

删 Redis
通过 Redis Pub/Sub 同时发广播
所有订阅方（包括发起方自己）收到广播 → 清各自本地

不是"先清自己再广播给别人"——本地清理与广播走的是同一条订阅路径，发起方也是订阅方之一。

sequenceDiagram
 Instance1->>Redis: DEL user:1
 Instance1->>Redis: PUBLISH "expire user:1"
 Redis->>Instance1: 自己也收到广播
 Redis->>Instance2: 收到广播
 Redis->>Instance3: 收到广播
 Instance1->>Caffeine: invalidate (本地)
 Instance2->>Caffeine: invalidate
 Instance3->>Caffeine: invalidate

这是用本地缓存时绝对要打开的特性——不开它，多实例本地缓存几乎没法用。

七、监控统计：开箱即用

statIntervalMinutes: 15 配置后，每 15 分钟会在日志里打出每个 cache 的命中率：

1
2
3


cache | qps | rate(local) | rate(remote) | hit | miss
user: | 12345 | 82.30% | 65.40% | 9876 | 234
hotConfig: | 321 | 95.20% | 80.00% | 300 | 21

把这个表周期性吐到监控系统（Prometheus / SkyWalking / 日志大盘），直接定位"哪个 cache 命中率低"——通常意味着 TTL 太短、key 设计有问题、或者业务实际并不重复。

八、踩坑提醒

1. `keyConvertor` 必须配

不配的话默认用对象的 toString() 当 key——对象 hash 变了 key 就不一样，缓存命中率瞬间归零。jackson / fastjson2 是常见选择。

2. 序列化版本兼容

valueEncoder: java 用 JDK 序列化，类字段加减会直接破坏序列化兼容。生产推荐 kryo 或 jackson：

1
2
3
4


remote:
 default:
 valueEncoder: kryo5
 valueDecoder: kryo5

3. 本地容量要算清楚

localLimit = 10000 说着轻巧，但每条数据多大决定了内存占用——10000 条用户对象可能 100MB。生产前务必算 size。

4. CacheType.LOCAL 慎用

只用本地缓存时数据一致性靠不住，强烈建议至少 BOTH——除非你的数据就是只读且全量加载的（如配置）。

5. 注解和方法签名

@Cached 的 key 不要写成 #user.id——null 时会 NPE。用 SpEL 的安全访问：'#user?.id'。

6. 不缓存 List<复杂对象>

复杂对象列表序列化反序列化都是开销，多个细粒度 cache 比一个大 cache 性能好。把"分页结果"缓存当反例——分页参数一变就 miss，命中率极低。

九、和其他方案对比

方案	多级	自动刷新	防穿透	一致性广播	注解友好	学习成本
Spring Cache 原生	✗	✗	△	✗	✓	低
Caffeine 单层	✗	△	△	✗	△	低
Redis 单层	✗	✗	△	✗	△	低
JetCache	✓	✓	✓	✓	✓	中
Redisson Cache	△	△	△	✓	△	中高

JetCache 在"开箱即用程度"上目前在 Java 生态里比较突出——它的核心价值不是缓存本身，而是把生产经验固化进了注解。

十、实战建议

先 BOTH 后调优——默认就用本地 + Redis 两级，稳定后再针对低命中率 cache 单独配
TTL 至少 5 分钟——TTL 过短的缓存几乎不会命中
热点 key 一律开 @CacheRefresh——避免雪崩
多实例必开广播失效——不开会让多实例本地缓存的数据一致性失控
cacheNullValue = true——除非业务明确不需要防穿透
监控命中率——低于 70% 的 cache 都要重新审视设计

1
2
3
4
5
6
7
8
9


// 一个生产推荐的"全功能"配置
@Cached(name = "user:", key = "#id",
 cacheType = CacheType.BOTH,
 expire = 600, localExpire = 60,
 cacheNullValue = true)
@CacheRefresh(refresh = 120, stopRefreshAfterLastAccess = 1800)
public User getById(Long id) {
 return userMapper.selectById(id);
}

小结

一句话压缩 JetCache 的价值：

把『多级缓存 + 自动刷新 + 防穿透 + 广播失效 + 监控』这五件该做但 Spring Cache 不做的事，全部塞进了注解里。

它解决的不是"缓存有没有"的问题，是"把缓存做对“的问题。

工程上记住几条：

默认 BOTH，TTL ≥ 5 分钟
热点开 @CacheRefresh
多实例必开广播失效
cacheNullValue 防穿透
命中率监控周期性看一眼

把这些吃透，缓存这层就基本不会再出大事故了。

智能合约的四种调用方式：Call / CallCode / DelegateCall / StaticCall

Thu, 17 Mar 2022 16:00:00 +0800

一段看似平平无奇的代码，行为完全不同

四个看起来很像的调用：

1
2
3
4


target.call(data); // call
target.callcode(data); // callcode（已弃用）
target.delegatecall(data); // delegatecall
target.staticcall(data); // staticcall

它们都是"调另一个合约"——但存储上下文、msg.sender、能否改状态完全不同。用错任何一个轻则无效，重则被攻击者利用整个协议归零。

本文把这四种调用的差异系统讲清楚，并配代码例子说明各自用法和风险。

一、四者本质对比

EVM 中合约调用的"上下文"由三个核心要素组成：

代码（Code）：要执行哪段字节码？
存储（Storage）：读写哪个合约的存储？
msg.sender / msg.value：调用者身份是谁？

四种调用对这三个要素的处理：

	执行的代码	操作的存储	msg.sender	msg.value	能否改状态
`call`	target	target	caller	可传值	✓
`callcode`	target	caller	caller	可传值	✓
`delegatecall`	target	caller	原发起者	原 value	✓
`staticcall`	target	target	caller	不可传值	✗ 只读

callcode 已经被官方标记为 deprecated（功能被 delegatecall 替代），实战中几乎不用。重点是 call / delegatecall / staticcall 三种。

二、call：最朴素的"远程调用"

1
2
3
4
5
6
7
8


contract Caller {
 function callTarget(address target) external payable {
 (bool ok, bytes memory data) = target.call{value: msg.value}(
 abi.encodeWithSignature("doSomething(uint256)", 100)
 );
 require(ok, "call failed");
 }
}

call 的语义是——让对方合约执行对方的代码、操作对方的存储。

执行 target 的代码
改 target 的存储
在 target 看来，msg.sender = Caller 这个调用方
可以转账（{value: x}）

这就是一次"标准的合约间调用"。

典型场景

转账给一个普通地址：recipient.call{value: amount}("")
调用未知接口：当目标合约接口不固定时（如 ERC-721 的 onERC721Received 钩子），用 call

注意点

call 失败不会自动 revert ——返回 bool ok，要自己 require
重入风险：call 触发外部代码执行，可能再调回来——经典 The DAO 漏洞就是这个

三、delegatecall：用别人的代码、操作自己的存储

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


contract Proxy {
 address public implementation;

 fallback() external payable {
 address impl = implementation;
 assembly {
 calldatacopy(0, 0, calldatasize())
 let result := delegatecall(gas(), impl, 0, calldatasize(), 0, 0)
 returndatacopy(0, 0, returndatasize())
 switch result
 case 0 { revert(0, returndatasize()) }
 default { return(0, returndatasize()) }
 }
 }
}

delegatecall 的语义是——借用对方的字节码逻辑，但操作的是自己的存储和上下文。

执行 target 的代码
改 caller 的存储（不是 target 的！）
msg.sender 是原始调用者（不是 caller）
msg.value 也是原始的

典型场景：代理升级模式

可升级合约（OpenZeppelin Proxy / UUPS）的根基就是 delegatecall：

flowchart LR
 User --> Proxy
 Proxy -- delegatecall --> Logic
 Proxy -.存储在.-> Storage

Proxy 把所有调用 delegatecall 给 Logic 合约——Logic 操作的存储是 Proxy 的，所以升级 Logic 不影响数据。

致命陷阱：存储槽冲突

delegatecall 操作 caller 的存储，但用的是 target 的存储槽布局——两边布局必须严格对齐。

1
2
3
4
5
6
7
8
9


contract LogicV1 {
 address public owner; // slot 0
 uint256 public counter; // slot 1
}

contract LogicV2 {
 uint256 public counter; // slot 0 ← 和 V1 的 owner 撞了
 address public owner; // slot 1
}

升级到 V2 后，原来 owner 槽存的地址被当作 counter 解读——协议直接报废。

致命陷阱二：误用 delegatecall 给陌生地址

1
2
3


function execute(address target, bytes calldata data) external onlyOwner {
 target.delegatecall(data); // ❌ 极度危险
}

如果攻击者诱导 owner 调用此函数指向恶意 target，target 的代码可以任意改 caller 的存储——包括把 owner 改成攻击者地址。

历史上的 Parity Wallet 漏洞、Audius 攻击等，都是 delegatecall 滥用导致的灾难。

delegatecall 必须只指向你自己控制的、白名单内的合约。

四、staticcall：只读调用

1
2
3
4
5
6
7


function readSomething(address target) external view returns (uint256) {
 (bool ok, bytes memory data) = target.staticcall(
 abi.encodeWithSignature("getValue()")
 );
 require(ok, "staticcall failed");
 return abi.decode(data, (uint256));
}

staticcall 是 EIP-214 引入——和 call 几乎一样，但强制只读：

执行 target 的代码
改 target 的存储——不行，只读
不能转账
target 内部任何 SSTORE / LOG / CREATE 都会让调用 revert

典型场景

view / pure 函数的调用——Solidity 编译器会自动用 staticcall
集成第三方合约的查询：你想查别人合约状态但不信任它会改你状态——staticcall 强制只读

1
2
3
4


function getPriceFromOracle(IOracle oracle) external view returns (uint256) {
 // 编译器自动选 staticcall
 return oracle.price();
}

为什么重要

没有 staticcall 之前，要"安全地查询别人的合约"非常麻烦——对方合约可能在 view 函数里偷偷改状态（虽然不该）。staticcall 从 EVM 层面强制只读——这是一个安全保障。

五、callcode：已弃用

1

target.callcode(data); // 已 deprecated

callcode 是 delegatecall 的早期版本，唯一区别是 msg.sender 不会保留为原始调用者——这通常是个 bug 而不是 feature。所以 Solidity 0.5.0 之后 callcode 被禁用，全部用 delegatecall。

新代码里永远不要写 callcode。

六、四种调用的"决策树"

flowchart TD
 Start([要调用另一个合约?])
 Start --> S{需要写状态?}
 S -->|不需要，只查询| Static[staticcall]
 S -->|需要写| Self{改的是自己的存储 or 对方的?}
 Self -->|对方的存储 - 远程调用| Call[call]
 Self -->|自己的存储 - 借代码| Trust{对方合约 100% 可信?}
 Trust -->|是| Delegate[delegatecall]
 Trust -->|否| Avoid[别 delegatecall！]

七、Solidity 高级语法的隐式调用

直接写函数调用时，Solidity 会根据函数修饰符自动选择：

1
2
3


ITarget(addr).viewFn(); // staticcall
ITarget(addr).pureFn(); // staticcall
ITarget(addr).normalFn(); // call

view / pure → staticcall
普通函数 → call
delegatecall 永远要显式写——没有"自动 delegatecall"

这是合理的——delegatecall 太危险，必须开发者明确知道自己在做什么。

八、几个工程实践

1. call 一律检查返回值

1
2


(bool ok, ) = target.call(data);
require(ok, "call failed");

不检查就忽略错误，等于"我以为调用成功了，其实没有"——脏数据由此而生。

2. 转账永远用 call 不要用 transfer

老代码：

1

recipient.transfer(amount); // ❌ 现代不推荐

transfer 一直限制 2300 gas（这点从 Solidity 引入 transfer 时就如此）。真正让它频繁出问题的是 EIP-2929（Berlin 升级，2021-04）——抬高了 SLOAD/CALL 等状态访问的 gas 成本，接收方 fallback 里很多原本能跑过的操作再也挤不进 2300 gas，导致 OOG。现代写法：

1
2


(bool ok, ) = recipient.call{value: amount}("");
require(ok, "transfer failed");

3. delegatecall 配 onlyOwner / 白名单

1
2
3
4
5
6
7


mapping(address => bool) public trustedTargets;

function delegateAction(address target, bytes calldata data) external onlyOwner {
 require(trustedTargets[target], "not trusted");
 (bool ok, ) = target.delegatecall(data);
 require(ok);
}

永远不要让外部参数决定 delegatecall 的目标。

4. staticcall 保证只读

集成新协议时——只查询、不修改：

1

ISomeProtocol(addr).getInfo(); // 用 view 接口，编译器自动 staticcall

如果对方接口没声明 view 但你确定它只读——可以手动 staticcall：

1

(bool ok, bytes memory data) = addr.staticcall(abi.encodeWithSignature("getInfo()"));

如果对方实际改了状态，staticcall 会让交易失败——EVM 层面拦截，比靠开发者自觉安全。

5. 用 OpenZeppelin Address 库

1
2
3
4
5


using Address for address;

target.functionCall(data); // 安全的 call + revert
target.functionStaticCall(data); // 安全的 staticcall
target.functionDelegateCall(data); // 安全的 delegatecall（要白名单）

OZ 的封装多了 require、revert reason 解析等——比裸 call 安全得多。

九、几个真实案例

案例 1：Parity Wallet 的 14 万 ETH（2017）

Parity 的多签钱包用 delegatecall 委托给一个共享 Library。攻击者发现可以直接调用 Library 的 init 函数把自己设成 owner——再调用 kill 函数，整个 Library 自毁，所有依赖它的钱包永久无法转账。

教训：delegatecall 目标合约的所有 public/external 函数都要审慎设计——public 入口被外部直接调用 + delegatecall 同时滥用，就是这种灾难。

案例 2：Audius 治理攻击（2022）

Audius 协议合约存在 storage collision + initialize 未保护双重 bug——存储槽布局错位让攻击者可以重新调用 initialize 把自己设为治理 guardian，然后通过提交并自我通过的恶意治理提案转走社区池里约 1860 万 AUDIO（约 600 万美元）。

教训：proxy 模式下，所有可升级合约的 initialize 必须加 initializer 修饰符防止重复调用，并且基类与子类的 storage 布局必须严格对齐——这两个 bug 任何一个不出，攻击都成立不了。

案例 3：The DAO（2016）

经典重入——call 触发的外部调用导致重新进入合约，余额还没扣就被反复提款。

教训：调用外部前先改自己的状态（Checks-Effects-Interactions 模式）。

十、调试工具

Foundry trace：forge test -vvvv 能看到每一层 call/delegatecall/staticcall 的细节
Tenderly：可视化交易调用链路
Etherscan trace：交易详情里的"Internal Txns"标签

调试 delegatecall 出现"为什么状态没变 / 变错"的问题——第一步永远是看清楚到底是 call 还是 delegatecall，存储槽对齐没。

小结

把全文压一句：

call 是远程调用、delegatecall 是借代码、staticcall 是强制只读、callcode 是历史。四者用错就是漏洞。

工程上几条铁律：

call 一定要 require(ok)
delegatecall 只指向自己控制的、白名单内的合约
delegatecall 升级要严格保持存储布局
查询用 staticcall 比信任 view 更安全
永远不要 callcode
转账用 call{value:...} 不用 transfer

把这四种调用的语义吃透——你看 OpenZeppelin / Aave / Uniswap 的代码就能瞬间看懂"为什么这里要这么写"。

Spring Boot 中被低估的扩展点——EnvironmentPostProcessor

Fri, 12 Nov 2021 15:30:00 +0800

一个真实的烦恼

每个上规模的项目都会遇到这种需求：

启动时要从某个外部源（密钥管理系统、配置中心、加密的 KMS）拿配置
配置要在 Spring 启动最早期就生效，因为后面的 Bean 初始化都依赖它
不能改业务代码——业务代码里只想看到普通的 @Value("${db.password}")

最常见的几种做法：

@Value：太晚，只能取已经加载好的属性
@PropertySource：能加载文件，但支持不了复杂逻辑（解密、调远程服务）
手动在 main 里 set：丑陋且和 Spring 配置体系脱节
写一个 @PostConstruct：太晚——很多 Bean（如数据源）已经基于错误密码初始化失败了

正确答案是 Spring Boot 提供的一个相对"冷门但极其关键"的扩展点——EnvironmentPostProcessor。

它是什么，处于什么位置

Spring Boot 的启动过程里，最早能干预配置的扩展点就是它：

flowchart TD
 A[SpringApplication.run] --> B[加载 spring.factories / SPI]
 B --> C[准备 Environment]
 C --> D["应用 EnvironmentPostProcessor
(每个 Processor 拿到 Environment 都能读、能加、能改)"]
 D --> E["@PropertySource 加载、application.yml 加载"]
 E --> F[ApplicationContext 创建]
 F --> G[Bean 初始化（含 @Value / @ConfigurationProperties）]

关键时机：

比 application.yml 加载完之后（你能读到已有配置）
比 Bean 初始化之前（你的修改对 @Value 全部生效）

也就是说——它是 Spring 配置体系的最后一道"前置插入点"。

一个最小可运行的例子

我们假设要做一件事：启动时根据 spring.profiles.active 自动注入一组运行时元数据（机器名、IP、构建版本号等）。

步骤 1：写一个 EnvironmentPostProcessor

 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


public class RuntimeMetaPostProcessor implements EnvironmentPostProcessor, Ordered {

 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 Map<String, Object> meta = new HashMap<>();
 meta.put("runtime.host", getHostName());
 meta.put("runtime.ip", getHostAddress());
 meta.put("runtime.startedAt", LocalDateTime.now().toString());
 meta.put("runtime.jvmVersion", System.getProperty("java.version"));

 // 把这些值作为最高优先级 PropertySource 注入
 env.getPropertySources().addFirst(new MapPropertySource("runtime-meta", meta));
 }

 @Override public int getOrder() { return Ordered.HIGHEST_PRECEDENCE + 10; }

 private String getHostName() {
 try { return InetAddress.getLocalHost().getHostName(); }
 catch (Exception e) { return "unknown"; }
 }
 private String getHostAddress() {
 try { return InetAddress.getLocalHost().getHostAddress(); }
 catch (Exception e) { return "unknown"; }
 }
}

步骤 2：注册

src/main/resources/META-INF/spring.factories（Spring Boot 2.x）：

1
2


org.springframework.boot.env.EnvironmentPostProcessor=\
com.app.config.RuntimeMetaPostProcessor

Spring Boot 3.x 改用 META-INF/spring/org.springframework.boot.env.EnvironmentPostProcessor.imports：

1

com.app.config.RuntimeMetaPostProcessor

步骤 3：业务里随便用

1
2
3
4
5


@Value("${runtime.host}")
private String host;

@Value("${runtime.ip}")
private String ip;

启动看到效果：

1
2
3


runtime.host=DESKTOP-ABC123
runtime.ip=192.168.1.101
runtime.startedAt=2021-11-12T15:30:11

它最有价值的几个真实场景

场景 1：数据库密码从 KMS / Vault 解密

业务里 application.yml 写的是密文，启动时解密后塞回去：

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


public class DecryptPostProcessor implements EnvironmentPostProcessor {

 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 String encrypted = env.getProperty("spring.datasource.password");
 if (encrypted != null && encrypted.startsWith("ENC(")) {
 String decrypted = decryptFromKms(encrypted);
 Map<String, Object> map = Map.of("spring.datasource.password", decrypted);
 env.getPropertySources().addFirst(new MapPropertySource("decrypted", map));
 }
 }
}

业务代码完全不知道密码加密过——这是它最干净的姿势。

场景 2：从配置中心拉配置

虽然 Spring Cloud Config / Nacos / Apollo 都有自己的 starter，但它们底层就是基于 EnvironmentPostProcessor / BootstrapContext 实现的。理解这个扩展点，你就能看懂这些组件的源码逻辑。

例如自己写一个最小的"远程配置中心客户端"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public class RemoteConfigPostProcessor implements EnvironmentPostProcessor {
 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 String app_id = env.getProperty("app.id");
 String env_name = env.getProperty("spring.profiles.active", "dev");

 Map<String, Object> remote = fetchFromRemote(app_id, env_name);
 env.getPropertySources().addLast(new MapPropertySource("remote-config", remote));
 }
}

addLast 的语义是"远程配置优先级低于本地"——本地能覆盖远程；反过来 addFirst 是"远程覆盖本地"。位置选择是核心设计决策。

场景 3：开发/测试自动开启功能开关

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


public class DevModePostProcessor implements EnvironmentPostProcessor {
 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 String[] active = env.getActiveProfiles();
 if (Arrays.asList(active).contains("dev")) {
 Map<String, Object> overrides = Map.of(
 "logging.level.com.app", "DEBUG",
 "spring.jpa.show-sql", "true",
 "feature.mock-payment", "true"
 );
 env.getPropertySources().addFirst(new MapPropertySource("dev-overrides", overrides));
 }
 }
}

业务代码都不需要看到这些开关，开发模式自动开启。

场景 4：从环境变量适配老配置 key 名

公司迁移老系统时，老的 K8s ConfigMap 用的是 DB_USER、DB_PASSWORD，新的 Spring Boot 期望 spring.datasource.username、spring.datasource.password：

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


public class LegacyEnvAdapter implements EnvironmentPostProcessor {
 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 Map<String, Object> map = new HashMap<>();
 if (env.getProperty("DB_USER") != null) {
 map.put("spring.datasource.username", env.getProperty("DB_USER"));
 }
 if (env.getProperty("DB_PASSWORD") != null) {
 map.put("spring.datasource.password", env.getProperty("DB_PASSWORD"));
 }
 if (!map.isEmpty()) {
 env.getPropertySources().addFirst(new MapPropertySource("legacy-adapter", map));
 }
 }
}

老的 ConfigMap 不动，新代码跑得起来。

与其他扩展点的对比

扩展点	触发时机	适用场景
`EnvironmentPostProcessor`	Environment 准备完之后	配置加载/改写
`ApplicationContextInitializer`	Context 创建之前	给 Context 注册 BeanDefinition
`BeanFactoryPostProcessor`	BeanDefinition 加载完	修改/新增 BeanDefinition
`BeanPostProcessor`	Bean 初始化前后	对 Bean 做增强（AOP 基础）
`ApplicationListener`	各种生命周期事件	监听启动/关闭
`@PostConstruct`	Bean 初始化完成	单 Bean 的初始化逻辑

只关心配置时，永远用 EnvironmentPostProcessor，其它扩展点就不要拿来挪用。

几个关键细节

1. Order 决定多个 Processor 的执行顺序

如果项目里有多个 Processor（比如解密 + 远程拉取 + 适配老配置），它们的执行顺序由 getOrder() 决定，值小的先执行。

1

@Override public int getOrder() { return Ordered.HIGHEST_PRECEDENCE + 10; }

业务自己的 Processor 应该排在框架的 Processor 之后——HIGHEST_PRECEDENCE 是 Integer.MIN_VALUE，加一点偏移避免和框架抢顺序。

2. PropertySource 的优先级

Environment 维护了一个有序的 PropertySource 列表：

flowchart LR
 A["addFirst
最高优先级"] --> B["命令行参数"] --> C["application.yml"] --> D["environment 变量"] --> E["addLast
最低优先级"]

加自定义 source 时关键决策是 addFirst 还是 addLast：

解密类、Override 类 → addFirst（自己的值优先）
远程 fallback 配置 → addLast（被本地优先）

写错位置会导致"为什么我设置了配置不生效？“这种排查噩梦。

3. 不要在 Processor 里依赖 Spring Bean

EnvironmentPostProcessor 触发时整个 ApplicationContext 还没建好——你不能 @Autowired，不能用 Spring Bean。需要的工具类要么自己 new，要么用静态工厂方法。

4. 异常处理

Processor 里抛异常会让整个应用启动失败。像"远程配置中心拉取失败"这种外部依赖应该有 fallback 行为：

1
2
3
4
5
6
7


try {
 Map<String, Object> remote = fetchFromRemote(...);
 env.getPropertySources().addLast(...);
} catch (Exception e) {
 log.warn("remote config unavailable, fallback to local", e);
 // 不重抛，让应用用本地配置启动
}

5. 日志：Processor 太早，标准 logback 还没初始化

Processor 触发时 logback / log4j2 通常还没初始化好，写日志可能丢失。一个 workaround 是用 DeferredLog：

1
2
3
4
5
6
7
8


private static final DeferredLog log = new DeferredLog();

@Override
public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 log.info("decrypting config...");
 // ...
 app.addInitializers(ctx -> log.replayTo(MyProcessor.class));
}

DeferredLog 把日志先缓存起来，等 logging 体系准备好后回放。生产代码里强烈建议用它。

调试技巧

启动时把 Environment 的所有 PropertySource 打出来看一下：

1
2
3


((ConfigurableEnvironment) env).getPropertySources().forEach(ps -> {
 log.info("PropertySource: {}", ps.getName());
});

更简单的办法是开 Spring Boot Actuator 的 /actuator/env，能看到每个 key 的来源——调试配置加载顺序，没有比这更快的方法。

小结

一句话总结：

EnvironmentPostProcessor 是 Spring Boot 配置体系的最后一道前置插入点——业务代码里看到的每一个 @Value，最终值都可以由它在最早期被改写。

什么时候用：

启动时要做"配置改写、解密、远程拉取、key 适配”
业务代码不应该感知这些"配置层操作"
触发时机必须早于 Bean 初始化

写 Processor 的几个原则：

addFirst vs addLast 看清楚——这是最大的坑
不依赖 Spring Bean，触发时还没有 ApplicationContext
用 DeferredLog，正常 logger 不一定准备好
异常要有 fallback，别让外部依赖卡死启动
用 getOrder() 控制多 Processor 顺序

把这个扩展点用熟，你就能优雅地解决很多原本只能"在 main 里 hack"的奇葩需求。

Spring 集成 Elasticsearch 的三种姿势与选型

Sat, 25 Sep 2021 16:00:00 +0800

为什么这件事比看起来复杂

接 Elasticsearch 这件事，乍一看就是"加个依赖、写两行代码"。真做起来你会发现——ES 的 Java 客户端在 7.x → 8.x 之间发生过断崖式变化：

7.x 时代主推 RestHighLevelClient，但它在 7.15 被官方标记为 deprecated
8.x 提供了全新的 ElasticsearchClient（基于 Java API Client）
Spring Data Elasticsearch 在不同版本间也跟着切换底层
还有 ES 7 → 8 的 mapping 兼容、_doc type 移除等历史包袱

很多博客文章给的代码例子混杂着 5.x、6.x、7.x、8.x 的写法，新人照着写常常踩到 deprecation 警告或者根本跑不起来。本文把这件事的现状捋清楚——给出一份适用于 ES 8.x + Spring Boot 3.x 的指南，同时讲一下迁移和共存。

三种 Java 接 ES 的方式

方式	抽象层级	适用场景
Low Level REST Client	极低	特殊、罕见 API，完全控制 HTTP
Java API Client (8.x 推荐)	中	99% 的业务场景
Spring Data Elasticsearch	高	CRUD + Repository 抽象，简化模型

简单说：

自己拼 JSON 调 REST → Low Level
ES 官方推荐的"业务用法" → Java API Client
像写 JPA 一样玩 ES → Spring Data ES

一、官方推荐：Java API Client（8.x）

引入依赖：

1
2
3
4
5
6
7
8
9


<dependency>
 <groupId>co.elastic.clients</groupId>
 <artifactId>elasticsearch-java</artifactId>
 <version>8.10.0</version>
</dependency>
<dependency>
 <groupId>jakarta.json</groupId>
 <artifactId>jakarta.json-api</artifactId>
</dependency>

构造 Client：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Configuration
public class EsConfig {
 @Bean
 public ElasticsearchClient esClient() {
 RestClient restClient = RestClient.builder(
 new HttpHost("localhost", 9200, "http")).build();
 ElasticsearchTransport transport =
 new RestClientTransport(restClient, new JacksonJsonpMapper());
 return new ElasticsearchClient(transport);
 }
}

索引文档

1
2
3
4
5
6
7


public void index(Article article) throws IOException {
 IndexResponse resp = esClient.index(i -> i
 .index("articles")
 .id(article.getId().toString())
 .document(article));
 log.info("indexed: {}", resp.result());
}

注意 Java API Client 大量用 Lambda + DSL Builder 风格——避免了 7.x 时代手拼 XContentBuilder 的痛苦。

查询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


SearchResponse<Article> resp = esClient.search(s -> s
 .index("articles")
 .query(q -> q.bool(b -> b
 .must(m -> m.match(t -> t.field("title").query(keyword)))
 .filter(f -> f.term(t -> t.field("status").value(1)))
 ))
 .from(0).size(10)
 .sort(so -> so.field(f -> f.field("createdAt").order(SortOrder.Desc))),
 Article.class);

resp.hits().hits().forEach(h -> log.info("{} - {}", h.id(), h.source().getTitle()));

这套 DSL 几乎和 ES 原生的 JSON 查询体一一对应，可读性远超手拼 JSON，类型也安全。

聚合

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


SearchResponse<Void> resp = esClient.search(s -> s
 .index("articles")
 .size(0)
 .aggregations("by_status", a -> a
 .terms(t -> t.field("status"))),
 Void.class);

resp.aggregations()
 .get("by_status")
 .sterms()
 .buckets()
 .array()
 .forEach(b -> log.info("status={}, count={}", b.key().stringValue(), b.docCount()));

二、Spring Data Elasticsearch：JPA 风格

如果你喜欢 Spring Data 那种 Repository 风格，能让 90% 的 CRUD 自动生成：

1
2
3
4


<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
</dependency>

1
2
3


spring:
 elasticsearch:
 uris: http://localhost:9200

实体类：

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


@Document(indexName = "articles")
@Setting(shards = 3, replicas = 1)
public class Article {
 @Id
 private String id;

 @Field(type = FieldType.Text, analyzer = "ik_max_word")
 private String title;

 @Field(type = FieldType.Keyword)
 private String status;

 @Field(type = FieldType.Date, format = DateFormat.date_hour_minute_second_millis)
 private LocalDateTime createdAt;
}

Repository：

1
2
3
4


public interface ArticleRepository extends ElasticsearchRepository<Article, String> {
 Page<Article> findByTitleContaining(String keyword, Pageable pageable);
 List<Article> findByStatus(String status);
}

业务里像 JPA 一样用：

1
2


articleRepository.save(article);
Page<Article> page = articleRepository.findByTitleContaining("Spring", PageRequest.of(0, 10));

复杂查询用 ElasticsearchOperations：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


NativeQuery query = NativeQuery.builder()
 .withQuery(q -> q.bool(b -> b
 .must(m -> m.match(t -> t.field("title").query("Spring")))
 .filter(f -> f.range(r -> r.field("createdAt")
 .gte(JsonData.of("2021-01-01"))))
 ))
 .withPageable(PageRequest.of(0, 10))
 .build();

SearchHits<Article> hits = operations.search(query, Article.class);

注意到了吗？Spring Data ES 底层其实就是 Java API Client——但在 CRUD 层多包了一层 Repository 抽象。

三、`RestHighLevelClient` 怎么办？

如果你接手了一个 ES 7.x 时代的项目，里面遍地 RestHighLevelClient：

1
2
3
4
5
6
7


// 老代码示意
RestHighLevelClient client = new RestHighLevelClient(
 RestClient.builder(new HttpHost("localhost", 9200, "http")));

SearchRequest req = new SearchRequest("articles");
req.source(new SearchSourceBuilder().query(...));
SearchResponse resp = client.search(req, RequestOptions.DEFAULT);

它已经被 deprecated，但官方留了兼容 jar 让你能升到 ES 8 而不立刻重写：

1
2
3
4
5


<dependency>
 <groupId>org.elasticsearch.client</groupId>
 <artifactId>elasticsearch-rest-high-level-client</artifactId>
 <version>7.17.21</version>
</dependency>

但这是临时过渡，不是长期方案——当你的 ES 集群升到 8.x，RestHighLevelClient 在 8.x 上能跑但不再有新功能、不再适配新版查询能力。新写代码不要再用它，老代码遇到要改的时候顺手迁到 Java API Client。

几个工程上的关键决策

1. 什么时候用 Spring Data ES，什么时候直接用 Java API Client

	Spring Data ES	Java API Client
简单 CRUD	✓ 极简	△ 自己写
复杂查询/聚合	△ 要 NativeQuery，绕一圈	✓ 直接 DSL
实体映射	✓ `@Field` 注解	△ 自己写 Jackson 配置
索引管理	✓ 自动建索引/Settings	△ 自己调 API
性能控制	△ 隔了一层	✓ 直接
学习成本	低（懂 Spring Data）	中（懂 ES 查询 DSL）

建议：CRUD 多、查询不复杂的业务，用 Spring Data ES；查询场景重的搜索/分析业务，直接用 Java API Client。

混用也很常见——Repository 处理基础 CRUD，搜索接口直接注入 ElasticsearchClient。

2. 索引建模：动态 vs 显式

强烈建议显式建 mapping，不要依赖 ES 的"自动推断"：

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


@Bean
public CommandLineRunner initIndex(ElasticsearchClient esClient) {
 return args -> {
 boolean exists = esClient.indices().exists(e -> e.index("articles")).value();
 if (!exists) {
 esClient.indices().create(c -> c
 .index("articles")
 .mappings(m -> m
 .properties("title", p -> p.text(t -> t.analyzer("ik_max_word")))
 .properties("status", p -> p.keyword(k -> k))
 .properties("createdAt", p -> p.date(d -> d))
 )
 .settings(s -> s.numberOfShards("3").numberOfReplicas("1"))
 );
 }
 };
}

动态推断会把"看似数字的字符串"识别成 long，把"中文字段"识别成 text 但用错分词器，到生产环境出问题再改 mapping 就晚了——ES 不允许修改字段类型，只能 reindex。

3. 中文分词：IK 不是默认装的

ES 默认分词器对中文按字切分，多数全文检索场景下不适用。生产环境必须装 ik 分词器：

1
2


# 8.10.0 示例（注意：插件版本必须与 ES 严格一致）
elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.10.0/elasticsearch-analysis-ik-8.10.0.zip

维护方变化：原 medcl/elasticsearch-analysis-ik 在 ES 8.x 后期已不再积极维护，主线维护已迁至 infinilabs/analysis-ik。新装请优先用 infinilabs 仓库的 release，能更快跟上新 ES 版本。

然后字段映射里指定 analyzer = "ik_max_word"（写入用最细切，搜索用 ik_smart 粗切）：

1
2


@Field(type = FieldType.Text, analyzer = "ik_max_word", searchAnalyzer = "ik_smart")
private String title;

4. 分页深度的坑

ES 默认 from + size 的分页最多到 10000 条。如果业务可能翻深页（比如导出全部），用 search_after 或 scroll：

1
2
3
4
5
6
7
8


// search_after：基于上一页最后一条记录的 sort 字段
SearchResponse<Article> resp = esClient.search(s -> s
 .index("articles")
 .size(100)
 .sort(so -> so.field(f -> f.field("createdAt").order(SortOrder.Desc)))
 .sort(so -> so.field(f -> f.field("_id").order(SortOrder.Asc)))
 .searchAfter(lastSortValues),
 Article.class);

5. 别在 ES 上做事务/严格一致性

ES 是近实时的——文档写入后默认 1 秒才能搜到（refresh_interval）。所以 ES 不能作为强一致的存储。常见模式是：

主存储用 MySQL / PostgreSQL（事务保证）
搜索/聚合走 ES（异步同步过去）
同步通过 Canal / Debezium / Flink CDC 解析 binlog

排错的几个真实坑

类型不匹配：mapping 里是 keyword，查询用 match——查不出来。term/keyword 用 term query，text 用 match
大字段返回：用 _source.includes/excludes 控制返回字段，避免拖宽带
分页超过 max_result_window：要么改配置要么用 search_after
批量写入：用 Bulk API，不要一条一条 index
mapping 写错改不掉：reindex 是唯一出路。前期建模一定要慎重

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 批量写入示例
BulkRequest.Builder br = new BulkRequest.Builder();
for (Article a : articles) {
 br.operations(o -> o.index(i -> i.index("articles").id(a.getId()).document(a)));
}
BulkResponse result = esClient.bulk(br.build());
if (result.errors()) {
 result.items().forEach(item -> {
 if (item.error() != null) log.error("bulk failed: {}", item.error().reason());
 });
}

选型总结

flowchart TD
 Start([新项目接 ES?])
 Start --> NewProject{Spring Boot 项目?}
 NewProject -->|是| HasComplex{复杂搜索/聚合多吗?}
 NewProject -->|否| Direct[Java API Client]
 HasComplex -->|不多，CRUD 为主| SDE[Spring Data ES]
 HasComplex -->|很多| Mix[Spring Data ES + Java API Client 混用]

老项目如果用的是 RestHighLevelClient：

ES 还在 7.x：先稳住，规划升级
已经升到 8.x：新代码用 Java API Client，老代码遇到要改时顺手迁

小结

把全文压成一句话：

ES 8.x 时代，Java 业务接 ES 的标准答案是：CRUD 用 Spring Data ES，复杂查询用 Java API Client，老代码里的 RestHighLevelClient 慢慢替换掉。

工程上多记几条铁律：

mapping 显式声明，不要依赖动态推断
中文必装 IK 分词器
不要把 ES 当事务存储用
深分页用 search_after，别用 from+size 翻天
批量写入用 Bulk

把这些做对，ES 这层基本不会翻车。

微服务通信用 OpenFeign 还是 Dubbo

Mon, 19 Jul 2021 16:00:00 +0800

一句话先把问题摆出来

服务之间应该用 HTTP 还是 RPC 通信？

这是任何一个 Java 微服务团队都绕不过去的选择。社区里两套生态各有铁粉：

Spring Cloud + OpenFeign：基于 HTTP/REST，整套 Spring 全家桶最自然的延伸
Apache Dubbo：阿里开源的 RPC 框架，国内大厂的事实标准

新人选型时常常陷入一个误区——纠结于"谁性能好"。但只看 QPS 这件事会让你错过更重要的因素：协议哲学、生态契合度、运维成本、组织能力。

本文把这两套方案的差异、各自优劣、以及不同场景下的选型建议讲清楚。

协议层：HTTP 与 RPC 的本质差异

OpenFeign：HTTP 客户端的"声明式"

Feign 的本质是对 HTTP 客户端的封装。你定义一个接口，加几个注解，Feign 用动态代理把方法调用翻译成 HTTP 请求：

1
2
3
4
5
6
7
8


@FeignClient(name = "order-service")
public interface OrderClient {
 @GetMapping("/orders/{id}")
 OrderVO getById(@PathVariable Long id);

 @PostMapping("/orders")
 OrderVO create(@RequestBody OrderCreateDTO dto);
}

调用方写起来像调本地方法：

1

OrderVO order = orderClient.getById(1001L);

但底层走的是标准 HTTP——序列化通常是 JSON，传输是文本，每次请求都有完整的 HTTP 头开销。所以 Feign 的本质就是一个"会的协议"被打包成"省心的姿势"。

Dubbo：原生 RPC

Dubbo 是为 RPC 而生的。客户端和服务端都是 Java，直接通过自定义的二进制协议（Dubbo 协议、Triple 协议等）传输 Java 对象。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 服务端
@DubboService
public class OrderServiceImpl implements OrderService {
 @Override public OrderVO getById(Long id) { ... }
}

// 调用端
@DubboReference
private OrderService orderService;

OrderVO order = orderService.getById(1001L);

注意——两端共享同一个接口（Java interface），通过注册中心拉到地址后建立长连接。没有 URL，没有 HTTP 头，序列化默认是 Hessian 或 Kryo（紧凑二进制）。

性能差距：到底差多少

实测数据（同机房、千兆内网、相同业务复杂度）：

指标	OpenFeign + Spring Cloud	Dubbo（默认 dubbo 协议）
单次 RTT	5-15 ms	1-3 ms
序列化大小	JSON，相对大	Hessian/Kryo，2-5 倍小
单连接 QPS	数千	数万
CPU 序列化开销	较高	较低

Dubbo 在性能上确实有显著优势——但请注意三点：

上述差距在"调用频率高、链路深"时才显著放大；多数业务一次接口调用 50-100ms，5ms 和 1ms 的差距完全淹没在业务里
Feign 改用 HTTP/2 + Protobuf 就能逼近 RPC 性能（Spring 6 / Spring Cloud 2022+ 支持）
性能问题大多在数据库、外部 API、缓存上，通信协议很少是瓶颈

不建议把『性能』当成选 Dubbo 的唯一理由。 如果你不能拿出一个真实的、被 Profiler 证实的、序列化耗时占主导的瓶颈，那性能差距对你来说几乎没意义。

生态契合度：谁配谁更顺手

维度	Spring Cloud + Feign	Dubbo
注册中心	Eureka / Nacos / Consul	Zookeeper / Nacos
配置中心	Spring Cloud Config / Nacos	Apollo / Nacos
网关	Spring Cloud Gateway	通常前置 Nginx + 业务网关
熔断	Resilience4j / Sentinel	Sentinel（原生集成）
链路追踪	Sleuth + Zipkin	Skywalking / 自建 Filter
服务治理	基础	强（路由、灰度、限流、调度都内置）
跨语言	天然 ✓（HTTP）	△（Triple 协议支持，gRPC 互通）
调试工具	Postman / curl 直接打	Telnet / Dubbo Admin

Spring Cloud 的强项是全家桶生态完整，Feign 只是其中一环；Dubbo 的强项是服务治理特性原生且强大——做到 Spring Cloud 同等治理能力，需要拼接一堆组件。

跨语言：被低估的因素

这是很多团队选型时最被低估的因素。

Feign 走 HTTP/REST：只要对方能发 HTTP 请求，谁都能调。Python、Go、Node 团队对接你的服务零门槛
Dubbo 默认是 Java-only：跨语言要切到 Triple 协议（基于 gRPC），配置和工具链都比 HTTP 复杂

如果你的组织是多语言团队——前端 Node、数据团队 Python、运营内部系统是 PHP——选 Feign 几乎没有疑问。强行用 Dubbo 让其他语言对接，会成为长期摩擦。

如果你的组织清一色 Java，跨语言不是问题，那 Dubbo 的劣势就消失了。

调试与可观测性

Feign 优势

HTTP 接口能直接用 Postman / curl 调试
浏览器开发工具能看请求响应
Nginx / 网关日志能直接读
Tcpdump / Wireshark 抓包能看明文

Dubbo 劣势

二进制协议要专用工具（Dubbo Admin、Telnet 命令）
Mock 和压测要起 Java 客户端
排查 “客户端发了什么” 比 HTTP 麻烦得多

1
2
3
4
5
6
7


# Feign 接口随时打：
curl http://order-service/orders/1001

# Dubbo 类似的事要用 telnet：
telnet 192.168.1.10 20880
ls com.xx.OrderService
invoke com.xx.OrderService.getById(1001)

可观测性是长期运维的核心痛点——调试方便程度对开发体验的影响远超 5ms 的性能差距。

学习曲线与团队上手成本

因素	Feign	Dubbo
新人上手	几乎零门槛（懂 HTTP 即可）	中等（注解 + 注册中心 + 协议）
大团队培训	简单	中等
调试体验	优	中
扩展定制	需懂 OkHttp / RestTemplate	需懂 Filter / Invoker SPI

新人入职第一周能用的是 Feign，三周后才能驾驭 Dubbo——团队规模一大，这个差距会成倍放大。

服务治理深度：Dubbo 的硬实力

如果说性能是 Dubbo 被高估的优势，那服务治理才是它真正的护城河。

Dubbo 原生支持的能力清单（Spring Cloud 多数都要拼装实现）：

多版本并行：@DubboReference(version = "1.0.0") 直接路由到指定版本服务
基于条件的路由规则：根据 Header / 参数 / 客户端 IP 路由到不同实例（灰度发布利器）
应用级 / 接口级粒度的治理
管理后台 Dubbo Admin 可视化调整路由、权重、限流，无需改代码
服务分组：环境/业务隔离

这些在 Spring Cloud 体系里要靠 Gateway + 自定义 Filter + Sentinel + Service Mesh 拼出来——能做，但维护成本高。

如果你做的是复杂的内部多团队协作系统（金融、电商核心链路），Dubbo 的治理能力会显著省心。

选型决策树

flowchart TD
 Start([选 Feign 还是 Dubbo?])
 Multi{多语言团队?}
 Start --> Multi
 Multi -->|是| Feign1[Feign / REST]
 Multi -->|否，纯 Java| Scale{服务规模?}
 Scale -->|小型，< 20 服务| Feign2[Feign / REST]
 Scale -->|中大型| Gov{是否需要复杂治理?
多版本/灰度/路由}
 Gov -->|不需要| Feign3[Feign 也够用]
 Gov -->|需要| Perf{对单次 RPC 性能敏感?}
 Perf -->|敏感| Dubbo1[Dubbo]
 Perf -->|不敏感| Choice[基于团队熟悉度选]

一些被反复争论的话题

争论 1：Spring Cloud 已经够强，Dubbo 没必要

部分对——如果你的业务复杂度还没碰到治理瓶颈，Spring Cloud 完全够。但有些治理特性（多版本、规则路由）原生 Spring Cloud 真的拼不出 Dubbo 那么顺手。

争论 2：Dubbo 把简单事情复杂化

部分对——Dubbo 的概念多（Provider/Consumer/Registry/Monitor，加上 Filter/Invoker/Cluster），新人确实一脸懵；但一旦上手，业务代码就和 Feign 一样简洁。

争论 3：现在该用 gRPC

gRPC 是个好选择，性能接近 Dubbo，跨语言天然支持。但生态在 Java 圈子相对薄弱——和 Spring 集成、注册中心选型、可观测性都要自己组装。Triple 协议（Dubbo 3）就是兼容 gRPC 的，意图是把"跨语言 + Dubbo 治理"一并拿下。

争论 4：直接用 Service Mesh

Mesh 把通信和治理下沉到 Sidecar，应用层只用最朴素的 HTTP/gRPC。理论上是终极方案，但运维 K8s + Istio 的复杂度让多数中小团队望而却步。

实战建议

我自己在团队里推的一份简版规则：

新启动的中小项目：直接 Spring Cloud + Feign。生态完整、上手快、调试方便，性能问题先不要担心
已有 Spring Cloud 体系的成熟团队：继续用 Feign，需要更高性能时点对点改 gRPC，不要整体迁 Dubbo
大量内部 Java 服务、纯 Java 技术栈、强治理需求：Dubbo（或 Dubbo 3）。多版本、灰度路由这些原生能力会省心
有跨语言需求：Feign / gRPC，不要 Dubbo（除非用 Triple）
绝不要"大力出奇迹"全家桶迁移：从 Spring Cloud 全部迁到 Dubbo 是高成本低收益的事，点对点重构才是务实做法

1
2
3
4
5
6


// 一个混合栈的例子：核心高频接口走 Dubbo，对外业务走 Feign
@FeignClient(name = "user-service")
public interface UserClient { ... } // 对外 / 跨语言

@DubboReference(version = "1.0.0")
private InventoryService inventory; // 内部高频

混合用没什么问题，只要团队两套都熟。

小结

把全文压成一句话：

OpenFeign 让通信变简单，Dubbo 让治理变强大。多数项目应当从 Feign 开始，治理瓶颈真正出现时再选择性引入 Dubbo——而不是反过来。

性能、生态、跨语言、调试、团队成本是五个真正影响选型的维度。别让"哪个性能好"这个伪问题误导你——通信协议很少是系统瓶颈，能让团队走得远的选择，永远是简单、可调试、生态完整的那一个。

Java API 设计中的 Fluent 与 Builder

Thu, 08 Apr 2021 14:30:00 +0800

引子：两段看似一样的代码

1
2
3
4
5


// 写法 A
User user = new User();
user.setName("张三");
user.setAge(20);
user.setEmail("zhangsan@example.com");

1
2
3
4
5
6


// 写法 B
User user = User.builder()
 .name("张三")
 .age(20)
 .email("zhangsan@example.com")
 .build();

1
2
3
4
5


// 写法 C
User user = new User()
 .setName("张三")
 .setAge(20)
 .setEmail("zhangsan@example.com");

B 和 C 都是"链式调用"，看起来差不多——但它们解决的是完全不同的问题。B 是Builder 模式，C 是Fluent Setter 风格。两者在中文社区经常被混为一谈，导致很多文章在讨论"Builder 模式"时其实展示的是 Fluent。

本文把这两个概念彻底分清楚，讲清楚各自解决什么问题、什么时候用哪个、配合 Lombok 怎么写最舒服。

一、先把概念分清楚

Fluent（流式接口）

Fluent 是一种接口设计风格——方法返回 this（或某种上下文对象），让调用可以连成一串。它本身不是设计模式，只是一种"让 API 读起来像句子"的写法。

1
2
3
4
5
6
7
8


public class StringBuilder {
 public StringBuilder append(String s) {
 // ...
 return this; // ← 关键
 }
}

new StringBuilder().append("Hello, ").append("world").append("!");

JDK 里 StringBuilder、Stream 都是 Fluent 风格。

Builder（生成器模式）

Builder 是 GoF 设计模式——为构造一个复杂对象单独建一个"建造者"对象，把"对象的构造过程"和"对象本身"分开。

1
2
3
4


User u = new User.Builder()
 .name("张三")
 .age(20)
 .build(); // ← 关键：build() 才返回真正的目标对象

Builder 通常也用 Fluent 风格写——所以才容易混淆。但它的核心特征不是"链式"，而是：

构造过程和目标对象分离（中间态在 Builder 上，不污染目标对象）
有一个明确的 build() 终点
目标对象通常是不可变的（构造完所有字段都 final）

二、Fluent Setter：最朴素的链式

最简单的 Fluent 写法——在 Setter 里返回 this：

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


public class User {
 private String name;
 private Integer age;

 public User setName(String name) {
 this.name = name;
 return this; // ← Fluent 关键
 }

 public User setAge(Integer age) {
 this.age = age;
 return this;
 }
}

new User()
 .setName("张三")
 .setAge(20);

Lombok 一个 @Accessors(chain = true) 就能生成：

1
2
3
4
5
6


@Data
@Accessors(chain = true)
public class User {
 private String name;
 private Integer age;
}

或者去掉 set 前缀让 API 更紧凑：

1
2
3
4
5
6
7


@Accessors(fluent = true)
public class User {
 private String name;
 private Integer age;
}

new User().name("张三").age(20);

优点

写法简单，对原 POJO 改动最小
API 紧凑，链式
容易加在已有项目上，渐进式改造

缺点

可变对象——构造完之后还能改，线程安全性差
没有"构造完成"的明确语义——任何时候都可以接着调
不能做必填校验——你 new User() 之后直接用，编译期不会报错
和 JavaBean 规范冲突——set 系列方法返回 void 是 JavaBean 标准，框架（早期 BeanUtils、序列化库）可能不识别

所以——Fluent Setter 更适合内部 POJO，对外 API 通常优先选 Builder 这种语义更明确的风格。

三、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


public class User {
 private final String name;
 private final Integer age;
 private final String email;

 private User(Builder b) {
 this.name = b.name;
 this.age = b.age;
 this.email = b.email;
 }

 public static Builder builder() {
 return new Builder();
 }

 public static class Builder {
 private String name;
 private Integer age;
 private String email;

 public Builder name(String name) { this.name = name; return this; }
 public Builder age(Integer age) { this.age = age; return this; }
 public Builder email(String e) { this.email = e; return this; }

 public User build() {
 // 必填校验放这里
 Objects.requireNonNull(name, "name is required");
 return new User(this);
 }
 }

 // 只暴露 getter，没有 setter
 public String getName() { return name; }
 public Integer getAge() { return age; }
 public String getEmail() { return email; }
}

调用方：

1
2
3
4
5


User u = User.builder()
 .name("张三")
 .age(20)
 .email("z@x.com")
 .build();

Lombok 一个 @Builder 就能生成上面所有的代码：

1
2
3
4
5
6
7


@Builder
@Getter
public class User {
 private final String name;
 private final Integer age;
 private final String email;
}

优点

目标对象不可变——所有字段 final，天然线程安全
build() 是明确终点——调用方知道"这里之前在配置，之后是真正的对象"
必填校验集中——所有约束放 build() 一处
构造逻辑可独立演化——Builder 可以加链式方法、衍生 API，目标对象保持简洁
天然适合"参数多且大部分可选"的对象

缺点

类多一倍（一个目标 + 一个 Builder），不用 Lombok 写起来烦
字段加减时 Builder 也要改

四、什么时候用 Fluent，什么时候用 Builder

用 Fluent Setter 的场景

进程内的 DTO / VO / Form——只在内部传递，不需要不可变性
已有 POJO 的最小改造——加个 @Accessors(chain=true) 就完事
配置类、上下文对象——会被持续修改，本就是可变的

用 Builder 的场景

不可变值对象——领域模型、配置对象、消息体
构造参数多（≥4 个）且大部分可选——Builder 比"重载 N 个构造器"清爽得多
对外暴露的 API——Builder 给调用方明确的"配置 → 完成"语义
需要必填校验——build() 是兜底

两者结合的反面教材

1
2
3
4
5
6
7


// 反面教材：既能 builder().build()，又能直接 new + setter
@Data
@Builder
public class User {
 private String name;
 private Integer age;
}

@Data 会生成 setter，@Builder 会生成 Builder——结果就是这个对象既不可变，又有 Builder。Builder 的不可变优势完全丧失。

正确写法：

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


// 不可变 + Builder
@Builder
@Getter // 只生成 getter，没有 setter
public class User {
 private final String name;
 private final Integer age;
}

// 或者：可变 + Fluent，不要 Builder
@Data
@Accessors(chain = true)
public class UserDTO {
 private String name;
 private Integer age;
}

两种风格通常不建议混在一个类上——除非你确实需要可变 + Builder 双重能力，否则会让语义模糊。

五、Builder 进阶用法

必填字段强制：阶梯式 Builder（Step Builder）

普通 Builder 只能在 build() 里运行时校验，编译期帮不了你。Step Builder 通过类型系统让"必填字段没填就编译不过"：

1
2
3
4
5
6


User u = User.builder()
 .name("张三") // 必填
 .age(20) // 必填
 .optional() // 进入"可选阶段"
 .email("...")
 .build();

实现要写多个接口（NameStep → AgeStep → OptionalStep），代码量大，只有"对外 SDK，且想强制必填"时才值得用。

Builder 里加业务校验

1
2
3
4
5
6
7
8
9


public User build() {
 if (age != null && age < 0) {
 throw new IllegalArgumentException("age must be >= 0");
 }
 if (email != null && !email.contains("@")) {
 throw new IllegalArgumentException("invalid email");
 }
 return new User(this);
}

所有"对象不变式"应当在 build() 里检查，让目标对象一旦构造出来就一定是合法的。

Builder 复用：从已有对象出发再修改

可变对象修改方便，不可变对象怎么办？答案是 toBuilder：

1
2
3
4
5
6
7
8
9


@Builder(toBuilder = true)
@Getter
public class User {
 private final String name;
 private final Integer age;
}

User u1 = User.builder().name("张三").age(20).build();
User u2 = u1.toBuilder().age(21).build(); // 创造一个"修改了 age 的副本"

toBuilder() 把现有对象的所有字段拷进 Builder，让你像"对象修改"一样，但底层每次都是创建新对象——既保留了不可变，又方便"小改造"。

集合字段：`@Singular`

参数里有集合的话，Lombok 提供 @Singular：

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


@Builder
public class Order {
 private final String orderNo;
 @Singular
 private final List<OrderItem> items;
}

Order o = Order.builder()
 .orderNo("123")
 .item(item1) // 单个元素
 .item(item2)
 .items(List.of(...))// 批量
 .build();

六、Fluent 的另外两个高级形态

1. Method Chaining 操作集合：`Stream`

1
2
3
4
5


List<String> result = users.stream()
 .filter(u -> u.getAge() > 18)
 .map(User::getName)
 .sorted()
 .collect(toList());

Stream 的每一步都返回 Stream<T>，看起来像 Fluent，但本质是返回新对象而非 this。这是 Fluent 的"不可变变体"——每个操作产生新流，原流不变。这种"Fluent + 不可变"的组合在函数式风格里非常常见。

2. 内部 DSL：建造一棵描述树

很多框架用 Fluent 风格搭出一个"Domain Specific Language"：

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


// MyBatis-Plus QueryWrapper
new LambdaQueryWrapper<User>()
 .eq(User::getStatus, 1)
 .like(User::getName, "张")
 .orderByDesc(User::getCreateTime);

// Mockito
when(repo.findById(1L))
 .thenReturn(Optional.of(user));

// AssertJ
assertThat(users)
 .hasSize(2)
 .extracting(User::getName)
 .containsExactly("张三", "李四");

Fluent 的真正威力在这里——让代码读起来像自然语言/SQL，远超普通 setter 链能做到的。

七、踩坑提醒

@Data + @Builder 反模式——前面说过，要么不可变 + Builder，要么可变 + Fluent，别叠加
@SuperBuilder 用于继承——@Builder 不支持父子类，要用 @SuperBuilder
Fluent Setter 和 JavaBean 规范冲突——一些老库（如 Apache BeanUtils）按"setter 返回 void"识别，看不到 Fluent setter；序列化库通常没问题（用反射）
链式调用的报错堆栈不友好——一行长链报错时只能看到行号，建议合理换行
不要做"链式校验"——把 validate() 加进链里看似优雅，实际让链式表达力变差，用 build() 集中校验
不可变对象的 equals/hashCode——使用 @Value 或者 @EqualsAndHashCode，否则 Map / Set 行为会出错

八、一个工程上的"风格指南"

我自己在团队里推的一份简版规则：

类型	推荐风格
领域模型 / 值对象	`@Builder + @Getter`，不可变
API 请求/响应 DTO	`@Data + @Accessors(chain=true)`，可变 + Fluent
配置类	`@Builder + @Getter`，不可变
内部 DTO/VO	视情况用 Fluent，不需要 Builder
框架配置/上下文	视情况用 Builder，明确"build 完成"语义

把"什么对象用什么风格"约定下来，比"代码漂亮"重要得多。

小结

把全文压一句：

Fluent 是 API 风格——让代码读起来像句子；Builder 是设计模式——让复杂对象的构造和不可变共存。前者解决可读性，后者解决可维护性。

记住三个判断：

要不要不可变？ 要 → Builder；不要 → Fluent Setter
构造参数多不多？ 多（≥4）→ Builder；少 → 普通构造器
是不是对外 API？ 是 → Builder（明确语义）；否 → 都行

把概念拎清楚，下次再看到 obj.a().b().c().build() 这种代码，你就能一眼看出它是真 Builder 还是 Fluent 冒充的，也就能写出更精准的 API。

用 Jackson 和 AOP 优雅地处理接口数据脱敏

Thu, 18 Feb 2021 15:30:00 +0800

这件事每个面向用户的接口都遇到

合规要求越来越严，业务接口里要返回手机号、身份证、邮箱、银行卡——但生产环境必须脱敏：

1
2
3
4


138****8000 原: 13800138000
510123****0023 原: 510123199001020023
z****@163.com 原: zhangsan@163.com
6228**********0023 原: 6228480000010990023

一个朴素的实现是在 Service 里手动转换：

1
2
3
4
5
6
7
8
9


public UserVO getUser(Long id) {
 User user = userRepo.findById(id).orElseThrow();
 UserVO vo = new UserVO();
 vo.setName(user.getName());
 vo.setPhone(MaskUtil.maskPhone(user.getPhone())); // 手动脱敏
 vo.setIdCard(MaskUtil.maskIdCard(user.getIdCard())); // 手动脱敏
 vo.setEmail(MaskUtil.maskEmail(user.getEmail())); // 手动脱敏
 return vo;
}

写一两次不烦——写到一百次必出错：

新人写新接口忘了脱敏 → 信息泄漏
字段重命名时 Util 的调用没改全 → 漏脱敏
测试环境不希望脱敏 → 各处 if 判断又加 bug
一个字段多个接口都返回 → 改脱敏规则要改一堆地方

正确姿势是——让脱敏变成"声明式"：

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


public class UserVO {
 private String name;

 @Sensitive(type = PHONE)
 private String phone;

 @Sensitive(type = ID_CARD)
 private String idCard;

 @Sensitive(type = EMAIL)
 private String email;
}

写一次注解，所有接口自动生效。本文讲清楚怎么用 Jackson 自定义序列化 + AOP 实现这套机制，以及生产环境的细节。

一、最朴素：用 Jackson 自定义序列化器

Spring Boot 默认用 Jackson 序列化 JSON——拦截这个过程是最干净的姿势。

1. 定义脱敏类型

1
2
3
4
5
6
7
8
9


public enum SensitiveType {
 PHONE,
 ID_CARD,
 EMAIL,
 BANK_CARD,
 NAME,
 ADDRESS,
 CUSTOM;
}

2. 定义注解

1
2
3
4
5
6
7
8
9


@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotationsInside // 让自定义注解能携带其他 Jackson 注解
@JsonSerialize(using = SensitiveSerializer.class)
public @interface Sensitive {
 SensitiveType type();
 int prefix() default -1;
 int suffix() default -1;
}

@JacksonAnnotationsInside 是一个非常关键的"元注解"——它让 @Sensitive 自带 @JsonSerialize 的能力。

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


public class SensitiveSerializer extends JsonSerializer<String>
 implements ContextualSerializer {

 private SensitiveType type = SensitiveType.PHONE;
 private int prefix = -1;
 private int suffix = -1;

 public SensitiveSerializer() {}
 public SensitiveSerializer(SensitiveType type, int prefix, int suffix) {
 this.type = type;
 this.prefix = prefix;
 this.suffix = suffix;
 }

 @Override
 public void serialize(String value, JsonGenerator gen, SerializerProvider sp)
 throws IOException {
 if (value == null) { gen.writeNull(); return; }
 gen.writeString(SensitiveUtil.mask(value, type, prefix, suffix));
 }

 @Override
 public JsonSerializer<?> createContextual(SerializerProvider prov,
 BeanProperty property) {
 if (property == null) return this;
 Sensitive ann = property.getAnnotation(Sensitive.class);
 if (ann != null) {
 return new SensitiveSerializer(ann.type(), ann.prefix(), ann.suffix());
 }
 return this;
 }
}

ContextualSerializer 让序列化器能在每次使用时拿到字段上的注解参数——这是注解能"传参"的关键。

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


public class SensitiveUtil {
 public static String mask(String src, SensitiveType type, int prefix, int suffix) {
 if (src == null || src.isEmpty()) return src;
 switch (type) {
 case PHONE:
 return src.length() == 11 ? src.substring(0, 3) + "****" + src.substring(7) : src;
 case ID_CARD:
 return src.length() == 18 ? src.substring(0, 6) + "********" + src.substring(14) : src;
 case EMAIL:
 int at = src.indexOf('@');
 if (at <= 1) return src;
 String name = src.substring(0, at);
 String mask = name.charAt(0) + "****";
 return mask + src.substring(at);
 case BANK_CARD:
 return src.length() < 4 ? src : "****" + src.substring(src.length() - 4);
 case NAME:
 return src.charAt(0) + "*";
 case ADDRESS:
 return src.length() <= 10 ? src : src.substring(0, 6) + "****";
 case CUSTOM:
 return maskCustom(src, prefix, suffix);
 default:
 return src;
 }
 }

 private static String maskCustom(String src, int prefix, int suffix) {
 if (src.length() <= prefix + suffix) return src;
 return src.substring(0, prefix)
 + "*".repeat(src.length() - prefix - suffix)
 + src.substring(src.length() - suffix);
 }
}

5. 实战使用

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


public class UserVO {
 private String name;

 @Sensitive(type = PHONE)
 private String phone;

 @Sensitive(type = ID_CARD)
 private String idCard;

 @Sensitive(type = EMAIL)
 private String email;

 @Sensitive(type = CUSTOM, prefix = 4, suffix = 4)
 private String bankCard;

 // getters / setters
}

业务代码原汁原味：

1
2
3
4
5
6
7


@GetMapping("/users/{id}")
public UserVO getUser(@PathVariable Long id) {
 User user = userRepo.findById(id).orElseThrow();
 UserVO vo = new UserVO();
 BeanUtils.copyProperties(user, vo); // 直接拷贝
 return vo; // 返回时 Jackson 自动脱敏
}

二、按角色控制是否脱敏

需求经常是这样：

普通用户调接口看到 138****8000；管理员调接口看到完整 13800138000。

注解里加一个"绕过角色"：

1
2
3
4


public @interface Sensitive {
 SensitiveType type();
 String[] bypassRoles() default {}; // 这些角色不脱敏
}

修改序列化器（在原有字段基础上加 bypassRoles，并在 createContextual 里读注解传进新实例）：

 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


public class SensitiveSerializer extends JsonSerializer<String> implements ContextualSerializer {

 private SensitiveType type = SensitiveType.PHONE;
 private int prefix = -1;
 private int suffix = -1;
 private String[] bypassRoles = new String[0]; // ★ 新增

 public SensitiveSerializer() {}
 public SensitiveSerializer(SensitiveType type, int prefix, int suffix, String[] bypassRoles) {
 this.type = type;
 this.prefix = prefix;
 this.suffix = suffix;
 this.bypassRoles = bypassRoles;
 }

 @Override
 public void serialize(String value, JsonGenerator gen, SerializerProvider sp)
 throws IOException {
 if (value == null) { gen.writeNull(); return; }
 Set<String> myRoles = UserContextHolder.current().getRoles();
 if (Arrays.stream(bypassRoles).anyMatch(myRoles::contains)) {
 gen.writeString(value); // 不脱敏
 return;
 }
 gen.writeString(SensitiveUtil.mask(value, type, prefix, suffix));
 }

 @Override
 public JsonSerializer<?> createContextual(SerializerProvider prov, BeanProperty property) {
 if (property == null) return this;
 Sensitive ann = property.getAnnotation(Sensitive.class);
 if (ann != null) {
 return new SensitiveSerializer(ann.type(), ann.prefix(), ann.suffix(), ann.bypassRoles());
 }
 return this;
 }
}

业务里：

1
2


@Sensitive(type = PHONE, bypassRoles = {"ADMIN", "RISK_OPS"})
private String phone;

三、Jackson 方案的限制

Jackson 序列化是 JSON 输出阶段 才介入——它解决了"返回给前端时脱敏"。但有些场景它不能覆盖：

入参脱敏（用户上传含敏感数据，落库前要脱敏）
写日志脱敏（日志里也不能完整打印身份证）
第三方接口调用脱敏（你不直接控制 JSON 序列化）

这些场景需要 AOP 配合。

四、AOP 方案：方法级数据转换

AOP 拦截 Controller / Service 方法，在方法返回后遍历返回对象，手动改写带 @Sensitive 的字段：

 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


@Aspect
@Component
public class SensitiveAspect {

 @AfterReturning(value = "@annotation(SensitiveResult)", returning = "result")
 public void after(JoinPoint pjp, Object result) {
 maskRecursively(result);
 }

 private void maskRecursively(Object obj) {
 if (obj == null) return;
 if (obj instanceof Collection) {
 ((Collection<?>) obj).forEach(this::maskRecursively);
 return;
 }
 for (Field f : obj.getClass().getDeclaredFields()) {
 Sensitive ann = f.getAnnotation(Sensitive.class);
 if (ann != null && f.getType() == String.class) {
 f.setAccessible(true);
 try {
 String v = (String) f.get(obj);
 f.set(obj, SensitiveUtil.mask(v, ann.type(), ann.prefix(), ann.suffix()));
 } catch (IllegalAccessException ignored) {}
 } else if (!f.getType().isPrimitive() && !f.getType().getName().startsWith("java.")) {
 f.setAccessible(true);
 try {
 maskRecursively(f.get(obj));
 } catch (IllegalAccessException ignored) {}
 }
 }
 }
}

调用方加注解：

1
2


@SensitiveResult
public List<UserVO> listUsers() { ... }

Jackson vs AOP

	Jackson	AOP
触发时机	JSON 序列化时	方法返回时
改的对象	输出流	Java 对象本身
后续可读	输出流写完即结束	对象被改了，后续逻辑读到脱敏值
性能	高	中（反射遍历）
控制粒度	字段级	方法级 + 字段级
适用	接口返回	入参、日志、复杂场景

生产推荐组合：Jackson 处理 99% 的接口返回，AOP 处理少数特殊场景。

五、踩坑提醒

1. 不要原地修改 Entity

AOP 方案里有个隐含风险——直接修改了 User 实体的字段：

1
2


List<User> users = userRepo.findAll();
maskRecursively(users); // 改了实体！

如果接下来还要把这些 users 写回 DB，会写入脱敏后的值——数据被破坏。

正确做法：只对 VO 脱敏，永不对 Entity。VO 是临时对象，Entity 是数据。

2. 注解要打在 String 上

Long、Integer 这些类型上加 @Sensitive 不会生效（序列化器只处理 String）——身份证存 String 不要存 Long。

3. 集合 + 嵌套对象

JSON 序列化器自动递归处理嵌套；AOP 方案要手动写递归，容易栈溢出——加个深度限制：

1
2
3
4


private void maskRecursively(Object obj, int depth) {
 if (depth > 10) return;
 // ...
}

4. 缓存的对象

如果对象被脱敏后又被放进缓存，缓存里的值就是脱敏的——下次拿出来给管理员也是脱敏的。永远只在最后一刻（接口返回）脱敏。

5. 日志里也要脱敏

1

log.info("user info: {}", user); // ❌ user.toString() 含完整手机号

可以为 Lombok 的 @ToString 用 @ToString.Exclude，或在 Logback 配 PatternMaskingFilter。

6. 测试环境不脱敏

通过 Profile 切换：

1
2
3
4
5


@Profile({"!test"})
@Configuration
public class SensitiveConfig {
 // 注册序列化器
}

测试环境关闭脱敏，方便调试。

7. 某些字段不脱敏 = 数据合规风险

不要让"业务方便"凌驾于合规之上——有人为了排查问题要"管理员能看完整信息"，要做：

操作日志（谁在什么时候查了谁的完整数据）
二次确认（点"查看完整"才显示）
限频（每天最多查 N 个）

六、生产推荐架构

flowchart TD
 Req[接口请求] --> Controller
 Controller --> Service[业务逻辑]
 Service --> DB[(DB 存原文)]
 Service --> VO[转 VO]
 VO --> Sensitive["@Sensitive 注解
(声明式)"]
 Sensitive --> Jackson[Jackson 序列化
自动脱敏]
 Jackson --> Resp[返回前端]
 
 Logging[日志记录] --> LogMask[Logback PatternFilter
脱敏]

每一层都有自己的脱敏机制，VO 上的注解是核心声明，序列化器/AOP/日志过滤器各自落实。

小结

把全文压一句：

数据脱敏不该写在业务代码里——它属于『数据展示层』的事。用注解声明字段类型，用 Jackson 序列化器或 AOP 做执行——业务代码只关心业务。

工程上几条铁律：

永远脱敏 VO，不脱敏 Entity
接口返回用 Jackson 序列化器，特殊场景用 AOP 兜底
日志脱敏单独走 Logback Filter
角色绕过要严格审计
测试环境通过 Profile 关闭

把这套做对，业务代码再也不用满地 MaskUtil.maskPhone(...)，新接口加字段也不会漏脱敏。

Makefile 在现代项目的价值与实践

Thu, 22 Oct 2020 15:00:00 +0800

为什么每个项目都该有一份 Makefile

很多人以为 Makefile 是 C/C++ 时代的产物——其实它在 Java / Go / Python / 前端 项目里同样好用。

它的真正价值不在"编译"，而在让项目所有日常操作都有"一行命令入口"：

1
2
3
4
5
6


make run # 启动
make test # 跑测试
make lint # 静态检查
make build # 构建产物
make image # 打 Docker 镜像
make deploy # 发布

新人入职第一天看一眼 Makefile，就知道这个项目能干啥、怎么开始。没有 Makefile 的项目，新人靠口口相传或翻 README，效率差得不是一点半点。

本文讲清楚 Makefile 的核心语法、现代项目里的写法、和那些容易踩的坑。

一、Makefile 的最小可用版

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


# Makefile
.PHONY: help run test build clean

help:
	@echo "Available commands:"
	@echo " make run - Run the application"
	@echo " make test - Run tests"
	@echo " make build - Build artifact"
	@echo " make clean - Remove artifacts"

run:
	go run main.go

test:
	go test ./...

build:
	go build -o bin/app main.go

clean:
	rm -rf bin/

执行：

1
2


make help
make test

⚠️ 关键陷阱：Makefile 命令前必须是 Tab 字符——空格会报 missing separator 错误。这是 Makefile 最让人崩溃的语法点。

二、核心概念

1. 目标（target）/ 依赖（prerequisite）/ 命令（recipe）

1
2


target: prerequisites
	recipe

例子：

1
2


build: src/main.go
	go build -o bin/app src/main.go

意思——“build 这个目标依赖 main.go，要执行 go build"。Make 会比较 main.go 的修改时间和 bin/app 的修改时间——如果 main.go 没变，重复 make build 不会重新构建。

2. 伪目标（.PHONY）

1
2
3


.PHONY: clean
clean:
	rm -rf bin/

.PHONY 告诉 Make——这不是一个真实文件，永远执行。否则如果项目目录里恰好有个文件叫 clean，make clean 会被识别成"clean 文件已存在，无需重做”——什么都不做。

所有"动作型"目标都要加 .PHONY，这是工程纪律。

3. 变量

1
2
3
4
5
6


APP := myapp
VERSION := $(shell git describe --tags --always)
GO := go

build:
	$(GO) build -ldflags "-X main.Version=$(VERSION)" -o bin/$(APP)

:= 是立即求值（推荐），= 是延迟求值（每次引用才计算，容易意外）。

4. 条件

1
2
3
4
5


GOOS ?= linux
GOARCH ?= amd64

build:
	GOOS=$(GOOS) GOARCH=$(GOARCH) go build -o bin/app

?= 表示"如果没设过就用这个默认值"——可以被命令行覆盖：

1

make build GOOS=darwin GOARCH=arm64

三、现代项目的 Makefile 模板

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


.PHONY: help run test test-cover lint build image clean

APP := myapp
VERSION := $(shell git describe --tags --always 2>/dev/null || echo "dev")
LDFLAGS := -ldflags "-X main.Version=$(VERSION) -s -w"
DOCKER_TAG := $(APP):$(VERSION)

help:
	@echo "Available commands:"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' Makefile | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-20s\033[0m %s\n", $$1, $$2}'

run: ## 启动开发服务器
	go run main.go

test: ## 跑单元测试
	go test ./... -race -v

test-cover: ## 测试 + 覆盖率报告
	go test ./... -coverprofile=coverage.out
	go tool cover -html=coverage.out -o coverage.html

lint: ## 静态检查
	golangci-lint run

build: ## 编译产物
	CGO_ENABLED=0 go build $(LDFLAGS) -o bin/$(APP) main.go

image: ## 打 Docker 镜像
	docker build -t $(DOCKER_TAG) .

clean: ## 清理产物
	rm -rf bin/ coverage.out coverage.html

grep -E ... ## ... 这套是个常用技巧——用注释自动生成 help：

1
2
3
4
5
6
7
8
9


$ make help
Available commands:
 run 启动开发服务器
 test 跑单元测试
 test-cover 测试 + 覆盖率报告
 lint 静态检查
 build 编译产物
 image 打 Docker 镜像
 clean 清理产物

Java Spring Boot 项目

 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


.PHONY: help run test build image deploy clean

APP := myapp
PROFILE ?= dev
TAG := $(shell git rev-parse --short HEAD)

help:
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' Makefile | awk 'BEGIN {FS = ":.*?## "}; {printf " %-12s %s\n", $$1, $$2}'

run: ## 启动应用
	./mvnw spring-boot:run -Dspring-boot.run.profiles=$(PROFILE)

test: ## 单元测试
	./mvnw test

build: ## 打 jar
	./mvnw clean package -DskipTests

image: build ## 打镜像
	docker build -t $(APP):$(TAG) .

deploy: image ## 推送 + 部署
	docker push registry.internal/$(APP):$(TAG)
	kubectl set image deploy/$(APP) $(APP)=registry.internal/$(APP):$(TAG)

clean:
	./mvnw clean
	rm -rf target/

注意 image: build 这种语法——image 依赖 build，所以执行 make image 时会先跑 make build。

前端项目

 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


.PHONY: help dev test lint build preview clean

PM := pnpm

help:
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' Makefile | awk 'BEGIN {FS = ":.*?## "}; {printf " %-12s %s\n", $$1, $$2}'

install: ## 装依赖
	$(PM) install

dev: install ## 开发模式
	$(PM) run dev

test: ## 跑测试
	$(PM) run test

lint: ## ESLint + Prettier 检查
	$(PM) run lint
	$(PM) run format:check

build: install ## 生产构建
	$(PM) run build

preview: build ## 预览构建产物
	$(PM) run preview

clean:
	rm -rf node_modules dist coverage

PM 变量让你能在 npm/yarn/pnpm 间切换——make build PM=npm 即可。

四、写 Makefile 的工程纪律

1. 命令前永远是 Tab

最大的坑——空格 vs Tab。配置编辑器：

1
2
3
4


.editorconfig:
[Makefile]
indent_style = tab
indent_size = 4

2. 所有动作目标都加 .PHONY

不加的话哪天目录里有个同名文件就废了。

3. 命令前加 @ 抑制回显

1
2
3


test:
	@echo "Running tests..."
	go test ./...

不加 @ 的话每条命令都会先打印一遍——输出会很啰嗦。

4. 常用变量放顶部

APP、VERSION、GO、DOCKER_TAG 这种所有人改起来频繁的变量放最上面，方便修改。

5. 提供 help 目标

5 行注释正则就能自动生成——这是 Makefile 体验的一半。

6. 别把环境变量硬编码

1
2
3
4
5
6
7
8


# ❌ 反例
build:
	GOPROXY=https://goproxy.cn go build

# ✓ 推荐
GOPROXY ?= https://goproxy.cn
build:
	GOPROXY=$(GOPROXY) go build

新人换代理时不用改 Makefile。

7. 错误处理

1
2
3


deploy:
	@./scripts/check-env.sh || (echo "env check failed"; exit 1)
	kubectl apply -f deploy.yaml

链式命令默认失败就停，但单独的脚本要显式 check。

五、进阶用法

1. 多目录子项目

1
2
3
4
5
6


SUBDIRS := api worker scheduler

build:
	for dir in $(SUBDIRS); do \
		$(MAKE) -C $$dir build; \
	done

$(MAKE) -C dir target 在子目录跑 make。

2. 多平台交叉编译

1
2
3
4
5
6
7
8
9


PLATFORMS := linux/amd64 linux/arm64 darwin/amd64 darwin/arm64

cross-build:
	@for p in $(PLATFORMS); do \
		os=$$(echo $$p | cut -d/ -f1); \
		arch=$$(echo $$p | cut -d/ -f2); \
		echo "Building for $$os/$$arch..."; \
		GOOS=$$os GOARCH=$$arch go build -o bin/app-$$os-$$arch; \
	done

3. 依赖检查

1
2
3
4
5
6
7


check-tools:
	@command -v go >/dev/null || (echo "go not found"; exit 1)
	@command -v docker >/dev/null || (echo "docker not found"; exit 1)
	@command -v kubectl >/dev/null || (echo "kubectl not found"; exit 1)

build: check-tools
	go build -o bin/app

4. include 子模块

1
2


include scripts/build.mk
include scripts/deploy.mk

把 Makefile 拆成多个文件——主 Makefile 只声明几个高阶目标，细节在子 mk 里。

六、Makefile vs 脚本 vs npm scripts

	Makefile	shell 脚本	package.json scripts
跨平台	△ 需要 make	△ 需要 bash	✓
依赖关系	✓ 内建	✗ 自己写	✗ 自己写
自动跳过未变	✓	✗	✗
可读性	△ 冷门语法	✓	✓
调试	△	✓	✓
已普及度	✓ Linux 自带	✓	△ 仅 Node 项目

给一个建议：

任何项目（不论语言）都该有 Makefile 作为『统一入口』——前端项目可以同时保留 package.json scripts，但 make dev / make test / make build 也应该能跑。这让"新人进项目"和"CI 配置"都极简。

七、Windows 兼容

Makefile 在 Windows 下需要装 make（通过 chocolatey、Git Bash、WSL 都行）。如果团队有 Windows 用户：

1
2
3
4
5
6
7
8


ifeq ($(OS),Windows_NT)
	RM := rmdir /s /q
else
	RM := rm -rf
endif

clean:
	$(RM) bin

或者更简单——让 Windows 用户用 WSL，业务级开发现在已经是默认配置。

八、CI 集成

GitLab CI / GitHub Actions 直接调 make：

1
2
3
4
5
6
7
8
9


# .github/workflows/ci.yml
jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - run: make test
 - run: make lint
 - run: make build

CI 配置文件极简——所有逻辑都在 Makefile 里。换 CI 平台（GitLab → GitHub Actions → Jenkins）只要改这一个文件，Makefile 不动。

小结

把全文压一句：

Makefile 不是构建工具，是『项目的遥控器』——让任何人 5 分钟看懂这个项目能做什么、怎么做。

记住几条：

命令前是 Tab 不是空格——这是 Makefile 第一坑
所有动作目标加 .PHONY
写 help 目标——用注释 + grep 自动生成
变量放顶部，外部可覆盖
CI 直接调 make——配置文件不要重复逻辑

把项目里那些"git 仓库下完不知道怎么跑"的痛点用 Makefile 一次性解决——这是最便宜的体验提升。

JUnit 4 到 JUnit 5：Java 测试框架的迁移与实战

Mon, 14 Sep 2020 15:30:00 +0800

为什么要从 JUnit 4 升级到 JUnit 5

很多团队的 pom.xml 里至今还躺着 junit:junit:4.x。JUnit 4 已经停止主线维护多年，但因为足够"够用"，迟迟没人动。

升级到 JUnit 5 不是为了赶时髦，而是它解决了 JUnit 4 时代积攒的几个核心痛点：

架构臃肿：JUnit 4 把整个框架塞在一个 jar 里，运行器（Runner）和扩展点（Rule）冲突，不能叠加
没有原生参数化测试：要靠 Parameterized Runner，写法别扭
嵌套测试丑陋：要用 @RunWith(Enclosed.class)
断言能力弱：复合断言、异常断言要靠第三方库
不支持 Java 8+ Lambda：很多优雅写法用不上

JUnit 5 推倒重来，拆成三个模块：

flowchart LR
 Platform["JUnit Platform
(运行平台)"]
 Jupiter["JUnit Jupiter
(JUnit 5 编程模型)"]
 Vintage["JUnit Vintage
(兼容跑 JUnit 3/4)"]

 Platform --> Jupiter
 Platform --> Vintage

Platform：测试引擎的标准接口，IDE/Maven/Gradle 都对它编程
Jupiter：你写的 @Test 用的就是它
Vintage：让 JUnit 4 测试在 Platform 上继续跑，平滑迁移

下面我们用一个个能跑的例子，把 JUnit 5 的常用与进阶用法过一遍。

一、最小可运行例子

1
2
3
4
5
6


<dependency>
 <groupId>org.junit.jupiter</groupId>
 <artifactId>junit-jupiter</artifactId>
 <version>5.10.0</version>
 <scope>test</scope>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class CalculatorTest {
 @Test
 void add_should_return_sum() {
 Calculator c = new Calculator();
 assertEquals(5, c.add(2, 3));
 }
}

注意——类和方法都不再需要 public，包私有就够了，因为 JUnit 5 用反射访问。这是个微小但很贴心的改进。

二、生命周期注解

JUnit 4 → JUnit 5 注解对照：

JUnit 4	JUnit 5
`@Before`	`@BeforeEach`
`@After`	`@AfterEach`
`@BeforeClass`	`@BeforeAll`
`@AfterClass`	`@AfterAll`
`@Ignore`	`@Disabled`

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


class LifecycleTest {

 @BeforeAll
 static void beforeAll() { /* 整个测试类前执行一次 */ }

 @BeforeEach
 void beforeEach() { /* 每个 @Test 前执行 */ }

 @Test
 void test1() { /* ... */ }

 @AfterEach
 void afterEach() { /* 每个 @Test 后执行 */ }

 @AfterAll
 static void afterAll() { /* 整个测试类后执行一次 */ }
}

@BeforeAll/@AfterAll 默认必须 static。如果不想写 static，把测试类加上 @TestInstance(Lifecycle.PER_CLASS)，整个类用一个实例，方法就不必 static 了——但要注意此时测试方法之间会共享实例字段。

三、断言：丰富又优雅

JUnit 5 的 Assertions 是终于"现代化"了：

 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


@Test
void richAssertions() {
 User u = userService.get(1L);

 // 基础
 assertNotNull(u);
 assertEquals("张三", u.getName());

 // 带 message（lambda 形式，断言失败前才计算字符串）
 assertEquals(20, u.getAge(), () -> "用户 " + u.getId() + " 年龄异常");

 // 一次性断言多个条件，全部都要执行
 assertAll("user properties",
 () -> assertEquals("张三", u.getName()),
 () -> assertEquals(20, u.getAge()),
 () -> assertTrue(u.getEmail().endsWith("@example.com"))
 );

 // 异常断言
 Exception ex = assertThrows(IllegalArgumentException.class,
 () -> userService.get(-1L));
 assertEquals("id must be positive", ex.getMessage());

 // 不抛异常断言
 assertDoesNotThrow(() -> userService.get(1L));

 // 超时断言（同步）
 assertTimeout(Duration.ofMillis(500), () -> userService.heavyTask());
 // 超时断言（一旦超时立刻终止任务）
 assertTimeoutPreemptively(Duration.ofMillis(500), () -> userService.heavyTask());
}

四、参数化测试：JUnit 5 的杀手锏

参数化测试是 JUnit 5 最值得单独学的特性。一个测试方法，多套输入，输出是多个独立测试用例——失败时 IDE 里能看到每个用例的结果。

需要额外依赖：

1
2
3
4
5
6


<dependency>
 <groupId>org.junit.jupiter</groupId>
 <artifactId>junit-jupiter-params</artifactId>
 <version>5.10.0</version>
 <scope>test</scope>
</dependency>

1. `@ValueSource` 单参数

1
2
3
4
5


@ParameterizedTest
@ValueSource(strings = {" ", "\t", "\n"})
void blank_strings_should_be_blank(String input) {
 assertTrue(StringUtils.isBlank(input));
}

2. `@CsvSource` 多参数

1
2
3
4
5
6
7
8
9


@ParameterizedTest(name = "[{index}] {0} + {1} = {2}")
@CsvSource({
 "1, 1, 2",
 "2, 3, 5",
 "10, 20, 30"
})
void add(int a, int b, int expected) {
 assertEquals(expected, calculator.add(a, b));
}

name 属性让每个用例在 IDE 里有清晰的标签，强烈推荐。

3. `@CsvFileSource` 从 CSV 文件读

1
2
3
4
5


@ParameterizedTest
@CsvFileSource(resources = "/test-cases.csv", numLinesToSkip = 1)
void fromCsv(int a, int b, int expected) {
 assertEquals(expected, calculator.add(a, b));
}

适合和测试人员协作——他们维护 CSV，开发不动代码。

4. `@MethodSource` 复杂数据

参数复杂时用方法源：

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


@ParameterizedTest
@MethodSource("userTestData")
void create(UserDTO input, boolean expectedValid) {
 assertEquals(expectedValid, userValidator.isValid(input));
}

static Stream<Arguments> userTestData() {
 return Stream.of(
 Arguments.of(new UserDTO("张三", 20), true),
 Arguments.of(new UserDTO("", 20), false),
 Arguments.of(new UserDTO("李四", -1), false)
 );
}

5. `@EnumSource` 遍历枚举

1
2
3
4
5


@ParameterizedTest
@EnumSource(value = OrderStatus.class, mode = Mode.EXCLUDE, names = {"DELETED"})
void allActiveStatusesShouldDisplayCorrectly(OrderStatus s) {
 assertNotNull(s.getDisplayName());
}

五、嵌套测试：让用例分组更优雅

@Nested 让测试类按场景分层，IDE 里看上去就是一棵树：

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


class UserServiceTest {

 @Nested
 @DisplayName("当用户已存在时")
 class WhenUserExists {
 @BeforeEach void setup() { /* 准备已存在用户 */ }

 @Test void getById_returns_user() { ... }
 @Test void update_should_succeed() { ... }
 }

 @Nested
 @DisplayName("当用户不存在时")
 class WhenUserNotFound {
 @Test void getById_returns_null() { ... }
 @Test void update_should_throw() { ... }
 }
}

@DisplayName 把测试名换成中文/句子式描述，让测试报告读起来像需求文档。

六、条件执行：根据环境跳过

JUnit 5 提供了一组 @EnabledOn* / @DisabledOn*：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Test
@EnabledOnOs(OS.LINUX)
void only_on_linux() { ... }

@Test
@EnabledIfSystemProperty(named = "env", matches = "ci")
void only_on_ci() { ... }

@Test
@DisabledIfEnvironmentVariable(named = "SKIP_HEAVY", matches = "true")
void heavy_test() { ... }

比 @Ignore 灵活得多。

七、扩展模型：替代 JUnit 4 的 Rule

JUnit 4 的 @Rule 不能多个叠加、不能跨类复用。JUnit 5 用统一的 Extension 模型替代：

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


@ExtendWith(MockitoExtension.class)
class UserServiceTest {

 @Mock UserRepository repo;
 @InjectMocks UserService service;

 @Test
 void getById_returns_user() {
 when(repo.findById(1L)).thenReturn(Optional.of(new User()));
 assertNotNull(service.getById(1L));
 }
}

@ExtendWith 可以叠加多个，也可以在方法级生效，灵活性远超 @Rule。

自定义 Extension 实现各种生命周期接口（BeforeEachCallback、AfterEachCallback、ParameterResolver 等），可以做到"在每个测试方法前自动初始化数据"、“自动清理数据库”、“自动注入参数"等。

八、Spring Boot 测试整合

Spring Boot 2.2+ 默认就用 JUnit 5。不需要任何额外配置：

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


@SpringBootTest
@AutoConfigureMockMvc
class UserControllerIT {

 @Autowired MockMvc mvc;
 @MockBean UserService service;

 @Test
 void getUser_should_return_200() throws Exception {
 when(service.get(1L)).thenReturn(new User(1L, "张三"));

 mvc.perform(get("/users/1"))
 .andExpect(status().isOk())
 .andExpect(jsonPath("$.name").value("张三"));
 }
}

值得一提的几个 Spring Boot 测试切片注解（瘦身的 @SpringBootTest）：

注解	用途
`@WebMvcTest`	只加载 Controller 层
`@DataJpaTest`	只加载 JPA 仓库
`@JsonTest`	只测试 JSON 序列化
`@DataRedisTest`	只加载 Redis 相关 Bean
`@RestClientTest`	测试 RestTemplate / FeignClient

切片测试启动快得多，单测就用切片，集成测试再用 @SpringBootTest。

九、JUnit 4 兼容：渐进式迁移

老项目里两套测试可以共存——保留 junit:junit 作为 Vintage 引擎，新增测试用 Jupiter：

1
2
3
4
5
6


<dependency>
 <groupId>org.junit.vintage</groupId>
 <artifactId>junit-vintage-engine</artifactId>
 <version>5.10.0</version>
 <scope>test</scope>
</dependency>

迁移建议：

先把 BUILD 配置好，让两套都能跑
新写的测试一律 Jupiter
改老代码时顺手把对应测试迁移过去
一两个迭代后，老测试全部迁完，移除 vintage 依赖

十、踩坑提醒

@BeforeAll/@AfterAll 默认要 static——除非用 @TestInstance(PER_CLASS)
@Test 不要再带 expected = Xxx.class——JUnit 5 没有这个属性，用 assertThrows
包还是 org.junit.jupiter.api——别混用 org.junit.*
Maven Surefire 要 ≥ 2.22，否则跑不起来 Jupiter 测试
参数化测试单独依赖 junit-jupiter-params
@SpringBootTest 不要乱用——它会启动整个上下文，单测应该用切片

小结

JUnit 5 不是"JUnit 4 的小升级”，是为 Lambda、模块化、现代 Java 重新设计的测试框架。

把这一篇压一句：

写新测试用 Jupiter，老测试靠 Vintage 兼容，慢慢迁；高频场景吃透 assertAll / 参数化 / @Nested，这三个特性能把单测写得像文档。

测试本身不是负担，写得好的测试是最准确的需求说明书。JUnit 5 给了你写出这种文档的工具，能不能用好是另一回事。

Drools 与 Aviator：Java 业务规则引擎实战

Sat, 08 Aug 2020 15:30:00 +0800

业务规则总是变，代码总是改

每个长期运行的业务系统都会面对这种场景：

风控规则：“新用户首次下单超过 1000 元 → 拦截”——一周后调整阈值，要发版
优惠券规则：“订单满 500 减 50，且非周末”——节假日要变，要发版
积分规则：“VIP 用户购买电子产品 3 倍积分”——业务搞活动一变就要发版
审批规则：“金额 > 10 万走总监审批”——金额线一调就要发版

这些规则的共同特征是——规则本身经常变化，但发版周期至少几天。把规则硬编码进代码导致两个难题：

业务跟不上：规则等代码发版才生效
代码越改越烂：if-else 嵌十几层，谁也不敢动

社区有两个 Java 生态的常用工具：

Drools：重型规则引擎，DSL 强、推理能力强、有规则库
Aviator：轻量级表达式引擎，类似"加强版 SpEL"，编译执行速度极快

它们解决的问题在不同量级。本文讲清楚两者的定位、典型用法、踩坑点。

一、什么时候该用规则引擎

先把"该不该用"讲清楚。规则引擎不是银弹，盲目引入反而是负担：

✅ 适合用规则引擎：

规则数量多（几十到几百条）
规则经常变（业务/运营频繁调整）
规则需要业务/运营/产品自己改（不希望走开发流程）
规则之间有交叉（一条规则匹配影响其他规则）

❌ 不适合：

规则就 3-5 条，全年改不到一次
规则只能由开发改（那写代码就行）
性能极敏感（规则引擎再快也比硬编码慢）
团队没人懂规则引擎（运维/排查反而更难）

不要"为了用规则引擎而用"——多数中小项目用枚举 + 策略模式 + 配置中心就够了。

二、Aviator：轻量表达式引擎

它是什么

Aviator 是阿里开源的轻量级表达式引擎——本质是字符串表达式 + 上下文变量 → 求值：

1
2
3
4
5
6
7
8
9


import com.googlecode.aviator.AviatorEvaluator;

Map<String, Object> ctx = new HashMap<>();
ctx.put("amount", 1500);
ctx.put("vip", true);

Boolean ok = (Boolean) AviatorEvaluator.execute(
 "amount > 1000 && vip == true", ctx);
// ok = true

典型用法 1：动态阈值

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


// 规则配置在数据库 / Nacos
String expr = configService.get("risk.threshold.expr");
// "amount > 1000 || (newUser && amount > 500)"

Map<String, Object> ctx = Map.of(
 "amount", order.getAmount(),
 "newUser", user.isNew(),
 "vip", user.isVip()
);

if ((Boolean) AviatorEvaluator.execute(expr, ctx)) {
 throw new BusinessException("风控拦截");
}

阈值改动只改配置中心，不发版。

典型用法 2：动态计算公式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// "积分 = 金额 * 倍率 + 固定值"
String expr = "amount * rate + bonus";

Map<String, Object> ctx = Map.of(
 "amount", order.getAmount(),
 "rate", 0.1,
 "bonus", 10
);

Long points = ((Number) AviatorEvaluator.execute(expr, ctx)).longValue();

Aviator 的核心特性

语法接近 Java——+ - * / && || == != 都按 Java 语义
支持自定义函数

1
2
3
4
5
6
7
8
9


AviatorEvaluator.addFunction(new AbstractFunction() {
 public String getName() { return "isWeekend"; }
 public AviatorObject call(Map<String, Object> env, AviatorObject d) {
 LocalDate date = LocalDate.parse(((String) d.getValue(env)));
 return AviatorBoolean.valueOf(date.getDayOfWeek().getValue() >= 6);
 }
});

AviatorEvaluator.execute("isWeekend('2020-08-08')"); // true

预编译加速

1
2


Expression compiled = AviatorEvaluator.compile("amount > 1000 && vip");
compiled.execute(ctx); // 反复调用更快

极快——比 SpEL 快数倍

Aviator 的限制

没有"规则集"概念——你需要自己管理多条规则
没有 then 部分——只能算出布尔值或数值，没有"满足条件做什么"
不能推理——只是算单个表达式

Aviator 的本质是『把 if 条件部分抽出来变成字符串』——其余还是你自己写。

三、Drools：完整规则引擎

它是什么

Drools 是一套完整的规则引擎——基于 Rete 算法，把规则编译成决策图，能高效匹配大量规则。

它有自己的 DSL（DRL 文件）：

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


package com.example.rules;
import com.example.Order;

rule "新用户首单大额拦截"
 when
 $o: Order(amount > 1000, user.newUser == true)
 then
 $o.reject("新用户首单不能超过 1000");
end

rule "VIP 用户折扣"
 when
 $o: Order(user.vip == true, amount > 500)
 then
 $o.applyDiscount(0.9);
end

DRL 文件加载到 Drools 的 KieSession 里：

1
2
3
4
5
6
7


KieServices ks = KieServices.Factory.get();
KieContainer kc = ks.getKieClasspathContainer();
KieSession session = kc.newKieSession();

session.insert(order);
session.fireAllRules();
session.dispose();

fireAllRules() 会根据规则匹配自动执行所有命中的规则——这就是规则引擎的核心。

Drools 比 Aviator 强在哪

	Aviator	Drools
单条表达式	✓	✓（更复杂）
规则集合	✗	✓
条件 → 动作	✗	✓ when/then
规则间推理	✗	✓（Rete 算法）
优先级	✗	✓ salience
规则库管理	✗	✓ KieBase
业务可维护性	△ 程序员	✓ Drools Workbench / 工具
学习成本	低	高

Drools 的典型场景

复杂风控：100+ 条规则，规则之间有依赖
保险/金融：精算规则、产品定价规则
审批引擎：审批节点、条件分支
促销引擎：满减、买赠、阶梯优惠组合

Drools 的痛点

学习曲线陡——DRL 语法、KieSession、KieBase、AgendaGroup 等概念多
运维复杂——规则更新机制、Workbench 部署、版本管理
性能不一定快——Rete 算法在小规模规则下未必比 if-else 快
调试困难——规则匹配链条难追踪

不是所有"规则多变"的业务都需要 Drools。80% 的业务场景，Aviator + 配置中心就够了。

四、实战对比：同一个场景两种解法

需求：“订单金额满足条件时给折扣，规则可热更新”。

方案 A：Aviator + 配置中心

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


@Component
public class DiscountService {
 @Autowired private ConfigService configService;
 private Map<String, Expression> compiled = new ConcurrentHashMap<>();

 public BigDecimal calculate(Order order) {
 List<DiscountRule> rules = configService.getDiscountRules();
 for (DiscountRule rule : rules) {
 Expression expr = compiled.computeIfAbsent(
 rule.getId(),
 k -> AviatorEvaluator.compile(rule.getCondition()));
 
 Map<String, Object> ctx = buildContext(order);
 if ((Boolean) expr.execute(ctx)) {
 return order.getAmount().multiply(rule.getRate());
 }
 }
 return order.getAmount();
 }
}

DiscountRule 配置：

1
2
3
4
5
6


- id: vip_discount
 condition: "vip == true && amount > 500"
 rate: 0.9
- id: first_order
 condition: "newUser == true"
 rate: 0.95

优点：实现简单、学习成本极低、规则用 YAML / DB 随便配。

缺点：规则之间没有自动推理，必须按顺序匹配（开发自己 for 循环）。

方案 B：Drools

discount.drl：

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


rule "VIP 折扣"
 salience 100
 when
 $o: Order(user.vip == true, amount > 500)
 then
 $o.setDiscountRate(0.9);
end

rule "首单折扣"
 salience 50
 when
 $o: Order(user.newUser == true)
 then
 $o.setDiscountRate(0.95);
end

salience 控制优先级——VIP 规则先于首单规则。

优点：规则之间能自动推理、能并行命中、可视化工具。

缺点：上手成本高、运维复杂、调试难。

五、选型决策

flowchart TD
 Start([需要把规则抽出来?])
 Start --> Count{规则有多少?}
 Count -->|< 30 条| Simple{业务/运营要自己改?}
 Count -->|>= 30 条且复杂| Complex{规则间有推理?}
 Simple -->|是| Aviator[Aviator + 配置中心]
 Simple -->|否| Code[直接代码 + 策略模式]
 Complex -->|有| Drools[Drools]
 Complex -->|没有| Aviator2[Aviator + 配置中心]

给一个直接的工程建议：

轻量场景优先 Aviator + 配置中心；只有规则数量上百、规则间有推理、且团队有人专门维护时，才值得引入 Drools 这种完整框架。

六、踩坑提醒

Aviator 篇

1. 表达式注入风险：用户输入直接执行表达式可能被构造恶意代码：

1
2
3


// ❌ 危险
String expr = userInput;
AviatorEvaluator.execute(expr);

要么白名单校验，要么把表达式只配在管理后台（运维/产品才能改）。

2. 类型转换：JSON 反序列化的 Number 在 Aviator 里可能是 Long 或 Double，比较时要小心：

1
2
3


ctx.put("amount", 100L);
AviatorEvaluator.execute("amount > 50.5", ctx); // ✓
AviatorEvaluator.execute("amount > 50", ctx); // ✓

3. null 安全：Aviator 默认对 null 比较会报错——要在表达式里 nil != amount && amount > 100。

4. 编译缓存：同一个表达式重复 execute 时一定要预编译，否则每次都重新解析。

Drools 篇

1. 内存里的规则：DRL 改了不会自动重载——要主动 reload KieBase。生产实践通常用 Drools Workbench 或自己实现热更新。

2. then 部分别写复杂逻辑：then 是 Java 代码，但塞太多业务逻辑会让规则文件膨胀。复杂动作应该放回 Service，then 只调一行。

3. fireAllRules 的副作用：规则的 then 段可能修改 fact，触发其他规则——容易陷入"规则套规则"的循环。用 no-loop true 关键字防止。

4. 性能：Rete 算法在规则少时反而慢——50 条以下用 Drools 收益不明显。

七、规则的版本与审计

不论用哪种引擎，生产规则都需要版本管理 + 审计：

每条规则有"最后修改人"、“修改时间”、“生效时间”
修改规则要走审批（运营 → 主管 → 上线）
上线前在测试环境验证（Dry Run）
生产环境支持快速回滚到上一版本

把这些做对，比规则引擎选什么都重要。

小结

把全文压一句：

业务规则要从代码里抽出来——简单场景 Aviator 一行表达式 + 配置中心，复杂决策 Drools 完整规则引擎，绝不要硬编码 if-else 然后频繁发版。

工程实践：

规则数量少 + 改动频率低 → 直接策略模式 + 配置
规则数量中等 + 业务运营要改 → Aviator
规则数量大 + 规则间有交叉 → Drools
规则一定要版本管理 + 审计——比引擎选型更重要

把规则与代码解耦，业务才能跑得动。

ExecutorCompletionService 与 CompletableFuture：场景与选型

Sat, 25 Apr 2020 16:30:00 +0800

一段几乎所有人都写过的反面代码

需要并发调用 5 个外部接口，最后聚合结果——多数人这么写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


ExecutorService pool = Executors.newFixedThreadPool(5);
List<Future<Result>> futures = new ArrayList<>();
for (Task task : tasks) {
 futures.add(pool.submit(() -> callApi(task)));
}

List<Result> results = new ArrayList<>();
for (Future<Result> f : futures) {
 results.add(f.get()); // ★ 阻塞等
}

看起来挺合理。但有个性能陷阱——futures 的顺序是提交顺序，不是完成顺序。

假设 5 个接口耗时是：

接口	耗时
A	3s
B	1s
C	5s
D	2s
E	1s

写在 for 循环里 f.get() 时——第一次 get 拿 A 的结果（3s）→ 然后 B 的（已经完成，立刻返回）→ 然后 C（再等 2s）→ D 已完成 → E 已完成。

总耗时是 5s（最慢的那个）。这没问题。

但中间 3s ~ 5s 之间 D、E、B 都已经完成了，结果还在原地等 C——如果"处理结果"也耗时（比如把结果写 DB），整个流水线被最慢的任务卡住。

理想情况是：谁先完成，就先处理谁的结果——而不是按提交顺序傻等。ExecutorCompletionService 就是为这件事设计的。

一、CompletionService 是什么

CompletionService 是 JDK 5 就有的接口，但很多人不知道它存在：

1
2
3
4
5
6


public interface CompletionService<V> {
 Future<V> submit(Callable<V> task);
 Future<V> take() throws InterruptedException; // 阻塞，拿一个完成的
 Future<V> poll(); // 非阻塞
 Future<V> poll(long timeout, TimeUnit unit); // 超时
}

它内部维护一个已完成任务队列——任何任务完成后立刻进队列，take() 从队列取出一个。

flowchart LR
 Submit[submit×N] --> Pool[ThreadPool]
 Pool --> Done[已完成队列]
 Take[take/poll] -.从队列读.-> Done

先完成的先被取走——而不是按提交顺序等。

二、用法对比

反例：朴素 Future.get()

1
2
3
4
5
6
7
8
9


ExecutorService pool = Executors.newFixedThreadPool(5);
List<Future<Result>> futures = tasks.stream()
 .map(t -> pool.submit(() -> callApi(t)))
 .collect(toList());

for (Future<Result> f : futures) {
 Result r = f.get(); // 按提交顺序阻塞
 handle(r);
}

正解：CompletionService

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


ExecutorService pool = Executors.newFixedThreadPool(5);
CompletionService<Result> ecs = new ExecutorCompletionService<>(pool);

for (Task t : tasks) {
 ecs.submit(() -> callApi(t));
}

for (int i = 0; i < tasks.size(); i++) {
 Result r = ecs.take().get(); // 先完成的先返回
 handle(r);
}

唯一变化是 take() 替代了 f.get()——但行为完全不同。

三、性能差异：一个真实数字

5 个任务，耗时分别 1s、1s、2s、3s、5s。handle() 处理每个结果耗时 1s。

方案	耗时
朴素 Future.get()	5s + 5×1s = 10s （处理被串行化）
CompletionService	5s + 1s = 6s （处理跟着完成走）

任务越多、处理越重，差距越大。这是 CompletionService 的真正价值——让"等待"和"处理"重叠。

四、典型场景

1. 并发调多个外部接口聚合

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


public List<UserVO> batchGetUsers(List<Long> ids) {
 CompletionService<UserVO> ecs = new ExecutorCompletionService<>(pool);
 for (Long id : ids) {
 ecs.submit(() -> rpcGetUser(id));
 }
 List<UserVO> result = new ArrayList<>();
 for (int i = 0; i < ids.size(); i++) {
 try {
 result.add(ecs.take().get());
 } catch (Exception e) {
 log.warn("partial failure", e);
 }
 }
 return result;
}

2. 并发处理大批量数据，结果立刻入库

1
2
3
4
5
6
7
8


CompletionService<Record> ecs = new ExecutorCompletionService<>(pool);
for (Long id : ids) {
 ecs.submit(() -> heavyCompute(id));
}
for (int i = 0; i < ids.size(); i++) {
 Record r = ecs.take().get();
 repository.save(r); // 一完成就入库，不傻等
}

3. “找到第一个就返回"语义

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


public Result findFirstHit(List<Source> sources) {
 CompletionService<Result> ecs = new ExecutorCompletionService<>(pool);
 List<Future<Result>> futures = sources.stream()
 .map(s -> ecs.submit(() -> tryQuery(s)))
 .collect(toList());

 try {
 for (int i = 0; i < sources.size(); i++) {
 Result r = ecs.take().get();
 if (r != null) {
 return r; // 第一个非空结果返回
 }
 }
 return null;
 } finally {
 futures.forEach(f -> f.cancel(true)); // 取消其他
 }
}

五、和 CompletableFuture 的区别

JDK 8 的 CompletableFuture 是更强大的并发工具——能不能用它替代 CompletionService？

1
2
3
4
5
6


List<CompletableFuture<Result>> futures = tasks.stream()
 .map(t -> CompletableFuture.supplyAsync(() -> callApi(t), pool))
 .collect(toList());

CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
 .thenApply(v -> futures.stream().map(CompletableFuture::join).collect(toList()));

CompletableFuture 能做更多事——chain / combine / handle 异常 / async。但它默认是"等所有完成"或"等任意完成”，没有"按完成顺序逐个处理"的内置语义。

要做到"按完成顺序处理"，CompletableFuture 需要这样：

1
2
3
4
5


List<CompletableFuture<Result>> futures = tasks.stream()
 .map(t -> CompletableFuture.supplyAsync(() -> callApi(t), pool))
 .collect(toList());

futures.forEach(f -> f.thenAccept(r -> handle(r)));

也行——但每个 future 完成时回调在 ForkJoinPool / 自定义池里执行，handle 之间是并发的。如果 handle 本身要按顺序做（写 DB 不能并发），还是 CompletionService 更适合。

	CompletionService	CompletableFuture
按完成顺序处理	✓	△ 用回调
顺序处理 handle	✓ 主线程串行	△ 要再加锁/单线程
链式组合 / 异常处理	△	✓ 强
async/await 风格	✗	✓
学习曲线	低	中

简单的"并发任务 + 顺序处理结果"——CompletionService 更直接。复杂的并发编排——CompletableFuture。

六、踩坑提醒

1. take() 是阻塞的

主线程会卡住。如果上层有超时要求：

1
2
3
4


Future<Result> f = ecs.poll(500, TimeUnit.MILLISECONDS);
if (f == null) {
 // 超时
}

2. take() 调用次数要等于 submit 次数

少调一次会漏处理一个结果，多调一次会无限阻塞。用 for 循环的次数严格等于 submit 数。

3. 异常需要在 .get() 里 try

1
2
3
4
5
6
7
8
9


for (int i = 0; i < n; i++) {
 Future<Result> f = ecs.take();
 try {
 Result r = f.get();
 handle(r);
 } catch (ExecutionException e) {
 log.error("task failed", e.getCause());
 }
}

ExecutionException 包装了原始异常，getCause() 才是业务真正抛的异常。

4. 共享线程池的污染

1
2


CompletionService<X> ecsA = new ExecutorCompletionService<>(sharedPool);
CompletionService<Y> ecsB = new ExecutorCompletionService<>(sharedPool);

ECS 用的是底层 pool，不会把 A、B 的结果混淆——但池子被两边任务挤占。共享池容量要够。

5. cancel 后 take 可能拿到 cancelled future

如果你 cancel 了某些任务，take 可能拿到已 cancelled 的 future，调用 f.get() 会抛 CancellationException。一定要 catch。

6. JDK 内置实现内部用 LinkedBlockingQueue

队列无界——任务慢、消费慢时队列会无限增长。海量任务场景需要自己实现 ECS（用有界队列）或者限流。

七、一份生产级模板

 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


public <T, R> List<R> parallelExecute(
 Collection<T> tasks,
 Function<T, R> action,
 ExecutorService pool,
 long timeout,
 TimeUnit unit) {

 CompletionService<R> ecs = new ExecutorCompletionService<>(pool);
 List<Future<R>> futures = tasks.stream()
 .map(t -> ecs.submit(() -> action.apply(t)))
 .collect(toList());

 long deadline = System.nanoTime() + unit.toNanos(timeout);
 List<R> results = new ArrayList<>();
 try {
 for (int i = 0; i < tasks.size(); i++) {
 long remaining = deadline - System.nanoTime();
 Future<R> f = ecs.poll(remaining, TimeUnit.NANOSECONDS);
 if (f == null) {
 log.warn("partial timeout, completed {}/{}", i, tasks.size());
 break;
 }
 try {
 results.add(f.get());
 } catch (ExecutionException e) {
 log.error("task failed", e.getCause());
 }
 }
 } catch (InterruptedException e) {
 Thread.currentThread().interrupt();
 } finally {
 futures.forEach(f -> f.cancel(true)); // 主流程结束时取消未完成任务
 }
 return results;
}

小结

把全文压一句：

ExecutorCompletionService 让『先完成的任务先被处理』——这是 Java 并发里最被低估的一个工具。

什么时候选它：

多个任务并发执行
需要按完成顺序逐个处理结果
处理逻辑本身耗时 / 串行
不需要 CompletableFuture 的复杂编排

工程纪律：

submit 几次就要 take 几次
异常 catch ExecutionException + getCause
主流程结束 cancel 未完成任务
海量任务时换有界队列实现

下次再写"并发调 N 个外部接口然后处理结果"时——别再 for 循环 f.get() 了。

服务端到客户端的进度推送：SSE 与 WebSocket 选型

Thu, 12 Mar 2020 16:00:00 +0800

一个看似简单的需求

用户在管理后台点"导出报表"——服务端要生成一个 200MB 的 Excel，前端等 30 秒。最差的体验是这样：

点了按钮，前端转圈圈。30 秒过去——用户以为卡住了，开始连点。后端被点出三次重复任务，最后崩了。

合格的体验应该是：

点了按钮，立刻看到"正在生成 Excel…12%"，每秒进度条往上跳，用户安心等待。

实现这种"实时进度反馈"看起来不复杂——但坑很多：

HTTP 是请求-响应模型，服务端没法主动告诉前端"现在 20% 了"
进度怎么从生成 Excel 的线程"流"到 HTTP 响应里
浏览器有 Range 请求、有 chunked 编码、有 SSE、有 WebSocket——该选哪个

本文把三种主流方案讲清楚——HTTP 流式响应、SSE、WebSocket。各自的优劣、代码、踩坑都覆盖。

一、需求拆解：什么叫"下载进度"

要讲清进度反馈，先把"下载"分两类：

类型 A：纯文件传输

文件已存在，浏览器直接下载——进度信息浏览器自己能算（Content-Length / 已接收字节）。前端不需要服务端告诉，可以自己监听 progress 事件。这种场景根本不需要后端反馈。

1
2
3
4
5
6
7
8


const xhr = new XMLHttpRequest();
xhr.responseType = 'blob';
xhr.onprogress = e => {
 const percent = (e.loaded / e.total * 100).toFixed(1);
 setProgress(percent); // 浏览器自己算
};
xhr.open('GET', '/file/download/1');
xhr.send();

这种是大部分场景——多数情况下不需要后端介入，避免加不必要的复杂度。

类型 B：服务端要先"做事"才有文件

真正复杂的——服务端先生成 Excel（30 秒）、再让前端下载。生成过程中浏览器看到的是 0 字节、Content-Length 还没确定。进度只有服务端知道。

类型 B 才是本文的主场。

二、方案 1：HTTP 流式响应（chunked）

最简单的姿势——把"任务进度"和"最终文件"塞到一个 HTTP 响应里。

服务端用 StreamingResponseBody，每行输出一个 JSON（NDJSON / JSON-Lines）：

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


@GetMapping("/export")
public ResponseEntity<StreamingResponseBody> export() {
 StreamingResponseBody stream = output -> {
 for (int i = 0; i <= 100; i += 10) {
 // 输出一行 JSON + \n
 String line = String.format("{\"progress\":%d}\n", i);
 output.write(line.getBytes(StandardCharsets.UTF_8));
 output.flush();
 Thread.sleep(500); // 模拟工作
 }
 output.write("{\"done\":true,\"url\":\"/file/123\"}\n".getBytes(StandardCharsets.UTF_8));
 };
 return ResponseEntity.ok()
 .contentType(MediaType.parseMediaType("application/x-ndjson"))
 .body(stream);
}

这里故意不用 SSE 的 data: …\n\n 协议格式——避免和方案 2 混淆。要 SSE 就直接用 SseEmitter（见方案 2），这里就是普通的"按行 JSON 流"。

前端用 fetch + ReadableStream 读：

1
2
3
4
5
6
7
8


const resp = await fetch('/export');
const reader = resp.body.getReader();
while (true) {
 const { done, value } = await reader.read();
 if (done) break;
 const text = new TextDecoder().decode(value);
 // 解析进度
}

优点：

实现简单，一个接口搞定
浏览器原生支持

缺点：

进度信息和文件内容混在一个流里，前端要自己解析协议
不是标准协议，每个项目都可能不一样

适合简单场景——不推荐做复杂业务。

三、方案 2：SSE（Server-Sent Events）

SSE 是 HTML5 的标准——专门为"服务端推送给客户端"设计，比 WebSocket 简单一半。

服务端

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


@GetMapping(value = "/export/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter exportStream() {
 SseEmitter emitter = new SseEmitter(60_000L); // 60s 超时

 executor.execute(() -> {
 try {
 for (int i = 0; i <= 100; i += 5) {
 emitter.send(SseEmitter.event()
 .name("progress")
 .data(Map.of("percent", i, "msg", "处理中...")));
 Thread.sleep(500);
 }
 // 最终输出文件下载链接
 emitter.send(SseEmitter.event()
 .name("done")
 .data(Map.of("url", "/file/12345")));
 emitter.complete();
 } catch (Exception e) {
 emitter.completeWithError(e);
 }
 });
 return emitter;
}

前端

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


const evt = new EventSource('/export/stream');

evt.addEventListener('progress', e => {
 const data = JSON.parse(e.data);
 setProgress(data.percent);
});

evt.addEventListener('done', e => {
 const data = JSON.parse(e.data);
 window.location.href = data.url;
 evt.close();
});

evt.onerror = err => {
 console.error('SSE error', err);
 evt.close();
};

SSE 的特点

服务端 → 客户端单向——客户端不能用同一通道发消息
基于 HTTP——不需要握手协议升级，CDN 能转发
自动重连——网络断了浏览器自动重连
协议极简——event 名 + data 行
比 WebSocket 轻量——但功能少一半

一个常被忽视的细节

很多 PaaS / Nginx 默认 buffer 响应，SSE 推送的消息要等 buffer 满了才到前端。要在 nginx 里关闭：

1
2
3
4
5
6


location /export/ {
 proxy_pass http://backend;
 proxy_buffering off; # ★ 关键
 proxy_read_timeout 3600s;
 chunked_transfer_encoding on;
}

不开就是"明明代码 emit 了但前端 30 秒后才一次性收到所有进度"。

四、方案 3：WebSocket

最重量级的——双向通信，服务端推前端、前端发命令到服务端都行。

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


@Component
public class ExportWebSocketHandler extends TextWebSocketHandler {

 @Override
 public void handleTextMessage(WebSocketSession session, TextMessage msg) throws Exception {
 // 收到前端"开始导出"指令后启动任务
 ExportRequest req = JSON.parseObject(msg.getPayload(), ExportRequest.class);
 executor.execute(() -> doExport(session, req));
 }

 private void doExport(WebSocketSession session, ExportRequest req) {
 try {
 for (int i = 0; i <= 100; i += 5) {
 session.sendMessage(new TextMessage(JSON.toJSONString(
 Map.of("type", "progress", "percent", i))));
 Thread.sleep(500);
 }
 session.sendMessage(new TextMessage(JSON.toJSONString(
 Map.of("type", "done", "url", "/file/123"))));
 } catch (Exception e) {
 log.error("export error", e);
 }
 }
}

适用场景：

同一连接里要前端 → 后端发指令（如取消任务、调整参数）
已经有 WebSocket 长连接复用
复杂双向交互（如客服聊天 + 文件传输）

但单纯做"进度反馈"上 WebSocket 是杀鸡用牛刀——SSE 已经够了。

五、三方案对比

	StreamingResponseBody	SSE	WebSocket
实现复杂度	极简	简单	中
协议	HTTP	HTTP（standard）	HTTP Upgrade
双向	✗	✗ 单向	✓
自动重连	✗	✓	✗（要自己写）
Nginx 兼容	△	△（要关 buffer）	△（要 upgrade 配置）
浏览器支持	✓ 全部	✓ 全部	✓ 全部
适用场景	进度+文件混合	单向进度反馈	双向交互

给一个直接的建议：

类型 A（纯文件下载）：浏览器原生 progress；类型 B（服务端做事 + 进度）：99% 用 SSE 就够。WebSocket 留给真正的双向场景。

六、生产细节

1. 进度的"真实性"

1
2
3
4


for (int i = 0; i <= 100; i += 5) {
 emit(i);
 Thread.sleep(500);
}

写成这样的进度是假进度——看着舒服但和真实工作进度无关。生产代码进度要从真实业务里取：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public void doExport(SseEmitter emitter, List<User> users) {
 int total = users.size();
 for (int i = 0; i < total; i++) {
 process(users.get(i));
 if (i % 100 == 0 || i == total - 1) { // 每 100 条推一次
 emitter.send(SseEmitter.event()
 .name("progress")
 .data(Map.of("percent", i * 100 / total)));
 }
 }
}

2. 异常处理

1

emitter.send(...); // 客户端断开会抛 IllegalStateException

客户端关页面、断网、超时——服务端继续 send 会异常。要 catch 后调 emitter.completeWithError(e)，并停止剩余工作（节省服务器资源）。

3. 资源清理

SseEmitter 是要释放的——onCompletion、onTimeout、onError 三个回调要注册：

1
2
3


emitter.onCompletion(() -> log.info("client disconnected"));
emitter.onTimeout(() -> log.warn("session timeout"));
emitter.onError(err -> log.error("session error", err));

4. 不要在 SSE 通道传文件本体

进度通道传进度元数据，文件本体走单独下载链接：

1
2


SSE 推送 → 任务完成时给一个临时下载 URL
前端拿到 URL → 触发标准下载

不要硬塞 base64 文件到 SSE，体积和性能都差。

5. 限流

SseEmitter 是长连接——大流量场景要限连接数（防止有人开 1 万个连接）：

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


@RestController
public class ExportController {
 private final Semaphore connections = new Semaphore(100); // 最多 100 并发

 @GetMapping("/export/stream")
 public SseEmitter export() {
 if (!connections.tryAcquire()) {
 throw new BusinessException("服务繁忙");
 }
 SseEmitter emitter = new SseEmitter();
 emitter.onCompletion(connections::release);
 emitter.onTimeout(connections::release);
 emitter.onError(e -> connections.release());
 // ...
 return emitter;
 }
}

6. 跨进程任务进度

如果导出任务是异步发到 MQ 或别的进程执行——进度数据要走 Redis：

flowchart LR
 Front --> SSE[SSE Endpoint]
 SSE -.poll.-> Redis[(Redis)]
 Worker[(异步 Worker)] -.write.-> Redis

SSE 通道每秒查一次 Redis 拿进度推给前端，Worker 进度写 Redis。进度生产和消费解耦。

小结

把全文压一句：

HTTP 是请求响应模型，要做"实时进度反馈"，就要打开一个『可以持续推送』的通道——单向选 SSE，双向选 WebSocket，文件本体永远走标准 HTTP 下载。

工程要点：

浏览器原生 progress 能算的进度，别让后端反馈
后端进度反馈优先 SSE
真实进度比假进度重要
Nginx proxy_buffering off 是 SSE 必配
进度和文件本体分离

把这套方案吃透，“导出报表"这种烦人功能能瞬间从 1 星体验变成 5 星。

JDK 8 Stream 与 Lambda 实战指南

Thu, 21 Nov 2019 15:30:00 +0800

写在前面

JDK 8 已经发布超过 5 年（写本文时是 2019 年）——如果你还在写这种代码：

1
2
3
4
5
6
7
8
9


List<String> result = new ArrayList<>();
for (User user : users) {
 if (user.getAge() >= 18) {
 if (user.getStatus() == 1) {
 result.add(user.getName().toUpperCase());
 }
 }
}
Collections.sort(result);

而不是这种：

1
2
3
4
5
6


List<String> result = users.stream()
 .filter(u -> u.getAge() >= 18)
 .filter(u -> u.getStatus() == 1)
 .map(u -> u.getName().toUpperCase())
 .sorted()
 .collect(Collectors.toList());

那是时候认真学一下 Stream 和 Lambda 了。

Stream 不只是"写法变化"——它把 Java 的数据处理范式从"循环 + 临时变量"改成"声明式管道"，让 Java 写起来像 SQL。

本文从基础到进阶把 Stream + Lambda 的常用、好用、容易踩坑的姿势过一遍。

一、Lambda：函数式接口的捷径

Lambda 是什么

Lambda 表达式是函数式接口的实例——一个匿名类的极简写法。

1
2
3
4
5
6
7
8
9


// JDK 8 之前
Runnable r = new Runnable() {
 @Override public void run() {
 System.out.println("hello");
 }
};

// JDK 8 Lambda
Runnable r = () -> System.out.println("hello");

任何只有一个抽象方法的接口（即 SAM——Single Abstract Method）都能用 Lambda 替代。

函数式接口家族

JDK 提供了一组通用函数式接口：

接口	签名	用途
`Function<T, R>`	R apply(T t)	转换
`Predicate<T>`	boolean test(T t)	判断
`Consumer<T>`	void accept(T t)	消费
`Supplier<T>`	T get()	提供
`BiFunction<T,U,R>`	R apply(T, U)	二元转换
`BinaryOperator<T>`	T apply(T, T)	二元归约

1
2
3
4


Function<Integer, String> f = i -> "num:" + i;
Predicate<String> isLong = s -> s.length() > 10;
Consumer<String> print = System.out::println;
Supplier<List<String>> newList = ArrayList::new;

方法引用：Lambda 的更简洁形式

1
2
3
4
5


// Lambda
users.stream().map(u -> u.getName())

// 方法引用（更简洁）
users.stream().map(User::getName)

四种方法引用：

类型	语法	例子
静态方法	`Class::method`	`Integer::parseInt`
实例方法	`instance::method`	`System.out::println`
类的实例方法	`Class::method`	`String::toUpperCase`
构造方法	`Class::new`	`ArrayList::new`

二、Stream：流式数据处理

一个 Stream 的生命周期

flowchart LR
 Source[数据源
List/Set/Array] --> Intermediate[中间操作
filter/map/sorted]
 Intermediate --> Terminal[终止操作
collect/forEach/reduce]
 Terminal --> Result[结果]

中间操作返回 Stream<T>，可以继续链式调用——懒执行
终止操作触发实际计算——只能调一次

常用中间操作

 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


List<User> users = ...;

// filter：筛选
users.stream().filter(u -> u.getAge() > 18)

// map：变换
users.stream().map(User::getName)
users.stream().mapToInt(User::getAge) // 原始类型流，避免装箱

// flatMap：拍平嵌套结构
users.stream().flatMap(u -> u.getRoles().stream())

// distinct：去重
users.stream().map(User::getCity).distinct()

// sorted：排序
users.stream().sorted(Comparator.comparing(User::getAge))
users.stream().sorted(Comparator.comparing(User::getAge).reversed())
users.stream().sorted(Comparator.comparing(User::getCity).thenComparing(User::getAge))

// limit / skip：分页
users.stream().skip(20).limit(10)

// peek：调试用
users.stream().peek(u -> log.debug("processing {}", u))

常用终止操作

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


// collect：收集成集合
List<User> list = users.stream().filter(...).collect(toList());
Set<String> set = users.stream().map(User::getName).collect(toSet());

// 收集成 Map
Map<Long, User> map = users.stream().collect(toMap(User::getId, Function.identity()));

// 分组
Map<String, List<User>> byCity = users.stream().collect(groupingBy(User::getCity));

// 聚合：count/sum/avg/min/max
long count = users.stream().filter(u -> u.getAge() >= 18).count();
int totalAge = users.stream().mapToInt(User::getAge).sum();

// 归约
int max = users.stream().mapToInt(User::getAge).max().orElse(0);

// 短路操作
boolean anyAdult = users.stream().anyMatch(u -> u.getAge() >= 18);
Optional<User> first = users.stream().filter(...).findFirst();

// forEach
users.stream().forEach(System.out::println);

三、Stream 的范式价值：让 Java 代码像 SQL

很多人觉得 Stream 是"换汤不换药"——其实它是数据处理范式的转移。看这两段代码：

场景：从用户列表里统计每个城市 18 岁以上用户的平均年龄，按平均年龄降序

传统写法：

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


Map<String, List<Integer>> cityAges = new HashMap<>();
for (User u : users) {
 if (u.getAge() >= 18) {
 cityAges.computeIfAbsent(u.getCity(), k -> new ArrayList<>())
 .add(u.getAge());
 }
}
Map<String, Double> avgByCity = new HashMap<>();
for (Map.Entry<String, List<Integer>> e : cityAges.entrySet()) {
 double avg = e.getValue().stream().mapToInt(Integer::intValue).average().orElse(0);
 avgByCity.put(e.getKey(), avg);
}
List<Map.Entry<String, Double>> sorted = new ArrayList<>(avgByCity.entrySet());
sorted.sort((a, b) -> Double.compare(b.getValue(), a.getValue()));

Stream 写法：

1
2
3
4
5
6


List<Map.Entry<String, Double>> result = users.stream()
 .filter(u -> u.getAge() >= 18)
 .collect(groupingBy(User::getCity, averagingInt(User::getAge)))
 .entrySet().stream()
 .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
 .collect(toList());

SQL 等价：

1
2
3
4
5


SELECT city, AVG(age) avg_age
FROM users
WHERE age >= 18
GROUP BY city
ORDER BY avg_age DESC;

Stream 写法和 SQL 几乎一一对应——这就是范式价值。写起来你描述的是『要什么』，不是『怎么做』。

四、Collectors 的进阶用法

Collectors 是 Stream 的"宝藏类"，掌握后能写出极强的归约操作：

 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


// 计数
Map<String, Long> count = users.stream()
 .collect(groupingBy(User::getCity, counting()));

// 求和
Map<String, Integer> sum = users.stream()
 .collect(groupingBy(User::getCity, summingInt(User::getAge)));

// 平均
Map<String, Double> avg = users.stream()
 .collect(groupingBy(User::getCity, averagingInt(User::getAge)));

// 收集到 List 但只取名字
Map<String, List<String>> names = users.stream()
 .collect(groupingBy(User::getCity, mapping(User::getName, toList())));

// 拼接成字符串
String allNames = users.stream()
 .map(User::getName)
 .collect(joining(", ", "[", "]")); // → [张三, 李四, 王五]

// 多级分组
Map<String, Map<Integer, List<User>>> byCityAndAge = users.stream()
 .collect(groupingBy(User::getCity, groupingBy(User::getAge)));

// partitioningBy：boolean 分两组
Map<Boolean, List<User>> adultPart = users.stream()
 .collect(partitioningBy(u -> u.getAge() >= 18));

五、Optional：终结 NPE 的优雅工具

JDK 8 还引入了 Optional——配合 Stream 用得心应手。

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


// 旧写法
User u = userRepo.findById(1L);
if (u != null) {
 String name = u.getName();
 if (name != null) {
 return name.toUpperCase();
 }
}
return "UNKNOWN";

// Optional 写法
return Optional.ofNullable(userRepo.findById(1L))
 .map(User::getName)
 .map(String::toUpperCase)
 .orElse("UNKNOWN");

Optional 用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Optional<User> opt = userRepo.findById(1L);

opt.isPresent(); // 是否有值
opt.ifPresent(u -> log.info(u)); // 有值时执行
opt.orElse(defaultUser); // 没值时给默认
opt.orElseGet(() -> heavyDefault()); // 没值时延迟计算默认
opt.orElseThrow(() -> new BusinessException("not found"));
opt.filter(u -> u.getAge() > 18); // 不满足时变 empty
opt.map(User::getName); // 转换
opt.flatMap(u -> Optional.ofNullable(u.getEmail())); // 链式 Optional

Optional 的边界

Optional 只设计用作返回值——不要做参数、不要做字段：

1
2
3
4
5
6
7
8


// ❌ 反模式：字段
private Optional<User> user;

// ❌ 反模式：参数
public void process(Optional<User> u) {}

// ✓ 返回值
public Optional<User> findUser(Long id) {}

字段用 Optional 浪费内存（包装类）；参数用 Optional 让调用方多一次包装动作，得不偿失——直接接受可空参数 + 内部 Optional.ofNullable 处理。

六、踩坑提醒

1. Stream 不能复用

1
2
3


Stream<User> s = users.stream().filter(...);
List<User> a = s.collect(toList());
List<User> b = s.collect(toList()); // ❌ IllegalStateException: stream has already been operated upon

2. forEach 里的副作用

1
2


List<User> result = new ArrayList<>();
users.stream().forEach(result::add); // ❌ 反模式

要收集结果用 collect(toList())——forEach 是"消费"语义，不是"收集"。

3. parallelStream 不是免费午餐

1

users.parallelStream().filter(...).collect(toList());

并行流听起来很美——多数场景下比串行慢：

集合元素少（< 1 万）：开销盖过收益
操作很快（CPU < 1ms）：线程切换更亏
I/O 密集（数据库/文件）：会把公共 ForkJoinPool 占满，影响其他业务

只在 CPU 密集 + 数据量大 + 没共享状态时才考虑 parallelStream，且最好用自己的 ForkJoinPool 而不是公共的。

4. toMap 的 key 重复

1
2


users.stream().collect(toMap(User::getCity, Function.identity()));
// → IllegalStateException: duplicate key

key 重复时要指定 merge 函数：

1

users.stream().collect(toMap(User::getCity, Function.identity(), (a, b) -> a));

5. mapToInt vs map

1
2


users.stream().mapToInt(User::getAge).sum(); // ✓
users.stream().map(User::getAge).reduce(0, Integer::sum); // ❌ 涉及装箱拆箱，慢

数值场景优先用 mapToInt/Long/Double——能避免装箱开销。

6. peek 不要做副作用

1

users.stream().peek(u -> u.setStatus(1)).count(); // ❌ peek 是调试用的

JDK 9+ 在终止操作是 count() 等"已知不需要遍历"的可短路场景下，会跳过 peek——副作用不执行。普通 collect / forEach 的 peek 会执行，但语义上 peek 就只是"调试用的旁路"——业务副作用不要放在 peek 里。

七、什么场景该用 Stream，什么场景不该

✅ 适合 Stream 的场景

数据筛选 / 转换 / 聚合
多步数据处理
集合 → 集合
写法贴近 SQL 的场景

❌ 不适合 Stream 的场景

简单循环——for (Foo f : list) 比 list.forEach(...) 更直观
检查异常需要处理——Lambda 里抛 checked exception 是噩梦
需要 break/continue——Stream 没有这种语义（虽然 findFirst 类似 break）
需要修改外部变量——Stream 强制函数式风格
可读性比性能更重要——简单逻辑别强行链式

小结

把全文压一句：

Stream + Lambda 不是写法升级，是范式转移——让 Java 从『循环 + 临时变量』变成『声明式管道』，写起来像 SQL，读起来像描述意图。

记住几条：

优先方法引用，其次 Lambda，最后匿名内部类（按可读性视情况调整）
Optional 只作返回值，不做字段/参数
parallelStream 慎用，多数场景串行更快
数值用 mapToInt/Long/Double
复杂归约都在 Collectors 里

把这套姿势用熟，Java 写数据处理代码会突然变得轻松——这种顿悟感是 JDK 8 给 Java 写代码人的最大礼物。

MyBatis 增强工具选型：MyBatis-Plus 与通用 Mapper 全面对比

Fri, 25 Oct 2019 20:00:00 +0800

写在前面

如果你写过原生 MyBatis，一定经历过这种崩溃时刻——

1
2
3
4
5
6
7
8


<select id="selectByCondition" resultType="User">
 SELECT id, name, age, status FROM user
 <where>
 <if test="name != null">AND name = #{name}</if>
 <if test="age != null">AND age = #{age}</if>
 <if test="status != null">AND status = #{status}</if>
 </where>
</select>

每张表都要写一遍 CRUD，字段一变就改十几个 XML，任何"按字段查"“按字段更新"都要新加一段 SQL。这种重复劳动催生了两个现象级开源项目：

通用 Mapper（tk.mybatis）：刘增辉（abel533）2014 年开源
MyBatis-Plus（MP）：苞米豆团队 2016 年开源

两者都自称"MyBatis 增强工具”，新人选型时常常分不清。本文把这两个项目从设计哲学、能力边界、典型用法、踩坑点一一对照，给出明确的选型建议。

一句话定位

通用 Mapper：在 MyBatis 上提供"通用 SQL 模板"，让你不写 XML 就能完成基础 CRUD。

MyBatis-Plus：在 MyBatis 上提供"增强能力 + 工具集"，目标是把 MyBatis 用得像 JPA 一样省事，同时保留 MyBatis 的灵活性。

通用 Mapper 是"做减法"——少写 XML；MyBatis-Plus 是"做加法"——给你一整套生态工具。

一、通用 Mapper 是怎么工作的

通用 Mapper 的核心思想：给你一个泛型 Mapper<T>，里面已经定义了一堆通用方法，框架在运行时根据泛型类型生成对应的 SQL。

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


public interface UserMapper extends Mapper<User> {
}

@Service
public class UserService {
 @Autowired private UserMapper userMapper;

 public User get(Long id) { return userMapper.selectByPrimaryKey(id); }
 public int add(User u) { return userMapper.insert(u); }
 public int update(User u) { return userMapper.updateByPrimaryKey(u); }
 public int remove(Long id) { return userMapper.deleteByPrimaryKey(id); }
}

实体类用 JPA 风格注解：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@Table(name = "user")
public class User {
 @Id
 @GeneratedValue(strategy = GenerationType.IDENTITY)
 private Long id;
 private String name;
 private Integer age;
 @Column(name = "status_code")
 private Integer status;
}

它的核心方法分几大类：

接口	提供能力
`BaseSelectMapper`	selectByPrimaryKey 等
`BaseInsertMapper`	insert
`BaseUpdateMapper`	updateByPrimaryKey
`BaseDeleteMapper`	deleteByPrimaryKey
`ConditionMapper`	通过 Example 条件查询
`RowBoundsMapper`	分页（基于 RowBounds）

复杂条件用 Example：

1
2
3
4
5


Example example = new Example(User.class);
example.createCriteria()
 .andEqualTo("status", 1)
 .andLike("name", "张%");
List<User> users = userMapper.selectByExample(example);

风格非常贴近 JPA Specification，有点"老 SSH 时代"的味道。

二、MyBatis-Plus 是怎么工作的

MyBatis-Plus 的核心入口是 BaseMapper<T> 和 IService<T> 两层抽象：

1
2
3
4
5
6
7
8
9


public interface UserMapper extends BaseMapper<User> {
}

public interface UserService extends IService<User> {
}

@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
}

实体类用 MP 自家注解（也可继承 Model<T>）：

1
2
3
4
5
6
7
8
9


@TableName("user")
public class User {
 @TableId(type = IdType.AUTO)
 private Long id;
 private String name;
 private Integer age;
 @TableField("status_code")
 private Integer status;
}

最闪光的是它的 LambdaQueryWrapper——以方法引用代替字符串字段名，全程类型安全：

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


List<User> users = userMapper.selectList(
 new LambdaQueryWrapper<User>()
 .eq(User::getStatus, 1)
 .like(User::getName, "张")
 .orderByDesc(User::getId)
);

userMapper.update(null,
 new LambdaUpdateWrapper<User>()
 .set(User::getStatus, 0)
 .eq(User::getId, 100L)
);

字段重命名时编译器会立刻报错，再也不用拼字符串。

三、能力对比

	通用 Mapper	MyBatis-Plus
基础 CRUD	✓	✓
条件构造	Example（字符串字段）	LambdaQueryWrapper（类型安全）
分页	RowBounds（物理分页要插件）	PaginationInterceptor（开箱即用）
主键策略	JPA `@GeneratedValue`	`IdType.AUTO/INPUT/ASSIGN_ID/ASSIGN_UUID` 等
自动填充	✗	`@TableField(fill = ...)` + Handler
逻辑删除	✗	`@TableLogic` 自动 where deleted=0
乐观锁	✗	`@Version` 自动 where version=#{old}
多租户	✗	TenantLineInnerInterceptor
数据权限/字段加密	✗	插件机制
代码生成器	第三方	官方代码生成器 + AI Friendly
ActiveRecord	✗	`Model<T>`（争议特性，不推荐用）
性能分析插件	✗	慢 SQL 输出、SQL 注入检测

简单说：通用 Mapper 只解决"少写 CRUD SQL"，MyBatis-Plus 是一整套生态。

四、设计哲学差异

通用 Mapper：贴近 JPA、最小侵入

用的是 javax.persistence.* 注解，和 JPA 互通——理论上可以无缝切到 Spring Data JPA
不引入新概念，学习成本极低
一切以"少写 SQL"为目标，不试图替你做更多事

MyBatis-Plus：全套生态、约定大于配置

自家注解 @TableId、@TableField、@TableLogic 等，绑定较深
提供了大量"开箱即用的便利"——逻辑删除、乐观锁、自动填充、分页都不用自己写代码
从 ORM 一直管到代码生成、慢 SQL 监控

简单总结：

通用 Mapper 是"工具"，MyBatis-Plus 是"框架"。

五、典型场景对比

场景 1：分页

通用 Mapper 自己只支持 RowBounds，物理分页要配合 PageHelper：

1
2
3


PageHelper.startPage(1, 10);
List<User> users = userMapper.selectAll();
PageInfo<User> page = new PageInfo<>(users);

MyBatis-Plus 自带分页插件：

1
2
3
4


IPage<User> page = userMapper.selectPage(
 new Page<>(1, 10),
 new LambdaQueryWrapper<User>().eq(User::getStatus, 1)
);

场景 2：逻辑删除

通用 Mapper 没有原生支持，要么写 SQL，要么自己注入 SqlInterceptor。

MyBatis-Plus 一个注解搞定：

1
2


@TableLogic
private Integer deleted; // 0 未删，1 已删

之后所有 selectXxx、deleteXxx 自动带上 WHERE deleted = 0，省心。

场景 3：自动填充 createTime / updateTime

通用 Mapper 要靠拦截器或自己手写。

MyBatis-Plus：

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


@TableField(fill = FieldFill.INSERT)
private LocalDateTime createTime;

@TableField(fill = FieldFill.INSERT_UPDATE)
private LocalDateTime updateTime;

@Component
public class MetaHandler implements MetaObjectHandler {
 @Override public void insertFill(MetaObject m) {
 this.strictInsertFill(m, "createTime", LocalDateTime.class, LocalDateTime.now());
 this.strictInsertFill(m, "updateTime", LocalDateTime.class, LocalDateTime.now());
 }
 @Override public void updateFill(MetaObject m) {
 this.strictUpdateFill(m, "updateTime", LocalDateTime.class, LocalDateTime.now());
 }
}

这种"业务无感"的能力是 MP 的杀手锏。

六、坑与争议

通用 Mapper 的坑

Example 用字符串字段名——重构改字段名时不报错，运行时才挂
生态薄——分页、性能监控、代码生成都要自己整合第三方
维护活跃度低——近几年更新明显放缓

MyBatis-Plus 的争议点

Wrapper 写多了 SQL 会变难读——复杂查询还是建议回到 XML
ActiveRecord (Model<T>) 模式虽然炫，但耦合实体和持久层，不推荐生产用
绑定较深——后期想换框架成本比通用 Mapper 高
历史上有过 SQL 注入 CVE——升级版本要及时跟

最值得提醒的一点：Wrapper 不要写超过 3 层的复杂条件。可读性是 SQL 维护的天花板。

七、选型建议

	通用 Mapper	MyBatis-Plus
单表 CRUD 占主导	✓	✓✓ （更顺手）
复杂多表 SQL	XML 写	XML + Wrapper 混用
团队熟悉 JPA	✓	△
想用全套生态工具	✗	✓
介意框架侵入	✓ 轻	△ 较重
项目活跃度需求	△	✓
学习曲线	平	略陡（Wrapper、插件多）
社区资料	较少	大量

给一个直接的建议：

新项目优先 MyBatis-Plus，社区活跃、生态完整、Lambda 类型安全，几乎没有理由选通用 Mapper。

老项目已用通用 Mapper 且稳定，没必要为了 MP 重构；对接新表时可以两者共存，MP 接 BaseMapper<T>，通用 Mapper 留旧 Mapper<T>，互不干扰。

八、共存方案

如果项目里同时存在两套 Mapper 也不冲突，但有几个细节：

包路径要分开——别让一个 Mapper 同时继承两套接口
MapperScan 要明确：

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


@Configuration
public class MybatisConfig {
 @Bean
 public MapperScannerConfigurer tk() {
 MapperScannerConfigurer s = new MapperScannerConfigurer();
 s.setBasePackage("com.app.mapper.tk");
 s.setMarkerInterface(tk.mybatis.mapper.common.Mapper.class);
 return s;
 }

 @Bean
 public MapperScannerConfigurer mp() {
 MapperScannerConfigurer s = new MapperScannerConfigurer();
 s.setBasePackage("com.app.mapper.mp");
 s.setMarkerInterface(com.baomidou.mybatisplus.core.mapper.BaseMapper.class);
 return s;
 }
}

实体类注解最好不要混用——同一个实体要么用 javax.persistence.*，要么用 @TableName/@TableId，别两边都加

小结

把全文压成一句话：

通用 Mapper 是 MyBatis 的"轻量减法"，MyBatis-Plus 是 MyBatis 的"完整加法"。在 2019 年之后的新项目，几乎没有理由再选通用 Mapper。

不管选哪个，记住几个一致的工程纪律：

不要被工具骗了，别碰复杂多表 Wrapper——XML 永远是复杂查询的归宿
不要写 ActiveRecord——实体类只描述结构，不调持久层方法
不要忘了原生 MyBatis 的能力——MP/通用 Mapper 都只是 MyBatis 的扩展，复杂场景永远可以回到 Mapper.xml

把工具当工具用，别让工具反过来定义你的代码风格——这是任何框架选型都通用的原则。

Spring 参数校验完整指南：JSR-380 与 Hibernate Validator

Sat, 17 Aug 2019 16:30:00 +0800

校验该写在哪一层？

很多项目里随处可见这样的代码：

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


public Result createUser(UserDTO dto) {
 if (dto.getName() == null || dto.getName().isEmpty()) {
 return Result.fail("姓名不能为空");
 }
 if (dto.getAge() == null || dto.getAge() < 0 || dto.getAge() > 200) {
 return Result.fail("年龄不合法");
 }
 if (!Pattern.matches("^1[3-9]\\d{9}$", dto.getPhone())) {
 return Result.fail("手机号格式错误");
 }
 // ... 真正的业务逻辑
}

每个 Controller 都重复一遍，手工拼错误消息，堆得密不透风。这种代码不该出现在业务方法里——校验是输入边界的责任，应该在数据进入业务方法前就被自动拦截。

Bean Validation（JSR-380）和它的事实标准实现 Hibernate Validator 就是为这件事而生。今天我们把它的常见用法和"骚姿势"过一遍。

基础：常用注解一览

注解	作用	适用类型
`@NotNull`	不能为 null	任意
`@NotEmpty`	不能 null 且不能为空	String / Collection / Array
`@NotBlank`	不能 null 且 trim 后非空	String
`@Size(min,max)`	长度/大小范围	String / Collection
`@Min` / `@Max`	数值最小/最大	数字
`@DecimalMin/Max`	支持 BigDecimal 的最小最大	数字
`@Positive` / `@Negative`	正数 / 负数	数字
`@Pattern(regexp)`	正则匹配	String
`@Email`	邮箱格式	String
`@Past` / `@Future`	过去 / 未来时间	时间类型
`@AssertTrue`	必须为 true	boolean
`@Valid`	触发嵌套校验	对象 / 集合

一份典型的 DTO：

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


public class UserCreateDTO {

 @NotBlank(message = "姓名不能为空")
 @Size(max = 20, message = "姓名最长 20 个字")
 private String name;

 @NotNull(message = "年龄必填")
 @Min(value = 0, message = "年龄不能为负")
 @Max(value = 200, message = "年龄太离谱了")
 private Integer age;

 @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不对")
 private String phone;

 @Email(message = "邮箱格式不对")
 private String email;

 @Valid // 嵌套校验
 private AddressDTO address;
}

接入 Spring：一个 `@Valid` 全自动

Spring MVC 集成是开箱即用的——参数前加 @Valid，校验失败会抛 MethodArgumentNotValidException：

1
2
3
4
5


@PostMapping("/users")
public Result createUser(@RequestBody @Valid UserCreateDTO dto) {
 // 进到这里，所有约束都已经通过
 return userService.create(dto);
}

Path Variable / Request Param 上需要 @Validated 在 Controller 类上配合：

1
2
3
4
5
6
7
8
9


@RestController
@Validated
public class UserController {

 @GetMapping("/users/{id}")
 public Result get(@PathVariable @Min(1) Long id) {
 return userService.get(id);
 }
}

Path/Param 校验失败会抛 ConstraintViolationException，异常类型和 @RequestBody 不一样，需要分别处理。

全局异常处理：让校验报错优雅返回

Controller 内部不该处理校验异常，应该用全局异常处理器统一处理：

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


@RestControllerAdvice
public class GlobalExceptionHandler {

 // @RequestBody 校验失败
 @ExceptionHandler(MethodArgumentNotValidException.class)
 public Result handleBody(MethodArgumentNotValidException e) {
 String msg = e.getBindingResult().getFieldErrors().stream()
 .map(f -> f.getField() + ": " + f.getDefaultMessage())
 .collect(Collectors.joining("; "));
 return Result.fail(400, msg);
 }

 // @RequestParam / @PathVariable 校验失败
 @ExceptionHandler(ConstraintViolationException.class)
 public Result handleParam(ConstraintViolationException e) {
 String msg = e.getConstraintViolations().stream()
 .map(v -> v.getPropertyPath() + ": " + v.getMessage())
 .collect(Collectors.joining("; "));
 return Result.fail(400, msg);
 }
}

至此基础就齐了。下面才是真正出彩的"骚姿势"。

骚姿势一：分组校验（Validation Groups）

最常见的场景：新增和修改用的是同一个 DTO，但字段约束不同。新增时 id 不能传，修改时 id 必填——硬拆两个 DTO 又冗余。

分组校验解决这个问题：

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


public interface CreateGroup {}
public interface UpdateGroup {}

public class UserDTO {

 @Null(message = "新增时不能传 ID", groups = CreateGroup.class)
 @NotNull(message = "修改时必须传 ID", groups = UpdateGroup.class)
 private Long id;

 @NotBlank(groups = {CreateGroup.class, UpdateGroup.class})
 private String name;
}

@PostMapping("/users")
public Result create(@RequestBody @Validated(CreateGroup.class) UserDTO dto) { ... }

@PutMapping("/users")
public Result update(@RequestBody @Validated(UpdateGroup.class) UserDTO dto) { ... }

注意——分组要用 @Validated 不能用 @Valid，因为 @Valid 不支持分组参数。

骚姿势二：嵌套校验

DTO 嵌 DTO 时，光在外层加 @Valid 是不够的，必须在内层字段上也加 @Valid，校验才会递归下去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class OrderDTO {

 @NotEmpty
 @Valid // ← 关键
 private List<OrderItemDTO> items;
}

public class OrderItemDTO {
 @NotNull private Long skuId;
 @Min(1) private Integer count;
}

如果集合里有元素违规，错误路径会是 items[2].count，前端能精确定位。

骚姿势三：跨字段校验（自定义类级注解）

校验"密码和确认密码必须一致"这种字段间约束，单字段注解搞不定，需要写一个类级注解：

 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


@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PasswordMatchValidator.class)
public @interface PasswordMatch {
 String message() default "两次密码不一致";
 Class<?>[] groups() default {};
 Class<? extends Payload>[] payload() default {};
}

public class PasswordMatchValidator implements ConstraintValidator<PasswordMatch, RegisterDTO> {
 @Override
 public boolean isValid(RegisterDTO dto, ConstraintValidatorContext context) {
 if (dto.getPassword() == null) return true; // 让 @NotBlank 去管 null
 boolean match = dto.getPassword().equals(dto.getConfirmPassword());
 if (!match) {
 // 让错误"挂"在 confirmPassword 字段上而不是整个对象上
 context.disableDefaultConstraintViolation();
 context.buildConstraintViolationWithTemplate("两次密码不一致")
 .addPropertyNode("confirmPassword")
 .addConstraintViolation();
 }
 return match;
 }
}

@PasswordMatch
public class RegisterDTO {
 @NotBlank private String password;
 @NotBlank private String confirmPassword;
}

骚姿势四：自定义字段约束

校验"枚举值必须在指定集合内"是另一个常见需求。写一个 @Enum 自定义约束：

 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


@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = EnumValidator.class)
public @interface EnumValue {
 String message() default "值不在允许范围内";
 Class<?>[] groups() default {};
 Class<? extends Payload>[] payload() default {};

 Class<? extends Enum<?>> enumClass();
 String method() default "name"; // 用 enum 的哪个方法取值
}

public class EnumValidator implements ConstraintValidator<EnumValue, Object> {
 private Set<Object> values;

 @Override
 public void initialize(EnumValue ann) {
 values = Arrays.stream(ann.enumClass().getEnumConstants())
 .map(e -> ReflectUtil.invoke(e, ann.method()))
 .collect(Collectors.toSet());
 }
 @Override
 public boolean isValid(Object value, ConstraintValidatorContext ctx) {
 return value == null || values.contains(value);
 }
}

用法：

1
2


@EnumValue(enumClass = OrderStatus.class, method = "getCode")
private String status;

写一次，全项目复用。

骚姿势五：Service 层方法参数校验

@Validated 不只能用在 Controller，也能用在 Service：

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


@Service
@Validated
public class UserService {

 public User getById(@Min(1) Long id) {
 // ...
 }

 public void batchCreate(@NotEmpty @Valid List<UserDTO> users) {
 // ...
 }
}

被 @Validated 标注的类，方法参数上的约束会通过 AOP 自动校验，失败抛 ConstraintViolationException。这意味着——业务方法可以放心地把"非法输入"假设成不可能发生。

骚姿势六：错误消息国际化

把 message 写成 {key} 形式，Hibernate Validator 会自动从 messages.properties 读取：

1
2


@NotBlank(message = "{user.name.notBlank}")
private String name;

src/main/resources/messages.properties：

1

user.name.notBlank=姓名不能为空

src/main/resources/messages_en.properties：

1

user.name.notBlank=Name is required

Spring Boot 默认就开启了国际化支持，根据请求 Accept-Language 自动切换。

骚姿势七：编程式 API 与 failFast

少数场景注解搞不定——例如根据运行时参数切换分组、或希望"遇到第一个错误就停"。可以用编程式 Validator：

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


// 1. 自定义 ValidatorFactory，开启 failFast
@Bean
public Validator validator() {
 return Validation.byProvider(HibernateValidator.class)
 .configure()
 .failFast(true) // 任一字段失败立即返回，不再校验后续
 .buildValidatorFactory()
 .getValidator();
}

// 2. 编程式调用，按运行时条件选 group
@Autowired private Validator validator;

public void create(UserDTO dto, boolean strict) {
 Set<ConstraintViolation<UserDTO>> errors = strict
 ? validator.validate(dto, StrictGroup.class)
 : validator.validate(dto);
 if (!errors.isEmpty()) throw new IllegalArgumentException(...);
}

failFast 适合批量导入这种"快报快停"的场景；编程式 API 适合规则需要根据上下文动态切换。注解和编程式 API 完全可以混用——80% 用注解、20% 用 API 兜底。

一些工程上的踩坑提醒

@NotEmpty ≠ @NotBlank——前者认空白字符串为有效，后者会 trim
@Valid 和 @Validated 不要混用——分组场景必须 @Validated，嵌套校验只能 @Valid
基本类型的 @NotNull 是没用的——int、long 这些永远有默认值；要校验"必填"就得用包装类型
groups 默认值是 Default.class——不指定 groups 的注解只在不传分组时生效；你给某个注解加了 groups = Update.class，新增校验时它就不参与了
错误消息别堆业务逻辑——消息只描述"为什么不合法"，不要写"请联系管理员"这种和校验无关的话
DTO 复用别贪心——三种以上场景共用一个 DTO 时，强烈建议拆开，分组校验维护成本会爆炸

小结

Hibernate Validator 的价值不只是"少写 if"，它把输入校验从业务逻辑中剥离，让业务方法可以放心地假设"参数都是合法的"。

把今天的内容压一句：

校验是边界的责任，不是业务方法的责任。让框架帮你拦在门口，业务里只关心业务。

至于使用层级：

能用注解就用注解——分组、嵌套、自定义约束都属于注解能力
跨字段或动态规则——写自定义类级注解或编程式 API
Service 层也别放过——加 @Validated 让内部接口也享受框架保护

把这些招数都用上，Controller 里再也不会有那一行行傻乎乎的 if (xxx == null)。

Spring 依赖注入：@Resource 与 @Autowired 的使用边界

Tue, 04 Dec 2018 15:30:00 +0800

老生常谈但很少人答得明白的一题

Spring 项目里随手就能写出这两种依赖注入：

1
2
3
4
5


@Autowired
private UserService userService;

@Resource
private OrderService orderService;

两个注解效果几乎一样。但面试官一问"两者区别"，多数人只能磕磕巴巴答出"前者按类型，后者按名字"——这只是冰山一角。

本文把这两个注解的差异、源头、行为细节、踩坑点系统讲清楚。

一、出处不同

	@Autowired	@Resource
出处	Spring 自家	JSR-250（Java EE 标准）
包路径	`org.springframework.beans.factory.annotation`	`javax.annotation` / `jakarta.annotation`
历史	Spring 2.5+	Java EE 5（2006）
跨框架	只有 Spring 认	Spring / CDI / 多框架认

@Resource 是 Java 标准注解，@Autowired 是 Spring 私货。这是两者最本质的差异——理论上，使用 @Resource 的代码可以无缝切到任何 JSR-250 兼容的容器；用 @Autowired 就只能跑在 Spring 上。

实际工程里这点意义不大——99% 的 Java Web 项目都跑在 Spring 上。

二、查找规则不同

这是最常被问的差异——但远不止"按类型 vs 按名字"。

@Autowired 的查找顺序

flowchart TD
 A[按类型查找] --> B{找到 1 个?}
 B -->|是| C[注入]
 B -->|否，找到 0 个| D{required=true?}
 B -->|否，找到多个| E[尝试按名称匹配]
 D -->|是| F[抛 NoSuchBeanDefinitionException]
 D -->|否| G[注入 null]
 E --> H{匹配成功?}
 H -->|是| C
 H -->|否| I[抛 NoUniqueBeanDefinitionException]

简化：先按类型，类型多个时退化到按名字。

@Resource 的查找顺序

flowchart TD
 Start[开始] --> Q1{显式指定 name?}
 Q1 -->|是| ByName[只按 name 查]
 Q1 -->|否| Q2{显式指定 type?}
 Q2 -->|是| ByType[只按 type 查]
 Q2 -->|否| ByField[默认: 字段名作为 name 查]
 ByField --> Q3{找到?}
 Q3 -->|否| Fallback[退化到按类型查]
 Q3 -->|是| Done[注入]
 ByName --> Done
 ByType --> Done
 Fallback --> Done

简化：先按名字（字段名），找不到再按类型。

行为差异举例

1
2
3
4
5
6
7


public interface MessageSender {}

@Component
public class SmsSender implements MessageSender {}

@Component
public class EmailSender implements MessageSender {}

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


// @Autowired：类型 MessageSender 有两个 Bean，先按类型找不唯一
@Autowired
private MessageSender smsSender; // ✓ 退化到字段名匹配 SmsSender

@Autowired
private MessageSender provider; // ❌ 字段名没匹配，抛异常

// @Resource：默认按字段名找
@Resource
private MessageSender smsSender; // ✓ 直接按 smsSender 找到

@Resource
private MessageSender provider; // ❌ 字段名没匹配的 Bean

// @Resource 显式指定
@Resource(name = "smsSender")
private MessageSender provider; // ✓

三、required 选项

@Autowired 有 required 属性：

1
2


@Autowired(required = false)
private OptionalService optionalService; // 没有 Bean 时注入 null

@Resource 没有这个开关——Bean 找不到一定抛异常。

不过现代 Spring 推荐用 Optional 替代：

1
2


@Autowired
private Optional<OptionalService> service;

四、能否注入到构造器 / 方法

1
2
3
4
5
6
7
8


@Autowired
public OrderService(UserService userService) { ... } // ✓ 构造器

@Autowired
public void setUserService(UserService userService) { ... } // ✓ Setter

@Autowired
public void initSomething(UserService u, OrderService o) { ... } // ✓ 任意方法

@Resource 主要用于字段和 Setter，不能注入到构造器：

1
2


@Resource
public OrderService(UserService userService) { ... } // ❌ 不支持

这是个关键差别——构造器注入是 Spring 推荐的方式（不可变、便于测试），但 @Resource 不支持。所以"全用 @Resource 替代 @Autowired“在构造器场景下行不通。

五、集合注入

@Autowired 能优雅注入集合：

1
2
3
4
5


@Autowired
private List<MessageSender> senders; // 所有实现都被注入

@Autowired
private Map<String, MessageSender> senderMap; // key 是 Bean name

@Resource 在集合注入上行为不那么友好——没有"按类型找全部"的语义。

这是 @Autowired 在写"策略模式"时的杀手锏——业务代码：

1
2
3
4
5
6


@Autowired
private Map<String, PaymentChannel> channels;

public void pay(String type, ...) {
 channels.get(type).charge(...);
}

加一个新支付渠道只需要 @Component，业务代码无感。

六、构造器注入 vs 字段注入

无论用哪个注解，字段注入是反模式。Spring 官方文档现在也推荐构造器注入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// ❌ 字段注入（反模式）
@Autowired
private UserService userService;

// ✓ 构造器注入
private final UserService userService;

public OrderService(UserService userService) {
 this.userService = userService;
}

如果用 Lombok 更简洁：

1
2
3
4
5
6


@RequiredArgsConstructor
@Service
public class OrderService {
 private final UserService userService;
 private final OrderRepository repo;
}

构造器注入的好处：

字段可以 final——不可变
无 Spring 也能 new 出来——纯 Java，方便单测
依赖关系暴露在签名上——一眼能看出这个类依赖什么
循环依赖会立刻报错——而不是"运行时 NPE”

这就是为什么"@Autowired vs @Resource“这场争论某种意义上已经过时了——两者都不该用在字段上。

七、@Qualifier 与 @Resource(name)

类型多个 Bean 时，两种注解各有指定方式：

1
2
3
4
5
6


@Autowired
@Qualifier("smsSender")
private MessageSender sender;

@Resource(name = "smsSender")
private MessageSender sender;

效果相同。@Qualifier 还可以自定义：

1
2
3
4
5
6
7


@Component
@Qualifier("primary-sms")
public class AlibabaSmsSender implements MessageSender {}

@Autowired
@Qualifier("primary-sms")
private MessageSender sender;

@Resource(name) 没有这种"分组标签"的扩展能力。

八、循环依赖处理

两者对循环依赖的处理一致——字段注入和setter 注入支持循环依赖（Spring 三级缓存）；构造器注入循环依赖直接报错。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// A 依赖 B
@Service
public class A {
 @Autowired private B b;
}

// B 依赖 A → Spring 三级缓存可以解
@Service
public class B {
 @Autowired private A a;
}

但生产代码里出现循环依赖通常意味着设计问题，不要因为 Spring 能 handle 就放任。

九、@Autowired vs @Inject

讲到 JSR 标准，绕不过 @Inject（JSR-330）：

注解	出处	required 默认
`@Autowired`	Spring	true
`@Resource`	JSR-250	true
`@Inject`	JSR-330	true

@Inject 是 Google Guice / CDI 的标准，Spring 也支持——实际工程里基本没人用，因为 Spring 自家 @Autowired 功能更全。

十、踩坑提醒

1. 接口多实现时

1
2


@Autowired
private Service service; // 多个实现时报错

要么字段名匹配某个 Bean，要么显式 @Qualifier，要么用 @Primary：

1
2
3


@Component
@Primary
public class DefaultService implements Service {}

2. final 字段不能用 @Autowired

1
2


@Autowired
private final UserService userService; // ❌

final 字段必须在构造器里初始化——直接用构造器注入。

3. static 字段不能注入

1
2


@Autowired
private static UserService userService; // ❌ 不会注入

要给 static 字段注入只能在 setter 里手动 set，但这通常是设计有问题。

4. 单例引用原型 Bean

1
2
3
4
5


@Component // 默认单例
public class A {
 @Autowired
 private B b; // B 是 prototype，但 A 单例 → 始终是同一个 B 实例
}

不是 Spring 的 bug——是单例的依赖只注入一次。要每次取新实例：

1
2
3
4
5
6


@Autowired
private ObjectProvider<B> bProvider;

public void use() {
 B b = bProvider.getObject(); // 每次都拿新实例
}

5. JDK 版本与 javax/jakarta

Spring 6 / Spring Boot 3 把 javax.annotation 改成了 jakarta.annotation——老项目升级时 @Resource 的 import 要批量替换。

十一、选型建议

flowchart TD
 Start([需要注入依赖?])
 Start --> Type{字段还是构造器?}
 Type -->|构造器| C[必须 @Autowired
或 @RequiredArgsConstructor]
 Type -->|字段，不可改| F{需要按名字精确匹配?}
 F -->|是| R[@Resource - 简洁]
 F -->|否| A[@Autowired - 类型 + Qualifier]

给一个直接的工程建议：

首选构造器注入（用 Lombok 的 @RequiredArgsConstructor），二选 @Autowired + @Qualifier，最后选 @Resource。@Resource 在新代码里其实没什么不可替代的优势。

小结

把全文压一句：

@Autowired 优先按类型，@Resource 优先按名字；前者 Spring 私货功能更全，后者 JSR 标准。但两者最佳实践都是『不要用在字段上』——构造器注入才是 Spring 官方推荐的姿势。

记住几点：

字段注入是反模式，无论用哪个注解
构造器注入只能用 @Autowired（Spring 4.3 后构造器只有一个时连注解都不需要）
集合注入用 @Autowired 才够灵活
@Resource 在按 Bean name 精确匹配时稍简洁，但不是不可替代

下次写 Service 字段时——先想想"是否能改成构造器”，再选注解。

Spring Boot 项目打包：War 与 Jar 的区别和注意事项

Tue, 30 Oct 2018 17:00:00 +0800

写在前面

新人接触 Spring Boot 时常困惑一个问题——明明同样是 Java Web 项目，为什么有的项目用 mvn package 出来是个 jar，有的项目却出来一个 war，部署方式还截然不同？

答案要从 Spring Boot 的设计哲学说起。Spring Boot 提倡"内嵌容器、可执行 jar"的方式——一个 java -jar app.jar 就跑起来，再也不用 Tomcat 这样的外部容器。但传统的 Java EE 时代，war 包 + 外部容器才是标准玩法。Spring Boot 也兼容这种做法，让老项目能平滑迁移。

这两种打包方式选错了，轻则启动姿势别扭，重则配置失效、监控失灵。本文把它们的区别、坑、和实操要点一次讲清楚。

War 与 Jar 的本质区别

	Jar 包	War 包
用途	通用 Java 库、可执行应用	Java Web 应用归档（Web Application Archive）
入口	`META-INF/MANIFEST.MF` 的 Main-Class	`WEB-INF/web.xml` 或 `ServletContainerInitializer`
部署	`java -jar app.jar`	拷到 Tomcat/Jetty 的 `webapps` 目录
容器	内嵌（Tomcat/Jetty/Undertow）	外部
静态资源	`BOOT-INF/classes/static`	项目根目录或 `webapp` 下
类加载顺序	由 Spring Boot Loader 控制	由外部容器控制

最关键一句话——jar 把容器装进了应用，war 把应用装进了容器。这条决定了两者后续所有差异。

Spring Boot 默认推荐 Jar，原因是什么

Spring Boot 默认 jar 不是凭感觉，是经过权衡的。

Jar 的好处：

零运维：不需要装 Tomcat，不需要管 server.xml，部署=拷贝 jar 包
环境一致：开发、测试、生产用的是同一个内嵌 Tomcat，行为一致
容器版本可控：升级 Tomcat 只是改 pom 依赖
天然适合容器化：一个 jar 就是一个 Docker 镜像的核心
每个应用独立运行：互不影响，Crash 隔离

War 的传统优势在云原生时代逐渐弱化：

原本"一个 Tomcat 跑多个应用"的模式，被 Kubernetes 一个 Pod 一个应用替代了
原本"运维统一管 Tomcat"的优势，被容器编排取代了
原本"war 包小，复用容器"的优势，对几百 MB 起步的 Spring 应用根本不算优势

所以现在的工程默认建议：除非有明确历史包袱或合规要求，新项目一律 jar。

怎么打 Jar 包

Spring Boot 项目默认就是 jar。pom.xml 里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<packaging>jar</packaging>

<build>
 <plugins>
 <plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 </plugin>
 </plugins>
</build>

spring-boot-maven-plugin 的 repackage 目标会把项目打成"可执行 jar"——里面包含一个特殊的 BOOT-INF/lib/ 装所有依赖，外层有 Spring Boot 自己的 JarLauncher：

1
2
3
4
5
6
7
8


app.jar
├── META-INF/
│ └── MANIFEST.MF ← Main-Class: org.springframework.boot.loader.JarLauncher
├── org/springframework/boot/loader/ ← Spring Boot 启动类加载器
└── BOOT-INF/
 ├── classes/ ← 你的代码
 ├── lib/ ← 所有第三方依赖 jar
 └── classpath.idx

启动方式：

1
2


java -jar app.jar
java -Xms512m -Xmx2g -jar app.jar --spring.profiles.active=prod

怎么打 War 包

把同一个项目改成 war 输出，需要四步：

1. 改 packaging

1

<packaging>war</packaging>

2. 排除内嵌 Tomcat

外部容器已经提供了 Servlet 容器，再带一份会冲突：

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


<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 <exclusions>
 <exclusion>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-tomcat</artifactId>
 </exclusion>
 </exclusions>
</dependency>

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-tomcat</artifactId>
 <scope>provided</scope> <!-- 编译用，不打进 war -->
</dependency>

3. 启动类继承 `SpringBootServletInitializer`

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


@SpringBootApplication
public class Application extends SpringBootServletInitializer {

 @Override
 protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
 return builder.sources(Application.class);
 }

 public static void main(String[] args) {
 SpringApplication.run(Application.class, args);
 }
}

SpringBootServletInitializer 会让 war 既能 java -jar 跑，也能丢进 Tomcat 跑。保留 main 方法是个好习惯——本地调试还是 java -jar 最方便。

4. 部署

把生成的 app.war 拷贝到 $TOMCAT_HOME/webapps/ 下，Tomcat 自动解压并启动：

1

http://host:port/app/... ← context path 默认是 war 包名

七个最常见的 War 部署坑

坑 1：context path 不一致

java -jar 启动时，Spring Boot 默认 context path 是 /；war 部署到 Tomcat 时，context path 默认是 war 文件名。前端写死接口路径的话，部署完所有请求 404。

对策：要么把 war 重命名为 ROOT.war（context path = /），要么前端通过相对路径拼接。

坑 2：内嵌 Tomcat 没排干净

如果忘了 <scope>provided</scope>，war 里会带一份 Tomcat。在外部 Tomcat 里跑会出现 ClassLoader 冲突——NoSuchMethodError、LinkageError 各种奇葩报错。

对策：用 mvn dependency:tree 检查 war 里没有 tomcat-embed-*。

坑 3：`server.port` 配置失效

application.yml 里的 server.port: 8081 在 war 部署里完全无效——端口由外部 Tomcat 决定。同理 server.servlet.context-path 也无效。

对策：明确知道这些"server.*“配置只对内嵌容器生效。

坑 4：`@PropertySource` 找不到外部配置

java -jar 时 Spring Boot 会自动加载 jar 同级目录的 application.yml 覆盖内置；war 部署时没有"jar 同级目录"这个概念，外部配置要显式放在 Tomcat 的 lib 或者通过 -Dspring.config.location= 指定。

对策：

1
2


# 在 Tomcat 启动参数里加
-Dspring.config.location=file:/etc/myapp/application.yml

坑 5：日志文件路径混乱

Spring Boot 的 logging.file.name=app.log 是相对当前工作目录的，war 部署时这个目录是 Tomcat 的 bin/，不是你以为的项目目录。

对策：日志路径永远写绝对路径。

坑 6：JSP 默认不支持

Spring Boot 的可执行 jar 不支持 JSP（这也是为什么老项目改造时会被卡）。war 部署时虽然支持，但前提是：

1
2
3
4
5


<dependency>
 <groupId>org.apache.tomcat.embed</groupId>
 <artifactId>tomcat-embed-jasper</artifactId>
 <scope>provided</scope>
</dependency>

对策：新项目用 Thymeleaf / Freemarker / 前后端分离，远离 JSP。

坑 7：Filter / Listener 触发顺序

外部 Tomcat 加载 war 时，@WebFilter 等注解的扫描机制和 Spring Boot 自带容器有差异。某些 Filter 可能比 Spring 容器还早初始化，导致 @Autowired 是 null。

对策：用 FilterRegistrationBean 显式注册 Filter，由 Spring 控制生命周期。

镜像化时代的最佳实践

如果你的项目要打 Docker 镜像，强烈推荐用 jar：

1
2
3


FROM eclipse-temurin:17-jre
COPY target/app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

简单、清晰、可复制。war + Tomcat 的镜像虽然也能跑，但要装 Tomcat、改 server.xml、暴露端口，且镜像体积更大、启动更慢。

进一步的优化是用 Spring Boot 的 Layered Jar 把不变的依赖和频繁变化的业务代码分层，加速 Docker 镜像构建：

1
2
3
4
5
6
7
8
9


<plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 <configuration>
 <layers>
 <enabled>true</enabled>
 </layers>
 </configuration>
</plugin>

1
2
3
4
5
6


FROM eclipse-temurin:17-jre
WORKDIR /app
COPY target/app.jar app.jar
RUN java -Djarmode=layertools -jar app.jar extract
# Spring Boot 3.2+ 路径
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

版本注意：ENTRYPOINT 类路径在 Boot 3.2 处发生过迁移——Boot 3.2+ 用 org.springframework.boot.loader.launch.JarLauncher，3.1 及以下是 org.springframework.boot.loader.JarLauncher。两者写错都会启动报 ClassNotFoundException，按你实际的 Boot 版本选。

选择决策树

flowchart TD
 Start([新项目还是老项目?])
 Start -->|新项目| Jar1[直接用 Jar]
 Start -->|老项目| Old{有外部 Tomcat 集群?}
 Old -->|没有| Jar2[迁移成 Jar]
 Old -->|有| Reason{为什么用外部 Tomcat?}
 Reason -->|历史习惯| Migrate[评估迁移成本，建议慢慢转 Jar]
 Reason -->|多应用共享容器| Docker[考虑 K8s 替代]
 Reason -->|合规/审计要求| War[继续用 War]
 Reason -->|JSP/老旧依赖| War

小结

War 与 Jar 的选择，本质上是"跟着 Java EE 时代的部署模式走，还是跟着云原生的部署模式走”。

给一句决策建议：

新项目优先用 Jar。老项目能改就改。除非有合规/历史/JSP 强约束，否则没有理由再用 War。

Spring Boot 仍然完整支持 war 是为了向后兼容，不是推荐方向。把这点拎清楚，后面所有选择就都顺了。

设计模式漫谈：四种「工厂」到底有什么区别

Thu, 12 Jul 2018 15:30:00 +0800

很多人聊"工厂模式"时会下意识地说"工厂模式嘛，就是 XxxFactory.create()"——可一旦有人追问"那简单工厂、静态工厂、工厂方法、抽象工厂到底有啥区别？"，往往就答不上来了。

这四个词长得像，但实际上只有两个属于 GoF 23 种正统设计模式，剩下两个是工程实践里大家叫顺嘴的"非正式说法"。今天我们就把它们一次性捋清楚。

先从一个让人头大的例子说起

假设我们要做一个发送通知的功能，有三种渠道：短信、邮件、推送。最直觉的写法是：

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


public class OrderService {
 public void notifyUser(String channel, String userId, String content) {
 if ("sms".equals(channel)) {
 SmsSender sender = new SmsSender("ak", "sk");
 sender.send(userId, content);
 } else if ("email".equals(channel)) {
 EmailSender sender = new EmailSender("smtp.xx.com", 25);
 sender.send(userId, content);
 } else if ("push".equals(channel)) {
 PushSender sender = new PushSender("appKey");
 sender.send(userId, content);
 }
 }
}

这种写法的麻烦之处在于：

创建逻辑散落各处：哪天 SmsSender 的构造参数变了，所有 new SmsSender(...) 的地方都要改。
业务和"造对象"耦合：OrderService 本不该知道 SmsSender 的 ak/sk 怎么填。
新增渠道要改老代码：再来一个微信渠道，又得加一个 else if，老代码越改越脏，违反开闭原则（OCP）。
不好测：业务方法里硬编码了 new，单元测试想替换成 mock 都难。

工厂模式要解决的就是这些痛点——把"用什么对象"和"对象怎么造"拆开。

一、简单工厂（Simple Factory）

它是什么

把"造对象"的逻辑收拢到一个工厂类的一个方法里，调用方只传"类型标识"，不关心具体实现。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class NotificationSenderFactory {

 public static Sender create(String channel) {
 switch (channel) {
 case "sms": return new SmsSender("ak", "sk");
 case "email": return new EmailSender("smtp.xx.com", 25);
 case "push": return new PushSender("appKey");
 default: throw new IllegalArgumentException("unknown channel: " + channel);
 }
 }
}

业务代码立刻清爽：

1
2


Sender sender = NotificationSenderFactory.create(channel);
sender.send(userId, content);

它的优缺点

优点：

创建逻辑集中到一个地方，构造参数变了只改一处。
业务代码只面向 Sender 接口编程，不依赖具体实现。

缺点：

新增类型要改 create 方法——违反开闭原则。
工厂方法里塞满 switch，类型多了之后会很臃肿。

一个常见的误解

很多书会把"简单工厂"列成一种设计模式，但 GoF 23 种里其实没有它。它更像是一种"惯用写法"，是迈向真正工厂模式的过渡形态。

二、静态工厂方法（Static Factory Method）

“静态工厂"这个词在中文社区有点歧义，常见有两层含义：

狭义：上面简单工厂里那个方法本身是 static 的，所以也叫静态工厂——这层含义没什么新东西。
广义（更值得讲的一层）：Effective Java 第 1 条提倡的——用类内部的静态工厂方法替代 public 构造器。

第二种含义长什么样

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


public final class Color {

 private final int r, g, b;

 private Color(int r, int g, int b) { // 构造器私有
 this.r = r; this.g = g; this.b = b;
 }

 public static Color of(int r, int g, int b) {
 return new Color(r, g, b);
 }

 public static Color fromHex(String hex) {
 int rgb = Integer.parseInt(hex.substring(1), 16);
 return new Color((rgb >> 16) & 0xFF, (rgb >> 8) & 0xFF, rgb & 0xFF);
 }

 public static Color black() {
 return BLACK; // 可以缓存常用实例
 }
 private static final Color BLACK = new Color(0, 0, 0);
}

JDK 里到处都是这个套路：

Integer.valueOf(int)：缓存了 -128~127 的实例
List.of(...) / Map.of(...)：返回不可变实现
Optional.of(x) / Optional.empty()
Files.newInputStream(path)：返回 InputStream 接口，实现类对外不可见

为什么推荐它

相比 new 构造器，静态工厂方法有四个真正有价值的优点：

方法可以有名字——Color.fromHex("#FF0000") 比 new Color(255, 0, 0) 表达力强得多。一个类想要"多种构造方式"时，构造器只能靠参数列表区分，名字不够用。
不必每次都创建新对象——可以缓存、可以复用。Integer.valueOf 和单例都是这个原理。
可以返回子类型甚至接口类型——隐藏具体实现，调用方只面向接口编程。Files.newInputStream 就是个例子。
返回类型可以根据参数动态决定——EnumSet.of(...) 会根据元素数量返回 RegularEnumSet 或 JumboEnumSet，调用方不感知。

它的代价

类如果没有 public 构造器，就不能被子类继承——这其实有时是好事（强制组合优于继承）。
静态工厂方法和普通静态方法在 IDE 里不易区分，所以业界约定了一组命名习惯：of / valueOf / from / getInstance / newInstance / create。看到这些名字，老司机就知道这是个工厂。

三、工厂方法（Factory Method）—— GoF 正统

简单工厂的最大问题是：新增类型要改 switch。工厂方法就是为了解决这个问题——把工厂本身也抽象化。

类关系

classDiagram
 class SenderFactory {
 <>
 +create() Sender
 }
 class Sender {
 <>
 +send(userId, content)
 }
 class SmsSenderFactory
 class EmailSenderFactory
 class SmsSender
 class EmailSender

 SenderFactory <|.. SmsSenderFactory
 SenderFactory <|.. EmailSenderFactory
 Sender <|.. SmsSender
 Sender <|.. EmailSender
 SmsSenderFactory ..> SmsSender : creates
 EmailSenderFactory ..> EmailSender : creates

每种产品配一个工厂，工厂自己也面向接口编程。

代码长什么样

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


public interface Sender {
 void send(String userId, String content);
}

public interface SenderFactory {
 Sender create();
}

public class SmsSenderFactory implements SenderFactory {
 @Override public Sender create() {
 return new SmsSender("ak", "sk");
 }
}

public class EmailSenderFactory implements SenderFactory {
 @Override public Sender create() {
 return new EmailSender("smtp.xx.com", 25);
 }
}

调用方持有一个 SenderFactory，至于背后是哪种工厂，由配置或 IoC 容器注入：

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


public class OrderService {
 private final SenderFactory factory; // 依赖抽象

 public OrderService(SenderFactory factory) {
 this.factory = factory;
 }

 public void notifyUser(String userId, String content) {
 Sender sender = factory.create();
 sender.send(userId, content);
 }
}

关键收益

新增一种"微信渠道"时：

加一个 WeChatSender 实现类
加一个 WeChatSenderFactory 实现类
老代码一行不动

这就是开闭原则的真正落地。代价是类的数量翻倍，所以只在"扩展性收益 > 类爆炸成本"时才值得用。

四、抽象工厂（Abstract Factory）—— GoF 正统

工厂方法解决的是"一种产品有多种实现”。当一个场景里同时有多种产品，且这些产品需要"配套使用"时，就需要抽象工厂。

经典场景：跨平台 UI

假设我们做一个跨平台 GUI 库，要支持 Windows 和 Mac，每个平台都有自己的 Button 和 Checkbox：

产品 \ 平台	Windows	Mac
Button	WindowsButton	MacButton
Checkbox	WindowsCheckbox	MacCheckbox

约束：Windows 程序里不能混入 Mac 风格的控件，反之亦然。

类关系如下：

classDiagram
 class UIFactory {
 <>
 +createButton() Button
 +createCheckbox() Checkbox
 }
 class Button {
 <>
 }
 class Checkbox {
 <>
 }

 class WindowsUIFactory
 class MacUIFactory

 class WindowsButton
 class WindowsCheckbox
 class MacButton
 class MacCheckbox

 UIFactory <|.. WindowsUIFactory
 UIFactory <|.. MacUIFactory
 Button <|.. WindowsButton
 Button <|.. MacButton
 Checkbox <|.. WindowsCheckbox
 Checkbox <|.. MacCheckbox

 WindowsUIFactory ..> WindowsButton : creates
 WindowsUIFactory ..> WindowsCheckbox : creates
 MacUIFactory ..> MacButton : creates
 MacUIFactory ..> MacCheckbox : creates

抽象工厂就是把"造一整套"的能力封装到一个工厂里：

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


public interface UIFactory {
 Button createButton();
 Checkbox createCheckbox();
}

public class WindowsUIFactory implements UIFactory {
 @Override public Button createButton() { return new WindowsButton(); }
 @Override public Checkbox createCheckbox() { return new WindowsCheckbox(); }
}

public class MacUIFactory implements UIFactory {
 @Override public Button createButton() { return new MacButton(); }
 @Override public Checkbox createCheckbox() { return new MacCheckbox(); }
}

调用方只拿 UIFactory，造出来的所有控件天然属于同一族：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class App {
 private final UIFactory ui;

 public App(UIFactory ui) { this.ui = ui; }

 public void render() {
 Button b = ui.createButton(); // 一定是同一个平台
 Checkbox c = ui.createCheckbox();
 // ...
 }
}

抽象工厂 vs 工厂方法

最容易混淆的就是这两兄弟，记住一句话就够：

工厂方法关心"一种产品的多种实现"，抽象工厂关心"多种产品的成套实现"。

抽象工厂的痛点是——产品族里加一个新成员（比如要加个 Slider）时，所有具体工厂都得改。这是它结构性的代价。

横向对比

模式	是否 GoF	解决的问题	新增类型成本	典型场景
简单工厂	✗	创建逻辑收拢	改工厂方法（违反 OCP）	类型少、且不常变的场景
静态工厂方法	✗	替代构造器	加一个静态方法	几乎所有库的对象创建
工厂方法	✓	把"造哪个"也抽象掉	新增产品类 + 新增工厂类（OCP）	插件化、可扩展的运行时切换
抽象工厂	✓	一族产品配套使用	新增成员要改所有工厂	跨平台、多环境、多套配套实现

工程上怎么选

不要看见"工厂"就上工厂方法/抽象工厂。多数业务场景里，越简单越好：

单纯想让对象创建更优雅、更有表达力：静态工厂方法（of、from）就够了，不需要任何工厂类。
类型种类有限、变化频率低：简单工厂足够。承担违反 OCP 的代价换简洁，是合理的工程取舍。
类型会持续扩展、且希望"加新类型不动老代码"：用工厂方法，配合 IoC 容器或 SPI 机制。
要支持"多套互不相容的实现族"：才考虑抽象工厂。它的复杂度不低，没真实需求别上。

一个常被忽略的现实是——Spring/Guice 这类 IoC 容器，本身就是一个超级抽象工厂。在用 Spring 的项目里，绝大多数"工厂模式"的需求其实可以通过 @Bean + @Qualifier 或 Map<String, XxxStrategy> 注入直接解决，不必手写工厂类。

小结

把四个工厂的本质用一句话压缩：

工厂模式的本质，是把"用什么"和"怎么造"拆开。

四种形态只是抽象程度不同：

简单工厂：拆得最浅，调用方还要自己传"类型标识"。
静态工厂方法：把"造"封装进类自己，对外只暴露语义化的命名。
工厂方法：把"造哪个"也抽象成接口，新增类型不再修改老代码。
抽象工厂：把"造一整套"抽象成接口，保证产品族内部一致性。

工程上永远从最简单的开始，业务复杂度真实驱动你时再向上升级——这才是设计模式正确的用法。

Spring 业务解耦：AOP 与事件监听的实战与边界

Wed, 09 May 2018 16:00:00 +0800

写在前面

业务代码里最容易长出"屎山"的两类逻辑——横切关注点（cross-cutting concerns）和副作用副流程：

日志、权限、审计、缓存、限流、监控埋点 → 横切关注点
用户注册后送积分、下单后通知库存、修改后清缓存 → 副流程

一旦把这些事写进业务方法，主线逻辑就被淹没：

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


public Order createOrder(OrderDTO dto) {
 log.info("user {} start create order", userId);
 if (!hasPermission(userId, "ORDER_CREATE")) throw new ...;

 long start = System.currentTimeMillis();
 try {
 // 真正的业务
 Order order = orderRepo.save(new Order(dto));

 // 副流程一坨
 sendNotification(...);
 addUserPoints(userId, order.getAmount());
 cleanCache(userId);
 sendMQ(...);
 // ...

 return order;
 } finally {
 metrics.record("createOrder", System.currentTimeMillis() - start);
 log.info("create order done, id={}", order.getId());
 }
}

业务和"基础设施 + 副流程"完全混在一起。

Spring 提供了两种让业务代码保持纯粹的武器——AOP 和 事件监听。本文把它们的适用场景、边界、最佳实践讲清楚。

一、AOP：解决"横切关注点"

AOP 在解决什么

AOP 把"和业务逻辑交叉但本身不属于业务"的代码抽出来，让业务方法只剩"业务"：

1
2
3
4
5


@LogTime
@RequirePermission("ORDER_CREATE")
public Order createOrder(OrderDTO dto) {
 return orderRepo.save(new Order(dto));
}

业务代码变得极简，所有横切逻辑由 AOP 统一处理。

一个完整例子：方法耗时日志

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


@Aspect
@Component
public class TimingAspect {

 @Around("@annotation(LogTime)")
 public Object around(ProceedingJoinPoint pjp) throws Throwable {
 long start = System.currentTimeMillis();
 try {
 return pjp.proceed();
 } finally {
 long cost = System.currentTimeMillis() - start;
 log.info("{} cost {}ms", pjp.getSignature().toShortString(), cost);
 }
 }
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface LogTime {}

业务方法加 @LogTime 即可。

AOP 的典型适用场景

场景	注解风格
方法耗时日志	`@LogTime`
接口幂等	`@Idempotent`
限流	`@RateLimit(qps = 100)`
缓存	`@Cached(ttl = 5m)`
数据权限	`@DataScope`
重试	`@Retry(times = 3)`
分布式锁	`@DistributedLock(key)`
操作日志	`@OperationLog("创建订单")`

共同特征：和业务无关、跨多个方法、可以"声明式开关"。

AOP 的限制和坑

1. Spring AOP 是基于代理的——同类调用不生效

1
2
3
4
5
6


@Service
public class OrderService {
 public void a() { b(); } // ❌ 调 b 不会触发 b 的切面
 @LogTime
 public void b() { ... }
}

代理只在外部调用入口生效，类内部 this.method() 调用绕过了代理。解决：

1
2


@Autowired private ApplicationContext ctx;
public void a() { ctx.getBean(OrderService.class).b(); }

或者把 b 拆到另一个 Service。

2. private 方法不能被切

代理基于继承/接口，private 方法直接绕过。

3. AOP 调试链路长

stack trace 里多了 CglibProxy、JdkDynamicAopProxy 这些层，新人看不懂。

4. 滥用会让代码难追

业务方法签名上看到一堆 @LogTime @Cached @Idempotent @RateLimit @OperationLog @DistributedLock——不熟悉项目的人根本不知道每个注解干啥，行为变成"看不见的魔法"。

经验上：业务方法上的 AOP 注解多于 3 个就值得复盘，多于 5 个往往是过度设计的信号。

二、事件监听：解决"副流程解耦"

Spring 事件机制

业务做完主线后，需要触发一系列副流程——传统写法是直接调用：

1
2
3
4
5
6
7


public Order createOrder(...) {
 Order o = orderRepo.save(...);
 notificationService.send(...); // 副流程 1
 pointService.addPoints(...); // 副流程 2
 cacheService.evict(...); // 副流程 3
 return o;
}

每加一个副流程都要改这个方法，代码越来越臃肿。事件机制的解法——业务方法只发一个事件，副流程自己订阅：

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


public Order createOrder(...) {
 Order o = orderRepo.save(...);
 publisher.publishEvent(new OrderCreatedEvent(o)); // 只发事件
 return o;
}

@Component
public class NotificationListener {
 @EventListener
 public void onCreate(OrderCreatedEvent e) { ... }
}

@Component
public class PointListener {
 @EventListener
 public void onCreate(OrderCreatedEvent e) { ... }
}

每个副流程独立、可单独测试、加新流程不动主业务。

同步 vs 异步

@EventListener 默认是同步的——和业务在同一个线程、同一个事务。这意味着：

任何 listener 抛异常，主业务回滚
listener 慢，主业务也慢

要改成异步，加 @Async：

1
2
3


@Async
@EventListener
public void onCreate(OrderCreatedEvent e) { ... }

这时 listener 在另一个线程跑，和主业务事务无关——常用于"发短信、发 MQ"这类不重要、可重试的副流程。

`@TransactionalEventListener`：等事务提交后再触发

最容易踩的坑——publishEvent 是在主业务事务提交之前调用的（在业务方法内）。所以无论同步还是异步监听器，listener 看到的都是"事务还没提交"的状态——副流程里去查 DB 可能查不到刚写入的数据：

1
2
3
4


@EventListener // 同步、异步（@Async）都一样
public void onCreate(OrderCreatedEvent e) {
 orderRepo.findById(e.getId()); // ❌ 可能查不到（事务还没提）
}

注意：这与"是否异步"无关——事件触发点本身就在事务提交之前。

正确写法：

1
2
3
4


@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onCreate(OrderCreatedEvent e) {
 // 主事务已提交，可以放心读取
}

AFTER_COMMIT 是最常用——只有主事务提交后才触发。生产场景里只要副流程要读 DB 数据，几乎都要用它。

事件机制的典型适用场景

领域事件：用户注册、订单创建、支付完成
副流程触发：积分、消息推送、缓存清理
解耦不同模块：订单模块发事件，营销模块、库存模块、积分模块各自订阅
审计 / 操作记录

事件机制的限制和坑

1. 事件不要变成"远程过程调用"

1
2
3
4


@TransactionalEventListener
public Result onCreate(OrderCreatedEvent e) {
 return riskService.check(...); // ❌ 想要返回值？事件不该这么用
}

事件是单向通知，不是"调用"。需要返回值的逻辑应该走普通 Service 调用。

2. 异步事件 + 事务

@Async + @EventListener 跨线程后默认丢失主线程的事务上下文——副流程内部的 DB 操作处于"自己开新事务"模式。要小心数据一致性。

3. 事件溯源能力弱

Spring 事件是进程内的——重启就没了，没有"事件回放"能力。要做事件溯源（Event Sourcing）需要更专业的方案（Axon、自己写 outbox）。

4. 链式事件失控

A 事件触发 B listener，B listener 又发 C 事件，C 又发 D……复杂业务里事件链能绕成一团乱麻。控制好事件层级，建议不超过 2 跳。

三、AOP vs 事件：怎么选

	AOP	事件监听
目标	横切关注点	副流程解耦
与主业务关系	“包"主业务（before/after/around）	主业务发出，副流程自己订阅
多对一?	单切面 → 多方法	单事件 → 多 listener
跨事务?	同事务	可配置（同步/异步/事务后）
业务感知度	业务方法加注解或不加	业务方法显式 publishEvent
可见性	“魔法”	比 AOP 显式

简单判断：

跟业务逻辑无关、想做声明式开关 → AOP
业务做完后需要触发若干副流程 → 事件监听
既不是横切又不是副流程 → 直接调 Service

四、典型场景示例对比

场景：下单后清缓存

❌ 反例：写在业务里

1
2
3
4
5


public Order createOrder(...) {
 Order o = orderRepo.save(...);
 redis.delete("user:" + userId + ":orders");
 return o;
}

✅ 用 AOP（声明式缓存）

1
2


@CacheEvict(value = "user:orders", key = "#dto.userId")
public Order createOrder(OrderDTO dto) { ... }

适合"创建/修改/删除都要清同样的 cache”——纯横切。

✅ 用事件（多个副流程都要做）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public Order createOrder(...) {
 Order o = orderRepo.save(...);
 publisher.publishEvent(new OrderCreatedEvent(o));
 return o;
}

@TransactionalEventListener(phase = AFTER_COMMIT)
public void cleanCache(OrderCreatedEvent e) { ... }

@TransactionalEventListener(phase = AFTER_COMMIT)
public void sendMQ(OrderCreatedEvent e) { ... }

副流程多、需要解耦时用事件。

五、组合用法

实际项目里两者经常配合：

1
2
3
4
5
6


@OperationLog("创建订单") // AOP 记审计
public Order createOrder(...) {
 Order o = orderRepo.save(...);
 publisher.publishEvent(new OrderCreatedEvent(o)); // 事件解耦副流程
 return o;
}

AOP 处理"操作日志"这种横切——业务无感
事件处理"积分/通知/MQ"这种副流程——主业务只发事件

六、几条工程惯例

1. 注解上限

业务方法上的 AOP 注解不要超过 3 个。多了说明：

你需要把多个注解合并成业务相关的 meta 注解（@OperationLog 包含审计 + 时间 + 权限）
或者你滥用了 AOP，把本该是业务的逻辑抽离了

2. 事件命名

事件名永远是**「实体 + 动作过去时」**：OrderCreatedEvent、UserRegisteredEvent、PaymentCompletedEvent。不要叫 CreateOrderEvent——前者表示"已发生"，后者像"指令"。

3. 事件的字段最小化

事件载荷只放"必要的标识 + 关键字段"，不要塞整个对象。listener 自己再去查 DB——避免事件载荷过大、同时减少耦合。

4. AOP 注解必须有"业务含义"

@LogTime、@RateLimit 一看就懂；不要写 @MyAspect1 这种含糊命名——业务方法签名应该自解释。

5. 事件不要用于强一致性场景

事件 = 异步 / 解耦 / 最终一致。强一致用普通调用 + 事务，事件不能替代。

6. 测试覆盖到 AOP 和事件

切面和监听器很容易在测试中被忽略——主业务跑得过、但 AOP/事件没生效，单测不一定能发现。要专门写集成测试覆盖。

小结

把全文压一句：

AOP 解决『跟业务无关但跨方法都要做的事』，事件机制解决『主业务做完之后触发的副流程』——前者是『包』，后者是『发』。

工程上几条建议：

业务方法专注业务，横切交给 AOP，副流程交给事件
AOP 注解 ≤ 3 个，命名要业务化
事件名 = 实体 + 过去时
事务后副流程一定用 @TransactionalEventListener(AFTER_COMMIT)
事件不要做"返回值调用"，那是 Service 的事

把这两个工具用对，业务代码会一下子清爽下来——这才是"代码优雅"的真正姿势。

编程语言 on 牛哥聊技术

从 Lambda 到虚拟线程——Java 关键特性演进

写在前面

一、Java 8（2014）：函数式革命

二、Java 11（2018）：第一个 LTS 之后

三、Java 17（2021）：第二个 LTS

四、Java 21（2023）：虚拟线程时代

虚拟线程（Project Loom）

结构化并发

Pattern Matching for Switch

Records & Sealed 升级

五、Java 25（2025 LTS）：当下的最新 LTS

Stream Gatherers（标准化）

Scoped Values（替代 ThreadLocal）

Class-File API

Pattern Matching 进一步增强

KEM（Key Encapsulation Mechanism）API

六、未来：在路上的特性

Project Valhalla：Value Types

Project Panama：原生互操作

Project Leyden：AOT 编译

Project Lilliput：紧凑对象头

Project Babylon：HAT（Heterogeneous Accelerator Toolkit）

七、生态展望

八、给开发者的实战建议

1. 升级路径

2. 选择当下的 LTS

3. 关注的特性

4. 工具链

小结

Go 与 Java 泛型：晚到的 vs 老牌的，对比谁更好用

写在前面

一、语法层面对比

最简单的例子：泛型函数

泛型类型 / 结构体

二、约束系统的差异

Java：基于 extends 的边界

Go：基于"约束接口"

类型集合（type set）

三、实现机制：擦除 vs 单态化

Java：类型擦除（Type Erasure）

类型擦除的代价

Go：单态化（Monomorphization）

对比

四、装箱与基本类型

五、常见用法对比

1. 集合工具函数

2. 容器类

3. 错误处理 / Result 类型

六、Go 泛型的限制

1. 无方法泛型

2. 无变型（Variance）

3. 无 Constraint Inference

4. 没有"条件实现"

5. 顺手吐槽：[] 把泛型、map、切片三件事挤在一起

6. 顺便再吐一句：Go 的时间格式

七、Java 泛型的限制

1. 类型擦除导致的反射受限

2. 不能 new T

3. 数组与泛型不兼容

八、性能对比

九、典型场景该用谁

十、Go 社区对泛型的争议

十一、什么时候真的该用泛型

小结

Protobuf 协议原理解析：为什么它能比 JSON 小一半还快几倍

写在前面

一、为什么不是 JSON

二、Wire Format：字段的二进制表示

Wire Types

例子

三、Varint：变长整数编码

编码规则

编码示例

Varint 的代价

四、Length-delimited：字符串和子消息

嵌套 message

五、字段编号：兼容性的命脉

兼容规则

reserved 的用法

Java：基于 `extends` 的边界

5. 顺手吐槽：`[]` 把泛型、map、切片三件事挤在一起

`spring.profiles.include`

五、`bootstrap.yml` vs `application.yml`

七、`@Value` vs `@ConfigurationProperties`

`@Value`：单字段注入

`@ConfigurationProperties`：批量映射

`@RefreshScope`

1. Actuator 的 `/actuator/env`