Gizmo不是轻量级API框架，而是企业级微服务工具包；它强制实现Service接口、支持HTTP/gRPC双协议、内置多层中间件与可观测性能力，适合需长期演进和统一治理的核心业务服务。
Gizmo 不是轻量级 API 框架，它定位是企业级微服务工具包——如果你图轻量，直接用 net/http 或 gin 更合适；选 Gizmo 是为了结构化、可扩展、协议统一，不是为了“轻”。
为什么 Gizmo 不能当“轻量框架”用
Gizmo 的设计目标是解决多协议（HTTP + gRPC）、中间件分层、服务注册/可观测性等工程问题，不是简化单个 HTTP handler 的编写。它的 server/kit 包强制你实现 Service 接口，包括 HTTPEndpoints()、RPCServiceDesc()、中间件注入点等——这些对简单 CRUD 服务是冗余负担。
- 常见错误现象：刚上手时照着示例写了个
GetUser方法，却发现还要配HTTPEndpoint映射、写HTTPMiddleware、定义endpoint.Endpoint链，最后发现比直接写http.HandleFunc多出 3 倍代码 - 使用场景错配：内部管理后台、临时脚手架、POC 接口——这类需求用
Gizmo反而拖慢迭代；它适合长期演进、需同时暴露 HTTP/gRPC、要对接 Consul/Prometheus 的核心业务服务 - 性能影响：
Gizmo默认启用多层中间件包装（logging → auth → tracing → transport），即使你只用其中一层，其余空壳仍参与调用链，实测比裸net/http高 15%–20% 基础延迟
Gizmo 真正该用在哪几个地方
- 你需要同一套业务逻辑，同时提供 RESTful JSON 接口和 gRPC 接口，且希望共享中间件（如 JWT 解析、请求 ID 注入）
- 你的服务必须接入公司级服务治理平台（如 Consul 注册 + 自动健康检查续租），而不想自己拼 net/http 调用
- 团队已用 Go-Kit 构建了 endpoint 层，现在需要统一 transport 层抽象，避免每个服务重复写 transport/http 和 transport/grpc-
HTTPEndpoints()返回的 map 结构必须严格匹配路径+方法，比如map[string]map[string]HTTPEndpoint{"GET": {"/users/{id}": ...}}，键名大小写敏感，少一个斜杠或方法名拼错，启动时报panic: invalid HTTP method -
RPCMiddleware()返回的是grpc.UnaryServerInterceptor，不能直接返回func(...)；常见错误是误写成类似http.HandlerFunc的签名，编译通不过 -
Gizmo不处理路由冲突，它把http.ServeMux完全交给使用者——如果你没显式 new 一个独立http.ServeMux，而是用了http.DefaultServeMux，多个Gizmo服务会互相覆盖路由
如何最小化启动一个 Gizmo 服务
这不是“Hello World”式启动，而是守住底线的最小可行集成：
- 必须实现
Service接口全部方法，哪怕空实现：Middleware、HTTPMiddleware、HTTPEndpoints、RPCMiddleware、RPCServiceDesc—— 少一个，gizmo.NewServer()直接 panic -
HTTPEndpoints()里每个HTTPEndpoint必须带DecodeRequestFunc和EncodeResponseFunc，不能留空；最简解码可用kit.DecodeJSONRequest，但要注意 struct tag 是否匹配 payload - 启动时别用
http.ListenAndServe，必须走gizmo.NewServer().Run()，否则中间件链、信号监听（SIGTERM graceful shutdown）全失效 - 日志和 traceID 注入必须在
Middleware里做，而不是在 handler 内部；Gizmo的上下文传递依赖这个入口，否则ctx.Value("trace_id")在下游 endpoint 里取不到
Gizmo 的复杂度不在代码行数，而在约束边界：它不让你自由发挥，而是用接口契约换长期可维护性。真正容易被忽略的，是它要求你提前想清楚服务暴露形态（HTTP/gRPC 是否都要？中间件是否跨协议复用？），而不是边写边加。
