API リファレンスの全体像
API リファレンスは「クラスやメソッドが何をし、どう使うべきか」を正確に伝える公式資料です。Java では標準ライブラリ（java.base など）の各クラスに対して、概要、コンストラクタ、メソッド一覧、パラメータ、戻り値、例外、サンプル、バージョン履歴などが体系的に記載されています。大切なのは「署名で機能をつかむ」「契約（前提・戻り値・例外）を理解する」「バージョンと互換性を意識する」の3点です。
まず見るべき項目と読み方の順序
クラス概要と責務
クラスの冒頭には「何をするクラスか」「スレッドセーフか」「不変か」「代表的な使用例」が載ります。ここで責務をつかみ、別クラスとの関係（実装インターフェース、継承）も確認します。例えば String は「不変の文字列」、StringBuilder は「可変の文字列バッファ」と明言されており、選択の指針になります。
メソッド署名（シグネチャ）を読む
署名は「可視性・static/instance・戻り値・メソッド名・引数型と順序・例外宣言」を一行に凝縮しています。
public static String format(String format, Object... args)
- public: どこからでも呼べる
- static: インスタンス不要で呼べる
- String: 戻り値の型
- format: メソッド名（動作の要約）
- Object…: 可変長引数（0個以上の引数）
- throws ～: 例外が宣言されていれば、呼び出し側の対応が必要
署名を見れば「何が入って何が返るか」「呼び出しの形」が即座に分かります。
パラメータ・戻り値・例外の契約
説明文には、各パラメータの意味、許容範囲（null 可否・上限下限・フォーマット）、戻り値の意味（空・null の可能性）、投げる例外の条件が明記されます。メソッドの正しい使い方は、ここに書かれた契約を守ることに尽きます。
重要ポイントの深掘り：契約の読み解き方
null 可否と境界条件の明記を探す
- 「null を許可しない」「空文字は特別扱い」などの文言は最重要です。許可されないなら呼び出し前にガードします。
- 境界は具体的に読み取る（「0 以上」「長さは size 未満」「end は排他」など）。IndexOutOfBoundsException や IllegalArgumentException の条件が指針になります。
public String substring(int beginIndex, int endIndex)
説明で「begin は包括、end は排他」「0 <= beginIndex <= endIndex <= length」という契約が示されます。これをそのままコードのガード節にします。
例外の意味を設計へ反映する
- チェック例外（throws IOException など）は「呼び出し側で回復可能性がある」前提。try-catch で処理するか、throws で上位へ委ねる設計にします。
- 実行時例外（IllegalArgumentException, NullPointerException など）は「契約違反」のシグナル。入口でバリデーションして未然に防ぐのが基本です。
戻り値の特殊値・Optional の扱い
- 戻り値に「null を返す」「空を返す」などの記述があれば、利用側の分岐に反映します。
- Optional を返す API は「有無」を型で表しており、orElse, ifPresent で安全に扱えます。
付随情報の読み方：バージョン、スレッドセーフ、性能
@since と非推奨（@deprecated）
- @since は導入バージョン。古い環境で使えるか判断できます。
- @deprecated は非推奨。代替 API の説明があるので、そちらへ移行します。非推奨は将来削除の可能性があるため、採用を避けるのが無難です。
スレッドセーフと不変性
- 「スレッドセーフ」や「不変」の記載があれば、並行処理での安全性が判断できます。不変（immutable）なら共有しても安全、可変なら外部への公開を慎重に。
- Collections.synchronizedList のような「ラッパーによる安全化」の説明も要チェックです。
計算量・性能上の注意
- リファレンスに「線形時間」「ハッシュベース」「要素数に比例」などの記述がある場合、アルゴリズム選択の指針になります。例えば ArrayList の get は O(1)、LinkedList の get は O(n) という違いが明記されます。
例題で身につける：実際の読み方とコードへの落とし込み
例 1: String.substring の契約をコード化
クラス説明で「不変の文字列」、メソッド説明で「begin 包括・end 排他」「境界条件」「例外発生条件」を確認します。そのままガード節に落とします。
public static String slice(String s, int begin, int end) {
if (s == null) throw new IllegalArgumentException("s must not be null");
if (begin < 0 || end > s.length() || begin > end)
throw new IllegalArgumentException("0<=begin<=end<=length must hold");
return s.substring(begin, end);
}
例 2: Files.newBufferedReader の例外宣言と後始末
署名で throws IOException を確認。try-with-resources の利用推奨が説明にあり、後始末は自動化できます。
import java.nio.file.*;
import java.io.*;
static String firstLine(Path p) throws IOException {
try (var br = Files.newBufferedReader(p)) {
return br.readLine(); // null の可能性は説明に従い分岐
}
}
「戻り値が null の可能性」は説明に従って対処します。
例 3: List のインデックス契約と例外条件
List#get の説明で「0 <= index < size」「範囲外は IndexOutOfBoundsException」と明記。利用側で前倒しチェックに反映します。
static <T> T safeGet(java.util.List<T> list, int index) {
if (index < 0 || index >= list.size())
throw new IllegalArgumentException("index out of range: " + index);
return list.get(index);
}
実戦的な読み方のコツ
1ページで分からなければ「関連クラス」「インターフェース」へ
API は連携で設計されています。List の振る舞いは Collection の契約が土台、実装差は ArrayList/LinkedList の個別説明で補完します。上位インターフェースの契約（null 可否、反復順序、同値性）を優先して理解します。
用語・キーワードをメモに落とす
「inclusive/exclusive」「immutable」「synchronized」「modification count」「fail-fast」などのキーワードは意味が固定されています。都度メモにして、コードのコメントや命名へ反映すると迷いません。
署名から使い方を「最短で再現」
説明を読み過ぎて迷うより、署名だけでまず最小コードを書き、コンパイル・実行して感触を掴むのが効果的です。動かしながら説明を再読すると、吸収率が上がります。
よくある落とし穴と回避策
例外を読まないまま使う
どんな例外が出るかを知らないと、想定外のクラッシュになります。throws と「投げる条件」を必ず読み、上位でまとめて扱うか、ここで回復するかを決めます。
境界の取り違え（inclusive/exclusive）
substring の end 排他、配列・リストの index は 0..size-1。契約文をそのままコード化し、テストで境界を含むケースを用意すると確実です。
バージョン差・非推奨を無視
環境によって使える API が違います。@since と @deprecated を確認し、代替 API が提示されていれば早めに移行します。
スレッドセーフでないものを共有
「スレッドセーフではない」記述を見落とすと、並行バグの温床に。可変オブジェクトを共有する設計を避け、不変（immutable）や同期ラッパーを選びます。
仕上げのアドバイス（重要部分のまとめ）
API リファレンスは「署名で使い方を掴み、説明で契約を確認し、付随情報で安全性と互換性を判断する」資料です。null 可否・境界条件・例外の条件をコードのガード節へ直訳し、try-with-resources で後始末を担保する。@since/@deprecated、スレッドセーフ、不変性、性能上の注意を設計へ織り込み、関連インターフェースの契約を優先して理解する——これが、迷わず正しく API を使うための「読み方の型」です。