From 899ba0a44273c36ea140dbe52018df016ad49610 Mon Sep 17 00:00:00 2001 From: Ryo Yamashita Date: Sat, 9 Nov 2024 23:54:43 +0900 Subject: [PATCH 1/2] =?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`という名のデータ型を使って表現します。 From 0832bddf9e628aaeee76f8634ec5c72546ed9811 Mon Sep 17 00:00:00 2001 From: Ryo Yamashita Date: Sun, 10 Nov 2024 19:14:09 +0900 Subject: [PATCH 2/2] =?UTF-8?q?`Range`=E3=81=AB=E3=81=A4=E3=81=84=E3=81=A6?= =?UTF-8?q?=E3=81=AF=E3=82=84=E3=82=81=E3=80=81todo=E3=81=AB=E3=81=99?= =?UTF-8?q?=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs: https://github.com/VOICEVOX/voicevox_core/pull/870#discussion_r1835601477 --- docs/guide/dev/api-design.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/dev/api-design.md b/docs/guide/dev/api-design.md index 0312b1d50..89df3e0dd 100644 --- a/docs/guide/dev/api-design.md +++ b/docs/guide/dev/api-design.md @@ -11,5 +11,5 @@ VOICEVOX CORE の主要機能は Rust で実装されることを前提として * [`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`という名のデータ型を使って表現します。 + +