Java零基础保姆级教程：告别版本升级API大坑 还在为JDK 17升级到21后，原本跑得好好的代码突然报错而抓狂吗？ 很多初学者刚把Hello World跑通，转头发现java.awt里的类全被标记为废弃，或者javax包名变成了jakarta，瞬间懵圈。 别慌，这篇java零基础实战文就是为你准备的保姆级教程，我们直接用一个真实的小项目，把版本差异和核心逻辑讲透。 项目目标：搭建跨版本的简易任务管理器 我们不做那种大而全的企业级框架，而是从一个最贴近生活的场景入手：构建一个基于控制台的待办事项管理器。 这个项目的核心价值在于，它使用了Java中变化最剧烈的几个领域：集合操作、异常处理、以及I/O流。 通过它，你能直观看到为什么旧教程的代码在新版JDK里跑不动，以及如何用现代Java风格写出既兼容又优雅的程序。 具体功能包括：添加任务：支持标题、优先级（高/中/低）、截止时间。 查看列表：按优先级排序，高优先级置顶。 完成任务：标记某项任务为已完成。 持久化：将数据保存到本地JSON文件，重启程序后数据不丢失。为什么选JSON而不是数据库？因为对于java零基础学习者，引入MySQL或H2数据库会增加环境配置复杂度。使用Java自带的javax.json或第三方轻量库，能让我们更聚焦于Java语言本身的特性变化。 目录结构：工程化思维起步 很多新手习惯把所有代码写在一个Main.java里，这是大忌。 从第一个项目开始，就要养成模块化的习惯。这不仅是为了代码整洁，更是为了应对未来版本升级时，不同模块受影响的程度不同。 以下是我们的标准目录结构，基于Maven构建（Maven是Java事实上的构建标准，几乎所有官方源码仓库项目都采用此结构）： task-manager/ ├── pom.xml ├── src/ │ └── main/ │ ├── java/ │ │ └── com/ │ │ └── example/ │ │ └── taskmanager/ │ │ ├── Main.java # 程序入口 │ │ ├── model/ │ │ │ └── Task.java # 任务实体类 │ │ ├── service/ │ │ │ └── TaskService.java # 业务逻辑层 │ │ └── utils/ │ │ └── JsonUtils.java # JSON读写工具 │ └── resources/ │ └── tasks.json # 数据文件 └── target/关键设计思路：Model层：只定义数据结构，不包含任何业务逻辑。 Service层：处理所有业务规则，比如排序、状态变更。 Utils层：封装通用工具，比如JSON解析。 Main层：只负责接收用户输入，调用Service，输出结果。这种分层架构，在JDK版本升级时，往往只需要改动Utils层或Service层，而Model层几乎不受影响。这就是工程化的价值。 核心代码实现：逐行拆解版本差异 1. 实体类：从POJO到Record 在JDK 14之前，Task类必须写成这样： // 旧版写法（JDK 13及以下） public class Task {private String id;private String title;private int priority;private boolean completed;private String dueDate;// 必须手写构造器、getter、setter、toStringpublic Task(String id, String title, int priority, String dueDate) { ... }public String getId() { return id; }public void setId(String id) { this.id = id; }// ... 其他getter/setter省略 }但在JDK 16+，我们推荐使用Record（记录类）。它是不可变的，且自动生成了构造器、equals、hashCode和toString。 // src/main/java/com/example/taskmanager/model/Task.java package com.example.taskmanager.model;/*** 任务实体类* 使用JDK 16+的Record特性，简化样板代码* 注意：Record是隐式final的，字段不可变*/ public record Task(String id,String title,int priority, // 1=低, 2=中, 3=高boolean completed,String dueDate ) {// 静态工厂方法，用于创建新任务public static Task createNew(String title, int priority, String dueDate) {// 生成简单UUID作为IDString id = java.util.UUID.randomUUID().toString().substring(0, 8);return new Task(id, title, priority, false, dueDate);}// 返回一个标记为已完成的新Task对象（因为Record不可变）public Task markAsCompleted() {return new Task(id, title, priority, true, dueDate);}@Overridepublic String toString() {return String.format([%s] %s (Priority: %d, Due: %s),completed ? DONE : TODO,title,priority,dueDate);} }避坑指南：兼容性：Record是JDK 14预览，JDK 16正式引入。如果你必须兼容JDK 11（很多银行、政府项目仍在使用），则不能使用Record，需回退到传统POJO。 序列化：Record支持标准的Java序列化，但部分JSON库（如老版本的Gson）可能对Record支持不佳，建议测试后再选型。2. 业务逻辑：Stream API vs 传统循环 排序是核心功能。旧代码通常用Collections.sort加匿名内部类，代码冗长且易错。 // src/main/java/com/example/taskmanager/service/TaskService.java package com.example.taskmanager.service;import com.example.taskmanager.model.Task; import java.util.ArrayList; import java.util.Comparator; import java.util.List; import java.util.stream.Collectors;public class TaskService {private final ListTask tasks = new ArrayList();private final JsonUtils jsonUtils;public TaskService(JsonUtils jsonUtils) {this.jsonUtils = jsonUtils;loadTasks();}/*** 添加新任务* 使用Stream API进行校验，比if-else更清晰*/public void addTask(String title, int priority, String dueDate) {// 参数校验：利用Objects.requireNonNull（JDK 7+，但JDK 17有更严格的检查）if (title == null || title.trim().isEmpty()) {throw new IllegalArgumentException(任务标题不能为空);}if (priority 1 || priority 3) {throw new IllegalArgumentException(优先级必须在1-3之间);}Task newTask = Task.createNew(title, priority, dueDate);tasks.add(newTask);saveTasks();}/*** 获取按优先级排序的任务列表* 注意：这里使用了Comparator.comparingInt，这是Stream API的一部分*/public ListTask getSortedTasks() {return tasks.stream().sorted(Comparator.comparingInt(Task::priority).reversed()) // 高优先级在前.collect(Collectors.toList());}/*** 完成任务* 关键：因为Task是Record（不可变），我们不能直接修改对象，* 而是找到索引，替换为一个新的已完成Task对象*/public void completeTask(String id) {int index = findIndexById(id);if (index == -1) {throw new IllegalArgumentException(未找到ID为 + id + 的任务);}Task currentTask = tasks.get(index);Task completedTask = currentTask.markAsCompleted();tasks.set(index, completedTask); // 替换对象，而非修改saveTasks();}private int findIndexById(String id) {for (int i = 0; i tasks.size(); i++) {if (tasks.get(i).id().equals(id)) {return i;}}return -1;}private void loadTasks() {tasks.clear();ListTask loaded = jsonUtils.loadTasks();if (loaded != null) {tasks.addAll(loaded);}}private void saveTasks() {jsonUtils.saveTasks(tasks);} }逐行讲解重点：Task::priority：这是方法引用，比task - task.priority()更简洁，JDK 8引入。 Comparator.reversed()：JDK 8引入，用于反转比较器，避免手动写b.priority() - a.priority()这种容易整数溢出的错误写法。 tasks.set(index, completedTask)：这是应对不可变对象的核心技巧。记住：在Java中，修改集合中的元素，往往是替换引用，而非修改对象内部状态。3. JSON工具：处理版本依赖 JSON处理库众多，但为了减少依赖，我们这里使用Java 11+引入的javax.json（注意：在Java EE模块中，包名是javax.json；在Jakarta EE中，包名变为jakarta.json。这是版本升级最大的坑之一）。 // src/main/java/com/example/taskmanager/utils/JsonUtils.java package com.example.taskmanager.utils;import com.example.taskmanager.model.Task; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.ArrayList; import java.util.List;import javax.json.Json; import javax.json.JsonArray; import javax.json.JsonObject; import javax.json.JsonReader; import javax.json.JsonWriter;/*** JSON读写工具* 依赖：javax.json (JDK 11+ 内置，无需额外jar包)* 注意：JDK 17/21中，javax.json依然可用，但未来可能迁移到jakarta.json*/ public class JsonUtils {private static final Path TASK_FILE = Paths.get(tasks.json);public void saveTasks(ListTask tasks) {try {JsonArray jsonArray = Json.createArrayBuilder().add(tasks.stream().map(this::toJsonObject).toArray()).build();// 使用try-with-resources，确保Writer关闭try (JsonWriter writer = Json.createWriter(Files.newBufferedWriter(TASK_FILE))) {writer.writeArray(jsonArray);}} catch (IOException e) {throw new RuntimeException(保存任务失败, e);}}public ListTask loadTasks() {if (!Files.exists(TASK_FILE)) {return new ArrayList();}ListTask tasks = new ArrayList();try {// 同样使用try-with-resourcestry (JsonReader reader = Json.createReader(Files.newBufferedReader(TASK_FILE))) {JsonArray array = reader.readArray();for (JsonObject obj : array) {tasks.add(fromJsonObject(obj));}}} catch (IOException e) {throw new RuntimeException(加载任务失败, e);}return tasks;}private JsonObject toJsonObject(Task task) {return Json.createObjectBuilder().add(id, task.id()).add(title, task.title()).add(priority, task.priority()).add(completed, task.completed()).add(dueDate, task.dueDate()).build();}private Task fromJsonObject(JsonObject obj) {return new Task(obj.getString(id),obj.getString(title),obj.getInt(priority),obj.getBoolean(completed),obj.getString(dueDate));} }关键避坑：包名冲突：如果你从JDK 10升级到JDK 11，javax.xml等包被移除，javax.json保留。但如果你从Java EE 8升级到Jakarta EE 9（对应JDK 11+的模块化调整），javax.json变成了jakarta.json。务必检查你的依赖来源。 文件IO：Files.newBufferedWriter是NIO.2 API，比旧的FileWriter更高效，且能更好地处理字符编码。运行与测试：从命令行到单元测试 1. 主程序入口 // src/main/java/com/example/taskmanager/Main.java package com.example.taskmanager;import com.example.taskmanager.model.Task; import com.example.taskmanager.service.TaskService; import com.example.taskmanager.utils.JsonUtils;import java.util.List; import java.util.Scanner;public class Main {public static void main(String[] args) {Scanner scanner = new Scanner(System.in);JsonUtils jsonUtils = new JsonUtils();TaskService service = new TaskService(jsonUtils);System.out.println(=== 简易任务管理器 ===);System.out.println(命令: 1-添加 2-查看 3-完成 4-退出);while (true) {System.out.print(\n请输入命令: );String input = scanner.nextLine().trim();switch (input) {case 1:System.out.print(任务标题: );String title = scanner.nextLine().trim();System.out.print(优先级 (1-低, 2-中, 3-高): );int priority = Integer.parseInt(scanner.nextLine().trim());System.out.print(截止日期 (yyyy-MM-dd): );String dueDate = scanner.nextLine().trim();try {service.addTask(title, priority, dueDate);System.out.println(✓ 任务已添加);} catch (Exception e) {System.out.println(✗ 添加失败: + e.getMessage());}break;case 2:ListTask tasks = service.getSortedTasks();if (tasks.isEmpty()) {System.out.println(暂无任务);} else {System.out.println(\n--- 任务列表 ---);tasks.forEach(System.out::println);}break;case 3:System.out.print(输入要完成的任务ID: );String id = scanner.nextLine().trim();try {service.completeTask(id);System.out.println(✓ 任务已完成);} catch (Exception e) {System.out.println(✗ 完成失败: + e.getMessage());}break;case 4:System.out.println(再见！);scanner.close();return;default:System.out.println(未知命令，请重试);}}} }2. 运行步骤初始化项目： mkdir task-manager cd task-manager mvn archetype:generate -DgroupId=com.example -DartifactId=task-manager -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false替换代码：将上述代码文件放入对应目录。 添加依赖：在pom.xml中，确保javax.json依赖已存在（JDK 11+内置，通常无需额外添加；若使用JDK 8，需添加org.glassfish:javax.json:1.1.4）。 编译运行： mvn compile java -cp target/classes com.example.taskmanager.Main3. 单元测试（可选但推荐） 虽然控制台程序难以测试，但我们可以为TaskService写单元测试，确保业务逻辑正确。 // src/test/java/com/example/taskmanager/service/TaskServiceTest.java package com.example.taskmanager.service;import com.example.taskmanager.utils.JsonUtils; import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*;class TaskServiceTest {@Testvoid testAddAndSortTask() {// 使用Mock或真实JsonUtils（指向临时文件）JsonUtils jsonUtils = new JsonUtils();TaskService service = new TaskService(jsonUtils);service.addTask(测试任务A, 1, 2023-12-01);service.addTask(测试任务B, 3, 2023-12-02);service.addTask(测试任务C, 2, 2023-12-03);var tasks = service.getSortedTasks();assertEquals(3, tasks.size());assertEquals(测试任务B, tasks.get(0).title()); // 高优先级在前assertEquals(测试任务C, tasks.get(1).title());assertEquals(测试任务A, tasks.get(2).title());} }优化扩展：面向未来 1. 配置外部化 将tasks.json的路径硬编码在JsonUtils中是不好的。应该通过application.properties或命令行参数传入。 # application.properties task.file.path=data/tasks.json2. 日志记录 引入java.util.logging（JDK内置）或SLF4J，替换System.out.println。 private static final Logger logger = Logger.getLogger(TaskService.class.getName()); logger.info(添加任务: + title);3. 支持JDK 17的虚拟线程（实验性） 如果你的项目未来涉及高并发，JDK 19+引入了虚拟线程。虽然本项目是单线程控制台程序，但了解这一特性有助于你理解Java的性能演进。 小结 这篇java零基础教程，我们从一个简单的项目出发，覆盖了：工程结构：Maven标准目录，模块化设计。 语言特性：Record、Stream API、方法引用、try-with-resources。 版本差异：JDK 11+的javax.json，JDK 16+的Record，以及包名迁移的潜在风险。 最佳实践：不可变对象、分层架构、单元测试。核心启示： 不要死记API，而要理解为什么这样设计。Record是为了简化样板代码，Stream是为了声明式编程，模块化是为了隔离变化。当你理解了这些，版本升级就不再是噩梦，而是进化的机会。 你在项目里踩过这个坑吗？评论区聊聊，比如你从JDK 8升级到17时，遇到的最奇怪的错误是什么？或者你有更好的JSON处理方案？期待你的分享。