API 設計観点とは何か
API 設計観点とは、
「他の人（他のクラス・他の開発者・他のシステム）が使いやすく、安全で、誤解されないインターフェースをどう作るか」
という視点のことです。
Java の API 設計は、単にメソッドを作るだけではありません。
名前、引数、戻り値、例外、状態管理、拡張性、将来の変更に耐えられるかなど、
多くの要素を考慮する必要があります。
初心者ほど「動けばいい」で API を作りがちですが、
実務では “使われる側の視点” が圧倒的に重要になります。
良い API の第一条件：直感的であること
名前を見ただけで「何をするか」が分かる
例えば、次の API を比べてみます。
// 悪い例
void doIt(User u);
// 良い例
void registerUser(User user);
後者は、名前を見ただけで「ユーザー登録するんだな」と分かります。
API 設計では、名前が最初のドキュメント です。
引数の順番・型も直感的に
// 悪い例
void send(String message, int retryCount, boolean urgent);
// 良い例
void sendMessage(String message, boolean urgent, int retryCount);
「緊急かどうか」はメッセージに近い概念なので前に置く、
などの“意味のまとまり”を意識すると API が理解しやすくなります。
null をどう扱うか：API 設計の最重要ポイント
null を返さない（Optional を返す）
// 悪い例
User find(String id); // 見つからなければ null？
// 良い例
Optional<User> find(String id);
null を返す API は、呼び出し側に null チェックを強制し、
チェック漏れによるバグを生みやすくなります。
Optional を返すことで、
「値がない可能性がある」ことを型で表現できます。
引数に null を許容するかどうか
API 設計では、
「null を渡していいのか？」を明確にする ことが重要です。
例えば、
「null は絶対に許容しない」なら、メソッドの最初でチェックします。
public void update(User user) {
Objects.requireNonNull(user, "user must not be null");
}
これにより、呼び出し側の誤りを早期に発見できます。
例外設計：API の“失敗の仕方”を決める
チェック例外 vs 非チェック例外
Java では例外の扱いが API 設計に直結します。
// チェック例外
void save(User user) throws IOException;
// 非チェック例外
void save(User user);
チェック例外は「呼び出し側に対処を強制する」ため、
本当に対処が必要な場合だけ使うべきです。
実務では、
ビジネスロジックの例外は非チェック例外
外部リソース（ファイル・ネットワーク）はチェック例外
という方針が多いです。
例外メッセージは API の一部
throw new IllegalArgumentException("id must not be blank");
このメッセージは、
呼び出し側が原因を理解するための重要な情報です。
拡張性：将来の変更に耐えられる API を作る
メソッドを安易に増やさない
API を増やすほど、将来の変更が難しくなります。
例えば、次のような API は危険です。
void createUser(String name);
void createUser(String name, int age);
void createUser(String name, int age, String email);
こうなると、
「次に住所を追加したい」となったときに破綻します。
パラメータオブジェクトを使う
record CreateUserRequest(String name, int age, String email) {}
void createUser(CreateUserRequest request);
こうすると、
将来フィールドを追加しても API は壊れません。
副作用を最小限にする：予測可能な API を作る
メソッドは「1 つの責務」に絞る
// 悪い例：保存してログ出してメール送る
void saveUser(User user);
// 良い例：責務を分ける
void save(User user);
void notifyUserCreated(User user);
API が複数のことをすると、
呼び出し側が予測できなくなり、バグの原因になります。
イミュータブルを基本にする
API が返すオブジェクトがミュータブルだと、
呼び出し側が勝手に書き換えてしまう可能性があります。
// 悪い例
User getUser(); // 返した User が書き換えられる
// 良い例
UserDto getUser(); // DTO はイミュータブル
イミュータブルな API は安全で予測可能です。
API の“使われ方”を想像する
呼び出し側のコードが美しくなるか？
API 設計の最重要ポイントは、
「呼び出し側のコードがどう見えるか」 です。
例えば、
// 悪い API
service.execute(user, true, 3);
// 良い API
service.register(user, RetryPolicy.withMaxRetries(3).urgent());
後者の方が圧倒的に読みやすく、意図が明確です。
API は「呼び出し側のコードを美しくするために存在する」と考えると、
設計の質が一気に上がります。
初心者が API 設計で意識すべきポイント
「動く」より「使いやすい」を優先する
初心者は「動けば OK」と思いがちですが、
API は “他の人が使うもの” です。
自分が呼び出し側だったらどう感じるかを常に考えてください。
- null を返さない
- 例外メッセージを丁寧に
- 名前は最重要
- 副作用を減らす
- 将来の変更に強い形にする
この 5 つを意識するだけで、
API の質は劇的に上がります。
まとめ：API 設計観点を自分の言葉で説明するなら
あなたの言葉で整理すると、こうなります。
「API 設計観点とは、
名前、引数、戻り値、例外、null の扱い、拡張性、副作用などを考慮し、
“呼び出し側が直感的に使えて、安全で、将来の変更にも強い API” を作るための視点。
API は“動けばいい”ではなく、
“使う人が迷わない・バグを生まない・将来も壊れない”ことが最重要。」