Replies: 3 comments 2 replies
-
|
↑定義を完全分離するのは単に私の好みなので、基本的には(ioがやろうとしているように)oRPCの導入を考えた方がいいんじゃないかと思います |
Beta Was this translation helpful? Give feedback.
-
|
あとはparamDef/res/json-schemaだけZodなりValibotなりで書き直すというのは部分的改良案としてかなりアリではある |
Beta Was this translation helpful? Give feedback.
-
|
定義が不揃いで気持ち悪いし2つの変換でトリッキーなことをしてるというだけで、たぶん大きなバグは出てないからこのままでもいいけど、でも実装コード以外の作業でコードの複雑さと量が増えてるのは厳しいというのは誰にでも理解してもらえる考えだと思っている あと村上さんがoRPCの話をしてた且つちょうど手が空いたので既存コードの欠点を指摘しようかなというモチベーションは大いにありました |
Beta Was this translation helpful? Give feedback.
-
|
論点がいくつかあるので、それぞれ分けて決めるのが良さそうです。
Schema定義/バリデーションに使用するライブラリ選定、oRPCの導入是非検討は次のステップに… |
Beta Was this translation helpful? Give feedback.
-
|
SchemaTypeはなくした方がいいのではと思っています 理由
|
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
#10752 の挫折
私は昔、 #10752 を書いたことがありましたが、定義移行の量が多すぎて断念した
(今ならAIエージェントを使って爆速で移行できるはずではあるが)
これ以降はmisskey-js/generatorが開発されてバックエンドから型定義を生成できるようになりはしたものの、個人的にはAPI定義についてまだ不満があるため、今一度API定義について問題点を洗い出し、現代的なAPI定義方法についてもまとめようと思う。
要件
Packed<'Hoge'>など)現状(2026.6.0現在)
APIエンドポイント定義の場所
そもそも、MisskeyのAPIエンドポイントはファイルで分かれており、
https://github.com/misskey-dev/misskey/blob/2026.6.0/packages/backend/src/server/api/
インデックスはendpoint-listに手書きされている
https://github.com/misskey-dev/misskey/blob/2026.6.0/packages/backend/src/server/api/endpoint-list.ts
応答はmeta.res, 入力はparamDefで定義されている。
paramDefはOpenAPI 3オブジェクト。
meta.resはOpenAPIっぽい何か(
Schema型オブジェクト。$refはrefで簡易的な参照にしていたり、optionalプロパティがあったり)。https://github.com/misskey-dev/misskey/blob/2026.6.0/packages/backend/src/server/api/endpoints.ts
https://github.com/misskey-dev/misskey/blob/2026.6.0/packages/backend/src/server/api/endpoints/notes/create.ts
型への変換/ref定義
バックエンドで型をどう使うかというと、API定義の
SchemaやOpenAPI 3オブジェクトからTypeScript型に変換するSchemaTypeが担っている(独自実装！)https://github.com/misskey-dev/misskey/blob/2026.6.0/packages/backend/src/misc/json-schema.ts
また、ref(使い回せる型)およびPacked<'Hoge'>の定義もこのファイル内に記されている
開発者向けOpenAPIスペック提供
Misskeyサーバーの
/api.json//api-docでOpenAPI定義/HTML化ドキュメントを確認できる。genOpenapiSpec関数でリスト化や変換を行なっている。https://github.com/misskey-dev/misskey/blob/2026.6.0/packages/backend/src/server/api/openapi/gen-spec.ts
convertSchemaToOpenApiSchema関数では、独自Schema型とOpenAPI 3との差異を確認できる。https://github.com/misskey-dev/misskey/blob/2026.6.0/packages/backend/src/server/api/openapi/schemas.ts
misskey-js→クライアントでの利用
genOpenapiSpecを走らせてOpenAPIスペックを保存https://github.com/misskey-dev/misskey/blob/2026.6.0/packages/backend/scripts/generate_api_json.js
https://github.com/misskey-dev/misskey/blob/2026.6.0/packages/misskey-js/generator
課題
convertSchemaToOpenApiSchemaが増えている改善案
現代的なバリデータとAPI型定義
現代のフルTypeScript Web開発においては、OpenAPI定義とajvを使うのではなく、Zod/Valibot/ArkTypeといったバリデータライブラリを使い、そこから出力される型を使うのが一般的になってきている。
また、これらはStandard Schemaに準拠したAPIを持っており、現代的なバリデータの代名詞ともなっている。
私が今 #10752 を書き換えるなら、Valibotを使った上でSchemaTypeは排除する。
(Valibotを使いたいのは高速らしいため)
oRPCを使う
サーバーからクライアントへ型を渡すのを実現するにはoRPCを使うのが良さそう(村上さんらが1年前からスポンサーしてるらしいし)
(もう少し手広いランタイム的なものとしてはElysia.jsというものもあるが、Bunベースだしあまりにも書き換え範囲が広そう)
コントラクトファースト？
私個人的にはクライアントやmisskey-jsからバックエンドを参照する書き方がどうしても気持ち悪くて受け付けないので、oRPCを使うのであればコントラクトファーストな書き方が好き
https://zenn.dev/dress_code/articles/9040b2e3532693#%E3%82%B3%E3%83%B3%E3%83%88%E3%83%A9%E3%82%AF%E3%83%88%E3%83%95%E3%82%A1%E3%83%BC%E3%82%B9%E3%83%88%E9%96%8B%E7%99%BA
misskey-jsに入れたくないなら別途ref/API定義用のモノリポを作るとか…
(ただこの構造にまでしちゃえばバリデータ定義の受け渡し方や使い方は自分でプログラムしてもいいので、oRPCは必須ではないのかもしれないとか思ったり)
Beta Was this translation helpful? Give feedback.
All reactions