跳至主要內容

Web应用程序多模块单体应用代码目录结构设计

Think2026/3/8大约 15 分钟开发规范程序设计规范开发设计

Web应用程序多模块单体应用代码目录结构设计

前言

每个有经验的开发者都有自己程序的开发规范，这篇文章是根据个人经验，以SpringBoot框架，java开发语言为示例，归纳总结出的一种代码目录结构。
在开发实践中不一定完全适合所有人，但是对于大部分人来说，应该可以满足大部分的场景。同时在实践中，需要基于需求，进行相应的调整，但大体上建议遵循该目录结构，提高代码的可读性以及可维护性.

后端

模块划分

即使是单体应用程序，也建议按照模块进行划分，每个模块对应一个目录，目录下存放该模块的代码。

📁 推荐模块结构（点击展开）

  • framework：框架模块，为整个应用程序提供基础功能，例如：数据库连接、缓存连接、日志记录、异常处理等。框架模块下应当有以下目录：

    • configration：框架级配置文件存放目录，例如：数据库连接配置、swagger配置文件等；
    • exception：异常处理类存放目录；
    • aspects：框架级切面类存放目录；
    • interceptors：框架级拦截器存放目录；
    • filters：框架级过滤器存放目录；

  • common：通用模块，为整个应用程序提供通用功能，例如：文件上传、图片处理、数据验证等，同时实体类、枚举类、工具类也可以放在该模块下。common模块下应当有以下目录：

    • models ：模型存放目录，例如：实体类、请求参数模型、响应参数模型等；
    • constants ：常量存放目录，例如：枚举类、静态常量类等；
    • utils ：工具类存放目录；

  • 业务模块：为业务功能提供支持，例如：后台管理、用户管理、权限管理、订单管理等。每个模块下应当有以下目录：

    • service：业务逻辑处理类存放目录，包含接口定义类和实现类；
    • controller：控制器存放目录；
    • mapper：数据库操作类存放目录；

    注意：如果业务模块中需要自定义特有的拦截器或者过滤器等需求，可以在对应的模块下创建相应的目录，例如：interceptors、filters、aspects等。

  • async：异步任务模块（可选），为应用程序提供异步任务功能，例如：定时任务、邮件发送、短信发送等。异步任务模块下应当有以下目录：

    • service：异步任务处理类存放目录，包含接口定义类和实现类；
    • listener：监听器存放目录；
    • mapper：数据库操作类存放目录；
    • configration：异步任务配置文件存放目录，例如：定时任务配置文件等；

常见业务模块示例：

admin
admin：后台模块，为后台提供功能，例如：用户管理、角色管理、权限管理等；

命名要求

数据库

表名

  • 要求使用下划线 _ 分隔

  • 前缀说明（视需求而定）

    • sys_：管理端数据表前缀，例如：系统配置表 sys_config
    • tb_：功能业务相关表，记录业务数据，也可以使用其他前缀，例如：业务中台 bme_

注意

在 单体应用 或 系统体量较小 的情况下，不建议使用前缀。极其不推荐使用拼音缩写作为表名，建议使用英文单词！

字段名
  • 要求使用下划线 _ 分隔
  • 建议使用英文单词

✅ 正确示范：user_name
❌ 错误示范：yhm

实体类

项目中应只出现三种后缀实体类：DTO、VO、PO。

提示

有些项目会使用一个 entity 类作为全局数据传输的数据封装类，这样的好处是避免了数据传输对象和实体对象之间的转换。但当页面展示内容与实体类存在差异时，需修改实体类，导致其臃肿复杂。因此，除非必要，尽量避免仅使用 entity 类作为全局数据传输对象。

领域驱动设计（DDD）提示

这里可能有些读者阅读过领域驱动设计(DDD)的设计文章，因此可以看出这是一个 贫血模型。如果想要引入 充血模型，则需要考虑当前系统是否存在领域模型。如果存在，则应该创建领域模型，当前的实体模型只用来和数据库进行交互。

存放位置
  • 实体类应都存在于 model 包中
  • 每种类型的实体类应新建独立子包（如 dto、vo、po）
  • 在各类型包下再按 业务内容 创建子包

📌 示例路径：
model/dto/user/CreateUserDTO
其中 user 是根据对象内容新增的一层归纳。

命名规范
类型用途命名示例
DTO接口请求参数 / 多入参封装CreateUserDTO,PaginatedQueryUserInfoListDTO
VO接口响应参数 / 多返回值封装QueryUserDetailInfoVO
PO数据库实体 / DB 映射字段UserPO

方法名命名

方法命名采用 蛇形命名法（camelCase），首字母小写，格式为：
{action}{object}{data range}{condition}

🔍 命名组件说明
  • action：动作（create, update, delete, query, paginatedQuery）
  • object：操作对象（如 User）
  • data range（可选）：detailInfo, infoList
  • condition（可选）：如 ByUnCode

💡 Service 接口方法命名示例（UserService）

  • Boolean createUser(CreateUserDTO createUserDTO)
  • Boolean updateUser(UpdateUserDTO updateUserDTO)
  • Boolean deleteUser(String unCode) 或 Boolean deleteUser(DeleteUserDTO deleteUserDTO)
  • QueryUserDetailInfoVO queryUserDetailInfo(String unCode)
  • PaginatedQueryUserInfoListVO paginatedQueryUserInfoList(Page page)

变量名命名

变量名需“名副其实”，见名知意。若需注释补充，应考虑优化命名。

类型建议示例
布尔值使用正逻辑（is, exist）✅ isSuccess
❌ flag, notSuccess
字符串可加 Str 后缀errorMsgStr
数值明确对象timeOfRequestRetry
数组可加 Arry 后缀idArry
列表可加 List 后缀userList

警告

极特殊情况下，变量命名 isXxxx 可能在序列化时导致错误。

代码功能划分

在继续对后端进行目录结构设计时，我们需要有以下共识作为前提：

  1. 每个业务实体都要有几个通用属性，例如：表id、业务主键id、创建人、创建时间、更新人、更新时间、逻辑删除标识、版本号等（详见 通用功能 章节）；
  2. 除了自身模块的Service可以引入当前模块的Mapper之外，其他模块都不允许直接引入当前模块的Mapper。如果需要查询数据或者操作指定模块的数据，则需要通过引入指定模块的Service来实现，例如：当需要在订单模块查询用户信息时，则需要引入用户模块的Service，而不是直接引入用户模块的Mapper；

通用功能

工具类

💾 TimeUtil - 日期工具类
用途：日期格式化，例如创建日志表名需要

import java.text.SimpleDateFormat;
import java.util.Date;
public class TimeUtil {
    /**
     * @param date
      * @return String
      * @description: 将Date对象转化为yyyyMMdd格式的数据
     */
    public static String getDateFormatStrYYYYMMDD(Date date) {
        SimpleDateFormat sdf = new SimpleDateFormat("yyyyMMdd");
        return sdf.format(date);
    }
}

🔑 UUIDUtil - UUID工具类
用途：返回32位小写去除"-"的uuid

import java.util.UUID;
public class UUIDUtil {
  /**
   * @description: 返回32位小写去除"-"的uuid
   */
  public static String getUUID() {
      return UUID.randomUUID().toString().replaceAll("-","");
  }
}
审计日志

📋 审计日志规范

审计日志，记录用户操作日志，包含 操作人、操作IP、操作时间、操作内容、操作结果 等信息。该功能应当在framework层完成，并借助消息队列异步记录到数据库中。

异常处理

在设计系统时，考虑到多语言支持以及统一集中管理需求，则定义了异常响应枚举接口：

/** 
 * @description: 基础响应状态码接口，所有的响应状态码枚举都应实现该接口
 */
public interface BaseResCodeEnum {
    String code();
    String msg();
}

每个异常响应状态码枚举，均继承该接口。例如：用户管理模块的异常响应状态码枚举：

为了能够统一处理异常，需要定义自定义异常处理类，并且定义自定义的异常接口，并实现两种异常。

自定义异常接口：

/**
 * @description: 基本异常接口
 */
public interface BaseException {
    String getCode();
    Object[] getExtendMessage();
    String getMsg();
    BaseResCodeEnum getResCodeEnum();
}

自定义的异常实现类：

BusinessException 🚨

自定义的异常处理类：

📋异常处理类示例代码（点击展开）

有了上面的异常处理逻辑逻辑作为支撑之后，在实现业务逻辑时需要抛出异常时，只需要参考以下代码逻辑抛出异常即可

//业务逻辑...
throw new BusinessException(UserResCodeEnum.RC_USER_NOT_EXIST);

提示

在抛出异常时，默认传入定义好的异常信息响应枚举，会自动返回对应的响应信息，如果需要扩展消息，则可以查看自定义的异常处理类中关于扩展消息的实现逻辑，并添加扩展消息。示例中演示的是业务异常信息，如果需要抛出系统异常信息，则需要更换成系统异常SystemException。

数据封装

统一响应对象数据封装

📦统一响应模板接口定义：

/** 
 * 
 * @description: 统一响应模板接口
 */
public interface BaseResult {
    /** 
     * 响应码
     */
    String getCode();
    /**
     * 消息体
     */
    String getMsg();
}

接口定义之后，定义统一响应对象，并实现该接口。

🎯 统一响应对象：

📋 统一响应对象示例代码（点击展开）

💡 统一响应对象说明

统一响应对象封装了 数据、状态码、消息 等信息，并实现了 BaseResult 接口，因此，该对象可以作为统一响应对象使用。

统一响应对象的重要性：在和前端进行交互时，前端可在前置路由卫士中对响应结果进行判断，并返回对应的错误信息，以此实现统一的错误处理。

🎯 统一响应对象使用场景：

控制器响应使用
模型基类封装

为了能够统一处理请求和响应参数模型，定义了 DTO 模型基类和 VO 模型基类，所以请求参数模型和返回结果模型都应该继承基类模型（特殊业务实现除外）。实际使用场景有：统一对响应模型中的创建人和修改人进行翻译。各个模型基类模型如下：

DTO模型基类

前端

下面以vue3为例，介绍前端项目目录结构。React项目同理。

命名要求

📝 命名规范

  • 文件名称：使用首字母小写的驼峰命名方式，例如：dictType.js
  • 目录名称：使用首字母小写的驼峰命名方式，例如：dictType

目录结构

📁 项目目录结构概览

src 目录下包含以下核心目录，各自承担不同的职责：

components

🧩 公共组件目录 (src/components/)
存放公共自定义组件，例如：

  • 分页组件
  • 表格组件
  • 表单组件
  • 弹窗组件

目录结构：

components/
├── componentName/
│   └── index.vue
└── anotherComponent/
    └── index.vue

每个组件都有独立的目录，目录名称即为组件名称，内部包含 index.vue 文件。

中间件

（内容待补充）