外部の決済サービスが、支払いの status に REVIEW(不正検知の審査中)という値を 1 つ足しました。呼び出す側のコードは例外を 1 件も出さず、そのまま動き続けます。以下は、決済サービスの値を 4 か所でそのまま読むコードと、値を 1 か所で自分たちの語に置き換えるコードに、REVIEW の支払いを 1 件ずつ渡した結果です。決済サービスとコードは、本記事のために書いた架空のものです。

上は ACL を置かない実装。status が REVIEW の支払いが出荷・メール・売上・在庫の 4 か所に直接届き、出荷は PENDING と同じ扱いで出荷を待つ、メールは PENDING と同じ扱いで入金案内のメールを送り(誤り)、売上は PAID と同じ扱いで計上し(誤り)、在庫は FAILED と同じ扱いで引当を外す(誤り)。誤りは 4 か所中 3 か所、例外は 0 件。下は ACL を置いた実装。REVIEW は ACL の translate() で確認中に置き換わり、ログに 1 行残る。4 か所とも確認中として扱い、出荷を待つ・送らない・計上しない・引当を保つで、誤りは 0 か所

status が REVIEW の支払い 1 件に対する 4 か所の動き

上の実装では、メールの処理は同じ 1 件の支払いを入金待ちとして、売上の処理は支払済として、在庫の処理は失敗として扱いました。4 か所のうち 3 か所が誤った動きをしていますが、どこにもエラーは出ていません。

本記事でいう語は、業務の概念をコードで表した型や状態の名前で、その集まりをモデルと呼びます。

下の translate() のように、外部システムから受け取ったものを自分たちの語に置き換える層を Anticorruption Layer(腐敗防止層、以下 ACL)と呼びます。Anti-Corruption Layer とも綴ります。Eric Evans 氏が 2003 年の書籍『Domain-Driven Design』で名付けたパターンで、相手のシステムにはほとんど手を入れず、呼ぶ側で作ります。

ACL が必要になるのは、決済・配送・社内の古い基幹システムのように、自分たちでは変えられない外部の API を呼ぶ時です。既存のコードで gateway や translator という名前の層に出会い、なぜわざわざ型を詰め替えているのかと思った人も、本記事の読者です。


本記事では、次の疑問に答えます。

  • 外部の API が値を 1 つ足すと、呼ぶ側のコードで何が起きるのか。
  • 値の追加と項目名の変更で、壊れ方はどう違うのか。
  • ACL を置けば、知らない値で誤らずに済むのか。
  • ACL は値の他に何を置き換え、コードのどこに置くのか。
  • ACL を作らずに、相手のモデルに従う方がよいのはいつか。

値の追加で起きること

実験に使った決済サービスは、支払いごとに次のような JSON を返します。status は、v1 の時点では PAID(支払済)、PENDING(コンビニ払いなどの入金待ち)、FAILED(失敗)の 3 つでした。

{"payment_id": "pay_0042", "status": "PAID", "amount": 3980}

DDD(Domain-Driven Design)では、開発するチームどうしの関係を上流と下流で表します。この決済サービスのように、自分たちの行動が相手の成否を左右する側を上流、左右される側を下流と呼びます。下流が何をしても、上流にはほとんど影響しません。

上流と下流は呼び出しの向きとは限らず、決済サービスが通販のシステムへ通知を送ってくる時も、決済サービスが上流です。上流は、境界を意識して設計されたシステムとは限らず、社内の古い基幹システムのこともあります。

下流である通販のシステムには、出荷、購入者へのメール、売上の計上、在庫の引当という 4 か所に、status を読む処理があります。以下の no_acl.py は、4 か所がそれぞれ上流の文字列をそのまま比べるコードです。どの関数も v1 の 3 つの値を前提に書き、知らない値で落ちないよう最後に else を置いています。

def shipping(p):  # 出荷
    if p["status"] == "PAID":
        return "出荷する"
    elif p["status"] == "FAILED":
        return "取り消す"
    else:
        return "出荷を待つ"


def mail(p):  # 購入者へのメール
    if p["status"] == "PAID":
        return "お礼のメール"
    elif p["status"] == "FAILED":
        return "失敗のメール"
    else:
        return "入金案内のメール"


def sales(p):  # 売上の計上
    if p["status"] in ("PENDING", "FAILED"):
        return "計上しない"
    else:
        return "計上する"


def stock(p):  # 在庫の引当
    if p["status"] in ("PAID", "PENDING"):
        return "引当を保つ"
    else:
        return "引当を外す"

v2 で、決済サービスが REVIEW を足しました。不正検知の審査に回った支払いで、数時間後に PAID か FAILED に変わります。正しい扱いは、審査が終わるまで決まっていない支払いとして待つこと、つまり出荷を待ち、メールは送らず、売上に計上せず、在庫の引当を保つことです。status が REVIEW の支払いを 4 つの関数に渡すと、次のようになりました。

A: ACL なし
  出荷  出荷を待つ    v1 の PENDING と同じ扱い
  メール 入金案内のメール v1 の PENDING と同じ扱い  ← 誤り(正しくは 送らない)
  売上  計上する     v1 の PAID と同じ扱い  ← 誤り(正しくは 計上しない)
  在庫  引当を外す    v1 の FAILED と同じ扱い  ← 誤り(正しくは 引当を保つ)
  誤り 3/4 か所、例外 0 件

カードで払った購入者にコンビニ払いの入金案内が届き、審査で落ちるかもしれない支払いが売上に入り、引当を外した在庫は別の購入者に売れます。審査が通って PAID に変わった時には、在庫が残っていないかもしれません。


4 つの関数が REVIEW をばらばらに扱った理由は、else の中身にあります。以下は、v1 の値を入れた箱として 4 つの関数の分岐を並べた図です。

出荷・メール・売上・在庫の 4 つの関数の分岐を横に並べた図。右端の赤い枠が else。出荷とメールの else には PENDING が、売上の else には PAID が、在庫の else には FAILED が入っていて、REVIEW はそれぞれの else に PENDING・PENDING・PAID・FAILED と並んで入る

4 つの関数の分岐と、REVIEW が入る else

else は「それ以外」と書いてありますが、書いた時点では残っている値が決まっていました。出荷とメールの else は PENDING のための分岐で、売上の else は PAID の、在庫の else は FAILED のための分岐です。REVIEW は、それぞれの else に残っていた値の意味を引き継ぎます。同じ書き方の else でも、条件を == で並べたか in で除外したかで、残る値が変わります。

出荷の関数だけが正しく動いたのも、else に残っていた値が、たまたま REVIEW と同じ「まだ決まっていない」意味だったからです。テストを v1 の 3 つの値で書いていれば、入力に REVIEW が現れないので、v2 の後もテストは落ちません。


余談: 届いた値を別の意味で読んだ事故

受け取る側が、送る側の値を取り決めと違う意味で読んだ例として、1996 年 6 月 4 日の Ariane 5 の初飛行があります。事故調査委員会の報告書によると、機体の姿勢を測る慣性基準装置(SRI)は予備と主系の 2 台とも、同じソフトウェアの例外で相次いで故障を宣言し、主系は姿勢を表すデータの代わりに診断用のビットパターンを送りました。搭載計算機(OBC)はそれを飛行データとして読み、起きていない姿勢のずれを直そうとしてノズルを大きく振りました。機体は飛行シーケンスを始めてから約 39 秒後に分解し、自爆装置が働きました。

規模も仕組みも違いますが、受け取る側が、届いた値を取り決めと違う意味で解釈した点は同じです。


上流にとっては壊さない変更

決済サービスから見ると、値の追加は利用者を壊さない変更として扱われることがあります。決済サービスを提供する Stripe の API では、決まった文字列の集合から値を取る項目を enum と呼び、値が増えない closed と値が増える open の 2 種類に分けています。API リファレンスによると、open な enum には API のバージョンを上げずに新しい値を足すことがあり、受け取る側には switch 文に default の分岐を置くような「安全な既定の動き」を書くよう勧めています。

実験の 4 つの関数は、全て else という既定の分岐を持っていました。それでも 3 か所が誤ったのは、各関数が、書いた時点で残っていた値に合わせて既定の分岐で何をするか決めていたからです。安全な既定の動きは、関数ごとに決める限り揃いません。


改名は例外で止まる

比べるために、v3 で決済サービスが status という項目名を payment_status に変えた場合も試しました。

A: ACL なし: KeyError を出した関数 4 個(mail, sales, shipping, stock)

4 つの関数は全て KeyError で止まりました。項目名の変更は上流にとっても互換を壊す変更で、Stripe のようにバージョンを持つ API では、新しいバージョンの変更として出されます。テストが v1 の JSON のままなら通り続けますが、本番では最初の 1 件で例外が出るので、呼ぶ側もすぐに気付けます。

上流の変更上流の扱いACL なしの 4 か所で起きたこと
値の追加(REVIEW)互換を保つ変更として扱われることがある例外 0 件のまま 3 か所が誤る
項目名の変更(payment_status)互換を壊す変更4 か所が KeyError で止まる

この実験のように上流の値を else で受ける書き方では、上流が「壊さない」と考える変更の方が、例外を出さずに誤りました。4 つの関数は p["status"] で読んでいたので改名で止まりましたが、p.get("status") で読んでいれば、改名も黙って else に落ちます。


翻訳を 1 か所に集める

ACL を置いた実装(lab と出力では C と呼びます)では、決済サービスの status を読むのは translate() だけです。上流の値は、通販のシステムが自分で決めた 4 つの状態(PaymentState)に置き換えます。4 つ目の UNCONFIRMED(確認中)は、上流から意味の分からない値が来た時の行き先として、最初から用意しておく状態です。

class PaymentState(enum.Enum):
    PAID = "支払済"
    AWAITING_DEPOSIT = "入金待ち"
    FAILED = "失敗"
    UNCONFIRMED = "確認中"  # 決済サービスから、意味の分からない値が来た


KNOWN = {
    "PAID": PaymentState.PAID,
    "PENDING": PaymentState.AWAITING_DEPOSIT,
    "FAILED": PaymentState.FAILED,
}


def translate(p):
    state = KNOWN.get(p["status"])
    if state is None:
        log.warning("知らない status: %r(payment_id=%s)", p["status"], p["payment_id"])
        return PaymentState.UNCONFIRMED
    return state


# 4 か所は、自分たちの 4 つの状態だけで分岐する。else を置かず、全ての状態を表に書く
ACTIONS = {
    #                              出荷          メール              売上          在庫
    PaymentState.PAID:             ("出荷する",   "お礼のメール",     "計上する",   "引当を保つ"),
    PaymentState.AWAITING_DEPOSIT: ("出荷を待つ", "入金案内のメール", "計上しない", "引当を保つ"),
    PaymentState.FAILED:           ("取り消す",   "失敗のメール",     "計上しない", "引当を外す"),
    PaymentState.UNCONFIRMED:      ("出荷を待つ", "送らない",         "計上しない", "引当を保つ"),
}

4 か所の処理は ACTIONS の表を引くだけで、上流の文字列を一度も見ません。PaymentState は通販のシステムが持つ型なので、状態が増えるのは自分たちが増やした時だけです。増やした時は、表に行を足さない限り、その状態の支払いが来て表を引いた所で KeyError で止まります。

REVIEW を渡すと、translate() がログを 1 行残し、4 か所とも確認中として扱いました。

C: ACL(知らない値は確認中)
  ログ: 知らない status: 'REVIEW'(payment_id=pay_0042)
  出荷  出荷を待つ    v1 の PENDING と同じ扱い
  メール 送らない     v1 のどの値とも違う扱い
  売上  計上しない    v1 の PENDING・FAILED と同じ扱い
  在庫  引当を保つ    v1 の PAID・PENDING と同じ扱い
  誤り 0/4 か所、例外 0 件

v3 の改名でも、KeyError を出したのは translate() の 1 か所だけでした。上流の項目名 status を読む関数は、ACL を置かない実装では 4 個、ACL を置いた実装では translate() だけで、直す場所もそこに集まります。

Evans 氏が書籍の要点をまとめた DDD Reference(PDF)では、ACL は次のように説明されています。

As a downstream client, create an isolating layer to provide your system with functionality of the upstream system in terms of your own domain model.

下流は隔離する層を作り、上流の機能を自分たちのモデルの語で使えるようにする、という意味です。実験の PaymentState が、ここでいう自分たちのモデルの語に当たります。同じ箇所は続けて、この層は上流が既に持つインターフェース越しに話すので、上流への変更はほとんど、あるいは全く必要ないと書いています。

ACL が必要な理由として DDD Reference が挙げるのは、上流とやり取りする項目や API が多いと、下流のモデルが場当たり的に上流のモデルへ似せて書き換えられていくことです。実験の 4 つの関数は、通販の語を持たず、決済サービスの 3 つの値で分岐を書いていました。上流のモデルに似せて書いたコードは、上流のモデルが変わると一緒に動きます。


置くだけでは防げない

ACL を置いても、知らない値の行き先を決めていなければ、else と同じことが 1 か所で起きます。以下の B は、知らない値を「入金待ち」に置き換える実装です。翻訳は KNOWN.get(p["status"], PaymentState.AWAITING_DEPOSIT) のように、辞書の既定値を書いただけです。

B: ACL(知らない値は入金待ち)
  出荷  出荷を待つ    v1 の PENDING と同じ扱い
  メール 入金案内のメール v1 の PENDING と同じ扱い  ← 誤り(正しくは 送らない)
  売上  計上しない    v1 の PENDING・FAILED と同じ扱い
  在庫  引当を保つ    v1 の PAID・PENDING と同じ扱い
  誤り 1/4 か所、例外 0 件

誤りは 3 か所から 1 か所に減りましたが、カードで払った購入者には、まだ入金案内が届きます。ログも残らないので、REVIEW が届いていることに誰も気付きません。B と C の違いは、知らない値を既存の状態に混ぜたか、そのための状態を別に用意したかだけです。C の 0/4 か所も、審査中のように決まるまで待てばよい値だったからで、確認中の扱いは値の意味に合わせて下流が決めます。

知らない値を「確認中」に置く代わりに、translate() で例外にして処理を止める作り方もあります。下流のモデルに意味の決まらない値が入らない点は同じで、止めた支払いを誰がどう扱うかを決めておく必要がある点も同じです。


翻訳するもの

status の値は、ACL が置き換えるものの 1 つです。上流と自分たちの間でずれやすいものには、次のような種類があります。

種類上流の例自分たちの語の例
値の集合REVIEW が増える open な enum4 つで閉じた PaymentState
項目名と形status・amount の平らな JSONPayment の型と、その中の状態と金額
成功と失敗の表し方失敗も HTTP 200 で返し、本文の項目で示す例外か、失敗を表す型
単位と時刻最小単位の整数、UTC の文字列金額の型、タイムゾーン付きの時刻
識別子上流の payment_id自分たちの注文番号との対応

成功と失敗の表し方は、実在の API でもよくずれます。例えば、Slack の Web API は、応答の JSON に ok という真偽値を持たせ、失敗の時は ok を false にして error に理由を入れます。Slack の Node.js 向け SDK の説明によると、Web API はエラーを返す時も HTTP のステータスを 200 にし、回数制限の時だけ 429 を返します。HTTP のステータスだけを見るコードは、この失敗を見落とします。

翻訳は、上流から受け取る向きだけではありません。Stripe の API では、要求で送る enum の値は、今サポートされている値だけが受け付けられます。自分たちの語から上流の語へ送る向きにも、置き換えが必要です。上流が出すイベントを非同期に受け取る経路も同じで、相手の形式で書かれたメッセージを自分たちの Domain Event に置き換えてから処理に渡します。

受け取った JSON は入口で自分たちの型に置き換え、それ以降は型を信じて書く、という考え方は、Parse, Don’t Validate と同じです。ACL は、その入口を外部システムとの境目に置いたものと見ることができます。


置く場所と形

ACL は、呼ぶ側のチームが自分のコードに作ります。上流のチームが配るクライアントライブラリ(SDK)は、上流のモデルをそのまま型にしたもので、ACL の代わりにはなりません。

Stripe の SDK は、Java や Go のような型付きの言語では、その SDK を出した時点の API バージョンに型が固定されると公式ドキュメントに書かれています。SDK の型に REVIEW が無くても、open な enum には値が増えることがあります。そのため SDK の型を下流のコードでそのまま使うと、ACL を置かない 4 か所と同じことが起きます。以下は、SDK を使う場合も含めて、ACL を置く位置を描いた図です。

左の灰色の領域が決済サービスの語で、決済サービスの API と SDK の型がある。右の青い領域が通販の語で、PaymentState、業務規則の ACTIONS の表、出荷・メール・売上・在庫の 4 か所がある。2 つの領域の境目に ACL の translate() があり、SDK の型から PaymentState への矢印は translate() だけを通る。業務規則は ACL の外、通販の語の領域に置く

ACL を置く位置と、業務規則を置く位置

図のように、SDK は決済サービスの語で書かれた部品です。translate() は、SDK と通販のコードをつなぐ境目に置きます。Microsoft の Azure Architecture Center にある解説は、このパターンが適さない場合を挙げる項の中で、ACL は翻訳に絞り、業務の規則や複数のシステムを呼ぶ順番の制御を置かないようにと書いています。実験で ACTIONS の表を translate() の外に置いたのも同じ理由で、「確認中なら出荷を待つ」は通販の業務規則であり、決済サービスの語とは関係がありません。

同じ解説によると、ACL はアプリケーションに組み込む部品としても、独立したサービスとしても作れます。独立したサービスにすると、呼び出しの遅延と、管理するサービスが 1 つ増えます。下流のアプリケーションが 1 つなら、実験のように同じプロセスの関数で足ります。

同じ翻訳を複数のプロセスで使う時は、独立したサービスにすれば 1 か所の更新で全てに届き、下流と別に配布でき、言語も上流のクライアントライブラリに合わせて選べます。


名前の似たパターン

同じ解説は、ACL を facade か adapter の層として作るパターンとも説明しています。facade は複雑な相手の API を単純な窓口にまとめる層、adapter は相手のインターフェースを自分が期待する形に合わせる層で、どちらも、著者 4 人の通称 Gang of Four から GoF 本と呼ばれる書籍『Design Patterns』に載っているパターンの名前です。実験の translate() は adapter に近い役です。

コンテナを並べる Adapter のパターンとは、名前が同じでも別物です。

ACL を独立したサービスにし、アプリケーションの隣で別のコンテナとして動かすと、配置は Ambassador と重なります。Ambassador は、アプリケーションの隣で外部への通信を代わりに受け持つコンテナで、再試行や接続先の切り替えはしても、受け取った値を下流の語には置き換えません。両者の区別は、翻訳した結果が下流のモデルで使う語になっているかどうかです。

上流の JSON を下流の型へ詰め替えるだけなら DTO(Data Transfer Object)の変換と変わりませんが、その変換が下流のモデルを上流から守る境目に置かれている時に、ACL と呼べます。


参照の向きと移行

実験のように同じプロセスの関数として作る時は、どちらがどちらを参照するかも決めておきます。下流が自分の語でインターフェースを宣言し、ACL がそれを実装すると、下流は ACL を参照せずに済みます。ACL を差し替えても、テストで偽物に替えても、下流のコードは変わりません。

同じ向きの変え方は Repository でも使います。ただし Repository が隠すのは自分たちの Aggregate を保存する先で、上流のモデルから守る ACL とは守る相手が違います。

古いシステムを新しいシステムへ少しずつ移す時も、新しいシステムの入口に ACL を置きます。古いシステムの項目名や状態の表し方を新しいシステムの中に持ち込むと、移し終えた後もその形が残るからです。移し方は Strangler Fig で扱っています。この使い方では、移し終えたら ACL を外すのか、置き続けるのかを先に決めておきます。外す前提なら、テストやエラーを包み直す型に掛ける手間を抑えられます。


上流の語が漏れる経路

translate() を作っても、上流の語が下流に漏れる経路は他にも残ります。

漏れる経路例止め方
上流の型を import する下流の関数が SDK の型を引数に取るimport を制限する lint を CI で回す
下流の型に生の値を持たせるOrder に status: str を足し、上流の値を入れる下流の型には PaymentState だけを持たせる
エラーの文面KeyError: 'status' が下流まで上がる下流で決めたエラーの型に包み直す
同じ ACL の使い回し業務の範囲が違う 2 つの下流が同じ translate() を使う下流ごとに翻訳を分ける

2 行目は、import が 1 本も無くても上流の語が入り込む例です。status に "REVIEW" が入り得る型を下流が持つと、その値の意味は、その型を読む全ての場所で判断されます。最後の行は、同じ上流を使う下流が 2 つある時に、1 つの ACL に両方の要求を集めると、どちらの語でもない共通のモデルが育つという話です。


他の選び方との比較

外部システムとの付き合い方は、ACL の他にもあります。DDD Reference では、上流のモデルに全面的に従って翻訳を作らない方式を Conformist と呼びます。下流は設計の自由が狭まりますが、統合は大きく単純になります。チームどうしの関係を並べた一覧は Bounded Context にあります。以下は、実験の 2 つの変更に対する違いです。

選び方作るもの値の追加(REVIEW)項目名の変更
Conformist(上流に従う)無し上流の値を読む全ての場所が影響を受ける読む全ての場所を直す
API のバージョンを固定する無しopen な enum は、固定しても増えることがある固定している間は届かない
上流に頼んで直してもらう無し上流が受けてくれれば、足す前に知らせてもらえる同左
ACL翻訳の層知らない値の行き先を 1 か所で決めるtranslate() だけを直す

API のバージョンを固定する方法は、Stripe なら要求ごとに Stripe-Version のヘッダーで指定します。項目名の変更のような互換を壊す変更は届かなくなりますが、open な enum への値の追加は、バージョンを上げなくても起こり得ます。固定と ACL は、守る範囲が違うので、両方を使うことができます。

上流を直してもらう方法は、上流のチームが同じ会社にいて、下流の要望を計画に入れてくれる時だけ取れます。DDD Reference で Conformist の説明が始まるのは、上流に下流の要望を叶える動機が無く、下流には手の打ちようがない状況です。決済サービスのような外部の事業者は、たいていこの状況に当たります。


DDD Reference は、設計の良い 2 つのシステムを協力的なチームの間で繋ぐなら翻訳は単純にでき、上流と調整できない時ほど翻訳は複雑になり、守りの色が濃くなる、とも書いています。ACL を選ぶと、統合する相手ごとに、両方の語を知る翻訳のコードを保守し続けることになります。翻訳で捨てた項目が後で要る時も手間が掛かります。実験の translate() は status だけを読み、amount を捨てています。売上の処理が金額を使うようになれば、translate() と、金額を受け取る下流の型を両方とも直します。

上流と下流でずれている所をどう扱うかも、UNCONFIRMED のように下流が決め、ACL の規則として書く必要があります。


ACL を作る前に見ること

外部システムの値を読むコードに出会ったら、最初に、上流の項目を読んでいる関数がいくつあるかを数えます。実験の run.py は、Python の ast で "status" という文字列を含む関数を数えました。1 か所しか読んでいないなら、ACL を作るよりも、その 1 か所の分岐を見直す方が早く済みます。

複数の場所が読んでいるなら、それぞれの else や default の分岐に、書いた時点でどの値が残っていたかを書き出します。冒頭の図で上に描いたように、分岐ごとに残っていた値が違えば、上流が値を 1 つ足しただけで、同じ支払いが場所ごとに別の意味になります。

ACL を作るなら、知らない値の行き先として、自分たちの語の中に専用の状態を用意します。実験の B のように既存の状態へ混ぜると、誤りは減っても無くならず、届いたことにも気付けません。C のように専用の状態に置いてログに残し、そのログを監視していれば、上流のチームが値を足したことに早く気付けます。


ACL を作らない場合

上流と自分たちの語がほぼ同じで、翻訳が項目名の写し替えだけになるなら、ACL は Conformist より手間が増えるだけです。1 回だけ流す移行スクリプトのように捨てる前提のコードにも、ACL は必要ありません。その場合も、上流の enum が open かどうかは、API のリファレンスで見ておく価値があります。

語のずれが、上流の設計が歪んでいることから来ていて、上流を直せる関係なら、直す方が根本的です。ただし、業務の範囲が違えばモデルが違うのは普通のことで、ずれていること自体は直す理由になりません。上流が別のチームで合意に時間が掛かるなら、下流が自分の判断だけで作れる ACL の方が早く進みます。

実験のコードと出力の全体は lab/ にあります。出力で acl.py の status を読む関数が 2 個になっているのは、B の translate_with_fallback() も同じファイルにあるためです。