Java 包結構設計規範：命名慣例、訪問控制與模塊化架構最佳實踐

包命名核心原則

包名採用**全小寫**、**反轉域名**作為前綴，確保全局唯一性，避免命名衝突。

// 標準格式
com.company.project.module.submodule

// 示例
com.alibaba.cloud.nacos.config
org.springframework.boot.autoconfigure
io.github.username.project.feature

命名層級含義

1. 頂級域：com (商業)、org (非營利)、net、io、edu、gov 等。
2. 組織標識：公司域名反轉 (com.alibaba) 或 GitHub 用戶名 (io.github.username)。
3. 項目/產品：project 或 product。
4. 功能模塊/層級：service, dao, controller, model, util, config 等。

常見反模式

• 使用大寫字母：com.MyProject ❌
• 使用項目代號而非域名：mp.user.service ❌ (極高衝突風險)
• 過度層級：com.a.b.c.d.e.f.g ❌ (超過 5 層建議拆模塊)
• 包含版本號：com.company.project.v2.service ❌ (應用模塊化管理版本)

訪問控制與封裝邊界

四種訪問級別對比

包級可見性設計哲學

• 默認使用 package-private：類、字段、方法無修飾符即為包可見，構建「模塊內部公開、模塊外部隱藏」的封裝邊界。
• 僅導出必要 API：public 僅用於對外契約 (Controller, Service Interface, DTO, Event)。
• protected 僅用於繼承擴展點：模板方法、鉤子方法、供子類覆寫的內部邏輯。
• 私有封裝實現細節：工具方法、內部狀態、算法細節。

接口與實現分離包結構

com.company.project
├── api           // 公共契約：Interface, DTO, Event, Exception (public)
├── spi           // 服務提供者接口：供第三方實現的擴展點
├── impl          // 內部實現：ServiceImpl, RepositoryImpl (package-private 類)
│   ├── internal  // 核心內部邏輯，嚴禁外部依賴
│   └── config    // 自動配置類
└── infrastructure // 技術適配：MyBatis Mapper, Redis Client, MQ Producer

模塊化架構與依賴規則

分層架構包規範 (傳統三層)

com.company.project
├── web           // Controller, Filter, Interceptor (依賴 service)
├── service       // Service Interface & Impl (依賴 dao, domain)
├── domain        // Entity, VO, BO, Repository Interface (零依賴，核心層)
├── dao           // Mapper, Repository Impl (依賴 domain, infrastructure)
└── infrastructure // DataSource, Redis, MQ, Feign Client 配置

依賴方向鐵律

• 外層依賴內層：web → service → domain ← dao ← infrastructure。
• 嚴禁反向依賴：domain 不依賴任何上層；service 不依賴 web/controller 細節。
• 接口隔離：service 定義 Repository Interface，dao 提供實現，domain 依賴接口而非實現。

模塊化拆分原則 (高內聚、低耦合)

1. 業務邊界劃分：按限界上下文拆分 (用戶、訂單、支付、庫存)。
2. 獨立構建單元：每個模塊獨立 Maven/Gradle 模塊，產出 Jar。
3. API/Impl 分離發布：發布 project-api 和 project-impl，消費者僅依賴 api。
4. 共享內核謹慎使用：僅共享極穩定的 Value Object / Enum / Exception。

實戰案例：Spring Boot 專案包規劃

com.example.mall
├── MallApplication.java
├── config                 // 全局配置類 (MyBatis, Redis, Security, Swagger)
├── common                 // 通用內核：Result, Constants, Enums, Exception, Util
├── module
│   ├── user
│   │   ├── api            // UserService, UserDTO, UserVO, UserEvent
│   │   ├── impl           // UserServiceImpl, UserRepositoryImpl
│   │   │   ├── converter  // DTO/Entity/VO 轉換器
│   │   │   └── listener   // 事件監聽器
│   │   └── infrastructure // UserMapper, UserPO, UserFeignClient
│   ├── order
│   │   ├── api
│   │   ├── impl
│   │   └── infrastructure
│   └── product
│       ├── api
│       ├── impl
│       └── infrastructure
└── infrastructure         // 跨模塊基礎設施：DatabaseConfig, RedisConfig, MQConfig

總結

包結構是項目架構的「骨架」。遵循**反轉域名命名**、**最小導出原則**、**依賴單向流動**、**業務模塊化拆分**，能構建清晰、可維護、可演進的 Java 系統。定期進行架構審查，清理循環依賴、收斂 public API，是技術治理的常態化工作。