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处理方案？期待你的分享。
