打破“目录只是放代码的地方”这一刻板印象是从零构建Java后端项目的第一步。很多教程告诉你建几个包却没人告诉你目录结构本质上是一份给未来同事包括六个月后的你自己的架构说明书。当项目膨胀到几十万行代码后返工重构目录的代价远超你最初“先搭起来再说”所节省的那几个小时。别让IDE的默认结构毁了你打开IDEA新建Spring Boot项目默认生成的com.example.demo包结构可能是Java后端领域最危险的“新手陷阱”。它看起来合理实则毫无信息量controller、service、dao、entity这四个词组成的结构让所有业务逻辑平铺在一起。订单、用户、支付、库存全部混在同一个service包里三个月后你会发现自己在一个叫OrderServiceImpl的千行大文件里翻找逻辑。目录结构的第一原则是围绕业务域Domain而非技术分层Layer。横向分层是逻辑概念纵向切片才是代码的组织单元。正确的做法是反向思考从业务能力出发而非从框架功能出发。一个用户模块就该拥有它自己的controller、service、repository、dto、event。这不是代码的物理搬家而是对业务边界的强制定义。当你把用户相关的所有代码都锁进user包里你就物理上阻止了OrderService直接操作UserMapper。这不是做作这是在用结构强制实施架构纪律。目录结构是唯一一种不需要写文档、不需要开会评审就能让全team遵守的架构约束。从零构建的时候建议你立刻删除默认包名里的.demo后缀换成真正的业务前缀比如com.yourcompany.productname。然后别急着建包拿出一张白纸写下你预判的核心业务模块。没有业务预判的目录设计就像没有图纸的施工队。复盘三层架构的错觉很多开发者对controller-service-mapper三层架构抱有近乎宗教般的信仰。这本身没问题但问题在于这三层远不足以支撑复杂业务的生命周期。你需要补全它们之间的空白参数校验逻辑放controller那service取到的永远是不可信数据。事务控制代码写在mapper里那只是把SQL执行器变成了面条代码基地。真正健壮的分层不是三个而是五到六个每个都有明确的职责边界和禁止跨越规则。controller层的职责只有一个接收HTTP请求解析请求参数调用service返回响应体。业务异常、分布式锁、批量任务的失控回滚统统与其无关。如果你的controller里出现了try-catch你的架构已经响起了警报。service层承载业务逻辑但它的可怕之处在于无休止地膨胀。你会不自觉地在service里加入数据拼装、权限判断、日志埋点、缓存预热。为了避免这种失控你必须引入service-support或biz-common子包专门存放跨业务域通用的业务规则、策略接口、模板方法。没有提取通用能力的service层最终都会退化成一座没有隔间的毛坯房。repository层不能仅仅等同于MyBatis的mapper接口。在Java后端目录中repository是需要被防腐处理的。你希望在业务代码里看到userRepository.findByOpenId(openId)而不是userMapper.selectByOpenId(openId)。前者隐藏了存储实现细节是MySQL还是Redis后者把你的业务逻辑和MyBatis的注解语法焊死在一起。目录上你应该允许repository/impl的存在内部去组合各种mapper和dao。缺失的那一层领域模型与DTO的分离无数项目爆掉的原因就是直接把数据库实体Entity扔给了前端。当你的UserEntity带有passwordHash、deletedFlag、internalRemark这些字段时把它直接序列化返回接口相当于在公共场合大声朗读自己的银行卡密码。从零构建的第一步就是务必把domain/model内部领域对象、infrastructure/persistence持久化实体、interfaces/dto传输对象三个不同的类集合放进彼此隔离的包中。想明白这件事你的目录结构才能称得上“有意识的设计”。很多新人疑惑这些类字段几乎一样为何要复制三遍因为它们的生命周期演化方向完全不同。持久化实体跟随数据库表结构变动DTO跟随接口协议变动领域模型则跟随业务规则变动。三者的变化频率和原因截然不同强行合并为一个类只会让每次数据库加字段变成一次前端联调事故。assembler装配器或者converter转换器子包正是这三者之间的桥梁。它的存在不是让代码显得高大上而是让“复制字段”这个丑陋的操作集中在一个类里接受审查。你可以在包结构里清晰看到assembler/UserAssembler.toDTO(User user)。这比散落在service里的BeanUtils.copyProperties高出好几个可维护性等级。包结构背后的团队契约当你规划目录时你其实是在定义团队的协作边界。如果你的项目采用中大型团队协同开发目录结构就是你们的“模块间通信协议”。order包和promotion包之间如何调用是直接跨包引用service还是强制通过独立定义的facade接口这决定了你未来是轻松拆分微服务还是被一团乱麻的依赖活活困死在单体里。在根目录的module或顶层app划分上你可以采用“按功能垂直切片 共享内核”的模式。核心业务模块之间禁止直接互相依赖它们只能通过client或api包暴露接口。例如user-client模块定义对内提供的接口order模块调用它时它不需要知道user模块内部的service类长得什么样。如果目录结构中出现了模块之间互相import彼此的Impl类代码评审直接打回。在同一个模块内部推荐使用“按边界封闭”的策略。比如order包下面直接建controller、service、repository、domain、event这个包内是自洽的。当你从user模块切到order模块时你能快速定位到相关的一切。目录命名不是给机器看的是给人快速建立“心智地图”用的。配置、异常与通用返回体的安放如果目录结构只规划业务包那你很快会被基础设施代码淹没。所有项目最终都会长出“杂项”包然后它就变成了垃圾场。为解决这个问题common包必须设定严格的准入标准。只有满足“彻底无业务含义、纯技术通用”的类才允许放进common包。比如通用返回体ResultT、统一异常结构ErrorResponse、基础分页请求对象、枚举基类等这些确实是跨模块的。但凡是和用户逻辑有关的比如“用户不存在”这种异常必须放到user模块的exception子包里。如果你不这么做最后common包会膨胀到比业务代码还大变成一个谁也不敢动、一动就全站报错的“屎山”博物馆。配置类Configuration建议独立成config包但要做到分门别类config/WebMvcConfig、config/SecurityConfig、config/MybatisPlusConfig、config/RedisConfig。命名必须直白说明是配置什么框架的。禁止出现一个名叫CommonConfig的类因为它是典型的上帝类雏形。当配置类之间产生隐式依赖比如SecurityConfig依赖了RedisConfig里的Bean你会发现调试起来痛苦到怀疑人生。请在目录中安排一个config/README.md或者用package-info.java强制声明依赖关系。接口的版本控制是目录级别的问题在你的根目录构建API时请不要拒绝controller包下使用v1、v2子包。目录结构如果忽略版本管理的存在后续每一次破坏性接口升级都会变成一次程序员之间的信任危机。你把OrderController改成OrderV2Controller旧调用方怎么办新的包结构controller/v1/OrderController和controller/v2/OrderController能让你实现平滑迁移。优雅是不存在的只有未雨绸缪的目录设计才能让线上接口平滑地“移形换位”。同时dto包内部也建议在包级别区分request和response。别小看这一层分类它直接决定了接口定义是否清晰。当你的DTO按请求、响应拆开包后你就不可能在响应用错请求对象反序列化失败的脑残Bug会急剧减少。事件驱动与监听器的专属席位现代Java后端几乎都引入了Spring的事件机制或消息队列。如果目录结构里没有event包的一席之地那这些监听器就会被顺手丢到service包里或util包中造成隐晦的循环依赖。在为订单支付成功后的发短信、送积分、更新库存等行为设计目录时请专门建一个order/domain/event子包。这个子包存放两类东西事件定义OrderPaidEvent和事件监听器OrderPaidListener。这样设计的好处是你一眼就能看出一笔订单交易成功后系统要联动发出多少个副作用Side Effect。这些副作用如果散落在service流水账里没有人能拼出完整的业务全景。加粗放这里目录结构编排得越清晰你的异步化改造、消息队列引入就会越顺畅。测试目录的镜像结构决定了工程质量从零构建时源码目录旁边的test/java目录绝对不能偷懒。要求测试目录结构必须与主源码目录完全一一对应。user/service对应user/service下的测试类order/controller对应order/controller下的MockMvc测试。如果允许测试类乱扔那么就没有任何机制能保证开发者的测试覆盖到真正的业务模块。要想把测试写明白还要在test/java下建立资源文件目录的镜像。src/test/resources里不要只放一个孤零零的application.yml。请建立fixtures、mocks、sql子目录专门存放每个业务模块的测试桩数据。测试目录结构是否严谨直接能反映这个团队对于质量保障的真实态度。很多项目的测试代码烂到没人敢跑就是因为结构随意导致测试之间互相污染。别过度设计保持“一个动作能完成”有些程序员喜欢参考阿里规约把包拆到十层深比如com.company.project.biz.order.core.service.impl这种完全冗余的命名。目录结构的深度控制在一个合理的范围内通常四到五层已经是极限。过深的嵌套只会增大你的包扫描耗时、IDE渲染延迟、以及阅读代码时不断点击展开文件夹的烦躁感。在从零阶段你可以按com.company.project.{module}.{layer}.{sub}来规划。module是核心业务单元layer是controller/service/repository/domainsub仅在子功能复杂时引入。不要为了“未来的扩展性”而预先搞一批永远用不上的空包。空包比杂乱包更让人沮丧因为它在暗示某种设计意图却又无法验证。我的建议是先按当前实际的业务需求建包每个包至少有一个类存在。没有类的空包是架构的谎言是代码里刺眼的坏味道。当新代码产生时你自然知道它该放哪里。如果不知道说明你的模块划分定义出现了模糊应该停下来重新梳理边界。启动类与根包的关系隐秘但致命你有没有遇到过Spring Boot启动类扫描不到Mapper注解明明加了却报404绝大多数情况下这是启动类所在的包必须位于根包的最上层目录层级造成的。SpringBootApplication默认扫描启动类所在包及其所有子包如果你图省事把启动类放在com.company.project里而业务代码放在com.company.biz.project下那基本就是天壤之别。确保启动类所在包是com.company.project所有业务模块代码都位于com.company.project包之下。这个看似微不足道的目录安排几乎决定了你项目能跑起来的最低底线。同时这也能杜绝你使用复杂的scanBasePackages配置那些配置是后期维护者的噩梦。任何自定义路径的注解扫描都是骨架上的破绽。实用主义从零构建时的操作顺序动手建目录时不要打开IDE一个个新建包效率太低且容易手滑。用文本文件或者maven archetype来生成骨架。请用一个文本文件structure.md去描述目录树并通过脚本校验它在实际代码库中的存在性。这听起来有点走火入魔但很多大佬团队确实这么干因为一旦你允许IDE的自动导入把包建出来一些空的默认包会充斥工程。构建顺序可以是先建根包然后建核心业务模块包。针对第一个核心模块把controller/service/repository/domain/dto/event/exception全部建好。接着把这个模块从接口到持久层的完整最小链路跑通。只有第一个模块跑通你才能验证目录结构是合理的。然后第二个模块照葫芦画瓢。最后再返回去提取common和config。这个过程能让你避免一次性建一大堆结构结果完全推倒重来的尴尬。让目录成为会呼吸的活文档最后请记住静态的目录结构不应该是僵死的。你要把目录结构视为一张不断演进的地图而不是一座竣工后就不许改动的钢筋混凝土大楼。当新业务出现时先问自己现有目录是否能自然地容纳它如果不能那就是一次重构目录的好机会。在演化中有几个重要的里程碑节点可以借力注意这不是串词是提示 第一当service包里的类超过15个时立刻审视是否需要按业务子域二次划分。 第二当common包里出现两个以上类似功能的工具类时立刻清理合并。 第三当dto包的类名变得难以直译业务含义时停止缩写回归完整单词。编写代码是在与电脑对话设计目录是在与未来的开发者对话。电脑不在乎你的包结构但你的同事、你未来的继任者、你三个月后的自己都会在无数个深夜打开这个项目的目录树试图弄清这段逻辑到底藏在哪里。花几个小时认真打磨目录结构这是你用最少的技术债务换取最高协作效率的杠杆点。你的代码值得一开始就住进一个结构清晰、边界明确、能呼吸的家。