github.com/danielgtaylor/huma @v2.38.0 sqlite
README
<img alt="HumaLogo" src="https://huma.rocks/huma.png" />
Humaとは
Huma（発音: /'hjuːmɑ/）は、OpenAPI 3とJSON Schemaをバックエンドに持つ、Go言語向けのモダンでシンプルかつ高速・柔軟なHTTP REST/RPC API構築用マイクロフレームワークです。
本プロジェクトの主な目的は以下の通りです：
- 既存サービスを持つチーム向けの段階的な導入
- 好きなルーター（Go 1.22+対応含む）、ミドルウェア、ロギング/メトリクスを利用可能
- 既存ルートをドキュメント化できる拡張性の高いOpenAPI & JSON Schemaレイヤ
- Go開発者のためのモダンなREST/HTTP RPC APIバックエンドフレームワーク
- OpenAPI 3.1 & JSON SchemaによるAPI記述
- よくあるミスを防止するガードレール
- ドキュメントと実装の乖離を防ぐ
- 高品質な開発者向けツール群の自動生成
主な機能
- 任意のルーター上で宣言的なインターフェースを提供
- オペレーションやモデルのドキュメント生成
- リクエストパラメータ（パス、クエリ、ヘッダー、Cookie）
- リクエストボディ
- レスポンス（エラー含む）とレスポンスヘッダー
- JSONエラーはRFC9457および
application/problem+json（デフォルト、変更可）に準拠 - 各オペレーションごとにリクエストサイズの制限（安全なデフォルト値）
- コンテンツネゴシエーションに対応
- デフォルト設定でJSON（RFC 8259）と、オプションでCBOR（RFC 7049）を
Acceptヘッダーで選択可能 If-MatchやIf-Unmodified-Since等の条件付きリクエストヘッダーをサポート- 自動
PATCHオペレーション生成（オプション） - RFC 7386 JSON Merge Patch
- RFC 6902 JSON Patch
- Shorthandパッチ
- 入出力モデルのGo型にアノテーションを付与
- Go型からJSON Schemaを自動生成
- パス/クエリ/ヘッダー/ボディ/レスポンスヘッダー等の静的型付け
- 入力モデルの自動バリデーション＆エラーハンドリング
- Stoplight Elementsによるドキュメント生成
- 組み込みCLI（引数や環境変数で設定可能）
- 例:
-p 8000,--port=8000,SERVICE_PORT=8000 - 起動時アクション＆グレースフルシャットダウン
- OpenAPI生成によりエコシステムの多彩なツールにアクセス可能
- API Sprout, Prismでのモック
- OpenAPI Generator, oapi-codegenでのSDK生成
- Restish等CLIツール
- その他多数, awesome-openapi3
describedbyリンクヘッダーや返却オブジェクト内の$schemaプロパティ等で各リソースのJSON Schemaを生成し、エディタでのバリデーションや補完と連携可能
このプロジェクトはFastAPIにインスパイアされており、ロゴとブランディングはKari Taylor氏によってデザインされました。
スポンサー
ご支援いただいたスポンサーの皆様に心より感謝いたします！
<img src="https://github.com/user-attachments/assets/aace5aa7-32bd-45cf-a8f8-2e352feaf017" alt="Zuplo" width="260" align="right">
Zuplo: あなたのHuma APIをスケール、保護、プロダクト化
当社のAPI Gatewayは、APIのセキュリティ強化、グローバルスケール、OpenAPIからのドキュメント生成、ユーザーの収益化を支援します。
- @bclements
- @bekabaz
- @victoraugustolls
- @phoenixtechnologies-io
- @chenjr0719
- @vinogradovkonst
- @miyamo2
- @nielskrijger
ユーザーの声
「GoのWebフレームワークの中で断然好き。FastAPIから影響を受けていて、機能も素晴らしいし、まだシンプルに使える。他のフレームワークだとイマイチしっくりこなかったけど、Humaは違う！」 — Jeb_Jenky
「#Golang歴1年でHumaに出会った。まさに#FastAPIインスパイアのWebフレームワーク。ずっとこれを探してた！」 — Hana Mohan
「Huma最高です！素晴らしいパッケージをありがとうございます。長く使っていますが、本当に助かっています。」 — plscott
「Humaに感謝します。OpenAPI生成が特に便利で、FastAPIのように使えて工数も大幅に削減できました。」 — WolvesOfAllStreets
「Huma素晴らしいです。最近使い始めましたが、開発が楽しいです。努力に感謝します。」 — callmemicah
「Python（FastAPI, SQL Alchemy）で3ヶ月かかったプラットフォームを、Go（Huma, SQL C）だと3週間で書き直せた。デバッグの時間も大幅減！」 — Bitclick_
「Humaは、標準mux/chi上の良い薄いレイヤーで、自動のボディ＆パラメータシリアライズ。dotnet Web APIのような気持ち良さもありつつ、リクエスト/レスポンスの構造体設計をちゃんと意識できるのが最高。」 — Kirides
インストール方法
go getでインストールできます。Go 1.25以降が必要です。
# 事前に: go mod init ...
go get -u github.com/danielgtaylor/huma/v2
サンプル
以下はHumaを使った最小限のHello Worldサンプルです。CLI付きのHumaアプリの初期化、リソースオペレーション宣言、ハンドラー定義方法を示しています。
package main
import (
"context"
"fmt"
"net/http"
"github.com/danielgtaylor/huma/v2"
"github.com/danielgtaylor/huma/v2/adapters/humachi"
"github.com/danielgtaylor/huma/v2/humacli"
"github.com/go-chi/chi/v5"
_ "github.com/danielgtaylor/huma/v2/formats/cbor"
)
// CLIオプション
type Options struct {
Port int `help:"Port to listen on" short:"p" default:"8888"`
}
// greetingオペレーションのレスポンス
type GreetingOutput struct {
Body struct {
Message string `json:"message" example:"Hello, world!" doc:"Greeting message"`
}
}
func main() {
cli := humacli.New(func(hooks humacli.Hooks, options *Options) {
router := chi.NewMux()
api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))
huma.Get(api, "/greeting/{name}", func(ctx context.Context, input *struct{
Name string `path:"name" maxLength:"30" example:"world" doc:"Name to greet"`
}) (*GreetingOutput, error) {
resp := &GreetingOutput{}
resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
return resp, nil
})
hooks.OnStart(func() {
http.ListenAndServe(fmt.Sprintf(":%d", options.Port), router)
})
})
cli.Run()
}
TIP: Go 1.22 以降の標準ライブラリルーターを使う場合は、
chi.NewMux()→http.NewServeMux()、humachi.New→humago.Newに変更してください。go.modのgoバージョンも1.22以上にする必要があります。それ以外は同じです。
サーバー起動例:
go run greet.go（ポート指定は--portでも可）
Restishやcurlでテストできます：
# サーバーからメッセージを取得
$ restish :8888/greeting/world
HTTP/1.1 200 OK
...
{
$schema: "http://localhost:8888/schemas/GreetingOutputBody.json",
message: "Hello, world!"
}
このシンプルな例でも、http://localhost:8888/docs で自動生成ドキュメント、http://localhost:8888/openapi.json や http://localhost:8888/openapi.yaml でOpenAPI仕様が確認できます。
Humaチュートリアル（インストール編）もぜひご覧ください。
ドキュメント
より詳しいドキュメントは公式サイトをご覧ください。 また、Goパッケージの公式ドキュメントはhttps://pkg.go.dev/github.com/danielgtaylor/huma/v2で参照できます。
記事・メディア掲載
- APIs in Go with Huma 2.0
- Reducing Go Dependencies: A case study of dependency reduction in Huma
- Golang News & Libs & Jobs shared on Twitter/X
- Go Weekly #495, #498 に掲載
- Bump.sh Deploying Docs from Huma
- Composable HTTP Handlers Using Generics で言及
Humaを使用しているプロジェクト
Humaは多くの企業やオープンソースプロジェクトで使用されています。リストについては、Humaを使用しているプロジェクトのページをご覧ください！
プロジェクトが役に立った場合はぜひスターをお願いします！
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=danielgtaylor/huma&type=Date" />