Java API 详细参考文档

基于 Java 17 LTS，涵盖 java.lang、java.util、java.time、java.io 等核心包

1. String 类

java.lang.String — 不可变字符序列，UTF-16 编码。

1.1 构造方法

1.2 长度与判空

String s = "  ";
s.length();      // 2
s.isEmpty();     // false
s.isBlank();     // true

1.3 字符/字节访问

1.4 比较

"abc".compareTo("abd");   // -1
"abc".compareTo("abc");   // 0
"abc".compareTo("abb");   // 1

1.5 查找

"hello world".indexOf('o');       // 4
"hello world".indexOf('o', 5);    // 7
"hello world".lastIndexOf('o');   // 7
"hello world".contains("wo");     // true
"hello world".startsWith("he");   // true
"hello world".endsWith("ld");     // true

1.6 提取子串

"hello".substring(1);      // "ello"
"hello".substring(1, 4);   // "el"

1.7 替换

"a,b,c".replace(',', '-');          // "a-b-c"
"a,b,c".replaceAll("[a-c]", "x");   // "x,x,x"
"a,b,c".replaceFirst(",", ";");     // "a;b,c"

1.8 大小写转换

1.9 去除空白

1.10 分割与连接

"a,b,c".split(",");                  // ["a", "b", "c"]
"a,b,c".split(",", 2);               // ["a", "b,c"]
String.join("-", "2024", "01", "01"); // "2024-01-01"

1.11 格式化

String.format("Hello, %s! You have %d messages.", "Alice", 3);
// "Hello, Alice! You have 3 messages."

"Age: %d".formatted(25);  // "Age: 25"

常用格式说明符：

1.12 其他方法

"Abc".repeat(3);               // "AbcAbcAbc"
"abc".intern();
"a\nb\nc".lines().count();     // 3
"123".matches("\\d+");         // true
String.valueOf(123);           // "123"
String.valueOf(true);          // "true"

valueOf 重载：boolean, char, char[], char[],offset,count, double, float, int, long, Object

2. StringBuilder / StringBuffer

2.1 构造方法

new StringBuilder();               // 初始容量 16
new StringBuilder(int capacity);   // 指定初始容量
new StringBuilder(String str);     // 初始内容为 str，容量 = str.length() + 16
new StringBuilder(CharSequence cs);

2.2 常用方法

StringBuilder sb = new StringBuilder("hello");
sb.append(" world")               // "hello world"
  .insert(5, ",")                 // "hello, world"
  .delete(5, 6)                   // "hello world"
  .reverse();                     // "dlrow olleh"

3. 包装类 (Wrapper Classes)

3.1 概览

3.2 通用方法

以 Integer 为例：

int n = Integer.parseInt("42");           // 42
int n2 = Integer.parseInt("ff", 16);      // 255
Integer i = Integer.valueOf(127);         // 缓存对象
Integer j = Integer.valueOf(127);         // 同一对象 (i == j)
String hex = Integer.toHexString(255);    // "ff"
int max = Integer.MAX_VALUE;              // 2147483647

3.3 Character 类特有方法

3.4 自动装箱/拆箱

Integer a = 100;        // 自动装箱 → Integer.valueOf(100)
int b = a;              // 自动拆箱 → a.intValue()
Integer c = null;
int d = c;              // NullPointerException!

4. Math 类

java.lang.Math — 基本数学运算。全部为静态方法。

4.1 常量

4.2 取舍与近似

Math.ceil(3.14);   // 4.0
Math.floor(3.14);  // 3.0
Math.round(3.5);   // 4
Math.round(3.4);   // 3
Math.rint(2.5);    // 2.0  (偶数偏好)
Math.rint(3.5);    // 4.0  (偶数偏好)

4.3 最值

4.4 幂、根、对数

Math.pow(2, 10);    // 1024.0
Math.sqrt(16);      // 4.0
Math.cbrt(27);      // 3.0
Math.log(Math.E);   // 1.0
Math.log10(100);    // 2.0

4.5 三角函数

所有角度参数单位为弧度：

4.6 随机数与符号

Math.random();                       // 0.0 ~ 0.999...
int dice = (int)(Math.random() * 6) + 1;  // 1 ~ 6
Math.floorMod(-1, 5);                // 4 (而 -1 % 5 = -1)
Math.multiplyExact(Integer.MAX_VALUE, 2); // throws ArithmeticException

5. Arrays 工具类

java.util.Arrays — 数组操作工具类。

5.1 排序

int[] arr = {3, 1, 4, 1, 5};
Arrays.sort(arr);                          // [1, 1, 3, 4, 5]
Arrays.sort(strArr, Comparator.reverseOrder());

5.2 查找

int[] arr = {1, 3, 5, 7, 9};
int idx = Arrays.binarySearch(arr, 5);     // 2
int idx2 = Arrays.binarySearch(arr, 4);    // -3 (插入点为索引2，-2-1 = -3)

5.3 比较与填充

5.4 转换

String[] strs = {"a", "b", "c"};
List<String> list = Arrays.asList(strs);
list.set(0, "x");        // OK, 数组同步变为 ["x", "b", "c"]
list.add("d");           // UnsupportedOperationException! 固定大小

int[] copy = Arrays.copyOf(new int[]{1,2,3}, 5);   // [1, 2, 3, 0, 0]
int[] range = Arrays.copyOfRange(new int[]{1,2,3,4,5}, 1, 4); // [2, 3, 4]

6. ArrayList

java.util.ArrayList<E> — 基于数组的动态列表，随机访问 O(1)，插入/删除 O(n)。

6.1 构造方法

new ArrayList<>();                   // 默认容量 10
new ArrayList<>(int initialCapacity);
new ArrayList<>(Collection<? extends E> c);

6.2 增删改查

list.remove(1);       // 按索引
list.remove(Integer.valueOf(1));  // 按值
list.removeIf(s -> s.startsWith("A"));

6.3 查询

6.4 迭代与转换

// 转数组推荐写法
String[] arr = list.toArray(new String[0]);

// subList 陷阱
List<Integer> sub = list.subList(0, 3);
sub.clear();  // 原 list 的前 3 个元素也被删除！

6.5 其他

7. LinkedList

java.util.LinkedList<E> — 双向链表。实现了 List<E> 和 Deque<E>。

7.1 Deque 方法（用作栈/队列）

// 作为栈 (LIFO)
LinkedList<String> stack = new LinkedList<>();
stack.push("a");          // addFirst
stack.push("b");
stack.pop();              // "b" (removeFirst)

// 作为队列 (FIFO)
LinkedList<String> queue = new LinkedList<>();
queue.offer("a");         // addLast
queue.offer("b");
queue.poll();             // "a" (removeFirst)

8. HashSet

java.util.HashSet<E> — 基于 HashMap 的集合，O(1) 增删查，无序。

构造时可传入 initialCapacity 和 loadFactor。

注意：自定义对象存入 HashSet 必须正确重写 equals() 和 hashCode()。

9. HashMap

java.util.HashMap<K, V> — 哈希表实现，键值对，O(1) 增删查。

9.1 构造方法

new HashMap<>();                          // 默认容量 16，负载因子 0.75
new HashMap<>(int initialCapacity);
new HashMap<>(int initialCapacity, float loadFactor);
new HashMap<>(Map<? extends K, ? extends V> m);

9.2 增删改查

9.3 查询

9.4 迭代

// 推荐遍历方式
for (Map.Entry<K, V> entry : map.entrySet()) {
    K key = entry.getKey();
    V value = entry.getValue();
}

// Lambda 遍历
map.forEach((k, v) -> System.out.println(k + " = " + v));

9.5 计算

// 计数
map.merge(word, 1, Integer::sum);

// 分组
map.computeIfAbsent(key, k -> new ArrayList<>()).add(item);

9.6 Map.Entry 方法

10. Stream API

java.util.stream.Stream<T> — 函数式流操作。

10.1 创建流

// 从集合
collection.stream();
collection.parallelStream();

// 从数组
Arrays.stream(arr);
Stream.of(array);

// 直接创建
Stream.of("a", "b", "c");
Stream.iterate(0, n -> n + 1);              // 无限流
Stream.iterate(0, n -> n < 100, n -> n + 1); // 有限流（Java 9+）
Stream.generate(Math::random);              // 无限流
Stream.<String>builder().add("a").add("b").build();

// 基本类型流（避免装箱）
IntStream.range(1, 10);       // [1, 10)
IntStream.rangeClosed(1, 10); // [1, 10]
LongStream, DoubleStream 同理

10.2 中间操作（惰性，返回 Stream）

10.3 终端操作

基本类型流特有：

10.4 Collectors 常用方法

java.util.stream.Collectors

// 分组计数
Map<String, Long> count = list.stream()
    .collect(Collectors.groupingBy(Function.identity(), Collectors.counting()));

// 分组为 List
Map<String, List<Item>> groups = items.stream()
    .collect(Collectors.groupingBy(Item::getCategory));

// toMap 冲突处理
Map<Integer, String> map = items.stream()
    .collect(Collectors.toMap(Item::getId, Item::getName, (old, n) -> old));

// joining
String result = list.stream().collect(Collectors.joining(", ", "[", "]"));
// "[a, b, c]"

// teeing（同时求平均分和总分）
record Stats(double avg, int sum) {}
Stats stats = scores.stream()
    .collect(Collectors.teeing(
        Collectors.averagingInt(Integer::intValue),
        Collectors.summingInt(Integer::intValue),
        Stats::new
    ));

11. Optional 类

java.util.Optional<T> — 容器对象，避免空指针。

11.1 创建

Optional<String> opt = Optional.of("hello");
Optional<String> empty = Optional.empty();
Optional<String> nullable = Optional.ofNullable(maybeNull);

11.2 获取值

// 推荐
String s = opt.orElse("default");
String s2 = opt.orElseGet(() -> computeDefault());   // 惰性，无值时再计算
String s3 = opt.orElseThrow(() -> new IllegalArgumentException("missing"));

11.3 判断

11.4 转换与过滤

// 链式调用
String result = Optional.ofNullable(user)
    .map(User::getAddress)
    .map(Address::getCity)
    .filter(city -> !city.isBlank())
    .orElse("Unknown");

// ifPresentOrElse
opt.ifPresentOrElse(
    v -> System.out.println("Found: " + v),
    () -> System.out.println("Not found")
);

12. Collections 工具类

java.util.Collections — 集合操作工具类。

12.1 排序与搜索

12.2 同步与不可变包装

12.3 其他

13. LocalDate / LocalTime / LocalDateTime

java.time.* — Java 8+ 日期时间 API。

13.1 创建

// 当前时间
LocalDate.now();                          // 当前日期
LocalTime.now();                          // 当前时间
LocalDateTime.now();                      // 当前日期时间
ZonedDateTime.now();                      // 带时区
Instant.now();                            // UTC 时间戳

// 指定值
LocalDate.of(2024, 1, 15);                // 2024-01-15
LocalTime.of(14, 30, 0);                  // 14:30:00
LocalDateTime.of(2024, 1, 15, 14, 30, 0);

// 解析
LocalDate.parse("2024-01-15");
LocalTime.parse("14:30:00");
LocalDateTime.parse("2024-01-15T14:30:00");

// 自定义格式
DateTimeFormatter fmt = DateTimeFormatter.ofPattern("yyyy/MM/dd");
LocalDate.parse("2024/01/15", fmt);

13.2 LocalDate 常用方法

13.3 Timeline 常用方法

13.4 LocalDateTime

LocalDateTime 是 LocalDate + LocalTime 的组合，两边的操作都支持：

LocalDateTime dt = LocalDateTime.now();
dt.toLocalDate();      // 提取日期部分
dt.toLocalTime();      // 提取时间部分
dt.atZone(ZoneId.systemDefault());    // 添加时区 → ZonedDateTime
dt.toInstant(ZoneOffset.UTC);         // 转 UTC Instant

13.5 TemporalAdjusters 常用调节器

import static java.time.temporal.TemporalAdjusters.*;

localDate.with(firstDayOfMonth());        // 当月第一天
localDate.with(lastDayOfMonth());         // 当月最后一天
localDate.with(firstDayOfNextMonth());    // 下月第一天
localDate.with(firstDayOfYear());         // 当年第一天
localDate.with(lastDayOfYear());          // 当年最后一天
localDate.with(next(DayOfWeek.MONDAY));   // 下一个周一
localDate.with(previous(DayOfWeek.MONDAY)); // 上一个周一
localDate.with(dayOfWeekInMonth(2, DayOfWeek.MONDAY)); // 本月第二个周一

13.6 DateTimeFormatter 常用模式

DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");  // 2024-01-15 14:30:00
DateTimeFormatter.ofPattern("yyyy年MM月dd日 E");      // 2024年01月15日 星期一
DateTimeFormatter.ISO_LOCAL_DATE;                    // 2024-01-15

13.7 Duration 与 Period

Duration d = Duration.ofMinutes(30);
Duration.between(Instant t1, Instant t2).toMillis();

Period p = Period.ofMonths(3);
Period.between(date1, date2).getDays();

14. File / Path / Files

java.io.File（旧）和 java.nio.file.*（Java 7+ NIO.2）。

14.1 Path 创建

Path p = Path.of("/home", "user", "doc.txt");        // Java 11+
Path p = Paths.get("/home", "user", "doc.txt");       // Java 7+
Path p = Path.of("/home/user/doc.txt");
Path p = Path.of("docs").resolve("readme.md");        // docs/readme.md
Path p = Path.of(".").toAbsolutePath().normalize();   // 规范化绝对路径

14.2 Files 常用静态方法

文件/目录检查

读/写

// 简洁读写
String content = Files.readString(Path.of("file.txt"));
Files.writeString(Path.of("file.txt"), "Hello World");

// try-with-resources 流式读取
try (Stream<String> lines = Files.lines(Path.of("large.txt"))) {
    lines.filter(s -> s.startsWith("ERROR")).forEach(System.out::println);
}

目录与文件操作

// 同时复制内容、属性和覆盖
Files.copy(src, dest, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.COPY_ATTRIBUTES);

// 查找目录下所有 .java 文件
try (Stream<Path> walk = Files.walk(Path.of("src"))) {
    walk.filter(p -> p.toString().endsWith(".java")).forEach(System.out::println);
}

文件属性

Map<String, Object> attrs = Files.readAttributes(path, "size,lastModifiedTime,isDirectory");
long size = (long) attrs.get("size");

14.3 旧 File 类（兼容参考）

15. Objects 工具类

java.util.Objects — Object 静态工具类。

Objects.equals(null, null);          // true
Objects.hash("a", 1, null);          // 安全哈希
Objects.toString(obj, "N/A");        // 空值友好
Objects.requireNonNull(param, "param must not be null");

参考资料

• Java 17 API Specification
• 本文格式说明：返回值 列中标记 static 表示静态方法；返回值为 this 表示返回当前实例（支持链式调用）。

本文档于 2026/05 基于 Java 17 LTS 整理。