Java文件命名结构如何规范

本文目录导读：

1. 核心命名规则
2. 文件与类名的对应关系
3. 包（Package）目录结构
4. 常见业务模块的命名惯例
5. 特殊规则与注意事项
6. 强制检查清单
7. 不符合规范的示例
8. 不同项目类型的最佳实践

Java文件的命名结构规范主要遵循以下核心原则和最佳实践,以确保代码的可读性、可维护性和团队协作效率。

核心命名规则

文件名必须与公共类名完全一致

• 每个Java文件只能包含一个public类（或接口），文件名必须与该类名相同，区分大小写。
• 示例：UserService.java 文件内只能有一个 public class UserService。

严格遵循大小写

• Java文件名区分大小写,UserService.java 和 userservice.java 是不同的文件。
• 类名采用大驼峰命名法（PascalCase），文件名必须完全匹配类名的大小写。

文件扩展名必须为 .java

• 所有Java源文件必须以 .java 编译后生成对应的 .class 字节码文件。

文件与类名的对应关系

包（Package）目录结构

Java文件的存放位置必须与其包声明一致,形成完整的目录结构。

包名规范

• 全小写字母，使用反向域名作为根包名。
• 示例：com.example.project.module
• 禁止使用下划线、连字符，用点号分隔层级。

目录路径示例

src/
└── main/
    └── java/
        └── com/
            └── example/
                └── project/
                    ├── controller/
                    │   └── UserController.java
                    ├── service/
                    │   ├── UserService.java
                    │   └── impl/
                    │       └── UserServiceImpl.java
                    ├── repository/
                    │   └── UserRepository.java
                    ├── model/
                    │   ├── entity/
                    │   │   └── User.java
                    │   └── dto/
                    │       └── UserDTO.java
                    └── config/
                        └── AppConfig.java

包声明与目录一致的示例

// 文件路径: src/main/java/com/example/project/controller/UserController.java
package com.example.project.controller;
public class UserController {
    // 类内容
}

常见业务模块的命名惯例

特殊规则与注意事项

内部类与匿名类

• 内部类不创建独立的 .java 文件，它们存在于外部类的文件中。
• 编译后生成 OuterClass$InnerClass.class 文件。

测试文件

• 测试类文件名通常采用 {被测试类名}Test.java 格式。
• 放入相应的测试源目录（如 src/test/java）中，包路径与被测试类一致。

避免使用Java关键字或内置类名

• 不要创建名为 String.java、System.java 等与JDK标准类同名的文件。

与框架规范的配合

• Spring Boot：约定大于配置，控制层用 *Controller，服务层用 *Service，仓库层用 *Repository。
• MyBatis：Mapper接口通常命名为 UserMapper.java。
• Lombok：不影响文件命名，但需注意 @Data 等注解的类名仍遵循大驼峰。

强制检查清单

✅ 检查项：

• [ ] 文件名是否与 public 类名完全一致（包括大小写）
• [ ] 文件扩展名是否为 .java
• [ ] 文件目录是否与 package 声明完全一致（包名全小写，目录层级匹配）
• [ ] 是否遵循了项目/团队的业务命名约定（如Controller、Service、Repository等）
• [ ] 是否避免了与JDK内置类重名
• [ ] 测试文件命名是否以 Test 或 Tests