后端项目目录结构与分层架构设计

按照修改原因组织文件,明确请求入口、业务逻辑和数据访问的边界

🎯 引言

学完这篇文章,你能按功能找到需要修改的文件,并判断什么时候值得拆分目录。

🗂 让目录对应实际修改任务

一个用户查询功能可以按下面的结构组织:

backend-demo/
    src/
        app.mjs
        server.mjs
        controllers/user-controller.mjs
        services/user-service.mjs
        repositories/user-repository.mjs
        config.mjs
    test/
        user.test.mjs
    .env
    .gitignore

这里的分工应当能回答“改这个需求去哪个文件”:

要修改什么先看哪个文件
给接口改地址或加公共中间件app.mjs
改监听端口、处理服务启动和停止server.mjs
改请求参数或 HTTP 状态controllers/user-controller.mjs
增加账号状态等业务规则services/user-service.mjs
改数据库查询字段repositories/user-repository.mjs
改端口、数据库地址等配置的读取方式config.mjs

Controller、Service、Repository 分别对应请求处理、业务规则和数据库访问。下一篇用一个真实查询展示三者如何调用,本篇先把文件位置安排清楚。


🔌 将应用定义与监听分开

app.mjs 创建应用、挂载路由,server.mjs 导入它并监听端口。这样测试可以直接使用 app,不会因为导入文件就占用开发端口。

新建功能时,先把路由接入 app,再由统一的启动文件启动,不要给每个功能文件都写一次 listen。


✂️ 什么时候需要拆文件

如果一个接口只有几行,可以先保存在同一文件。出现这些情况时再拆:

  • 同一段用户规则被多个接口调用,把规则放入 Service,修改时只改一处。
  • SQL 已经盖过接口的参数和响应逻辑,把查询放入 Repository。
  • 一个文件混合了用户、文件、消息等多类接口,按功能拆分,避免互相干扰。

拆分后的函数应有明确工作。一个函数仅原样转发参数、没有独立规则,也没有复用需求时,不必为了凑齐三层增加文件。


🔒 配置文件放在哪里

本地 .env 保存端口、数据库地址等配置,.gitignore 忽略包含真实凭据的文件。可提交 .env.example,让协作者知道需要配置哪些变量,其中只写示例值。

不要把密钥、上传文件和日志混进源码目录。配置读取与日志接入的具体做法在本章对应文章集中说明。


❓ 知识问答

Q1:换成 Egg 后要照搬这些目录吗?

按 Egg 的目录约定放置文件即可,业务分工仍然适用。自动加载 Controller 和 Service 的写法见 Egg 课程。

Q2:一个接口拆成很多文件才算规范吗?

文件数量不是目标,能清楚地找到和修改功能才有价值。

Q3:多个功能都要查询数据库,要各建一套连接吗?

通常共用连接池,控制总连接数,并在服务退出时统一关闭。


🧪 小练习

为“修改昵称后返回新的用户资料”标出参数检查、业务规则和数据库修改分别放在哪个文件,不必先创建空文件。

// 请在这里记录文件及其职责