Yoshimoto-Samonji on Rindrics Mumbles

API 契約駆動で開発できるようにした

Sun, 12 Jul 2026 00:00:00 +0900

Open API 形式の API 仕様を基礎として開発できるような体制を整えた。

背景と問題点

前回記事では、frasyr をモノリスの API サーバーとして動かすための第一歩として、ひとまず plumber でラップしてみた。当然 frasyr を API 経由で使えるようになったものの、一方で後に控える契約層やフロントの開発のことを考えると、依存の向きに致命的な課題があった。というのも、前回は plumber をひとまず触ってみるのが目的だったので、frasyr を API 化できること、また API ドキュメントを Swagger UI で閲覧できることを確認して一区切りとしていた。問題は API ドキュメントの確認のほうで、これをやりたいために前記事では plumber の getApiSpec() を利用しており、将来的には契約の実体としたい OpenAPI 形式の仕様ファイルの方がコードから生成されていた。本来あるべき姿としては、モノリスの API は契約に準拠している必要があるが（下図左）、API から仕様を生成したのでは、依存の向きが逆になってしまっている（下図右）。これでは「契約」という概念を持ち込んだ意味がない。

前回記事の時点では、契約のほうが API から生成されてしまっていた

将来的には上図左の “Contract layer” を契約から生成したいので、次のステップとして下記 2 点に取り組むこととした:

Open API 形式の API 仕様ファイルを契約の SSOT とする
前回作ったモノリスサービスがこの契約に違反しないような仕組みを確立する

やったこと

ざっくりこんな感じ:

API 仕様をバージョン管理
Contract test の導入
リクエスト・レスポンスの検証
API ドキュメントの配信

それぞれ簡単にメモしておく。

API 仕様をバージョン管理

Open API 形式の仕様ファイルを、フロント–バック間における契約の SSOT としたい。これまでは plumber から生成される openapi.json を .gitignore していたがこれをやめ、バージョン管理を始めた。

これから仕様を手で書いていくとなると JSON 形式だと少々厳しそうなので、ついでに YAML に変換した:

yq -p json -o yaml '.' schema/openapi.json > schema/openapi.yaml

Contract test の導入

frasyr の API サーバーを契約通りに実装できているかを確認するために Contract test を導入した。テスト用ツールには当初 Claude に薦められるがままに Dredd を使いかけていたが、repo の方を見てみたら public archive になっていたので Schemathesis を使うことにした。他の候補として一応 Prism も検討したが、一人で開発するので Prism の売りの一つであるモックサーバーはそんなに魅力的に映らなかった。

Contract test としてのコア機能はこんな感じ:

Examples: API 仕様の example に valid なリクエスト例を書いておくことで、正常系のリクエストが生成される
Fuzzing: API 仕様をもとに、正常系・異常系のリクエストを生成する

Examples はまぁいいとして、Fuzzin test がなかなかおもしろかった。 Schemathesis が生成した、仕様的に valid なリクエストに対して 4XX や 5XX が返った場合、テストが失敗してくれるので、エラーハンドリングが甘かったり、仕様記述が漏れていたりといったミスに気付ける。また逆に、仕様的に invalid なリクエストに対して 2XX 系が返った場合にも、エラーハンドリングや仕様記述のミスに気づけるというわけ。

あとは Reproducible Failures という機能が地味に便利で、期待と異なるレスポンスが返った時に、再現用の curl リクエストを表示してくれた:

=================================== FAILURES ===================================
_________________________________ POST /v0/vpa _________________________________
1. Test Case ID: FZf6yc

- Server error

[500] Internal Server Error:

    `{"error":"Internal validation error"}`

Reproduce with:

    curl -X POST -H 'Content-Type: application/json' -d '{"data": {"caa_url": "https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_caa.csv", "waa_url": "https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_waa.csv", "maa_url": "https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_maa.csv"}, "params": {"m": 0.5, "fc_year": [2015, 2016, 2017], "tf_year": [2015, 2016], "term_f": "max", "stat_tf": "mean", "pope": true, "tune": false, "p_init": 0.5}}' http://host.docker.internal:31502/v0/vpa
    
    st replay FZf6yc

これだけでも、サーバー側のログと照らし合わせることで問題箇所の特定が捗った。

ちなみに、contract test が参照すべき Open API 仕様はローカルファイルパスだけでなく URL 指定もできるので、provider–consumer 関係の複数チームでも運用できそう。本プロジェクトではひとまず monorepo でやるのでローカルパス指定でいく。

Dev 環境および CI におけるテスト設定のポイント

Dev 環境

開発中は検証サイクルを早くしたいので、image build を介さず、ホストの R ランタイムで直接起動した plumber server に対してテストするようにした:

# Makefile

run:
	VALIDATE_RESPONSE=true \
    LOG_LEVEL=$(LOG_LEVEL) \
    OPENAPI_SPEC_PATH=../../schema/openapi.yaml \
    PLUMBER_PORT=$(PLUMBER_DEV_PORT) \
    Rscript run.R

test-local:
	docker run --rm \
	  -v $$(pwd)/../../schema:/schema \
	  -v $$(pwd)/../../schemathesis.toml:/workspace/schemathesis.toml \
	  -v $$(pwd)/../..:/workspace \
	  -w /workspace \
	  ghcr.io/schemathesis/schemathesis:stable \
	  run /schema/openapi.yaml \
	  --url http://host.docker.internal:$(PLUMBER_DEV_PORT) \
 	  --coverage-format html --coverage-report-html-path ./schema-coverage.html

本プロジェクトは現時点ではクラウド環境を作っておらず、compose で立ち上げるコンテナを暫定的に本番環境とみなしている。このコンテナを使った動作確認も並行して行う機会があったので、dev 環境（ホストの R ランタイムで立ち上げた plumber サーバー）のポートは PLUMBER_DEV_PORT として別に割り当てた。

ちなみにコンテナ版の Schemathesis からホストのエンドポイントを叩くので、base URL には host.docker.internal の利用が必須。

CI

CI ではより本番環境に近い状態でテストしたいので、API サーバーはコンテナ版を使うようにした。ただしデリバリー済みのイメージを使ってしまうと PR 時などの CI として意味がないので、ワークフロー内でイメージをビルドしている。

CI で利用しているテストコマンドは下記:

# Makefile

test:
	docker run --rm \
	  --network $(DOCKER_NETWORK) \
	  -v $$(pwd)/../../schema:/schema \
 	  -v $$(pwd)/../../schemathesis.toml:/workspace/schemathesis.toml \
	  -v $$(pwd)/../..:/workspace \
	  -w /workspace/.schemathesis \
	  ghcr.io/schemathesis/schemathesis:stable \
	  run /schema/openapi.yaml \
	  --url http://monolith:$(CONTAINER_PORT) \
	  --coverage-format html --coverage-report-html-path ./schema-coverage.html

dev 環境とパスがちょっと違うのは、レポート書き出し時に permission error になったのでディレクトリを掘って逃げた形跡。あとは compose で立ち上げたサービスを叩くので docker network を使うようになっており、エンドポイントはサービス名 monolith で解決できる。

リクエスト・レスポンスの検証

リクエストの検証に関しては、Schemathesis Fuzzy test のおかげで突貫ながらもそこそこ進められた。 additionalProperties についてはやや迷ったのだが、今のところ BFF しか利用しない内部 API として作るので false にしておいた。

レスポンスの検証は dev 環境のみで有効になるようにした。これはちょうど最近読んだ『データ指向プログラミング¹』のプラクティスを参考にしている。

API ドキュメントの配信

せっかく API 仕様を管理していくので、API ドキュメントをどこかにホストしたい。 Scalar というのがよさそうだったのでこれを使うことにした。全然真面目に選定していないが、この手のツールは Open API document を読ませるだけなので、いざ問題が生じたとしても乗り換えコストは小さいはず。ホスト先はいつも使っている Netlify にした。

ドメインについては、下手に stock-assessment とかを当ててしまうと、方向転換を新規プロジェクトでやりたくなったときに不便なので、プロジェクト名からなるドメインにした: https://api-docs.yoshimoto-samonji.rindrics.com/#tag/vpa

ハマったところ

Sechemathesis が生成した QUERY method によるテスト失敗

Schemathesis が（今年の 6 月に出たばかりの）QUERY method を投げてくれるのには困った。

==================================== ERRORS ====================================
_________________________________ POST /v0/vpa _________________________________
Network Error

Connection failed

    Connection aborted. Remote end closed connection without response

Reproduce with:

    curl -X QUERY -H 'Content-Type: application/json' -d '{"data": {"caa_url": "https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_caa.csv", "waa_url": "https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_waa.csv", "maa_url": "https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_maa.csv"}, "params": {"m": 0.5, "fc_year": [2015, 2016, 2017], "tf_year": [2015, 2016], "term_f": "max", "stat_tf": "mean", "pope": true, "tune": false, "p_init": 0.5}}' http://host.docker.internal:31502/v0/vpa

確かに繋がらない:

curl -v -X QUERY -H 'Content-Type: application/json' -d '{"data": {"caa_url": "https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_caa.csv", "waa_url": "https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_waa.csv", "maa_url": "https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_maa.csv"}, "params": {"m": 0.5, "fc_year": [2015, 2016, 2017], "tf_year": [2015, 2016], "term_f": "max", "stat_tf": "mean", "pope": true, "tune": false, "p_init": 0.5}}' http://localhost:31502/v0/vpa
* Host localhost:31502 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:31502...
* connect to ::1 port 31502 from ::1 port 51462 failed: Connection refused
*   Trying 127.0.0.1:31502...
* Connected to localhost (127.0.0.1) port 31502
> QUERY /v0/vpa HTTP/1.1
> Host: localhost:31502
> User-Agent: curl/8.7.1
> Accept: */*
> Content-Type: application/json
> Content-Length: 435
> 
* upload completely sent off: 435 bytes
* Empty reply from server
* Closing connection
curl: (52) Empty reply from server

どうしようもなかったので、いったんは phases.coverage.unexpected-methods に空配列を指定して、仕様にないメソッドを使ったケース自体の生成を止めて対応した。 plumber 側にメソッドを追加する contrubution など、時間があったら検討するかも。

DNS 解決に時間のかかる URL

現時点の実装では、データは URL を指定してネットワーク越しに取得するようになっている²。この理由から、例えば年齢別漁獲尾数をロードするために使われるパラメータ caa_url は format: uri になっているのだが、この情報をもとに Schemathesis は fuzzy test phase ではランダムな URL を生成してリクエストを投げてくる。このランダムな URL の中に、まれに valid（ホストがいる）だが DNS 解決に時間がかかるものがあり（例えば A.aG）、そのせいで契約テストが失敗することがあった。

$ dig A.aG

; <<>> DiG 9.10.6 <<>> A.aG
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: SERVFAIL, id: 30374
;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;A.aG.				IN	A

;; Query time: 3003 msec
;; SERVER: 2404:1a8:7f01:a::3#53(2404:1a8:7f01:a::3)
;; WHEN: Mon Jul 13 03:16:29 JST 2026
;; MSG SIZE  rcvd: 33

テストを通すにはそのような URL の生成を抑制する方法も考えられたが、ドメインと無関係な知識（？）を持ち込むことになるのでやめた。代わりに、DNS 解決に内部タイムアウトを設け、タイムアウトした場合には Cannot resolve hostname として 404 を返すようにした。

check_dns <- function(hostname) {
  result <- system(
    sprintf("timeout 2 nslookup %s >/dev/null 2>&1", shQuote(hostname)),
    intern = FALSE
  )
  # timeout returns 124 if timed out, nslookup returns 1 if not found
  if (result %in% c(1, 124)) {
    stop(vpa_error(sprintf("Cannot resolve hostname: %s", hostname), 404))
  }
}

条件つき nullability のパラメータ

frasyr の vpa() の引数のうち、nullability が条件付きのものがある。 frasyr の利用法ドキュメントを見ると、例えば abund などのチューニングに使う引数は tune: true のときだけ必須となる。このあたりを API 仕様にきちんと書かないと、fuzzy test がパターンを網羅的に生成するので 5XX 地獄になる。意図しない組み合わせで呼ばれると、正しい使い方を促すエラーが frasyr からちゃんと出ているのだが、API としては仕様違反となって 500 が返ってしまう。直訳するならば JSON schema の dependentRequired を使ってできそうではあるが、例えば optional なオブジェクト型の withTune パラメータを定義したほうがシンプルかもしれない。ひとまず、今回は時間がなかったので tune が false しか受け付けないものとして逃げた。これはチューニング VPA をサポートする issue として個別に対応したほうがいいだろう。

学んだこと

一つのエンドポイントが多くのパラメータを受け取ると、contract test が大規模になりがち
Fuzzy test は強力。静的な生成物のよい使い方って感じ

Contract test にやや手こずったが、依存の向きを逆転させて無事に API 契約駆動で開発できるようになったので今回はここまで。

契約の生成（左）をやめて、API を契約に準拠させられるようになった（右）

参考情報

Yehonathan Sharvit (2023) “データ指向プログラミング” 株式会社クイープ (訳), 翔泳社 ↩︎
将来的にデータ配信サービスを導入する可能性があるため ↩︎

plumber を使ってみた

Tue, 16 Jun 2026 00:00:00 +0900

前回記事でリファクタリングの方針を立てたので、モノリスアプリケーションを作るところから始めてみる。

とりあえずリポジトリを作った。開発コードは yoshimoto-samonji（義元左文字）。

技術選定

計算エンジンを Web UI から利用するモノリスアプリがゴールなら Shiny App 化すればいいのだが、評価ステータス管理の実験をしていた当時のように、最終的には評価「事業」全体をアプリ化したい。丁寧なドメインモデリングが必要になるので、フロントは始めから型を扱える TypeScript で実装しておきたい。

これを踏まえて、モノリスのバックエンドは plumber を使って構築することにした。ドキュメントをざっと見てみたが、OpenAPI ドキュメントを生成してくれるようなので、フロント–バック境界は HTTP になる見込み。ということは、フロントエンドに Next.js を使っておけば、Route handler を BFF に使える。そうすると認証やセッション管理、画面向けのレスポンス整形を Next.js 側に寄せられるので、BFF を独立サービスとして立てる手間を抑えられそう。

ここまでを ADR にした。

plumber を使ってみる

hello, plumber

始めて触るので、plumber を使った最低限の実装を書いてみる。

とりあえずパッケージをセットアップし、 referenceを参考に実装してみた。

Plumber オブジェクトの $run() を実行する関数を作り、devtools::load_all() してから呼び出すと、指定したポートでサーバーが起動した:

> devtools::load_all(); start_server()
ℹ Loading legacy
Running plumber API at http://127.0.0.1:31501
Running swagger Docs at http://127.0.0.1:31501/__docs__/

クエリパラメータ msg に渡した文字列を利用したレスポンスを返す API ができた:

$ curl "http://127.0.0.1:31501/vpa/echo?msg=hello"
{"msg":["The message is: 'hello'"]}%

また、/__docs__ にアクセスすることで Swagger UI も利用できた:

生成された API ドキュメント。UI から動作確認できる

せっかく OpenAPI を利用できているので、将来的にはクライアントコードを生成するなどして契約駆動開発していきたい。 API スキーマをファイルに直接書き出すメソッドは無さそうだったが、getApiSpec() を使うと仕様をリストで取得できそうだったので、これを JSON にマッピングして書き出すことにした。スキーマはいったん ignore しておいて、クライアントコード生成などは Next.js のセットアップをしてから整えることにした。

ちなみに生成されたスキーマを見ると、設定した覚えのないメタデータが既に入っていた:

{
  "openapi": ["3.0.3"],
  "info": {
    "description": ["API Description"], <- このへんは設定した覚えがない
    "title": ["API Title"],
    "version": ["1.0.0"]
  },

ドキュメントを見ると設定方法がちゃんと書いてあって、アノテーションか pr_set_api_spec() を使って設定できるらしい。初めドキュメントの通りにアノテーションを足したつもりが、スキーマに反映されなかったが、このように Plumber オブジェクトを作っているファイル名を pr() の file 引数に指定することで反映されるようになった。ドキュメントでは引数なしで動いているように見えたが、断りがない限り Plumber を作るファイル名は plumber.R になっている想定らしい。

コンテナ image 化

R ではライブラリ系の使われ方をする開発しかしたことなかったので、思考停止でパッケージアプローチを取る癖がついてしまっていたけど、今回コンテナ用イメージを作る段になって、ランタイム系のイメージを作るにはパッケージアプローチは無駄が多すぎることに気づいた。 devtools のような開発系ツールや、その他パッケージ化に必要なメタデータもランタイムとしては完全に無駄なので、結局シンプルなスクリプト構成に移行した。

plumber がどうやって動作しているかを理解していなかったせいで、スクリプト形式に移行する過程でだいぶハマった。それはそれで学ぶこともあったので、時間があったら別記事にする。

VPA を実行する image を作る

こちらのドキュメントを参考にとりあえず vpa() を実行することにした。データの保存場所は恐らく分かれると思うので、それぞれのデータは URL で受け取るようにした。リクエストもレスポンスも、設計余地がけっこうありそうなので、まだ仮の実装にしてある。将来的に API 仕様を変えることが明らかなので、予めバージョンを切っておいた。

バージョンを切った。

まず一つ API を作ってみた感じでは、見積もりの 5 倍くらいは時間がかかった気がする。ただし、内訳としては plumber の使い方自体だったり、ビルドプロセスの調整などに手間取っていた。 API 自体の設計とかは全然していなかったので、今後は別のところに時間がかかるようになるはず。

学んだこと

改めて、使われ方に応じた構成をとることが大事。型がないとスキーマ定義などがめちゃめちゃ面倒。