2020-09-19

マイクロサービス時代のアプリケーションサーバ実装について

4年前の下書きが出てきたので、供養のために置いておきます。

SpringOne Platform 2016のKeynoteとSessionを、特にProject Reactor周りについて確認した。

これらに最近考えていたことを加えて、マイクロサービスやサーバサイドリアクティブについて（利点や必要性は一旦論点から外したうえで）実現するためのあるべき論をざっくり整理したい。プライベートプロジェクトで検証済みではあるがチーム開発でも通用するかは不明である。

なお簡単のためRxJava用語のみ記述するが、Project Reactor等の用語で置き換えても良い（Single → Mono, Observable → Flux）。

あるべき論

APIサーバ＆BFF共通

Repository（DAO）
- 境界を超えないデータストアに対するアクセスを担うレイヤのこと。
- Repositoryのメソッドは非同期I/Oを呼び出すことが期待される。よってSingleあるいはObservableを返すべき。
- 戻り値がない場合（例えば更新処理）でも、内部の処理が正常に終了したかどうかを表現するために Single<Void> を返すべき。
- 非同期I/Oを呼び出さないことが明らかな場合のみ、同期的にインスタンスを返しても良い。
Service（ビジネスロジック）
- ServiceのメソッドはDAOを通じて、あるいは境界外へアクセスするクライアントを通じて非同期I/Oを呼び出すことが期待される。よってSingleあるいはObservableを返すべき。
- 戻り値がない場合（例えばジョブキューにジョブを登録する場合）でも、内部の処理が正常に終了したかどうかを表現するために Single<Void> を返すべき。
- Repositoryから渡されたSingle/Observableのエラー処理（ログ出力等）は、
  - その Single/Observable がControllerから利用されるのであれば、Service内で行っても行わなくても良い。
  - その Single/Observable がControllerから利用されないのであれば、Service内で行う。
- Serviceは冪等性を保つ必要がある。UUID version 1でID採番する場合などは、処理結果にランダム失敗した性が含まれるので扱いに注意する（Eventual Consistencyを意識する）。
Client（境界外アクセス）
- RestTemplate等を直接呼び出す実装が多く見受けられるが、サーキットブレーカーや監視や自動テスト容易性を考えると一枚抽象化を入れた方が良いと思われる。
- 各マイクロサービス提供者がEntityと共にユーザに提供する。Serviceから呼び出され、HTTP等によるRPCを行う。よってSingleあるいはObservableを返すべき。
- コレオグラフィ優先採用するならば、基本的には使用しない方が良い。
EventBus
- Serviceによって購読ないしpublishされる。
Controller
- モデルとしてSingleやObservableをテンプレートエンジンに渡す。テンプレートエンジンの機能に応じて、SingleやObservableを変換するかもしれない。CompletableFutureあたりが有望か。
- 通信先サービスが正常動作しなかった場合、CircuitBreakerが落ちている場合のUIも考えておく。

BFFサーバの実装

WebAPIを多数コールして1つのレスポンスにまとめるには、大きく分けて2つ実装パターンが考えられる。

サーバ内ですべてのサービスからのレスポンスを束ね、1枚のHTMLページやJSONデータをつくり上げる
サービスから逐次受け取ったデータをクライアントに横流しして、クライアント側で組み立てる（Server-sent Event, WebSocket, Big pipe etc.）
- 2020年夏時点ではJSON listをうまく扱うJS手法はまだなさそう？Streams APIの安定化を待つ必要があるのでは。

完全な2だとBFFを作る意味が無いので、1を主体として見た目に影響の薄い部分で2のような遅延処理をを採用することが多いはず。しかし1のレスポンスを束ねる部分で各サービスに線形的に問い合わせてはレイテンシ低下が容易に発生するため、非同期I/Oを使った並行問い合わせが必要になる。

サーバ間連携

メッセージキューには永続性が必要
- コレオグラフィを志向してサービスを実装するためには「イベントを永続化してサブスクライバが何度も読みに行く」か「サービスを冪等にしてパブリッシャが何度もリトライする」かのどちらかになる。後者はパブリッシャがイベント発火によって行われる処理を知っている必要があるので、基本的には前者が好ましいと思われる（Webアプリだとパブリッシャが何度もリトライするような書き方だとユーザへのレスポンスが遅れるのも痛い）。
  - 2020年追記：一見意味不明だが、ここで言うサブスクライバとパブリッシャはサービス単位を指している（同一JVM内にあるインスタンスを比較しているわけではない）と思われる。前者はイベントが永続化することで、同じイベントを何度も聞きに行くケースのこと。複数種類のサブスクライバがいたり、サブスクライバが常時起動でなかったりするとこの必要性が生じるはず。後者は非同期処理を依頼する、例えば送信処理や投機的実行のケースで事実上リアルタイム性を求めているケースのこと。当時使ってたVertxがデフォルト設定で利用するhazelcastのイメージに引っ張られてそう。
- このため、キューに記録されたメッセージは1回以上必ず読まれること、つまりロストがないことを保証したい。そのためにはキューに永続性が必要。
サブスクライバごとにイベントの既読管理を行う
- コレオグラフィを採用するならば、1イベントにサブスクライバが多数いることも予想されるため、メッセージ（イベント）がConsumeされたかどうかはサブスクライバごとに管理する必要がある。
- 例えばKafkaなら、イベント種別＝Topic、サブスクライバ＝Consumer Groupとすることでサブスクライバごとの管理が可能。

備考

RxJava v2, reactive-streams そして Java9 Flow API について

現状では気にしないので良さそうな印象。

operatorすら用意されていないシンプルなreactive-streamsが、それだけ見ていれば詳細実装を気にしないで良いレベルのインタフェースになることは当面ないだろうし、そもそもそこを目指していないように見受けられる。ライブラリ提供者にとっては各プラットフォームを公平にサポートするための良いインタフェースになるだろうが、サービス開発者にとってはRxJavaやProject Reactorに直接依存・利用したほうがコードもシンプルになるし利用できる機能も多く便利なはず。

参考：

2020-09-19

CompletableFutureの何が嬉しいか、そしてReactorへ……

java reactor

そうですね。例えば2つのクエリをDBに投げて結果を合成する、みたいなことを書いてみると実感しやすいです。Statementをcloseする処理ももちろん書くのです。
— 達者でな (@Kengo_TODA) March 14, 2020

DBにクエリを2つ投げて合成する処理

例えばユーザーIDから所有するリソースを検索してその情報を返すAPI Stream<Resource> find(long userId) を実装するとします。Resourceは大量に帰ってくる可能性があるので、List<Resource>ではなくStream<Resource>として扱います。実装はどうなるでしょうか：

// blocking API (wrong)
try (UserDao userDao = daoFactory.createUserDao();
    ResourceDao resourceDao = daoFactory.createResourceDao();) {
  Stream<Long> resourceIds = userDao.search(userId); // ページング処理を隠蔽
  return resourceIds.map(resourceId -> {
    Resource resource = resourceDao.find(resourceId);
    return resource;
  }); // Stream<Result>
}

これは正常に動作しません。メソッドを抜ける前にtry-with-finallyブロックがDAOを閉じてしまうからです。呼び出し元がStream<Resource>を閉じてくれることを期待して、以下のようなコードになるでしょう：

// blocking API
UserDao userDao = daoFactory.createUserDao();
ResourceDao resourceDao = daoFactory.createResourceDao();
Stream<Long> resourceIds = userDao.search(userId); // ページング処理を隠蔽

// Streamが閉じられたらDAOも閉じる
resourceIds.onClose(userDao::close);
resourceIds.onClose(resourceDao::close);

return resourceIds.map(resourceId -> {
  Resource resource = resourceDao.find(resourceId);
  return resource;
}); // Stream<Result>

このように処理を遅延するコードはFutureでは書けません。Java8で登場したCompletableFutureを使うことになります。例えばUserにResourceがひとつだけ結びつく状態なら以下のように書けます：

// CompletableFuture
UserDao userDao = daoFactory.createUserDao();
ResourceDao resourceDao = daoFactory.createResourceDao();
CompletableFuture<Long> future = userDao.search(userId).whenComplete( ... );

return future.thenApply(resourceId -> {
  Resource resource = resourceDao.find(resourceId);
  return resource;
}).whenComplete( ... ); // CompletableFuture<Result>

が、Streamのように複数の値を返すモノに使うのは複雑な工夫が必要ですし、やりようによってはすべての値を一度にオンメモリに乗せてしまいます。私の知る限りではReactorフレームワークやRxJavaの採用がこの問題へのスマートな解になります。例えばFlux#using()を使うと以下のように書けます：

// Reactor
Flux<Long> resourceIds = Flux.using(daoFactory::createUserDao, userDao -> {
  return userDao.search(userId);
}, UserDao::close);

return resourceIds.flatMap(resourceId -> {
  Mono<Resource> resource = Mono.using(daoFactory::createResourceDao, resourceDao -> {
    resourceDao.find(resourceId);
  }, ResourceDao::close);
  return resource; // Flux<Resource>
});

blog.kengo-toda.jp

2020-09-15

Project Reactorでページング処理を書くにはFlux#expand()を使う

reactor

Bing検索で見つけるのが難しかったのでメモ。Project Reactorでページング処理を書く方法について。

例えばこういうAPIがあったときに、どう実装するか？

class Foo { ... }

class FooPage {
  @NonNull
  Foo[] getEntities();
  Optional<Integer> getNextPageNumber();
}

interface FooRepository {
  /** @param page 0-indexed page number */
  @NonNull
  Mono<FooPage> loadPage(int page);
}

class FooService {
  @Inject // use constructor injection instead in prod.
  FooRepository repository;

  @NonNull
  Flux<Foo> loadAll() {
   // TODO
  }
}

以下のようにFlux#expand()を利用する必要があります。引数には前回ロード時の値が入っているので、そこから次回のリクエストに使用するパラメータを算出します。大抵はサーバのレスポンスに次のページ番号が入っていたり、検索パラメータとして使用すべきトークンやIDが入っているはずなので、それを引き回す形になるでしょう。

  Flux<Foo> loadAll() {
    Flux<FooPage> fluxForPage = repository.loadPage(0).expand(prevPage -> {
      return prevPage.getNextPage().map(repository::loadPage).orElse(Mono.empty());
    });
    Flux<Foo> fluxForEntity = fluxForPage.flatMap(page -> Flux.fromArray(page.getEntities()));
    return fluxForEnttiy;
  }

Reactorはリソースの開放に using() を使うのもわかりにくかったですが、ページング処理もJavadocやGitHubを検索しても出てこないのでちょっと苦労しました。

2020-08-07

SLF4Jの1.8は安定版が出ないので2.0を使おうという話

SLF4J

前回の投稿で、SLF4Jには現在1.7、1.8、2.0の3バージョンがあるという話をしました。

これについてSLF4Jのuser向けメーリングリストで質問をしたところ、1.8の開発中にFluent Logging APIを追加するために2.0へとメジャーバージョンを上げたという旨の回答を得られました。つまり1.8は今後開発されず、安定版も出ないことになります。

[slf4j-user] Will version 1.8 be released in future?

よって現時点では1.8を利用する積極的な理由はあまりないと思われます。ライブラリ開発者としては、JPMS（Jigsaw）あるいはFluent Logging APIが必要なら2.0、そうでないなら1.7を選択することが良いのではないでしょうか。

2020-07-21

Javaライブラリを配布する際のログ周りにおける配慮と実践 2020

SLF4J java Gradle

この記事は、2013年に書いた記事を現状に合わせてアップデートするものです。結論から言うと、当時から id:miyakawa_taku さんがおっしゃっていた「APIは依存に含めて良い」を支持するものです。あるいは無難にバージョン 1.7.30 を使っておきましょう。

blog.kengo-toda.jp

slf4j-apiに1.7, 1.8, 2.0の3バージョンが生まれた

現在slf4j-apiには3つのバージョンが存在します。現在のSLF4Jエコシステムを考える上では、これらの違いを抑える必要があります：

1.7.x: Java 1.5から利用できるバージョンです。安定版にこだわるなら未だこのバージョンを使う必要があります。

1.8.x: JPMS（a.k.a. jigsaw）を採用しServiceLoaderを使ってBindingを呼び出すようになったバージョンです。Java 1.6が必要です。alpha0が出てから3年以上経ちますが、未だbeta4です*1。作業用ブランチも残っていないので、1.8は安定しないまま2.0開発に移ったものと思われます。

2.0.x: このバージョンからはJava 8が必要です。Fluent Logging APIが実装され、ログの書き方の選択肢が増えました。新しい実装はinterfaceのdefault methodを使って実装されているため、slf4j-api単体で変更が完結しており、binding側は変更なく利用できます。

複数バージョンの存在を踏まえ、ライブラリ配布者は何を気にするべきか

前出の情報を紐解くと、3バージョン間に眠る2つの差が見えてきます：

APIの差。slf4j-api 2.0.x には従来存在しなかったメソッドが増えている。これに依存したライブラリのユーザは、slf4j-api 2.0.xを利用しなければ実行時に NoSuchMethodError が出るかもしれない。
binding選択手法の差。slf4j-api 1.7.x と1.8.x以降では実装を決定するための手法が異なるため、apiとbindingのバージョンは揃える必要がある。

このうち2については、アプリケーションをビルドする開発者に責任があります。実行時にCLASSPATHにどのバージョンのAPIとbindingを含めるか、彼らに決定権があるからです。のでライブラリ提供者としては、彼らに選択肢と必要な情報を提供しつつ、1に取り組む必要があります。

考慮すべきはライブラリでFluent Logging APIを使っているかどうか、です。このAPIに依存していないなら、実行時にslf4j-apiのどのバージョンを利用しても問題ありません。

もし使っているなら、その旨をユーザに伝えて実行時にもslf4j-api 2.0.xを使ってもらう必要があります。そしてそのための最もsemanticな方法が、compileスコープで依存することです。ライブラリが2.0.xに依存しているにも関わらずに古いバージョンで依存が上書きされてしまった場合、ビルドツールによっては警告を発してくれます。Gradleの場合はもっと細かな依存指定も可能です。

よって、現時点では slf4j-api には compile スコープで依存することが望ましいと思います。bindingは引き続きprovidedあるいはtestスコープが望ましいでしょう。

どのバージョンを使うべきか

安定版にこだわるなら1.7.xを、JPMSを使いたいなら1.8.xか2.0.xを、Fluent Logging APIを使いたいなら2.0.xを選ぶことになるでしょう。

1.8.xと2.0.xはJPMSに準拠しており、モジュールを利用したビルドを行っているプロジェクトでも安心して使うことができます。ただどちらも安定版が出ていない点には注意が必要です。

2020-08-07 追記: 1.8を選択する積極的な理由がないことを以下の記事に記載しました。 SLF4Jの1.8は安定版が出ないので2.0を使おうという話 - Kengo's blog

マイナーケース：ライブラリとしても実行可能ファイルとしても配布する場合

私がメンテに参加しているSpotBugsは、spotbugs-gradle-pluginやspotbugs-maven-pluginなどから利用されるライブラリとしての性質と、CUIやGUIで実行される実行ファイルとしての性質とを持ち合わせています。内部的にはDistribution Pluginで配布用パッケージを作成しています。

この場合、Maven Centralにアップロードする pom.xml にはSLF4J bindingを依存として追加しない一方で、distribution pluginの対象にはSLF4J bindingを追加する必要があります。

runtimeOnly 依存を使うことが素直な解決になるでしょう。configurations.runtimeClasspath を配布用ファイルに入れる形になります。

ただSpotBugsの場合はEclipse用依存を別に管理している（Eclipse用のruntimeClasspathにはSLF4J bindingを入れたくない）ので、以下のようにconfigurationを自前で定義しています。

plugins {
    id 'distribution'
}
configurations {
  slf4jBinding
}
dependencies {
  implementation 'org.slf4j:slf4j-api:1.8.0-beta4'
  logBinding ('org.apache.logging.log4j:log4j-slf4j18-impl:2.13.3') {
    exclude group: 'org.slf4j'
  }
}
distributions {
  main {
    contents {
      from ([configurations.compileClasspath, configurations.slf4jBinding]) {
        into 'lib'
        include '**/*.jar'
      }
    }
  }
}

*1:newsページにはbeta5が公開された旨が記載されていますが、Maven Centralには来ていませんし、タグも残っていません

2020-06-25

研究などの学術的目的で問い合わせや協力依頼をいただく際の私の対応方針

たまに研究への協力依頼などをいただくのですが、それに対するポリシーをこちらにまとめます。説明用です。

連絡先

Twitterかメールを推奨しています。メールアドレスは私のウェブサイトで紹介しています。

サーベイに対する協力

常識的なボリュームのサーベイであれば協力させていただきます。URLと回答所要時間を共有いただければそれで充分です。

その他の協力

SpotBugsの使い方やbytecode manipulationなどについて、突っ込んだ質問をいただくことがあります。こうしたクローズドな質問はStackoverflowやGitHubで行っているFOSS活動とは一線を画するものですし、対応コストも高いので、基本的にはお受けしません。まずは対応するFOSSコミュニティ、あるいは周囲の指導担当者からの協力を得るようにしてください。ウェブサイトやメーリングリスト、GitHubプロジェクトなどで質問を行えることが多いはずです。

どうしても必要と思われる場合は、所属機関のメールアドレス（.ac.jpドメインなど）から所属と研究目的、得たい協力について説明するメールを送ってください。この際、指導担当者もCCに入れてください。指導担当者はあなたの指導に何らかのポリシーを持っているはずで、それを逸脱する助力をすることを避けるためです。

2020-06-21

GitHub Actions 最近のやらかし一覧

GitHub

FOSS開発で細かいやらかしを積み上げてきたのでまとめる。

テストの失敗原因レポートをartifactとしてアップロードしそこねる

actions/upload-artifactを使ってテストレポートをartifactとしてアップロードする際、以下の書き方だと失敗する。

# bad
    - run: |
      ./gradlew test --no-daemon --stacktrace
    - uses: actions/upload-artifact@v2
      with:
        name: reports
        path: build/reports

これはテストが失敗した時点で後続のstepsが実行されなくなるため。明示的に失敗時でもアップロードされるように指示する必要がある。

# bad
    - run: |
      ./gradlew test --no-daemon --stacktrace
    - uses: actions/upload-artifact@v2
      if: always() # this config is necessary to upload reports in case of build failure
      with:
        name: reports
        path: build/reports

forkからのPRではGITHUB_TOKENを除くsecretsを参照できない

secretsの存在を前提にしているコードがあると、forkからPRをもらったときにビルドが通らなくなる。

# bad
  - name: Decrypt file
    env:
      GPG_SECRET_PASSPHRASE: ${{ secrets.GPG_SECRET_PASSPHRASE }}
    run: |
      gpg --quiet --batch --yes --decrypt --passphrase="$GPG_SECRET_PASSPHRASE" --output decrypted encrypted
      # -> gpg: missing argument for option "--passphrase="

後述する方法でsecretsが空かどうか確認する必要がある。

if では $VAR で環境変数を参照できない

if で書くのはbashじゃくてexpressionなので、runに書くのと同じノリでやると失敗する。

# bad
    - name: Run SonarQube Scanner
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SONAR_LOGIN: ${{ secrets.SONAR_LOGIN }}
      if: ${{ $SONAR_LOGIN != "" }}
      run: |
        ./gradlew sonarqube -Dsonar.login=$SONAR_LOGIN --no-daemon

正しくはenvコンテキストを参照する（なお${{ .. }} で囲むのは必須ではない）か、

# good
    - name: Run SonarQube Scanner
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SONAR_LOGIN: ${{ secrets.SONAR_LOGIN }}
      if: env.SONAR_LOGIN != ""
      run: |
        ./gradlew sonarqube -Dsonar.login=$SONAR_LOGIN --no-daemon

bashで統一して読みやすくしたいなら run の中で判定する。

# good
    - name: Run SonarQube Scanner
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SONAR_LOGIN: ${{ secrets.SONAR_LOGIN }}
      run: |
        if [ "$SONAR_LOGIN" != "" ]; then
          ./gradlew sonarqube -Dsonar.login=$SONAR_LOGIN --no-daemon
        fi

gradleで環境変数があるときだけ特定タスクを実行する場合は、こういう書き方もできるらしい。シンプル。

    - name: Run SonarQube Scanner
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SONAR_LOGIN: ${{ secrets.SONAR_LOGIN }}
      run: |
        ./gradlew spotlessCheck build smoketest ${SONAR_LOGIN:+sonarqube} --no-daemon -Dsonar.login=$SONAR_LOGIN

Kengo's blog

Technical articles about original projects, JVM, Static Analysis and TypeScript.

マイクロサービス時代のアプリケーションサーバ実装について

あるべき論

APIサーバ＆BFF共通

BFFサーバの実装

サーバ間連携

備考

RxJava v2, reactive-streams そして Java9 Flow API について

CompletableFutureの何が嬉しいか、そしてReactorへ……

DBにクエリを2つ投げて合成する処理

関連記事

Project Reactorでページング処理を書くにはFlux#expand()を使う

SLF4Jの1.8は安定版が出ないので2.0を使おうという話

Javaライブラリを配布する際のログ周りにおける配慮と実践 2020

slf4j-apiに1.7, 1.8, 2.0の3バージョンが生まれた

複数バージョンの存在を踏まえ、ライブラリ配布者は何を気にするべきか

どのバージョンを使うべきか

マイナーケース：ライブラリとしても実行可能ファイルとしても配布する場合

研究などの学術的目的で問い合わせや協力依頼をいただく際の私の対応方針

連絡先

サーベイに対する協力

その他の協力

GitHub Actions 最近のやらかし一覧

テストの失敗原因レポートをartifactとしてアップロードしそこねる

forkからのPRではGITHUB_TOKENを除くsecretsを参照できない

if では $VAR で環境変数を参照できない

あるべき論

APIサーバ＆BFF共通

BFFサーバ の実装

サーバ間連携

備考

RxJava v2, reactive-streams そして Java9 Flow API について

DBにクエリを2つ投げて合成する処理

関連記事

slf4j-apiに1.7, 1.8, 2.0の3バージョンが生まれた

複数バージョンの存在を踏まえ、ライブラリ配布者は何を気にするべきか

どのバージョンを使うべきか

マイナーケース：ライブラリとしても実行可能ファイルとしても配布する場合

連絡先

サーベイに対する協力

その他の協力

テストの失敗原因レポートをartifactとしてアップロードしそこねる

forkからのPRではGITHUB_TOKENを除くsecretsを参照できない

if では $VAR で環境変数を参照できない

BFFサーバの実装