Java包名必须全小写、点分隔、严格对应文件路径，禁止大写/下划线/中文；需以反向域名开头（如com.example），按功能分层（controller/service/repository等），确保“包名=路径=逻辑归属”三者一致。
Java 包名路径不是随便写的目录别名，而是代码结构、可维护性和工具链兼容性的基础。规范包名路径的核心在于让“包名 = 目录路径 = 逻辑归属”三者严格对齐。
包名必须全小写且用点分隔
包名中不能出现大写字母、下划线、连字符或中文。比如 com.example.user 是合规的；而 Com.Example.User、com_example_user、com.example.UserService 都是错误写法。大小写敏感在 Linux 和 CI 环境中极易引发 package does not exist 编译失败，IDEA 有时会自动修正但构建工具（如 Maven）不会容忍。
- 所有字母强制小写，单词间不用任何分隔符，仅靠点（.）层级区分
- 避免拼音缩写（如 com.shangwu.order），优先用英文通用词（com.example.order）
- 不使用数字开头的段（如 com.2026.utils 不合法），但数字出现在中间或末尾可以（com.example.v2.api）
采用反向域名作为顶级前缀
这是确保全局唯一性的最有效方式。如果你公司域名为 yourcompany.com，包名就从 com.yourcompany 开始。它既表明归属，又天然避免和开源库（如 org.springframework、com.google.guava）冲突。
- 个人项目可用公开邮箱域名，如 com.gmail.youname 或 io.github.youname
- 不要省略顶级域（如只写 yourcompany.service），否则失去唯一性保障
- 模块名紧接其后，体现业务含义，例如 com.yourcompany.payment、com.yourcompany.notification
按功能分层组织二级及以下包名
包的层级不宜过深（建议控制在 3–4 级），但每级都要有明确语义。常见分层模式与对应职责如下：
立即学习“Java免费学习笔记（深入）”；
- com.yourcompany.appname.controller：接收 HTTP 请求，不做业务处理
- com.yourcompany.appname.service：定义业务接口，含核心流程
- com.yourcompany.appname.service.impl：实现类，可与接口同包或单独放
- com.yourcompany.appname.repository 或 .mapper：数据访问契约
- com.yourcompany.appname.entity 或 .model：领域对象，映射数据库或 DTO
- com.yourcompany.appname.util：无状态工具类，不依赖 Spring 上下文
物理路径必须与包声明完全一致
声明 package com.yourcompany.order.service;，源码就必须放在 src/main/java/com/yourcompany/order/service/ 下。编译器和 JVM 都按此规则查找类文件——这不是约定，是硬性机制。
- IDEA 创建包时默认同步建目录，但手动移动文件或改包名后，务必检查目录是否同步更新
- Git 提交前留意是否出现大小写不一致的路径（如 Com/Yourcompany），Windows 可能不报错，Linux 构建直接失败
- Maven 项目中，src/main/java 是默认源根，不要擅自改成其他路径，否则包识别失效
