Java / 知识点
Java 开发速查手册
手册条目
java -version
javac -version
java -XshowSettings:properties -version 2>&1快速确认当前 Java、Javac 和 JVM 的版本及运行环境。
查看 Java 版本
用于确认终端实际调用的 Java、Javac 与 JVM 运行环境,适合排查“版本不一致”“编译器缺失”或 PATH 指向错误。
基本命令
java -version
javac -version
java -XshowSettings:properties -version 2>&1预期输出
openjdk version "<JAVA_VERSION>" <DATE>
OpenJDK Runtime Environment <VENDOR_BUILD>
OpenJDK 64-Bit Server VM <VENDOR_BUILD>, mixed mode
javac <JAVA_VERSION>
Property settings:
java.home = <PATH>
java.vendor = <VENDOR>
java.version = <JAVA_VERSION>先比较 java -version 与 javac -version 的主版本号;再读取 java.home,确认 JVM 来自预期 JDK。版本、日期、厂商和路径会随安装环境变化。
确认命令来源
Linux 或 macOS 使用:
command -v java
command -v javac预期输出
<PATH>/java
<PATH>/javacWindows PowerShell 使用:
Get-Command java | Select-Object -ExpandProperty Source
Get-Command javac | Select-Object -ExpandProperty Source预期输出
<PATH>\java.exe
<PATH>\javac.exe读取路径时重点检查是否命中旧 JDK、JRE、SDK 管理器目录或系统占位程序,而不是只看版本字符串。
高频判断
java可用但javac不存在:通常只安装了 JRE,或 JDK 的bin未加入 PATH。- 两者主版本不同:PATH 中混入多个 Java 安装目录,编译与运行可能产生兼容性问题。
java.home与命令路径不一致:可能经过符号链接、版本管理器或系统启动器,应继续解析真实路径。- 终端与 IDE 版本不同:分别检查 IDE 的 Project SDK、Gradle JVM 或 Maven Runner JDK。
风险与边界
java -version 输出通常写入标准错误流,脚本采集时若只读取标准输出,可能得到空结果。安全做法是在需要合并输出时使用 2>&1,并同时记录命令路径与 java.home,避免只依据一行版本文本判断。
速查顺序:先看 java -version,再看 javac -version,最后确认命令路径和 java.home。
export JAVA_HOME="<JDK_PATH>"
export PATH="$JAVA_HOME/bin:$PATH"
[Environment]::SetEnvironmentVariable("JAVA_HOME", "<JDK_PATH>", "User") # PowerShell配置 JDK 环境变量并确认命令行使用的 Java 路径。
配置 JAVA_HOME
用于让 Maven、Gradle、应用服务器和脚本稳定定位同一套 JDK。JAVA_HOME 应指向 JDK 根目录,不要指向其 bin 子目录。
Linux 与 macOS
先确认 JDK 根目录。Linux 可从 Java 命令解析,macOS 可使用系统工具:
# Linux:解析当前 java 的真实文件路径
readlink -f "$(command -v java)"
# macOS:返回当前默认 JDK 根目录
/usr/libexec/java_home预期输出
<PATH>/bin/java
<PATH>将实际 JDK 根目录写入当前 Shell 的启动文件,例如 Bash 使用 ~/.bashrc:
export JAVA_HOME="<JDK_PATH>"
export PATH="$JAVA_HOME/bin:$PATH"
source ~/.bashrc
printf '%s\\n' "$JAVA_HOME"
command -v java
java -version预期输出
<JDK_PATH>
<JDK_PATH>/bin/java
openjdk version "<JAVA_VERSION>" <DATE>
OpenJDK Runtime Environment <VENDOR_BUILD>
OpenJDK 64-Bit Server VM <VENDOR_BUILD>, mixed mode使用 Zsh 时写入 ~/.zshrc 并执行 source ~/.zshrc。系统服务不会自动读取个人 Shell 配置,systemd 服务应在单元文件中显式设置环境变量或使用 EnvironmentFile。
Windows PowerShell
下面同时配置当前会话和当前用户的持久变量;新打开的终端才会读取持久 PATH:
$jdk = "<JDK_PATH>"
# 当前 PowerShell 会话立即生效
$env:JAVA_HOME = $jdk
$env:Path = "$env:JAVA_HOME\bin;$env:Path"
# 持久化到当前用户环境
[Environment]::SetEnvironmentVariable("JAVA_HOME", $jdk, "User")
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*%JAVA_HOME%\bin*") {
[Environment]::SetEnvironmentVariable(
"Path",
"%JAVA_HOME%\bin;$userPath",
"User"
)
}
$env:JAVA_HOME
Get-Command java | Select-Object -ExpandProperty Source
java -version预期输出
<JDK_PATH>
<JDK_PATH>\bin\java.exe
openjdk version "<JAVA_VERSION>" <DATE>
OpenJDK Runtime Environment <VENDOR_BUILD>
OpenJDK 64-Bit Server VM <VENDOR_BUILD>, mixed mode验证要点
JAVA_HOME输出为 JDK 根目录,例如<JDK_PATH>,末尾不应是bin。java和javac都应来自$JAVA_HOME/bin或%JAVA_HOME%\bin。- 修改持久环境变量后,重新打开终端、IDE 或构建代理,再执行版本检查。
- Maven 可补充执行
mvn -version,Gradle 可执行gradle -version,确认工具报告的 JVM 路径一致。
风险与边界
直接覆盖整个 PATH 可能导致 Git、Node.js 或系统命令失效。安全做法是仅把 Java 的 bin 前置,并保留原 PATH。配置多个 JDK 时不要反复手工改全局变量,优先使用 SDKMAN、jEnv、asdf 或 IDE 的项目级 JDK 设置,减少不同项目互相影响。
若修改后仍命中旧版本,先关闭并重新打开终端,再检查 PATH 中是否存在更靠前的旧 Java 目录。
javac [编译选项] <SOURCE.java>...
java [运行选项] <MAIN_CLASS> [程序参数...]使用 javac 和 java 编译并运行单文件或多文件程序。
编译运行 Java 程序
javac 把 .java 源文件编译为 JVM 可加载的 .class 字节码,java 再启动 JVM 并调用主类的 main 方法。适合手工验证源码、复现编译错误或检查类路径问题。
基本语法
javac [编译选项] <SOURCE.java>...
java [运行选项] <MAIN_CLASS> [程序参数...]运行已编译程序时填写主类名,不带 .java 或 .class 后缀。类声明了 package 时,必须使用完整类名并让类路径指向包目录的上一级。
单文件编译运行
保存为 Hello.java;文件名必须与 public class Hello 一致。
public class Hello {
public static void main(String[] args) {
String name = args.length > 0 ? args[0] : "World";
System.out.println("Hello, " + name);
}
}在源码所在目录执行:
javac Hello.java
java Hello Anystack预期输出:
Hello, Anystackjavac 成功时通常没有终端输出,并在当前目录生成 Hello.class。Java 11 及以上也可用 java Hello.java Anystack 直接运行源码;该模式主要用于临时验证,不会留下可复用的构建产物。
多文件编译运行
保存下面两个文件。App 调用同目录中的 Greeter,编译结果统一写入 out,避免 .class 文件散落在源码目录。
// Greeter.java
public final class Greeter {
private Greeter() {
}
public static String message(String name) {
return "Hello, " + name;
}
}// App.java
public class App {
public static void main(String[] args) {
String name = args.length > 0 ? args[0] : "World";
System.out.println(Greeter.message(name));
}
}javac -encoding UTF-8 --release 17 -d out Greeter.java App.java
java -cp out App Anystack预期输出:
Hello, Anystack--release 17 同时限制语言级别和目标标准库版本;运行环境也应为 Java 17 或更高。修改源码后应重新编译,否则 java 可能继续运行旧的 .class。
常用参数
| 参数 | 作用 |
|---|---|
javac -d <DIR> |
指定类文件输出目录,并按包名创建子目录 |
javac -encoding UTF-8 |
明确源文件编码,避免不同机器默认编码不一致 |
javac --release <N> |
按指定 Java 版本编译,优先于只设置 -source |
javac -Xlint:all |
显示未检查转换、废弃 API 等编译警告 |
javac -cp <PATH> |
指定编译依赖 |
java -cp <PATH> |
指定运行时类路径;会替换默认类路径 |
java -ea |
启用 assert 断言 |
Linux 和 macOS 的多个类路径用 : 分隔,Windows 用 ; 分隔。依赖较多时优先使用 Maven 或 Gradle 维护类路径,不要手工拼接生产启动命令。
排障清单
class X is public, should be declared in a file named X.java:文件名与公共类名不一致。cannot find symbol:检查拼写、导入、参与编译的源文件及javac -cp。Could not find or load main class:检查当前目录、完整类名以及java -cp是否指向类文件根目录。NoClassDefFoundError:编译时能找到依赖,但运行时类路径缺失。UnsupportedClassVersionError:运行 JDK 低于编译目标;升级运行环境或用匹配的--release重新编译。javac: command not found:当前只有 JRE、JDK 未安装,或 JDK 的bin未加入PATH。
速查原则:先确认 java -version 与 javac -version 来自同一套 JDK,再清理旧输出目录并完整重编译。
jshell [选项]
/help | /vars | /methods | /exit通过 JShell 快速验证语法、表达式和标准库 API。
使用 JShell 快速验证 Java
JShell 是 JDK 自带的交互式 Java REPL,适合立即验证表达式、语法和标准库 API,不必创建类、编写 main 或启动完整项目。
启动与退出
jshell预期输出:
| Welcome to JShell -- Version <VERSION>
| For an introduction type: /help intro
jshell><VERSION> 取决于本机 JDK。输入 /exit 退出;若系统提示找不到命令,先确认安装的是 JDK 9 或更高版本,并检查 JAVA_HOME 与 PATH。
主示例
在 jshell> 提示符后依次输入下列内容。变量声明保留在当前会话中,纯表达式结果会自动保存为 $<ID> 临时变量。
int price = 19;
int count = 3;
price * count
"java".toUpperCase()
/vars
/exit预期输出:
price ==> 19
count ==> 3
$3 ==> 57
$4 ==> "JAVA"
| int price = 19
| int count = 3
| int $3 = 57
| String $4 = "JAVA"
| Goodbye$3、$4 等编号由当前会话中的片段顺序决定,实际编号可能不同。看到 ...> 表示语句尚未闭合,应补全括号、花括号或字符串引号,而不是重复输入整段。
高频用法
- 验证表达式:直接输入算术、字符串、集合或流操作,JShell 会显示类型和值。
- 临时定义方法或类:输入完整方法或类声明,随后直接调用;适合缩小语法或 API 问题。
- 查看会话状态:使用
/vars、/methods、/types、/imports和/list。 - 保存与复用:使用
/save <FILE>保存有效片段,使用/open <FILE>重新载入。
常用命令如下:
| 命令 | 用途 |
|---|---|
/help |
查看 JShell 命令帮助 |
/list |
列出当前会话片段及编号 |
/vars |
查看变量、类型和值 |
/methods |
查看已定义方法 |
/edit |
在配置的编辑器中修改片段 |
/reset |
清空当前会话状态 |
/save <FILE> |
把当前有效片段保存到文件 |
/open <FILE> |
执行文件中的 JShell 片段 |
/exit |
退出 JShell |
依赖与启动选项
验证第三方库时必须把依赖加入类路径;否则会出现 package ... does not exist 或 cannot find symbol。
jshell --class-path "<PATH>"预期结果:
| Welcome to JShell -- Version <VERSION>
| For an introduction type: /help intro
jshell><PATH> 应指向 JAR 或类目录。多个路径在 Linux、macOS 用 : 分隔,在 Windows 用 ; 分隔。会话已启动时可用 /env -class-path <PATH> 更新环境,但环境重载可能使依赖旧类型的片段失效。
常见启动选项包括 --feedback concise 精简回显、--startup <FILE> 加载初始化片段、--no-startup 跳过默认启动定义,以及 --module-path <PATH> 配置模块路径。
风险与边界
JShell 会保留并允许重新定义变量、方法和类型,长会话可能混入旧状态,导致结果无法在干净项目中复现。出现行为异常时先执行 /reset,再按最小步骤重放。
JShell 不支持普通源码中的 package 声明,也不会替代项目构建、单元测试、依赖解析或性能基准。涉及多模块、注解处理、框架启动和并发时序时,应改用最小 Maven/Gradle 工程或自动化测试。
排错时先用 /list -all 检查实际执行过的片段;语法验证通过后,再把代码放回目标 JDK、真实依赖和相同编译参数下确认。
javac -cp <目录或JAR列表> -d <输出目录> <源文件>
java -cp <目录或JAR列表> <完整主类名>通过 classpath 指定类文件、目录和第三方依赖的位置。
设置 Java 类路径
类路径用于告诉 javac 和 java 到哪些目录或 JAR 中查找类。编译时报“程序包不存在”,或运行时报 ClassNotFoundException、NoClassDefFoundError 时,先核对类路径、包名和实际文件位置。
基本语法
javac -cp <目录或JAR列表> -d <输出目录> <源文件>
java -cp <目录或JAR列表> <完整主类名>-cp 是 -classpath 的简写,较新 JDK 也支持 --class-path。Linux、macOS 使用冒号 : 分隔多个条目,Windows 使用分号 ;。目录必须指向包结构的根,而不是最深层的 .class 所在目录。
主示例
下面创建一个工具 JAR,再编译并运行依赖它的主程序。命令适用于 Linux、macOS 和 Git Bash。
set -e
workdir="$(mktemp -d)"
cd "$workdir"
mkdir -p src/com/example/util src/com/example/app build/util build/app lib
cat > src/com/example/util/Message.java <<'EOF'
package com.example.util;
public class Message {
public static String text() {
return "classpath ok";
}
}
EOF
cat > src/com/example/app/Main.java <<'EOF'
package com.example.app;
import com.example.util.Message;
public class Main {
public static void main(String[] args) {
System.out.println(Message.text());
}
}
EOF
# 先生成依赖 JAR,再把它加入编译期和运行期类路径
javac -d build/util src/com/example/util/Message.java
jar --create --file lib/message.jar -C build/util .
javac -cp lib/message.jar -d build/app src/com/example/app/Main.java
java -cp "build/app:lib/message.jar" com.example.app.Main预期输出:
classpath ok读取方法:build/app 提供主类,lib/message.jar 提供 Message。缺少任意一项,程序都无法完成类装载。
常用写法
沿用上例目录,使用环境变量设置默认类路径:
export CLASSPATH="build/app:lib/message.jar"
java com.example.app.Main预期输出:
classpath ok加载某目录下全部 JAR:
java -cp "build/app:lib/*" com.example.app.Main预期输出:
classpath oklib/* 只展开该目录中的 JAR,不递归子目录,也不包含普通 class 目录。Windows 中应把 build/app:lib/message.jar 改成 build\app;lib\message.jar。
风险与边界
命令行中的 -cp 会覆盖环境变量 CLASSPATH,不会自动合并。生产脚本若同时依赖二者,可能漏载依赖;安全做法是只在启动命令中显式声明完整类路径。
类路径按从左到右搜索。同名类存在于多个条目时,前面的版本通常先被加载,可能触发 NoSuchMethodError 或行为漂移。应删除重复依赖,并用 Maven 或 Gradle 检查依赖树。
不要把来源不可信的 JAR 加入类路径;其中代码可能在启动或调用时执行。应固定制品来源、校验摘要,并使用最小权限账户运行。
排障清单
ClassNotFoundException:确认运行命令使用完整类名,例如com.example.app.Main。NoClassDefFoundError:确认编译期依赖也出现在运行期类路径中。- “程序包不存在”:确认
javac -cp指向 JAR 或包结构根目录。 - Windows 可运行、Linux 失败:检查分隔符是否从
;改为:,并核对文件名大小写。 - 使用
java -jar时补充-cp无效:改用清单文件的Class-Path,或使用java -cp指定主类。
jar --create --file <文件.jar> [--main-class <完整主类名>] -C <目录> .
jar --list --file <文件.jar>
java -jar <可执行文件.jar>打包、查看并运行普通 JAR 和可执行 JAR 文件。
创建与运行 JAR
JAR 用于把编译后的类和资源集中成一个文件。普通 JAR 通过 java -cp 指定主类运行;带 Main-Class 清单项的可执行 JAR 可直接用 java -jar 启动。
基本语法
jar --create --file <文件.jar> -C <目录> .
jar --list --file <文件.jar>
java -cp <文件.jar> <完整主类名>
java -jar <可执行文件.jar>-C <目录> . 表示先切换到该目录,再按相对路径写入内容,可避免把构建目录本身带进 JAR。
创建普通 JAR
下面创建源码、编译、打包、查看内容,并通过类路径运行。
set -e
workdir="$(mktemp -d)"
cd "$workdir"
mkdir -p src/com/example out dist
cat > src/com/example/Main.java <<'EOF'
package com.example;
public class Main {
public static void main(String[] args) {
System.out.println("jar ok");
}
}
EOF
javac -d out src/com/example/Main.java
jar --create --file dist/app.jar -C out .
jar --list --file dist/app.jar
java -cp dist/app.jar com.example.Main预期输出:
META-INF/
META-INF/MANIFEST.MF
com/
com/example/
com/example/Main.class
jar ok前几行是 JAR 内部条目,最后一行来自主程序。普通 JAR 即使包含 main 方法,也不能让 java -jar 自动确定入口类。
创建可执行 JAR
沿用上例编译结果,通过 --main-class 写入入口类:
jar --create \
--file dist/app-exec.jar \
--main-class com.example.Main \
-C out .
jar --list --file dist/app-exec.jar
java -jar dist/app-exec.jar预期输出:
META-INF/
META-INF/MANIFEST.MF
com/
com/example/
com/example/Main.class
jar ok最后一行成功出现,说明清单中的 Main-Class 已生效。入口类必须使用完整包名,并且对应 class 文件必须存在于 JAR 中。
常用参数
--create:创建新 JAR;同名文件会被覆盖。--file:指定 JAR 文件名。--main-class:写入可执行入口类。--list:查看条目但不解压。--extract:把内容解压到当前目录。--update:向已有 JAR 添加或替换条目。
风险与边界
普通 jar 命令只收集指定文件,不会自动合并第三方依赖。直接发布时可能在目标机触发 NoClassDefFoundError;应配置清单 Class-Path,或使用 Maven Shade、Gradle Shadow、Spring Boot 插件生成包含依赖的制品。
执行 java -jar app.jar 时,命令行类路径不会用于补充该 JAR 的应用依赖。需要外部依赖时,应设置清单 Class-Path,或改用 java -cp "app.jar:lib/*" com.example.Main。
jar --create --file 会覆盖同名文件,误用正式路径会丢失旧制品。安全做法是先输出到临时文件,完成启动验证和摘要校验后再替换。jar --extract 可能覆盖当前目录同名文件,应在新建空目录中解压未知 JAR。
排障清单
no main manifest attribute:缺少Main-Class,使用--main-class重新打包。Could not find or load main class:入口类名、包名或 JAR 内路径不一致。NoClassDefFoundError:第三方依赖既未进入运行类路径,也未打入 fat JAR。- 修改源码后结果不变:先重新执行
javac,再重建 JAR,并用jar --list核对条目。 - JDK 8 不支持长选项:改用
jar cf、jar tf、jar cfe等短命令形式。
mvn [全局参数] [生命周期阶段或插件目标] [-D属性=值]
mvn clean package
mvn dependency:tree快速完成 Maven 项目的编译、测试、打包和依赖分析。
Maven 常用命令
在包含 pom.xml 的项目根目录执行,用于编译、测试、打包以及定位依赖冲突。Maven 阶段按生命周期顺序执行,例如执行 package 时会先完成校验、编译和测试;install 还会把产物写入本地仓库。:contentReference[oaicite:0]{index=0}
命令定位
先确认当前使用的 Maven 与 JDK,避免因终端环境、JAVA_HOME 或 IDE 配置不一致导致构建结果不同。
mvn -version预期输出
Apache Maven <VERSION>
Maven home: <PATH>
Java version: <VERSION>, vendor: <VENDOR>
Default locale: <LOCALE>, platform encoding: <ENCODING>
OS name: "<OS>"<VERSION>、<PATH> 等值随机器而变化;重点确认 Maven 版本、Java 版本和 Maven home 是否符合项目要求。
基本语法
下面是语法模板,不可直接运行;阶段、插件目标和参数可以组合。
mvn [全局参数] [生命周期阶段或插件目标] [-D属性=值]常用阶段包括 compile、test、package、verify 和 install。阶段会顺序执行,通常不必把前置阶段全部写出。:contentReference[oaicite:1]{index=1}
常用参数:
-P<PROFILE>:启用指定 Profile。-pl <MODULE> -am:只构建指定模块,并同时构建它依赖的模块。-DskipTests:编译测试代码但不执行测试;-Dmaven.test.skip=true连测试编译也跳过。:contentReference[oaicite:2]{index=2}-U:强制检查更新的 SNAPSHOT 或缺失版本;-o:仅使用本地缓存离线构建。:contentReference[oaicite:3]{index=3}-e:显示异常堆栈;-X:输出调试日志。
高频用法
清理并运行测试
mvn clean test预期输出
[INFO] Tests run: <N>, Failures: 0, Errors: 0, Skipped: <N>
[INFO] BUILD SUCCESS
[INFO] Total time: <TIME>看到 BUILD SUCCESS 且失败数、错误数均为 0,表示测试阶段通过。测试数量和耗时以实际项目为准。
清理并打包
mvn clean package预期输出
[INFO] Building jar: <PATH>/target/<ARTIFACT>-<VERSION>.jar
[INFO] BUILD SUCCESS
[INFO] Total time: <TIME>产物通常位于 target/。若项目使用 WAR、Spring Boot 重打包或自定义插件,文件名和产物类型会不同。
查看运行时依赖树
mvn dependency:tree -Dscope=runtime预期输出
[INFO] <GROUP>:<ARTIFACT>:jar:<VERSION>
[INFO] +- <GROUP>:<DIRECT-DEPENDENCY>:jar:<VERSION>:compile
[INFO] | \- <GROUP>:<TRANSITIVE-DEPENDENCY>:jar:<VERSION>:runtime
[INFO] BUILD SUCCESS缩进表示传递依赖关系;先定位重复组件,再检查最终采用的版本。dependency:tree 支持按 scope、includes 和 excludes 过滤。:contentReference[oaicite:4]{index=4}
风险与边界
clean 会删除 target/,未复制的本地产物和生成文件会丢失;仅需快速增量验证时可直接执行 test 或 package。-DskipTests 会产出未经过测试执行的包,可能把回归问题带入环境,安全做法是在正式交付前至少执行一次完整 verify。install 会写入本地仓库,SNAPSHOT 可能影响其他本地项目;只验证当前项目时优先使用 package。
-X 可能输出仓库地址、环境属性或插件参数。排障日志对外发送前应删除令牌、用户名、内部域名和业务路径。
排障清单
- 出现
Could not resolve dependencies:检查网络、镜像仓库与settings.xml,确认后再使用-U重试。 - 多模块只失败一个模块:使用
-pl <MODULE> -am test缩小范围,并从第一条Caused by开始定位。 - IDE 能构建而终端失败:对比
mvn -version与 IDE 使用的 JDK、Maven 和 Profile。 - 构建成功但产物不对:检查实际执行的是
package、verify还是自定义插件目标,并查看target/中最终文件。
./gradlew [任务1 任务2 ...] [--选项]
./gradlew clean build
./gradlew dependencies --configuration runtimeClasspath快速完成 Gradle 项目的构建、测试、清理和依赖查看。
Gradle 常用命令
在包含 gradlew、gradlew.bat 或 settings.gradle(.kts) 的项目根目录执行,用于运行任务、测试、构建产物和分析依赖。已有 Wrapper 时优先使用 ./gradlew,它能让团队按项目锁定的 Gradle 版本构建。:contentReference[oaicite:5]{index=5}
命令定位
先确认 Wrapper 能启动以及它实际使用的 Gradle、JVM 和操作系统信息。
./gradlew --version预期输出
Gradle <VERSION>
Kotlin: <VERSION>
Groovy: <VERSION>
JVM: <VERSION> (<VENDOR>)
OS: <OS> <VERSION> <ARCH>Windows 使用 gradlew.bat --version。<VERSION>、<OS> 等值按本机和 Wrapper 配置变化。
基本语法
下面是语法模板,不可直接运行。Gradle 一次可以执行一个或多个任务,参数可放在任务前后。
./gradlew [任务1 任务2 ...] [--选项]例如 clean build 会先清理再构建。具体任务由项目应用的插件注册,因此不同项目的任务列表可能不同,可通过 tasks 查看。:contentReference[oaicite:6]{index=6}
常用参数:
--console=plain:输出适合日志采集的纯文本。--stacktrace:失败时显示堆栈;--info、--debug逐级增加日志。--offline:只使用本地缓存;缺少依赖时会直接失败。--refresh-dependencies:重新检查依赖缓存与远端状态。-x test:从任务图中排除测试任务。--no-daemon:本次构建不复用常驻 Daemon,适合部分隔离排障场景。
高频用法
清理并运行测试
./gradlew clean test --console=plain预期输出
> Task :clean
> Task :compileJava
> Task :compileTestJava
> Task :test
BUILD SUCCESSFUL in <TIME>
<N> actionable tasks: <N> executed看到 BUILD SUCCESSFUL 表示任务图执行完成。实际任务名称、数量和耗时取决于插件、源码状态与缓存命中情况。
清理并完成构建
./gradlew clean build --console=plain预期输出
> Task :clean
> Task :compileJava
> Task :test
> Task :jar
> Task :build
BUILD SUCCESSFUL in <TIME>
<N> actionable tasks: <N> executedJava 项目的 JAR 通常位于 build/libs/。build 一般负责组装并执行测试,clean 删除构建目录。:contentReference[oaicite:7]{index=7}
查看运行时依赖
./gradlew dependencies --configuration runtimeClasspath预期输出
> Task :dependencies
runtimeClasspath - Runtime classpath of source set 'main'.
+--- <GROUP>:<DIRECT-DEPENDENCY>:<VERSION>
| \--- <GROUP>:<TRANSITIVE-DEPENDENCY>:<VERSION>
\--- <GROUP>:<DEPENDENCY>:<REQUESTED> -> <SELECTED>
BUILD SUCCESSFUL in <TIME>树形缩进表示传递关系,请求版本 -> 选中版本 表示版本解析结果。dependencies 可按 configuration 展示直接与传递依赖;需要解释某个版本为何被选中时再使用 dependencyInsight。:contentReference[oaicite:8]{index=8}
输出字段说明
UP-TO-DATE 表示输入输出未变化,任务无需重跑;FROM-CACHE 表示结果来自构建缓存;NO-SOURCE 表示任务没有可处理的源文件;SKIPPED 表示任务被条件或参数跳过;FAILED 表示任务执行失败。排障时先找到第一个失败任务,再查看其后的异常根因。
风险与边界
clean 会删除 build/,未复制的本地产物会丢失;只需验证改动时可直接执行 test 或 build。-x test 会让构建跳过测试,可能生成未经验证的产物,正式交付前应恢复完整 build。--refresh-dependencies 会增加远端检查和构建耗时,不应作为每次构建的默认参数;离线环境优先使用 --offline,但必须确保缓存完整。
--debug 日志可能包含环境属性、仓库信息和任务参数。共享日志前应删除凭据、内部地址和业务数据。
排障清单
- 不确定项目支持哪些任务:执行 Wrapper 的
tasks报告,并确认目标插件已应用。 - 只排查子模块:使用完整任务路径,例如
:app:test,避免触发无关模块。 - 依赖版本冲突:先查看指定 configuration 的依赖树,再用
dependencyInsight定位选择原因。 - 本机成功、CI 失败:对比 Wrapper 版本、JDK、环境变量、仓库凭据以及是否启用了离线或缓存参数。
- 错误信息过短:先加
--stacktrace,仍不足再加--info;仅在受控环境使用--debug。
package <包名>;
import <包名>.<类名>;
import static <包名>.<类名>.<静态成员>;声明包、导入类型并避免命名冲突和目录结构错误。
包与导入
用于把类放入稳定命名空间,并在源文件中引用其他包的类型。包名、目录和运行时类名必须一致,否则常见结果是编译找不到类型或启动时提示主类不存在。
基本规则
package 必须位于源文件第一条有效语句,并且一个源文件只能声明一个包。通常让目录与包名逐级对应,例如 com.example.app.Main 放在 src/com/example/app/Main.java。
java.lang 中的类型和同包类型无需导入;其他类型使用 import 包名.类型名;。通配符导入只覆盖当前包,例如 import java.util.*; 不会导入 java.util.concurrent。
可运行示例
下面同时演示包声明、单类型导入、按包名编译,以及两个同名 Date 类型的冲突处理。
rm -rf /tmp/java-package-demo
mkdir -p /tmp/java-package-demo/src/com/example/app
mkdir -p /tmp/java-package-demo/src/com/example/model
cd /tmp/java-package-demo
cat > src/com/example/model/Person.java <<'JAVA'
package com.example.model;
public record Person(String name) {
}
JAVA
cat > src/com/example/app/Main.java <<'JAVA'
package com.example.app;
import com.example.model.Person;
import java.time.LocalDate;
import java.util.Date;
public class Main {
public static void main(String[] args) {
Person person = new Person("Ada");
Date utilDate = new Date(0);
// java.util.Date 已导入,java.sql.Date 使用全限定名避免同名冲突
java.sql.Date sqlDate = java.sql.Date.valueOf(LocalDate.of(2026, 8, 1));
System.out.println(person.name());
System.out.println(utilDate.getClass().getName());
System.out.println(sqlDate);
}
}
JAVA
mkdir out
javac -encoding UTF-8 -d out src/com/example/model/Person.java src/com/example/app/Main.java
java -cp out com.example.app.Main预期输出:
Ada
java.util.Date
2026-08-01-d out 会按包名生成 out/com/example/... 目录;运行时必须使用全限定类名 com.example.app.Main,不能只写 Main。
命名冲突与边界
当两个包存在同名类型时,Java 不能同时用单类型导入消除歧义。保留其中一个 import,另一个在代码中写全限定名,通常比通配符导入更清晰。
不要通过修改包声明临时绕过冲突。触发条件是源码包名与调用方、构建配置或目录约定不一致;后果可能是重复类、类无法加载或产物路径异常;安全做法是同步重构包名、目录和所有引用。
排障清单
package ... does not exist:先确认依赖是否参与编译,再检查导入名和包声明是否逐字一致。cannot find symbol:检查类型是否为public、是否导入正确,以及源文件是否已加入编译命令。Could not find or load main class:确认类路径指向包目录的上一级,本例应使用-cp out。- IDE 正常但命令行失败:检查 IDE 是否额外配置了源码根目录或依赖,使用实际构建工具重新验证。
兼容性
record 需要 JDK 16+;使用较旧 JDK 时可改为普通 public class Person。包和导入规则本身适用于主流 Java 版本。
<类型> <变量名> = <初始值>;
var <变量名> = <初始值>;
static final <类型> <常量名> = <值>;声明局部变量、成员变量和不可重新赋值的常量。
变量与常量
用于保存运行过程中的状态,并通过作用域、类型和 final 限制误修改。局部变量必须先赋值再读取,成员变量会获得默认值,常量通常声明为 static final。
声明方式
局部变量只在所在代码块内有效;成员变量属于对象;静态变量属于类。Java 10+ 可在局部变量中使用 var,但编译器仍会推断出固定类型,不能随后改成其他类型。
常量通常写成 private static final 或 public static final,名称使用全大写加下划线。final 只禁止变量重新指向其他值,不保证引用对象不可变。
可运行示例
cat > VariableDemo.java <<'JAVA'
import java.util.ArrayList;
import java.util.List;
public class VariableDemo {
private int retryCount; // 成员变量默认值为 0
private static final int MAX_RETRIES = 3;
public static void main(String[] args) {
int attempts = 1; // 局部变量必须显式初始化
final String requestId = "REQ-1001";
var status = "READY"; // 推断为 String
final List<String> roles = new ArrayList<>();
roles.add("ADMIN"); // final 引用仍可修改对象内容
VariableDemo demo = new VariableDemo();
System.out.println(demo.retryCount);
System.out.println(attempts + "/" + MAX_RETRIES);
System.out.println(requestId + " " + status);
System.out.println(roles);
}
}
JAVA
javac VariableDemo.java
java VariableDemo预期输出:
0
1/3
REQ-1001 READY
[ADMIN]成员变量 retryCount 未显式赋值,因此为 0;局部变量 attempts 若未初始化就读取,编译会直接失败。
作用域与赋值边界
变量只应放在最小必要作用域内,避免同名变量遮蔽成员字段。构造器或方法参数与字段同名时,使用 this.retryCount = retryCount; 明确左侧是对象字段。
窄化转换可能丢失数据。例如把 long 强转为 int 时,超出范围会截断高位;安全替代方案是先检查范围,或使用 Math.toIntExact(longValue),溢出时让程序明确失败。
风险与安全写法
把可变集合声明为 public static final 只固定了引用,外部仍可增删元素,可能造成全局状态被意外修改。对外暴露常量集合时优先使用 List.of(...)、不可变副本或只读访问方法。
成员变量在多线程间共享时,普通赋值不自动保证可见性和原子性。触发条件是多个线程并发读写同一字段;后果是读取旧值或发生竞争;安全替代方案是根据操作选择 volatile、原子类或同步机制。
排障清单
variable ... might not have been initialized:为局部变量在所有分支上赋值后再读取。cannot assign a value to final variable:不要二次赋值;需要变化时移除final或创建新变量。- 数值结果异常:检查整数溢出、整数除法和强制类型转换。
- 字段值未更新:检查是否被同名局部变量遮蔽,给字段赋值时显式使用
this。
兼容性
var 仅适用于 JDK 10+ 的局部变量,不能用于字段、方法参数或无初始化表达式的声明。其余变量、字段和 final 规则适用于主流 Java 版本。
byte short int long float double char boolean
<包装类>.MIN_VALUE / <包装类>.MAX_VALUE查询整数、浮点数、字符和布尔类型的范围与默认值。
Java 基本类型范围
查询数值能否容纳、字段初始值是否符合预期时,先确认基本类型的位数、取值范围和默认值。Java 基本类型的位数固定,不随操作系统变化;默认值只适用于实例字段、静态字段和数组元素,局部变量必须先赋值。
范围与默认值
| 类型 | 位数 | 取值范围 | 字段默认值 |
|---|---|---|---|
byte |
8 | -128 ~ 127 | 0 |
short |
16 | -32768 ~ 32767 | 0 |
int |
32 | -2147483648 ~ 2147483647 | 0 |
long |
64 | -9223372036854775808 ~ 9223372036854775807 | 0L |
float |
32 | 有限值约 -3.4028235E38 ~ 3.4028235E38 | 0.0F |
double |
64 | 有限值约 -1.7976931348623157E308 ~ 1.7976931348623157E308 | 0.0D |
char |
16 | 0 ~ 65535,即 '\u0000' ~ '\uffff' |
'\u0000' |
boolean |
JVM 语义类型 | true 或 false |
false |
Float.MIN_VALUE 和 Double.MIN_VALUE 分别表示约 1.4E-45、4.9E-324 的最小正非零值,不是最小负数。
运行查询
下面的完整程序直接读取 JDK 常量,适合核对运行环境和边界值。
public class PrimitiveRangeDemo {
static int intValue;
static char charValue;
static boolean booleanValue;
public static void main(String[] args) {
System.out.println("byte: " + Byte.MIN_VALUE + " .. " + Byte.MAX_VALUE);
System.out.println("int: " + Integer.MIN_VALUE + " .. " + Integer.MAX_VALUE);
System.out.println("long: " + Long.MIN_VALUE + " .. " + Long.MAX_VALUE);
System.out.println("float max: " + Float.MAX_VALUE);
System.out.println("double max: " + Double.MAX_VALUE);
System.out.println("char code: " + (int) Character.MIN_VALUE + " .. "
+ (int) Character.MAX_VALUE);
System.out.println("defaults: " + intValue + ", "
+ (int) charValue + ", " + booleanValue);
}
}预期输出:
byte: -128 .. 127
int: -2147483648 .. 2147483647
long: -9223372036854775808 .. 9223372036854775807
float max: 3.4028235E38
double max: 1.7976931348623157E308
char code: 0 .. 65535
defaults: 0, 0, falsechar 默认值不可见,因此示例转为整数后输出 0。浮点常量可能以等价科学计数法显示。
风险与边界
整数越界不会抛异常,而是按补码回绕。例如 Integer.MAX_VALUE + 1 会得到 Integer.MIN_VALUE。计数、金额最小单位或容量计算接近上限时,优先改用 long,并用 Math.addExact、Math.multiplyExact 检测溢出。
float 和 double 不能精确表示多数十进制小数。金额、费率和对账值直接使用它们,可能出现比较失败或累计误差;安全替代方案是使用 BigDecimal,并通过字符串构造。
局部变量没有默认值。读取未初始化局部变量会编译失败;不要把字段默认值规则套到方法内部变量。
速查提示
需要程序化获取边界时,使用包装类的 MIN_VALUE、MAX_VALUE;需要最小负浮点值时使用 -Float.MAX_VALUE 或 -Double.MAX_VALUE。
目标类型 变量 = (目标类型) 原值;
Integer.parseInt(<字符串>) / String.valueOf(<值>)处理基本类型之间的自动转换、强制转换和精度损失。
Java 基本类型转换
处理赋值不兼容、计算结果异常或数据截断时,先区分自动扩大转换与强制缩小转换。扩大转换通常可直接赋值,但不保证数值精度完全不变;缩小转换必须显式写出目标类型,并承担截断或溢出风险。
转换规则
自动扩大转换的主链路是:
byte、short、char → int → long → float → double
byte、short 与 char 之间不能互相自动转换。boolean 不能与任何数值类型转换。表达式计算还会触发数值提升,例如两个 byte 相加的结果是 int。
片段示例(需放在方法体内):
目标类型 变量 = (目标类型) 原值;强制转换只改变表示方式,不检查结果是否仍在目标类型范围内。
主示例
下面的完整程序同时演示自动扩大、整数回绕、浮点截断和扩大转换中的精度损失。
public class TypeConversionDemo {
public static void main(String[] args) {
int count = 120;
long widened = count; // int 自动扩大为 long
int source = 130;
byte narrowed = (byte) source; // 超出 byte 范围后发生回绕
double price = 9.8;
int truncated = (int) price; // 直接舍弃小数部分,不四舍五入
long precise = 16_777_217L;
float rounded = precise; // float 无法精确保存该整数
byte a = 10;
byte b = 20;
int sum = a + b; // byte 运算前先提升为 int
System.out.println(widened);
System.out.println(narrowed);
System.out.println(truncated);
System.out.println(rounded);
System.out.println(sum);
}
}预期输出:
120
-126
9
1.6777216E7
30130 转为 byte 后只保留低 8 位,因此结果为 -126。9.8 转为 int 时向零截断。16777217 转为 float 后变成可表示的相邻值 16777216,输出为科学计数法。
安全转换
从 long 转为 int 时,直接强转可能静默产生错误值。需要越界即失败时使用 Math.toIntExact:
public class SafeNarrowingDemo {
public static void main(String[] args) {
long value = 3_000_000_000L;
try {
int result = Math.toIntExact(value);
System.out.println(result);
} catch (ArithmeticException e) {
System.out.println("out of int range");
}
}
}预期输出:
out of int range浮点数转整数前需要明确舍入策略。四舍五入可使用 Math.round,向下取整使用 Math.floor,向上取整使用 Math.ceil;最终仍要检查目标整数范围。
风险与边界
整数缩小转换在源值超出范围时不会报错,可能造成 ID、金额最小单位、状态码或长度字段变成错误值。安全替代方案是先比较目标类型的 MIN_VALUE、MAX_VALUE,或使用 Math.toIntExact 等精确转换方法。
long 自动转为 float、double 虽然语法合法,但大整数可能丢失低位精度。需要保存完整整数时保持 long,不要为了统一计算类型提前转成浮点数。
把 double 强转为整数会丢弃小数;NaN 转整数得到 0,超出整数范围时结果会压到对应边界。生产代码应先校验有限值、范围和舍入规则,再执行转换。
排障清单
遇到转换后的值异常时,依次确认源值是否超出目标范围、表达式是否发生了 int 提升、整数是否先做了除法、浮点数是否丢失精度,以及强制转换发生在运算前还是运算后。
Integer boxed = <int 值>; // 自动装箱
int value = boxed; // 自动拆箱,boxed 为 null 时抛 NullPointerException在基本类型与包装类型之间转换并规避空值和比较陷阱。
Java 装箱与拆箱
在基本类型与包装类型之间赋值、传参或参与集合操作时使用。重点防止包装类型为 null 时自动拆箱触发 NullPointerException,以及误用 == 比较包装对象。
基本语法
装箱把基本类型转换为包装类型,拆箱执行相反转换。Java 通常会自动完成,也可以显式调用方法。
public class BoxingDemo {
public static void main(String[] args) {
int primitive = 128;
Integer boxed = primitive; // 自动装箱
int unboxed = boxed; // 自动拆箱
Integer explicit = Integer.valueOf("42");
System.out.println(boxed);
System.out.println(unboxed);
System.out.println(explicit);
}
}预期输出
128
128
42读取方法:三个值相同,说明转换成功;Integer.valueOf 适合从字符串创建包装值,非法数字会抛出 NumberFormatException。
高频用法
集合泛型不能直接使用基本类型,应使用包装类型:
import java.util.List;
public class BoxingListDemo {
public static void main(String[] args) {
List<Integer> numbers = List.of(10, 20, 30);
int total = numbers.stream().mapToInt(Integer::intValue).sum();
System.out.println(total);
}
}预期输出
60读取方法:元素加入集合时发生装箱,mapToInt 调用 intValue() 后按基本类型求和。
需要默认值时,先处理 null 再拆箱:
public class SafeUnboxingDemo {
public static void main(String[] args) {
Integer retryCount = null;
int safeCount = retryCount == null ? 0 : retryCount;
System.out.println(safeCount);
}
}预期输出
0风险与边界
Integer value = null; int n = value; 会在拆箱时抛出 NullPointerException。安全替代方案是先判空,或使用 Objects.requireNonNullElse(value, 0) 提供默认值。
不要用 == 判断两个包装对象的数值是否相等。部分小整数可能因缓存而返回 true,超出缓存范围后却返回 false,导致结果依赖数值范围。应使用 a.equals(b);任一值可能为 null 时使用 Objects.equals(a, b)。
频繁装箱会创建对象并增加内存与 GC 压力。大量数值计算优先使用 int、long、double,流处理中优先使用 IntStream、LongStream、DoubleStream。
排障清单
遇到空指针时,先检查算术运算、比较、方法参数和三元表达式中是否隐式拆箱。遇到包装值比较异常时,将 == 改为 Objects.equals。遇到性能抖动时,检查循环、集合和 Stream 中是否产生了大量临时包装对象。
速查:包装类型允许 null,基本类型不允许;只要包装值参与基本类型运算,就可能发生拆箱。
a.equals(b)
a.equalsIgnoreCase(b)
Objects.equals(a, b)
a.compareTo(b)正确比较字符串内容、忽略大小写以及处理 null 值。
Java 字符串比较
比较字符串内容时使用 equals,忽略大小写时使用 equalsIgnoreCase,可能出现 null 时优先使用常量调用或 Objects.equals。不要用 == 判断字符串内容。
基本语法
equals 比较字符序列并区分大小写;equalsIgnoreCase 忽略大小写;== 只判断两个变量是否指向同一个对象。
import java.util.Objects;
public class StringCompareDemo {
public static void main(String[] args) {
String actual = new String("Java");
String expected = "Java";
String optional = null;
System.out.println(expected.equals(actual));
System.out.println(expected == actual);
System.out.println("java".equalsIgnoreCase(actual));
System.out.println(Objects.equals(optional, null));
}
}预期输出
true
false
true
true读取方法:第一行内容相同;第二行对象引用不同;第三行忽略大小写后相同;第四行说明 Objects.equals 能安全处理两个 null。
高频用法
固定值比较时,把常量写在前面可规避空指针:
public class NullSafeStringDemo {
public static void main(String[] args) {
String status = null;
if ("SUCCESS".equals(status)) {
System.out.println("paid");
} else {
System.out.println("not paid");
}
}
}预期输出
not paid两个变量都可能为 null 时使用 Objects.equals(left, right)。它在两者都为 null 时返回 true,只有一方为 null 时返回 false。
比较用户输入前若需要忽略首尾空白,应先按业务规则规范化:
public class NormalizedCompareDemo {
public static void main(String[] args) {
String input = " admin ";
boolean matched = "admin".equalsIgnoreCase(input.trim());
System.out.println(matched);
}
}预期输出
true风险与边界
a == b 偶尔返回 true,通常是因为字符串常量池或编译器优化,不代表它能比较内容。输入来自文件、数据库、HTTP 或 new String() 时尤其容易得到错误结果,安全替代方案是 equals 或 Objects.equals。
直接调用 variable.equals(...) 时,如果 variable 为 null 会抛出 NullPointerException。固定值比较使用 "VALUE".equals(variable);双方都不固定时使用 Objects.equals。
equalsIgnoreCase 适合协议值、状态码和一般英文文本,不适合需要语言环境规则的排序或本地化比较。此类场景应使用 Collator,不要简单转成大写或小写后比较。
空字符串 ""、纯空白字符串和 null 含义不同。是否视为等价必须由业务规则决定,不能仅靠字符串比较方法自动合并。
排障清单
比较结果反常时,先打印字符串长度和可见边界,检查首尾空格、换行及不可见字符;再确认是否误用了 ==。出现空指针时,检查 equals 的调用者是否可能为 null。接口状态判断失败时,确认大小写和字符编码是否符合协议。
速查:内容比较用 equals,忽略大小写用 equalsIgnoreCase,可空变量用 Objects.equals。
s.substring(<begin>, <end>) / s.indexOf(<子串>) / s.split(<正则>)
s.replace(<旧>, <新>) / s.strip() / String.join(<分隔符>, <元素>)完成字符串查找、截取、替换、分割和格式化操作。
处理字符串
用于完成字符串查找、截取、替换、分割和格式化。Java 的 String 不可变,所有修改类方法都会返回新字符串,原变量不会自动改变。
基本语法
常用方法如下:
| 操作 | 方法 | 读取方式 |
|---|---|---|
| 查找 | contains、indexOf、startsWith、endsWith |
indexOf 返回首次位置,未找到返回 -1 |
| 截取 | substring(begin, end) |
包含 begin,不包含 end |
| 替换 | replace、replaceAll |
replaceAll 的第一个参数是正则表达式 |
| 分割 | split(regex) |
返回 String[],参数按正则解析 |
| 格式化 | String.format、formatted |
使用 %s、%d、%.2f 等占位符 |
高频用法
下面示例覆盖查找、截取、替换、分割和格式化,可直接编译运行。
import java.util.Arrays;
public class StringOperationsDemo {
public static void main(String[] args) {
String text = "order:PAY-20260802,status=SUCCESS,amount=128.50";
int orderStart = text.indexOf("PAY-");
int orderEnd = text.indexOf(',', orderStart);
String orderNo = text.substring(orderStart, orderEnd);
// replace 按普通文本替换;replaceAll 按正则替换。
String masked = orderNo.replaceAll("\\d{4}$", "****");
String normalized = text.replace("SUCCESS", "PAID");
String fieldsText = "PAY-20260802,SUCCESS,128.50";
String[] fields = fieldsText.split(",");
String message = String.format(
"订单=%s,状态=%s,金额=%.2f",
fields[0], fields[1], Double.parseDouble(fields[2])
);
System.out.println("orderStart=" + orderStart);
System.out.println("orderNo=" + orderNo);
System.out.println("masked=" + masked);
System.out.println("normalized=" + normalized);
System.out.println("fields=" + Arrays.toString(fields));
System.out.println(message);
}
}预期输出:
orderStart=6
orderNo=PAY-20260802
masked=PAY-2026****
normalized=order:PAY-20260802,status=PAID,amount=128.50
fields=[PAY-20260802, SUCCESS, 128.50]
订单=PAY-20260802,状态=SUCCESS,金额=128.50orderStart=6 表示目标字符串从索引 6 开始;substring 的结束索引不包含逗号,因此结果只保留订单号。
风险与边界
substring 的索引小于 0、超过字符串长度,或起始索引大于结束索引时会抛出 StringIndexOutOfBoundsException。截取前应先确认 indexOf 结果不是 -1,生产代码可在找不到分隔符时返回默认值或抛出业务异常。
replaceAll 和 split 使用正则表达式。处理点号、竖线、反斜杠等普通字符时,直接传入可能产生错误匹配;固定文本优先用 replace,动态分隔符可先用 Pattern.quote(value) 转义。
split 默认丢弃末尾空字段。例如 "a,b,".split(",") 只得到两个元素;需要保留末尾空值时使用 split(",", -1)。
排障清单
- 查找结果异常:输出
indexOf返回值,确认大小写、空格和全角字符。 - 截取越界:检查开始、结束索引是否存在且顺序正确。
- 替换范围过大:确认是否误用
replaceAll,以及正则是否缺少边界。 - 分割数量不符:确认分隔符是否为正则特殊字符,并检查是否需要
limit=-1。 - 出现空指针:调用字符串方法前先处理
null,不要把null与空字符串混为一谈。
兼容性
String.format 可用于较早版本的 Java;实例方法 "内容 %s".formatted(value) 从 Java 15 开始提供。需要兼容 Java 8 或 Java 11 时,统一使用 String.format。
new StringBuilder().append(<值>)...toString()
String.join(<分隔符>, <元素>)
new StringJoiner(<分隔符>, <前缀>, <后缀>)根据使用场景选择加号、StringBuilder、join 和格式化方法。
高效拼接字符串
根据拼接次数和数据来源选择 +、StringBuilder、String.join 或格式化方法。少量固定字段优先可读性;循环和批量数据优先避免反复创建中间字符串。
选择方法
| 场景 | 推荐方式 | 原因 |
|---|---|---|
| 少量、一次性拼接 | + |
代码最直观,编译器可优化单个表达式 |
| 循环或条件拼接 | StringBuilder |
复用内部缓冲区,减少临时对象 |
| 集合或数组加分隔符 | String.join、Collectors.joining |
自动处理分隔符,不产生首尾多余字符 |
| 面向用户的模板文本 | String.format、formatted |
字段位置和格式更清楚 |
高频用法
下面示例分别演示四种常见方式,可直接编译运行。
import java.util.List;
import java.util.stream.Collectors;
public class StringConcatDemo {
public static void main(String[] args) {
String orderNo = "PAY-20260802";
double amount = 128.50;
String simple = "订单 " + orderNo + " 金额 " + amount;
List<String> items = List.of("apple", "banana", "orange");
// 循环中持续追加时复用同一个缓冲区。
StringBuilder builder = new StringBuilder(64);
for (int i = 0; i < items.size(); i++) {
if (i > 0) {
builder.append(" | ");
}
builder.append(i + 1).append(':').append(items.get(i));
}
String joined = String.join(",", items);
String upperJoined = items.stream()
.map(String::toUpperCase)
.collect(Collectors.joining(" -> "));
String message = String.format(
"订单=%s,金额=%.2f,商品数=%d",
orderNo, amount, items.size()
);
System.out.println(simple);
System.out.println(builder);
System.out.println(joined);
System.out.println(upperJoined);
System.out.println(message);
}
}预期输出:
订单 PAY-20260802 金额 128.5
1:apple | 2:banana | 3:orange
apple,banana,orange
APPLE -> BANANA -> ORANGE
订单=PAY-20260802,金额=128.50,商品数=3第一行使用 +,适合字段少的一次性表达式;第二行由 StringBuilder 在循环中构造;第三、四行展示带分隔符拼接;最后一行负责固定格式和小数位控制。
风险与边界
在循环中执行 result = result + value 会反复创建新字符串。数据量增大时可能增加 CPU 和垃圾回收压力;安全替代方案是在循环外创建一个 StringBuilder,循环内只调用 append,最后调用 toString。
StringBuilder 不是线程安全的。多个线程共享同一个实例时可能出现内容交叉或数据损坏;优先让它成为方法内局部变量。确实需要共享可变缓冲区时,应使用外部同步,或评估 StringBuffer,但不要仅为“可能并发”盲目替换。
手工处理分隔符时容易出现开头或结尾多一个逗号。集合直接使用 String.join;需要先转换元素时使用 Collectors.joining,比拼接后再删除最后一个分隔符更安全。
格式化方法可读性高,但不适合极高频的热点循环。性能敏感路径可改用 StringBuilder,并通过基准测试确认优化收益,不要仅凭方法名称判断快慢。
排障清单
- 输出出现
null:检查参与拼接的对象是否为空,并在进入拼接前决定默认值。 - 分隔符重复或缺失:优先改用
String.join或Collectors.joining。 - 循环拼接耗时或 GC 上升:查找循环内的
+=,改为复用局部StringBuilder。 - 金额小数位不固定:使用
String.format("%.2f", amount);金融金额计算本身应使用BigDecimal。 - 多线程结果混乱:确认是否共享了同一个
StringBuilder实例。
兼容性
StringBuilder 自 Java 5 起可用,String.join 和 Collectors.joining 从 Java 8 起可用,String.formatted 从 Java 15 起可用。需要兼容 Java 8 或 Java 11 时,可使用 String.format 代替 formatted。
String text = """
<多行内容>
""";使用文本块编写多行 SQL、JSON、HTML 和模板字符串。
Java 文本块
文本块用三个双引号声明多行字符串,适合直接保存 SQL、JSON、HTML 和模板片段,避免大量 \n 与 \" 转义。文本块仍然是普通 String,可调用 formatted()、replace() 等方法。
基本语法
开始分隔符 """ 后必须换行;结束分隔符的位置会参与公共缩进计算。编译器会移除每行共有的附带缩进,但保留内容内部的相对缩进。
片段示例,需放在类的方法体或初始化代码中:
String text = """
first line
second line
""";变量不会自动插值。需要替换内容时,优先使用 %s 配合 formatted(),或使用模板引擎处理复杂模板。
高频用法
下面的程序同时演示多行 SQL、JSON、HTML,以及文本块中的格式化占位符。
public class TextBlockDemo {
public static void main(String[] args) {
String tableName = "orders";
String status = "SUCCESS";
// formatted() 只替换占位符,不会对 SQL 参数做安全转义
String sql = """
SELECT id, amount
FROM %s
WHERE status = '%s'
ORDER BY id DESC
""".formatted(tableName, status);
String json = """
{
"name": "Anystack",
"enabled": true
}
""";
String html = """
<section class="card">
<h1>%s</h1>
</section>
""".formatted("Java 文本块");
System.out.print(sql);
System.out.print(json);
System.out.print(html);
}
}预期输出
SELECT id, amount
FROM orders
WHERE status = 'SUCCESS'
ORDER BY id DESC
{
"name": "Anystack",
"enabled": true
}
<section class="card">
<h1>Java 文本块</h1>
</section>print 不会额外补换行;示例中的换行来自文本块本身。结束分隔符单独放在下一行时,字符串通常包含末尾换行。
缩进与换行控制
关闭分隔符与内容同级时,公共缩进会被剥离。需要保留行尾空格时可使用 \s;需要让源码换行但字符串不换行时,可在行尾使用反斜杠。
public class TextBlockWhitespaceDemo {
public static void main(String[] args) {
String message = """
Java\s
text \
block
""";
System.out.print(message.replace(" ", "·"));
}
}预期输出
Java·
text·block这里 \s 明确保留一个行尾空格;行尾反斜杠取消了 text 后的换行。
风险与边界
文本块只改善源码可读性,不提供 SQL 参数绑定、JSON 校验或 HTML 转义。把用户输入直接放入 formatted() 可能造成 SQL 注入或页面注入;安全替代方案是 SQL 值使用 PreparedStatement 参数,JSON 使用 Jackson,HTML 使用模板引擎的转义能力。
关闭分隔符缩进变化可能改变字符串前导空格,末尾换行也可能影响快照测试、签名或协议报文。对空白敏感的内容可用 text.length()、replace(" ", "·") 或单元测试检查实际字符。
兼容性
文本块从 Java 15 起正式可用。Java 13、14 中曾以预览特性提供,生产代码应使用 Java 15 及以上,并确保编译与运行时 JDK 版本一致。
<类型>[] arr = new <类型>[<长度>];
<类型>[] arr = {<元素>, ...};
Arrays.sort(arr) / Arrays.copyOf(arr, <新长度>) / System.arraycopy(src, srcPos, dest, destPos, length)创建、复制、填充、排序、查找和遍历 Java 数组。
Java 数组操作
Java 数组长度固定、元素类型统一,适合保存已知规模的数据。常用操作集中在 java.util.Arrays 和 System.arraycopy():创建后可填充、复制、排序、查找和遍历,但不能直接扩容。
创建与基本访问
声明数组时必须确定长度或直接给出元素。下标从 0 开始,最后一个下标是 length - 1。
片段示例,需放在类的方法体中:
int[] scores = new int[3];
scores[0] = 90;
String[] names = {"Alice", "Bob", "Carol"};
System.out.println(scores.length);
System.out.println(names[2]);预期输出
3
Carol访问负数下标或大于等于 length 的下标会抛出 ArrayIndexOutOfBoundsException。
常用操作
| 目标 | 推荐写法 | 关键边界 |
|---|---|---|
| 填充全部或区间 | Arrays.fill() |
区间右边界不包含 |
| 复制并调整长度 | Arrays.copyOf() |
扩大后使用类型默认值补齐 |
| 复制指定区间 | Arrays.copyOfRange() |
起点包含,终点不包含 |
| 原地复制 | System.arraycopy() |
源和目标可为同一数组 |
| 排序 | Arrays.sort() |
修改原数组 |
| 二分查找 | Arrays.binarySearch() |
查找前必须按同一规则排序 |
下面的完整示例覆盖创建、填充、复制、排序、查找和遍历。
import java.util.Arrays;
public class ArrayDemo {
public static void main(String[] args) {
int[] values = new int[5];
Arrays.fill(values, 7);
// copyOf 会创建新数组;扩大部分用 int 默认值 0 填充
int[] expanded = Arrays.copyOf(values, 7);
expanded[5] = 3;
expanded[6] = 9;
Arrays.sort(expanded);
int index = Arrays.binarySearch(expanded, 9);
System.out.println("sorted=" + Arrays.toString(expanded));
System.out.println("index=" + index);
int sum = 0;
for (int value : expanded) {
sum += value;
}
System.out.println("sum=" + sum);
}
}预期输出
sorted=[3, 7, 7, 7, 7, 7, 9]
index=6
sum=47数组中存在多个相同值时,binarySearch() 只保证返回其中一个匹配位置,不保证返回第一个。未找到时返回负数,插入点可按 -result - 1 计算。
区间复制与原地移动
System.arraycopy() 适合高效复制连续区间,也能安全处理同一数组内的重叠移动。
import java.util.Arrays;
public class ArrayCopyDemo {
public static void main(String[] args) {
int[] numbers = {10, 20, 30, 40, 50};
// 将前 3 个元素向右移动一位,底层会正确处理重叠区域
System.arraycopy(numbers, 0, numbers, 1, 3);
System.out.println(Arrays.toString(numbers));
}
}预期输出
[10, 10, 20, 30, 50]参数依次是源数组、源起点、目标数组、目标起点和复制长度。任一区间越界会抛出异常;源与目标元素类型不兼容时会抛出 ArrayStoreException。
遍历与输出
只读取元素时使用增强 for;需要下标、倒序或修改指定位置时使用普通 for。对象数组可用 Arrays.stream(),基本类型数组则使用对应的 IntStream、LongStream 或 DoubleStream。
调试时不要直接打印数组对象,例如 System.out.println(values),它通常显示类型和哈希形式。应使用 Arrays.toString();二维及更深数组使用 Arrays.deepToString()。
风险与边界
Arrays.sort()、Arrays.fill() 和 System.arraycopy() 都会修改目标数组。调用方仍持有同一数组引用时,可能观察到意外变化;需要隔离修改时先用 Arrays.copyOf() 创建副本。
Arrays.asList(intArray) 会把整个 int[] 当成一个元素,不能得到整数列表。安全替代方案是 Arrays.stream(intArray).boxed().toList()。数组长度固定,频繁插入、删除或动态扩容时应改用 ArrayList。
if (<条件>) { ... } else if (<条件>) { ... } else { ... }
<条件> ? <值1> : <值2>使用 if、else 和条件运算符表达分支逻辑。
Java 条件判断
用于根据布尔条件选择不同执行路径。简单二选一使用 if...else,多段条件使用 else if,只需得到一个值时可使用条件运算符 ?:。
基本语法
if (condition) {
// 条件为 true 时执行
} else if (otherCondition) {
// 前一条件为 false,且当前条件为 true 时执行
} else {
// 所有条件都为 false 时执行
}
String result = condition ? "yes" : "no";condition 必须是 boolean 表达式,Java 不允许用整数代替真假值。
高频用法
下面示例同时演示范围判断、分支顺序和条件运算符,可直接保存为 ConditionDemo.java 运行。
public class ConditionDemo {
public static void main(String[] args) {
int score = 82;
String level;
if (score < 0 || score > 100) {
level = "invalid";
} else if (score >= 90) {
level = "A";
} else if (score >= 80) {
level = "B";
} else {
level = "C";
}
String result = score >= 60 ? "pass" : "fail";
System.out.println("level=" + level);
System.out.println("result=" + result);
}
}预期输出:
level=B
result=pass从上到下只执行第一个命中的分支,因此 score >= 80 必须放在更宽泛的 else 之前。
风险与边界
- 条件顺序错误会让后续分支永远无法命中,例如先判断
score >= 60,再判断score >= 90。 - 比较字符串内容应使用
equals,使用==可能只比较对象引用。可写成"OK".equals(status),同时避免status为null时抛出异常。 - 条件运算符适合简单赋值;嵌套多个
?:会降低可读性,应改用if...else。
排障清单
遇到分支结果不符合预期时,依次检查:条件边界是否包含等号、分支顺序是否从具体到宽泛、参与比较的值是否为 null、字符串是否误用 ==。
for (int i = 0; i < <上限>; i++) { ... }
for (<类型> item : <集合>) { ... }
while (<条件>) { ... } // break / continue使用 for、增强 for、while、break 和 continue 控制循环。
Java 循环控制
用于重复执行代码。已知次数时用 for,遍历数组或集合时优先用增强 for,次数不确定且依赖条件时用 while;break 立即结束循环,continue 跳过当前轮次。
基本语法
for (int i = 0; i < limit; i++) {
// 使用索引控制次数
}
for (String item : items) {
// 只读取当前元素
}
while (condition) {
// 条件为 true 时持续执行
}增强 for 不提供索引,也不适合在遍历时直接增删普通集合。
高频用法
下面示例遍历整数数组,跳过负数,累计非负数;累计值达到 10 后立即结束。
public class LoopDemo {
public static void main(String[] args) {
int[] numbers = {3, -1, 4, 5, 8};
int sum = 0;
for (int number : numbers) {
if (number < 0) {
continue; // 当前元素无效,直接处理下一个
}
sum += number;
System.out.println("add=" + number + ", sum=" + sum);
if (sum >= 10) {
break; // 已满足目标,不再扫描剩余元素
}
}
int countdown = 3;
while (countdown > 0) {
System.out.println("countdown=" + countdown);
countdown--;
}
}
}预期输出:
add=3, sum=3
add=4, sum=7
add=5, sum=12
countdown=3
countdown=2
countdown=1数组中的 -1 被 continue 跳过;累计到 12 后触发 break,因此末尾的 8 不再处理。
风险与边界
while条件依赖的变量若不更新,会形成无限循环并持续占用 CPU;应确保每轮都推进状态,或设置明确退出条件。- 普通
for的边界通常写成i < array.length;误写为i <= array.length会触发ArrayIndexOutOfBoundsException。 - 在增强
for中直接调用集合的remove可能触发ConcurrentModificationException;需要删除元素时使用Iterator.remove()或removeIf()。 break和continue只作用于当前循环;多层循环需要调整结构、使用标签,或抽取为方法后return。
排障清单
循环次数异常时,检查初始值、终止条件和步进表达式;遗漏元素时检查是否提前触发 break;结果未更新时检查是否被 continue 跳过;集合遍历报并发修改异常时改用迭代器安全删除。