mirror of
https://github.com/zap-proto/zip.git
synced 2026-10-19 15:38:57 +00:00
zeekayandHanzo Dev
5f71d2496b
App, Group, Operation. A group is a prefix and what holds under it, an operation
is one typed route declared there, and the verb methods are generic methods —
which Go 1.27 allows on a concrete type and still refuses on an interface. So In
and Out come from the handler and the caller writes no type arguments:
users := app.Group("/v1/users")
users.Post("/", api.Create)
mint := users.Group("/mint").With(middleware.Mint(gate))
mint.Post("/deposit", api.Deposit)
A Group is a CLOSED HANDLE: two unexported fields, and no method that hands back
the app, the parent or the fiber underneath. A subsystem given the group at its
own prefix cannot reach above it, so confinement is a property of the type
instead of a rule something has to police — which is what a host needs in order
to hand out a bounded surface and know what comes back.
That is bought by giving up the router interface, deliberately. Router and
OpTarget are gone, and with them the ability to implement a route table outside
this package: a decorator is no longer a router, a gate is middleware on a group,
and a bound is a path. The five package-level verb functions go the same way —
a registration is a method on the thing it registers into.
Raw carries what is not a typed operation: a stream, an upgrade, a probe, a
foreign subtree. It names its method, and it is the longer spelling because
opting out of the typed model is the exception and should read like one.
Co-authored-by: Hanzo Dev <[email protected]>
87 lines
3.0 KiB
Go
87 lines
3.0 KiB
Go
// migrate-from-gin example — mechanical port of a gin-style API to zip.
|
|
//
|
|
// gin before:
|
|
//
|
|
// r := gin.Default()
|
|
// r.GET("/users/:id", func(c *gin.Context) {
|
|
// c.JSON(200, gin.H{"id": c.Param("id")})
|
|
// })
|
|
//
|
|
// zip after — Sinatra/Express idiom is preserved; gin.Context becomes
|
|
// *zip.Ctx; gin.H becomes any map-shaped value.
|
|
//
|
|
// # The port is two steps, and stopping after the first loses the point
|
|
//
|
|
// STEP 1 is mechanical and shown below: the handler shape is the same, so a
|
|
// route moves in one edit. It is a WAY-STATION. An untyped route registers no
|
|
// operation, so after step 1 the endpoint is in no OpenAPI document, is no MCP
|
|
// tool, has no command, and no service can reach it with zip.Call — which is
|
|
// exactly the surface gin gave you, and the surface you are migrating away from.
|
|
//
|
|
// STEP 2 declares the In/Out types the handler was already parsing by hand and
|
|
// registers the route as a typed op. That is where the projections turn on. Port
|
|
// mechanically to get it running, then type it; do not ship a service that
|
|
// stopped halfway.
|
|
//
|
|
// A gin codebase built on router groups keeps them: zip.Get takes the App or
|
|
// any Group of it, so a group's prefix is part of the op exactly as it is part
|
|
// of an untyped route. The port does not have to flatten the router to type it.
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"log"
|
|
|
|
"github.com/zap-proto/zip"
|
|
"github.com/zap-proto/zip/middleware"
|
|
)
|
|
|
|
// GetUserIn addresses one user; `id` is the path segment.
|
|
type GetUserIn struct {
|
|
ID string `json:"id"`
|
|
}
|
|
|
|
// User is one user record.
|
|
type User struct {
|
|
ID string `json:"id"`
|
|
}
|
|
|
|
// CreateUserIn is the create body — the same field the untyped port bound by
|
|
// hand with c.Bind, declared once instead.
|
|
type CreateUserIn struct {
|
|
Name string `json:"name" validate:"required"`
|
|
}
|
|
|
|
func main() {
|
|
app := zip.New(zip.Config{AppName: "migrate-from-gin"})
|
|
app.Use(middleware.Recover(), middleware.RequestID())
|
|
|
|
// STEP 1 — the mechanical port. The same shape as the gin handler, running
|
|
// on zip after one edit, and invisible to every projection until step 2.
|
|
app.Raw("GET", "/legacy/users/:id", func(c *zip.Ctx) error {
|
|
return c.JSON(200, map[string]string{"id": c.Param("id")})
|
|
})
|
|
|
|
// STEP 2 — the same routes as typed ops, declared on the group the gin
|
|
// router already had. The hand-written c.Param and c.Bind are gone: the In
|
|
// type says what the request IS, and one declaration feeds the route, the
|
|
// document, the tool list, the CLI and the call plane.
|
|
v1 := app.Group("/v1")
|
|
v1.Get("/users/:id", getUser)
|
|
v1.Post("/users", createUser)
|
|
|
|
log.Fatal(app.Listen("http://:8080"))
|
|
}
|
|
|
|
// GetUser returns one user by id.
|
|
func getUser(_ context.Context, in *GetUserIn) (*User, error) {
|
|
return &User{ID: in.ID}, nil
|
|
}
|
|
|
|
// CreateUser creates a user. A missing name is refused before the handler runs,
|
|
// by the same `validate:"required"` tag that makes the field required in the
|
|
// published schema.
|
|
func createUser(_ context.Context, in *CreateUserIn) (*CreateUserIn, error) {
|
|
return in, nil
|
|
}
|