# Java 最佳实践 ## 目的该技能为 Java 开发提供了全面的最佳实践，可作为代码审查和架构决策期间的参考指南。它涵盖了 SOLID 原则、DRY、简洁代码、Java 特定模式、测试策略和常见反模式。 **何时使用此技能：** * 对Java项目进行代码审查 * 编写新的Java代码 * 重构现有的Java代码 * 评估架构和设计决策 * 向团队成员教授 Java 最佳实践 * 使用 Spring 框架应用程序 ## 上下文高质量的 Java 代码对于构建可维护、可扩展且健壮的应用程序至关重要。该技能记录了强调以下内容的行业标准实践： * **SOLID 原则**：精心设计的面向对象代码的基础 * **干净的代码**：可读、可维护和自记录的代码 * **Java 特定功能**：正确使用现代 Java 功能 (8+) * **可测试性**：易于测试和验证的代码 * **性能** ：高效利用Java语言和JVM特性 * **Spring 框架**：基于 Spring 的应用程序的最佳实践该技能旨在供“uncle-duke-java”代理在代码审查期间以及开发人员在编写 Java 代码时参考。 ## 先决条件 **所需知识：** * Java 基础知识（Java 8+） * 面向对象的编程概念 * 对设计模式的基本了解 * 熟悉 Spring 框架（针对 Spring 特定部分） **所需工具：** * JDK 8 或更高版本（推荐 11、17 或 21） * 用于构建管理的 Maven 或 Gradle * JUnit 5 用于测试 * Mockito 用于模拟 * 支持 Java 的 IDE（IntelliJ IDEA、Eclipse、VS Code） **预期项目结构：** 项目/ ├── src/ │ ├── 主要/ │ │ ├── java/ │ │ │ └── com/example/ │ │ │ ├── 型号/ │ │ │ ├──服务/ │ │ │ ├── 仓库/ │ │ │ ├── 控制器/ │ │ │ └── util/ │ │ └── 资源/ │ │ └── 应用程序.properties │ └── 测试/ │ └── java/ │ └── com/例子/ ├── pom.xml（或build.gradle） └── 自述文件.md ** ** ## Java 的坚实原则 ### 单一职责原则 (SRP) **规则：** 一个类应该只有一个改变的理由。每个类都应该有一个单一的、明确定义的职责。 **为什么重要：** 具有多重职责的类更难理解、测试和维护。一项职责的改变可能会影响其他职责。 #### SRP 实践 ❌ **坏 - 多重责任：** // 此类违反了 SRP：它处理用户数据、验证、持久性和电子邮件公共类用户{ 私人字符串电子邮件；私有字符串密码； // 职责1：数据验证公共布尔 isValid() { 返回电子邮件！= null && email.contains("@") && 密码 != null && 密码.length() >= 8; } // 职责2：数据库操作公共无效保存（）{ 连接 conn = DriverManager.getConnection("jdbc:..."); PreparedStatement ps = conn.prepareStatement("插入用户..."); ps.setString(1, 电子邮件); ps.setString(2, 密码); ps.executeUpdate(); } // 职责3：邮件操作公共无效sendWelcomeEmail（）{ EmailService.send(email, "欢迎！", "欢迎使用我们的应用程序"); } // 职责4：密码加密公共无效加密密码（）{ this.password = BCrypt.hashpw(密码, BCrypt.gensalt()); } } **问题：** * 用户类有 4 个职责：数据、验证、持久化、电子邮件 * 验证逻辑的更改会影响 User 类 * 数据库模式的更改会影响 User 类 * 电子邮件模板的更改会影响用户类别 * 难以测试个人职责 ✅ **好 - 单一职责：** // 职责：保存用户数据公共类用户{ 私人最终字符串电子邮件；私有最终字符串密码哈希；公共用户（字符串电子邮件，字符串密码哈希）{ this.email = 电子邮件； this.passwordHash = 密码Hash; } 公共字符串 getEmail() { 返回电子邮件; } 公共字符串 getPasswordHash() { 返回密码Hash; } } // 职责：验证用户数据公共类用户验证器{ 公共 ValidationResult 验证（字符串电子邮件，字符串密码）{ List 错误 = new ArrayList<>(); if (email == null || !email.contains("@")) { error.add("电子邮件格式无效"); } if (密码 == null || 密码.length() < 8) { error.add("密码必须至少8个字符"); } 返回新的 ValidationResult(errors.isEmpty(), 错误); } } // 职责：保存用户数据公共类用户存储库{ 私有最终数据源数据源；公共 UserRepository（数据源 dataSource）{ this.dataSource = 数据源; } 公共无效保存（用户用户）{ 尝试 (连接 conn = dataSource.getConnection(); 准备语句 ps = conn.prepareStatement( “插入用户（电子邮件、密码哈希）值（？、？）”））{ ps.setString(1, user.getEmail()); ps.setString(2, user.getPasswordHash()); ps.executeUpdate(); } catch (SQLException e) { throw new DataAccessException("无法保存用户", e); } } } // 职责：发送电子邮件公共类电子邮件服务{ 公共无效sendWelcomeEmail（用户用户）{ send(user.getEmail(), "欢迎！", "欢迎使用我们的应用程序"); } 私有无效发送（字符串到，字符串主题，字符串正文）{ // 邮件发送逻辑 } } // 职责：哈希密码公共类密码编码器{ 公共字符串编码（字符串rawPassword）{ 返回 BCrypt.hashpw(rawPassword, BCrypt.gensalt()); } 公共布尔匹配（字符串原始密码，字符串编码密码）{ 返回 BCrypt.checkpw(rawPassword,encodedPassword); } } **好处：** * 每个班级都有明确的职责 * 易于单独测试每个职责 * 一个问题的改变不会影响其他问题 * 小班授课，重点突出 ### 开闭原则 (OCP) **规则：** 软件实体（类、模块、函数）应该对扩展开放，但对修改关闭。 **为什么重要：** 您应该能够在不更改现有代码的情况下添加新功能，从而降低破坏现有功能的风险。 #### OCP 实践 ❌ **不好 - 违反 OCP：** 公共类支付处理器{ 公共无效processPayment（字符串付款类型，双倍金额）{ if ( paymentType.equals("CREDIT_CARD")) { // 处理信用卡付款 System.out.println("处理信用卡付款：$" + amount); } else if ( paymentType.equals("PAYPAL")) { // 处理PayPal付款 System.out.println("正在处理 PayPal 付款：$" + 金额); } else if ( paymentType.equals("BITCOIN")) { // 处理比特币支付 System.out.println("正在处理比特币支付：$" + amount); } // 添加新的支付方式需要修改这个类！ } } **问题：** * 必须修改PaymentProcessor以添加新的支付类型 * 违反OCP（不关闭修改） * 不断增长的 if-else 链 * 难以测试个别支付类型 ✅ **好 - 遵循 OCP：** // 抽象支付接口公共接口支付方法{ 无效流程（双倍金额）； } // 具体实现公共类 CreditCardPayment 实现 PaymentMethod { @覆盖公共无效过程（双倍金额）{ System.out.println("处理信用卡付款：$" + amount); // 信用卡具体逻辑 } } 公共类 PayPalPayment 实现 PaymentMethod { @覆盖公共无效过程（双倍金额）{ System.out.println("正在处理 PayPal 付款：$" + 金额); // PayPal具体逻辑 } } 公共类 BitcoinPayment 实现 PaymentMethod { @覆盖公共无效过程（双倍金额）{ System.out.println("正在处理比特币支付：$" + amount); // 比特币具体逻辑 } } // 处理器委托付款方式公共类支付处理器{ 公共无效processPayment（PaymentMethod paymentMethod，双倍金额）{ paymentMethod.process(金额); } } // 用法 PaymentProcessor 处理器 = new PaymentProcessor(); 处理器.processPayment(new CreditCardPayment(), 100.0); 处理器.processPayment(new PayPalPayment(), 50.0); // 添加新的支付方式：只需创建新类，无需修改！公共类 ApplePayPayment 实现 PaymentMethod { @覆盖公共无效过程（双倍金额）{ System.out.println("正在处理 Apple Pay 付款：$" + 金额); } } **好处：** * 添加新的支付方式，无需修改现有代码 * 每种支付类型均可独立测试 * 遵循OCP：对扩展开放，对修改关闭 * 清晰的关注点分离 #### OCP 与策略模式 ✅ **高级示例 - 折扣策略：** // 策略接口公共接口折扣策略{ double applyDiscount(双倍价格); } // 具体策略公共类 NoDiscount 实现 DiscountStrategy { @覆盖公共双applyDiscount（双倍价格）{ 退货价格； } } 公共类 PercentageDiscount 实现 DiscountStrategy { 私人最终双倍百分比；公共百分比折扣（双倍百分比）{ this.percentage = 百分比； } @覆盖公共双applyDiscount（双倍价格）{ 退货价格*（1 - 百分比/100）； } } 公共类FixedAmountDiscount实现DiscountStrategy { 私人最终双倍金额；公共固定金额折扣（双倍金额）{ this.金额 = 金额； } @覆盖公共双applyDiscount（双倍价格）{ return Math.max(0, 价格 - 金额); } } // 上下文使用策略公共类价格计算器{ 私人最终 DiscountStrategy 折扣策略；公共 PriceCalculator(DiscountStrategy 折扣策略) { this.discountStrategy =discountStrategy; } 公共双计算最终价格（双原始价格）{ return discountStrategy.applyDiscount(originalPrice); } } // 用法 PriceCalculator calc1 = new PriceCalculator(new PercentageDiscount(10)); 双倍价格1 = calc1.calculateFinalPrice(100); // 90.0 PriceCalculator calc2 = new PriceCalculator(new FixAmountDiscount(15)); 双倍价格2 = calc2.calculateFinalPrice(100); // 85.0 ### 里氏替换原理 (LSP) **规则：** 超类的对象应该可以用子类的对象替换，而不会破坏应用程序。子类型必须可替换其基本类型。 **为什么重要：** 违反 LSP 会导致意外行为并破坏多态性。 #### LSP 实践 ❌ **不好 - 违反 LSP：** 公共类矩形{ 受保护的 int 宽度；受保护的 int 高度；公共无效setWidth（int宽度）{ this.width = 宽度； } 公共无效setHeight（int高度）{ this.height = 高度； } 公共 int getArea() { 返回宽度*高度； } } // Square 违反了 LSP，因为它改变了 setter 的行为公共类 Square 扩展 Rectangle { @覆盖公共无效setWidth（int宽度）{ this.width = 宽度； this.高度=宽度； // 副作用！ } @覆盖公共无效setHeight（int高度）{ this.宽度=高度； // 副作用！ this.height = 高度； } } // 此测试适用于矩形，但不适用于正方形公共无效测试矩形（矩形矩形）{ 矩形.setWidth(5); 矩形.setHeight(4); assertEquals(20, rect.getArea()); // Square 失败！（25 而不是 20） } **问题：** * Square 改变了 Rectangle 方法的行为 * 不能用正方形代替矩形 * 违反LSP并破坏多态性 ✅ **好 - 遵循 LSP：** // 形状的通用接口公共接口形状{ int getArea(); } // 矩形实现公共类矩形实现形状{ 私有最终 int 宽度；私有最终 int 高度；公共矩形（int宽度，int高度）{ this.width = 宽度； this.height = 高度； } @覆盖公共 int getArea() { 返回宽度*高度； } 公共 int getWidth() { 返回宽度; } 公共 int getHeight() { 返回高度; } } // Square 实现（没有继承自 Rectangle）公共类 Square 实现 Shape { 私有最终 int 侧；公共广场(int side) { this.side = 边； } @覆盖公共 int getArea() { 返回边*边； } 公共 int getSide() { 返回一面; } } // 适用于任何形状公共 int 计算TotalArea（列表<形状>形状）{ 返回shapes.stream() .mapToInt(形状::getArea) .sum(); } **好处：** * 正方形和矩形是独立的 * 两者都正确实现了 Shape 契约 * 可以替代任何 Shape 实现 * 没有意外的行为 #### LSP - 前置条件和后置条件 ✅ **好 - 维持合同：** 公共接口银行账户{ // 前提条件：金额 > 0 // 后置条件：余额增加金额作废存款（双倍金额）； // 前提条件：金额 > 0 且金额 <= 余额 // 后置条件：余额减少了数量 voidwithdraw(double amount) 抛出InsufficientFundsException；双 getBalance(); } 公共类 SavingsAccount 实现 BankAccount { 私人双重余额； @覆盖公共无效存款（双倍金额）{ 如果（金额 <= 0）{ throw new IllegalArgumentException("金额必须为正数"); } 余额+=金额； } @覆盖公共无效提款（双倍金额）抛出 InsufficientFundsException { 如果（金额 <= 0）{ throw new IllegalArgumentException("金额必须为正数"); } 如果（金额 > 余额）{ 抛出新的 InsufficientFundsException(); } 余额-=金额； } @覆盖公共双 getBalance() { 返回余额； } } // 子类维护合约（LSP）公共类 CheckingAccount 实现 BankAccount { 私人双重余额；私人最终双倍透支限额；公共CheckingAccount（双透支限额）{ this.overdraftLimit = 透支限额； } @覆盖公共无效存款（双倍金额）{ 如果（金额 <= 0）{ throw new IllegalArgumentException("金额必须为正数"); } 余额+=金额； // 相同的后置条件 } @覆盖公共无效提款（双倍金额）抛出 InsufficientFundsException { 如果（金额 <= 0）{ throw new IllegalArgumentException("金额必须为正数"); } // 可以削弱前提条件（允许透支）但不能加强 if (金额 > 余额 + 透支限额) { 抛出新的 InsufficientFundsException(); } 余额-=金额； // 相同的后置条件 } @覆盖公共双 getBalance() { 返回余额； } } ### 接口隔离原则（ISP） **规则：** 客户端不应被迫依赖他们不使用的接口。许多特定接口比一种通用接口更好。 **为什么重要：** 大型接口迫使实现提供它们不需要的方法，导致空实现和紧密耦合。 #### ISP 实践 ❌ **糟糕 - 胖接口：** // Fat 接口强制所有实现提供所有方法公共接口工人{ 无效工作（）；无效吃（）；无效睡眠（）；无效 getSalary(); 无效出席会议（）； } // 机器人不吃饭不睡觉却被迫实现这些方法公共类 RobotWorker 实现 Worker { @覆盖公共无效工作（）{ System.out.println("机器人正在工作"); } @覆盖公共无效吃（）{ // 对机器人来说没有意义！ throw new UnsupportedOperationException("机器人不吃东西"); } @覆盖公共无效睡眠（）{ // 对机器人来说没有意义！ throw new UnsupportedOperationException("机器人不睡觉"); } @覆盖公共无效 getSalary() { throw new UnsupportedOperationException("机器人没有得到报酬"); } @覆盖公共无效出席会议（）{ System.out.println("机器人参加会议"); } } **问题：** * 机器人被迫实施生物方法 * 抛出 UnsupportedOperationException 是一种代码味道 * 违反 ISP * 与不相关方法的紧密耦合 ✅ **好 - 隔离接口：** // 隔离的接口 - 客户端仅取决于他们需要什么公共接口可行{ 无效工作（）； } 公共接口可吃{ 无效吃（）； } 公共接口可休眠{ 无效睡眠（）； } 公共接口应付{ 无效 getSalary(); } 公共接口 MeetingAttendee { 无效出席会议（）； } // 人类实现相关接口公共类 HumanWorker 实现 Workable、Eatable、Sleepable、Payable、MeetingAttendee { @覆盖公共无效工作（）{ System.out.println("人类工作"); } @覆盖公共无效吃（）{ System.out.println("人类在吃东西"); } @覆盖公共无效睡眠（）{ System.out.println("人类在睡觉"); } @覆盖公共无效 getSalary() { System.out.println("人类领取工资"); } @覆盖公共无效出席会议（）{ System.out.println("有人参加会议"); } } // Robot只实现相关接口公共类 RobotWorker 实现 Workable、MeetingAttendee { @覆盖公共无效工作（）{ System.out.println("机器人正在工作"); } @覆盖公共无效出席会议（）{ System.out.println("机器人参加会议"); } } **好处：** * 实现只提供有意义的方法 * 不需要UnsupportedOperationException * 清晰的关注点分离 * 灵活的组合 ### 依赖倒置原则（DIP） **规则：** 高级模块不应依赖于低级模块。两者都应该依赖于抽象。抽象不应该依赖于细节。细节应该取决于抽象。 **为什么重要：** DIP 解耦了代码，使其更加灵活、可测试和可维护。 #### DIP 实践 ❌ **不好 - 高级别依赖于低级别：** // 底层模块公共类 MySQLDatabase { 公共无效保存（字符串数据）{ System.out.println("保存到MySQL：" + data); } } // 高层模块依赖于具体的低层模块公共类用户服务{ 私有MySQL数据库； // 具体依赖！公共用户服务（）{ this.database = new MySQLDatabase(); // 紧耦合！ } 公共无效createUser（字符串用户数据）{ // 业务逻辑数据库.保存（用户数据）； } } **问题：** * UserService与MySQLDatabase紧密耦合 * 不修改UserService就无法切换到PostgreSQL * 难以测试（无法模拟数据库） * 违反 DIP ✅ **好 - 两者都依赖于抽象：** // 抽象公共接口数据库{ 无效保存（字符串数据）； } // 低级模块依赖于抽象公共类 MySQLDatabase 实现数据库 { @覆盖公共无效保存（字符串数据）{ System.out.println("保存到MySQL：" + data); } } 公共类 PostgreSQLDatabase 实现数据库 { @覆盖公共无效保存（字符串数据）{ System.out.println("保存到PostgreSQL：" + data); } } 公共类 MongoDatabase 实现数据库 { @覆盖公共无效保存（字符串数据）{ System.out.println("保存到MongoDB：" + data); } } // 高层模块依赖于抽象公共类用户服务{ 私有最终数据库数据库； // 抽象！ // 通过构造函数注入依赖公共UserService（数据库数据库）{ this.database = 数据库； } 公共无效createUser（字符串用户数据）{ // 业务逻辑数据库.保存（用户数据）； } } // 用法 - 客户端选择实现数据库 db = new MySQLDatabase(); UserService 服务 = new UserService(db); service.createUser("约翰·多伊"); // 轻松切换实现数据库 postgresDb = new PostgreSQLDatabase(); UserService postgresService = new UserService(postgresDb); // 易于使用mock进行测试数据库mockDb = mock(Database.class); UserService testService = new UserService(mockDb); **好处：** * UserService与数据库实现解耦 * 轻松切换数据库实现 * 易于使用模拟进行测试 * 遵循 DIP ### Spring 框架中的坚实原则 Spring 框架建立在 SOLID 原则之上，特别是依赖倒置。 #### Spring 中的依赖注入 ✅ **Spring DI 示例：** // 抽象公共接口用户存储库{ 用户findById(长id); 无效保存（用户用户）； } // 实现 @存储库公共类 JpaUserRepository 实现 UserRepository { @PersistenceContext 私有EntityManager实体管理器； @覆盖公共用户findById（长id）{ 返回entityManager.find(User.class, id); } @覆盖公共无效保存（用户用户）{ 实体管理器.persist(用户); } } // 服务依赖于抽象 @服务公共类用户服务{ 私有最终 UserRepository userRepository; // 构造函数注入（推荐）公共 UserService(UserRepository userRepository) { this.userRepository = userRepository; } 公共用户 getUser(长 id) { 返回 userRepository.findById(id); } } // 控制器依赖于服务抽象 @RestController @RequestMapping("/用户") 公共类用户控制器{ 私有最终 UserService userService；公共 UserController(UserService userService) { this.userService = userService; } @GetMapping("/{id}") 公共 ResponseEntity getUser(@PathVariable Long id) { 用户 user = userService.getUser(id); 返回 ResponseEntity.ok(用户); } } **Spring DI 最佳实践：** * 使用构造函数注入（必需的依赖项、不变性） * 仅对可选依赖项首选字段注入 * 依赖于接口，而不是具体的类 * 当存在多个实现时使用`@Qualifier` ** ** ## DRY（不要重复） **规则：** 每条知识都必须在系统内有一个单一的、明确的、权威的表示。 **为什么重要：** 重复会导致不一致、更难维护和更多错误。 ### 识别代码重复 ❌ **不好 - 明显重复：** 公共类 OrderService { 公共无效processOnlineOrder（订单订单）{ // 验证如果（订单==空）{ throw new IllegalArgumentException("订单不能为空"); } if (order.getItems().isEmpty()) { throw new IllegalArgumentException("订单必须有商品"); } if (order.getTotalAmount() <= 0) { throw new IllegalArgumentException("订单总数必须为正"); } // 处理 System.out.println("正在处理在线订单：" + order.getId()); order.setStatus(OrderStatus.PROCESSING); 保存订单（订单）； } 公共无效processPhoneOrder（订单订单）{ // 相同的验证 - 重复！如果（订单==空）{ throw new IllegalArgumentException("订单不能为空"); } if (order.getItems().isEmpty()) { throw new IllegalArgumentException("订单必须有商品"); } if (order.getTotalAmount() <= 0) { throw new IllegalArgumentException("订单总数必须为正"); } // 处理 System.out.println("正在处理电话订单：" + order.getId()); order.setStatus(OrderStatus.PROCESSING); 保存订单（订单）； } } ✅ **好 - 提取通用逻辑：** 公共类 OrderService { 公共无效processOnlineOrder（订单订单）{ 验证订单（订单）； processOrder(订单, "在线"); } 公共无效processPhoneOrder（订单订单）{ 验证订单（订单）； processOrder(订单,“电话”); } 私人无效validateOrder（订单订单）{ 如果（订单==空）{ throw new IllegalArgumentException("订单不能为空"); } if (order.getItems().isEmpty()) { throw new IllegalArgumentException("订单必须有商品"); } if (order.getTotalAmount() <= 0) { throw new IllegalArgumentException("订单总数必须为正"); } } private void processOrder(订单顺序, String类型) { System.out.println("正在处理" + type + "订单：" + order.getId()); order.setStatus(OrderStatus.PROCESSING); 保存订单（订单）； } } ### 实用程序类和辅助方法 ✅ **为可重用逻辑创建实用程序类：** 公共最终类 StringUtils { 私有 StringUtils() { // 防止实例化 } 公共静态布尔 isBlank(String str) { 返回 str == null || str.trim().isEmpty(); } 公共静态字符串大写（字符串str）{ if (isBlank(str)) { 返回字符串； } 返回 str.substring(0, 1).toUpperCase() + str.substring(1).toLowerCase(); } 公共静态字符串截断（字符串str，int maxLength）{ if (str == null || str.length() <= maxLength) { 返回字符串； } 返回 str.substring(0, maxLength) + "..."; } } // 用法 if (StringUtils.isBlank(用户名)) { throw new ValidationException("需要用户名"); } String displayName = StringUtils.capitalize(name); ### 可重用性泛型 ✅ **使用泛型避免重复：** // 而不是为不同类型创建单独的类公共类 GenericRepository { 私有最终类实体类； @PersistenceContext 私有EntityManager实体管理器；公共 GenericRepository（类实体类）{ this.entityClass = 实体类; } 公共可选 findById(ID id) { T 实体=entityManager.find(entityClass, id); 返回Optional.ofNullable(实体); } 公共列表 findAll() { CriteriaQuery 查询 =EntityManager.getCriteriaBuilder() .createQuery(entityClass); query.select(query.from(entityClass)); 返回entityManager.createQuery(query).getResultList(); } 公共无效保存（T实体）{ 实体管理器.persist(实体); } 公共无效删除（T实体）{ 实体管理器.删除(实体); } } // 具体存储库扩展了通用存储库 @存储库公共类 UserRepository 扩展 GenericRepository { 公共用户存储库（）{ 超级(用户.类); } // 添加用户特定的查询公共可选<用户> findByEmail（字符串电子邮件）{ // 自定义查询 } } ** ** ## 整洁代码原则 ### 有意义的名字 **规则：** 名称应揭示意图、可发音且可搜索。 ❌ **坏名字：** 整数d； // 经过的时间（以天为单位）字符串 yyyymmdd；列表列表1; 公共无效 getData() { // 什么数据？ } ✅ **好名字：** int elapsedTimeInDays；字符串格式化日期；列表<客户> activeCustomers；公共客户 getCustomerById(Long customerId) { // 明确这个方法的作用 } #### 命名约定 // 类：PascalCase、名词公共类客户服务{} 公共类 OrderRepository { } // 接口：PascalCase，通常是形容词或名词公共接口可序列化{} 公共接口 UserRepository { } // 方法：驼峰命名法、动词公共无效计算总计（）{} 公共客户 findCustomerById(长 id) { } // 变量：驼峰命名法、名词字符串客户名称； int 订单计数；布尔值是否处于活动状态； // 常量：UPPER_SNAKE_CASE 公共静态最终 int MAX_RETRY_COUNT = 3; 公共静态最终字符串DEFAULT_ENCODING =“UTF-8”； // 包：小写、句点包com.example.service；包 com.example.repository; // 布尔方法/变量：is、has、can 布尔值 isValid(); 布尔值 hasPermission(); 布尔值可以执行（）； ### 函数大小和复杂性 **规则：** 函数应该很小并且只做一件事。每个方法的目标是 5-20 行。 ❌ **不好 - 大型、复杂的方法：** 公共无效processOrder（订单顺序）{ // 验证 if (order == null) 抛出 new IllegalArgumentException(); if (order.getItems().isEmpty()) 抛出新的 IllegalArgumentException(); // 计算总数双倍总计 = 0； for (OrderItem 项目: order.getItems()) { 双 itemPrice = item.getPrice(); int 数量 = item.getQuantity(); 双倍折扣 = item.getDiscount(); 总计+=（商品价格*数量）*（1-折扣）； } order.setTotal(总计); // 应用优惠券 if (order.getCoupon() != null) { String couponCode = order.getCoupon().getCode(); if (couponCode.startsWith("SAVE")) { 总计 *= 0.9； } else if (couponCode.startsWith("BIG")) { 总计 *= 0.8； } order.setTotal(总计); } // 检查库存 for (OrderItem 项目: order.getItems()) { int available = inventoryService.getAvailableQuantity(item.getProductId()); if (可用 < item.getQuantity()) { 抛出新的 InsufficientInventoryException(); } } // 保存订单 orderRepository.save(order); // 发送电子邮件 emailService.send(order.getCustomer().getEmail(), "订单确认", "您的订单 " + order.getId() + " 已确认"); // 更新库存 for (OrderItem 项目: order.getItems()) { inventoryService.decrementQuantity(item.getProductId(), item.getQuantity()); } } ✅ **好 - 小而集中的方法：** 公共无效processOrder（订单顺序）{ 验证订单（订单）；计算订单总计（订单）；应用优惠券折扣（订单）；检查库存可用性（订单）；保存订单（订单）；发送确认电子邮件（订单）；更新库存（订单）； } 私人无效validateOrder（订单订单）{ 如果（订单==空）{ throw new IllegalArgumentException("订单不能为空"); } if (order.getItems().isEmpty()) { throw new IllegalArgumentException("订单必须包含商品"); } } 私有无效calculateOrderTotal（订单订单）{ 双总计 = order.getItems().stream() .mapToDouble(this::calculateItemTotal) .sum(); order.setTotal(总计); } 私有双计算ItemTotal（OrderItem项目）{ 返回 item.getPrice() * item.getQuantity() * (1 - item.getDiscount()); } 私人无效 applyCouponDiscount（订单订单）{ if (order.getCoupon() == null) { 返回； } 双折扣Multiplier = getDiscountMultiplier(order.getCoupon()); order.setTotal(order.getTotal() *discountMultiplier); } private double getDiscountMultiplier(优惠券优惠券) { 字符串代码 = coupon.getCode(); if (code.startsWith("SAVE")) 返回 0.9; if (code.startsWith("BIG")) 返回 0.8；返回 1.0； } 私人无效checkInventoryAvailability（订单订单）{ for (OrderItem 项目: order.getItems()) { int available = inventoryService.getAvailableQuantity(item.getProductId()); if (可用 < item.getQuantity()) { 抛出新的InsufficientInventoryException（ "产品" + item.getProductId() + "库存不足"); } } } 私人无效 saveOrder（订单顺序）{ orderRepository.save(order); } 私人无效sendConfirmationEmail（订单订单）{ String email = order.getCustomer().getEmail(); String subject = "订单确认"; String body = String.format("您的订单%s已确认", order.getId()); emailService.send(电子邮件、主题、正文); } 私人无效updateInventory（订单订单）{ order.getItems().forEach(项目 -> inventoryService.decrementQuantity(item.getProductId(), item.getQuantity()) ）； } **好处：** * 每种方法都有明确、单一的目的 * 易于理解和测试 * Main方法读起来就像一个目录 * 可重用的辅助方法 ### 评论最佳实践 **规则：** 代码应该是不言自明的。评论应该解释“为什么”，而不是“什么”。 ❌ **差评：** // 将标志设置为 true 有效=真； // 循环遍历用户对于（用户用户：用户）{ // 检查用户是否活跃 if (user.isActive()) { // 添加到列表 activeUsers.add(用户); } } // 这是 UserService 类公共类用户服务{ } ✅ **好评：** // 不需要注释 - 代码是不言自明的有效=真；列表<用户> activeUsers = users.stream() .filter(用户::isActive) .collect(Collectors.toList()); // 好：解释“为什么”，而不是“什么” // 我们使用指数退避来避免压垮外部 API // 多次失败后（断路器模式）私有 intcalculateRetryDelay(int attemptsNumber) { return (int) Math.pow(2, attemptsNumber) * 1000; } // 好：公共 API 的 JavaDoc /** * 在账户之间自动转移资金。 * * @param fromAccount 源账户（必须有足够的余额） * @param toAccount 目标账户 * @param amount 转账金额（必须为正数） * 如果源帐户缺少资金，则抛出 InsufficientFundsException * 如果金额为负数或零则@抛出 IllegalArgumentException */ public voidtransferFunds(账户从账户，账户到账户，双倍金额) 抛出 InsufficientFundsException { // 实现 } // 好：解释了不明显的业务规则 // 税费计算不包括运费，但包括折扣调整 // 根据 IRS 法规 2024-15 double 应税金额 = 小计 - 折扣； **何时发表评论：** * 公共 API (JavaDoc) * 复杂算法（解释方法） * 业务规则（监管要求） * 解决方法（为什么需要解决方法） * TODO/FIXME（带有票号） **何时不发表评论：** * 明显的代码 * 注释掉的代码（删除它，使用版本控制） * 更改日志（使用git） ### 错误处理 **规则：** 对于特殊情况使用例外。不要使用异常来控制流程。 ❌ **错误处理错误：** // 使用异常来控制流程公共用户findUser（长id）{ 尝试{ 返回 userRepository.findById(id); } catch (NotFoundException e) { 返回空值； // 吞没异常 } } // 捕获通用异常公共无效processData（字符串数据）{ 尝试{ // 复杂逻辑 } catch (异常 e) { // 太宽泛了！ } } // 空catch块尝试{ 有风险的操作（）； } catch (IOException e) { // 被忽略 - 永远不要这样做 } ✅ **良好的错误处理：** // 对于“未找到”场景使用Optional 公共可选<用户> findUser（长id）{ 返回 userRepository.findById(id); } // 捕获特定的异常公共无效processData（字符串数据）{ 尝试{ 解析并验证（数据）；保存到数据库（数据）； } catch (JsonParseException e) { log.error("解析 JSON 数据失败：{}", data, e); throw new DataProcessingException("无效的 JSON 格式", e); } catch (DataAccessException e) { log.error("保存数据时数据库出错", e); throw new DataProcessingException("保存数据失败", e); } } // 总是处理或重新抛出异常尝试{ 有风险的操作（）； } catch (IOException e) { log.error("操作失败", e); throw new ApplicationException("执行操作失败", e); } // 使用 try-with-resources 来自动关闭资源公共字符串readFile（字符串路径）抛出IOException { 尝试 (BufferedReader reader = new BufferedReader(new FileReader(path))) { return reader.lines().collect(Collectors.joining("\n")); } // Reader自动关闭，即使发生异常 } ### 代码组织 **规则：** 在类内逻辑地组织代码。相关方法应该紧密结合在一起。 ✅ **良好的班级组织：** 公共类用户服务{ // 1. 常量私有静态最终 int MAX_LOGIN_ATTEMPTS = 3; 私有静态最终长 LOCKOUT_DURATION_MINUTES = 30; // 2. 静态字段私有静态最终 Logger 日志 = LoggerFactory.getLogger(UserService.class); // 3. 实例字段私有最终 UserRepository userRepository; 私人最终密码编码器密码编码器；私人最终电子邮件服务电子邮件服务； // 4. 构造函数公共 UserService(UserRepository userRepository, 密码编码器密码编码器，电子邮件服务电子邮件服务）{ this.userRepository = userRepository; this.passwordEncoder = 密码编码器； this.emailService = emailService; } // 5. 公共方法（按功能分组） // 用户创建方法公共用户注册用户（UserRegistrationDto dto）{ 验证注册（dto）；用户 user = createUser(dto); 发送欢迎电子邮件（用户）；返回用户； } // 用户认证方法公共AuthToken登录（字符串电子邮件，字符串密码）{ 用户 user = findUserByEmail(电子邮件); 验证密码（用户，密码）；返回generateAuthToken（用户）； } // 6. 私有辅助方法（使用它们的近方法）私有无效 validateRegistration(UserRegistrationDto dto) { // 验证逻辑 } 私人用户createUser（UserRegistrationDto dto）{ // 创建逻辑 } 私人无效sendWelcomeEmail（用户用户）{ emailService.send(user.getEmail(), "欢迎！", getWelcomeEmailBody()); } 私人用户findUserByEmail（字符串电子邮件）{ 返回 userRepository.findByEmail(电子邮件) .orElseThrow(() -> new UserNotFoundException(email)); } private void validatePassword(用户用户，字符串密码) { if (!passwordEncoder.matches(password, user.getPasswordHash())) { throw new AuthenticationException("密码无效"); } } 私人AuthToken生成AuthToken（用户用户）{ // 令牌生成逻辑 } 私有字符串 getWelcomeEmailBody() { return“欢迎使用我们的应用程序！”； } } ** ** ## Java 特定的最佳实践 ### 使用Optional代替Null **规则：** 使用 `Optional` 来表示可能不存在的值。永远不要为集合返回 null。 ❌ **不好 - 返回 Null：** 公共用户findUser（长id）{ 用户 user = 数据库.find(id); 返回用户； // 可能返回 null！ } // 调用者必须记住检查 null 用户 user = findUser(123L); 如果（用户！=空）{ // 使用用户 } ✅ **好 - 使用可选：** 公共可选<用户> findUser（长id）{ 用户 user = 数据库.find(id); 返回Optional.ofNullable(用户); } // 调用者被迫处理缺席情况可选<用户> userOpt = findUser(123L); // 方法一：ifPresent userOpt.ifPresent(用户 -> System.out.println(user.getName())); // 方法二：orElse 用户 user = userOpt.orElse(createDefaultUser()); // 方法三：orElseThrow 用户 user = userOpt.orElseThrow(() -> new UserNotFoundException("未找到用户 123")); // 方法四：map/flatMap 字符串电子邮件 = userOpt .map(用户::getEmail) .orElse("unknown@example.com"); **可选最佳实践：** * 从可能找不到值的方法返回 `Optional` * 切勿对字段使用“Optional” * 切勿将“Optional”作为方法参数传递 * 永远不要从“Optional”返回方法返回 null * 使用`Optional.empty()`代替`Optional.ofNullable(null)` ❌ **错误的可选用法：** // 不要使用Optional作为字段公共类用户{ 私有可选 middleName; // 坏的！ } // 不要使用Optional作为参数 public void setEmail(Optional email) { // 不好！ } // 未经检查请勿调用 get() 可选<用户> userOpt = findUser(id); 用户 user = userOpt.get(); // 可能会抛出 NoSuchElementException！ ✅ **良好的可选用法：** // 对可选字段使用 null（或使用正确的 null 处理）公共类用户{ 私有字符串中间名； // 可以为空公共可选 getMiddleName() { 返回Optional.ofNullable(middleName); } } // 使用带有@Nullable注解的常规参数公共无效setEmail（@Nullable String电子邮件）{ this.email = 电子邮件； } // 始终在 get() 之前进行检查，或者使用其他方法可选<用户> userOpt = findUser(id); 如果 (userOpt.isPresent()) { 用户 user = userOpt.get(); // 使用用户 } // 或者使用 orElse/orElseThrow/ifPresent 用户 user = userOpt.orElseThrow(() -> new NotFoundException()); ### 更喜欢组合而不是继承 **规则：** 优先使用组合 (has-a) 而不是继承 (is-a)，除非存在真正的 is-a 关系。 ❌ **不好 - 继承滥用：** // 继承只是为了重用代码（错误！）公共类 Stack 扩展 ArrayList

Java 最佳实践

包含技能