Java / 知识点
Java 开发速查手册
手册条目
Set<E> set = new HashSet<>(); // LinkedHashSet 保持插入顺序,TreeSet 排序
set.add(e) / set.contains(e) / set.addAll(other) / set.retainAll(other)使用集合去重并处理无序、有序和排序需求。
操作 Set
Set 用于保存不重复元素。需要最高通用性能时选 HashSet,需要保留插入顺序时选 LinkedHashSet,需要自动排序或范围查询时选 TreeSet。
类型选择
| 实现 | 顺序 | 典型操作 | 适用场景 |
|---|---|---|---|
HashSet |
不保证 | add、contains 平均为 |
去重、成员判断 |
LinkedHashSet |
插入顺序 | 平均为 | 去重后仍按原顺序输出 |
TreeSet |
排序顺序 | add、contains 为 |
排序、最大最小值、范围查询 |
不要依赖 HashSet 当前看似稳定的输出顺序;JDK 版本、容量变化或元素分布变化后都可能改变。
基本语法
常用方法包括:add 添加元素,remove 删除元素,contains 判断是否存在,size 获取数量,isEmpty 判断是否为空。重复调用 add 不会新增元素,返回值可用于判断本次是否真正插入。
高频用法
下面的完整示例同时演示按原顺序去重、成员判断、排序,以及并集、交集和差集。集合运算使用副本,避免修改原集合。
import java.util.Arrays;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import java.util.TreeSet;
public class SetDemo {
public static void main(String[] args) {
List<Integer> source = Arrays.asList(3, 1, 3, 2, 1);
// LinkedHashSet 去重并保留首次出现顺序
Set<Integer> unique = new LinkedHashSet<>(source);
System.out.println("unique=" + unique);
System.out.println("contains2=" + unique.contains(2));
System.out.println("sorted=" + new TreeSet<>(unique));
Set<Integer> left = new TreeSet<>(Arrays.asList(1, 2, 3));
Set<Integer> right = new TreeSet<>(Arrays.asList(3, 4));
Set<Integer> union = new TreeSet<>(left);
union.addAll(right);
Set<Integer> intersection = new TreeSet<>(left);
intersection.retainAll(right);
Set<Integer> difference = new TreeSet<>(left);
difference.removeAll(right);
System.out.println("union=" + union);
System.out.println("intersection=" + intersection);
System.out.println("difference=" + difference);
}
}预期输出:
unique=[3, 1, 2]
contains2=true
sorted=[1, 2, 3]
union=[1, 2, 3, 4]
intersection=[3]
difference=[1, 2]读取方法:unique 表示保留原顺序后的去重结果;union、intersection、difference 分别对应并集、交集和左集合减右集合。
风险与边界
当元素参与 equals 或 hashCode 计算的字段在入集合后被修改时,contains、remove 可能找不到该元素,甚至留下无法正常删除的脏数据。安全做法是使用不可变对象,或先删除、修改后再重新加入。
TreeSet 依赖自然顺序或 Comparator。比较器若把两个不相等对象判为 0,后加入的对象会被视为重复而丢失;应保证排序规则与 equals 语义一致。自然排序的 TreeSet 通常也不能加入 null。
多个线程同时修改普通 Set 可能出现数据丢失或遍历异常。并发写入使用 ConcurrentHashMap.newKeySet();只读共享则在发布前构造完成并避免后续修改。
排障清单
- 去重结果顺序异常:确认是否误用了
HashSet,需要稳定顺序时改用LinkedHashSet。 contains返回false:检查元素的equals、hashCode是否一致,以及入集合后是否修改过关键字段。- 遍历时报
ConcurrentModificationException:不要在增强for中直接增删原集合,改用迭代器的remove、先收集待删除项,或使用并发集合。 TreeSet少元素:检查比较器是否错误地对不同对象返回0。
速查:去重选 HashSet,保序去重选 LinkedHashSet,排序和范围查询选 TreeSet。
Map<K, V> map = new HashMap<>(); // LinkedHashMap / TreeMap
map.put(k, v) / map.get(k) / map.getOrDefault(k, <默认值>)
map.computeIfAbsent(k, key -> ...) / map.merge(k, v, Integer::sum)完成键值数据的查询、更新、合并和遍历。
操作 Map
Map 用键定位值,适合缓存、索引、计数和分组。通用场景优先选 HashMap,需要稳定遍历顺序时选 LinkedHashMap,需要按键排序或范围查询时选 TreeMap。
类型选择
| 实现 | 键顺序 | 典型操作 | 适用场景 |
|---|---|---|---|
HashMap |
不保证 | get、put 平均为 |
普通查询与更新 |
LinkedHashMap |
插入顺序或访问顺序 | 平均为 | 稳定输出、简单 LRU 基础结构 |
TreeMap |
按键排序 | get、put 为 |
排序、区间和相邻键查询 |
ConcurrentHashMap |
不保证 | 并发查询与更新 | 多线程共享写入 |
基本语法
put 会新增或覆盖值,并返回旧值;putIfAbsent 只在键不存在时写入;getOrDefault 提供缺省值;computeIfAbsent 适合延迟创建;merge 适合累计、合并和计数;forEach 用于遍历键值对。
当值本身允许为 null 时,get(key) == null 无法区分“键不存在”和“键存在但值为 null”,需要再用 containsKey 判断。
高频用法
下面的完整示例覆盖查询、条件更新、合并累计和稳定遍历。使用 LinkedHashMap 是为了让预期输出顺序确定。
import java.util.LinkedHashMap;
import java.util.Map;
public class MapDemo {
public static void main(String[] args) {
Map<String, Integer> stock = new LinkedHashMap<>();
stock.put("apple", 3);
stock.putIfAbsent("banana", 2);
// 仅在键已存在时更新;键不存在时保持不变
stock.computeIfPresent("apple", (key, value) -> value + 2);
// merge:键不存在时写入给定值,存在时执行合并函数
stock.merge("banana", 1, Integer::sum);
stock.merge("orange", 4, Integer::sum);
System.out.println("pear=" + stock.getOrDefault("pear", 0));
stock.forEach((key, value) ->
System.out.println(key + "=" + value));
}
}预期输出:
pear=0
apple=5
banana=3
orange=4读取方法:apple 通过 computeIfPresent 从 3 更新为 5;banana 通过 merge 从 2 累加为 3;orange 原先不存在,因此直接写入 4。
更新与合并边界
compute、computeIfPresent 和 merge 的重映射函数如果返回 null,对应键会被删除。若只是想保留空值,不要让函数返回 null,可改用明确的占位对象或 Optional。
作为键的对象在放入 HashMap 后,不能修改参与 equals 或 hashCode 的字段,否则后续 get、remove 可能失效。安全替代方案是使用不可变键,例如 String、包装类型、不可变记录类型,或重新创建键对象。
普通 HashMap 不适合多线程并发写入,可能产生覆盖、状态不一致或遍历异常。共享写入使用 ConcurrentHashMap,并优先通过 compute、merge 等原子复合操作更新;不要使用“先 get 再 put”实现并发计数。ConcurrentHashMap 不允许 null 键或 null 值。
排障清单
- 查询结果意外为
null:先用containsKey区分键缺失与空值,再检查键的equals、hashCode。 - 遍历顺序变化:不要依赖
HashMap顺序,需要稳定输出时使用LinkedHashMap或显式排序。 - 计数在并发下偏小:检查是否使用了非原子的“读取、加一、写回”,改为
merge(key, 1, Integer::sum)。 Collectors.toMap报重复键:提供合并函数,明确保留旧值、使用新值或累计值。TreeMap丢键:检查比较器是否把不同键判为相等,即比较结果为0。
兼容性
getOrDefault、putIfAbsent、compute、merge 和 forEach 自 Java 8 可用;Map.of 自 Java 9 可用,返回不可变且不接受 null 的映射。
速查:普通键值查询选 HashMap,稳定遍历选 LinkedHashMap,按键排序选 TreeMap,并发共享写入选 ConcurrentHashMap。
Queue<E> queue = new ArrayDeque<>(); queue.offer(e); queue.poll(); queue.peek();
Deque<E> stack = new ArrayDeque<>(); stack.push(e); stack.pop();
PriorityQueue<E> heap = new PriorityQueue<>(<Comparator>);使用队列和双端队列实现先进先出、栈和缓冲区。
操作 Queue 与 Deque
Queue 适合先进先出任务,Deque 同时支持队列、栈和固定长度缓冲区。无并发要求时优先使用 ArrayDeque,并用不会因空队列抛异常的 offer、poll、peek 系列方法。
基本语法
Queue 只暴露队首和队尾操作;Deque 在两端都能插入、读取和删除元素。
| 目标 | 推荐方法 | 空容器时 |
|---|---|---|
| 队尾入队 | offer(e) / offerLast(e) |
返回 false 表示失败 |
| 队首出队 | poll() / pollFirst() |
返回 null |
| 查看队首 | peek() / peekFirst() |
返回 null |
| 栈顶压入 | push(e) |
正常压入队首 |
| 栈顶弹出 | pop() |
抛出 NoSuchElementException |
add、remove、element 在容量不足或队列为空时会抛异常,生产代码通常优先选择 offer、poll、peek。
高频用法
下面示例同时演示 FIFO 队列、LIFO 栈和滑动缓冲区,可直接编译运行。
import java.util.ArrayDeque;
import java.util.Deque;
import java.util.Queue;
public class QueueDequeDemo {
public static void main(String[] args) {
Queue<String> tasks = new ArrayDeque<>();
tasks.offer("task-A");
tasks.offer("task-B");
System.out.println("queue.peek=" + tasks.peek());
System.out.println("queue.poll=" + tasks.poll());
System.out.println("queue.left=" + tasks);
Deque<Integer> stack = new ArrayDeque<>();
stack.push(10);
stack.push(20);
System.out.println("stack.pop=" + stack.pop());
Deque<String> buffer = new ArrayDeque<>();
for (String value : new String[]{"A", "B", "C"}) {
buffer.offerLast(value);
if (buffer.size() > 2) {
buffer.pollFirst(); // 始终保留最近两个元素
}
}
System.out.println("buffer=" + buffer);
}
}预期输出
queue.peek=task-A
queue.poll=task-A
queue.left=[task-B]
stack.pop=20
buffer=[B, C]读取结果时,peek 只查看不删除,poll 返回并删除队首;push 和 pop 操作的是队首,因此表现为后进先出。
风险与边界
ArrayDeque 不允许插入 null。如果业务把 null 当作普通元素,就无法区分“取到空值”和“队列已空”,应改用显式对象或状态枚举。
ArrayDeque 不是线程安全容器。多个线程并发读写可能出现元素丢失、顺序异常或内部状态不可预期;生产者消费者场景应改用 BlockingQueue,双端并发场景使用 ConcurrentLinkedDeque。
不要在判空后再调用 remove 或 pop 依赖两步检查;并发环境中队列可能在两步之间被清空。优先直接调用 poll,再判断返回值。
排障清单
- 出队结果总是
null:确认是否实际调用了offer,以及容器是否被其他逻辑提前清空。 - 顺序与预期相反:队列使用
offerLast配合pollFirst;栈使用push配合pop,不要混用两套语义。 - 内存持续增长:检查是否只有入队没有出队;需要容量上限时改用有界
ArrayBlockingQueue。 - 并发下偶发丢数据:确认是否误用了
ArrayDeque或LinkedList作为共享队列。
速查:FIFO 用 offer、poll、peek;LIFO 用 push、pop、peek。
list.sort(Comparator.comparing(<类型>::<取值方法>).thenComparing(...).reversed());
Collections.sort(list); // 元素实现 Comparable使用 Comparable、Comparator 和组合比较器排序数据。
集合排序
集合排序主要解决三类需求:定义对象的默认顺序、按业务条件临时排序,以及组合多个排序字段。默认顺序放在 Comparable,业务排序优先使用 Comparator,避免把不同场景硬编码进实体类。
基本语法
Comparable<T> 通过 compareTo 定义自然顺序;Comparator<T> 在调用处定义外部顺序。list.sort(null) 使用自然顺序,list.sort(comparator) 原地修改列表,stream.sorted(comparator) 返回有序流而不修改原集合。
比较结果小于 0 表示当前对象排在前面,等于 0 表示排序上等价,大于 0 表示排在后面。
主示例
下面先按年龄和姓名定义自然顺序,再按分数降序、年龄升序、姓名升序组合业务排序。
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
public class CollectionSortDemo {
record User(String name, int age, int score) implements Comparable<User> {
@Override
public int compareTo(User other) {
int byAge = Integer.compare(this.age, other.age);
return byAge != 0 ? byAge : this.name.compareTo(other.name);
}
}
public static void main(String[] args) {
List<User> users = new ArrayList<>(List.of(
new User("Alice", 20, 90),
new User("Bob", 18, 90),
new User("Carol", 19, 95)
));
users.sort(null);
System.out.println("natural=" + users);
Comparator<User> byBusinessRule =
Comparator.comparingInt(User::score).reversed()
.thenComparingInt(User::age)
.thenComparing(User::name);
users.sort(byBusinessRule);
System.out.println("business=" + users);
}
}预期输出
natural=[User[name=Bob, age=18, score=90], User[name=Carol, age=19, score=95], User[name=Alice, age=20, score=90]]
business=[User[name=Carol, age=19, score=95], User[name=Bob, age=18, score=90], User[name=Alice, age=20, score=90]]第一行来自 compareTo;第二行先比较分数,分数相同时再比较年龄和姓名。thenComparing 的书写顺序就是优先级顺序。
常用组合
数值字段优先使用 comparingInt、comparingLong、comparingDouble,避免装箱。降序只对当前比较器调用 reversed(),再追加次级条件。
含 null 元素时必须明确位置,否则比较过程可能抛出 NullPointerException。例如将 Comparator.nullsLast(String.CASE_INSENSITIVE_ORDER) 传给 list.sort,可忽略字符串大小写并把 null 放在末尾。
风险与边界
不要使用 a - b 作为整数比较结果。数值接近上下界时可能溢出,导致排序顺序错误;使用 Integer.compare(a, b) 或 Comparator.comparingInt。
比较器必须满足自反性、反对称性和传递性。比较逻辑依赖随机数、当前时间或可变字段时,可能触发 Comparison method violates its general contract,或得到不稳定结果;排序前应固定参与比较的数据。
List.of 返回不可变列表,直接调用 sort 会抛出 UnsupportedOperationException。需要原地排序时先复制为 new ArrayList<>(source);不希望修改原集合时使用 stream().sorted(...).toList()。
排障清单
- 排序后原列表改变:
List.sort是原地操作;先复制列表或改用流式排序。 - 降序后次级字段也反了:先对主比较器调用
reversed(),再追加thenComparing。 - 出现空指针:检查元素本身或参与比较的字段是否为
null,按需要使用nullsFirst、nullsLast。 TreeSet丢元素:比较器返回0会被视为同一个排序键;补充能区分对象的字段,或改用允许重复的List。
速查:稳定默认顺序用 Comparable,临时业务规则用 Comparator,多字段按优先级连续调用 thenComparing。
List.of(...) / Set.of(...) / Map.of(<k1>, <v1>, ...)
List.copyOf(<集合>) / Collections.unmodifiableList(<列表>)创建只读集合并区分不可变集合与不可修改视图。
创建不可变集合
需要返回只读数据、固定配置或防止调用方增删集合时,优先使用 List.of、Set.of、Map.of 或 copyOf。它们禁止结构修改;Collections.unmodifiableXxx 只是包装视图,底层集合变化仍会反映出来。
基本用法
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.Set;
public class ImmutableCollectionDemo {
public static void main(String[] args) {
List<String> fixed = List.of("A", "B");
Set<Integer> codes = Set.of(200, 404);
Map<String, Integer> limits = Map.of("read", 10, "write", 2);
List<String> source = new ArrayList<>(List.of("x", "y"));
List<String> snapshot = List.copyOf(source);
List<String> view = Collections.unmodifiableList(source);
source.add("z"); // snapshot 不变,view 会跟随底层集合变化
System.out.println(fixed);
System.out.println(codes.contains(404));
System.out.println(limits.get("read"));
System.out.println(snapshot);
System.out.println(view);
}
}预期输出:
[A, B]
true
10
[x, y]
[x, y, z]读取时重点看最后两行:copyOf 得到独立快照,unmodifiableList 得到不可修改视图。
选型速查
| 需求 | 推荐写法 | 特性 |
|---|---|---|
| 少量固定元素 | List.of、Set.of、Map.of |
创建后不能增删改 |
| 从现有集合生成只读快照 | List.copyOf(source) |
后续不受源集合结构变化影响 |
| 限制调用方修改现有集合 | Collections.unmodifiableList(source) |
源集合变化会同步到视图 |
| 键值超过 10 组 | Map.ofEntries(...) |
避免 Map.of 重载数量限制 |
风险与边界
of 和 copyOf 不接受 null;Set.of 遇到重复元素、Map.of 遇到重复键会抛出 IllegalArgumentException。输入可能含空值或重复项时,先清洗数据,再创建集合。
这些 API 只保证集合结构不可修改,不会递归冻结元素。集合中的对象若有 setter,仍可被修改;需要真正只读时,应使用不可变元素类型、record 或防御性复制。
对只读集合调用 add、remove、clear 等方法会抛出 UnsupportedOperationException。不要用捕获异常来判断是否可修改,应在接口契约和变量命名中明确只读语义。
排障清单
出现 UnsupportedOperationException 时,先确认是否对 of、copyOf 或不可修改视图执行了写操作。确实需要修改时,创建可变副本:
List<String> editable = new ArrayList<>(List.of("A", "B"));
editable.add("C");
System.out.println(editable);预期输出:
[A, B, C]List.of、Set.of 和 Map.of 从 Java 9 提供,copyOf 从 Java 10 提供。固定数据用 of,隔离源集合用 copyOf,仅包装现有集合才用 unmodifiableXxx。
(参数) -> 表达式
(参数) -> { 语句; return 值; }
类名::静态方法 / 对象::实例方法 / 类名::new使用 Lambda、函数式接口和方法引用传递行为。
Lambda 与方法引用
需要把筛选、转换、排序或回调逻辑作为参数传递时,使用 Lambda;已有方法与函数式接口签名完全匹配时,可改成方法引用以减少样板代码。
基本语法
Lambda 的目标类型必须是函数式接口,即只有一个抽象方法的接口。常见接口位于 java.util.function:
| 接口 | 抽象方法 | 常见用途 |
|---|---|---|
Predicate<T> |
boolean test(T t) |
条件判断、过滤 |
Function<T,R> |
R apply(T t) |
类型转换 |
Consumer<T> |
void accept(T t) |
消费数据、输出 |
Supplier<T> |
T get() |
延迟创建对象 |
常见写法为 (参数) -> 表达式 或 (参数) -> { 语句; }。只有一个参数时可省略圆括号;代码块有返回值时必须显式 return。
主示例
import java.util.Comparator;
import java.util.List;
import java.util.function.Function;
import java.util.function.Predicate;
public class LambdaDemo {
public static void main(String[] args) {
List<String> names = List.of("Bob", "alice", "Tom");
Predicate<String> longName = name -> name.length() >= 4;
Function<String, String> normalize = String::toUpperCase;
names.stream()
.filter(longName)
.map(normalize)
.sorted(Comparator.comparingInt(String::length)
.thenComparing(String::compareTo))
.forEach(System.out::println);
}
}预期输出:
ALICE执行顺序是过滤长度、转为大写、按长度及字典序排序,最后输出。当前数据只有 alice 满足长度条件。
方法引用速查
| 形式 | 示例 | 等价 Lambda |
|---|---|---|
| 静态方法 | Integer::parseInt |
s -> Integer.parseInt(s) |
| 特定对象实例方法 | System.out::println |
x -> System.out.println(x) |
| 任意对象实例方法 | String::length |
s -> s.length() |
| 构造方法 | ArrayList::new |
() -> new ArrayList<>() |
方法引用不会“按名称自动匹配”,编译器会根据目标函数式接口检查参数数量、参数类型和返回值。签名不直观或需要额外判断时,保留 Lambda 通常更清楚。
风险与边界
Lambda 捕获的局部变量必须是 final 或“事实上未修改”。若在 Lambda 外重新赋值,会编译失败;需要累计状态时,优先使用流的归约操作,而不是共享可变变量。
重载方法可能导致方法引用歧义,例如目标类型不明确时 SomeType::method 无法推断。安全替代方案是显式声明函数式接口类型,或改写为带参数类型的 Lambda。
标准函数式接口通常不能直接抛出受检异常。调用会抛受检异常的方法时,应在 Lambda 内处理、封装为自定义函数式接口,或在业务边界转换异常;不要静默吞掉异常。
大量使用 Function<Integer, Integer> 可能产生装箱开销,热点路径可改用 IntFunction、IntPredicate、IntUnaryOperator 等原始类型接口。
排障清单
编译器提示“目标类型必须是函数式接口”时,检查接收位置是否明确声明了函数式接口。提示“局部变量必须为 final 或 effectively final”时,移除外部变量修改或改用 reduce、collect。方法引用报歧义时,先改成显式 Lambda,确认参数与返回值后再决定是否简化。
Lambda 和方法引用从 Java 8 提供;本例使用的 List.of 需要 Java 9 及以上。逻辑短且自包含用 Lambda,已有方法签名完全匹配用方法引用,可读性优先于字符更少。
<集合>.stream() / Stream.of(<元素>...) / Arrays.stream(<数组>)
Stream.iterate(<种子>, <下一项>).limit(<n>) / IntStream.range(<起>, <止>)
try (Stream<String> lines = Files.lines(<Path>)) { ... }从集合、数组、文件和生成函数创建顺序流。
创建 Stream
需要从已有数据或按规则生成数据流水线时,使用 Stream 统一执行筛选、转换和聚合。常见来源包括集合、数组、文件以及 generate、iterate 等生成函数;创建后通常继续连接中间操作,最后以终止操作触发计算。
基本语法
集合优先调用 collection.stream();数组使用 Arrays.stream(array);文件逐行读取使用 Files.lines(path);没有现成数据源时,可用 Stream.of、Stream.generate 或 Stream.iterate。
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;
public class CreateStreamDemo {
public static void main(String[] args) throws Exception {
List<String> users = Arrays.asList("alice", "bob", "carol");
String[] levels = {"INFO", "WARN", "ERROR"};
System.out.println("集合: " +
users.stream().map(String::toUpperCase).collect(Collectors.toList()));
System.out.println("数组: " +
Arrays.stream(levels).filter(s -> !s.equals("INFO")).collect(Collectors.toList()));
Path logFile = Files.createTempFile("stream-demo-", ".log");
Files.write(logFile, Arrays.asList("200 OK", "500 ERROR", "404 NOT_FOUND"));
// Files.lines 持有文件句柄,必须在 try-with-resources 中关闭。
try (Stream<String> lines = Files.lines(logFile)) {
System.out.println("文件: " +
lines.filter(line -> line.startsWith("5")).collect(Collectors.toList()));
}
System.out.println("generate: " +
Stream.generate(() -> "PING").limit(3).collect(Collectors.toList()));
// iterate 默认可无限生成,必须通过 limit 或三参数重载设置边界。
System.out.println("iterate: " +
Stream.iterate(1, n -> n + 2).limit(5).collect(Collectors.toList()));
Files.deleteIfExists(logFile);
}
}预期输出
集合: [ALICE, BOB, CAROL]
数组: [WARN, ERROR]
文件: [500 ERROR]
generate: [PING, PING, PING]
iterate: [1, 3, 5, 7, 9]读取时先确认数据来源,再看终止操作的结果。临时文件名属于动态值,但程序输出的数据内容固定。
高频用法
Stream.of(a, b, c) 适合少量已知元素;Stream.empty() 适合在条件分支中返回空流,避免返回 null。集合流默认是顺序流,只有明确需要并行且操作无共享副作用时才使用 parallelStream()。
Java 9 及以上可用三参数 Stream.iterate(1, n -> n <= 5, n -> n + 1) 创建有终止条件的序列;Java 8 则使用两参数 iterate 配合 limit 限制元素数量。
风险与边界
同一个流只能消费一次。已经执行 count、collect、forEach 等终止操作后再次使用,会触发 IllegalStateException;安全替代方案是重新创建流,或把结果先收集到集合。
Files.lines、Files.walk 等 I/O 流在未关闭时会占用文件句柄,批量处理文件可能导致“打开文件过多”;应始终使用 try-with-resources。generate 和两参数 iterate 默认无限,遗漏 limit 等边界会导致程序持续运行、内存增长或终止操作无法返回。
流默认不保存元素,也不会在创建时立即计算。不要把依赖可变外部状态的逻辑放进 map、filter 或 forEach,尤其不要直接切换并行流;更安全的做法是使用无副作用函数,并通过 collect、reduce 汇总结果。
排障清单
- 没有任何输出:检查是否缺少
collect、count、forEach等终止操作。 - 报“stream has already been operated upon or closed”:检查是否重复消费同一个流。
- 文件无法删除或句柄持续增长:检查 I/O 流是否放入 try-with-resources。
- 程序一直不结束:检查无限流是否设置
limit,或使用了带终止条件的三参数iterate。 - 顺序异常:确认是否误用了
parallelStream(),以及后续操作是否依赖 encounter order。
兼容性
基础 Stream API 自 Java 8 可用;Stream.iterate(seed, hasNext, next) 从 Java 9 开始提供。Java 8 若需要有界迭代,可使用两参数 iterate 配合 limit。
stream.filter(<条件>).map(<函数>).flatMap(<函数>).distinct().sorted(<比较器>).limit(<n>)使用 filter、map、flatMap、distinct 和 reduce 处理数据。
转换 Stream 数据
需要在不修改原始集合的情况下完成筛选、字段转换、嵌套数据展开、去重和汇总时,可组合 filter、map、flatMap、distinct 与 reduce。中间操作按声明顺序组成流水线,直到终止操作执行时才真正处理数据。
基本语法
filter 保留满足条件的元素,map 把一个元素转换成另一个元素,flatMap 把多个子流摊平成一个流,distinct 按 equals 与 hashCode 去重,reduce 将多个元素合并为一个结果。
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
public class TransformStreamDemo {
static class Order {
final String id;
final boolean paid;
final List<String> tags;
final int amount;
Order(String id, boolean paid, List<String> tags, int amount) {
this.id = id;
this.paid = paid;
this.tags = tags;
this.amount = amount;
}
}
public static void main(String[] args) {
List<Order> orders = Arrays.asList(
new Order("A100", true, Arrays.asList("java", "backend"), 120),
new Order("A101", false, Arrays.asList("java", "trial"), 80),
new Order("A102", true, Arrays.asList("backend", "cloud"), 200)
);
List<String> paidIds = orders.stream()
.filter(order -> order.paid)
.map(order -> order.id)
.collect(Collectors.toList());
// 每个订单包含多个标签,flatMap 将 List<String> 展开为单个字符串流。
List<String> uniqueTags = orders.stream()
.flatMap(order -> order.tags.stream())
.distinct()
.sorted()
.collect(Collectors.toList());
int paidTotal = orders.stream()
.filter(order -> order.paid)
.map(order -> order.amount)
// identity 为 0,后续把每个金额累加到当前结果。
.reduce(0, Integer::sum);
System.out.println("已支付订单: " + paidIds);
System.out.println("去重标签: " + uniqueTags);
System.out.println("已支付总额: " + paidTotal);
}
}预期输出
已支付订单: [A100, A102]
去重标签: [backend, cloud, java, trial]
已支付总额: 320读取结果时先按流水线顺序理解:第一条先筛选已支付订单再取编号;第二条展开全部标签后去重并排序;第三条筛选已支付订单、提取金额并累加。
操作选择
| 操作 | 输入到输出 | 适用场景 |
|---|---|---|
filter |
0 或 1 个元素 | 按状态、范围、非空条件筛选 |
map |
1 个元素变 1 个元素 | 提取字段、格式转换、对象映射 |
flatMap |
1 个元素变 0 到多个元素 | 展开列表、拆分文本、合并子流 |
distinct |
多个元素变唯一元素 | 清除重复值或重复对象 |
reduce |
多个元素合并为一个值 | 求和、求积、拼接或自定义归并 |
当元素是对象时,distinct 是否能去重取决于对象的 equals 和 hashCode。仅字段值需要去重时,通常先 map 提取字段,再调用 distinct。
高频用法
筛选条件应尽量提前,以减少后续映射和展开的数据量。对于数字求和,mapToInt(...).sum() 通常比装箱后的 map(...).reduce(...) 更直接;reduce 更适合自定义合并逻辑或需要返回同类型结果的场景。
例如,主示例中的金额汇总可改成 orders.stream().filter(order -> order.paid).mapToInt(order -> order.amount).sum(),结果仍为 320。mapToInt 使用原始类型流,可减少 Integer 装箱。
风险与边界
map 返回 null 不会自动丢弃元素,后续调用实例方法时可能触发 NullPointerException;安全做法是先过滤空值,或使用能明确表达缺失值的 Optional。flatMap 的映射函数也不应返回 null,没有子元素时返回 Stream.empty()。
没有 identity 的 reduce 返回 Optional,因为空流没有结果;直接调用 get() 可能触发 NoSuchElementException。可使用 orElse 提供默认值,或者使用带 identity 的重载。并行流中的归并函数必须满足结合律,且不能修改共享对象,否则可能出现结果不稳定或数据丢失。
distinct 是有状态操作,需要记录已见元素;大数据流或高基数数据会增加内存占用。若数据可在数据库、消息源或上游服务去重,应优先在更靠近数据源的位置处理。
排障清单
flatMap后数量异常:检查子集合是否包含重复值,以及是否还需要distinct。- 对象去重无效:检查是否正确实现
equals和hashCode。 reduce空流报错:检查是否无保护地调用Optional.get()。- 并行结果偶发错误:检查归并函数是否满足结合律,以及是否修改共享集合或计数器。
- 性能偏慢:把高选择性的
filter前移,并避免重复创建相同的中间流水线。
兼容性
这里使用的核心操作从 Java 8 起均可用。示例使用普通内部类和 Collectors.toList(),可直接在 Java 8 及以上编译运行。
.collect(Collectors.toList())
.collect(Collectors.groupingBy(<分类函数>, <下游收集器>))
.collect(Collectors.toMap(<键函数>, <值函数>, <合并函数>))
.collect(Collectors.joining(<分隔符>))将流收集为集合并完成分组、分区、拼接和统计。
使用 Collectors 收集 Stream
Collectors 用在流的终止操作 collect() 中,把元素一次性汇总为集合、分组结果、分区结果、字符串或统计信息。优先使用标准收集器,不要在 forEach() 中手动修改外部集合。
基本语法
常见写法是 stream.collect(Collectors.xxx())。需要静态导入时,可省略 Collectors. 前缀。
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
List<String> names = List.of("alice", "bob", "anna");
Map<Character, List<String>> grouped = names.stream()
.collect(Collectors.groupingBy(name -> name.charAt(0)));
System.out.println(grouped);预期输出:
{a=[alice, anna], b=[bob]}键是分组条件的返回值,值是落入该组的元素列表。HashMap 的键遍历顺序不应作为业务依赖。
高频用法
下面的完整示例覆盖集合转换、分组、分区、拼接和统计。
import java.util.IntSummaryStatistics;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;
public class CollectorsDemo {
record Order(String customer, int amount, boolean paid) {}
public static void main(String[] args) {
List<Order> orders = List.of(
new Order("Alice", 120, true),
new Order("Bob", 80, false),
new Order("Alice", 200, true)
);
Set<String> customers = orders.stream()
.map(Order::customer)
.collect(Collectors.toSet());
Map<String, List<Order>> byCustomer = orders.stream()
.collect(Collectors.groupingBy(Order::customer));
Map<Boolean, List<Order>> byPaid = orders.stream()
.collect(Collectors.partitioningBy(Order::paid));
String paidCustomers = orders.stream()
.filter(Order::paid)
.map(Order::customer)
.distinct()
.collect(Collectors.joining(", "));
IntSummaryStatistics stats = orders.stream()
.collect(Collectors.summarizingInt(Order::amount));
System.out.printf("customers=%d,hasAlice=%s%n",
customers.size(), customers.contains("Alice"));
System.out.println(byCustomer.get("Alice"));
System.out.println(byPaid.get(false));
System.out.println(paidCustomers);
System.out.printf("count=%d,sum=%d,min=%d,max=%d,avg=%.1f%n",
stats.getCount(), stats.getSum(), stats.getMin(),
stats.getMax(), stats.getAverage());
}
}预期输出:
customers=2,hasAlice=true
[Order[customer=Alice, amount=120, paid=true], Order[customer=Alice, amount=200, paid=true]]
[Order[customer=Bob, amount=80, paid=false]]
Alice
count=3,sum=400,min=80,max=200,avg=133.3toSet() 不保证元素顺序,因此示例通过数量和成员检查验证结果;分组中的列表仍按输入流的遭遇顺序读取。
常用组合
groupingBy() 可以配合下游收集器,直接得到计数、求和或字段列表,避免分组后再二次遍历。以下为片段示例,沿用前面定义的 orders。
Map<String, Integer> amountByCustomer = orders.stream()
.collect(Collectors.groupingBy(
Order::customer,
Collectors.summingInt(Order::amount)
));
System.out.printf("Alice=%d,Bob=%d%n",
amountByCustomer.get("Alice"),
amountByCustomer.get("Bob"));预期输出:
Alice=320,Bob=80风险与边界
Collectors.toMap() 遇到重复键且未提供合并函数时会抛出 IllegalStateException。生产代码应明确重复键策略。以下为片段示例,沿用前述 orders。
Map<String, Integer> latestAmount = orders.stream()
.collect(Collectors.toMap(
Order::customer,
Order::amount,
(oldValue, newValue) -> newValue
));
System.out.printf("Alice=%d,Bob=%d%n",
latestAmount.get("Alice"),
latestAmount.get("Bob"));预期输出:
Alice=200,Bob=80如果重复键代表脏数据,不要静默覆盖,应先校验并记录冲突。groupingBy() 不能接受 null 分组键;数据可能为空时先过滤、映射为默认值,或在进入流前完成校验。
速查提示
集合去重用 toSet(),分类用 groupingBy(),真假两组用 partitioningBy(),文本输出用 joining(),一次获得数量、总和、最小值、最大值和平均值用 summarizingInt()。
判断并行流适用场景并规避共享状态和线程池问题。
控制并行流风险
只有每个元素的计算可独立执行、合并规则正确且任务规模足够时,才尝试并行流。对少量数据、阻塞网络调用或依赖先后顺序的任务,先用顺序实现测量基线。
语法与执行约束
对集合调用 parallelStream(),或对流调用 parallel(),请求并行执行;sequential() 切回顺序模式。行为参数应不干扰数据源、避免共享可变状态。并行归约的运算必须可结合,初始值必须是对应单位元,例如加法的 0。
forEach 不保证元素处理顺序;forEachOrdered 可以保持遇见顺序,却可能限制吞吐。不能用日志输出顺序推断线程启动顺序,也不能把线程名写进业务契约。常见 JDK 实现使用公共 ForkJoin 资源,不应让慢 I/O 挤占其他功能的执行能力。
无共享累加器的例子
保存为 ParallelRisk.java。用归约得到平方和,不让多个线程同时修改同一个普通整数或列表。
import java.util.stream.IntStream;
public class ParallelRisk {
public static void main(String[] args) {
// sum 的零值与加法满足可结合归约,本例数值不会溢出
long sequential = IntStream.rangeClosed(1, 1000)
.mapToLong(n -> (long) n * n).sum();
long parallel = IntStream.rangeClosed(1, 1000).parallel()
.mapToLong(n -> (long) n * n).sum();
System.out.println(sequential);
System.out.println(parallel);
System.out.println(sequential == parallel);
}
}预期结果:顺序与并行计算相同;本例验证正确性,不证明并行更快。执行:
javac ParallelRisk.java
java ParallelRisk预期输出:
333833500
333833500
true上线前检查
把 list.add(value) 放进并行 forEach,即使偶尔结果正确,也不能说明普通 ArrayList 安全。优先用流自身的归约或收集操作。共享状态确实不可避免时,单独评估锁竞争,而不是添加锁后就默认性能提升。
比较性能时固定输入、预热、CPU 限额和同机负载,并测端到端延迟。浮点加法不满足严格结合律,并行重新分组可能改变末尾精度;金额计算应遵守明确的数值与舍入规则。修改后要保留顺序实现作为对照。
回退方式
出现吞吐下降、超时或资源争抢时,先切回顺序流恢复可预测行为。需要限制网络并发、超时与取消时,使用显式任务和有界资源设计;不要指望给并行流加一个全局参数就隔离全部调用。避免在公共池任务中等待同池的其他任务完成,减少线程饥饿风险。
new BigDecimal("<数值字符串>")
a.add(b) / a.subtract(b) / a.multiply(b) / a.compareTo(b)
a.divide(b, <小数位>, RoundingMode.HALF_UP) / a.setScale(2, RoundingMode.HALF_UP)完成金额计算、舍入、比较和精度控制。
使用 BigDecimal
BigDecimal 用于金额、费率和需要十进制精度的计算。核心原则是用字符串创建数值、显式指定舍入规则,并用 compareTo 判断数值大小。
基本语法
优先使用 new BigDecimal("19.90") 或 BigDecimal.valueOf(19.90)。不要直接传入 double,因为二进制浮点值可能在构造前已经产生误差。
常用操作包括 add、subtract、multiply、divide、setScale 和 compareTo。BigDecimal 是不可变对象,每次计算都会返回新值,必须接收返回结果。
金额计算与舍入
下面示例完成小计、折扣、应付金额、均摊和比较,可直接运行。
import java.math.BigDecimal;
import java.math.RoundingMode;
public class BigDecimalDemo {
public static void main(String[] args) {
BigDecimal price = new BigDecimal("19.90");
BigDecimal quantity = new BigDecimal("3");
BigDecimal discountRate = new BigDecimal("0.15");
BigDecimal subtotal = price.multiply(quantity);
// 金额落库或展示前统一保留 2 位,避免各环节舍入规则不一致
BigDecimal discount = subtotal.multiply(discountRate)
.setScale(2, RoundingMode.HALF_UP);
BigDecimal payable = subtotal.subtract(discount);
// 除法可能产生无限小数,必须同时指定小数位和舍入模式
BigDecimal perItem = payable.divide(quantity, 2, RoundingMode.HALF_UP);
System.out.println("subtotal=" + subtotal.toPlainString());
System.out.println("discount=" + discount.toPlainString());
System.out.println("payable=" + payable.toPlainString());
System.out.println("perItem=" + perItem.toPlainString());
System.out.println("compareTo=" +
(payable.compareTo(new BigDecimal("50.740")) == 0));
System.out.println("equals=" +
payable.equals(new BigDecimal("50.740")));
}
}预期输出:
subtotal=59.70
discount=8.96
payable=50.74
perItem=16.91
compareTo=true
equals=falsecompareTo 只比较数值,因此 50.74 与 50.740 相等;equals 同时比较数值和小数位,因此结果为 false。
常用规则
金额相加减前通常不要求 scale 完全一致,但对外展示、数据库字段或接口报文应在边界处统一 setScale(2, RoundingMode.HALF_UP)。中间计算不要过早舍入,否则多步骤累计后可能出现分差。
需要限制整体有效数字时使用 MathContext;只控制小数位时使用 setScale。输出金额优先用 toPlainString(),避免极大或极小数值显示成科学计数法。
风险与边界
直接执行 new BigDecimal(0.1) 会带入浮点误差,可能导致金额尾差;安全替代是字符串构造或 BigDecimal.valueOf。执行无法整除的 divide 且未指定舍入规则,会抛出 ArithmeticException;安全替代是明确 scale 和 RoundingMode。
用 equals 做金额相等判断时,不同 scale 会被判为不等,可能导致对账失败;金额比较应使用 compareTo(...) == 0。不要把舍入模式分散在多个业务层,生产系统应由统一金额工具或领域规则集中管理。
排障清单
- 出现长小数:检查是否从
double构造,或除法是否缺少 scale。 - 金额相等却判断失败:检查是否误用了
equals。 - 汇总金额相差一分钱:检查是否在明细阶段重复舍入,以及各系统舍入模式是否一致。
- 数据库存取后小数位变化:检查列类型是否为
DECIMAL,并核对 Java 与数据库 scale。
LocalDate.of(<年>, <月>, <日>) / LocalDateTime.now() / Instant.now()
ZonedDateTime.now(ZoneId.of("<时区>"))
DateTimeFormatter.ofPattern("<格式>").format(<时间>) / LocalDate.parse("<文本>", <formatter>)使用 java.time 创建、转换、格式化和计算日期时间。
处理日期时间
使用 java.time 处理日期、时间、时区和时间点。无时区业务日期用 LocalDate,绝对时间点用 Instant,跨时区展示或调度用 ZonedDateTime。
类型选择
LocalDate 表示日期,不含时分秒;LocalTime 表示一天内时间;LocalDateTime 表示本地日期时间,但不包含时区。Instant 表示 UTC 时间线上的唯一时刻,适合日志、事件时间和跨系统传输。
ZonedDateTime 同时保存本地时间、时区和偏移量,适合需要处理夏令时的场景。固定偏移量报文可使用 OffsetDateTime,但它不包含完整时区规则。
创建、转换与格式化
下面示例使用固定时间,演示日期计算、吉隆坡时间转 UTC、同一时刻转伦敦时间,以及 Period 和 Duration 的区别。
import java.time.Duration;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.Period;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.time.temporal.ChronoUnit;
public class DateTimeDemo {
public static void main(String[] args) {
LocalDate date = LocalDate.of(2026, 8, 2);
LocalDate nextWeek = date.plusWeeks(1);
LocalDateTime localTime = LocalDateTime.of(2026, 8, 2, 9, 30);
ZonedDateTime kualaLumpur = localTime.atZone(
ZoneId.of("Asia/Kuala_Lumpur"));
// Instant 表示唯一时间点,可安全传输到其他系统或转换到任意时区
Instant instant = kualaLumpur.toInstant();
ZonedDateTime london = instant.atZone(ZoneId.of("Europe/London"));
DateTimeFormatter formatter =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm XXX VV");
Period calendarPeriod = Period.between(
date, date.plusMonths(1).plusDays(3));
Duration elapsed = Duration.between(
instant, kualaLumpur.plusHours(2).toInstant());
System.out.println("nextWeek=" + nextWeek);
System.out.println("days=" + ChronoUnit.DAYS.between(date, nextWeek));
System.out.println("kualaLumpur=" + formatter.format(kualaLumpur));
System.out.println("instant=" + instant);
System.out.println("london=" + formatter.format(london));
System.out.println("period=" + calendarPeriod);
System.out.println("duration=" + elapsed);
}
}预期输出:
nextWeek=2026-08-09
days=7
kualaLumpur=2026-08-02 09:30 +08:00 Asia/Kuala_Lumpur
instant=2026-08-02T01:30:00Z
london=2026-08-02 02:30 +01:00 Europe/London
period=P1M3D
duration=PT2HPeriod 按年、月、日计算日历差值;Duration 按秒和纳秒计算真实经过时间。跨夏令时边界计算耗时,应基于 Instant 或 ZonedDateTime,不要只减 LocalDateTime。
解析与格式化边界
解析固定格式文本时使用与输入完全匹配的 DateTimeFormatter。ISO 格式优先使用内置常量,如 DateTimeFormatter.ISO_LOCAL_DATE 和 DateTimeFormatter.ISO_OFFSET_DATE_TIME,减少自定义格式不一致。
格式中的 MM 表示月份,mm 表示分钟;HH 是 24 小时制,hh 是 12 小时制。格式化器是不可变且线程安全的,可定义为 static final 复用。
风险与边界
调用 LocalDateTime.now() 或 ZoneId.systemDefault() 会依赖服务器时区,容器迁移后可能产生时间偏移;安全替代是显式传入 Clock 或 ZoneId。把 LocalDateTime 当成 UTC 直接存储,会丢失原始时区语义;跨系统传输优先使用带 Z 或偏移量的 ISO 时间。
夏令时切换时,某些本地时间可能不存在或出现两次,直接拼接日期和时间可能得到意外偏移;安全替代是使用业务指定的 ZoneId 创建 ZonedDateTime,并在关键调度场景验证转换结果。
排障清单
- 时间固定相差 8 小时:检查 UTC 与本地时间是否重复转换,或是否丢失
Z/偏移量。 - 格式化月份异常:检查是否把
MM写成mm。 - 跨地区显示不一致:确认存储的是
Instant,展示时再应用目标ZoneId。 - 定时任务在夏令时当天重复或跳过:检查调度时区和目标地区的 DST 规则。
java.time 自 Java 8 起可用;旧的 Date、Calendar 和 SimpleDateFormat 应只在兼容旧接口时使用,并尽快在边界层转换。
Pattern pattern = Pattern.compile("<正则>", Pattern.CASE_INSENSITIVE);
Matcher matcher = pattern.matcher("<文本>");
matcher.find() / matcher.matches() / matcher.group(<n>)编译正则并完成字符串匹配、提取、替换和分割。
使用正则表达式
需要校验格式、从文本中提取字段、批量替换或按规则分割时,先用 Pattern 编译表达式,再用 Matcher 执行匹配。固定表达式应复用已编译的 Pattern,不要在循环中反复调用 Pattern.compile。
基本语法
Pattern pattern = Pattern.compile("正则", Pattern.CASE_INSENSITIVE);
Matcher matcher = pattern.matcher("待处理文本");matches() 要求整个字符串完全匹配;find() 从当前位置查找下一个子串;group() 读取本次命中的完整文本,group(n) 读取第 n 个捕获组。只需判断是否包含时通常用 find(),不要误用 matches()。
高频用法
下面示例覆盖校验、提取、替换和分割,可直接保存为 RegexDemo.java 后运行。
import java.util.Arrays;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
public class RegexDemo {
private static final Pattern ORDER =
Pattern.compile("(?<prefix>[A-Z]{2})-(?<serial>\\d{4})");
public static void main(String[] args) {
String input = "订单 PM-1024 已支付,备用单号 PM-2048";
// matches() 校验完整字符串;find() 逐个提取局部命中。
System.out.println("valid=" + ORDER.matcher("PM-1024").matches());
Matcher matcher = ORDER.matcher(input);
while (matcher.find()) {
System.out.printf("order=%s, prefix=%s, serial=%s%n",
matcher.group(), matcher.group("prefix"), matcher.group("serial"));
}
// 替换串中的 $ 和 \ 有特殊含义,动态文本应使用 quoteReplacement。
String masked = ORDER.matcher(input).replaceAll(
Matcher.quoteReplacement("<ORDER>"));
System.out.println("masked=" + masked);
String[] fields = Pattern.compile("\\s*,\\s*")
.split("java, regex, files");
System.out.println("fields=" + Arrays.toString(fields));
}
}预期输出:
valid=true
order=PM-1024, prefix=PM, serial=1024
order=PM-2048, prefix=PM, serial=2048
masked=订单 <ORDER> 已支付,备用单号 <ORDER>
fields=[java, regex, files]读取时先看 valid 是否通过完整校验;每个 order 对应一次 find() 命中;命名组直接按业务名读取,比分组序号更不易因表达式调整而错位。
常用参数
| 写法 | 作用 | 使用边界 |
|---|---|---|
Pattern.CASE_INSENSITIVE |
忽略 ASCII 大小写 | Unicode 场景通常同时加 UNICODE_CASE |
Pattern.MULTILINE |
让 ^、$ 按行匹配 |
不会让 . 自动匹配换行 |
Pattern.DOTALL |
让 . 包含换行 |
可能扩大匹配范围,应配合明确边界 |
Pattern.LITERAL |
把表达式整体按普通文本处理 | 动态字面量也可使用 Pattern.quote |
需要在 Java 字符串中表示正则反斜杠时要写两层转义,例如正则 \d+ 在源码中写成 "\\d+"。用户输入作为普通文本拼入正则时,先用 Pattern.quote(userInput),避免 .、*、[ 等字符改变规则。
风险与边界
复杂回溯表达式在长文本或恶意输入下可能造成 CPU 长时间占用,例如大量嵌套量词、宽泛的 .* 与模糊分支组合。后果是请求线程阻塞甚至服务超时;优先改成明确字符类、长度上限和非回溯结构,并在入口限制待匹配字符串长度。
Matcher 保存当前位置和捕获结果,不是线程安全对象;跨线程复用会产生错乱结果。安全做法是共享不可变的 Pattern,每次调用重新创建 Matcher。
表达式来自配置或用户输入时,Pattern.compile 可能抛出 PatternSyntaxException。加载配置时应提前编译并失败告警,不要等业务请求进入后才暴露错误。
排障清单
matches()返回false:确认是否只需要子串命中;需要时改用find(),或在表达式中明确首尾边界。- 分组值错位:检查是否新增了捕获括号;不需要捕获的分组改为
(?:...),关键字段使用命名组。 - 替换时报
Illegal group reference:动态替换值使用Matcher.quoteReplacement。 - 线上 CPU 突升:记录输入长度和表达式,重点检查嵌套量词、模糊分支及无上限重复。
速查:固定规则复用 Pattern,单次执行独占 Matcher;完整校验用 matches(),批量提取用 find()。
Path path = Path.of("<目录>", "<文件名>");
Files.exists(path) / Files.createDirectories(path.getParent())
Files.copy(<源>, <目标>, StandardCopyOption.REPLACE_EXISTING) / Files.move(...) / Files.delete(path)使用 Path 和 Files 创建、复制、移动、删除及遍历文件。
操作路径与文件
创建目录、读写文件、复制、移动、删除或遍历目录时,使用 Path 表示路径,使用 Files 执行实际 I/O。优先保留 Path 对象,不要手工用字符串拼接目录分隔符。
基本语法
Path path = Path.of("data", "report.txt");
Files.createDirectories(path.getParent());
Files.writeString(path, "content", StandardCharsets.UTF_8);Path.of 只构造路径,不会创建文件;真正访问磁盘时才可能抛出 IOException。createDirectories 会连同缺失的父目录一起创建,目录已经存在时不会报错。
高频用法
下面示例在系统临时目录中完成创建、写入、复制、移动、遍历和清理,可直接保存为 FilesDemo.java 后运行。
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.Comparator;
import java.util.stream.Collectors;
import java.util.stream.Stream;
public class FilesDemo {
public static void main(String[] args) throws IOException {
Path root = Files.createTempDirectory("files-demo-");
Path dataDir = Files.createDirectories(root.resolve("data"));
Path archiveDir = Files.createDirectories(root.resolve("archive"));
Path source = dataDir.resolve("source.txt");
try {
Files.writeString(source, "alpha\nbeta\n", StandardCharsets.UTF_8);
System.out.println("content=" + Files.readString(
source, StandardCharsets.UTF_8).replace("\n", "|"));
// 复制默认不覆盖;目标可能已存在时必须明确 REPLACE_EXISTING。
Path copy = Files.copy(source, archiveDir.resolve("copy.txt"),
StandardCopyOption.REPLACE_EXISTING);
Path moved = Files.move(source, archiveDir.resolve("moved.txt"),
StandardCopyOption.REPLACE_EXISTING);
try (Stream<Path> stream = Files.list(archiveDir)) {
System.out.println("archive=" + stream
.map(Path::getFileName)
.map(Path::toString)
.sorted()
.collect(Collectors.toList()));
}
try (Stream<Path> stream = Files.walk(root)) {
System.out.println("pathCount=" + stream.count());
}
System.out.println("copyExists=" + Files.exists(copy));
System.out.println("sourceExists=" + Files.exists(source));
System.out.println("movedExists=" + Files.exists(moved));
} finally {
// 删除非空目录前先按深度逆序处理,确保子项先于父目录删除。
try (Stream<Path> stream = Files.walk(root)) {
stream.sorted(Comparator.reverseOrder())
.forEach(FilesDemo::deleteQuietly);
}
}
}
private static void deleteQuietly(Path path) {
try {
Files.deleteIfExists(path);
} catch (IOException e) {
System.err.println("deleteFailed=" + path.getFileName());
}
}
}预期输出:
content=alpha|beta|
archive=[copy.txt, moved.txt]
pathCount=5
copyExists=true
sourceExists=false
movedExists=true临时目录的真实路径包含动态随机值,但示例只输出文件名和状态。sourceExists=false 表示移动成功后原路径已不存在;pathCount=5 包含根目录、两个子目录和两个归档文件。
常用选项
| 选项或方法 | 作用 | 注意点 |
|---|---|---|
REPLACE_EXISTING |
覆盖已存在目标 | 覆盖前确认目标是否允许丢失 |
COPY_ATTRIBUTES |
复制基础文件属性 | 不保证所有文件系统属性都支持 |
ATOMIC_MOVE |
请求原子移动 | 文件系统不支持时会抛出 AtomicMoveNotSupportedException |
deleteIfExists |
存在则删除 | 非空目录仍会失败 |
Files.list |
只遍历一层 | 返回的 Stream 必须关闭 |
Files.walk |
递归遍历 | 大目录应限制深度并及时关闭流 |
拼接子路径用 root.resolve("child");需要标准化 a/../b 时用 normalize()。normalize() 只做语法化简,不解析符号链接;需要真实磁盘路径时使用 toRealPath(),但路径必须存在。
风险与边界
复制或移动时使用 REPLACE_EXISTING,触发条件是目标路径已存在;后果是原目标内容被覆盖。安全替代是先检查目标、生成唯一文件名,或先写临时文件再使用同文件系统内的原子移动完成替换。
递归遍历用户可控目录时,符号链接可能把处理范围引向预期目录之外;误删工具还可能删除非目标文件。默认不要启用 FOLLOW_LINKS,删除前将目标转成规范路径并确认其位于允许的根目录下。
Files.readString、readAllBytes 会一次性把内容读入内存,大文件可能触发高内存占用甚至 OutOfMemoryError。大文件应使用 Files.newBufferedReader、newInputStream 或按行流式处理。
文件操作可能在检查后到执行前被其他进程改变,单独依赖 exists() 存在竞态。应直接执行目标操作并处理异常,而不是把“先检查、后操作”当作并发安全保证。
排障清单
NoSuchFileException:打印path.toAbsolutePath(),确认工作目录、父目录和文件名大小写。AccessDeniedException:检查运行用户、目录权限、只读挂载以及文件是否被其他程序占用。FileAlreadyExistsException:确认是否应覆盖;允许时显式添加REPLACE_EXISTING。DirectoryNotEmptyException:先遍历删除子项,再删除父目录;不要直接删除非空目录。- 遍历后文件句柄未释放:确认
Files.list、Files.walk返回的流位于 try-with-resources 中。 - 原子移动失败:捕获
AtomicMoveNotSupportedException,评估是否允许降级为普通移动。
兼容性:Path、Files 从 Java 7 提供;Files.walk 从 Java 8 提供;Path.of、readString、writeString 需要 Java 11。Java 8 项目可改用 Paths.get 和缓冲流读写。
Files.readString(path, StandardCharsets.UTF_8) / Files.readAllLines(path)
Files.writeString(path, <文本>, StandardCharsets.UTF_8, <OpenOption>...)
Files.newBufferedReader(path) / Files.newBufferedWriter(path)按指定字符集读取和写入文本文件。
读写文本文件
用于按明确字符集读取或写入文本,避免依赖操作系统默认编码。小文件优先用 Files.readString、Files.writeString;大文件或逐行处理使用缓冲读写器。
基本语法
将以下代码保存为 TextFileDemo.java。示例覆盖 UTF-8 覆盖写入、追加写入、整文件读取和按行读取。
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;
import java.util.List;
public class TextFileDemo {
public static void main(String[] args) throws Exception {
Path file = Path.of("notes.txt");
// 明确指定 UTF-8;默认会创建文件并截断已有内容。
Files.writeString(
file,
"alpha\n中文\n",
StandardCharsets.UTF_8
);
// 追加时显式声明 APPEND,避免再次覆盖。
Files.writeString(
file,
"omega\n",
StandardCharsets.UTF_8,
StandardOpenOption.APPEND
);
String all = Files.readString(file, StandardCharsets.UTF_8);
List<String> lines = Files.readAllLines(file, StandardCharsets.UTF_8);
System.out.print(all);
System.out.println("lineCount=" + lines.size());
}
}编译并运行:
javac TextFileDemo.java
java TextFileDemo预期输出:
alpha
中文
omega
lineCount=3先检查文本是否正常,再核对 lineCount。若中文乱码,通常是写入、读取或外部编辑器使用了不同字符集。
高频用法
- 小文件整体读取:
Files.readString(path, StandardCharsets.UTF_8)。 - 覆盖写入:
Files.writeString(path, text, StandardCharsets.UTF_8)。 - 安全追加:同时传入
StandardOpenOption.CREATE和StandardOpenOption.APPEND,文件不存在时创建,存在时追加。 - 大文件逐行处理:使用
Files.newBufferedReader(path, charset),在 try-with-resources 中循环调用readLine(),避免一次载入全部内容。
需要逐行写入时使用 Files.newBufferedWriter。关闭写入器会自动刷新缓冲区;只有持续写入且下游必须立即读取时才主动调用 flush()。
风险与边界
Files.writeString 未指定打开选项时会覆盖原文件。触发条件是目标文件已存在,后果是旧内容丢失;不确定时先写同目录临时文件,校验成功后再用 Files.move 替换。
readString、readAllLines 会把完整文件载入内存。处理数百 MB 或大小未知的文件时可能造成高内存占用甚至 OutOfMemoryError;改用 newBufferedReader 流式读取。
不要使用 Charset.defaultCharset() 处理跨机器文件。开发机和生产机默认编码可能不同,后果是乱码或解析失败;协议、配置和数据文件应固定为 UTF-8 或业务约定编码。
排障清单
MalformedInputException:文件实际编码与指定字符集不一致,先确认来源系统的编码。NoSuchFileException:打印path.toAbsolutePath(),确认相对路径所基于的工作目录。AccessDeniedException:检查目录权限、只读挂载以及文件是否被其他进程独占。- 追加后内容粘连:确认原内容末尾或追加内容开头包含所需换行符。
- 写入成功但读取旧内容:确认读取的是同一路径,并排查应用缓存或其他进程覆盖。
兼容性
Files.readString、Files.writeString 从 Java 11 提供。Java 8 可使用 Files.readAllBytes、Files.write,或 Files.newBufferedReader、Files.newBufferedWriter。
try (InputStream in = new BufferedInputStream(Files.newInputStream(<源>));
OutputStream out = new BufferedOutputStream(Files.newOutputStream(<目标>))) {
int n; while ((n = in.read(buffer)) != -1) out.write(buffer, 0, n);
}使用字节流、缓冲流和通道处理二进制数据。
处理二进制与缓冲 I/O
用于复制图片、压缩包、协议报文等原始字节。普通字节流负责读写,缓冲流减少系统调用;大文件顺序复制、随机访问或文件锁场景可使用 FileChannel。
基本语法
将以下代码保存为 BinaryIoDemo.java。示例先生成二进制文件,再分别用缓冲流和通道复制,并验证结果一致。
import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.IOException;
import java.nio.channels.FileChannel;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;
import java.util.Arrays;
public class BinaryIoDemo {
private static final int BUFFER_SIZE = 8192;
public static void main(String[] args) throws Exception {
Path source = Path.of("source.bin");
Path bufferedCopy = Path.of("copy-buffered.bin");
Path channelCopy = Path.of("copy-channel.bin");
byte[] payload = {0, 1, 2, 3, 127, (byte) 128, (byte) 255};
Files.write(source, payload);
copyWithBuffer(source, bufferedCopy);
copyWithChannel(source, channelCopy);
System.out.println("bufferedEqual=" +
Arrays.equals(Files.readAllBytes(source), Files.readAllBytes(bufferedCopy)));
System.out.println("channelEqual=" +
Arrays.equals(Files.readAllBytes(source), Files.readAllBytes(channelCopy)));
System.out.println("bytes=" + Files.size(source));
}
private static void copyWithBuffer(Path source, Path target) throws IOException {
try (var in = new BufferedInputStream(Files.newInputStream(source));
var out = new BufferedOutputStream(
Files.newOutputStream(
target,
StandardOpenOption.CREATE,
StandardOpenOption.TRUNCATE_EXISTING
))) {
byte[] buffer = new byte[BUFFER_SIZE];
int read;
// read 返回本轮有效字节数,最后一轮通常小于缓冲区长度。
while ((read = in.read(buffer)) != -1) {
out.write(buffer, 0, read);
}
}
}
private static void copyWithChannel(Path source, Path target) throws IOException {
try (FileChannel in = FileChannel.open(source, StandardOpenOption.READ);
FileChannel out = FileChannel.open(
target,
StandardOpenOption.CREATE,
StandardOpenOption.WRITE,
StandardOpenOption.TRUNCATE_EXISTING
)) {
long position = 0;
while (position < in.size()) {
// transferTo 允许部分传输,必须按返回值推进位置。
long transferred = in.transferTo(position, in.size() - position, out);
if (transferred <= 0) {
throw new IOException("No progress while copying");
}
position += transferred;
}
}
}
}编译并运行:
javac BinaryIoDemo.java
java BinaryIoDemo预期输出:
bufferedEqual=true
channelEqual=true
bytes=7两个 true 表示复制结果与源文件逐字节一致;bytes=7 是示例负载长度。实际文件名、大小和耗时会随输入变化。
高频用法
- 普通文件复制:优先用
Files.copy(source, target, REPLACE_EXISTING),代码最少且不易漏处理边界。 - 自定义处理链:用
BufferedInputStream和BufferedOutputStream,例如复制过程中计算摘要、解密或限速。 - 固定长度协议字段:用
DataInputStream.readFully(byte[]);数据不足时抛出异常,避免把半包当成完整消息。 - 大文件、随机访问、文件锁或内存映射:使用
FileChannel。
正常关闭 BufferedOutputStream 会自动刷新。网络长连接或持续写入且接收端必须立即处理时才主动 flush();每写少量数据就刷新会显著降低吞吐。
输出字段说明
InputStream.read(byte[]) 返回本次实际读取的字节数,返回 -1 才表示结束。写出时必须使用 out.write(buffer, 0, read),否则最后一轮可能把缓冲区残留数据写入目标文件。
Java 的 byte 范围是 -128 到 127。查看无符号字节值时使用 b & 0xFF;例如 (byte) 255 的有符号值是 -1,但转换后得到 255。
FileChannel.transferTo 的返回值是本次实际传输字节数,不保证一次完成全部数据。循环应累计位置,并对持续零进度设置失败处理或重试上限。
风险与边界
未使用 TRUNCATE_EXISTING 覆盖较短文件时,旧文件尾部可能残留。触发条件是目标文件已存在且新内容更短;安全做法是明确截断,或写临时文件后原子替换。
把二进制数据转成字符串再写回会经过字符编码,可能破坏任意字节。图片、密钥、压缩包和协议帧必须始终使用字节流或通道;文本化传输应使用明确的 Base64 编解码。
缓冲区越大不一定越快。过大的单连接缓冲区会增加总内存占用;普通文件复制可从 8 KiB 到 64 KiB 起步,再根据压测结果调整。
示例中的 Files.readAllBytes 仅用于验证 7 字节数据。验证大文件时直接计算摘要或分块比较,避免完整载入内存。
排障清单
- 文件大小不一致:检查是否始终按
read返回值写出。 - 文件尾部多出旧数据:确认目标流使用了
TRUNCATE_EXISTING。 - 大文件复制卡住:检查通道循环是否处理部分传输和零进度。
- 文件内容损坏:确认中途没有经过
String、错误 Base64 解码或错误字节序转换。 - 句柄耗尽:所有流和通道都放入 try-with-resources,避免异常路径漏关闭。
- 吞吐忽高忽低:检查是否频繁
flush、磁盘空间不足或源目标位于同一慢盘。
兼容性
InputStream、缓冲流和 FileChannel 在 Java 8 可用;var 与 Path.of 分别需要 Java 10、Java 11。Java 8 中将 var 改为具体类型,并用 Paths.get(...)。
HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(<秒>)).build();
HttpRequest request = HttpRequest.newBuilder(URI.create("<URL>")).GET().build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());使用标准 HttpClient 发送同步和异步 HTTP 请求。
发送 HTTP 请求
Java 11+ 使用 java.net.http.HttpClient 发送 HTTP/1.1 或 HTTP/2 请求。同步调用适合当前线程必须立即拿到结果的场景;异步调用返回 CompletableFuture,适合并发请求或不希望阻塞调用线程的场景。
基本语法
通常复用一个 HttpClient,为每次调用创建 HttpRequest,再选择同步 send 或异步 sendAsync。连接超时配置在客户端,请求级超时配置在请求对象。
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(3))
.followRedirects(HttpClient.Redirect.NORMAL)
.build();
HttpRequest request = HttpRequest.newBuilder(uri)
.timeout(Duration.ofSeconds(5))
.header("Accept", "application/json")
.GET()
.build();这是片段示例,依赖 java.net.URI、java.net.http.* 和 java.time.Duration。connectTimeout 只限制建连阶段,request.timeout 设置请求级等待上限。
同步与异步请求
下面的程序先启动本地测试服务,再分别发送同步 GET 和异步 POST,不依赖外部网络。保存为 HttpClientDemo.java 后运行。
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
public class HttpClientDemo {
public static void main(String[] args) throws Exception {
HttpServer server = HttpServer.create(new InetSocketAddress(0), 0);
server.createContext("/sync", exchange -> {
byte[] body = "sync-ok".getBytes(StandardCharsets.UTF_8);
exchange.sendResponseHeaders(200, body.length);
exchange.getResponseBody().write(body);
exchange.close();
});
server.createContext("/async", exchange -> {
String requestBody = new String(
exchange.getRequestBody().readAllBytes(),
StandardCharsets.UTF_8
);
byte[] body = ("received:" + requestBody).getBytes(StandardCharsets.UTF_8);
exchange.sendResponseHeaders(201, body.length);
exchange.getResponseBody().write(body);
exchange.close();
});
server.start();
int port = server.getAddress().getPort();
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(3))
.build();
HttpRequest syncRequest = HttpRequest.newBuilder(
URI.create("http://127.0.0.1:" + port + "/sync"))
.timeout(Duration.ofSeconds(5))
.GET()
.build();
HttpResponse<String> syncResponse = client.send(
syncRequest,
HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)
);
System.out.println("sync=" + syncResponse.statusCode()
+ ", body=" + syncResponse.body());
HttpRequest asyncRequest = HttpRequest.newBuilder(
URI.create("http://127.0.0.1:" + port + "/async"))
.timeout(Duration.ofSeconds(5))
.header("Content-Type", "text/plain; charset=UTF-8")
.POST(HttpRequest.BodyPublishers.ofString(
"hello",
StandardCharsets.UTF_8
))
.build();
HttpResponse<String> asyncResponse = client.sendAsync(
asyncRequest,
HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)
).join();
System.out.println("async=" + asyncResponse.statusCode()
+ ", body=" + asyncResponse.body());
server.stop(0);
}
}编译并运行:
javac --add-modules jdk.httpserver HttpClientDemo.java
java --add-modules jdk.httpserver HttpClientDemo预期输出:
sync=200, body=sync-ok
async=201, body=received:hello读取结果时先判断 statusCode(),再按接口约定处理 body();HTTP 4xx、5xx 不会自动抛出异常,仍会正常返回 HttpResponse。
常用选项
BodyPublishers.noBody()、ofString()、ofFile():构造空请求体、字符串请求体或文件请求体。BodyHandlers.ofString()、ofByteArray()、ofFile():将响应读取为字符串、字节数组或文件。header()追加单个请求头;headers()一次追加多组键值。version(HttpClient.Version.HTTP_2)表示优先使用 HTTP/2,服务端不支持时可能回退。followRedirects()控制 3xx 跳转;默认不自动跟随重定向。
风险与边界
未设置超时时,请求可能因网络半开、服务端无响应而长期占用线程或连接。安全做法是同时设置连接超时和请求超时,并在业务层限制重试次数。
对非幂等 POST 自动重试可能造成重复下单或重复写入。只有接口具备幂等键或明确支持重试时才重发,并记录请求 ID。
异步调用的异常通常由 CompletionException 包装;只调用 join() 而不处理异常,会把网络错误推迟到取结果时暴露。生产代码应使用 exceptionally、handle 或集中异常转换。
不要为每次请求创建新的 HttpClient,否则连接池无法复用,可能增加握手耗时和临时端口压力。一个服务通常按代理、证书或超时策略复用少量客户端实例。
排障清单
- 超时:区分建连超时、请求级超时和上游处理超时。
- 状态异常:打印状态码、响应头和受控长度的响应体,避免日志泄露令牌或敏感数据。
- TLS 失败:检查系统时间、证书链、主机名和 JDK 信任库。
- 异步无结果:确认
CompletableFuture被消费,且进程没有在回调完成前退出。
兼容性速查:HttpClient 从 Java 11 正式可用;示例中的本地测试服务属于 jdk.httpserver 模块,生产客户端本身只需 java.net.http。
URLEncoder.encode(<值>, StandardCharsets.UTF_8) / URLDecoder.decode(<值>, StandardCharsets.UTF_8)
URI uri = URI.create("<URL>"); uri.getPath() / uri.getRawQuery()构造 URI 并正确处理查询参数和字符编码。
处理 URI 与编码
构造带查询参数的 URI 时,只编码参数名和参数值,不要对完整 URL 执行一次整体编码。这样可避免 :, /, ?, &, = 等结构字符被破坏,也能正确保留中文、空格、加号和 &。
编码规则
查询参数常按 UTF-8 编码。URLEncoder 使用表单编码规则,会把空格编码成 +;很多 HTTP 服务可直接识别,但严格要求百分号编码时应将 + 替换为 %20。
不要把已经包含 %E4... 的值再次传入编码函数,否则 % 会变成 %25,形成双重编码。解码也只应执行一次。
构造与读取查询参数
下面的完整示例编码两个参数,构造 URI,再读取并解码参数值。第二个参数故意包含 + 和 &,用于验证它们不会被误当成空格或参数分隔符。
import java.net.URI;
import java.net.URLDecoder;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.stream.Collectors;
public class UriEncodingDemo {
private static String encodeQueryComponent(String value) {
return URLEncoder.encode(value, StandardCharsets.UTF_8)
.replace("+", "%20");
}
private static URI buildUri(String baseUrl, Map<String, String> params) {
String query = params.entrySet().stream()
.map(entry -> encodeQueryComponent(entry.getKey())
+ "=" + encodeQueryComponent(entry.getValue()))
.collect(Collectors.joining("&"));
return URI.create(baseUrl + "?" + query);
}
private static Map<String, String> decodeQuery(URI uri) {
Map<String, String> result = new LinkedHashMap<>();
String rawQuery = uri.getRawQuery();
if (rawQuery == null || rawQuery.isEmpty()) {
return result;
}
for (String pair : rawQuery.split("&")) {
String[] parts = pair.split("=", 2);
String key = URLDecoder.decode(parts[0], StandardCharsets.UTF_8);
String value = parts.length == 2
? URLDecoder.decode(parts[1], StandardCharsets.UTF_8)
: "";
result.put(key, value);
}
return result;
}
public static void main(String[] args) {
Map<String, String> params = new LinkedHashMap<>();
params.put("q", "Java HTTP 客户端");
params.put("tag", "a+b&c");
URI uri = buildUri("https://api.example.com/search", params);
Map<String, String> decoded = decodeQuery(uri);
System.out.println(uri.toASCIIString());
System.out.println("q=" + decoded.get("q"));
System.out.println("tag=" + decoded.get("tag"));
}
}编译并运行:
javac UriEncodingDemo.java
java UriEncodingDemo预期输出:
https://api.example.com/search?q=Java%20HTTP%20%E5%AE%A2%E6%88%B7%E7%AB%AF&tag=a%2Bb%26c
q=Java HTTP 客户端
tag=a+b&c读取 URI 时,getRawQuery() 返回尚未解码的查询串,适合自行拆分;getQuery() 会返回已解码的查询内容,但其中原始分隔符与参数值中的字符可能难以区分,因此解析参数时优先使用 getRawQuery()。
路径与 URI 字段
URI 区分原始值和解码值:
| 方法 | 返回内容 | 常见用途 |
|---|---|---|
toASCIIString() |
非 ASCII 字符转为百分号编码 | 写入 HTTP 请求或日志 |
getRawPath() |
原始编码路径 | 保留 %2F 等编码差异 |
getPath() |
解码后的路径 | 业务读取 |
getRawQuery() |
原始查询串 | 安全拆分参数 |
getFragment() |
# 后片段 |
客户端定位,通常不发送给服务端 |
路径参数不能直接拼接用户输入。例如用户 ID 为 a/b 时,直接拼到 /users/ 后会被解释成两级路径。标准库没有专门的“路径段编码器”,生产项目可使用框架提供的 URI Builder,或对每个路径段采用明确的编码策略后再拼接。
风险与边界
对完整 URL 使用 URLEncoder.encode() 会把协议和分隔符一起编码,结果无法作为正常 URI。安全替代方案是固定基础地址,只编码动态参数名、参数值和独立路径段。
先手工编码再交给会自动编码的 URI Builder,可能触发双重编码,服务端最终收到 %2520。应明确由一层组件负责编码,并用 toASCIIString() 检查最终请求地址。
直接拼接未编码参数会产生参数注入。例如值中包含 &admin=true 时,服务端可能把它解析为新参数。应逐个编码参数名和值,并限制允许的目标主机,避免把用户输入直接当作完整 URL。
URLDecoder 会把 + 解码为空格;只有原始加号编码为 %2B 时才能无损还原。不要用它解码完整路径或完整 URL。
排障清单
- 中文乱码:客户端和服务端统一使用 UTF-8,并检查是否重复解码。
%25增多:通常是已经编码的内容再次编码。- 参数被截断:检查值中的
&、=是否逐项编码。 - 空格变成
+:确认服务端是否采用表单查询规则;严格 URI 场景改用%20。 - 签名不一致:签名前固定参数排序、编码规则和是否使用原始查询串。
速查原则:URI 结构由程序控制,动态数据按组件编码;编码一次,解码一次。
Process process = new ProcessBuilder(List.of("<命令>", "<参数>")).directory(<目录>).redirectErrorStream(true).start();
int exitCode = process.waitFor();使用 ProcessBuilder 执行命令并读取输出和退出状态。
启动外部进程
用于从 Java 调用系统命令或其他程序,并可靠取得标准输出、错误输出和退出码。生产代码应同时处理输出读取、超时和进程回收,避免子进程卡死或长期占用资源。
命令定位
ProcessBuilder 适合参数可控、需要设置工作目录或环境变量、还要检查退出状态的场景。命令和参数应拆成独立字符串传入;只有确实需要管道、重定向或通配符时才调用 shell。
高频用法
下面示例兼容 Windows 与 Linux/macOS:启动命令、合并错误流、异步读取输出,并为进程设置 5 秒超时。
import java.io.BufferedReader;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;
public class ProcessBuilderDemo {
public static void main(String[] args) throws Exception {
List<String> command = isWindows()
? List.of("cmd.exe", "/d", "/s", "/c", "echo process-ok")
: List.of("sh", "-c", "printf 'process-ok\n'");
ProcessBuilder builder = new ProcessBuilder(command);
builder.redirectErrorStream(true); // 合并 stderr,避免两条流互相阻塞
Process process = builder.start();
ExecutorService readerPool = Executors.newSingleThreadExecutor();
try {
Future<String> outputFuture = readerPool.submit(() -> {
try (BufferedReader reader =
process.inputReader(StandardCharsets.UTF_8)) {
return reader.lines()
.collect(Collectors.joining(System.lineSeparator()));
}
});
boolean finished = process.waitFor(5, TimeUnit.SECONDS);
if (!finished) {
process.destroy();
if (!process.waitFor(1, TimeUnit.SECONDS)) {
process.destroyForcibly();
}
throw new IllegalStateException("process timeout");
}
String output = outputFuture.get(1, TimeUnit.SECONDS);
System.out.println("output: " + output);
System.out.println("exitCode: " + process.exitValue());
} finally {
readerPool.shutdownNow();
}
}
private static boolean isWindows() {
return System.getProperty("os.name")
.toLowerCase()
.contains("win");
}
}编译并运行:
javac ProcessBuilderDemo.java
java ProcessBuilderDemo预期输出:
output: process-ok
exitCode: 0exitCode 为 0 通常表示成功,非零值的具体含义由被调用程序定义。实际输出中的路径、时间、进程号等动态内容可能不同,应按该程序的文档解释。
常用设置
| 设置 | 什么时候用 | 生效行为 |
|---|---|---|
directory(File) |
子进程必须在指定目录执行 | 修改子进程工作目录,不修改当前 JVM 目录 |
environment() |
需要补充或覆盖环境变量 | 只影响新进程;删除键可移除继承变量 |
redirectErrorStream(true) |
输出量不大且无需区分错误流 | 将 stderr 合并到 stdout,降低双流阻塞风险 |
redirectOutput(File) |
输出很大或无需实时处理 | 直接写文件,减少 JVM 内存和读取线程压力 |
inheritIO() |
命令行工具需要直接复用当前终端 | 子进程输入输出连接到当前 Java 进程控制台 |
风险与边界
- 当用户输入被拼接进
sh -c或cmd /c时,可能触发命令注入并执行任意指令。安全做法是跳过 shell,使用new ProcessBuilder("program", "arg1", userValue)分离程序与参数,并对允许值做白名单校验。 - 当 stdout 或 stderr 持续写满系统管道而父进程未读取时,子进程可能阻塞,
waitFor()也会一直等待。应并发消费两条流、合并错误流,或重定向到文件。 - 当外部程序无响应且没有超时控制时,请求线程和系统进程可能长期堆积。应使用带超时的
waitFor,先destroy(),仍未退出再destroyForcibly()。 - 当命令依赖 shell 内建语法、PATH、字符集或当前目录时,不同系统结果可能不同。应使用绝对程序路径、明确工作目录和字符集,并分别在目标操作系统验证。
排障清单
- 出现“找不到文件”时,先打印命令列表并确认第一个元素是可执行文件,而不是整条带空格的命令。
- 进程不退出时,检查是否未读取输出、是否仍等待标准输入,以及超时后是否真正回收子进程。
- 输出乱码时,确认子进程编码与
inputReader使用的字符集一致;Windows 控制台程序不一定使用 UTF-8。 - 非零退出码时,同时保留错误输出、完整参数和工作目录,但日志中不要记录密码、令牌或私钥。
速查原则:参数优先分开传递,输出必须被消费,等待必须有超时,退出码必须检查。
创建线程、设置名称并控制启动、中断和等待。
创建与管理线程
需要后台执行并能等待其结束时,给线程命名、调用一次 start,并设计协作退出条件。中断是请求,代码必须在阻塞处或循环内响应它,不能依赖强制终止释放资源。
关键方法
| 调用 | 作用与边界 |
|---|---|
new Thread(Runnable, String) |
创建尚未启动的平台线程 |
start() |
开始运行;同一线程对象只能调用一次 |
interrupt() |
设置中断状态或使可中断阻塞抛异常 |
join() |
等待结束;调用方也可能被中断 |
isInterrupted() |
读取状态,不清除 |
Thread.interrupted() |
读取并清除当前线程状态 |
直接调用 run() 只是在当前线程执行普通方法。Java 21 也提供虚拟线程,但它不会让 CPU 密集计算自动加速;下面用平台线程展示所有权和关闭流程。
可控中断示例
保存为 ThreadLifecycle.java。锁存器确保子线程已进入任务,再由主线程发出中断,避免靠随机睡眠猜测时序。
import java.util.concurrent.CountDownLatch;
public class ThreadLifecycle {
public static void main(String[] args) throws InterruptedException {
CountDownLatch ready = new CountDownLatch(1);
Thread worker = new Thread(() -> {
ready.countDown();
try {
Thread.sleep(60_000); // 模拟可中断阻塞,不必真等一分钟
} catch (InterruptedException ex) {
Thread.currentThread().interrupt(); // 保留退出信号
System.out.println("interrupted");
} finally {
System.out.println("cleanup");
}
}, "demo-worker");
worker.start();
ready.await();
worker.interrupt();
worker.join(); // 结束后才能安全核对最终状态
System.out.println("alive=" + worker.isAlive());
}
}预期结果:立即响应中断并完成清理,无需等待 60 秒。运行:
javac ThreadLifecycle.java
java ThreadLifecycle预期输出:
interrupted
cleanup
alive=false停止与恢复边界
sleep、wait、join 抛出 InterruptedException 时会清除中断状态。不能向上抛出时,恢复状态并退出当前工作;捕获后继续死循环会吞掉关闭请求。计算循环需要定期检查状态,普通 synchronized 锁竞争不能通过 interrupt 立即退出。
不要使用已废弃的 Thread.stop,它可能在对象状态更新到一半时释放锁。线程不能重启;业务需要重试时创建新任务并确保副作用可重入。服务关闭可用带超时的 join,超时后 isAlive 仍可能为真,应记录未完成任务和处置策略,不能假装线程已经停止。