Java / 系统课时

项目结构规范与代码组织

项目结构规范与代码组织

当 Java 项目从单个文件发展为多个类时,需要将入口、业务逻辑、数据模型、资源和测试分开管理。本课使用 Maven 标准目录组织一个商品折扣程序,演示包声明、类职责和依赖方向,并通过编译运行验证项目结构是否正确。

学习目标

  • 掌握 Maven 标准目录与 Java 包路径的对应规则。
  • 能按模型、服务和入口划分类职责,避免不必要的反向依赖。
  • 能创建、运行并验证一个具有规范目录结构的小型 Java 项目。

标准目录与文件职责

Maven 约定了源代码、资源、测试和构建配置的位置。遵循这些约定,IDE 与构建工具便能识别相应目录,减少手动配置。

路径 职责
pom.xml 定义项目坐标、编译版本和依赖
src/main/java 保存生产 Java 源码
src/main/resources 保存配置文件、模板等运行时资源
src/test/java 保存测试源码
src/test/resources 保存测试专用资源
target 保存 Maven 生成的编译与打包产物

target 由构建工具生成,通常不提交到 Git。资源文件应通过类路径读取,不要假定程序运行时的工作目录始终是项目根目录。密码、令牌等敏感信息也不应直接写入并提交到资源文件。

包结构与依赖方向

以商品折扣程序为例,使用 com.example.shop 作为基础包,并按职责划分三个子包:

  • model:保存商品的数据结构 Product。
  • service:保存价格计算逻辑 PricingService。
  • app:保存程序入口 Main,负责组装对象和调用服务。

Java 的包声明应与源码根目录下的相对路径一致。例如 package com.example.shop.model; 对应 src/main/java/com/example/shop/model/Product.java。推荐使用反向域名命名包,避免将多个类长期放在默认包中。

入口依赖服务和模型,服务依赖模型,模型不反向依赖入口。这样可以单独测试价格计算,而不必启动整个应用。业务规模较大时,可先按订单、商品等业务模块组织,再划分模块内部职责。

商品折扣程序的包结构与单向依赖关系

创建并运行规范项目

下面将原来集中在 Main.java 中的三个类拆分为独立文件。示例使用 Java 17 或更高版本,以支持 record,并使用 Maven 完成编译运行。

先在项目根目录创建 pom.xml,声明 Java 17 编译版本:

xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>shop-demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <properties>
        <maven.compiler.release>17</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
</project>

此文件是完整的 Maven 项目配置。使用 mvn -version 检查 Maven 可用,并确认其使用的 JDK 版本不低于 17。

在 src/main/java/com/example/shop/model/Product.java 中定义商品模型:

java
package com.example.shop.model;

// 数据模型只保存商品信息,不依赖程序入口。
public record Product(String name, double price) {
}

在 src/main/java/com/example/shop/service/PricingService.java 中定义价格服务:

java
package com.example.shop.service;

import com.example.shop.model.Product;

public class PricingService {
    // 折扣计算独立于命令行输出,便于复用和测试。
    public double discountedPrice(Product product, double rate) {
        return product.price() * rate;
    }
}

在 src/main/java/com/example/shop/app/Main.java 中编写入口:

java
package com.example.shop.app;

import com.example.shop.model.Product;
import com.example.shop.service.PricingService;

public class Main {
    public static void main(String[] args) {
        // 入口负责组装对象和展示结果,不承载折扣算法。
        Product product = new Product("Java 实战课", 199.0);
        PricingService service = new PricingService();
        System.out.printf("%s折扣价=%.2f%n",
                product.name(), service.discountedPrice(product, 0.8));
    }
}

这里保留原示例的计算规则:商品原价 199.00 元,折扣系数为 0.8,得到 159.20 元。三个类分别承担数据、计算和展示职责,跨包访问的类型与方法需要使用适当的访问修饰符。

在包含 pom.xml 的项目根目录执行:

bash
mvn compile
java -cp target/classes com.example.shop.app.Main

预期结果:mvn compile 成功完成编译,随后程序输出:

text
Java 实战课折扣价=159.20

Maven 编译完成时通常还会显示 BUILD SUCCESS,具体日志与构建耗时因环境而异。这里执行的 Java 类名必须是包含包名的完整类名,而不能只写 Main。

资源与测试如何放置

假设应用名称保存于 src/main/resources/app.properties,文件内容为:

properties
app.name=Java 实战课

这是配置文件片段,不会自行产生控制台输出。运行 mvn process-resources 后,可检查 target/classes/app.properties 是否存在。后续代码可使用 Main.class.getResourceAsStream("/app.properties") 从类路径读取它;资源名称前的 / 表示从类路径根位置查找。

测试代码应放在 src/test/java,并使用与被测类对应的包路径,例如 src/test/java/com/example/shop/service/PricingServiceTest.java。实际运行单元测试时,还需要在 pom.xml 中声明相应测试框架依赖。mvn test 会触发测试阶段,但没有配置测试框架和测试类时,不代表业务逻辑已经通过测试。

常见组织错误与修正

把所有类放进默认包

默认包缺少明确的命名空间,也无法被有名包中的类正常导入。将类移动到对应包目录,补齐 package 声明,并修改相关 import。移动文件后重新执行 mvn compile,确认没有找不到类型的错误。

把所有逻辑放进 Main

如果入口同时承担输入校验、折扣计算和数据访问,修改业务规则就必须改动入口。应将计算提取为 PricingService 的方法,让 Main 仅负责组装与输出。后续测试可直接调用服务方法,无须执行命令行入口。

让底层包反向依赖上层包

例如让 model.Product 调用 app.Main 的静态方法,会造成职责混乱;如果多个包互相引用,还会形成循环依赖。应把共享规则移动到合理的服务或独立组件中,或者重新设计接口归属,不要通过增加更多静态方法掩盖依赖问题。

动手验证组织规则

  1. 将 PricingService.discountedPrice 的折扣系数改为 0.75,重新编译运行。预期输出的折扣价变为 149.25,而 Product 和入口的职责无需改变。
  2. 在 src/main/resources 中创建 app.properties,执行 mvn process-resources,确认文件被复制到 target/classes,而不是放进 Java 源码目录。

如果编译报出找不到类,先核对 package、import 和实际文件路径,再确认使用的是项目根目录及正确的 JDK。规范的目录结构应让每次修改都有明确位置:数据放模型,计算放服务,启动与组装留在入口。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

项目结构规范与代码组织

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通