번역: Application Layering - A Pattern for Extensible Elixir Application Design (Aaron Renner)

소개

배경

대안적 접근 방식

ecto_sql ~> 3.0 (Hex package)
├── db_connection ~> 2.0 (Hex package)
│   └── connection ~> 1.0.2 (Hex package)
├── ecto ~> 3.1.0 (Hex package)
│   └── decimal ~> 1.6 (Hex package)
├── postgrex ~> 0.14.0 or ~> 0.15.0 (Hex package)
└── telemetry ~> 0.4.0 (Hex package)

패턴

앱을 여러 계층으로 나누기

• 이해 가능성 레이어는 단일 수준의 추상화에 초점을 맞추기 때문에 코드를 따라가기 쉬워집니다. 예를 들어, 비즈니스 로직 계층은 SQL 명령이나 이메일 전달과 같은 하위 수준의 세부 사항에 얽매이지 않고 사용자 등록 프로세스(데이터베이스에 사용자 만들기, 환영 이메일 보내기 등)에 집중할 수 있습니다.

• 유지 관리 용이성 이해하기 쉬운 코드는 개발자가 업데이트하기가 더 쉽습니다. 애플리케이션이 여러 계층으로 분리되어 있으면 새 로직을 어디에 작성해야 하는지 훨씬 더 쉽게 이해할 수 있습니다. 데이터가 외부 API로 전송될 때 직렬화되는 방식에 대한 업데이트는 API 클라이언트와 같은 낮은 수준의 레이어에서 수행하는 것이 좋습니다. 마찬가지로 새로운 비즈니스 프로세스를 지원하는 로직은 상위 수준의 비즈니스 로직 계층에서 작성해야 합니다.

• 적응성 상위 계층은 명확하게 정의된 API를 통해 하위 계층과 통신하기 때문에 하위 계층의 구현을 동일한 API를 준수하는 개선된 구현으로 대체할 수 있습니다. 따라서 상위 레이어까지 변경 사항이 파급되지 않고 전체 레이어의 구현을 교체할 수 있습니다.

최상위 API 구축하기

• 추가 모듈이 공개되면 하위 모듈이 공용 API의 일부인지 아니면 내부적으로만 호출해야 하는 하위 수준의 구현 세부 사항인지 파악하기가 매우 어려워집니다.

• 여러 구성 요소에 걸쳐 있는 새로운 비즈니스 프로세스를 추가할 때(예: 계정을 만들고 환영 알림을 보내는 사용자 등록) 최상위 공개 API 모듈은 이러한 구성 요소를 하나의 비즈니스 프로세스로 묶는 장소 역할을 합니다. 최상위 비즈니스 로직을 위한 합의된 단일 장소가 없으면 이 로직이 어디로 이동해야 할지 불분명해집니다.

네임스페이스를 활용하여 레이어 표시하기

• 공용 API에서 참조하는 구조체 전용 모듈.

• 공개 API의 구현 세부 사항이며 공개적으로 호출되지 않는 내부 헬퍼 모듈.

defmodule ZoneMealTracker do
	@moduledoc """
  Public API for ZoneMealTracker application
  """
  alias ZoneMealTracker.User

  @doc """
  Registers a new user with email and password.
  """
  @spec register_user(String.t(), String.t()) ::
          {:ok, User.t()} | {:error, :email_already_registered}
  def register_user(email, password), do: #...
end

defmodule ZoneMealTracker.User do
	@moduledoc """
  User struct
  """
  # This is a struct module used by the public APIdefstruct [:id, :email]

  @type id :: String.t()
  @type t :: %__MODULE__{
    id: id,
    email: String.t()
  }
end

defmodule ZoneMealTracker.Notifications do
	@moduledoc false

  # This module is just an implementation detail of ZoneMealTracker
  # and not exposed on the public API. You can tell this by `@moduledoc false`
  # and it doesn't define a struct.
  #
  # No modules other than ZoneMealTracker should call this because it's
  # not part of the public API.
  @spec send_welcome_message(User.t) do
end

네임스페이스를 완전히 활용하기

1. 최상위 모듈은 퍼블릭 API입니다.

2. 하위 모듈은 다음과 같습니다:
1. 공용 API에서 참조하는 구조체 전용 모듈.
2. 공개 API의 구현 세부 사항이며 공개적으로 호출되지 않는 내부 헬퍼 모듈.

1. 현재 모듈은 API입니다.

2. 자식 모듈은 다음 중 하나입니다.
1. 현재 모듈의 API가 참조하는 구조체
2. API의 구현에서 사용되는 내부 모듈

3. 모듈은 직계 자식에만 액세스해야 합니다. 형제자매, 손자, 증손자 등에는 액세스할 수 없습니다
1. 형제자매에 액세스해야 하는 경우 로직은 다음 상위 네임스페이스로 이동해야 합니다.
2. 손자녀에 액세스해야 하는 경우 자식 모듈에서 해당 기능을 위한 API를 제공해야 합니다.

자연스럽게 생성되는 레이어

1. 모듈의 로직이 어떻게 구현되는지 신경 쓰지 않는 한 모듈의 자식을 살펴볼 필요가 없습니다. 예를 들어 ZoneMealTracker.register_user/2 함수를 호출하는 경우 사용자가 제대로 등록되었다는 것을 신뢰할 수 있어야 합니다. 해당 코드나 하위 모듈을 살펴봐야 하는 유일한 이유는 사용자를 등록하는 방법을 알아야 할 때입니다.

2. 코드베이스를 이해하기 쉽게 유지합니다. 상사가 “이제 사용자가 등록되면 메트릭을 전송해야 한다”고 말하는 경우, 이 새로운 기능을 통합하기 위해 ZoneMealTracker.register_user/2가 논리적으로 좋은 곳입니다. 이 최상위 퍼블릭 API를 사용할 수 없다면 사용자 등록은 ZoneMealTracker.Accounts.register_user/1과 같은 기존 컨텍스트에 배치할 수 있습니다. 그러나 일부 기능은 비즈니스 로직 계층에서 작동하고 다른 기능은 지속성 계층에서 작동하므로 ZoneMealTracker.Accounts 모듈을 이해하기 더 어렵게 만듭니다. 이제 개발자는 어떤 함수가 상위 수준(비즈니스 로직)이고 어떤 함수가 하위 수준(지속성 로직)인지를 기억하고 현재 작업 중인 수준에 적합한 함수를 호출해야 합니다. 모듈의 API가 단일 추상화 수준에서만 작동한다면 훨씬 더 간단합니다.

구현을 스왑 가능하게 만들기

• 상위 레벨 레이어는 “왼쪽 포트”를 통해 육각형 내부의 로직을 호출하고

• 육각형 내부의 로직은 “오른쪽 포트”를 통해 하위 레벨 레이어를 호출합니다.

• 외부 서비스를 호출하지 않고도 비즈니스 로직을 쉽게 단위 테스트할 수 있습니다.

• 다른 팀이 하위 레이어를 구축하는 동안 앱의 상위 레이어를 개발할 수 있도록 가짜 데이터를 반환하는 하위 레이어의 구현을 빌드합니다.

• 하위 레이어 구현 코드를 실제로 작성하지 않고도 하위 레이어 API의 기능을 강화할 수 있습니다. 이를 통해 어떤 데이터 저장소를 사용할지, 데이터베이스 테이블을 어떻게 구성할지 등과 같은 기술적 결정을 제공해야 하는 인터페이스에 대한 이해가 명확해질 때까지 연기할 수 있습니다.

• 변화하는 비즈니스 요구 사항에 쉽게 적응할 수 있습니다. 예를 들어, 비즈니스에서 새로운 API 제공업체로 마이그레이션하기를 원할 경우 해당 하위 계층의 새로운 구현으로 교체하기만 하면 됩니다. 새 구현이 이전 구현과 동일한 코드 수준의 인터페이스를 제공할 수 있다면 업스트림에 영향을 주지 않고 새 구현을 교체할 수 있습니다.

엘릭서에서 자손 레이어를 교체하는 메커니즘

• 협업 함수를 선택적 매개변수로 주입하기

• 함수를 호출하기 전에 현재 구현을 조회하기

• 현재 구현을 백그라운드에서 위임하는 API 모듈 호출하기

@spec register_user(String.t(), String.t()) ::
        {:ok, User.t()} | {:error, :email_already_registered}
def register_user(email, password) do
  case AccountStore.create_user(email, password) do
    {:ok, %User{id: user_id} = user} ->
      :ok = Notifications.set_user_email(user_id, email)
      :ok = Notifications.send_welcome_message(user_id)

      {:ok, user}

    {:error, :email_not_unique} ->
      {:error, :email_already_registered}
  end
end

스와핑 접근 방식: 협업 함수를 선택적 매개변수로 삽입하기

@type register_user_opt ::
  {:create_user_fn, (String.t(), String.t() -> {:ok, User.t()} | {:error, Changeset.t}) |
  {:set_primary_notification_email_fn, (String.t(), String.t() -> :ok)} |
  {:send_welcome_message_fn, (String.t() -> :ok)}

@spec register_user(String.t(), String.t()) ::
        {:ok, User.t()} | {:error, :email_already_registered}
def register_user(email, password, opts \\ []) do
  create_user_fn = Keyword.get(opts, :create_user_fn, &AccountStore.create_user/2)
  set_primary_notification_email_fn =
    Keyword.get(opts, :set_primary_notification_email, &Notifications.set_user_email/2)
  send_welcome_message_fn =
    Keyword.get(opts, :send_welcome_message, &Notifications.send_welcome_message/1)

  case create_user_fn.(email, password) do
    {:ok, %User{id: user_id} user} ->

      :ok = set_primary_notification_email_fn.(user_id, email)
      :ok = send_welcome_message_fn.(user_id)

      {:ok, user}

    {:error, :email_not_unique} ->
      {:error, :email_already_registered}
  end
end

• 낮은 진입 장벽

• 협업 기능을 다른 구현으로 교체할 수 있습니다. 추가 모듈을 정의할 필요가 없습니다.

• 함수 호출마다 대체 구현을 교체할 수 있습니다. 애플리케이션 환경에서 글로벌 구성이 필요하지 않습니다.

• 함수를 빠르게 더 복잡하고 추론하기 어렵게 만듭니다.

• 상당한 코드 변경이 필요함

• 모의 구현과 대체 구현이 예상과 다른 방향으로 흐르기 쉬움

• 다이얼라이저 지원 없음

스와핑 접근 방식: 함수를 호출하기 전에 현재 구현을 조회하기

@spec register_user(String.t(), String.t()) ::
        {:ok, User.t()} | {:error, :email_already_registered}
def register_user(email, password) do
  case account_store().create_user(email, password) do
    {:ok, %User{id: user_id} = user} ->
      :ok = notifications().set_user_email(user_id, email)
      :ok = notifications().send_welcome_message(user_id)

      {:ok, user}

    {:error, :email_not_unique} ->
      {:error, :email_already_registered}
  end
end

defp account_store do
  Application.get_env(:zone_meal_tracker, :account_store, AccountStore)
end

defp notifications do
  Application.get_env(:zone_meal_tracker, :notifications, Notifications)
end

• Mox와 호환

• 함수 호출 시 코드 변경이 필요함

• 모듈 이름이 동적으로 확인되므로 다이얼라이저에서 작동하지 않음

• 모든 호출자 모듈이 현재 구현을 직접 조회해야 합니다. 이는 상당한 부담이 됩니다.

• 현재 구현은 애플리케이션 환경을 통해 전역적으로 제어됩니다. 따라서 여러 구현을 병렬로 실행하기가 어렵습니다.

스와핑 접근 방식: 백그라운드에서 현재 구현에 위임하는 API 모듈을 호출합니다.

@spec register_user(String.t(), String.t()) ::
        {:ok, User.t()} | {:error, :email_already_registered}
def register_user(email, password) do
  case AccountStore.create_user(email, password) do
    {:ok, %User{id: user_id} = user} ->
      :ok = Notifications.set_user_email(user_id, email)
      :ok = Notifications.send_welcome_message(user_id)

      {:ok, user}

    {:error, :email_not_unique} ->
      {:error, :email_already_registered}
  end
end

defmodule ZoneMealTracker.AccountStore do
  @moduledoc false

  alias ZoneMealTracker.AccountStore.User

  @behaviour ZoneMealTracker.AccountStore.Impl

  @impl true
  @spec create_user(User.email(), User.password()) ::
          {:ok, User.t()} | {:error, :email_not_unique}
  def create_user(email, password) do
    impl().create_user(email, password)
  end

  defp impl do
    Application.get_env(:zone_meal_tracker, :account_store, __MODULE__.PostgresImpl)
  end
end

defmodule ZoneMealTracker.AccountStore.PostgresImpl do
  @moduledoc false

  alias Ecto.Changeset
  alias ZoneMealTracker.AccountStore.PostgresImpl.InvalidDataError
  alias ZoneMealTracker.AccountStore.PostgresImpl.Repo
  alias ZoneMealTracker.AccountStore.User

  @behaviour ZoneMealTracker.AccountStore.Impl

  @impl true
  @spec create_user(User.email(), User.password()) ::
          {:ok, User.t()} | {:error, :email_not_unique}
  def create_user(email, password) when is_email(email) and is_password(password) do
    %User{}
    |> User.changeset(%{email: email, password: password})
    |> Repo.insert()
    |> case do
      {:ok, %User{} = user} ->
        {:ok, user}

      {:error, %Changeset{errors: errors}} ->
        if Enum.any?(errors, &match?({:email, {"is_already_registered", _}}, &1)) do
          {:error, :email_not_unique}
        else
          raise InvalidDataError, errors: errors
        end
    end
  end
end

defmodule ZoneMealTracker.AccountStore.Impl do
  @moduledoc false

  alias ZoneMealTracker.AccountStore.User

  @callback create_user(User.email(), User.password()) ::
              {:ok, User.t()} | {:error, :email_not_unique}
end

• 클라이언트 코드를 변경할 필요가 없음

• 다이얼라이저 작동

• 한 곳에서 구현을 교체할 수 있음

• Mox와 호환

• 네임스페이스가 추가되어 여러 구현을 쉽게 분리할 수 있습니다. 각 구현에는 고유한 네임스페이스가 있으며, 구현을 삭제하는 것은 해당 네임스페이스를 삭제하는 것만큼이나 쉽습니다.

• 더 많은 스캐폴딩이 필요함

• 네임스페이스 계층 구조에 추가 레벨 추가

• 현재 구현은 애플리케이션 환경을 통해 전역적으로 제어됩니다. 따라서 여러 구현을 병렬로 실행하기가 어렵습니다.

단위 테스트

# lib/zone_meal_tracker.ex

defmodule ZoneMealTracker do
  @moduledoc """
  Public API for ZoneMealTracker
  """

  alias ZoneMealTracker.AccountStore
  alias ZoneMealTracker.Notifications

  @spec register_user(String.t(), String.t()) ::
        {:ok, User.t()} | {:error, :email_already_registered}
  def register_user(email, password) do
    case AccountStore.create_user(email, password) do
      {:ok, %User{id: user_id} = user} ->
        :ok = Notifications.set_user_email(user_id, email)
        :ok = Notifications.send_welcome_message(user_id)

        {:ok, user}

      {:error, :email_not_unique} ->
        {:error, :email_already_registered}
    end
  end
end

# test/test_helper.exs

Mox.defmock(ZoneMealTracker.MockAccountStore,
  for: ZoneMealTracker.AccountStore.Impl
)

Application.put_env(
  :zone_meal_tracker,
  :account_store,
  ZoneMealTracker.MockAccountStore
)

Application.put_env(
  :zone_meal_tracker,
  :notifications_impl,
  ZoneMealTracker.MockNotifications
)

Mox.defmock(ZoneMealTracker.MockNotifications,
  for: ZoneMealTracker.Notifications.Impl
)

# test/zone_meal_tracker.exs

defmodule ZoneMealTrackerTest do
  use ExUnit.Case, async: true

  import Mox

  alias ZoneMealTracker
  alias ZoneMealTracker.MockAccountStore
  alias ZoneMealTracker.MockNotifications
  alias ZoneMealTracker.User

  setup [:set_mox_from_context, :verify_on_exit!]

  test "register_user/2 when email is unique" do
    email = "foo@bar.com"
    password = "password"
    user_id = "123"
    user = %User{id: user_id, email: email}

    expect(MockAccountStore, :create_user, fn ^email, ^password ->
      {:ok, user}
    end)

    MockNotifications
    |> expect(:set_user_email, fn ^user_id, ^email -> :ok end)
    |> expect(:send_welcome_message, fn ^user_id -> :ok end)

    assert {:ok, ^user} = ZoneMealTracker.register_user(email, password)
  end

  test "register_user/2 when email is already taken" do
    email = "foo@bar.com"
    password = "password"

    expect(MockAccountStore, :create_user, fn ^email, ^password ->
      {:error, :email_not_unique}
    end)

    assert {:error, :email_already_registered} = ZoneMealTracker.register_user(email, password)
  end
end

아래쪽까지 교체 가능한 레이어

애플리케이션 구조를 반영하는 파일 구조

lib/zone_meal_tracker/
  account_store.ex <- Top level API module
  account_store/
    impl.ex <- Behaviour to be implemented by top level module and impls
    in_memory_impl.ex <- An in-memory implementation
    in_memory_impl/ <- modules used only by this specific implementation
      state.ex
    login.ex <- struct returned by public API
    postgres_impl.ex <- A postgres-backed implementation
    postgres_impl/ <- modules used only by this specific implementation
      domain_translator.ex
      exceptions.ex
      login.ex
      repo.ex
      supervisor.ex
      user.ex
    supervisor.ex <- Helper module used across all implementations (@moduledoc false)
    user.ex <- struct returned by public API

• _impl로 끝나는 모든 것은 구현입니다. <impl_name>_impl/ 폴더 안에 있는 모든 것은 해당 구현에서만 사용되는 헬퍼 모듈입니다.

• impl.ex는 최상위 모듈과 구현을 동기화 상태로 유지하는 역할을 합니다.

• 폴더에 있는 대부분의 다른 모듈(application.ex 또는 supervisor.ex와 같이 잘 알려진 모듈 제외)은 API에서 참조하는 구조체 전용 모듈입니다.

통합 테스트

존밀트래커 앱의 통합 테스터 폴더에 예제 통합 테스터가 있습니다.

팁과 요령

• 비즈니스 로직 레이어와 외부 서비스(API, 데이터베이스 등)에 연결되는 레이어

• 뚜렷한 비즈니스 로직 레이어. 예를 들어, 개발자는 ZoneMealTracker.Notifications에 대한 스와핑 메커니즘을 삽입하여 상위 계층인 ZoneMealTracker를 따로 테스트할 수 있습니다. ZoneMealTracker를 테스트할 때는 알림이 전송되는 방식은 신경 쓰지 않고 ZoneMealTracker.Notifications에서 적절한 함수가 호출되는지만 신경 쓰면 됩니다.

구현 세부 정보를 API에 노출하지 않기

긴 네임스페이스로 작업하는 것

defmodule ZoneMealTracker.DefaultImpl
						.Notifications.DefaultImpl.NotificationPreferenceStore.PostgresImpl.PrimaryEmail do

end

• 각 내부 앱에는 자체 mix.exs가 있으므로 어떤 레이어가 종속성을 도입하는지 쉽게 알 수 있습니다.

• API 클라이언트와 같은 독립형 라이브러리는 엄브렐러에서 자체 프로젝트로 쉽게 추출하여 Hex에 게시할 수 있습니다.

• 내부 애플리케이션에서도 최상위 모듈은 나머지 시스템에서 빌드할 수 있는 API를 노출합니다. 이 모듈에는 추출할 가치가 있을 만큼 충분한 기능이 있으므로 이 최상위 내부 API에 대한 문서도 추가했습니다. 이제 개발자가 프로젝트에 대한 ExDoc을 생성할 때 기본 공개 API(ZoneMealTracker)뿐만 아니라 ZMTNotifications와 같이 접근 가능한 모든 내부 API도 볼 수 있습니다.

API 모듈에 로직 없음

# API Module that contains logic
defmodule ZMTNotifications do
  @spec fetch_registered_email(String.t()) | {:ok, String.t()} | {:error, :not_found}
  def fetch_registered_email(email) do
    current_impl().fetch_registered_email(
  end

  @spec email_registered?(String.t) :: boolean
  def email_registered?(email) do
    # This contains logic instead of a passthrough
    match?({:ok, _}, fetch_email_registered(email)
  end
end

# Module being tested
defmodule ZoneMealTracker do

  @spec email_registered?(String.t) :: boolean
  def email_registered?(email) do
    # Code under test
    ZMTNotifications.email_registered?(email)
  end
end

# Test Case
defmodule ZoneMealTrackerTest do
  use ExUnit.Case
  import Mox
  alias ZoneMealTracker.MockZMTNotifications

  test "email_registered?/1 returns true when email is registered" do
    # Although the code under test is calling
    # `ZMTNotifications.email_registered?/1`, we have to know to mock
    # `fetch_registered_email/1` because there is logic in
    # `ZMTNotifications.email_registered?/1` instead of being just a straight
    # passthrough.

    expect(MockZMTNotifications, :fetch_registered_email, fn email -> {:ok, email})

    assert ZoneMealTracker.email_registered?("foo@bar.com")
  end
end

이전 작업과의 관계

최종 조언

• 비공개 함수를 추출하여 공개 함수를 더 읽기 쉽게 만들기

• 여러 개의 관련 비공개 함수가 추출되었거나 이러한 비공개 함수에 대한 단위 테스트를 작성해야 하는 경우 하위 모듈로 추출합니다.

• 내 비즈니스 로직에 대한 테스트가 외부 서비스 또는 별도의 비즈니스 로직 섹션에 대한 호출이 필요하여 작성하기 어려운 경우, 내 비즈니스 로직과 외부 서비스/별도의 도메인 사이의 경계 역할을 하는 스왑 가능한 계층을 모듈에 삽입합니다.