backend-architecture-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Backend Architecture Guidelines - 7-Layer Laravel-Native

Laravel原生7层后端架构指南

This skill provides architectural guidelines for Laravel applications following a 7-layer Laravel-native architecture.

本指南为遵循Laravel原生7层架构的Laravel应用提供架构设计规范。

How to Use This Skill

如何使用本指南

Quick Reference - Phase 1: Architecture Planning

快速参考 - 第一阶段：架构规划

Architecture Decision Checklist:

要件から適切なレイヤーを決定 (Layer Responsibilities)
依存関係ルールを検証 (Dependency Rules)
DTO設計（Laravel Data）を検討
Repository の必要性を判断 (Decision Framework)
Anti-patternsチェック (Anti-Patterns)
Deptrac設定を計画

詳細な規約:

```
.claude/rules/backend/
```
- レイヤー構造、DTO、テスト、コーディング規約の詳細

架构决策检查清单：

根据需求确定合适的层级（参考各层职责）
验证依赖规则（参考依赖规则）
考虑DTO设计（Laravel Data）
判断是否需要Repository（参考决策框架）
检查反模式（参考需避免的反模式）
规划Deptrac配置

详细规范：

```
.claude/rules/backend/
```
- 层级结构、DTO、测试、编码规范的详细内容

Architecture Overview

架构概述

7層レイヤードアーキテクチャ（Laravel-native）

┌─────────────────────────────────────────────────────────────┐
│                   Presentation Layer                         │
│               (Controller, Middleware, Inertia)             │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Request Layer                            │
│                (FormRequest, Validation)                    │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     UseCase Layer                            │
│                  (Business Logic, DTO)                      │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Service Layer                            │
│                 (Shared/Reusable Logic)                     │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Repository Layer                          │
│              (Data Access Abstraction)                      │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Model Layer                             │
│                  (Eloquent Models)                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Resource Layer                            │
│               (JSON Response Transformation)                │
└─────────────────────────────────────────────────────────────┘

7層レイヤードアーキテクチャ（Laravel-native）

┌─────────────────────────────────────────────────────────────┐
│                   Presentation Layer                         │
│               (Controller, Middleware, Inertia)             │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Request Layer                            │
│                (FormRequest, Validation)                    │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     UseCase Layer                            │
│                  (Business Logic, DTO)                      │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Service Layer                            │
│                 (Shared/Reusable Logic)                     │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Repository Layer                          │
│              (Data Access Abstraction)                      │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Model Layer                             │
│                  (Eloquent Models)                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Resource Layer                            │
│               (JSON Response Transformation)                │
└─────────────────────────────────────────────────────────────┘

ディレクトリ構造 (

app/

配下にフラット配置)

目录结构（平级放置在

app/

目录下）

app/
├── Http/
│   ├── Controllers/
│   │   ├── Api/              # API Controllers（REST API）
│   │   └── Web/              # Web Controllers（Inertia.js用）
│   ├── Requests/             # FormRequests（バリデーション）
│   └── Resources/            # API Resources（JSONレスポンス）
├── UseCases/                 # UseCases（ビジネスロジック）
│   └── {Resource}/
│       ├── Create{Resource}UseCase.php
│       └── Update{Resource}UseCase.php
├── Services/                 # Services（共通ロジック）
├── Repositories/             # Repositories（データアクセス）
│   └── {Resource}/
│       ├── {Resource}RepositoryInterface.php
│       └── {Resource}Repository.php
├── Data/                     # DTOs（Laravel Data）
│   └── {Resource}/
│       ├── Create{Resource}Data.php
│       └── Update{Resource}Data.php
├── Models/                   # Eloquent Models
├── Policies/                 # Policies（認可）
└── Enums/                    # Enums（列挙型）

app/
├── Http/
│   ├── Controllers/
│   │   ├── Api/              # API控制器（REST API）
│   │   └── Web/              # Web控制器（用于Inertia.js）
│   ├── Requests/             # FormRequests（验证）
│   └── Resources/            # API Resources（JSON响应）
├── UseCases/                 # UseCases（业务逻辑）
│   └── {Resource}/
│       ├── Create{Resource}UseCase.php
│       └── Update{Resource}UseCase.php
├── Services/                 # Services（通用逻辑）
├── Repositories/             # Repositories（数据访问）
│   └── {Resource}/
│       ├── {Resource}RepositoryInterface.php
│       └── {Resource}Repository.php
├── Data/                     # DTOs（Laravel Data）
│   └── {Resource}/
│       ├── Create{Resource}Data.php
│       └── Update{Resource}Data.php
├── Models/                   # Eloquent Models
├── Policies/                 # Policies（授权）
└── Enums/                    # Enums（枚举类型）

Dependency Rules

依赖规则

基本ルール

基本规则

依存は上位層から下位層への一方向のみ

Presentation → Request → UseCase → Service/Repository → Model → Resource

依赖仅允许从上位层到下位层的单向依赖

Presentation → Request → UseCase → Service/Repository → Model → Resource

各レイヤーの依存関係

各层的依赖关系

レイヤー	依存可能	依存禁止
Presentation (Controllers)	Request, UseCase, Resource	Model直接, Service直接
Request (FormRequests)	DTO (Laravel Data)	Model, UseCase
UseCase	Repository Interface, Service, Policy	Controller, Request
Service	Repository, Model	Controller, UseCase
Repository	Model	Controller, UseCase
Model	なし（最下層）	全ての上位層
Resource	Model	Controller, UseCase

层级	允许依赖	禁止依赖
Presentation (Controllers)	Request, UseCase, Resource	直接依赖Model, 直接依赖Service
Request (FormRequests)	DTO (Laravel Data)	Model, UseCase
UseCase	Repository Interface, Service, Policy	Controller, Request
Service	Repository, Model	Controller, UseCase
Repository	Model	Controller, UseCase
Model	无（最底层）	所有上位层
Resource	Model	Controller, UseCase

Layer Responsibilities

各层职责

各層の責務一覧

各层职责列表

レイヤー	責務	配置
Presentation	HTTP Request/Response, 認可チェック	`app/Http/Controllers/`
Request	バリデーション、DTO変換	`app/Http/Requests/`
UseCase	ビジネスロジック、トランザクション制御	`app/UseCases/`
Service	汎用的なビジネスロジック（複数UseCaseで共有）	`app/Services/`
Repository	データアクセス抽象化、複雑なクエリ	`app/Repositories/`
Model	ドメインモデル、リレーション定義	`app/Models/`
Resource	JSONレスポンス整形	`app/Http/Resources/`

层级	职责	位置
Presentation	HTTP请求/响应处理、授权检查	`app/Http/Controllers/`
Request	验证、DTO转换	`app/Http/Requests/`
UseCase	业务逻辑、事务控制	`app/UseCases/`
Service	通用业务逻辑（供多个UseCase共享）	`app/Services/`
Repository	数据访问抽象、复杂查询	`app/Repositories/`
Model	领域模型、关联关系定义	`app/Models/`
Resource	JSON响应格式化	`app/Http/Resources/`

Web Controllers vs API Controllers

Web控制器 vs API控制器

種別	責務	命名
Web Controller	初期ページ描画、静的マスターデータ提供	`{Resource}PageController`
API Controller	CRUD操作、動的データ処理	`{Resource}Controller`

📖 詳細:

.claude/rules/backend/02-layers.md

类型	职责	命名
Web Controller	初始页面渲染、静态主数据提供	`{Resource}PageController`
API Controller	CRUD操作、动态数据处理	`{Resource}Controller`

📖 详情:

.claude/rules/backend/02-layers.md

Static Analysis with Deptrac

使用Deptrac进行静态分析

Deptrac を使用してアーキテクチャ境界を静的解析で検証する。

yaml

undefined

使用Deptrac通过静态分析验证架构边界。

yaml

undefined

deptrac/layer.yaml

deptrac: paths: - ./app layers: - name: Presentation collectors: - type: directory value: app/Http/Controllers - name: Request collectors: - type: directory value: app/Http/Requests - name: UseCase collectors: - type: directory value: app/UseCases - name: Service collectors: - type: directory value: app/Services - name: Repository collectors: - type: directory value: app/Repositories - name: Model collectors: - type: directory value: app/Models - name: Resource collectors: - type: directory value: app/Http/Resources

ruleset: Presentation: - Request - UseCase - Resource Request: - Data UseCase: - Repository - Service - Policy Service: - Repository - Model Repository: - Model Resource: - Model Model: []


```bash

ruleset: Presentation: - Request - UseCase - Resource Request: - Data UseCase: - Repository - Service - Policy Service: - Repository - Model Repository: - Model Resource: - Model Model: []


```bash

検証コマンド

验证命令

./vendor/bin/deptrac analyse --config-file=deptrac/layer.yaml

---

./vendor/bin/deptrac analyse --config-file=deptrac/layer.yaml

---

Anti-Patterns to Avoid

需避免的反模式

1. Controller でのビジネスロジック

1. 在Controller中编写业务逻辑

php

// ❌ WRONG
class PostController extends Controller
{
    public function store(Request $request)
    {
        // ビジネスロジックがControllerに
        if (Post::where('user_id', auth()->id())->count() > 10) {
            throw new \Exception('Limit exceeded');
        }
        $post = Post::create($request->all());
        return response()->json($post);
    }
}

// ✅ CORRECT
class PostController extends Controller
{
    public function store(StorePostRequest $request, CreatePostUseCase $useCase)
    {
        $data = $request->getCreatePostData();
        $post = $useCase->execute($data);
        return response()->json(new PostResource($post), 201);
    }
}

php

// ❌ 错误示例
class PostController extends Controller
{
    public function store(Request $request)
    {
        // 业务逻辑写在Controller中
        if (Post::where('user_id', auth()->id())->count() > 10) {
            throw new \Exception('Limit exceeded');
        }
        $post = Post::create($request->all());
        return response()->json($post);
    }
}

// ✅ 正确示例
class PostController extends Controller
{
    public function store(StorePostRequest $request, CreatePostUseCase $useCase)
    {
        $data = $request->getCreatePostData();
        $post = $useCase->execute($data);
        return response()->json(new PostResource($post), 201);
    }
}

2. UseCase での HTTP 依存

2. 在UseCase中依赖HTTP

php

// ❌ WRONG
class CreatePostUseCase
{
    public function execute(Request $request): Post  // HTTP依存
    {
        return Post::create($request->all());
    }
}

// ✅ CORRECT
class CreatePostUseCase
{
    public function execute(CreatePostData $data): Post  // DTOを使用
    {
        return $this->repository->create(...);
    }
}

php

// ❌ 错误示例
class CreatePostUseCase
{
    public function execute(Request $request): Post  // 依赖HTTP
    {
        return Post::create($request->all());
    }
}

// ✅ 正确示例
class CreatePostUseCase
{
    public function execute(CreatePostData $data): Post  // 使用DTO
    {
        return $this->repository->create(...);
    }
}

3. Web Controller での動的データ提供

3. 在Web Controller中提供动态数据

php

// ❌ WRONG
class PostPageController extends Controller
{
    public function index()
    {
        return Inertia::render('Post/Index', [
            'posts' => Post::all(),  // 動的データをWeb Controllerで
        ]);
    }
}

// ✅ CORRECT
class PostPageController extends Controller
{
    public function index()
    {
        return Inertia::render('Post/Index', [
            'statusOptions' => PostStatus::toSelectArray(),  // 静的データのみ
        ]);
        // 動的データはReact側からAPI経由で取得
    }
}

php

// ❌ 错误示例
class PostPageController extends Controller
{
    public function index()
    {
        return Inertia::render('Post/Index', [
            'posts' => Post::all(),  // Web Controller中提供动态数据
        ]);
    }
}

// ✅ 正确示例
class PostPageController extends Controller
{
    public function index()
    {
        return Inertia::render('Post/Index', [
            'statusOptions' => PostStatus::toSelectArray(),  // 仅提供静态数据
        ]);
        // 动态数据由React端通过API获取
    }
}

Decision Framework

决策框架

Repository を作成すべきケース

应创建Repository的场景

ケース	理由
複雑なクエリ	複数テーブル結合、サブクエリ、集計処理
トランザクション制御	複数のDB操作を1つのトランザクションで管理
テスト容易性	モック可能なインターフェース提供

场景	理由
复杂查询	多表关联、子查询、聚合处理
事务控制	将多个数据库操作纳入单个事务管理
易于测试	提供可Mock的接口

Repository を作成しなくても良いケース

无需创建Repository的场景

ケース	理由
シンプルな CRUD	Eloquent の標準機能で十分
単一モデル操作	複雑なクエリロジックがない

📖 詳細:

.claude/rules/backend/02-layers.md

场景	理由
简单CRUD	Eloquent的标准功能已足够
单一模型操作	无复杂查询逻辑

📖 详情:

.claude/rules/backend/02-layers.md

Service を作成すべきケース

应创建Service的场景

ケース	例
複数UseCase間で共有されるロジック	ファイルエクスポート、通知送信
外部サービス連携	API呼び出し、メール送信
複雑な計算処理	レポート集計、統計計算

场景	示例
多UseCase共享逻辑	文件导出、通知发送
外部服务集成	API调用、邮件发送
复杂计算处理	报表统计、统计计算

Architecture Decision Checklist

架构决策检查清单

レイヤー配置

层级放置

コードは正しいレイヤーに配置されているか？
依存方向は上位→下位の一方向か？
ビジネスロジックは UseCase に集約されているか？

代码是否放置在正确的层级？
依赖方向是否为从上到下的单向？
业务逻辑是否集中在UseCase中？

Controller 設計

Controller设计

Controller は HTTP handling のみか？
UseCase を呼び出しているか？
Web Controller は静的データのみ提供しているか？

Controller是否仅处理HTTP相关逻辑？
是否调用了UseCase？
Web Controller是否仅提供静态数据？

UseCase 設計

UseCase设计

Input DTO (Laravel Data) を使用しているか？
Repository Interface 経由でアクセスしているか？
HTTP 依存がないか？

是否使用了输入DTO（Laravel Data）？
是否通过Repository Interface访问数据？
是否存在HTTP依赖？

Repository 設計

Repository设计

Interface と Implementation が分離されているか？
トランザクション制御が適切か？
Eloquent Model を返しているか？

接口与实现是否分离？
事务控制是否恰当？
是否返回Eloquent Model？

DTO 設計

DTO设计

```
#[TypeScript()]
```
attribute が付与されているか？
```
readonly
```
property を使用しているか？
FormRequest に DTO 変換メソッドがあるか？

是否添加了
```
#[TypeScript()]
```
属性？
是否使用了
```
readonly
```
属性？
FormRequest中是否有DTO转换方法？

Reference Documentation

参考文档

詳細な実装ガイドと例:

.claude/rules/backend/01-overview.md
- アーキテクチャ全体像
.claude/rules/backend/02-layers.md
- 各レイヤーの詳細責務とコード例
.claude/rules/backend/03-dto-data.md
- Laravel Data による DTO 実装

.claude/rules/backend/04-typescript-generation.md
- TypeScript 型生成

.claude/rules/backend/05-inertia-backend.md
- Inertia.js バックエンド実装

.claude/rules/backend/06-testing.md
- テスト戦略

.claude/rules/backend/07-best-practices.md
- ベストプラクティス

.claude/rules/backend/08-coding-standards.md
- コーディング規約

详细的实现指南与示例：

.claude/rules/backend/01-overview.md
- 架构整体概览
.claude/rules/backend/02-layers.md
- 各层详细职责与代码示例
.claude/rules/backend/03-dto-data.md
- 基于Laravel Data的DTO实现

.claude/rules/backend/04-typescript-generation.md
- TypeScript类型生成

.claude/rules/backend/05-inertia-backend.md
- Inertia.js后端实现

.claude/rules/backend/06-testing.md
- 测试策略

.claude/rules/backend/07-best-practices.md
- 最佳实践

.claude/rules/backend/08-coding-standards.md
- 编码规范

backend-architecture-guidelines

Original

Translation

Backend Architecture Guidelines - 7-Layer Laravel-Native

Laravel原生7层后端架构指南

Table of Contents

目录

How to Use This Skill

如何使用本指南

Quick Reference - Phase 1: Architecture Planning

快速参考 - 第一阶段：架构规划

Architecture Overview

架构概述

ディレクトリ構造 (app/ 配下にフラット配置)

目录结构（平级放置在app/目录下）

Dependency Rules

依赖规则

基本ルール

基本规则

各レイヤーの依存関係

各层的依赖关系

Layer Responsibilities

各层职责

各層の責務一覧

各层职责列表

Web Controllers vs API Controllers

Web控制器 vs API控制器

Static Analysis with Deptrac

使用Deptrac进行静态分析

deptrac/layer.yaml

deptrac/layer.yaml

検証コマンド

验证命令

Anti-Patterns to Avoid

需避免的反模式

1. Controller でのビジネスロジック

1. 在Controller中编写业务逻辑

2. UseCase での HTTP 依存

2. 在UseCase中依赖HTTP

3. Web Controller での動的データ提供

3. 在Web Controller中提供动态数据

Decision Framework

决策框架

Repository を作成すべきケース

应创建Repository的场景

Repository を作成しなくても良いケース

无需创建Repository的场景

Service を作成すべきケース

应创建Service的场景

Architecture Decision Checklist

架构决策检查清单

レイヤー配置

层级放置

Controller 設計

Controller设计

UseCase 設計

UseCase设计

Repository 設計

Repository设计

DTO 設計

DTO设计

Reference Documentation

参考文档

ディレクトリ構造 (
`app/`
配下にフラット配置)

目录结构（平级放置在
`app/`
目录下）