Snowy-Cloud のアーキテクチャ概要

Snowy-Cloud は、マイクロサービスアーキテクチャを採用したフロントエンドとバックエンドを分離した迅速な開発プラットフォームです。このシステムは明確な階層構造とモジュール化された設計により、コードの保守性、拡張性、再利用性を確保しています。主な構成要素にはプレゼンテーション層、ビジネスロジック層、データアクセス層、およびサービス層が含まれ、機能モジュールはプラグイン方式で疎結合されています。

階層アーキテクチャ

プロジェクトはクラシックな三层モデルに基づき、マイクロサービスの要件に合わせて拡張されています。

• プレゼンテーション層（表示層）
  • ディレクトリ：snowy-admin-web
  • 役割：ユーザーインターフェースのレンダリングとインタラクション処理を担当。
  • 使用技術：Vue 3 と Ant Design Vue を採用し、動的ルーティングと多言語サポートを提供。
  • 例： ルート定義の変更：

export default [
  {
    path: '/console',
    meta: { title: '管理画面', icon: 'control-panel' },
    component: () => import('@/views/layout/Layout.vue')
  }
];

• ビジネスロジック層（業務層）
  • ディレクトリ：snowy-modules および snowy-plugin
  • 役割：コアとなる業務処理を実行。認証や権限管理などの機能は独立したプラグインとして抽出されます。
  • 例： サービスインターフェースの定義（名称変更あり）：

public interface IdentityVerificationService {
    UserPrincipal verifyCredentials(String username, String password);
}

• データアクセス層（DAO 層）
  • ディレクトリ：snowy-base と snowy-server
  • 役割：データベースとの永続化操作およびクエリ処理。MyBatis-Plus を利用して簡素化し、マルチデータソース設定に対応可能。
  • 例： リポジトリインタフェース：

@Mapper
public interface AccountDao extends BaseMapper<AccountEntity> {
    List<AccountEntity> findAccountsByGroup(Long groupId);
}

• サービス層
  • ディレクトリ：snowy-server
  • 役割：マイクロサービス間の通信および調整。Spring Cloud および Nacos を活用し、登録と検出を実現。
  • 例： フェイククライアント呼び出し：

@RemoteClient(name = "snowy-identity-service")
public interface GatewayInterface {
    @PostMapping("/auth/token")
    ResponseEntity<TokenResponse> issueToken(@RequestBody CredentialDto credentials);
}

モジュール設計

機能は独立したコンポーネントに分割されており、各エリアは明確な責任範囲を持ちます。

1. プラグインモジュール
   snowy-plugin ディレクトリ内には、API 定義、Feign クライアント、および機能実装サブモジュールが含まれます。
   代表例：snowy-plugin-auth（認証）、snowy-plugin-codegen（生成ツール）など。


2. コンポーネントモジュール
   snowy-admin-web/src/components に配置される UI ビルドブロック。
   例：XnDataList（一覧表示）、XnFormBuilder（フォーム生成）など。


3. ユーティリティモジュール
   snowy-admin-web/src/utils に格納された共通関数群。
   例：cipher.js（暗号化処理）、http-wrapper.js（HTTP 非同期処理）など。

モジュール化の利点

• 高凝集・低結合： 各部分は独立してテスト・デプロイ可能。
• 拡張容易： 新機能の実装は新規モジュールの追加で完了。
• 再利用性： 汎用コンポーネントやヘルパー関数は複数プロジェクトで流用可。

フロントエンドとバックエンドの統合と運用

本プラットフォームはモジュール化と標準化された API 設計に基づき、両サイドの協調を促進します。

フロントエンド組織構造

コードベースは snowy-admin-web に位置し、Vue3、Vite、Ant Design Vue を基盤としています。

• api: バックエンド API との通信定義。モジュールごとに分類（例：sysUser.ts）。
• components: 再利用可能な UI 部品。
• router: アプリケーションナビゲーション定義。
• store: Pinia による状態管理（モジュール化）。
• views: メインページビューコンポーネント。

バックエンド組織構造

Spring Boot および Spring Cloud によるマイクロサービス構築が行われています。

• snowy-base: コア機能、共用設定、ユーティリティクラス。
• snowy-modules: 主要ビジネスアプリケーション（例：snowy-core）。
• snowy-plugin: 拡張機能エリア（ログイン、ログ管理など）。
• snowy-server: インフラストラクチャ（ゲートウェイ、ディスカバリー）。

通信設計

両者の相互作用は RESTful API を通じて行われ、JSON フォーマットが標準です。

1. API 定義（JS）：

   // src/api/sys/dataList.ts
   import http from '@/utils/axios';
   export const fetchData = (query) => 
     http.get('/data/v1/search', { params: query });

2. コントローラー実装（Java）：

   @RestController
   @RequestMapping("/data/v1")
   public class DataViewController {
       @GetMapping("/search")
       public ResponseResult<Page<DataVO>> searchItems(Map<String, Object> filters) {
           return ResponseResult.ok(pageService.query(filters));
       }
   }

3. レスポンス形式：

   {
     "code": 0,
     "msg": "operation success",
     "data": { ... }
   }

セキュリティ対策

機密情報の保護には国産暗号アルゴリズムが採用されています。

• 認証時：パスワードは SM2 で暗号化して送信し、サーバー側で復号。
• 保存時：個人情報（電話番号等）は SM4 アルゴリズムで暗号化して DB に格納。

開発標準と品質保証

コードの一貫性と可読性を維持するため、以下のガイドラインに従います。

命名規則

• クラス名： PascalCase（例：OrderProcessor）
• メソッド名： camelCase（例：calculateTotal）
• 変数名： camelCase（例：totalAmount）
• 定数： スネークケースの大文字（例：MAX_RETRY_TIMES）
• パッケージ： スネークケースの小文字（例：com.snowy.biz.order）

コードスタイル

• 整Formatter ツール（Prettier や Checkstyle）の使用推奨。
• 行長制限（120 文字以内）。
• インデントはスペース 4 個。

ドキュメント記述

Javadoc またはコメント付きの仕様書作成は必須です。

/**
 * データ取得サービスのメインロジックを実装
 *
 * @author System
 * @since 2.0.0
 */
public class OrderServiceImpl {

    /**
     * 注文データを検索する
     *
     * @param orderId 対象の注文 ID
     * @return 注文詳細オブジェクト
     * @throws NotFoundOrderException 該当しない場合
     */
    public OrderDTO findById(Long orderId) { ... }

レビュープロセス

マージ前にはチームによるコードレビューを実施し、命名規則の遵守、コメントの網羅性、ロジックの明快さを確認します。

トラブルシューティングと解決策

本システムの運用中によく発生する課題とその対処法を紹介します。

依存関係の競合

Maven パッケージバージョンの不一致が発生した場合の対策。

• 依存ツリー確認：

  mvn dependency:tree | grep conflict-lib

• pom.xml での排除：

  <exclusions>
    <exclusion>
      <groupId>old.version</groupId>
      <artifactId>conflicting-artifact</artifactId>
    </exclusion>
  </exclusions>

• BOM の統一： 親 POM の dependencyManagement でバージョンを一元管理。

サービス登録の不具合

Nacos 上への正常な登録が確認できない場合。

• 設定確認： bootstrap.yml 内の nacos.discovery.server-addr が正しく設定されているか確認。
• ステータスチェック： Nacos コンソールにてサービス状態を確認。
• ネットワーク： クライアントとサーバー間のポート開放状況を確認。

CORS エラー

ブラウザからのクロスオリジンリクエスト拒否に対処。

• サーバー設定： 特定の経路に対する許可設定。
• Vite プロキシ： vite.config.js で開発環境の転送を設定。

データベース接続エラー

コネクションプールまたは設定ミスによる接続失敗。

• DB 設定： URL、ユーザー名、パスワードの照合。
• HikariCP 最適化： プールの最大サイズやタイムアウト値の調整。

  spring.datasource.hikari.maximum-pool-size=20

フロントエンドビルド失敗

依存パッケージの破損やバージョン相違が原因の場合。

• キャッシュ削除： node_modules の再インストールを徹底。
• 依存関係検証： package.json のバリデーション実行。
• ログ解析： コンソール出力のエラースタックを追跡。

分散トランザクション

複数サービス間の一貫性問題。

• Seata 統合： トランザクショングループ ID を設定。

  seata.tx-service-group=group_tx_001

• イベント駆動型： メッセージキューを使用し、最終整合性を担保するアプローチも検討。

パフォーマンスチューニング

• クエリ最適化： インデックスの適切な付与と SQL ログの確認。
• キャッシュ戦略： Redis を活用したホットデータのキャッシング。
• 非同期処理： 重いタスクはメッセージブローカー経由でバックグラウンドへ移行。