Huma框架：现代化REST/GraphQL API开发框架

Huma是一个现代化的Go语言API开发框架，专注于简化REST和GraphQL API的创建过程。它结合了高性能和开发效率，提供了许多开箱即用的功能。

Huma核心特性

1. 同时支持REST和GraphQL
2. 自动OpenAPI/Swagger文档生成
3. 内置验证和序列化
4. 高性能路由
5. 简洁的API设计

安装Huma

go get github.com/danielgtaylor/huma/v2

基本REST API示例

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/danielgtaylor/huma/v2"
	"github.com/danielgtaylor/huma/v2/adapters/humagin"
	"github.com/gin-gonic/gin"
)

// 定义输入模型
type GreetingInput struct {
	Name string `path:"name" maxLength:"30" example:"world" doc:"Name to greet"`
}

// 定义响应模型
type GreetingResponse struct {
	Message string `json:"message" example:"Hello, world!"`
}

func main() {
	// 创建路由
	router := gin.New()
	
	// 创建Huma API实例
	api := humagin.New(router, huma.DefaultConfig("My API", "1.0.0"))

	// 注册路由
	huma.Register(api, huma.Operation{
		OperationID: "get-greeting",
		Method:      http.MethodGet,
		Path:        "/greet/{name}",
		Summary:     "Get a greeting",
		Description: "Get a personalized greeting for the given name.",
	}, func(ctx context.Context, input *GreetingInput) (*GreetingResponse, error) {
		resp := &GreetingResponse{
			Message: fmt.Sprintf("Hello, %s!", input.Name),
		}
		return resp, nil
	})

	// 启动服务器
	http.ListenAndServe(":8888", router)
}

GraphQL支持示例

Huma也提供了GraphQL支持：

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/danielgtaylor/huma/v2"
	"github.com/danielgtaylor/huma/v2/graphql"
	"github.com/danielgtaylor/huma/v2/adapters/humagin"
	"github.com/gin-gonic/gin"
)

type Todo struct {
	ID    string `json:"id"`
	Title string `json:"title"`
	Done  bool   `json:"done"`
}

var todos = []Todo{
	{ID: "1", Title: "Buy milk", Done: false},
	{ID: "2", Title: "Walk dog", Done: true},
}

func main() {
	router := gin.New()
	api := humagin.New(router, huma.DefaultConfig("Todo API", "1.0.0"))

	// 注册GraphQL处理器
	graphqlHandler := graphql.NewHandler(api)
	
	// 添加GraphQL路由
	api.AddHandler(huma.Operation{
		Method: http.MethodPost,
		Path:   "/graphql",
	}, graphqlHandler)

	// 定义GraphQL查询
	graphqlHandler.Register(
		graphql.Query("todos", "Get all todos", func(ctx context.Context) ([]Todo, error) {
			return todos, nil
		}),
		graphql.Query("todo", "Get a todo by ID", func(ctx context.Context, args struct {
			ID string `graphql:"id"`
		}) (*Todo, error) {
			for _, todo := range todos {
				if todo.ID == args.ID {
					return &todo, nil
				}
			}
			return nil, fmt.Errorf("todo not found")
		}),
	)

	http.ListenAndServe(":8888", router)
}

高级功能

中间件支持

func LoggerMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		next.ServeHTTP(w, r)
		duration := time.Since(start)
		log.Printf("%s %s took %v", r.Method, r.URL.Path, duration)
	})
}

func main() {
	router := gin.New()
	api := humagin.New(router, huma.DefaultConfig("My API", "1.0.0"))
	
	// 添加中间件
	api.UseMiddleware(LoggerMiddleware)
	
	// ...注册路由等
}

验证器

Huma内置了强大的验证功能：

type CreateUserInput struct {
	Body struct {
		Username string `json:"username" minLength:"3" maxLength:"20" pattern:"^[a-zA-Z0-9]+$"`
		Email    string `json:"email" format:"email"`
		Age      int    `json:"age" minimum:"18" maximum:"120"`
	}
}

huma.Register(api, huma.Operation{
	OperationID: "create-user",
	Method:      http.MethodPost,
	Path:        "/users",
}, func(ctx context.Context, input *CreateUserInput) (*huma.NoResponse, error) {
	// 输入会自动验证
	// 处理逻辑...
	return nil, nil
})

自动文档

Huma会自动生成OpenAPI文档，可通过以下端点访问：

• /openapi.json - OpenAPI规范JSON
• /docs - 交互式API文档界面

性能考虑

Huma在性能方面做了优化：

1. 使用高效的路由实现
2. 零或最小化的反射使用
3. 智能的序列化/反序列化
4. 内置缓存机制

总结

Huma框架为Go开发者提供了创建现代化API的完整解决方案，主要优势包括：

• 简洁直观的API设计
• 同时支持REST和GraphQL
• 自动化的文档生成
• 内置验证和序列化
• 良好的性能特性

对于需要快速开发高质量API的项目，Huma是一个值得考虑的选择。它特别适合需要同时提供REST和GraphQL接口，或者需要自动生成API文档的场景。