From 899ba0a44273c36ea140dbe52018df016ad49610 Mon Sep 17 00:00:00 2001 From: Ryo Yamashita Date: Sat, 9 Nov 2024 23:54:43 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20"API=E3=83=87=E3=82=B6=E3=82=A4?= =?UTF-8?q?=E3=83=B3=20=E3=82=AC=E3=82=A4=E3=83=89=E3=83=A9=E3=82=A4?= =?UTF-8?q?=E3=83=B3"=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 3 +-- docs/guide/dev/api-design.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 docs/guide/dev/api-design.md diff --git a/README.md b/README.md index 8f4f2749d..c766f23c8 100644 --- a/README.md +++ b/README.md @@ -139,8 +139,7 @@ Issue 側で取り組み始めたことを伝えるか、最初に Draft プル ### Rust 以外の言語の API に関する方針 -VOICEVOX CORE の主要機能は Rust で実装されることを前提としており、他の言語のラッパーでのみの機能追加はしない方針としています。これは機能の一貫性を保つための方針です。 -各言語の特性に応じた追加実装（例えば、Python での `style_id` の [`NewType`](https://docs.python.org/ja/3/library/typing.html#newtype) 化など）は許容されます。 +[APIデザイン ガイドライン](./docs/guide/dev/api-design.md)をご覧ください。 ## コアライブラリのビルド diff --git a/docs/guide/dev/api-design.md b/docs/guide/dev/api-design.md new file mode 100644 index 000000000..0312b1d50 --- /dev/null +++ b/docs/guide/dev/api-design.md @@ -0,0 +1,15 @@ +# APIデザイン ガイドライン + +## Rust 以外の言語の API + +VOICEVOX CORE の主要機能は Rust で実装されることを前提としており、他の言語のラッパーでのみの機能追加はしない方針としています。これは機能の一貫性を保つための方針です。 + +ただし機能追加ではない範囲で、各言語の習慣に適合するような変更は積極的に行っていきます。例えば: + +* [`AudioQuery`](https://voicevox.github.io/voicevox_core/apis/rust_api/voicevox_core/struct.AudioQuery.html)といったJSONで表現可能なデータ型は、Pythonなら[Pydantic](https://docs.pydantic.dev)、JavaScriptなら[Zod](https://zod.dev/)といったライブラリを使って表現すべきです。 + * Rust APIとやりとりする際はJSONを介して変換します。 +* [`StyleId`](https://voicevox.github.io/voicevox_core/apis/rust_api/voicevox_core/struct.StyleId.html)といった[newtype](https://rust-unofficial.github.io/patterns/patterns/behavioural/newtype.html)は、そのままnewtypeとして表現するべきです。 + * 例えばPythonなら[`typing.NewType`](https://docs.python.org/ja/3/library/typing.html#newtype)で表現します。 +* オプショナルな引数は、キーワード引数がある言語であればキーワード引数で、ビルダースタイルが一般的な言語であればビルダースタイルで表現すべきです。 +* 「範囲」を表すデータ型が言語レベルである場合は、可能な限りそのデータ型を用いてAPIを構成するべきです。 + * 例えばSwiftやRubyでは`Range`という名のデータ型を使って表現します。