実生活に役立つ実用的な Angular アーキテクチャ

ほとんどの Angular アーキテクチャ コースでは理論を教えます。これではありません。

ここでは、実際の問題を検出し、状況に応じた意思決定を行い、チームが成長し、製品が変更され、時間が経っても耐えられるシステムを構築する方法を学びます。

モジュールは 20 個。実践志向。パディングはありません。

---

INDEX — 実生活のための実践的な Angular アーキテクチャ

---

モジュール 0 — システムベース

ポイント 0 はコンテンツ モジュールではありません。これは、ロードマップ全体で使用する見方です。

Angular の特定の問題について話す前に、次の質問に答える必要があります。

知らないアプリをどうやって見て、良いか悪いかを判断しますか?

そのための基本スキルは 4 つあります。

---

1. コードに触れることなくアプリを分析する

アプリの最初の読み取りはエディターでは行われません。それは構造の中にあります。単一のファイルを開く前に、情報を抽出できます。

• フォルダーは何と呼ばれますか?名前は何をするのかを表していますか？
• 他のすべてよりも重いフォルダー shared はありますか?
• 構造にはネストレベルがいくつありますか?
• モジュールまたは機能にはドメイン名または技術名が付いていますか?
• サービスはどこにありますか?緩んでいますか、それとも特徴の範囲内ですか?

これは、アプリを作成した人がビジネスの観点から考えたのか、それとも技術的なレイヤーの観点から考えたのかについて、すでに多くのことを物語っています。

---

2. 実践的な方法でアーキテクチャを検討する

レビューとはコードを上から下に読むことではありません。それは次のような基準を持って質問しています。

• ビジネス ロジックはどこに存在しますか?
• 各レイヤーに何が含まれているかは誰にもわかりません。
• 新しい機能を追加するには、いくつのサイトを変更する必要がありますか?
• 間違った方向に進んでいる依存関係はありますか?

上級アーキテクトは、最も複雑なコンポーネントから始めるわけではありません。最も高いリスク ポイントである共有サービス、グローバル状態、データ アクセス層から始めます。

---

3. プログラミング前に問題を検出する

アーキテクチャ上の損傷のほとんどは、無関係に見える初期の決定で発生します。

• 「今のところこれを共有サービスに置いています」
• 「親コンポーネントがこの状態を処理してから、それを移動します。」
• 「すべてに NgRx を使用しているため、一貫性があります。」

これらの決定は、数か月後に実際の結果をもたらします。アーキテクチャ上の基準は、それぞれの決定によって何を購入するのか、またどのような負債が発生するのかを把握することです。

---

4. 理論を実際のチェックリストに変換する

このロードマップで登場する各概念 (スマート/ダム コンポーネント、状態の配置、ゴッド サービスなど) は、実際のコードを確認しながら自問できる質問で終わる必要があります。

• このコンポーネントはデータの出所を知っていますか?
• このサービスを変更する理由は複数ありますか?
• この状態は 2 つの異なる場所に存在しますか?

概念を復習の質問に変えることができない場合は、それがまだ内面化されていません。

---

モジュール 1 — コードに触れることなく Angular アプリを分析する方法

最初のアーキテクチャ レビューは、エディタを開く前に行われます。フォルダー構造とファイル名だけで、品質を示す明確な信号をすでに抽出できます。これは、上級アーキテクトが未知のアプリを使用して最初の 10 分間行うことです。

なぜそれが重要なのでしょうか?

• アーキテクチャ上の問題の検出に長い時間がかかると、問題を修正するコストが飛躍的に増大します。
• 初日から設計が不十分な構造は、数か月後にはチームの妨げとなる技術的負債となります。
• 視覚的に素早く判断できるようになると、コードを 1 行書く前に、より適切な意思決定ができ​​るようになります。

ステップ 1 — フォルダー構造をマップとして読み取る

フォルダー構造は、最初に目に見えるアーキテクチャ上の決定です。それは、チームが精神世界をどのように整理したか、つまりテクノロジーの観点から考えているのか、それともビジネスの観点から考えているのかを示しています。

機能とは何ですか?

フィーチャーとは、完全なビジネス機能です。ファイルタイプではありません。技術層ではありません。

eコマースアプリを考えてみましょう。特徴は次のとおりです。

• 製品カタログ
• ショッピングカート
• チェックアウトプロセス
• ユーザープロフィール
• 注文管理

それらはそれぞれ、それ自体で意味のあるビジネスです。ユーザーは入力し、カタログを参照し、カートに追加し、チェックアウトします。それらが特徴です。

モデル 1 — 技術層ごとの組織 (規模が大きいと問題が発生する)

これは、きれいに見えるため、ほとんどの人が始めるときに行うことです。

src/app/
  components/
    product-card.component.ts
    product-list.component.ts
    cart-item.component.ts
    checkout-form.component.ts
    user-profile.component.ts
  services/
    product.service.ts
    cart.service.ts
    checkout.service.ts
    user.service.ts
  models/
    product.model.ts
    cart.model.ts
    user.model.ts

本当の問題は、チェックアウト フローを変更する必要があることです。関係する内容を理解するには、3 つの異なるフォルダー間を移動します。components/ でコンポーネント、services/ でサービス、models/ でモデルを探します。特定のチェックアウト パイプがある場合、それは他の機能からのパイプと混合された pipes/ 内にあります。

単一の機能を変更するには、アプリ全体を移動します。それは構造による結合です。チームが成長すると、異なる機能に取り組んでいる 2 人が常に同じフォルダーにアクセスするため、Git 内で競合が発生し、誰が何を所有しているかを把握することが困難になります。

モデル 2 — 機能ごとの編成 (スケールの範囲)

src/app/
  features/
    catalog/
      components/
        product-card.component.ts
        product-list.component.ts
      services/
        product.service.ts
      models/
        product.model.ts
      catalog.routes.ts
    cart/
      components/
        cart-item.component.ts
        cart-summary.component.ts
      services/
        cart.service.ts
      cart.routes.ts
    checkout/
      components/
        checkout-form.component.ts
        order-confirmation.component.ts
      services/
        checkout.service.ts
      checkout.routes.ts
  shared/
  core/

これが機能する理由: チェックアウトをタップすると、チェックアウト内のすべてが一緒になります。新しい開発者は、どこを見るべきかを正確に知っています。 1 人が機能全体を所有できます。フォルダーのみを削除することで、フィーチャー全体を削除できます。異なる機能間の Git 競合はほぼ完全に解消されます。

重要な経験則: 機能を削除する場合、他には何も触れずにそのフォルダー全体を削除できますか?答えが「はい」の場合、その機能は十分に分離されています。アプリ全体でピースを探す必要があるかというと、そうではありません。

ステップ 2 — 名前を読む

名前はドキュメントです。悪い名前は意図を隠し、コードを読む各人に認知的負荷を与えます。

shared/ — 何を含めるべきか、何を含めるべきではないか

shared/ は、複数の機能が使用し、独自のビジネス ロジックを持たないものに使用されます。

shared/ を修正:

shared/
  components/
    button/
    modal/
    spinner/
    avatar/
  pipes/
    date-format.pipe.ts
    truncate.pipe.ts
  directives/
    click-outside.directive.ts
  validators/
    email-validator.ts

これらは再利用可能な UI 部分または純粋なユーティリティです。彼らはそのビジネスについて何も知りません。 ButtonComponent は、それがチェックアウト ボタンなのかユーザー プロフィール ボタンなのかわかりません。彼はボタンになる方法しか知りません。

shared/ が間違っています:

shared/
  services/
    cart.service.ts           ← lógica de negocio aquí
    user-auth.service.ts      ← pertenece a auth/core
    product-filter.service.ts ← pertenece a catalog
    report-generator.service.ts ← pertenece a reporting

shared/ 内にビジネス ロジックを含むサービスが表示された場合、誰かがそのサービスをどこに配置すればよいのかわからず、そこに配置されたことを意味します。時間が経つにつれて、shared/ がアプリの包括的なものになります。

core/ — それは何であり、何ではないのか

core/ は、アプリ全体を一度に必要とするシングルトン インフラストラクチャ用です。

core/ を修正:

core/
  services/
    auth.service.ts
    logger.service.ts
    error-handler.service.ts
  interceptors/
    auth.interceptor.ts
    error.interceptor.ts
  guards/
    auth.guard.ts
  models/
    user-session.model.ts

core/ が間違っています:

core/
  components/
    dashboard.component.ts  ← eso es una feature
    home.component.ts       ← igual
  services/
    product.service.ts      ← pertenece a catalog
    report-generator.service.ts ← pertenece a reporting

これらは一度インスタンス化されると、アプリ全体に影響を与えます。認証インターセプターはアプリ全体のすべての HTTP リクエストをインターセプトするため、認証インターセプターは core/ に存在します。

あいまいな名前 — 危険信号

曖昧な名前は決定を先延ばしにすることです。誰かが data.service.ts を作成するとき、そのサービスがどのようなデータについて話しているのかはまだ決まっていません。

あなたが見ているもの	それが何を意味するのか
shared/ とても大きい	他では当てはまらなかったものすべて。混合バッグになります。
common/	shared/ と同じですが、名前が悪くなります。何が入るかの基準がない。
utils/ サービス付き	ユーティリティを装ったビジネス ロジック。深刻な危険信号。
helpers/	utils/ と同じ。名前は責任について何も語っていません。
ルート内のcomponents/	ドメインごとの組織化はありません。すべてのコンポーネントを一緒に。
core/ 40 個のファイル	コアの定義が不十分です。 shared/ が 2 番目として使用されました。
app.service.ts	成長を待つ神サービス。最大アラーム信号。
data.service.ts	何のデータ？名前からして無期限の責任。
helper.service.ts	関係のないメソッドを使ったサービスになってしまいます。
main.component.ts	「メイン」とは何ですか？本当の責任を隠した総称。

名前の規則: ファイル名からその内容が正確にわからない場合は、そのファイルの機能が多すぎるか、ファイルの場所が不十分である可能性があります。

曖昧な名前とその隠蔽内容の具体例:

• utils/format.ts 800 行: 日付書式設定 + フォーム検証 + API 変換の組み合わせ。
• helper.service.ts: 無関係なメソッドを使用した神サービスになってしまいます。
• app.service.ts: アプリ全体に対する責任を持つ、アプリ全体として呼び出されるサービス。

ステップ 3 — ファイルを開かずにカウントおよび測定する

コードを読む前に、構造から次のことを直接観察できます。

記号としてのコンポーネントのサイズ

サイン	それは何を示しているのでしょうか？
1 つのコンポーネントで +300 ～ 400 行	あなたはほとんどいつもやりすぎています。これは絶対的な規則ではありませんが、検討する価値はあります。
+10 の入出力	API が複雑すぎます。候補はいくつかのコンポーネントに分割されます。
コンポーネントでの直接 HTTP 呼び出し	プレゼンテーションとデータ アクセスを組み合わせます。サービス層がありません。
機能ごとに 1 ～ 2 つのコンポーネント	彼らはおそらくやりすぎです。内部分裂の欠如。
+20 のグローバルプロバイダー	状態と集中ロジックが多すぎます。すべてがグローバルである必要はありません。

グローバル サービス — providedIn: 'root' の危険性

グローバル サービスとは、任意の機能の任意のコンポーネントがそのサービスを挿入して使用できることを意味します。これにより、独立しているはずの機能間に目に見えない依存関係が生じます。

// Servicio que DEBERÍA ser local a la feature de catalog:
@Injectable({ providedIn: 'root' })  // ← señal de problema
export class ProductFilterService { ... }

// Ahora cualquier componente de cualquier feature puede usarlo.
// Si catalog cambia su lógica de filtrado, puede romper
// algo en una feature aparentemente no relacionada.

ステップ 4 — app.module.ts または app.config.ts: 何を探すか

モジュールを含むアプリ (Angular < 17 またはレガシー)

@NgModule({
  imports: [
    BrowserModule,
    HttpClientModule,
    RouterModule,
    AuthModule,       // ← bien, infraestructura singleton

    ProductModule,    // ← señal de problema
    CartModule,       // ← señal de problema
    CheckoutModule,   // ← señal de problema
    UserModule,       // ← señal de problema
    DashboardModule,  // ← señal de problema
    // Si hay 15+ módulos de features aquí,
    // el lazy loading no está funcionando.
  ],
  providers: [
    ProductService,   // ← si hay 20+ providers aquí,
    CartService,      // hay demasiada centralización
    UserService,
    AuthService,
  ]
})

機能モジュールは、ルート モジュールに直接インポートするのではなく、遅延 (オンデマンド) でロードする必要があります。これらがすべてここにある場合は、ユーザーがまったく必要としない場合でも、起動時にすべてロードされます。

スタンドアロン アプリの場合 (Angular 17 以降)

// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes, withLazyLoading()),   // ← correcto
    provideHttpClient(withInterceptors([authInterceptor])),
    provideAnimations(),

    ProductService,   // ← esto NO debería estar aquí
    CartService,      // ← pertenece a la feature de cart
  ]
}

グローバル設定ルール: グローバル設定には、アプリ全体に影響するインフラストラクチャのみを含める必要があります。遅延読み込みを備えたルーター、グローバル インターセプタを備えた HttpClient、アニメーション、インフラストラクチャ シングルトン サービス (認証、ロガー、エラー ハンドラー)。グローバル設定に機能サービスが表示される場合、誰かが必要性ではなく便宜のためにグローバルに登録していることになります。

完全なチェックリスト — Angular アプリの最初の読み込み

構造

• 構造は機能 (ビジネス ドメイン) ごとに編成されていますか? それとも技術レイヤーごとに編成されていますか?
• 他には何も触れずにフォルダーだけを削除することで、機能全体を削除できますか?
• 機能にはビジネス ドメイン名 (checkout、catalog) または技術名 (list、form、detail) が付いていますか?
• utils、helpers、common、misc、data などのあいまいな名前のフォルダーはありますか?

shared/ および core/

• shared/ には、ビジネス ロジックを含まない UI コンポーネントとユーティリティのみが含まれていますか?
• core/ にはシングルトン インフラストラクチャ (インターセプタ、ガード、認証サービス) のみが含まれていますか?
• shared/ 内にビジネス ロジックを備えたサービスはありますか?
• core/ には機能コンポーネントまたはドメイン サービスがありますか?

サービスとプロバイダー

• ビジネス サービスは自社の機能内にありますか、それともグローバルに緩んでいますか?
• グローバルプロバイダーは 20 を超えていますか?
• ルート モジュールまたは app.config.ts は機能モジュールを (遅延なしで) 直接インポートしますか?
• 機能に対してローカルである必要がある providedIn: 'root' を持つサービスはありますか?

名前

• ファイル名は、その内容を正確に示していますか?
• アプリのどの部分にも適用できる名前のファイルはありますか?
• app.service.ts、data.service.ts、または helper.service.ts という名前のファイルはありますか?
• shared/ は個々の機能よりも重要ですか?

＃＃＃ エクササイズ

GitHub で公開されている Angular プロジェクトを検索します。独自のプロジェクトでも、オープンソースのプロジェクトでも構いません。ファイルを開かずに、フォルダー構造と名前だけを確認します。

1. どのような組織モデルを使用していますか: 機能または技術レイヤー?
2. 疑問や疑いを抱かせる名前は何ですか?
3. ビジネス ロジックがどこにあると思われますか?
4. 最も多くの役割が混在しているフォルダーはどれだと思いますか?
5. 他には何も触れずに機能を削除できますか?

セッション中に観察したことを共有し、上級アーキテクトが行うように一緒にレビューします。

---

プロンプト: 4 つのポイントを使用してプロジェクトを分析します

このプロンプトをコピーし、プロジェクトのフォルダー ツリーに渡す任意の AI (ChatGPT、Claude、Copilot) で使用します。

---

第 1 の柱の 4 つのポイントを適用してプロジェクト アーキテクチャを分析し、レポートを生成します。

ポイント1 — フォルダー構成

apps/ と libs/ を分析して次のように答えます。

• 組織は機能別（ビジネスドメイン別）ですか、それとも技術レイヤー別ですか？
• フォルダーのみを削除して、機能全体を削除できますか?
• 機能にはドメイン名 (checkout、catalog) または技術名 (list、form、detail) がありますか?
• utils、helpers、common、misc、data などのあいまいな名前のフォルダーはありませんか?
• 見つかったフォルダーの実際のツリーを表示します。

ポイント2 — ファイル名とフォルダー名

プロジェクト全体を検索してリストします。

• あいまいな名前のファイル: data.service.ts、helper.service.ts、app.service.ts、main.component.ts、utils、内部にサービスが含まれています。
• shared/ 内のビジネス ロジックを含むサービス。
• core/ 内のコンポーネントまたはドメイン サービス。
• shared/ は個々の機能よりも重要ですか?ファイル数。

POINT 3 — グローバルなサービス

プロジェクト全体を検索します。

• providedIn: 'root' を持つすべてのサービス — どのサービスであるか、および機能に対してローカルである必要があるかどうかをリストします。
• グローバルプロバイダーの合計数をカウントします。
• 機能内に含めるべきグローバルに登録されたビジネス サービスを識別します。
• 明らかに特定のドメインに属するサービスを libs/services/ で検索します。

ポイント 4 — グローバル構成 (app.config.ts または app.module.ts)

各アプリのルート構成ファイルを見つけて分析します。

• グローバルに登録されているべきではないものは何ですか?
• 機能モジュールは遅延読み込みでロードされますか、それとも直接インポートされますか?
• グローバル構成にビジネス サービスはありますか?
• 世界中で合計何社のプロバイダーが登録されていますか?

レポート形式

各ポイントに対して、次の正確な構造を使用します。

✅何が良いのか

(実際のコード例を含む具体的なリスト)

⚠️ 確認すべき兆候

(ファイルパスとそれが記号である理由を含む具体的なリスト)

❌ 明確な問題

(ファイルパス、問題、実際の影響を含む具体的なリスト)

最終的には次のものが含まれます。

＃＃ エグゼクティブサマリー 4 つのポイント、ステータス絵文字 (✅ ⚠️ ❌)、およびポイントごとの結論行を含む表。

優先順位を付けた次のステップ

影響順に並べられた最大 5 つの特定のアクションのリスト。タッチするファイルまたはフォルダーの正確なパスも含まれます。

率直に言ってください。機能や理論が何であるかを説明しないでください。この特定のプロジェクトを分析して、実際の結果を提供してください。