![[アップデート] Smithy-Java クライアントフレームワークが GA になったので Quickstart で試してみた](https://images.ctfassets.net/ct0aopd36mqt/wp-thumbnail-6869bd88d85be63e2c18c4dbf7477717/fa54943ce9fed64a911d7640c8ba155f/aws-tools-and-sdks?w=3840&fm=webp)
[アップデート] Smithy-Java クライアントフレームワークが GA になったので Quickstart で試してみた
いわさです。
Smithy は AWS が開発したプロトコル非依存のインターフェース定義言語（IDL）です。
API のモデルを定義すると、そこから型安全なクライアントやサーバーのコードを複数言語で自動生成できます。
元々は AWS 内部で10年以上使われてきたモデリングシステムで、AWS SDK もこの仕組みで生成されています。
2019年にオープンソース化[1]され、ユーザーが自社サービスの API 定義にも使えるようになりました。
API 定義からのコード生成自体は色々な方法がありますが、Smithy はプロトコルに依存しない点と、AWS エコシステム（SigV4 認証や AWS プロトコル）との親和性が特徴とされています。
これまで TypeScript[2]や Python[3]向けのコード生成は提供されていましたが、Java 向けは公式にはサポートされていませんでした。
今回、Smithy-Java クライアントフレームワークがリリースされ、Smithy エコシステムの中で Java のクライアントやサーバーも自動生成できるようになった、というのがこのアップデートのポイントです。
なお、GitHub のコミットログを見た感じ、2025年2月頃から 0.0.x バージョンで開発が進められており、2026年4月に 1.0.0 として GA リリースされました。
今回こちらを確認してみたので紹介します。
Quickstart で試してみる
公式の Quickstart ガイドに沿って試してみます。
このガイドでは「コーヒーショップ」をテーマにしたサンプルサービスを使って、Smithy モデルからサーバーとクライアントを生成・実行する流れを体験できます。
プロジェクトの作成
JDK 17 以上と Smithy CLI が必要です。
Smithy CLI は Homebrew でインストールできます。
% brew tap smithy-lang/tap
% brew install smithy-cli
% smithy --version
1.68.0
smithy init コマンドでテンプレートからプロジェクトを作成します。
% smithy init -t smithy-java-quickstart
template repo cloned [1.642s]
Smithy project created in directory: smithy-java-quickstart
smithy/ にモデル定義、client/ にクライアント、server/ にサーバーのコードが配置される構成です。
Smithy モデルの確認
main.smithy でサービスの全体像が定義されています。
$version: "2"
namespace com.example
use aws.protocols#restJson1
@title("Coffee Shop Service")
@restJson1
service CoffeeShop {
version: "2024-08-23"
operations: [
GetMenu
]
resources: [
Order
]
}
メニュー取得やオーダーの作成・取得といった操作が定義されています。
このモデルからクライアントとサーバーのコードが自動生成されます。
ビルドと実行
Gradle でビルドします。
なお、smithy init で生成されたテンプレートの gradle.properties には smithyJavaVersion=0.0.3 が設定されていましたが、このバージョンではビルドが失敗しました。
% ./gradlew build
> Task :client:smithyBuild FAILED
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':client:smithyBuild'.
> Could not resolve all files for configuration ':client:smithyBuild'.
> Could not find software.amazon.smithy.java:codegen-plugin:0.0.3.
Searched in the following locations:
- https://repo.maven.apache.org/maven2/software/amazon/smithy/java/codegen-plugin/0.0.3/codegen-plugin-0.0.3.pom
Required by:
project ':client'
codegen-plugin:0.0.3 が Maven Central に見つからないというエラーです。
テンプレートが GA 版に追いついていないようです。
GA リリースの 1.1.0 に変更したところ、問題なくビルドできました。
smithyVersion=1.68.0
smithyGradleVersion=1.4.0
smithyJavaVersion=1.1.0
% ./gradlew build
> Task :smithy:smithyBuild
Running smithy build
SUCCESS: Validated 361 shapes
...
> Task :client:smithyBuild
Running smithy build
SUCCESS: Validated 392 shapes
...
> Task :server:smithyBuild
Running smithy build
SUCCESS: Validated 392 shapes
...
BUILD SUCCESSFUL in 13s
ビルドが成功すると、Smithy モデルから Java のクライアントコードとサーバースタブが自動生成されます。
例えばクライアント側では CoffeeShopClient というインターフェースが生成され、createOrder() や getOrder() といった型安全なメソッドが使えるようになっています。
@SmithyGenerated
public interface CoffeeShopClient {
default CreateOrderOutput createOrder(CreateOrderInput input) {
return createOrder(input, null);
}
default GetMenuOutput getMenu(GetMenuInput input) {
return getMenu(input, null);
}
default GetOrderOutput getOrder(GetOrderInput input) {
return getOrder(input, null);
}
static Builder builder() {
return new Builder();
}
}
サーバー側では、各操作に対応するインターフェースが生成されるので、それを実装してビジネスロジックを書く形です。
Quickstart テンプレートにはサンプル実装が含まれているので、そのまま動かせます。
サーバーの起動と動作確認
サーバーを起動します。
% ./gradlew :server:run
INFO: Starting server...
INFO: Started listening on http://localhost:8888
curl でメニューを取得してみます。
% curl -s http://localhost:8888/menu | python3 -m json.tool
{
"items": [
{"type": "DRIP", "description": "A clean-bodied, rounder, and more simplistic flavour profile.\n..."},
{"type": "POUR_OVER", "description": "Similar to drip coffee, but with a process that brings out more subtle nuances in flavor.\n..."},
{"type": "LATTE", "description": "A creamier, milk-based drink made with espresso.\n..."},
{"type": "ESPRESSO", "description": "A highly concentrated form of coffee, brewed under high pressure.\n..."}
]
}
REST-JSON プロトコルでレスポンスが返ってきていることが確認できます。
クライアントアプリケーションの実行
次に、生成された SDK を使ったクライアントアプリケーションを実行します。
コーヒーのオーダーを作成し、ステータスを取得するサンプルです。
% ./gradlew :client:run
INFO: Created request with id = 7530b8af-0f2a-4a52-a415-a3bd7ec1ef6b
INFO: Got order with id = 7530b8af-0f2a-4a52-a415-a3bd7ec1ef6b
INFO: Waiting for order to complete....
INFO: Completed Order :GetOrderOutput[id=7530b8af-0f2a-4a52-a415-a3bd7ec1ef6b, coffeeType=COLD_BREW, status=COMPLETED]
COLD_BREW のオーダーを作成し、5秒待ってから再取得すると status=COMPLETED になっていることが確認できます。
Smithy モデルから生成されたクライアントとサーバーが正しく連携して動作していることが確認できました。
さいごに
本日は Smithy-Java クライアントフレームワークが GA になったので、Quickstart テンプレートを使ってサーバーとクライアントの生成・実行を確認してみました。
Smithy モデルを書くだけでクライアントとサーバーが自動生成される仕組みはなかなか良さそうです。
テンプレートのバージョンが GA 版と合っていない点は少し気になりましたが、変更するだけで問題なく動作しました。
今回は Quickstart の範囲でしたが、Dynamic Client やプロトコルの実行時切り替えなども含まれているようなので、別途確認してみたいと思います。
