Kengo's blog

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

TypeScriptでGitHub Actionを書くときのTips

GitHub TypeScript

actions-setup-docker-compose, sonar-update-center-actionやsauce-connect-actionなど5つくらいActionを実装したので、Tipsをここにまとめます。

公式テンプレートを使う

TypeScriptでGitHub Actionを書くためのテンプレートが公開されています。とりあえずこのテンプレートを使うのがおすすめです。

github.com

使っているのはnpm, jest, @vercel/ncc, eslint, prettier とオーソドックスなもの。jest が気に入らなければ置き換えても構わないでしょう。

公式ドキュメントとライブラリに目を通す

さらっとで良いので以下のページは読んでおくといいです。どういった情報がどこにあるのか、これをするために何を使えばいいのか、情報の場所を掴んでおきます。

特に以下は必要になる知識だと思われます：

Fixtureの作成と読込

単体テストでは api.github.com との通信を再現してコードの挙動を見ていくことになります。一応 docs.github.com に期待されるステータスコードやそのペイロードが書かれていますが、まだ内容が間違っていることがあったので実際にコードを回して確認することを薦めます。ドキュメントよりは @octokit/rest の型情報のほうが信用できます。

レスポンスを再現するためのFixtureは、JSON.stringify(response.data)をJSONファイルに保存して作成します。tsconfig.jsonに"resolveJsonModule": trueを設定すればJSONファイルをそのままオブジェクトとしてimportできるので便利です。

// quoted from https://git.io/JIchk
import releases from './fixtures/sonarqube-releases.json'

const token = process.env.GITHUB_TOKEN
if (!token) {
  throw new Error('No GITHUB_TOKEN env var found')
}

test('searchLatestMinorVersion()', async () => {
  const scope = nock('https://api.github.com')
    .get('/repos/SonarSource/sonarqube/releases')
    .reply(200, releases)
  expect(await searchLatestMinorVersion(token)).toBe('8.5.*')
})

こうしたテストの面倒を見てくれる@octokit/fixtures もあるようですが、私はまだnockしか使っていないので詳しいことは不明です。

Changelog Blogを購読する

Actions周りはまだ動きが活発で、最近も add-path コマンドなどが削除されたばかりです。 変更に追従するためにもChangelog Blogは購読をすると良いでしょう。

TBU: まだ自動化できていないこと

  • dependabot が依存を更新したら dist ディレクトリ以下のファイルも更新する
    • pull_request イベントでActionを発火させて、 npm run all した結果をcommit & pushするようにすればできるはず

2021年8月29日更新：下記、2つやり方をまとめました。

技術書「JavaのビルドとCIのキホン」を公開しました

Gradle java GitHub

zenn.dev がホットなのでフォロワーの皆様にアンケートを取った結果、「JavaのビルドとCIのキホン」が5票を獲得したので書きました。

書籍はこちらです。

zenn.dev

zenn.dev上では約26266文字と言われてるんですが、いや流石にそんなに書いてないはず。まえがきと付録を除いて6章構成です。 初心者向けを意図していますが、経験者でないとわからない論理的飛躍というか、結果ありきの書き方になっているところが残っているかもしれません。しばらくは継続的に更新します。

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

java J2EE ReactiveX vert.x

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. サーバ内ですべてのサービスからのレスポンスを束ね、1枚のHTMLページやJSONデータをつくり上げる
  2. サービスから逐次受け取ったデータをクライアントに横流しして、クライアント側で組み立てる（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に直接依存・利用したほうがコードもシンプルになるし利用できる機能も多く便利なはず。

参考：

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

java reactor

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

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を検索しても出てこないのでちょっと苦労しました。

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を選択することが良いのではないでしょうか。

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つの差が見えてきます：

  1. APIの差。slf4j-api 2.0.x には従来存在しなかったメソッドが増えている。これに依存したライブラリのユーザは、slf4j-api 2.0.xを利用しなければ実行時に NoSuchMethodError が出るかもしれない。
  2. 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には来ていませんし、タグも残っていません