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 编译版本:
<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 中定义商品模型:
package com.example.shop.model;
// 数据模型只保存商品信息,不依赖程序入口。
public record Product(String name, double price) {
}在 src/main/java/com/example/shop/service/PricingService.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 中编写入口:
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 的项目根目录执行:
mvn compile
java -cp target/classes com.example.shop.app.Main预期结果:mvn compile 成功完成编译,随后程序输出:
Java 实战课折扣价=159.20Maven 编译完成时通常还会显示 BUILD SUCCESS,具体日志与构建耗时因环境而异。这里执行的 Java 类名必须是包含包名的完整类名,而不能只写 Main。
资源与测试如何放置
假设应用名称保存于 src/main/resources/app.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 的静态方法,会造成职责混乱;如果多个包互相引用,还会形成循环依赖。应把共享规则移动到合理的服务或独立组件中,或者重新设计接口归属,不要通过增加更多静态方法掩盖依赖问题。
动手验证组织规则
- 将
PricingService.discountedPrice的折扣系数改为0.75,重新编译运行。预期输出的折扣价变为149.25,而Product和入口的职责无需改变。 - 在
src/main/resources中创建app.properties,执行mvn process-resources,确认文件被复制到target/classes,而不是放进 Java 源码目录。
如果编译报出找不到类,先核对 package、import 和实际文件路径,再确认使用的是项目根目录及正确的 JDK。规范的目录结构应让每次修改都有明确位置:数据放模型,计算放服务,启动与组装留在入口。