APIリファレンス - 概要

本セクションでは、createExeプロジェクトのAPI仕様について説明します。

概要

createExeプロジェクトは、統一された3層アーキテクチャで実装されており、全モジュールが一貫性のあるAPIを提供しています。

アーキテクチャ構成

3層構造の統一

全モジュールは以下の3層で構成されています：

┌─────────────────┐
│  Controller層   │ ← 外部インターフェース、フォーム操作
├─────────────────┤
│   Service層     │ ← ビジネスロジック、複数Componentの協調
├─────────────────┤
│  Component層    │ ← 単一責務の部品（Validator/Manager/Check）
└─────────────────┘

レイヤー間通信

Request/Responseパターン: 統一されたデータ交換形式
依存方向: Controller → Service → Component の単方向
エラーハンドリング: 共通のCode定義によるエラー分類

共通インターフェース

Request オブジェクト

各モジュールのRequestオブジェクトは、dataclassで実装され、以下の2つのパターンがあります：

パターン1: 公開フィールド（直接アクセス）

@dataclass(frozen=True)
class ConfigStatusRequest:
    ok_click: bool          # OK選択状態（直接アクセス）
    back_click: bool        # BACK選択状態（直接アクセス）
    input_data: str         # 入力データ（直接アクセス）
    pre_status: int         # 前ステータス（直接アクセス）

パターン2: プロパティアクセサ

@dataclass(frozen=True)
class ConfigActionRequest:
    _param1: bool
    _param2: str

    @property
    def param1(self) -> bool:
        return self._param1

    @property
    def param2(self) -> str:
        return self._param2

Response オブジェクト

処理結果は統一されたResponseオブジェクトで返却：

from common.layer.response.response import Response
from common.layer.code.code import Code

# 成功時
Response(data=result_data, result=Code.OK)

# エラー時
Response(data=error_info, result=Code.ARGUMENT_ERROR)

結果判定メソッド

Responseオブジェクトは以下の判定メソッドを提供：

is_ok(): 成功判定
is_do_nothing(): 何もしない判定
is_argument_error(): 引数エラー判定
is_sound_pending(): 音声処理待機判定（CONFIGモジュール専用）
is_sound_error(): 音声エラー判定（CONFIGモジュール専用）

モジュール別API仕様

各モジュールの詳細なAPI仕様については、以下を参照してください：

モジュール別APIリファレンス: 全モジュールの詳細なクラス・メソッド仕様

主要モジュール概要

モジュール	主要API
CONFIG	Action, Display, Sound, Status (設定管理)
HOME	Action, Display, Sound, Status (ホーム画面)
SAVE	Action, Display, Sound, Status (データ永続化)
END	Action, Display, Sound, Status (終了処理)

使用パターン

標準的な使用パターン

Requestオブジェクト作成:

# 公開フィールド型の場合
request = ConfigStatusRequest(
    ok_click=True,
    back_click=False,
    input_data="test_data",
    pre_status=1
)

# プロパティアクセサ型の場合
request = ConfigActionRequest(
    param1=True,
    param2="example",
    param3=42
)

Controller層呼び出し:
```
ModuleAction.execute(form, request)
```

Service層直接呼び出し （テスト時など）:

service = ModuleService(request)
response = service.execute()

if response.is_ok():
    result = response.data
else:
    handle_error(response)

エラーハンドリング

統一されたエラーハンドリングパターン：

response = service.execute()

if response.is_ok():
    # 成功時の処理
    process_success(response.data)
elif response.is_argument_error():
    # 引数エラー時の処理
    log_error(f"Invalid arguments: {response.data}")
elif response.is_do_nothing():
    # 何もしない場合（正常だが変更なし）
    pass
else:
    # その他のエラー
    handle_unexpected_error(response)

バリデーション

各モジュールはRequestValidatorを提供：

from common.config.service.component.actionRequestValidator import RequestValidator

try:
    RequestValidator(request).raise_if_invalid()
except ValueError as e:
    # バリデーションエラー処理
    handle_validation_error(e)

型安全性

型注釈の活用

全APIで型注釈を提供：

def execute(self, request: ModuleActionRequest) -> Response:
    """
    :param request: 実行リクエスト
    :type request: ModuleActionRequest
    :return: 実行結果
    :rtype: Response
    """

mypyによる型チェック

開発時の型チェック推奨：

mypy common/config/
mypy common/home/
mypy common/save/

テスト支援

モックとテスト

統一されたテストパターン：

import unittest
from unittest.mock import MagicMock

class ModuleServiceTest(unittest.TestCase):
    def test_success_case(self):
        request = create_valid_request()
        service = ModuleService(request)

        response = service.execute()

        self.assertTrue(response.is_ok())
        self.assertEqual(expected_data, response.data)

ファクトリーメソッド

テスト用のRequestオブジェクト作成支援：

def create_valid_config_status_request():
    # 公開フィールド型
    return ConfigStatusRequest(
        ok_click=True,
        back_click=False,
        input_data="test_value",
        pre_status=1
    )

def create_valid_config_action_request():
    # プロパティアクセサ型
    return ConfigActionRequest(
        param1=True,
        param2="test_value",
        param3=100
    )

パフォーマンス考慮事項

効率的な使用

Requestオブジェクトの再利用: 同じパラメータでの複数回実行時
Responseの適切な判定: 不要な分岐を避けるため、適切な判定メソッド使用
Component層の直接利用: 高頻度処理では、必要に応じてComponent層を直接利用

メモリ使用量

大容量データ: Response.dataには大容量データを直接格納しない
リソース解放: 長時間保持するオブジェクトでは、適切なリソース解放を実施

拡張性

新モジュール追加

新しいモジュールを追加する場合は、既存のパターンに従って実装：

3層アーキテクチャの採用
共通のRequest/Responseパターンの利用
統一された命名規則の採用

詳細は createExe プロジェクト - モジュール管理ガイドを参照してください。

下位互換性

APIの変更時は下位互換性を考慮：

Deprecated警告: 旧APIの段階的廃止
バージョニング: 重要な変更時のバージョン管理
移行ガイド: API変更時の移行手順提供