TuraIDC 文档中心

Appearance

后端目录分类规范 ​

  • 文档性质：现行方向
  • 对齐时间：2026-07-02
  • 读者画像：后端开发、代码整理、文档维护人员
  • 适用范围：backend/ 下目录与新增 PHP 文件的落点规则

1. 目标 ​

本规范用于给 backend 建立稳定的目录分类和文件落点规则，减少“同一类文件散落多处”“新文件放哪全靠临时判断”“一个目录里堆满跨域类”的问题。

本规范的执行原则：

  1. 以当前真实代码结构为基础做增量收敛。
  2. 先规范新增文件落点，再处理历史杂项。
  3. 不为了“看起来整齐”一次性大规模移动命名空间。
  4. 现有稳定引用路径优先，不做无关重构。

2. backend 顶层目录分类 ​

目录分类用途规则
app/业务代码控制器、服务、模型、支持类、命令、任务长期业务代码只放这里
bootstrap/框架启动Laravel 启动配置不放业务逻辑
config/配置层系统配置、驱动配置不放运行时数据
database/数据结构层migrations、seeders、factories只放数据库相关内容
public/Web 入口层对外公开入口、公开静态资源不放业务实现
routes/路由层admin/client/site/web/console 路由只放路由注册
scripts/维护脚本一次性导出、排查、修复工具不放长期业务类
storage/运行时输出日志、缓存、上传、临时文件不手写业务源码
tests/测试层Feature、Unit、测试基类测试文件统一在此
vendor/第三方依赖Composer 依赖不手工修改

2.1 顶层禁止项 ​

  • 禁止把新业务 PHP 文件直接放在 backend/ 根目录。
  • 禁止把长期业务逻辑放进 scripts/。
  • 禁止把接口、服务、模型混放在 routes/、config/、public/。
  • 禁止把临时调试产物作为正式结构的一部分保留。

3. app/ 目录分类 ​

当前 app/ 目录分为以下固定层：

目录分类用途
Http/交付层控制器、中间件、请求校验、响应资源
Services/业务层业务流程、领域服务、对上游封装
Models/实体层Eloquent 模型
Support/支撑层跨域工具类、生成器、净化器、值对象
Constants/常量层状态枚举、权限码、错误码常量
Exceptions/异常层业务异常、自定义异常
Jobs/异步任务层队列任务
Console/命令层Artisan 命令
Providers/注册层Laravel Provider
Traits/复用层轻量共用 trait
Casts/转换层自定义字段 cast

4. Http/ 目录分类规则 ​

4.1 Controllers ​

当前控制器分类：

  • app/Http/Controllers/Admin/
    • 管理端接口
  • app/Http/Controllers/Client/
    • 用户端接口
  • app/Http/Controllers/
    • 只保留以下两类
    • 基类控制器
    • 公开站点/公共入口控制器，例如 SiteConfigController.php、SiteHomeController.php、SecureAssetController.php

4.2 Controllers 落点规则 ​

  • 新增管理端接口：放 Controllers/Admin/
  • 新增用户端接口：放 Controllers/Client/
  • 新增公开站点接口：放 Controllers/ 顶层，且文件名以 Site 或明确公共资源语义命名
  • 顶层 Controllers/ 禁止新增后台/用户侧控制器

4.3 Requests ​

当前 Requests/ 已按端区分：

  • app/Http/Requests/Admin/
  • app/Http/Requests/Client/

后续规则：

  • 端内请求对象继续按业务域落子目录
  • 例如：
    • Admin/Content/
    • Admin/Product/
    • Admin/User/
    • Client/Auth/
    • Client/Invoice/
    • Client/Service/

4.4 Resources ​

app/Http/Resources/ 当前仍较多平铺文件。

收敛规则：

  • 现有资源类暂不强制整体迁移
  • 新增资源类按业务域建子目录，避免继续平铺增长
  • 推荐目录：
    • Resources/Admin/
    • Resources/Client/
    • Resources/Content/
    • Resources/Product/
    • Resources/User/

5. Services/ 目录分类规则 ​

5.1 当前状态 ​

app/Services/ 现在已经混合了两类内容：

  1. 已经成形的领域目录
    • ClientServiceConsole/
    • ProductCatalog/
    • Order/
    • Upstream/
    • User/
  2. 大量仍平铺在顶层的服务类

这说明当前最容易变乱的就是 Services/。

5.2 顶层 Services/ 的保留用途 ​

以后顶层 Services/ 只保留：

  • 跨域编排服务
  • 旧结构遗留但暂未迁移的类
  • 单文件级别的系统服务，且短期内不会扩展成一个子域

例如当前可接受继续留顶层的类型：

  • AuthService.php
  • PaymentService.php
  • NotificationService.php
  • ScheduleTaskService.php

5.3 新增服务落点规则 ​

新增服务优先按业务域进入子目录，不再默认平铺在 Services/ 根下。

推荐收敛目录如下：

目录放什么
Services/User/用户资料、用户账变、用户管理相关服务
Services/Order/下单、账单、支付投影、支付编排
Services/ProductCatalog/商品、分类、供应商商品映射、目录能力
Services/ClientServiceConsole/服务控制台、监控、NAT、安全组、VNC
Services/Upstream/供应商驱动基座、能力契约、provider 解析与具体驱动实现
Services/Content/文章、分类、媒体库、站点内容
Services/Referral/推荐、返佣、提现、等级
Services/Site/站点聚合、首页、SEO、公开产品读取
Services/Automation/自动化任务、账单清理、服务生命周期自动化
Services/Integrations/Plugins/插件扫描、安装、配置、运行时注册和领域 adapter

第三方真实实现落点：

  • 支付、实名、短信、邮件、上游服务器的真实 provider 实现优先放 backend/plugins/{domain}/{slug}/。
  • 平台侧 app/Services/Integrations/Plugins/ 只保留插件基础设施和 adapter，不承载具体供应商协议细节。
  • 通用上游 provider 解析、能力契约和共享 transport 仍放 Services/Upstream/。
  • 不再新增 Services/Integration/ 单数目录；历史引用统一核对当前真实目录。

5.4 什么时候创建新子目录 ​

满足以下任一条件就应建新目录，而不是继续平铺：

  1. 同一业务域预计会有 3 个及以上服务类。
  2. 同一业务域同时存在“读服务 + 写服务 + 对上游适配”。
  3. 服务名已经开始出现共同前缀，例如 Site*Service、Referral*Service。
  4. 一个服务需要配套 DTO、解析器、专用帮助类。

5.5 不允许的新增方式 ​

  • 禁止继续新增 XxxService.php.new、XxxService_v2.php、NewXxxService.php
  • 禁止把同一业务域的 5 到 10 个服务长期平铺在根目录
  • 禁止用“供应商专用逻辑”污染通用服务类

6. Models/ 目录分类规则 ​

app/Models/ 当前保持平铺。

这是当前可接受状态，因为：

  • Laravel 模型天然高频被引用
  • 模型拆分命名空间会带来更高的迁移成本
  • 当前模型数量虽多，但语义仍清晰

因此模型层规则如下：

  • 现阶段模型继续平铺，不做目录化大迁移
  • 新增模型优先保持单实体一文件
  • 只有当某个模型需要强绑定同域辅助对象时，优先把辅助对象放 Support/ 或 Casts/，不要急着拆 Models/

7. Support/ 目录分类规则 ​

app/Support/ 只放跨域支撑类，不放业务流程。

可以放的类型：

  • 响应构造器
  • 编号生成器
  • 纯工具值对象
  • 净化器
  • URL/文件辅助类
  • 站点配置读取器

不该放的类型：

  • 含大量业务查询的服务
  • 直接改写业务状态的流程类
  • 某一单一业务域独享的“伪工具类”

如果一个类只服务某单一业务域，优先回到该业务域目录，不放 Support/。

8. Constants / Exceptions / Traits 规则 ​

8.1 Constants ​

  • 放状态枚举、权限码、错误码常量
  • 禁止放运行时依赖数据库的逻辑

8.2 Exceptions ​

  • 放业务异常和自定义异常类型
  • 不把普通流程控制写成异常类

8.3 Traits ​

  • 只放轻量复用片段
  • Trait 超过一个业务域的理解成本时，应回收成 Service 或 Support 类

9. 新增文件落点速查 ​

你要新增的文件应放目录
管理端控制器app/Http/Controllers/Admin/
用户端控制器app/Http/Controllers/Client/
公开站点控制器app/Http/Controllers/
管理端请求校验app/Http/Requests/Admin/<业务域>/
用户端请求校验app/Http/Requests/Client/<业务域>/
业务资源类app/Http/Resources/<业务域>/ 或先按端区分
跨域响应/工具类app/Support/
领域服务app/Services/<业务域>/
队列任务app/Jobs/
Artisan 命令app/Console/Commands/
迁移database/migrations/
一次性维护脚本scripts/
测试tests/Feature/ 或 tests/Unit/

10. 当前需要重点防乱的区域 ​

按当前仓库现状，优先控制以下区域继续变乱：

  1. app/Services/
  2. app/Http/Resources/
  3. scripts/
  4. backend/ 根目录临时文件

11. 执行建议 ​

11.1 现在就执行的规则 ​

  • 新增业务服务优先进入子目录，不再默认平铺
  • 新增请求对象必须按端区分
  • 新增公开站点控制器只允许放 Controllers/ 顶层
  • 新增文档型说明不放 backend/ 根目录

11.2 暂不做的事 ​

  • 暂不整体迁移 Models/
  • 暂不批量改已有服务命名空间
  • 暂不因为文档规范而一次性移动全部历史文件

11.3 后续可选收敛顺序 ​

如果后面要继续整理，建议按这个顺序做：

  1. 先收敛 Services/
  2. 再收敛 Http/Resources/
  3. 最后清理根目录和 scripts/ 的历史杂项

12. 禁止项 ​

  • 禁止把新增业务文件丢进 backend/ 根目录
  • 禁止用文件名后缀区分版本，如 .new、_v2、final
  • 禁止把“临时排查脚本”当成正式业务实现长期保留
  • 禁止跨 admin/client/site 混放控制器
  • 禁止在 Support/ 里塞入重业务流程

基于 AGPL-3.0-or-later 发布

Copyright © TuraIDC Contributors