ElixirでPAY.JPのライブラリ作成シリーズ④ ドキュメントに設計

こちらの続きです。

さて、シリーズ①で作成したプロジェクトを開くとデフォルトで以下のコードが生成されています。
これをベースに実装していきましょう。

defmodule Payjpex do
  @moduledoc """
  PAY.JP API client for Elixir.
  Documentation for `Payjpex`.
  """

  @doc """
  Hello world.

  ## Examples

      iex> Payjpex.hello()
      :world

  """
  def hello do
    :world
  end
end

テストコードも同様に用意されているのでこちらを書き換えていきます。

defmodule PayjpexTest do
  use ExUnit.Case
  doctest Payjpex

  test "greets the world" do
    assert Payjpex.hello() == :world
  end
end

ドキュメント使って簡単な設計

まずは、Let it crushに基づいて、スーパーバイザツリーを実装していきます。
基本的な方針として、API連携を管理するConfigと、実際に操作するApiclientを実装するモジュールを追加していきます。

まず初めに、大まかな動作イメージをドキュメントとして書いていきます。設計ですね。もしかしたら後で変えるかも知れません。が、そんな事はお構いなく、現時点での設計イメージをドキュメントにしておきます。

PAY.JPは日本語のドキュメントがしっかりしてる所がポイントな気がしたので、Elixirのライブラリもしっかり日本語にしてみました。

defmodule Payjpex do
  @moduledoc """
    PAY.JP API用のElixirクライアントライブラリ。

    このモジュールはPAY.JP APIクライアントのメインアプリケーションモジュールです。
    設定管理とAPIクライアントプロセスを含むスーパービジョンツリーを管理します。

    ## アプリケーション構造

    起動時、このアプリケーションは以下のプロセスを含むスーパービジョンツリーを開始します：
      * `Payjpex.Config` - Agent プロセスを使用して設定値を管理
      * `Payjpex.ApiClient` - PAY.JP との API 通信を処理

    ## 設定方法

    設定は設定ファイルで指定できます：

        config :payjpex,
          api_key: "sk_test_xxxxxxxxxxxxxxxxxxxxxxxx",
          api_base: "https://api.pay.jp",
          api_version: "2024-01-01"

    または、実行時に動的に設定することもできます：

        Payjpex.Config.put(:api_key, "sk_test_xxxxxxxxxxxxxxxxxxxxxxxx")

    ## スーパービジョン

    `:one_for_one`戦略を使用しています。これは、子プロセスが終了した場合、
    スーパーバイザーによってそのプロセスのみが再起動されることを意味します。
  """

  use Application

  @doc """
  PAY.JP APIクライアントアプリケーションを起動します。

  この関数はOTPアプリケーションマネージャーによって自動的に呼び出されます。
  設定とAPIクライアントプロセスを含むスーパービジョンツリーを初期化します。

  ## パラメータ

    * `type` - 起動タイプ (:normal、:failover、または{:takeover, node_name})
    * `args` - 引数のリスト（通常は空）

  ## 戻り値

    * `{:ok, pid}` - スーパーバイザーが正常に起動した場合
    * `{:error, term()}` - スーパーバイザーの起動に失敗した場合

  """

 def start(_type, _args) do
   children = [
     {Payjpex.Config, []},
     {Payjpex.ApiClient, []}
   ]

   opts = [strategy: :one_for_one, name: Payjpex.Supervisor]
   Supervisor.start_link(children, opts)
 end
end

続いて、テストを書いていきます。

defmodule PayjpexTest do
  use ExUnit.Case
  doctest Payjpex

  describe "アプリケーションの起動" do
    test "スーパーバイザーが正常に起動すること" do
      # Application.start(:payjpex)は不要 - mix test が自動的に開始

      # スーパーバイザーが起動していることを確認
      assert Process.whereis(Payjpex.Supervisor) != nil
    end

    test "Config プロセスが起動していること" do
      assert Process.whereis(Payjpex.Config) != nil
    end

    test "ApiClient プロセスが起動していること" do
      assert Process.whereis(Payjpex.ApiClient) != nil
    end
  end
end

それでは次に、ConfigとApiclientを実装していきましょう。と言いたいところですが、長くなるので次回にします。