エラー処理#

エラーが表に出る道は3本あります。通る場所が違います。

error の書き方#

error((context, cause, statusCode) -> {
	context.response().code(statusCode).send("エラー: " + statusCode);
});

引数は3つです。例外だけでなくステータスコードも渡ってきます。 cause から毎回コードを引き直さなくて済むようにするためです。

void handle (WebContext context, Throwable cause, int statusCode) throws Exception;

効く範囲#

before / after と同じで、書いたブロックに付きます（パスのノードではありません）。 実行は内側から外側へ。詳しくは ルーティング を見てください。

JimbleApp app = new JimbleApp() {
	{
		error((context, cause, statusCode) -> log.add("outer"));

		path("/admin", () -> {
			error((context, cause, statusCode) -> {
				log.add("inner");
				throw new IllegalStateException("error handler failed");
			});
			get("/x", context -> {
				throw new HttpException(400, "bad");
			});
		});
	}
};

/admin/x に来ると、内側 → 外側の順に呼ばれます。 内側が例外を投げても外側に進みます（下の「ハンドラ自身が失敗したら」）。

ステータスコードの決まり方#

JimbleApp#resolveStatusCode(Throwable) が決めます。既定はこれだけです。

JimbleApp app = new JimbleApp() {
	{
		error((context, cause, statusCode) -> {
			log.add("error:" + statusCode);
			context.response().code(statusCode).send();
		});
		get("/forbidden", context -> {
			throw new HttpException(403, "だめ");
		});
	}
};

自分の例外にコードを割り当てるなら上書きします。

JimbleApp app = new JimbleApp() {

	{
		error((context, cause, statusCode) -> log.add("error:" + statusCode));
		get("/x", context -> {
			throw new MyException();
		});
	}

	@Override
	protected int resolveStatusCode (Throwable cause) {
		if (cause instanceof MyException) {
			return 409;
		}
		return super.resolveStatusCode(cause);
	}

};

本文は誰が作るか#

順番はこうです。

1. context.response().code(statusCode) を先に入れる（ハンドラが上書きできる）
2. error(...) を内側から順に呼ぶ。送った時点で止まる
3. 誰も本文を用意していなければ、既定のエラー応答を入れる
4. response().send() を呼ぶ

4 が send(statusCode) ではなく send() なのが要点です。 ハンドラが json(...) などで組み立てた中身を、捨てずに送るためです。

error((context, cause, statusCode) -> {

	// API なら JSON、画面なら HTML
	if (context.request().acceptJson()) {
		context.response().json("error", cause.getMessage());
		return;
	}

	context.response().send("エラー: %d %s".formatted(statusCode, cause.getMessage()));

});

何も書かなかったとき#

error(...) を1つも書いていない、あるいは書いたけれど本文を作らなかったとき、 jimble が決まった形を返します。

Accept が JSON を名指ししていれば JSON です。

{"error": {"status": 404, "message": "Not Found"}}

そうでなければ、短いテキストです（Content-Type: text/plain; charset=UTF-8）。

404 Not Found

• message は RFC 9110 の短い語です（Not Found / Internal Server Error）。 ステータス行やクライアントのライブラリに出てくる語と同じにしてあります
• 原因は入りません。 例外のメッセージも SQL もスタックトレースも載せません。 原因はログに出ています（500 番台は Log.error）
• */* はテキストです。「何でもいい」であって「JSON がいい」ではありません
• error(...) で組み立てていれば、そちらが勝ちます。 送信まで済んでいなくてもです

acceptJson() は Accept が application/json か text/javascript を 名指ししているかを見ます。application/json;q=0.9 のようにパラメータが付いていても効きます。 q=0（要らない）と */*（何でもいい）は名指しに数えません。

405 と 404 は分かれます#

パスは合っていてメソッドだけ違うときは 405 で、Allow が付きます。

$ curl -i -X POST http://localhost:9000/hello
HTTP/1.1 405 Method Not Allowed
Allow: GET

404 は「そんなものは無い」、405 は「あるが、その呼び方ではない」です。 一緒にすると、post と書くべきところを get と書いただけの間違いが 「パスが違う」に見えてしまいます。

ハンドラ自身が失敗したら#

握って次（外側）へ進みます。 エラー処理の失敗で何も返せなくなるほうが困るからです。 失敗は エラーハンドラで例外が発生しました としてログに出ます。

ログの出しかた#

after と onComplete の中で例外が出た場合も、握ってログに出します（レスポンスは返ります）。

検証の失敗は error を通らない#

ValidationExecutor は例外を投げません。 自分をキャンセルして、後続の Executor を捨て、そのまま返します。

context.response().putForm(context.request().bodyAll());
context.response().json("validation", errors);
context.response().code(422);

返る形はこうです。入力値も一緒に返るので、画面を組み直せます。

{
  "validation": { "title": ["入力してください"] },
  "title": "",
  "body": "..."
}

アプリ全体で差し替えられるもの#

JimbleApp で上書きできるのは3つだけです。

ディスパッチャそのものは差し替えられません（final）。 道を1本にしておくためです。