Java API 与帮助文档

API(Application Programming Interface,应用程序编程接口),可以简单理解为别人已经提供好的功能,我们学会调用,就能在自己的程序里使用。比如之前接触过的 String、Random、Scanner,都是 Java API 中的常见类。

Java API 包含 Java 平台提供的类、接口以及各种方法。很多功能的实现已经封装好了,我们主要需要弄清楚:这个类能做什么、怎样创建对象、有哪些方法,以及方法需要什么参数、会返回什么结果。

遇到不熟悉的类或方法,可以查 API 帮助文档。我写这篇笔记时找到了一个 中文 JDK 帮助文档,也可以使用 Oracle 官方 Java API 文档(JDK 21)。中文文档的部分内容对应较早的 JDK 版本,如果遇到版本差异,可以到官方文档中核对。

例如,打开 String 类的文档,就可以看到它的构造方法、成员方法等内容。String 位于 java.lang 包,这个包中的类可以直接使用,通常不需要自己写 import。

试着用文档解决一个问题

之前我们通过 Scanner 读取整数,用的是 nextInt()。如果现在想读取小数,该怎么办?

既然会用 nextInt(),不妨照猫画虎,到 Scanner 的方法列表里找找有没有读取小数的方法。查一下就会发现 nextDouble(),它可以读取 double 类型的数据。于是把原来的 nextInt() 换成 nextDouble(),其他部分照着写就可以了。

java
import java.util.Scanner;
public class Test1 {
    public static void main(String[] args) {
        Scanner sc = new Scanner(System.in);
        double a=sc.nextDouble();
        System.out.println(a);
    }
}

例如输入 3.14,程序就会读取这个小数,再把它打印出来。以后遇到陌生的方法,也可以先查文档,再写一段小代码试试。

String:字符串

java.lang.String 类用于表示字符串。Java 程序中写出的字符串字面量,例如 "abc"、"hello",都是 String 类型。

String 有一个很重要的特点:字符串对象的内容不可变。 比如把两个字符串拼接起来,看起来像是在原来的字符串后面添加内容,实际上得到的是一个新的字符串结果,原来的字符串对象没有被直接修改。

创建 String 对象的两种方式

常见的创建方式有两种:

  1. 直接赋值:String s = "helloworld";
  2. 使用 new:通过 String 的构造方法创建对象。

String 有多种构造方法,先记住下面几个:

构造方法作用
String()创建一个空字符串,内容为 ""
String(String original)根据已有字符串的内容创建新的字符串对象
String(char[] value)将字符数组中的字符组成字符串
String(byte[] bytes)使用默认字符集解码字节数组,得到字符串

可以直接看代码,每种方式都写了一个例子:

java
public class Test1 {
    public static void main(String[] args) {
        //直接赋值获取一个字符串对象
        String s1 = "abcd";
        System.out.println(s1);//abcd
        //使用new关键字获取一个字符串对象
        //空参构造:可以获取一个空白的字符串对象
        String s2 = new String();
        System.out.println(s2);//空白
        //传递一个字符串,根据传递的内容创建一个新的字符串
        //完全没必要,直接赋值更方便。
        String s3 = new String("helloworld");
        System.out.println(s3);//helloworld
        //传递一个字符数组,根据字符数据的内容创建一个新的字符串
        char[] chs = { 'a', 'b', 'c' };
        String s4 = new String(chs);
        System.out.println(s4);//abc
        //传递一个字节数组,根据字节数组的内容创建一个新的字符串
        byte[] bytes = { 65, 66, 67 };
        String s5 = new String(bytes);//根据ASCII表,查找数字对应的字符然后拼接。
        System.out.println(s5);//ABC
    }
}

最后一个例子比较有意思。我们知道 ASCII 编码中 65、66、67 分别对应 A、B、C,所以在常见的兼容 ASCII 的字符集下会输出 ABC。准确地说,String(byte[]) 是按照字符集对字节进行解码;当字节不再是这些简单的英文字符时,就需要留意所使用的字符集。

另外,new String() 打印出来是一行空白,因为它创建的是空字符串,不是因为没有创建对象。

平时如果已经知道字符串的内容,直接赋值最简单,例如 String s = "hello";。使用 new String("hello") 也能得到相同内容,但通常没有必要额外创建一个对象。

两种创建方式在内存中的区别

直接赋值和使用 new,还涉及一个叫字符串常量池(也叫字符串池、StringTable)的知识点。

java
public class Test1 {
    public static void main(String[] args) {
        String s1 = "hello";
        String s2 = "hello";
    }
}

这里可以这样理解:当程序使用字面量 "hello" 时,会得到字符串池中与它对应的对象;下一次又用到同样的字面量,就可以直接复用这个对象,所以 s1 和 s2 指向同一个字符串对象。

但如果写成 new String("hello"),情况就不一样了:它会创建一个新的 String 对象。虽然内容仍是 "hello",却不是上面复用的那个对象。

注意,这里的区别是有没有复用同一个字符串对象,而不是简单地认为“字符串池里的对象不在堆中”。现阶段先理解对象复用,具体的 JVM 内存实现可以以后再研究。

字符串的比较:== 和 equals()

字符串应该怎么比较呢?先看下面这段代码,两个字符串都是 "hello",你觉得会输出什么?

java
public class Test1 {
    public static void main(String[] args) {
        String s1 = "hello";
        String s2 = new String("hello");
        System.out.println(s1 == s2);
    }
}

输出结果是 false。这就要回到 == 的含义了:

  • 基本数据类型使用 ==,比较的是两个值是否相等。例如 10 == 20,结果就是 false。
  • 引用数据类型使用 ==,比较的是两个引用是否指向同一个对象。

上面 s1 指向复用的字符串对象,s2 指向 new 创建的新对象。内容虽然相同,但不是同一个对象,所以结果为 false。即使 new 两次、两个对象的内容完全一样,使用 == 比较也会得到 false。

如果我们真正想知道的是两个字符串的内容是否一样,就需要使用字符串提供的方法:

方法作用
equals(Object anObject)比较字符串内容是否一致,区分大小写
equalsIgnoreCase(String anotherString)比较字符串内容是否一致,忽略大小写

比如判断两个字符串的内容是否完全相同,可以使用 equals()。如果某个验证码的规则允许不区分大小写,那么比较用户输入的验证码时,就可以考虑 equalsIgnoreCase()。

java
public class Test1 {
    public static void main(String[] args) {
        String s1 = "hello";
        String s2 = new String("hello");
        System.out.println(s1.equals(s2));//true
        String s3 = "Hello";
        System.out.println(s1.equals(s3));//false
        System.out.println(s1.equalsIgnoreCase(s3));//true
    }
}

这样就很清楚了:s1 和 s2 虽然不是同一个对象,但它们的内容一样,所以 equals() 返回 true;"hello" 和 "Hello" 大小写不同,equals() 返回 false,而 equalsIgnoreCase() 返回 true。

StringBuilder:可变的字符串容器

String 的内容不能直接修改。如果我们需要反复拼接字符串,就可能遇到效率问题。

比如想把 "a"、"b"、"c" 依次拼起来,假设每一步都单独执行:先用 "a" 和 "b" 拼成 "ab",再拿 "ab" 和 "c" 拼成 "abc"。第一次拼接得到的 "ab" 就是中间结果,第二次又会得到新的 "abc"。

如果继续往后加 "d"、"e",一直加到 "z",每一步都可能产生新的字符串结果。拼接次数很多时,这些中间对象的创建就会带来额外开销。

这时候可以把 StringBuilder 理解成一个内容能不断追加、修改的容器。我们把 "a" 放进去,再放 "b"、"c",一直往里面添加就行;处理完成后,再得到普通的 String 字符串。这样就可以复用它内部已有的空间,减少反复构造中间字符串。

这里讲的是分多次进行的字符串拼接。如果代码直接写成 "a" + "b" + "c",三个都是常量,编译器可以提前算出结果,后面还会单独看看这种情况。

常见构造方法

构造方法作用
StringBuilder()创建空的 StringBuilder,初始容量为 16
StringBuilder(String str)用已有字符串的内容创建 StringBuilder

常用方法

方法作用
append(内容)在末尾追加内容,并返回当前对象
reverse()将内容反转,并返回当前对象
length()返回当前内容的长度
toString()将当前内容转换为 String

可以把这几个方法放到一起试试:

java
public class Test1 {
    public static void main(String[] args) {
        StringBuilder sb = new StringBuilder();
        // 直接打印为空,我们自己定义的类直接打印是地址值,String和StringBuilder做了一些特殊处理
        System.out.println(sb);
        // 添加多个元素然后打印
        sb.append("a");
        sb.append("b");
        sb.append("c");
        System.out.println(sb);
        // 反转
        sb.reverse();
        System.out.println(sb);
        // 获取长度
        int len = sb.length();
        System.out.println(len);
        // 变回字符串
        String s = sb.toString();
        System.out.println(s);
    }
}

刚创建的 StringBuilder 里面没有内容,所以第一次打印得到空行。添加 a、b、c 后,输出 abc;执行 reverse() 后变成 cba,长度为 3,最后通过 toString() 得到普通的 String。

这里有一个值得注意的地方:我们以前直接打印自己定义的普通类对象,往往会得到 类名@... 这样的结果,为什么打印 StringBuilder 却能看到内容?因为打印对象时会用到它的 toString() 方法,而 StringBuilder 已经实现了这个方法,返回的是当前保存的字符内容。

那既然直接打印就能看到内容,为什么还要手动调用 toString() 呢?因为打印出来和得到一个 String 对象是两回事。比如后面要调用 String 的字符串比较方法,或者把拼接结果交给需要 String 参数的方法,就可以先转换成 String。StringBuilder 虽然也继承了 equals(),但没有重写成按字符串内容比较的版本,因此不能直接用它代替 String.equals()。

链式调用

调用一个方法后,如果这个方法返回了对象,我们还可以接着在返回结果上调用下一个方法,这就是链式调用。

比如想从 "hello,world" 中取出 "world",再把它转换成大写:

java
public class Test1 {
    public static void main(String[] args) {
        String s = "hello,world";
        System.out.println(s.substring(6).toUpperCase());
    }
}

这里先通过 substring(6) 取出 "world",再调用 toUpperCase(),最后输出 WORLD。不需要先定义一个变量接收 "world",再单独写一行转换。

StringBuilder 的 append() 也会返回当前对象,所以可以连续写成 sb.append("a").append("b").append("c"),代码会更简洁。

StringJoiner:带分隔符的字符串拼接

如果想在每个字符串之间加一个固定符号,有没有更省事的办法?还真有,StringJoiner 就是为这种场景准备的。

它可以像 StringBuilder 一样逐步添加内容,同时自动在元素之间加分隔符,还可以给整个结果设置开头和结尾。StringJoiner 从 JDK 8 开始提供。

构造方法

构造方法作用
StringJoiner(CharSequence delimiter)指定每个元素之间的分隔符
StringJoiner(CharSequence delimiter, CharSequence prefix, CharSequence suffix)除分隔符外,还能指定整个字符串的前缀和后缀

比如只需要把 aaa、bbb、ccc 用 --- 连起来,就用第一种构造方法;如果想得到 [1,2,3] 这样的形式,就用第二种,在元素之间加逗号,再给整个结果添加 [ 和 ]。

常用方法

方法作用
add(CharSequence newElement)添加一个元素,并返回当前 StringJoiner
length()获取当前拼接结果的长度
toString()获取拼接后的字符串
java
import java.util.StringJoiner;
public class Test1 {
    public static void main(String[] args) {
        StringJoiner sj1 = new StringJoiner("---");
        sj1.add("aaa").add("bbb").add("ccc");
        System.out.println(sj1);//aaa---bbb---ccc
        StringJoiner sj2 = new StringJoiner(",", "[", "]");
        sj2.add("1").add("2").add("3");
        System.out.println(sj2);//[1,2,3]
        System.out.println(sj2.toString());//[1,2,3]
    }
}

这里的 add() 同样可以链式调用,连续添加多个元素。我们不用手动在每个元素之间拼接 --- 或 ,,StringJoiner 会按照创建对象时指定的规则处理。

学到这里,可以先简单区分这三个类:

  • String:用来表示字符串,创建后的内容不可变,也提供许多操作字符串的方法。
  • StringBuilder:内容可变,适合反复追加、修改或者反转字符串。
  • StringJoiner:侧重于把多个元素按指定分隔符拼接起来,还能加前缀和后缀。

字符串的几个底层原理

前面已经知道了这些类怎么使用。接下来再看看几个细节:为什么常量拼接很快、变量拼接会发生什么,以及 StringBuilder 为什么能减少反复创建对象的开销。

字符串常量拼接

java
public class Test1 {
    public static void main(String[] args) {
        String s = "a" + "b" + "c";
        System.out.println(s);//abc
    }
}

这里的 "a"、"b"、"c" 都是字符串常量,编译器在编译阶段就能确定拼接结果,因此可以直接把表达式处理成 "abc"。运行时没有必要再一步步创建 "ab"、"abc" 这样的中间结果。

带变量的字符串拼接

再看另一段代码:

java
public class Test1 {
    public static void main(String[] args) {
        String s1 = "a";
        String s2 = s1 + "b";
        String s3 = s2 + "c";
        System.out.println(s3);//abc
    }
}

这次就不一样了。s2 = s1 + "b" 要在运行时得到 "ab",接着 s3 = s2 + "c" 又得到 "abc"。由于 String 内容不可变,第二步不会直接修改前一步生成的 "ab",而是产生新的字符串结果。像这样把前一次拼接的结果拿到下一次继续拼接,次数多了就可能产生不少中间对象。

Java 对 + 拼接也做过优化,具体实现和 JDK 版本有关:

  • JDK 8 及更早的常见实现:编译器通常把一次含变量的字符串拼接转换成类似 new StringBuilder().append(...).toString() 的操作。
  • 从 JDK 9 开始:引入了基于 invokedynamic 的拼接机制,可以在运行时采用更灵活的优化策略。

这两种实现都在尽量减少拼接开销。不过,当代码在循环中反复执行 s = s + 一段内容,每次都把新结果赋回去时,仍可能不断产生新的字符串。对于这种需要频繁追加的场景,我们可以自己创建一个 StringBuilder,在循环外保留同一个对象,循环中不断调用 append(),最后统一用 toString() 获取结果。

少量拼接直接写 + 很方便;大量、反复地追加内容时,再考虑 StringBuilder。如果要给每个元素自动加分隔符,就可以选择 StringJoiner。

StringBuilder 为什么能减少中间对象?

StringBuilder 内部维护了一块可以增长的缓冲空间。只要还有足够容量,append() 就能把新内容继续放进去,不需要在每次追加时都重新创建一个完整的 String。

例如,我们创建一个空的 StringBuilder,再添加 "abc":

java
StringBuilder sb = new StringBuilder();
sb.append("abc");

刚创建时,默认容量是 16,里面还没有字符,因此长度是 0。添加 "abc" 后,长度变成 3,但容量仍然是 16,说明还有空间能继续放字符。

这里的两个概念要区分:

  • 长度(length()):现在实际存了多少个字符。
  • 容量(capacity()):当前内部缓冲区最多能容纳多少个字符,超过才需要扩容。

StringBuilder 的容量如何增长?

假如继续添加更多字符,原有容量不够用了,StringBuilder 就会自动扩容。以空参构造出来的对象为例,初始容量为 16,一种常见的扩容计算规则是:

纯文本
新容量 = max(原容量 × 2 + 2, 本次操作所需的最小容量)

这个公式可以拆成两步理解:先算出原容量的两倍再加 2;如果算出的容量仍然放不下要添加的内容,就直接采用本次实际需要的容量。

例如从容量 16 开始,第一次扩容计算得到 16 × 2 + 2 = 34:

  • 一次追加 26 个字符:需要容量 26,而 34 已经够用,所以扩到 34。
  • 一次追加 43 个字符:34 仍然装不下 43 个字符,因此这次直接扩到 43。

下面把几个情况放在一起对比。每一组都从新的空 StringBuilder 开始,而不是在同一个对象上连续追加:

操作内容长度容量
new StringBuilder()016
新对象执行 append("abc")316
新对象一次追加 "abcdefghijklmnopqrstuvwxyz"2634
新对象一次追加长度为 43 的字符串4343

前两次扩容的结果是不是就很直观了?容量是 16,想放 26 个字符,按两倍加 2 扩成 34;想一次放 43 个字符,34 不够,就按实际所需扩成 43。

不过,这里的 34 是从原容量 16 算出来的,并不是所有情况下都固定先扩到 34。例如一个对象已经扩容到 34,之后又需要容纳 43 个字符,那么新一轮计算会变成 34 × 2 + 2 = 70,容量就会扩到 70。每次扩容都要看当时的旧容量。

也可以直接通过 capacity() 观察:

java
StringBuilder sb = new StringBuilder();
System.out.println(sb.capacity()); // 16
sb.append("abcdefghijklmnopqrstuvwxyz");
System.out.println(sb.length());   // 26
System.out.println(sb.capacity()); // 34

因此,StringBuilder 的优势就是有空间时继续使用,空间不够时再扩容。它不需要每添加一个字符就创建一份完整的新字符串,很适合需要持续追加内容的场景。至于 JVM 内部具体用什么数组保存字符,不同 JDK 版本可能有区别,现阶段理解容量和扩容规则就足够了。

谢谢你读到这里。 ✧

聊两句

评论审核后显示

有疑问、补充,或者想交流一下,都可以写在这里。

评论区将在滚动到这里时加载。