Skip to content

README_JA.md

Latest commit

 

History

History
252 lines (192 loc) · 12.4 KB

README_JA.md

File metadata and controls

252 lines (192 loc) · 12.4 KB
HumaLogo

HUMA Powered CI codecov Docs Go Report Card

🌎English Documentation 🌎中文文档

Humaとは

Huma（発音: /'hjuːmɑ/）は、OpenAPI 3とJSON Schemaをバックエンドに持つ、Go言語向けのモダンでシンプルかつ高速・柔軟なHTTP REST/RPC API構築用マイクロフレームワークです。

本プロジェクトの主な目的は以下の通りです：

  • 既存サービスを持つチーム向けの段階的な導入
    • 好きなルーター（Go 1.22+対応含む）、ミドルウェア、ロギング/メトリクスを利用可能
    • 既存ルートをドキュメント化できる拡張性の高いOpenAPI & JSON Schemaレイヤ
  • Go開発者のためのモダンなREST/HTTP RPC APIバックエンドフレームワーク
  • よくあるミスを防止するガードレール
  • ドキュメントと実装の乖離を防ぐ
  • 高品質な開発者向けツール群の自動生成

主な機能

  • 任意のルーター上で宣言的なインターフェースを提供
    • オペレーションやモデルのドキュメント生成
    • リクエストパラメータ（パス、クエリ、ヘッダー、Cookie）
    • リクエストボディ
    • レスポンス（エラー含む）とレスポンスヘッダー
  • JSONエラーはRFC9457およびapplication/problem+json（デフォルト、変更可）に準拠
  • 各オペレーションごとにリクエストサイズの制限（安全なデフォルト値）
  • コンテンツネゴシエーションに対応
    • デフォルト設定でJSON（RFC 8259）と、オプションでCBOR（RFC 7049）をAcceptヘッダーで選択可能
  • If-MatchやIf-Unmodified-Since等の条件付きリクエストヘッダーをサポート
  • 自動PATCHオペレーション生成（オプション）
  • 入出力モデルのGo型にアノテーションを付与
    • Go型からJSON Schemaを自動生成
    • パス/クエリ/ヘッダー/ボディ/レスポンスヘッダー等の静的型付け
    • 入力モデルの自動バリデーション＆エラーハンドリング
  • Stoplight Elementsによるドキュメント生成
  • 組み込みCLI（引数や環境変数で設定可能）
    • 例: -p 8000, --port=8000, SERVICE_PORT=8000
    • 起動時アクション＆グレースフルシャットダウン
  • OpenAPI生成によりエコシステムの多彩なツールにアクセス可能
  • describedbyリンクヘッダーや返却オブジェクト内の$schemaプロパティ等で各リソースのJSON Schemaを生成し、エディタでのバリデーションや補完と連携可能

このプロジェクトはFastAPIにインスパイアされており、ロゴとブランディングはKari Taylor氏によってデザインされました。

スポンサー

ご支援いただいたスポンサーの皆様に心より感謝いたします！

Zuplo

Zuplo: あなたのHuma APIをスケール、保護、プロダクト化

当社のAPI Gatewayは、APIのセキュリティ強化、グローバルスケール、OpenAPIからのドキュメント生成、ユーザーの収益化を支援します。

無料で始める

ユーザーの声

「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で参照できます。

記事・メディア掲載

Humaを使用しているプロジェクト

Humaは多くの企業やオープンソースプロジェクトで使用されています。リストについては、Humaを使用しているプロジェクトのページをご覧ください！

プロジェクトが役に立った場合はぜひスターをお願いします！

Star History Chart