Springのドキュメントの探し方
私のね。
三行で
- Single page HTML でページ内検索する。
- Googleでは
site:https://docs.spring.io/spring-boot/docs/current/を検索条件に含める。 - GitHubの
spring-projectsでin this organizationで検索する。
蛇足
該当ツイート、発端はbouzuyaさんのクイズ です。
Springのドキュメントは充実していて、欲しい情報はだいたいどこかに書かれています。機能についても使い方についてもどうすればいいのかなども書かれています。なんだけど、できることがたくさんあるうえに一つのことをいろんなやり方でできるため、できることが限定されたものと比べると初見の人が目的のドキュメントにたどり着くのは難しいと思います。
情報はないわけではなく、たいていのものは https://spring.io のどこか、もしくは https://github.com/spring-projects/ のどこかにあります。どこかに。
高い確率で書かれてはいるんだけど、見つからないものはないものと同じ。見つけられないのを「探し方が悪い」とかいうのは簡単ですが、ことSpringに関してはそれで済ませていいとはちょっと思えないのでこんなブログ書いてます。
正直なところ 見つけられなくても仕方ない と思っています。
これは能力的な問題というより、構造的な問題かなと。先に挙げたように、多くのドキュメントは初見の人に向けて書かれていないと思います。Getting Startedとかはそちら向けですが、「ドキュメントを探す」と言う文脈のことはGetting Startedには書かれていないでしょう。なので見つけられなくても仕方ないと思う（大事なので重ねる）。でもきっとどこかにはあります。まぁ「コードに書いてある」も「どこかにある」に含めちゃってたりするからずるい表現ではあるけど、推奨の使い方とかはちゃんとドキュメントに書かれております。たぶん。見つけられないのは構造的な問題、見つけられない人は悪く無いし、かと言ってSpringが悪いわけでもない。そこを埋められていないだけです。
書籍でも初心者向けとエキスパート向けの二極化して間がないのはありがちなんですが、Spring Frameworkのような歴史が長いにもかかわらず活発に更新されるプロダクトではより顕著なように思えます。挙げた書籍も既にバージョンの問題もあり、現在参照するのは微妙になっています。仕方ない話ではある。残念ながらこのブログも「この間を埋めるもの」ではありません。
一冊手元にあると安心感がある厚さですが、2016年出版でSpringBoot 1.3.5.RELEASE、SpringFramework 4.2.6.RELEASE です。王道な使い方が紹介されている書籍でもあり、書いてあることのほとんどは現在も通用しますが、現在のSpringFrameworkは 5.3.8（.RELEASE は 5.3.0 から外れています。）であり、そろそろ 6 の声も聞こえてきているご時世。差分のキャッチアップを行う必要があります。そのためにもドキュメントを見つけて読めるようになるのがなんだかんだで早いです。
「見つけられないのは仕方ない」と言われたところで、仕事はそれでは済ませられません。打率はあげて行きたいところですよね。
と言うことで探し方
……とか題してますが、裏技的なものではなく、順当というか、力技に近いです。「これで一発で見つけられるようになる！」みたいなものではありません。悪しからず。
spring.ioのトップページから何かしら動線はつながってるとは思うんですが、検索エンジンなしに膨大なドキュメントから見つけられる気はしません。「検索エンジンを有効活用しましょう！」みたいな話ではあるんですが、以下のような条件がつけられます。
- 大体のことは公式ドキュメントに書いてある
- 歴史が長く、バージョンが入り混じっている
- 事例が多く、玉石混淆な情報に溢れている
情報が多すぎるがゆえにキーワードだけでGoogle検索しても、膨大な全く関係ない情報に当たってしまいます。 出てきた情報の取捨選択をやってもいいんですが、正直きりがなく、役に立たない情報の海で途方に暮れてしまうかもしれません。 仮に「何か動きそうなもの」を見つけても、その情報の正しさは怪しいところです。
なので私は検索する際は最初から検索対象を限定しています。こんな感じ。
- Single page HTML でページ内検索する。
- Googleでは
site:https://docs.spring.io/spring-boot/docs/current/を検索条件に含める。 - GitHubの
spring-projectsでin this organizationで検索する。
ほぼほぼ spring-boot 経由で使っている＆だいたい最新バージョンを使っているのでこんな感じです。
SpringBootでなくSpringSecurityだとか特定のプロジェクトで探す時は spring-boot を、特定バージョンのときは current を変えて検索します。検索時にバージョンを入れるのがかなり大事です。
調べる対象がSpring Projectのどれか識別するハードルは高いかもしれませんが、それぞれのOverviewをざっくり眺めた上で、使ってるクラスのパッケージ名などから推測していく感じです。AWSのサービスと同じで、全部覚える必要なんて無いですし、全部同時に使うこともないので、よく使うものから識別していきましょう。とりあえずシンプルなWebアプリケーションを作ってるなら、SpringBootとSpringFramework（MVCとかもこの中）、Spring Data（ベースとしてJDBC）、Spring Securityあたりからかなと。
英語読む気力がなかったり、日本語しか読まない人にリンクを示す時は pleiades のお世話になりますが、「対象を英語で見つけてから該当するpleiadesさんのページを開く」みたいな順番でやることが多いです。 これは私のSpringに対する検索キーワードのクセが英語に寄ってて、日本語だとうまく検索できないから……。
StackOverflowとかはエラーメッセージとかで検索する時と、なかなか引っかからない時にザッピング的にみることはある、くらい。あくまでキーワードを拾う用。 使い方から入るときは TERASOLUNA を見てたこともあります。最近の更新内容とかテーマによっては特定の人のQiitaやセッション資料を見たりもしなくはないです。
検索以外のアプローチだと spring-boot-autoconfigure を眺めたりします。
「AutoConfigurationできる使い方＝Spring（Boot）の想定している使い方＝ベストプラクティスに近い」みたいな発想。
クラス名で XxxAutoConfiguration とかを直接開いてみるか、パッケージツリーから使いたいものを選んでクラスを適当に眺め、そのクラス名やJavadocに書いているキーワードでドキュメントを検索する、と言った感じです。
物によってはそのままコードだけ読んで「あーなるほどー」と言っちゃうこともしばしばあります。Springに限らない話ですが、コードを見慣れると推測が効く様になってくるものです。これは実務でも「このプロジェクトならこの辺に実装してそう」みたいなのがあるので、体感したことはあるんじゃないかなと。フレームワークやライブラリも一緒です。
あと番外で適当にツイートしたり、とか……。
まとめ
Springの情報は「きっとドキュメントのどこかに書いてある」を信じて探していいと思います。探し方は挙げたものでなくて構いません。
どうしても見つからないなら「チャレンジングな使い方をしていないか」「書いてある使い方にできないか」などを検討してみるのをお勧めします。どうしてもその使い方をしたいならコードを読んで確実にしておくのがいいかなと思います。もちろんテストも。Springのドキュメントにあまりないのは、Springが使ってる別ライブラリの突っ込んだ使い方。たとえばJacksonはよく使うし、Nimbusとかもちょいちょい触ったりしたりしなかったり。あまりないと言いつつJacksonなんかは結構書かれてたりするんですが。
非ドキュメントな使い方はバージョンアップで互換性が失われる可能性があります。こう言うところは互換性が失われてもリリースノートに書かれないかもしれない。ドキュメントに書かれてる使い方なら互換性が保たれる可能性も高いし、非互換になる時はアナウンスがあります。なので、ドキュメントを見つけておくのは大事かなと。
脱線になりますが、Springが現状このポジションを保ててる理由の大きなところに、非ドキュメントな挙動であってもアナウンスなしに互換性が失われたものはバグとして扱われ、マイナーバージョンアップでちゃんと戻される点が挙げられると思います。直近の2.5.xでもありました。すべてがそうなるわけではありませんが、自分が踏まなくても他の人が踏んで、気づいたら直ってたーみたいな話もよく聞きます。
とりとめもないですが、こんな感じ。
