一. 背景介紹

當前，我們使用 Spring Boot + Mybatis + Maven 技術棧，按照微服務設計的要求（小而自治）開發 Java 應用，不推薦和使用 Module 實現項目分層。

二. 規範意義

規範 Java 項目的目錄結構是 Java 工程化的基礎，也是打通 DevOps 流程的起點。合理的目錄結構能減輕設計負擔，提升項目的模塊化程度與可維護性，促進團隊協作，降低溝通成本，確保研發、測試、編譯、部署和交付等環節的標準化與一致性。實際制定時，應結合技術棧、項目管理工具以及組織內部習慣（習慣取代配置）來制定合理的目錄結構。這一規範將直接影響開發體驗、維護效率、標準化實施和交付質量。

三. 思考與設計點

3.1 數據實體目錄規劃與使用建議

數據實體在項目中承擔載體和傳輸的作用，是項目重要組成部分

3.2 controller、service 和 dao 子包該如何劃分？

相比業務需求的多樣性，數據源相對較為單一和固定，建議 dao 中子包按數據源劃分，controller、service 子包或業務類可以考慮按業務劃分，以適應業務多樣性。

3.3 自動和人工生成的同類實體類如何存放？

自動生成的代碼不應被人為改動，否則後續可能存在不一致的問題。建議將自動生成和人為創建的同類代碼分別保存在不同的目錄，目錄名分別為：generator 和 custom。例如，mybatis-generator 生成的 PO 實體，建議保存在 po.db.{dbname}.generator 目錄下；人為創建的與該 db 相關的 PO，保存在 po.db.{dbname}.custom 目錄下，mapper.xml 和 Mapper 類同理。

3.4 配置與工具類如何存放？

（1）配置類，建議按數據源或數據類型，統一存放在 config 包（目錄）下，如 enums、properties（項目配置信息）、kafka、redis、retrofit 等，常量類 Constants 建議也保存在該包下。

（2）工具類，建議存放在 util 包下，類名以 Util 結尾。

四. 推薦項目結構及命名規範

src/main/java
└── com
    └── example
        |── config
        │   │── enums
        │   │── properties
        │   │── kafka
        │   │── redis
        │   │── retrofit
        │   └── Constants.java
        ├── model
        │   │── dto
        │   │   ├── in
        │   │   │   └── UserDTOIn.java
        │   │   │── out
        │   │   │   └── UserDTOOut.java
        │   ├── bo
        │   │   └── UserBO.java
        │   ├── po
        │   │   ├── db
        │   │   │   ├── {dbname}
        │   │   │   │   ├── generator
        │   │   │   │   │   └── UserPO.java
        │   │   │   │   ├── custom
        │   │   │   │   │   └── User{XXX}PO.java
        │   │   ├── http
        │   │   ├── redis
        │   │   ├── kafka
        │   ├── converter
        │   │   ├── dto
        │   │   │   ├── in
        │   │   │   │   └── UserDTOInConverter.java        
        │   │   │   │── out
        │   │   │   │   └── UserDTOOutConverter.java        
        │   │   ├── bo
        │   │   │   └── UserBOConverter.java
        │   │   │── po
        │   │   │   └── UserPOConverter.java
        ├── controller
        ├── service
        │   ├── bussinessA
        │   ├── bussinessB
        ├── dao
        │   ├── mapper
        │   │   ├── {dbname}
        │   │   │   ├── generator
        │   │   │   │   └── UserMapper.java
        │   │   │   ├── custom
        │   │   │   │   └── UserCustomMapper.java 
        │   ├── http
        │   ├── redis
        │   ├── kafka        
        ├── util
        │   └── ListUtil.java
        └── Application.java
└── resources
│   ├── mapper
│   │   ├── {dbname}
│   │   │   ├── generator
│   │   │   │   └── UserMapper.xml
│   │   │   ├── custom 
│   │   │   │   └── UserCustomMapper.xml
│   │── application.yml
│   │── application-{env}.yml
└── test