From 6395c38da77f34111aa6cc6d9f6a16a1c53f0c1c Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Thu, 26 Mar 2020 16:47:49 +0900 Subject: [PATCH 1/2] Add Japanese version to PR #442 --- docs/_advanced/ja_error_handling.md | 4 +- docs/_advanced/ja_middleware_global.md | 2 + docs/_advanced/ja_middleware_listener.md | 2 + docs/_basic/ja_listening_actions.md | 1 + docs/_tutorials/ja_hubot_migration.md | 2 +- docs/_tutorials/ja_migration_v2.md | 120 +++++++++++++++++++++++ 6 files changed, 128 insertions(+), 3 deletions(-) create mode 100644 docs/_tutorials/ja_migration_v2.md diff --git a/docs/_advanced/ja_error_handling.md b/docs/_advanced/ja_error_handling.md index c602e0912..8c05a5548 100644 --- a/docs/_advanced/ja_error_handling.md +++ b/docs/_advanced/ja_error_handling.md @@ -6,9 +6,9 @@ order: 1 ---
-リスナーの中でエラーが発生した場合は、リスナー内で直接ハンドリングすることが望ましいでしょう。しかし、リスナーがすでに return した後でエラーが発生する場合もあります。 (`say()` または `respond()` を呼び出した場合や、必要なときに `ack()` を呼び出さなかった場合など)。このようなエラーはデフォルトではコンソールにログ出力されます。ユーザー自身がこうしたエラーを処理するには、`error(fn)` メソッドを使用してグローバルエラーハンドラーをアプリにアタッチします。 +*注: Bolt 2.x からエラーハンドリングが改善されました！詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* -エラーをよりスマートに管理するには、`client` キーの配下で (`say()` や `respond()` の代わりに) アプリにアタッチされている [`chat.postMessage`](https://api.slack.com/methods/chat.postMessage) メソッドを使用することをお勧めします。これにより `Promise` が返されるため、そこでエラーをキャッチして処理することができます。 +リスナーでエラーが発生した場合は `try`/`catch` を使って直接ハンドリングすることをおすすめします。しかし、それでもなおすり抜けてしまうエラーのパターンもあるでしょう。デフォルトでは、このようなエラーはコンソールにログ出力されます。ご自身でこれらをハンドリングするには、`error(fn)` メソッドによって、グローバルエラーハンドラーを定義してください。
```javascript diff --git a/docs/_advanced/ja_middleware_global.md b/docs/_advanced/ja_middleware_global.md index 7210c7d61..7dc595f44 100644 --- a/docs/_advanced/ja_middleware_global.md +++ b/docs/_advanced/ja_middleware_global.md @@ -11,6 +11,8 @@ order: 4 グローバルミドルウェアとリスナーミドルウェアは、いずれも、`await next()` を呼び出して実行チェーンの制御を次のミドルウェアに渡すか、`throw` を呼び出して以前に実行したミドルウェアチェーンにエラーを渡す必要があります。 たとえば、アプリが、対応する内部認証サービス (SSO プロバイダ、LDAP など) で識別されたユーザーにのみ応答する必要があるとします。この場合、グローバルミドルウェアを使用して認証サービス内のユーザーレコードを検索し、ユーザーが見つからない場合はエラーとなるように定義するのがよいでしょう。 + +*注: Bolt 2.x からグローバルミドルウェアが `async` 関数をサポートしました！詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* ```javascript diff --git a/docs/_advanced/ja_middleware_listener.md b/docs/_advanced/ja_middleware_listener.md index 5d902927c..19cd13f2c 100644 --- a/docs/_advanced/ja_middleware_listener.md +++ b/docs/_advanced/ja_middleware_listener.md @@ -13,6 +13,8 @@ order: 5 ただしもちろん、よりカスタマイズされた機能を追加するために、独自のミドルウェアを作成することもできます。独自のミドルウェアを記述する際には、関数で `await next()` を呼び出して制御を次のミドルウェアに渡すか、`throw` を呼び出して以前に実行されたミドルウェアチェーンにエラーを渡す必要があります。 たとえば、リスナーが人間からのメッセージのみを扱うのであれば、ボットメッセージを除外するリスナーミドルウェアを作成できます。 + +*注: Bolt 2.x からミドルウェアが `async` 関数をサポートしました！詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* ```javascript diff --git a/docs/_basic/ja_listening_actions.md b/docs/_basic/ja_listening_actions.md index 796c7455a..44de67bd1 100644 --- a/docs/_basic/ja_listening_actions.md +++ b/docs/_basic/ja_listening_actions.md @@ -12,6 +12,7 @@ order: 5 すべての `action()` の例で `ack()` が使用されていることに注目してください。Slack からイベントを受信したことを確認するために、アクションリスナー内で `ack()` 関数を呼び出す必要があります。これについては、「[イベントの確認](#acknowledge)」 セクションで説明しています。 +*注: Bolt 2.x からメッセージショートカット（以前はメッセージアクションと呼ばれていました）は `action()` ではなく `shortcut()` メソッドを使用するようになりました。詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* ```javascript diff --git a/docs/_tutorials/ja_hubot_migration.md b/docs/_tutorials/ja_hubot_migration.md index b6b5c61e9..0a5da6667 100644 --- a/docs/_tutorials/ja_hubot_migration.md +++ b/docs/_tutorials/ja_hubot_migration.md @@ -1,6 +1,6 @@ --- title: Hubot のアプリを Bolt に移行する方法 -order: 1 +order: 2 slug: hubot-migration lang: ja-jp layout: tutorial diff --git a/docs/_tutorials/ja_migration_v2.md b/docs/_tutorials/ja_migration_v2.md new file mode 100644 index 000000000..5fca4dd56 --- /dev/null +++ b/docs/_tutorials/ja_migration_v2.md @@ -0,0 +1,120 @@ +--- +title: 2.x マイグレーションガイド +order: 1 +slug: migration-v2 +lang: ja-jp +layout: tutorial +permalink: /ja-jp/tutorial/migration-v2 +--- +# 2.x マイグレーションガイド + +
+このガイドは Bolt 1.x を利用しているアプリを 2.x にアップグレードするための手順について説明します。 +
+ +--- + +## リスナー関数を `async` 関数に変更 + +Bolt アプリ内のリスナー関数は、全て `async` 関数に変更する必要があります。そして、そのリスナー関数内の `say()`、`respond()`、`ack()` メソッドの呼び出しも全て `await` を呼び出しの前につける必要があります。 + +これまで: + +```javascript +app.action('some-action-id', ({action, ack, say}) => { + ack(); + say('hello world'); +}) +``` + +これから: + +```javascript +app.action('some-action-id', async ({action, ack, say}) => { + await ack(); + await say('hello world'); +}) +``` + + +## エラーハンドリング + +Bolt for JavaScript 2.x では、より多くのユースケースで、必要に応じてエラーをキャッチし、グローバルエラーハンドラーにそれを送るかを制御できるよう改善されました。これまでと同様、グローバルエラーハンドラーに全て任せるよりは、可能な限り、リスナー関数の内部でエラーに対処することをおすすめします。 + +### リスナー関数内で `try`/`catch` 節を用いたエラーハンドリング + +```javascript +app.action('some-action-id', async ({action, ack, say, logger}) => { + try { + await ack(); + await say('hello world'); + } catch (error) { + // ここでエラーに対処 + logger.error(error); + } +}) +``` + +### グローバルエラーハンドラーによるエラーハンドリング + +```javascript +app.error((error) => { + // エラーの詳細をチェックして、メッセージ送信のリトライやアプリの停止などの対処を行う + console.error(error); +}); +``` + +その他のエラーに関する変更: + +- リスナー関数が `ack()` メソッドを 3 秒間のうちに呼び出さなかった場合、これまでのように例外を投げるのではなくログを出力するようになりました +- もしミドルウェア実行中に複数のエラーが発生した場合、Bolt for JavaScript は `slack_bolt_multiple_listener_error` という `code` と全てのエラーで構成される配列を含む `original` というパラメーターをラップしたエラーを返します + +## メッセージショートカット + +[メッセージショートカット](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts) (以前はメッセージアクションと呼ばれていました)は、これまで `action()` メソッドでハンドリングしていましたが `shortcut()` メソッドを使うようになりました。 + +これまで: + +```javascript +app.action('message-action-callback', ({action, ack, context}) => { + ack(); + // ここで処理を行う +}) +``` + +これから: + +```javascript +app.shortcut('message-action-callback', async ({shortcut, ack, context}) => { + await ack(); + // Do stuff +}) +``` + +## ミドルウェアに関する変更 + +もしカスタムのミドルウェアを書いている場合は、その関数を `async` に変更し、さらに `next()` の呼び出しを `await next()` に変更してください。もし後続の処理がある場合は、関数右を `next()` に渡す代わりに、その後続の処理を `await next()` の後に実行してください。 + +これまで: + +```javascript +function noBotMessages({message, next }) { + function doAfter() { + // 後続の処理をここでやる + } +if (!message.subtype || message.subtype !== 'bot_message') { + next(doAfter); + } +} +``` + +これから: + +```javascript +async function noBotMessages({message, next }) { + if (!message.subtype || message.subtype !== 'bot_message') { + await next(); + // 後続の処理をここでやる + } +} +``` \ No newline at end of file From 2e8d09d3fe7145380024b5370c13f43d9fce1d97 Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Thu, 26 Mar 2020 18:48:11 +0900 Subject: [PATCH 2/2] Apply the changes corresponding to the suggestions https://github.com/slackapi/bolt/pull/442 --- docs/_advanced/ja_error_handling.md | 4 ++-- docs/_advanced/ja_middleware_global.md | 2 +- docs/_advanced/ja_middleware_listener.md | 2 +- docs/_basic/ja_listening_actions.md | 2 +- docs/_tutorials/ja_migration_v2.md | 6 +++--- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/_advanced/ja_error_handling.md b/docs/_advanced/ja_error_handling.md index 8c05a5548..d44afe157 100644 --- a/docs/_advanced/ja_error_handling.md +++ b/docs/_advanced/ja_error_handling.md @@ -6,9 +6,9 @@ order: 1 ---
-*注: Bolt 2.x からエラーハンドリングが改善されました！詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* +*注: Bolt 2.x からエラーハンドリングが改善されました！この変更については [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* -リスナーでエラーが発生した場合は `try`/`catch` を使って直接ハンドリングすることをおすすめします。しかし、それでもなおすり抜けてしまうエラーのパターンもあるでしょう。デフォルトでは、このようなエラーはコンソールにログ出力されます。ご自身でこれらをハンドリングするには、`error(fn)` メソッドによって、グローバルエラーハンドラーを定義してください。 +リスナーでエラーが発生した場合は `try`/`catch` を使って直接ハンドリングすることをおすすめします。しかし、それでもなおすり抜けてしまうエラーのパターンもあるでしょう。デフォルトでは、このようなエラーはコンソールにログ出力されます。ご自身でこれらをハンドリングするには、`app.error(fn)` メソッドによって、グローバルエラーハンドラーを定義してください。
```javascript diff --git a/docs/_advanced/ja_middleware_global.md b/docs/_advanced/ja_middleware_global.md index 7dc595f44..cb1abda39 100644 --- a/docs/_advanced/ja_middleware_global.md +++ b/docs/_advanced/ja_middleware_global.md @@ -12,7 +12,7 @@ order: 4 たとえば、アプリが、対応する内部認証サービス (SSO プロバイダ、LDAP など) で識別されたユーザーにのみ応答する必要があるとします。この場合、グローバルミドルウェアを使用して認証サービス内のユーザーレコードを検索し、ユーザーが見つからない場合はエラーとなるように定義するのがよいでしょう。 -*注: Bolt 2.x からグローバルミドルウェアが `async` 関数をサポートしました！詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* +*注: Bolt 2.x からグローバルミドルウェアが `async` 関数をサポートしました！この変更については [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* ```javascript diff --git a/docs/_advanced/ja_middleware_listener.md b/docs/_advanced/ja_middleware_listener.md index 19cd13f2c..d9e016bbd 100644 --- a/docs/_advanced/ja_middleware_listener.md +++ b/docs/_advanced/ja_middleware_listener.md @@ -14,7 +14,7 @@ order: 5 たとえば、リスナーが人間からのメッセージのみを扱うのであれば、ボットメッセージを除外するリスナーミドルウェアを作成できます。 -*注: Bolt 2.x からミドルウェアが `async` 関数をサポートしました！詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* +*注: Bolt 2.x からミドルウェアが `async` 関数をサポートしました！この変更については [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* ```javascript diff --git a/docs/_basic/ja_listening_actions.md b/docs/_basic/ja_listening_actions.md index 44de67bd1..e272615d8 100644 --- a/docs/_basic/ja_listening_actions.md +++ b/docs/_basic/ja_listening_actions.md @@ -12,7 +12,7 @@ order: 5 すべての `action()` の例で `ack()` が使用されていることに注目してください。Slack からイベントを受信したことを確認するために、アクションリスナー内で `ack()` 関数を呼び出す必要があります。これについては、「[イベントの確認](#acknowledge)」 セクションで説明しています。 -*注: Bolt 2.x からメッセージショートカット（以前はメッセージアクションと呼ばれていました）は `action()` ではなく `shortcut()` メソッドを使用するようになりました。詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* +*注: Bolt 2.x からメッセージショートカット（以前はメッセージアクションと呼ばれていました）は `action()` ではなく `shortcut()` メソッドを使用するようになりました。この変更については [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。* ```javascript diff --git a/docs/_tutorials/ja_migration_v2.md b/docs/_tutorials/ja_migration_v2.md index 5fca4dd56..1fa8a3a4b 100644 --- a/docs/_tutorials/ja_migration_v2.md +++ b/docs/_tutorials/ja_migration_v2.md @@ -9,7 +9,7 @@ permalink: /ja-jp/tutorial/migration-v2 # 2.x マイグレーションガイド
-このガイドは Bolt 1.x を利用しているアプリを 2.x にアップグレードするための手順について説明します。 +このガイドは Bolt 1.x を利用しているアプリを 2.x にアップグレードするための手順について説明します。いくつかの変更が必要とはなりますが、ほとんどのアプリの場合で、おそらく対応に必要な時間は 5 〜 15 分程度です。
--- @@ -67,7 +67,7 @@ app.error((error) => { その他のエラーに関する変更: - リスナー関数が `ack()` メソッドを 3 秒間のうちに呼び出さなかった場合、これまでのように例外を投げるのではなくログを出力するようになりました -- もしミドルウェア実行中に複数のエラーが発生した場合、Bolt for JavaScript は `slack_bolt_multiple_listener_error` という `code` と全てのエラーで構成される配列を含む `original` というパラメーターをラップしたエラーを返します +- もし一つのイベントに対して複数のリスナー関数を実行中に複数のエラーが発生した場合、Bolt for JavaScript は `ErrorCode.MultipleListenerError` の値での `code` と、発生した個々のエラーの配列を含む `originals` というパラメーターをラップしたエラーを返します ## メッセージショートカット @@ -76,7 +76,7 @@ app.error((error) => { これまで: ```javascript -app.action('message-action-callback', ({action, ack, context}) => { +app.action({ callback_id: 'message-action-callback' }, ({action, ack, context}) => { ack(); // ここで処理を行う })