Java REST API 三层架构项目目录规划与使用建议

一. 背景介绍

当前，我们使用 Spring Boot + Mybatis + Maven 技术栈，按照微服务设计的要求（小而自治）开发 Java 应用，不推荐和使用 Module 实现项目分层。

二. 规范意义

规范 Java 项目的目录结构是 Java 工程化的基础，也是打通 DevOps 流程的起点。合理的目录结构能减轻设计负担，提升项目的模块化程度与可维护性，促进团队协作，降低沟通成本，确保研发、测试、编译、部署和交付等环节的标准化与一致性。实际制定时，应结合技术栈、项目管理工具以及组织内部习惯（习惯取代配置）来制定合理的目录结构。这一规范将直接影响开发体验、维护效率、标准化实施和交付质量。

三. 思考与设计点

3.1 数据实体目录规划与使用建议

数据实体在项目中承担载体和传输的作用，是项目重要组成部分，其目录规范与使用建议可参考：Java 三层架构项目中数据实体目录规划与使用建议。

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